API Documentation

size(::PlotlyBase.Plot)

Return the size of the plot in pixels. Obtained from the layout.width and layout.height fields.

_partial_val_sortperm(obsvals, orders, order_keys)

lexographically sort obsvals to match orders, given keys into orders

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]

addtraces!(p::Plot, traces::AbstractTrace...)

Add trace(s) to the end of the Plot's array of data

Draw a circle from ((x0+x1)/2, (y0+y1)/2)) with radius (|(x0+x1)/2 - x0|, |(y0+y1)/2 -y0)|)

deletetraces!(p::Plot, inds::Int...) =

Remove the traces at the specified indices

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 or AbstractString specifying the trace attribute to be updated. These attributes must already exist in the trace
• The values of the dict must be a Vector of Vector of data. The outer index tells Plotly which trace to update, whereas the Vector 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)

hline(y, fields::AbstractDict=Dict{Symbol,Any}(); kwargs...)

Draw horizontal lines at each point in y that span the width of the plot

opens a browser tab with the given html file

Draw a line through the points (x0, y0) and (x1, y2)

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}

movetraces!(p::Plot, to_end::Int...)

Move one or more traces to the end of the data array"

Draw an arbitrary svg path

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

Draw a rectangle linking (x0,y0), (x1,y0), (x1,y1), (x0,y1), (x0,y0)

relayout!(l::Layout, update::AbstractDict=Dict(); kwargs...)

Update l using update dict and/or kwargs

relayout!(p::Plot, update::AbstractDict=Dict(); kwargs...)

Update p.layout on using update dict and/or kwargs

restyle!(p::Plot, update::AbstractDict=Dict(); kwargs...)

Update all traces using update dict and/or kwargs

restyle!(gt::GenericTrace, i::Int=1, update::AbstractDict=Dict(); kwargs...)

Update trace gt using dict/kwargs, assuming it was the ith ind in a call to restyle!(::Plot, ...)

restyle!(p::Plot, ind::Int=1, update::AbstractDict=Dict(); kwargs...)

Update p.data[ind] using update dict and/or kwargs

restyle!(::Plot, ::AbstractVector{Int}, ::AbstractDict=Dict(); kwargs...)

Update specific traces at p.data[inds] using update dict and/or kwargs

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 ith trace listed in the vector of inds (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), then k is set directly to v.

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"))

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.

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 except error_y, which is used to draw the stems
• stem_color - sets the color of the stems
• stem_thickness - sets the thickness of the stems

to_html(
    io::IO,
    p::Plot;
    autoplay::Bool=true,
    include_plotlyjs::Union{String,Missing}="cdn",
    include_mathjax::Union{String,Missing}="cdn",
    post_script::Union{String,Missing}=missing,
    full_html::Bool=true,
    animation_opts::Union{Dict,Missing}=missing,
    default_width::String="100%",
    default_height::String="100%"
)

• io: IO stream to write to
• p: Plot to save
• autoplay: Should animations start automatically
• include_plotlyjs: How to include plotly.js. Options are
  • cdn: include a <script> tag to load plotly.js from cdn. Output will be standalone
  • require: load using requirejs. Useful in Jupyter notebooks
  • require-loaded: assume a plotly statement has already loaded via requirejs (don't load it in context of this plot)
  • directory: hardcode <script src="plotly.min.js> – will only work when the plotly.min.js file is in the same directory as the output file
  • anything ending in js: we assume you give us the path to the plotly.js file. We will read it in and include it inline in the output. Works best when points to a minified file (plotly.min.js)
• include_mathjax: How mathjax should be included. Options are
  • string ending in .js: we load via <script src="$(include_mathjax)">. You are responsible for making sure it resolves
  • anything else: we load via cdn for you
• post_script: arbitrary javascript to run after plotly.js finishes drawing the plot
• full_html: include all parts necessary for standalone html file
• animation_opts: extra options used to control animation. included in addFrames call after the actual frames. See plotly.js docs for more info on addFrames
• default_width: valid css specifier for width
• default_height: valid css specifier for height

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.

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"
      }
    }
  ]
}

vline(x, fields::AbstractDict=Dict{Symbol,Any}(); kwargs...)

Draw vertical lines at each point in x that span the height of the plot

GenericTrace(df, x, y; kwargs...)

Pass the provided values of x and y as keyword arguments for constructing the trace from df. See other method for more information

GenericTrace(df, y; kwargs...)

Pass the provided value y as keyword argument for constructing the trace from df. See other method for more information

GenericTrace(df; group, kind, kwargs...)

Build a trace of kind kind, using the columns of df where possible. In particular for all keyword arguments, if the value of the keyword argument is a Symbol and matches one of the column names of df, replace the value of the keyword argument with the column of df

If group is passed and is a Symbol that is one of the column names of df, then call by(df, group) and construct one trace per SubDataFrame, passing all other keyword arguments. This means all keyword arguments are passed applied to all traces

Also, when using this routine you can pass a function as a value for any keyword argument. This function will be replaced by calling the function on the DataFrame. For example, if I were to pass name=(df) -> "Wage (average = $(mean(df[!, :X1])))" then the name attribute on the trace would be replaced by the Wage (average = XX), where XX is the average of the X1 column in the DataFrame.

The ability to pass functions as values for keyword arguments is particularly useful when using the group keyword arugment, as the function will be applied to each SubDataFrame. In the example above, the name attribute would set a different mean for each group.

