PlotlyBase.jl API Documentation
Welcome to the PlotlyBase.jl API documentation. On this page we include all docstrings found in PlotlyBase.jl.
Navigation
The following types are documented:
PlotlyBase.Inset
PlotlyBase.Plot
PlotlyBase.Plot
PlotlyBase.Plot
PlotlyBase.Plot
PlotlyBase.PlotConfig
PlotlyBase.Spec
PlotlyBase.Subplots
The following functions are documented
PlotlyBase.addtraces!
PlotlyBase.addtraces!
PlotlyBase.circle
PlotlyBase.deletetraces!
PlotlyBase.extendtraces!
PlotlyBase.hline
PlotlyBase.launch_browser
PlotlyBase.line
PlotlyBase.movetraces!
PlotlyBase.movetraces!
PlotlyBase.path
PlotlyBase.prependtraces!
PlotlyBase.rect
PlotlyBase.relayout!
PlotlyBase.relayout!
PlotlyBase.restyle!
PlotlyBase.restyle!
PlotlyBase.restyle!
PlotlyBase.restyle!
PlotlyBase.restyle!
PlotlyBase.sizes
PlotlyBase.stem
PlotlyBase.trace_map
PlotlyBase.update!
PlotlyBase.vline
Types
PlotlyBase.Inset
— Type.Parameters
cell
: index of the subplot cell to overlay inset axes onto.kind
: Subplot kind (seeSpec
docs)l
: padding left of inset in fraction of cell widthw
: inset width in fraction of cell width ('to_end': to cell right edge)b
: padding bottom of inset in fraction of cell heighth
: inset height in fraction of cell height ('to_end': to cell top edge)
PlotlyBase.Plot
— Type.Plot(f, x0, x1)
Plot(f, x0, x1, l; config, kwargs...)
Construct a plot of f
from x0
to x1
, using the layout l
. All keyword arguments are applied to the constructed trace.
PlotlyBase.Plot
— Type.Plot(fs, x0, x1)
Plot(fs, x0, x1, l; config, kwargs...)
For each function in f
in fs
, construct a scatter trace that plots f
from x0
to x1
, using the layout l
. All keyword arguments are applied to all constructed traces.
PlotlyBase.Plot
— Method.Plot(y)
Plot(y, l; kwargs...)
Build a scatter plot and set y
to y. All keyword arguments are passed directly as keyword arguments to the constructed scatter.
PlotlyBase.Plot
— Method.Plot(x, y)
Plot(x, y, l; kind, config, kwargs...)
Build a plot of with one trace of type kind
and set x
to x and y
to y. All keyword arguments are passed directly as keyword arguments to the constructed trace.
NOTE: If y
is a matrix, one trace is constructed for each column of y
NOTE: If x
and y
are both matrices, they must have the same number of columns (say N
). Then N
traces are constructed, where the i
th column of x
is paired with the i
th column of y
.
PlotlyBase.PlotConfig
— Type.PlotConfig(;kwargs...)
Configuration options to be sent to the frontend to control aspects of how the plot is rendered. The acceptable keyword arguments are:
scrollZoom
: Determines whether mouse wheel or two-finger scroll zooms is enable. Turned on by default for gl3d, geo and mapbox subplots (as these subplot types do not have zoombox via pan), but turned off by default for cartesian subplots. SetscrollZoom
to false to disable scrolling for all subplots.editable
: Determines whether the graph is editable or not. Sets all pieces ofedits
unless a separateedits
config item overrides individual parts.staticPlot
: Determines whether the graphs are interactive or not. If false, no interactivity, for export or image generation.toImageButtonOptions
: Statically override options for toImage modebar button allowed keys are format, filename, width, heightdisplayModeBar
: Determines the mode bar display mode. If true, the mode bar is always visible. If false, the mode bar is always hidden. If hover, the mode bar is visible while the mouse cursor is on the graph container.modeBarButtonsToRemove
: Remove mode bar buttons by namemodeBarButtonsToAdd
: Add mode bar button using config objects. To enable predefined modebar buttons e.g. shape drawing, hover and spikelines, simply provide their string name(s). This could include: v1hovermode, hoverclosest, hovercompare, togglehover, togglespikelines, drawline, drawopenpath, drawclosedpath, drawcircle, drawrect and eraseshape. Please note that these predefined buttons will only be shown if they are compatible with all trace types used in a graph.showLink
: Determines whether a link to Chart Studio Cloud is displayed at the bottom right corner of resulting graphs. Use withsendData
andlinkText
.plotlyServerURL
: When set it determines base URL for the 'Edit in Chart Studio'showEditInChartStudio
/showSendToCloud
mode bar button and the showLink/sendData on-graph link. To enable sending your data to Chart Studio Cloud, you need to set bothplotlyServerURL
to 'https://chart-studio.plotly.com' and also setshowSendToCloud
to true.linkText
: Sets the text appearing in theshowLink
link.showEditInChartStudio
: Same asshowSendToCloud
, but use a pencil icon instead of a floppy-disk. Note that if bothshowSendToCloud
andshowEditInChartStudio
are turned, onlyshowEditInChartStudio
will be honored.locale
: Which localization should we use? Should be a string like 'en' or 'en-US'.displaylogo
: Determines whether or not the plotly logo is displayed on the end of the mode bar.responsive
: Determines whether to change the layout size when window is resized.doubleClickDelay
: Sets the delay for registering a double-click in ms. This is the time interval (in ms) between first mousedown and 2nd mouseup to constitute a double-click. This setting propagates to all on-subplot double clicks (except for geo and mapbox) and on-legend double clicks.
PlotlyBase.Spec
— Type.Parameters
kind
Subplot type. One of- 'xy': 2D Cartesian subplot type for scatter, bar, etc.
- 'scene': 3D Cartesian subplot for scatter3d, cone, etc.
- 'polar': Polar subplot for scatterpolar, barpolar, etc.
- 'ternary': Ternary subplot for scatterternary
- 'mapbox': Mapbox subplot for scattermapbox
- 'domain': Subplot type for traces that are individually positioned. pie, parcoords, parcats, etc.
secondary_y
: If true, create a secondary y-axis positioned on the right side of the subplot. Only valid if kind="xy".colspan
: number of subplot columns for this subplot to span.rowspan
: number of subplot rows for this subplot to span.l
: padding left of cellr
: padding right of cellt
: padding right of cellb
: padding bottom of cell
PlotlyBase.Subplots
— Type.Parameters
rows
: Number of rows in the subplot grid. Must be greater than zero.cols
: Number of columns in the subplot grid. Must be greater than zero.shared_xaxes
: Assign shared (linked) x-axes for 2D cartesian subplots- true or "columns": Share axes among subplots in the same column
- "rows": Share axes among subplots in the same row
- "all": Share axes across all subplots in the grid
shared_yaxes
: Assign shared (linked) y-axes for 2D cartesian subplots- "columns": Share axes among subplots in the same column
- true or "rows": Share axes among subplots in the same row
- "all": Share axes across all subplots in the grid.
start_cell
: Choose the starting cell in the subplot grid used to set the domains_grid of the subplots.- "top-left": Subplots are numbered with (1, 1) in the top left corner
- "bottom-left": Subplots are numbererd with (1, 1) in the bottom left corner
horizontal_spacing
: Space between subplot columns in normalized plot coordinates. Must be a float between 0 and 1. Applies to all columns (use "specs" subplot-dependents spacing)vertical_spacing
: Space between subplot rows in normalized plot coordinates. Must be a float between 0 and 1. Applies to all rows (use "specs" subplot-dependents spacing)subplot_titles
: Title of each subplot as a list in row-major ordering. Empty strings ("") can be included in the list if no subplot title is desired in that space so that the titles are properly indexed.specs
: Per subplot specifications of subplot type, row/column spanning, and spacing.- The number of rows in "specs" must be equal to "rows".
- The number of columns in "specs"
- Each item in the "specs" list corresponds to one subplot in a subplot grid. (N.B. The subplot grid has exactly "rows" times "cols" cells.)
- Use missing for a blank a subplot cell (or to move past a col/row span).
- Each item in "specs" is an instance of
Spec
. See docs forSpec
for more information - Note: Use
horizontal_spacing
andvertical_spacing
to adjust the spacing in between the subplots.
insets
: Inset specifications. Insets are subplots that overlay grid subplots- Each item in "insets" is an instance of
Inset
. See docs forInset
for more info
- Each item in "insets" is an instance of
column_widths
: Array of lengthcols
of the relative widths of each column of suplots. Values are normalized internally and used to distribute overall width of the figure (excluding padding) among the columns.row_heights
: Array of lengthrows
of the relative heights of each row of subplots. Values are normalized internally and used to distribute overall height of the figure (excluding padding) among the rowscolumn_titles
: list of lengthcols
of titles to place above the top subplot in each column.row_titles
: list of lengthrows
of titles to place on the right side of each row of subplots.x_title
: Title to place below the bottom row of subplots, centered horizontallyy_title
: Title to place to the left of the left column of subplots, centered vertically
PlotlyBase.addtraces!
— Method.addtraces!(p::Plot, i::Int, traces::AbstractTrace...)
Add trace(s) at a specified location in the Plot's array of data.
The new traces will start at index p.data[i]
PlotlyBase.addtraces!
— Method.addtraces!(p::Plot, traces::AbstractTrace...)
Add trace(s) to the end of the Plot's array of data
PlotlyBase.circle
— Function.Draw a circle from ((x0
+x1
)/2, (y0
+y1
)/2)) with radius (|(x0
+x1
)/2 - x0
|, |(y0
+y1
)/2 -y0
)|)
PlotlyBase.deletetraces!
— Method.deletetraces!(p::Plot, inds::Int...) =
Remove the traces at the specified indices
PlotlyBase.extendtraces!
— Function.extendtraces!(::Plot, ::Dict{Union{Symbol,AbstractString},AbstractVector{Vector{Any}}}), indices, maxpoints)
Extend one or more traces with more data. A few notes about the structure of the update dict are important to remember:
- The keys of the dict should be of type
Symbol
orAbstractString
specifying the trace attribute to be updated. These attributes must already exist in the trace - The values of the dict must be a
Vector
ofVector
of data. The outer index tells Plotly which trace to update, whereas theVector
at that index contains the value to be appended to the trace attribute.
These concepts are best understood by example:
# adds the values [1, 3] to the end of the first trace's y attribute and doesn't
# remove any points
extendtraces!(p, Dict(:y=>Vector[[1, 3]]), [1], -1)
extendtraces!(p, Dict(:y=>Vector[[1, 3]])) # equivalent to above
# adds the values [1, 3] to the end of the third trace's marker.size attribute
# and [5,5,6] to the end of the 5th traces marker.size -- leaving at most 10
# points per marker.size attribute
extendtraces!(p, Dict("marker.size"=>Vector[[1, 3], [5, 5, 6]]), [3, 5], 10)
PlotlyBase.hline
— Function.hline(y, fields::AbstractDict=Dict{Symbol,Any}(); kwargs...)
Draw horizontal lines at each point in y
that span the width of the plot
PlotlyBase.line
— Function.Draw a line through the points (x0, y0) and (x1, y2)
PlotlyBase.movetraces!
— Method.movetraces!(p::Plot, src::AbstractVector{Int}, dest::AbstractVector{Int})
Move traces from indices src
to indices dest
.
Both src
and dest
must be Vector{Int}
PlotlyBase.movetraces!
— Method.movetraces!(p::Plot, to_end::Int...)
Move one or more traces to the end of the data array"
PlotlyBase.path
— Method.Draw an arbitrary svg path
PlotlyBase.prependtraces!
— Function.prependtraces!(p::Plot, update::AbstractDict, indices::AbstractVector{Int}=[1],
maxpoints=-1)
The API for prependtraces
is equivalent to that for extendtraces
except that the data is added to the front of the traces attributes instead of the end. See Those docstrings for more information
PlotlyBase.rect
— Function.Draw a rectangle linking (x0
,y0
), (x1
,y0
), (x1
,y1
), (x0
,y1
), (x0
,y0
)
PlotlyBase.relayout!
— Function.relayout!(l::Layout, update::AbstractDict=Dict(); kwargs...)
Update l
using update dict and/or kwargs
PlotlyBase.relayout!
— Method.relayout!(p::Plot, update::AbstractDict=Dict(); kwargs...)
Update p.layout
on using update dict and/or kwargs
PlotlyBase.restyle!
— Function.restyle!(p::Plot, ind::Int=1, update::AbstractDict=Dict(); kwargs...)
Update p.data[ind]
using update dict and/or kwargs
PlotlyBase.restyle!
— Function.restyle!(::Plot, ::AbstractVector{Int}, ::AbstractDict=Dict(); kwargs...)
Update specific traces at p.data[inds]
using update dict and/or kwargs
PlotlyBase.restyle!
— Function.restyle!(p::Plot, update::AbstractDict=Dict(); kwargs...)
Update all traces using update dict and/or kwargs
PlotlyBase.restyle!
— Function.The restyle!
method follows the semantics of the Plotly.restyle
function in plotly.js. Specifically the following rules are applied when trying to set an attribute k
to a value v
on trace ind
, which happens to be the i
th trace listed in the vector of ind
s (if ind
is a scalar then i
is always equal to 1)
- if
v
is an array or a tuple (both translated to javascript arrays when
json(v)
is called) then p.data[ind][k]
will be set to v[i]
. See examples below
- if
v
is any other type (any scalar type), thenk
is set directly tov
.
Examples
# set marker color on first two traces to be red
restyle!(p, [1, 2], marker_color="red")
# set marker color on trace 1 to be green and trace 2 to be red
restyle!(p, [2, 1], marker_color=["red", "green"])
# set marker color on trace 1 to be red. green is not used
restyle!(p, 1, marker_color=["red", "green"])
# set the first marker on trace 1 to red, the second marker on trace 1 to green
restyle!(p, 1, marker_color=(["red", "green"],))
# suppose p has 3 traces.
# sets marker color on trace 1 to ["red", "green"]
# sets marker color on trace 2 to "blue"
# sets marker color on trace 3 to ["red", "green"]
restyle!(p, 1:3, marker_color=(["red", "green"], "blue"))
PlotlyBase.restyle!
— Function.restyle!(gt::GenericTrace, i::Int=1, update::AbstractDict=Dict(); kwargs...)
Update trace gt
using dict/kwargs, assuming it was the i
th ind in a call to restyle!(::Plot, ...)
PlotlyBase.stem
— Method.stem(; y, stem_color, stem_thickness, kwargs...)
Creates a "stem" or "lollipop" trace. It is implemented using plotly.js's scatter
type, using the error bars to draw the stem.
Keyword Arguments:
- All properties accepted by
scatter
excepterror_y
, which is used to draw the stems - stem_color - sets the color of the stems
- stem_thickness - sets the thickness of the stems
PlotlyBase.update!
— Function.Apply both restyle!
and relayout!
to the plot. Layout arguments are specified by passing an instance of Layout
to the layout
keyword argument.
The update
Dict (optional) and all keyword arguments will be passed to restyle
Example
julia> p = Plot([scatter(y=[1, 2, 3])], Layout(yaxis_title="this is y"));
julia> print(json(p, 2))
{
"layout": {
"margin": {
"l": 50,
"b": 50,
"r": 50,
"t": 60
},
"yaxis": {
"title": "this is y"
}
},
"data": [
{
"y": [
1,
2,
3
],
"type": "scatter"
}
]
}
julia> update!(p, Dict(:marker => Dict(:color => "red")), layout=Layout(title="this is a title"), marker_symbol="star");
julia> print(json(p, 2))
{
"layout": {
"margin": {
"l": 50,
"b": 50,
"r": 50,
"t": 60
},
"yaxis": {
"title": "this is y"
},
"title": "this is a title"
},
"data": [
{
"y": [
1,
2,
3
],
"type": "scatter",
"marker": {
"color": "red",
"symbol": "star"
}
}
]
}
PlotlyBase.vline
— Function.vline(x, fields::AbstractDict=Dict{Symbol,Any}(); kwargs...)
Draw vertical lines at each point in x
that span the height of the plot
Base.size
— Method.size(::PlotlyBase.Plot)
Return the size of the plot in pixels. Obtained from the layout.width
and layout.height
fields.
PlotlyBase.launch_browser
— Method.opens a browser tab with the given html file
PlotlyBase.sizes
— Function.Given the number of rows and columns, return an NTuple{4,Float64} containing (width, height, vspace, hspace)
, where width
and height
are the width and height of each subplot and vspace
and hspace
are the vertical and horizonal spacing between subplots, respectively.
PlotlyBase.trace_map
— Function.trace_map(p::Plot, axis::Symbol=:x)
Return an array of length(p.data)
that maps each element of p.data
into an integer for which number axis of kind axis
that trace belogs to. axis
can either be x
or y
. If x
is given, return the integer for which x-axis the trace belongs to. Similar for y
.