API Documentation
Base.size
— Methodsize(::PlotlyBase.Plot)
Return the size of the plot in pixels. Obtained from the layout.width
and layout.height
fields.
PlotlyBase.addtraces!
— Methodaddtraces!(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!
— Methodaddtraces!(p::Plot, traces::AbstractTrace...)
Add trace(s) to the end of the Plot's array of data
PlotlyBase.circle
— FunctionDraw a circle from ((x0
+x1
)/2, (y0
+y1
)/2)) with radius (|(x0
+x1
)/2 - x0
|, |(y0
+y1
)/2 -y0
)|)
PlotlyBase.deletetraces!
— Methoddeletetraces!(p::Plot, inds::Int...) =
Remove the traces at the specified indices
PlotlyBase.extendtraces!
— Functionextendtraces!(::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
— Functionhline(y, fields::AbstractDict=Dict{Symbol,Any}(); kwargs...)
Draw horizontal lines at each point in y
that span the width of the plot
PlotlyBase.line
— FunctionDraw a line through the points (x0, y0) and (x1, y2)
PlotlyBase.movetraces!
— Methodmovetraces!(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!
— Methodmovetraces!(p::Plot, to_end::Int...)
Move one or more traces to the end of the data array"
PlotlyBase.path
— MethodDraw an arbitrary svg path
PlotlyBase.prependtraces!
— Functionprependtraces!(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
— FunctionDraw a rectangle linking (x0
,y0
), (x1
,y0
), (x1
,y1
), (x0
,y1
), (x0
,y0
)
PlotlyBase.relayout!
— Functionrelayout!(l::Layout, update::AbstractDict=Dict(); kwargs...)
Update l
using update dict and/or kwargs
PlotlyBase.relayout!
— Methodrelayout!(p::Plot, update::AbstractDict=Dict(); kwargs...)
Update p.layout
on using update dict and/or kwargs
PlotlyBase.restyle!
— FunctionThe 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!
— Functionrestyle!(p::Plot, ind::Int=1, update::AbstractDict=Dict(); kwargs...)
Update p.data[ind]
using update dict and/or kwargs
PlotlyBase.restyle!
— Functionrestyle!(::Plot, ::AbstractVector{Int}, ::AbstractDict=Dict(); kwargs...)
Update specific traces at p.data[inds]
using update dict and/or kwargs
PlotlyBase.restyle!
— Functionrestyle!(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.restyle!
— Functionrestyle!(p::Plot, update::AbstractDict=Dict(); kwargs...)
Update all traces using update dict and/or kwargs
PlotlyBase.savefig
— Methodsavefig(
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
PlotlyBase.savefig
— Methodsavefig(
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
PlotlyBase.sizes
— FunctionGiven 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.stem
— Methodstem(; 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.trace_map
— Functiontrace_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
.
PlotlyBase.update!
— FunctionApply 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
— Functionvline(x, fields::AbstractDict=Dict{Symbol,Any}(); kwargs...)
Draw vertical lines at each point in x
that span the height of the plot
PlotlyBase.GenericTrace
— MethodGenericTrace(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
PlotlyBase.GenericTrace
— MethodGenericTrace(df, y; kwargs...)
Pass the provided value y
as keyword argument for constructing the trace from df
. See other method for more information
PlotlyBase.GenericTrace
— MethodGenericTrace(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.
PlotlyBase.Plot
— TypePlot(fs, x0, x1)
Plot(fs, x0, x1, l; style, 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
— TypePlot(df)
Plot(df, l; style, kwargs...)
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
PlotlyBase.Plot
— TypePlot(f, x0, x1)
Plot(f, x0, x1, l; style, 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
— TypePlot(d, x, y)
Plot(d, x, y, l; style, 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.
PlotlyBase.Plot
— TypePlot(d, y)
Plot(d, y, l; style, kwargs...)
Construct a plot from df
, passing the provided value y as a keyword argument. See docstring for other method for more information.
PlotlyBase.Plot
— MethodPlot(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
— MethodPlot(x, y)
Plot(x, y, l; kind, style, 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.savehtml
— FunctionPlotlyBase.savehtml(io::IO, p::Union{Plot,SyncPlot}, js::Symbol=js_default[])
PlotlyBase.savehtml(p::Union{Plot,SyncPlot}, fn::AbstractString, js::Symbol=js_default[])
Save plot to standalone html file suitable for including in a website or opening in a browser
Can either be written to an arbitrary IO stream, or saved to a file noted with a string fn
.
The js
argument can be one of
:local
: Reference the local plotly.js file included in this Julia package Pros: small file size, offline viewing. Cons: Can't share with others or move to different machine..:remote
: Reference plotly.js from a CDN. Pros small file size, move to other machine. Cons: need internet access to fetch from CDN:embed
: Embed the entirety of your local copy of plotly.js in the outputted file. Pros: offline viewing, move to other machine. Con: large file size (adds about 2.7 MB)
The default is :local