Plotly for MATLAB User Guide

Plotly is a browser-based data analysis and visualization tool that lets you and your team make and share beautiful, interactive graphs, 3D graphs, and streaming graphs via the open source JavaScript graphing library plotly.js.
This API allows MATLAB users to generate Plotly graphs from the desktop MATLAB environment: turning MATLAB figures into interactive, shareable, collaborative projects.
For more information on how to create specific chart types see our documentation examples

Initial Setup

The Plotly MATLAB API has been embedded into our MATLAB toolboxes and our Plotly credentials have been saved using plotlysetup.m. In order to start using the Plotly MATLAB API all we have to do now is start MATLAB! More information regarding installation / setting up the Plotly MATLAB API can be found on the online documentation.

How It Works

Plotly charts are described declaratively with struct and cell array objects. For an extensive list of the keys used to describe plotly graphs see our reference page. To get an idea of how the MATLAB API works, check out this simple example of how to translate a MATLAB figure, modify some attributes, and then send it to Plotly.

In [ ]:
>> x = linspace(-2*pi, 2*pi);
>> y1 = sin(x);
>> y2 = cos(x);
>> plot(x, y1, x, y2);

%% Translate the figure from MATLAB to Plotly
>> fig = plotlyfig(gcf);

>> fig.PlotOptions.Strip = 0; % If 0, don't strip MATLAB's styling in translation. If 1, strip MATLAB's styling.

>> fig.data
ans =

   [1x1 struct]    [1x1 struct]

>> fig.data{1}    % The 'type' of this trace is 'scatter'. scatter's reference: #scatter
ans =

        xaxis: 'x1'             % more about scatter's 'xaxis': #scatter-xaxis
        yaxis: 'y1'             % scatter's 'yaxis' property:   #scatter-yaxis
         type: 'scatter'
      visible: 1                % scatter's 'visible' property: #scatter-visible
            x: [1x100 double]   % scatter's 'x' property:       #scatter-x
            y: [1x100 double]   % scatter's 'y' property:       #scatter-y
         name: ''               % scatter's 'name' property:    #scatter-name
         mode: 'lines'          % scatter's 'mode' property:    #scatter-mode
         line: [1x1 struct]     % scatter's 'line' property:    #scatter-line
       marker: [1x1 struct]     % scatter's 'marker' property:  #scatter-marker
   showlegend: 1                % scatter's 'showlegend':       #scatter-marker

%% Modify or add new properties to this trace
>> fig.data{1}.name = 'Current'; % Update the legend name to 'Current'

>> fig.layout     % layout reference: #layout
ans =

        autosize: 0                     % layout's 'autosize':      #layout-autosize
          margin: [1x1 struct]          % layout's 'margin':        #layout-margin
      showlegend: 0                     % layout's 'showlegend':    #layout-showlegend
           width: 840                   % layout's 'width':         #layout-width
          height: 630                   % layout's 'height':        #layout-height
   paper_bgcolor: 'rgb(255,255,255)'    % layout's 'paper_bgcolor': #layout-paper_bgcolor
       hovermode: 'closest'             % layout's 'hovermode':     #layout-hovermode
    plot_bgcolor: 'rgba(0,0,0,0)'       % layout's 'plot_bgcolor':  #layout-plot_bgcolor
          xaxis1: [1x1 struct]          % layout's 'xaxis':         #layout-xaxis
          yaxis1: [1x1 struct]          % layout's 'yaxis':         #layout-yaxis
     annotations: {[1x1 struct]}        % layout's 'annotations':   #layout-annotations

>> fig.layout.showlegend = true;  % layout's 'showlegend':    #layout-showlegend
>> fig.layout.legend = struct('x', 1, 'y', 1); % Update the legend: #layout-legend
>> fig.layout.title = 'Modified plot';

%% Set the filename, and overwrite the plot if it already exists
>> fig.PlotOptions.FileName = 'Customized plot';
>> fig.PlotOptions.FileOpt = 'overwrite';
%% Use offline
%% Download the offline bundle
>> getplotlyoffline('https://cdn.plot.ly/plotly-latest.min.js') 
>> fig.PlotOptions.Offline = true;

