Construct a new Heatmap object
The data that describes the heatmap value-to-color mapping isset in z
. Data in z
can either be a 2D list of values(ragged or not) or a 1D array of values. In the case where z
is a 2D list, say that z
has N rows and M columns. Then, bydefault, the resulting heatmap will have N partitions along they axis and M partitions along the x axis. In other words, thei-th row/ j-th column cell in z
is mapped to the i-thpartition of the y axis (starting from the bottom of the plot)and the j-th partition of the x-axis (starting from the left ofthe plot). This behavior can be flipped by using transpose
.Moreover, x
(y
) can be provided with M or M+1 (N or N+1)elements. If M (N), then the coordinates correspond to thecenter of the heatmap cells and the cells have equal width. IfM+1 (N+1), then the coordinates correspond to the edges of theheatmap cells. In the case where z
is a 1D list, the x and ycoordinates must be provided in x
and y
respectively toform data triplets.
- Parameters
arg – dict of properties compatible with this constructor oran instance of plotly.graph_objects.Heatmap
autocolorscale – Determines whether the colorscale is a default palette(
autocolorscale: true
) or the palette determined bycolorscale
. In casecolorscale
is unspecified orautocolorscale
is true, the default palette will bechosen according to whether numbers in thecolor
array are all positive, all negative or mixed.coloraxis – Sets a reference to a shared color axis. References tothese shared color axes are “coloraxis”, “coloraxis2”,“coloraxis3”, etc. Settings for these shared color axesare set in the layout, under
layout.coloraxis
,layout.coloraxis2
, etc. Note that multiple colorscales can be linked to the same color axis.colorbar – plotly.graph_objects.heatmap.ColorBar instanceor dict with compatible properties
colorscale – Sets the colorscale. The colorscale must be an arraycontaining arrays mapping a normalized value to an rgb,rgba, hex, hsl, hsv, or named color string. At minimum,a mapping for the lowest (0) and highest (1) values arerequired. For example,
[[0, 'rgb(0,0,255)'], [1,'rgb(255,0,0)']]
. To control the bounds of thecolorscale in color space, usezmin
andzmax
.Alternatively,colorscale
may be a palette namestring of the following list: Blackbody,Bluered,Blues,Cividis,Earth,Electric,Greens,Greys,Hot,Jet,Picnic,Portland,Rainbow,RdBu,Reds,Viridis,YlGnBu,YlOrRd.connectgaps – Determines whether or not gaps (i.e. {nan} or missingvalues) in the
z
data are filled in. It is defaultedto true ifz
is a one dimensional array andzsmooth
is not false; otherwise it is defaulted to false.customdata – Assigns extra data each datum. This may be useful whenlistening to hover, click and selection events. Notethat, “scatter” traces also appends customdata items inthe markers DOM elements
customdatasrc – Sets the source reference on Chart Studio Cloud for
customdata
.dx – Sets the x coordinate step. See
x0
for more info.dy – Sets the y coordinate step. See
y0
for more info.hoverinfo – Determines which trace information appear on hover. If
none
orskip
are set, no information is displayedupon hovering. But, ifnone
is set, click and hoverevents are still fired.hoverinfosrc – Sets the source reference on Chart Studio Cloud for
hoverinfo
.hoverlabel – plotly.graph_objects.heatmap.Hoverlabelinstance or dict with compatible properties
hoverongaps – Determines whether or not gaps (i.e. {nan} or missingvalues) in the
z
data have hover labels associatedwith them.hovertemplate – Template string used for rendering the information thatappear on hover box. Note that this will override
hoverinfo
. Variables are inserted using %{variable},for example “y: %{y}” as well as %{xother}, {%_xother},{%_xother_}, {%xother_}. When showing info for severalpoints, “xother” will be added to those with differentx positions from the first point. An underscore beforeor after “(x|y)other” will add a space on that side,only when this field is shown. Numbers are formattedusing d3-format’s syntax %{variable:d3-format}, forexample “Price: %{y:$.2f}”.https://github.com/d3/d3-format/tree/v1.4.5#d3-formatfor details on the formatting syntax. Dates areformatted using d3-time-format’s syntax%{variable|d3-time-format}, for example “Day:%{2019-01-01|%A}”. https://github.com/d3/d3-time-format/tree/v2.2.3#locale_format for details on thedate formatting syntax. The variables available inhovertemplate
are the ones emitted as event datadescribed at this linkhttps://plotly.com/javascript/plotlyjs-events/#event-data. Additionally, every attributes that can bespecified per-point (the ones that arearrayOk: true
)are available. Anything contained in tag<extra>
isdisplayed in the secondary box, for example“<extra>{fullData.name}</extra>”. To hide the secondarybox completely, use an empty tag<extra></extra>
.hovertemplatesrc – Sets the source reference on Chart Studio Cloud for
hovertemplate
.hovertext – Same as
text
.hovertextsrc – Sets the source reference on Chart Studio Cloud for
hovertext
.ids – Assigns id labels to each datum. These ids for objectconstancy of data points during animation. Should be anarray of strings, not numbers or any other type.
idssrc – Sets the source reference on Chart Studio Cloud for
ids
.legend – Sets the reference to a legend to show this trace in.References to these legends are “legend”, “legend2”,“legend3”, etc. Settings for these legends are set inthe layout, under
layout.legend
,layout.legend2
,etc.legendgroup – Sets the legend group for this trace. Traces and shapespart of the same legend group hide/show at the sametime when toggling legend items.
legendgrouptitle – plotly.graph_objects.heatmap.Legendgrouptitleinstance or dict with compatible properties
legendrank – Sets the legend rank for this trace. Items and groupswith smaller ranks are presented on top/left side whilewith “reversed”
legend.traceorder
they are onbottom/right side. The default legendrank is 1000, sothat you can use ranks less than 1000 to place certainitems before all unranked items, and ranks greater than1000 to go after all unranked items. When havingunranked or equal rank items shapes would be displayedafter traces i.e. according to their order in data andlayout.legendwidth – Sets the width (in px or fraction) of the legend forthis trace.
meta – Assigns extra meta information associated with thistrace that can be used in various text attributes.Attributes such as trace
name
, graph, axis andcolorbartitle.text
, annotationtext
rangeselector
,updatemenues
andsliders
label
text all supportmeta
. To access the tracemeta
values in an attribute in the same trace, simply use%{meta[i]}
wherei
is the index or key of themeta
item in question. To access tracemeta
inlayout attributes, use%{data[n[.meta[i]}
wherei
is the index or key of themeta
andn
is the traceindex.metasrc – Sets the source reference on Chart Studio Cloud for
meta
.name – Sets the trace name. The trace name appears as thelegend item and on hover.
opacity – Sets the opacity of the trace.
reversescale – Reverses the color mapping if true. If true,
zmin
will correspond to the last color in the array andzmax
will correspond to the first color.showlegend – Determines whether or not an item corresponding to thistrace is shown in the legend.
showscale – Determines whether or not a colorbar is displayed forthis trace.
stream – plotly.graph_objects.heatmap.Stream instanceor dict with compatible properties
text – Sets the text elements associated with each z value.
textfont – Sets the text font.
textsrc – Sets the source reference on Chart Studio Cloud for
text
.texttemplate – Template string used for rendering the information textthat appear on points. Note that this will override
textinfo
. Variables are inserted using %{variable},for example “y: %{y}”. Numbers are formatted usingd3-format’s syntax %{variable:d3-format}, for example“Price: %{y:$.2f}”.https://github.com/d3/d3-format/tree/v1.4.5#d3-formatfor details on the formatting syntax. Dates areformatted using d3-time-format’s syntax%{variable|d3-time-format}, for example “Day:%{2019-01-01|%A}”. https://github.com/d3/d3-time-format/tree/v2.2.3#locale_format for details on thedate formatting syntax. Every attributes that can bespecified per-point (the ones that arearrayOk: true
)are available. Finally, the template string has accessto variablesx
,y
,z
andtext
.transpose – Transposes the z data.
uid – Assign an id to this trace, Use this to provide objectconstancy between traces during animations andtransitions.
uirevision – Controls persistence of some user-driven changes to thetrace:
constraintrange
inparcoords
traces, as wellas someeditable: true
modifications such asname
andcolorbar.title
. Defaults tolayout.uirevision
.Note that other user-driven trace attribute changes arecontrolled bylayout
attributes:trace.visible
iscontrolled bylayout.legend.uirevision
,selectedpoints
is controlled bylayout.selectionrevision
, andcolorbar.(x|y)
(accessible withconfig: {editable: true}
) iscontrolled bylayout.editrevision
. Trace changes aretracked byuid
, which only falls back on trace indexif nouid
is provided. So if your app can add/removetraces before the end of thedata
array, such thatthe same trace has a different index, you can stillpreserve user-driven changes if you give each trace auid
that stays with it as it moves.visible – Determines whether or not this trace is visible. If“legendonly”, the trace is not drawn, but can appear asa legend item (provided that the legend itself isvisible).
x – Sets the x coordinates.
x0 – Alternate to
x
. Builds a linear space of xcoordinates. Use withdx
wherex0
is the startingcoordinate anddx
the step.xaxis – Sets a reference between this trace’s x coordinates anda 2D cartesian x axis. If “x” (the default value), thex coordinates refer to
layout.xaxis
. If “x2”, the xcoordinates refer tolayout.xaxis2
, and so on.xcalendar – Sets the calendar system to use with
x
date data.xgap – Sets the horizontal gap (in pixels) between bricks.
xhoverformat – Sets the hover text formatting rulefor
x
using d3formatting mini-languages which are very similar tothose in Python. For numbers, see:https://github.com/d3/d3-format/tree/v1.4.5#d3-format.And for dates see: https://github.com/d3/d3-time-format/tree/v2.2.3#locale_format. We add two items tod3’s date formatter: “%h” for half of the year as adecimal number as well as “%{n}f” for fractionalseconds with n digits. For example, 2016-10-1309:15:23.456 with tickformat “%H~%M~%S.%2f” woulddisplay *09~15~23.46*By default the values areformatted usingxaxis.hoverformat
.xperiod – Only relevant when the axis
type
is “date”. Sets theperiod positioning in milliseconds or “M<n>” on the xaxis. Special values in the form of “M<n>” could beused to declare the number of months. In this casen
must be a positive integer.xperiod0 – Only relevant when the axis
type
is “date”. Sets thebase for period positioning in milliseconds or datestring on the x0 axis. Whenx0period
is round numberof weeks, thex0period0
by default would be on aSunday i.e. 2000-01-02, otherwise it would be at2000-01-01.xperiodalignment – Only relevant when the axis
type
is “date”. Sets thealignment of data points on the x axis.xsrc – Sets the source reference on Chart Studio Cloud for
x
.xtype – If “array”, the heatmap’s x coordinates are given by“x” (the default behavior when
x
is provided). If“scaled”, the heatmap’s x coordinates are given by “x0”and “dx” (the default behavior whenx
is notprovided).y – Sets the y coordinates.
y0 – Alternate to
y
. Builds a linear space of ycoordinates. Use withdy
wherey0
is the startingcoordinate anddy
the step.yaxis – Sets a reference between this trace’s y coordinates anda 2D cartesian y axis. If “y” (the default value), they coordinates refer to
layout.yaxis
. If “y2”, the ycoordinates refer tolayout.yaxis2
, and so on.ycalendar – Sets the calendar system to use with
y
date data.ygap – Sets the vertical gap (in pixels) between bricks.
yhoverformat – Sets the hover text formatting rulefor
y
using d3formatting mini-languages which are very similar tothose in Python. For numbers, see:https://github.com/d3/d3-format/tree/v1.4.5#d3-format.And for dates see: https://github.com/d3/d3-time-format/tree/v2.2.3#locale_format. We add two items tod3’s date formatter: “%h” for half of the year as adecimal number as well as “%{n}f” for fractionalseconds with n digits. For example, 2016-10-1309:15:23.456 with tickformat “%H~%M~%S.%2f” woulddisplay *09~15~23.46*By default the values areformatted usingyaxis.hoverformat
.yperiod – Only relevant when the axis
type
is “date”. Sets theperiod positioning in milliseconds or “M<n>” on the yaxis. Special values in the form of “M<n>” could beused to declare the number of months. In this casen
must be a positive integer.yperiod0 – Only relevant when the axis
type
is “date”. Sets thebase for period positioning in milliseconds or datestring on the y0 axis. Wheny0period
is round numberof weeks, they0period0
by default would be on aSunday i.e. 2000-01-02, otherwise it would be at2000-01-01.yperiodalignment – Only relevant when the axis
type
is “date”. Sets thealignment of data points on the y axis.ysrc – Sets the source reference on Chart Studio Cloud for
y
.ytype – If “array”, the heatmap’s y coordinates are given by“y” (the default behavior when
y
is provided) If“scaled”, the heatmap’s y coordinates are given by “y0”and “dy” (the default behavior wheny
is notprovided)z – Sets the z data.
zauto – Determines whether or not the color domain is computedwith respect to the input data (here in
z
) or thebounds set inzmin
andzmax
Defaults tofalse
whenzmin
andzmax
are set by the user.zhoverformat – Sets the hover text formatting rulefor
z
using d3formatting mini-languages which are very similar tothose in Python. For numbers, see: https://github.com/d3/d3-format/tree/v1.4.5#d3-format.By default the valuesare formatted using generic number format.zmax – Sets the upper bound of the color domain. Value shouldhave the same units as in
z
and if set,zmin
mustbe set as well.zmid – Sets the mid-point of the color domain by scaling
zmin
and/orzmax
to be equidistant to this point.Value should have the same units as inz
. Has noeffect whenzauto
isfalse
.zmin – Sets the lower bound of the color domain. Value shouldhave the same units as in
z
and if set,zmax
mustbe set as well.zorder – Sets the layer on which this trace is displayed,relative to other SVG traces on the same subplot. SVGtraces with higher
zorder
appear in front of thosewith lowerzorder
.zsmooth – Picks a smoothing algorithm use to smooth
z
data.zsrc – Sets the source reference on Chart Studio Cloud for
z
.
- Returns
- Return type
Heatmap