Native MATLAB graphing functions have been included as overloaded methods of plotlyfigure.m
. These methods behave excatly as their corresponding MATLAB counterparts with the additional functionality of automatically populating the data and layout properties of the plotlyfigure.m object and making a direct call to Plotly via the plotly
method. These methods can be invoked by passing a plotlyfigure object as the first argument to the native MATLAB plotting function.
EXAMPLE:
>> p = plotlyfigure.m;
>> plot(p, ... );
The following graphing functions are currently supported:
area
bar
image
imagesc
line
patch
rectangle
contour
plot
errorbar
quiver
scatter
stairs
stem
boxplot
mesh
data [cell array]
The data traces associated with the Plotly figure.
layout [structure array]
The layout structure associated with the Plotly figure.
PlotOptions [structure array]
The Plot options associated with the creation of the
plotlyfigure.m
object within MATLAB and the online figure created on your Plotly account. The following fields are contained withthin the PlotOptions property:
FileName [string]:
The name of the figure as it will appear at the top of the figure in MATLAB and the filename associated with the figure created on Plotly. By default
Filename = 'myplotlyfigure'
if no filename is provided upon the initialization of the plotlfigure object.
FileOpt [string]:
The file write option specifying how each new call to Plotly will affect the plot in your workspace of the same name. By default
FileOpt = 'overwrite'
. SetFileOpt = 'new' or 'append' or 'extend'
as desired.
WorldReadable [boolean]:
The privacy of the figure once sent to Plotly. By default,
WorldReadable = true
for public graphs. For private graphs, setWorldReadable = false
.
OpenURL [boolean]:
A boolean switch used for displaying/suppressing the figure hyperlink when a call is made to Plotly. By default,
OpenUrl = true
and the URL is displayed (if a MATLAB command window is present). SetOpenUrl = false
to suppress displaying the figure hyperlink.
Visible [boolean]:
A boolean switch used for displaying/supressing the MATLAB figure upon creation of the plotlyfigure object. By default
Visible = true
and the MATLAB figure is displayed. SetVisible = false
to prevent the MATLAB figure from being displayed upon creation.
State [structure array]
The state property houses infromation regarding the MATLAB figure, axes, plots, texts, colorbars, and legends involved in the creation of the Plotly figure. The fields contained with the
State
property structure the information on each of these MATLAB graphics objects as follows:
å
Figure [structure array]:
The
Figure
field of theState
property is a structure array with the following fields:
Handle: graphics handle associated with the figure.
NumAxes: number of axes parented by the figure.
NumPlots: number of plots parented by the figure.
NumLegends: number of legends parented by the figure.
NumColorbars: number of colorbars parented by the figure.
NumTexts: number of text parented by the figure.
Axis [array of structs]:
The
Axis
field of theState
property is a structure array with the following fields:
Handle: graphics handle associated with the axis.
Plot [array of structs]:
The
Plot
field of theState
property is a structure array with the following fields:
Handle: graphics handle associated with the plot.
AssociatedAxis: graphics handle of the axis parenting the plot.
Class: name of graphing class associated with the plot.
Text [array of structs]:
The
Text
field of theState
property is a structure array with the following fields:
Handle: graphics handle associated with the plot.
AssociatedAxis: graphics handle of the axis parenting the text.
Title: boolean indicating if the text is an axis title (true).
Colorbar [array of structs]:
The
Colorbar
field of theState
property is a structure array with the following fields:
Handle: graphics handle associated with the colorbar.
AssociatedAxis: graphics handle of the axis peered with the colorbar.
Legend [array of structs]:
Handle: graphics handle associated with the legend.
AssociatedAxis: graphics handle of the axis peered with the legend.
PlotlyDefaults
[structure array]
The defaults used to smooth the transition between the MATLAB and Plotly figures. These settings can be changed to suit your personal preference. The current Plotly Defaults are set as follows:
å
PlotlyDefaults.MinTitleMargin = 80;
PlotlyDefaults.TitleHeight = 0.01;
PlotlyDefaults.FigureIncreaseFactor = 1.5;
PlotlyDefaults.AxisLineIncreaseFactor = 1.5;
PlotlyDefaults.MarginPad = 0;
PlotlyDefaults.MaxTickLength = 20;
PlotlyDefaults.ExponentFormat = 'none';
PlotlyDefaults.ErrorbarWidth = 6;
PlotlyDefaults.ShowBaselineLegend = false;
PlotlyDefaults.Bargap = 0;
UserData [structure array]
The data associated with the user and the user experience. The fields contained within the UserData structure are as follows: å
Username [string]:
The username associated with your Plotly account.
ApiKey [string]:
The API key associated with your Plotly account.
PlotlyDomain [string]:
The endpoint url for the REST API. By default the Plotly domain is set to https://plot.ly . This may change depening on your Plotly subscription.
Verbose: [boolean]:
A boolean switch used to enable/disable the output of the
plotlyfigure
object'svalidation
method. By default,Verbose = true
and any errors found from the data/layout keys validation will be outputted. SetVerbose = false
to supress this output.
Response [structure array]
A structure array containing the response returned once successfully making a call to the Plotly REST API. The
Response
property is only populated once theplotly
method is invoked. The fields of theResponse
property are as follows:
å
filename [string]:
The filename of the plot as saved in your user account.
url [string]:
A url where you can view the rendered graph of your data.
error: [string]:
A string describing a possible error that may have occured. Example:
Error: A user with this username already exists
warning [string]:
A string describing a possible warning message. A string describing a possible warning message. Example:
Warning: You are using an outdated version of the API
message [string]:
A string describing a non-critical message.
Example: Message: Plotly has recently expanded the API library.
plotlyfigure
: Class constructor
[INPUT]:
>> p = plotlyfigure;
>> p = plotlyfigure(fig_han)
>> p = plotlyfigure(fig_han, ...,'Property','Value',...)
>> p = plotlyfigure(...,'Property','Value',...)
[WHERE]:
fig_han: [handle]
Figure handle to be parsed
[PROPERTIES / VALUES]:
filename: [string]{'plotlyfigure'}
Name of the Plotly figure
fileopt: [string]{'overwrite'}
new, overwrite, extend, append
world_readable[boolean]{true}
true = public , false = private
open[boolean]{true}
true = show hyperlink (if command window), false = no hyperlink
visible[boolean]{true}
true = show MATLAB figure, false = hide MATLAB figure
data[cell array]{}
Initial data cell array
layout[structure array]{struct()}
Initial layout structure array
[OUTPUT]:
p [object]
plotlyfigure object
update
: Parse the MATLAB figure and update the data and layout properties
[INPUT]:
>> p.update;
>> update(p);
[WHERE]:
p: [object]
plotlyfigure object
[OUTPUT]:
p.data
updated with parsed figure data
p.layout
updated with parsed figure layout
plotly
: Upload the figure to your Plotly account
[INPUT]:
>> p.plotly;
>> plotly(p);
[WHERE]:
p: [object]
plotlyfigure object
[OUTPUT]:
Creation/update of online Plotly figure
p.Response
updated with Plotly REST API response
strip
: Remove all graph object keys of type "style"
[INPUT]:
>> p.strip;
>> strip(p);
[WHERE]:
p: [object]
plotlyfigure object
[OUTPUT]:
p.data
updated with all graph oject keys of type "style" removed
p.layout
updated with all graph oject keys of type "style" removed
getdata
: Retrieve all graph object keys of type "data"
[INPUT]:
>> data = p.getdata;
>> data = getdata(p);
[WHERE]:
p: [object]
plotlyfigure object
[OUTPUT]:
data [cell array]
cell array of all graph oject keys of type "data" in
p
**
validate
: Validate the data and layout graph object key syntax
[INPUT]:
>> p.validate;
>> validate(p);
[WHERE]:
p: [object]
plotlyfigure object
[OUTPUT]:
A warning message displayed if any graph object keys within the data and layout fields are invalid and
p.UserData.Verbose = true
grab
: Retrieve the data/layout information from an online Plotly figure
[INPUT]:
>> p.grab('fileowner','file_id');
>> grab(p,'fileowner','file_id');
[WHERE]:
p: [object]
plotlyfigure object
file_owner: [string]{}
Username of the owner of the Plotly figure
file_id: [strin]{}
Identification number of the Plotly figure
[OUTPUT]:
p.data
updated with data of the requested Plotly figure
p.layout
updated with the layout of the requested Plotly figure
saveas
: Save a static image of plotlyfigure to specified directory
[INPUT]:
>> p.saveas('filename');
>> saveas(p,'filename');
[WHERE]:
p: [object]
plotlyfigure object
filename: [string]{p.PlotOptions.FileName}
The name of the image to be saved
[OUTPUT]:
A static image representation of your Plotly figure
*If a directory is not specified within the filename, the image is saved to the current working directory
*If an image extension is not specified in the filename, a .png image is rendered by default.
jpeg
: Save a static JPEG image of plotlyfigure to specified directory
[INPUT]:
>> p.jpeg('filename');
>> jpeg(p,'filename');
[WHERE]:
p: [object]
plotlyfigure object
filename: [string]{p.PlotOptions.FileName}
The name of the image to be saved
[OUTPUT]:
A static JPEG image representation of your Plotly figure
*If a directory is not specified within the filename, the image is saved to the current working directory
pdf
: Save a static PDF image of plotlyfigure to specified directory
[INPUT]:
>> p.pdf('filename');
>> pdf(p,'filename');
[WHERE]:
p: [object]
plotlyfigure object
filename: [string]{p.PlotOptions.FileName}
The name of the image to be saved
[OUTPUT]:
A static PDF image representation of your Plotly figure
*If a directory is not specified within the filename, the image is saved to the current working directory
png
: Save a static PNG image of plotlyfigure to specified directory
[INPUT]:
>> p.png('filename');
>> png(p,'filename');
[WHERE]:
p: [object]
plotlyfigure object
filename: [string]{p.PlotOptions.FileName}
The name of the image to be saved
[OUTPUT]:
A static PNG image representation of your Plotly figure
*If a directory is not specified within the filename, the image is saved to the current working directory
svg
: Save a static SVG image of plotlyfigure to specified directory
[INPUT]:
>> p.svg('filename');
>> svg(p,'filename');
[WHERE]:
p: [object]
plotlyfigure object
filename: [string]{p.PlotOptions.FileName}
The name of the image to be saved
[OUTPUT]:
A static SVG image representation of your Plotly figure
*If a directory is not specified within the filename, the image is saved to the current working directory
Want to help improve this notebook? Please send us your comments/questions! Feedback concerning this notebook can be directed to ** chuck@plot.ly **
# CSS styling within IPython notebook
from IPython.display import display, HTML
display(HTML(open('./css/custom.css').read()))