%% Send to plotly
>> fig.plotly

Core Functions

fig2plotly.m

Plot a MATLAB figure object with Plotly

fig2plotly.m converts MATLAB figures to online Plotly graphs. MATLAB describes figures differently than Plotly. Plotly's MATLAB library crawls the MATLAB figure objects and translates the MATLAB attributes into the structure that Plotly uses to describe and draw data visualizations.

Usage

In [ ]:
[INPUT]:
resp = fig2plotly()
resp = fig2plotly(f)
resp = fig2plotly(gcf)
resp = fig2plotly(f,'property',value, ... )
resp = fig2plotly(gcf,'property',value, ... )

[WHERE]:
gcf - root figure object handle [double].
f - root figure object [struct] >> f = get(gcf)

[PROPERTIES]:
'name' - name of the plot [string]['untitled']
'strip' - use plotly default styling [boolean][0]
'open' - opens a browser with plot result [boolean][1]

[OUTPUT]:
resp - results info of the plot [struct]
resp.[url,warning,message,filename,error]

Example

In [ ]:
api_path = ('/Users/chuckbronson/Documents/PLOTLY/MATLAB_API_DEV/DEV/TEST_PLOTS');
addpath(genpath(api_path));

load fitdata x y yfit;
fig = figure;
scatter(x, y, 'k');
line(x, yfit, 'color', 'k', 'linestyle', '-', 'linewidth', 2);
line(x, yfit + 0.3, 'color', 'r', 'linestyle', '--', 'linewidth', 2);
line(x, yfit - 0.3, 'color', 'r', 'linestyle', '--', 'linewidth', 2);
legend('Data', 'Localized Regression', 'Confidence Intervals', 2);
xlabel('X');
ylabel('Noisy');

%%Just ONE line of Plotly Code!%%
resp = fig2plotly(fig,'filename','matlab_overview_1','strip',false); 
resp.url

ans = https://plot.ly/~matlab_user_guide/661/noisy-vs-x/

The above plot is the ouptut from calling the scatter.m and line.m functions inherent in MATLAB. Using the fig2plotly.m function, we are able to extract the relevant data from the MATLAB figure object and throw the output over to our Plotly account! The returned response variable, resp, is a structure array which contains a url field with the address of our plot.

Offline Example

We can make a Plotly graph in Matlab offline which will be saved as an html file to your current working directory using Plotly Offline. These html files will contain all of the necessary dependencies to render the plot within a browser.

In [ ]:
X = linspace(0,2*pi,50)';
Y = [cos(X), 0.5*sin(X)];
stem(X,Y)

fig2plotly(gcf,'offline',true,'filename','offline-graph');

self-hosted matlab online

getplotlyfig.m

Get data, style, and layout from the plots stored online

One of Plotly's secret powers is the ability to translate between MATLAB's structure/cell array syntax and JSON. This allows a smooth transition between your figures in MATLAB and those stored in your Plotly account. getplotlyfig.m allows you to grab the data, style, and layout information from your plots saved online. In fact, getploylyfig.m lets you grab the data, style and layout of anyone's Plotly plots (as long as they are made public) - not just your own! See a graph you like online? Grab the style, layout, and data and make one for yourself.

Usage

In [ ]:
[INPUT]:
plotlyfigure = getplotlyfig('file_owner',file_id)

[WHERE]:
file_owner - user name associated with the plot [string].
file_id - number identifier associated with the plot [string]

[OUTPUT]:
plotlyfigure - results info of the plot [struct] plotlyfigure.[data,layout]

Example

Here we can use getplotlyfig.m and have a go at changing the bar and line colours on a different graph: https://plot.ly/~matlab_user_guide/664/ !

In [ ]:
%%matlab
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%       GET PLOTLY FIG!       %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