Parameters

• cell: index of the subplot cell to overlay inset axes onto.
• kind: Subplot kind (see Spec docs)
• l: padding left of inset in fraction of cell width
• w: inset width in fraction of cell width ('to_end': to cell right edge)
• b: padding bottom of inset in fraction of cell height
• h: inset height in fraction of cell height ('to_end': to cell top edge)

Plot(df; ...)
Plot(
    df,
    l;
    category_orders,
    labels,
    facet_row,
    facet_row_wrap,
    facet_col,
    facet_col_wrap,
    group,
    symbol,
    color,
    line_dash,
    kw...
)

Construct a plot using the columns of df if possible. For each keyword argument, if the value of the argument is a Symbol and the df has a column whose name matches the value, replace the value with the column of the df.

If group is passed and is a Symbol that is one of the column names of df, then call by(df, group) and construct one trace per SubDataFrame, passing all other keyword arguments. This means all keyword arguments are passed applied to all traces

All keyword arguments are passed directly to the trace constructor, with the following exceptions:

• category_orders: A mapping from DataFrame column name to a vector of values that appear in that column. Wherever the column is used in the chart (facets, x, y, etc.) the chart elements tied to the column will be sorted according to the vector of values specified here. This ordering can be partial, in which case all elements that appear in the DataFrame, but not in the vector of values specified here, will be included after values explicitly listed here.
• labels: A mapping from column names (symbols) to text that should appear on the chart. This can be used to customize the title of axes, title of legend, etc.
• facet_row: A symbol denoting which DataFrame column should be used to create facetted subplots in the vertical direction.
• facet_col: A symbol denoting which DataFrame column should be used to create facetted subplots in the horizontal direction.
• symbol: A symbol noting which column should be used for the marker symbol. The values of this column are not used directly, but rather a new trace will be created for each unique value in this column. Each trace will have a different marker symbol, such as circle, diamond, square, etc.
• color: Similar to symbol, but for the color of a trace
• line_dash: Similar to symbol, but for the line style of a trace.

Plot(d, y; ...)
Plot(d, y, l; kwargs...)

Construct a plot from df, passing the provided value y as a keyword argument. See docstring for other method for more information.

Plot(d, x, y; ...)
Plot(d, x, y, l; kwargs...)

Construct a plot from df, passing the provided values of x and y as keyword arguments. See docstring for other method for more information.

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.

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.

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.

Plot(x, y; ...)
Plot(x, y, l; kind, config, kwargs...)

Build a plot of with one trace of type kindand 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 ith column of x is paired with the ith column of y.

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. Set scrollZoom to false to disable scrolling for all subplots.
• editable: Determines whether the graph is editable or not. Sets all pieces of edits unless a separate edits 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, height
• displayModeBar: 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 name
• modeBarButtonsToAdd: 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.
• modeBarButtons: Define fully custom mode bar buttons as nested array where the outer arrays represents button groups, and the inner arrays have buttons config objects or names of default buttons.
• showLink: Determines whether a link to Chart Studio Cloud is displayed at the bottom right corner of resulting graphs. Use with sendData and linkText.
• 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 both plotlyServerURL to 'https://chart-studio.plotly.com' and also set showSendToCloud to true.
• linkText: Sets the text appearing in the showLink link.
• showEditInChartStudio: Same as showSendToCloud, but use a pencil icon instead of a floppy-disk. Note that if both showSendToCloud and showEditInChartStudio are turned, only showEditInChartStudio 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.

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.
  • Trace type: Put the name of the type of trace here and we will determine the appropriate kind of subplot

• 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 cell

• r: padding right of cell

• t: padding right of cell

• b: padding bottom of cell

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 for Spec for more information
  • Note: Use horizontal_spacing and vertical_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 for Inset for more info
• column_widths: Array of length cols 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 length rows 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 rows
• column_titles: list of length cols of titles to place above the top subplot in each column.
• row_titles: list of length rows 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 horizontally
• y_title: Title to place to the left of the left column of subplots, centered vertically

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 for Spec for more information
  • Note: Use horizontal_spacing and vertical_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 for Inset for more info
• column_widths: Array of length cols 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 length rows 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 rows
• column_titles: list of length cols of titles to place above the top subplot in each column.
• row_titles: list of length rows 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 horizontally
• y_title: Title to place to the left of the left column of subplots, centered vertically

savefig(
    io::IO,
    p::Plot;
    width::Union{Nothing,Int}=nothing,
    height::Union{Nothing,Int}=nothing,
    scale::Union{Nothing,Real}=nothing,
    format::String="png"
)

Save a plot p to the io stream io. They keyword argument format determines the type of data written to the figure and must be one of png, jpeg, webp, svg, pdf, eps, json, or html. scale sets the image scale. width and height set the dimensions, in pixels. Defaults are taken from p.layout, or supplied by plotly

savefig(
    p::Plot, fn::AbstractString;
    format::Union{Nothing,String}=nothing,
    width::Union{Nothing,Int}=nothing,
    height::Union{Nothing,Int}=nothing,
    scale::Union{Nothing,Real}=nothing,
)

Save a plot p to a file named fn. If format is given and is one of png, jpeg, webp, svg, pdf, eps, json, or html; it will be the format of the file. By default the format is guessed from the extension of fn. scale sets the image scale. width and height set the dimensions, in pixels. Defaults are taken from p.layout, or supplied by plotly