plotlyfigure = getplotlyfig('matlab_user_guide','664'); 


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
%         DATA/STYLE          %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% COLOUR CHOICES 
col1 = '#3C8A22';
col2 = '#097054'; 
col3 = 'black'; 


% LINE STYLE 
plotlyfigure.data{1}.line.width = 10; 
plotlyfigure.data{1}.line.color = col2;  
plotlyfigure.data{1}.opacity = 0.7; 
plotlyfigure.data{1}.name = 'Infection Rate'; 

% BAR CHART STYLE 
plotlyfigure.data{2}.marker.color = col1;
plotlyfigure.data{2}.marker.line.width = 2; 
plotlyfigure.data{2}.marker.line.color = col3; 
plotlyfigure.data{2}.opacity = 0.7; 
plotlyfigure.data{2}.name = 'Cases'; 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
%           LAYOUT            %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Y2 AXIS STYLE
plotlyfigure.layout.yaxis2.titlefont.color = col3; 
plotlyfigure.layout.yaxis2.tickfont.color = col2;
plotlyfigure.layout.yaxis2.tickcolor = col2; 
plotlyfigure.layout.yaxis2.linecolor = col2; 
plotlyfigure.layout.yaxis2.linewidth = 2; 

% X AXIS STYLE
plotlyfigure.layout.xaxis.mirror = 0; 
plotlyfigure.layout.xaxis.showline = 0; 

% BAR LAYOUT
plotlyfigure.layout.bargap = 0.2; 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
%             ARGS            %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

args.layout = plotlyfigure.layout; 
args.filename = 'matlab_overview_5'; 
args.fileopt = 'overwrite'; 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
%           PLOTLY            %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

resp = plotly(plotlyfigure.data,args);
resp.url

saveplotlyfig.m

Save your MATLAB figure as an image using Plotly

saveplotlyfig.m allows you to convert your MATLAB figures into static images (.png, .svg, .pdf, .jpeg) using Plotly.

Usage

In [ ]:
[INPUT]:
saveplotlyfig(data, filename, format {otional})
saveplotlyfig(plotlyfigure, filename, format {optional})
NOTE: if format is unspecified, saveplotlyfig will use the image format given by the extension of filename. If filename does not have an explicit extension (ex: filename.pdf), the default format of PNG will be used for the conversion.

[WHERE]:
data - data/style of plot [cell array]
plotlyfigure.data - data/style of plot [cell array]
plotlyfigure.layout - layout of plot [struct]
filename - name of image to be saved [string]

[OUTPUT]:
Image 'filename' of the specified format (PNG, PDF, JPEG, or SVG) saved to your working directory.

Example

Let's have a look at saveplotlyfig.m to see how it works. Check out this next plot that was featured on the MATLAB plot gallery.

In [ ]:
%%matlab
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%            FROM MATLAB PLOT GALLERY              %
%  http://www.mathworks.com/discovery/gallery.html %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Load Morse data
load MDdata dissimilarities dist1 dist2 dist3

% Plot the first set of data in blue
fig = figure;
plot(dissimilarities, dist1, 'bo');
hold on;

% Plot the second set of data in red
plot(dissimilarities, dist2, 'r+');

% Plot the third set of data in green
plot(dissimilarities, dist3, 'g^');

% Add title and axis labels
title('Morse Signal Analysis');
xlabel('Dissimilarities');
ylabel('Distances');


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%            PLOTLY           %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

filename = 'matlab_overview_8'; 
resp = fig2plotly(fig,'filename',filename,'strip',false);
resp.url
In [ ]:
plotlyfigure = getplotlyfig('matlab_user_guide','670');
filename = 'morse.png'; 

saveplotlyfig(plotlyfigure,filename)

Boom! morse.png has been automatically saved to our working directory. Let's have a look.

https://plot.ly/~matlab_user_guide/670.png

Awesome! Do you notice how the above plot is no longer interactive? That's because it is a static PNG image, ready to be placed in your offline documents. Plotly graphics are rendered as high-quality vector graphics so they embed really well in presentations and reports.