plotly / plotly_matlab

Plotly Graphing Library for MATLAB®

Plotly Graphing Library for MATLAB®

Plotly Graphing Library for MATLAB® - Create interactive charts in your web browser with MATLAB® and Plotly

Version: 2.2.10

MATLAB is a registered trademarks of The MathWorks, Inc.

Install

The latest version of the wrapper can be downloaded here.

Once downloaded, run plotlysetup_offline() to get started If you have a plotly bundle url of the form 'http://cdn.plot.ly/plotly-latest.min.js', then run instead `plotlysetup_offline('plotly_bundle_url')

For online use, run plotlysetup_online('your_username', 'your_api_key') to get started.

Updates

NOTE: plotlyupdate.m is currently turned off.

Please manually download and setup the latest version of the wrapper by following the installation instructions above.

Usage

Convert your MATLAB® figures into online Plotly graphs with a single line of code:

 % Create some data for the two curves to be plotted
 x  = 0:0.01:20;
 y1 = 200*exp(-0.05*x).*sin(x);
 y2 = 0.8*exp(-0.5*x).*sin(10*x);

 % Create a plot with 2 y axes using the plotyy function
 figure;
 [ax, h1, h2] = plotyy(x, y1, x, y2, 'plot');

 % Add title and x axis label
 xlabel('Time (s)');
 title('Frequency Response');

 % Use the axis handles to set the labels of the y axes
 set(get(ax(1), 'Ylabel'), 'String', 'Low Frequency');
 set(get(ax(2), 'Ylabel'), 'String', 'High Frequency');

 %--PLOTLY--%
 p = fig2plotly; % <-- converts the yy-plot to an interactive, online version.

 %--URL--%
 % p.url = 'https://plot.ly/~matlab_user_guide/1522'

Also, access other Plotly services and graphs programatically. Like, publication-quality image export:

 saveplotlyfig(p, 'testimage.svg')

and Plotly figure retrieval:

 p = getplotlyfig('chris', 1638) % downloads the graph data from https://plot.ly/~chris/1638

Documentation

This lives here: https://plot.ly/matlab

Questions & troubleshooting

• https://community.plotly.com/c/api/matlab/

Contribute

Please do! This is an open source project. Check out the issues or open a PR!

We want to encourage a warm, welcoming, and safe environment for contributing to this project. See the code of conduct for more information.

License

MIT © 2021 Plotly, Inc.

plotly_matlab's Issues

Update persistent variables with endpoint urls

is this right @BRONSOLO ? or do we just need to update the instructions?

clustergram support

This would be cool:

http://www.mathworks.com/help/bioinfo/ref/clustergram.html?refresh=true

CleanFeedTitle should not grab empty annotations as the title

A user wrote in unable to locate the plot title using the webapp. Typically, the title is simply set as the first subplot title (from CleanFeedTitle). In their case, the first subplot title was empty () , making it very hard to find in the web app. Note: Empty annotations are being set as (a carry over from the old wrapper design). I believe just changing empty annotations to being empty strings '' will fix the problem.

carpet plots

These almost work, but render in 3d instead of 2d:

http://www.mathworks.com/matlabcentral/fileexchange/41467-the-carpetplot-class/content/html/carpetplot.html

I've had this issue with streamline plots too - plots that draw in a 3d scene but the data is only in the x-y plane at z=0. It would be cool if there were a way to "force" drawing in 2d.

Link to Mathwork's FEX

You can now link github to the file excahnge repos by the Mathworks.
This would give more visibility and allow other to contribute.

figures created with `initial` don't convert

A = [-0.8 3.6 -2.1;-3 -1.2 4.8;3 -4.3 -1.1];
B = [0; -1.1; -0.2];
C = [1.2 0 0.6];
D = -0.6;
G = ss(A,B,C,D);
x0 = [-1;0;2];  % initial state
initial(G,x0)
grid

>> fig2plotly()
Attempted to access m_data.Children(1); index out of bounds because
numel(m_data.Children)=0.

Error in findDataType (line 77)
    m_child  = m_data.Children(1);

Error in convertFigure (line 79)
                    data_type = findDataType(m_data, m_axis);

Error in fig2plotly (line 70)
[data, layout, title] = convertFigure(f, strip_style);

create multi-lined title example

FH = figure;
plot(rand(1,2),rand(1,2))
title({'line1','line2'})
fig2plotly(FH)

shouldn't need credentials to create a `plotlyfig` now that `plotlyfig`s are used in offline mode

"Error using ==> plotlyfig>plotlyfig.plotlyfig at 47
Oops! You must be signed in to initialize a plotlyfig object."

cc @cldougl @BRONSOLO

Time series x-axis errors on fig2plotly

Using the first example here:
http://www.mathworks.com/help/matlab/ref/timeseries.plot.html

Rounding when converting MATLAB data to JSON

Noticed that when MATLAB generates the JSON after calling fig2plotly(), it may round the data such that it displays incorrectly in Plotly. It particularly happens with datenums, e.g. where 7.357676e+05 in the JSON doesn't have enough resolution to distinguish seconds.

e.g.

dts = datenum('2014-06-01 12:00'):(1/24/3600):datenum('2014-06-01 15:00');
data = sin((2*pi/length(dts))*(1:length(dts)));
figure; plot(dts,data);
datetick;
fig2plotly();

3d quiver plots render in 2d

These would be cool:
http://www.mathworks.com/help/matlab/ref/quiver3.html

`plotlysetup` should still try to save credentials even if it can't place folders in toolbox directory

Multiple plots in a single figure should use Plotly titles instead of annotations.

x=[1:10];
y1=2*x;
y2=3*x;
plot(x,y1);hold all;plot(x,y2);hold off;
title('hello2');
fig2plotly;

plotly in Octave

Hi

I did try to install plotly api (v2.1.9) with Octave 3.8.
The plotly directory has been correctly installed. So does the signin with account and key. But when I try a basic test as in https://plot.ly/matlab/plot/ , I got the following message:

error: invalid use of script C:\Octave\MATLAB-api-master\plotly\plotlyfig.m in index expression
error: called from:
error: C:\Octave\MATLAB-api-master\plotly\fig2plotly.m at line 44, column 3
error: C:\temp\testing_plotly.m at line 24, column 10

plot.ly generates blank graph with warning message

A graph in matlab is created and fig2plotly called. The following warning message is generated and no plot available on the URL:
Warning: Integer operands are required for colon operator when used as index

In parseFill at 30
In convertFigure at 117
In fig2plotly at 70
https://plot.ly/~nive/0
What is going on?

marker pixel size mapping could be improved

N = 10;
x = linspace(1, 10, 10);
hold on
clr1 = [133, 20, 75]/255;
plot(x, y, '.', x, mean(y'), 'linewidth', 2, 'MarkerSize', 10, 'Color', clr1);
plot(x, mean(y'), '.', 'MarkerSize', 32, 'Color', clr1)
fig2plotly(gcf, 'strip', false)

Does Plotly support Latex Encoding in Text?

If I use LaTeX interpreter in MATLAB figure, does Plotly will be able to display the test in LaTeX?

Thank You.

OHLC charts barf on conversion

http://www.mathworks.com/help/finance/highlow.html

tickfont size too small in fig2plotly conversion

plotlyfig fails on MATLAB 2014+

---

ERROE MESSAGE

No appropriate method, property, or field 'classhandle'
for class 'matlab.ui.Figure'.
Error in plotlyfig (line 110)
                        if
                        strcmp(handle(varargin{1}).classhandle.name,'figure')
                        Error in fig2plotly (line 44)
p = plotlyfig(varargin{:}); 

---

SOLUTION

file plotlyfig, line 100, change to

if strcmp(get(varargin{1},'type'),'figure')

first heatmap example failing in 2014b

https://plot.ly/matlab/heatmaps/

1st example won't convert unless
colorbar; is commented out
// also the linked graph isn't colormap('hot');

Make plotlyhelp('online') point to enterprise instance

currently hardcoded as https://plot.ly/matlab

Re-run tests on R2015a

Inject axis information for 3D in scene key

Currently, this is not being done and axis information is being auto formatted.

scatter3 creates a 2d plot

[X,Y,Z] = sphere(16);
x = [0.5_X(:); 0.75_X(:); X(:)];
y = [0.5_Y(:); 0.75_Y(:); Y(:)];
z = [0.5_Z(:); 0.75_Z(:); Z(:)];
scatter3(x,y,z)

1.0

#8 presents a really seamless new interface between fig2plotly and matlab's native plotting routines (thanks @okomarov!).

@BRONSOLO and I suggest the following re-design of our module:

PLOTLY-MATLAB 1.0

• p = plotlyfig;

  • p = plotlyfig(filename, fileopt, world_readable, auto_open);
  • p = plotlyfig('filename', filename, 'fileopt', fileopt, 'world_readable', world_readable, 'auto_open', auto_open);

  Properties

  • p.Data
  • p.Layout
  • p.PlotOptions.Filename (defaults to 'MATLAB plot')
  • p.PlotOptions.FileOpt (defaults to 'new', implicitly set to 'overwrite' if filename is specified)
  • p.PlotOptions.WorldReadable (defaults to true)
  • p.PlotOptions.StripStyle (defaults to true)
  • p.PlotOptions.AutoOpen (defaults to true)

  Methods

  • plot(p)

    saves the plotlyfig (p.Data and p.Layout) to user's account on plotly
    with p.Filename, FileOpt, WorldReadable.

    p = plotlyfig;
    p.Layout.title = 'my graph title';
    p.Data{1}.x = [1,2,3];
    p.Data{1}.y = [10,20,30];
    
    p.PlotOptions.Filename = 'my plotly filename';
    
    plot(p);
    

    Also, all overloaded plot commands, e.g.:

    • plot(p, x1, y1, 'r-', x2, y2, 'g-o');
    • hist(p, y1);
    • bar(p, x1, y1);
    • polar(p, x1, y1);
    • scatter(p, x1, y1);
    • stem(p, x1, y1);
    • step(p, x1, y1);
    • contour(p, z);
    • image(p, z);

    These commands:

    1. create an invisible MATLAB fig
    2. convert it to plotly's syntax via fig2plotly and populate a plotlyfig
       object with Data and Layout
    3. ship that plotlyfig to that user's account with
       filename as p.PlotlyOptions.Filename,
       fileopt as p.PlotOptions.FileOpt,
       WorldReadable as p.PlotOptions.WorldReadable

  • p_new = p.GetData()

    returns a plotlyfig with the "data" keys
    (as classified in the graph_reference repo: https://github.com/plotly/graph_reference)

    Usage

    >>> chris_figure = getplotlyfig('https://plot.ly/~chris/34')
    >>> disp(chris_figure.Data{1})
      x = [1,2,3]
      y = [10,20,30]
      marker.color = 'blue'
    >>> chris_data = chris_figure.getdata()
    >>> disp(chris_data{1})
      x = [1,2,3]
      y = [10,20,30]
    

  • p.saveas('filename.ext') % saveas(p, 'filename.ext');

    • p.saveas(h, 'filename', 'format') % saveas(p, 'local_filename', 'format');

      Saving Static Images - Route 1

      p = plotlyfig;
      plot(p, x, y)
      ...
      
      saveas(p, 'local_filename', 'png');
      
      

      Saving Static Images - Route 2

      plot(x, y)
      ...
      
      p = fig2plotly(gcf);
      saveas(p, 'local_filename', 'png');
      

      Saving Static Images - Route 3

      p = plotlyfig;
      p.Layout.title = 'my graph title';
      p.Data{1}.x = [1,2,3];
      p.Data{1}.y = [10,20,30];
      
      saveas(p, 'local_filename', 'png');
      

• plotlysetcredentials(username, api_key)

  Credentials are saved to ~/.plotly/.credentials and set in calling
  plotlysetcredentials(username, api_key).

  Credential Examples

  • Setting credentials:

    setplotlycredentials('chris', 'asdfbasd');
    

  • Error setting credentials (e.g. permission denied to write to that file):

    >>> setplotlycredentials('chris', 'asdfbasd');
    Error: Saving your credentials to /home/chris/.plotly/.credentials failed.
    Contact your systam admin or [email protected] for some help. For now, 
    you can still sign in with:
     >>> plotlysignin('chris', 'asdbad3d');
    

  • Temporarily setting credentials to persistent variable space:

    plotlysignin('chris', 'asdbad3d')
    

  • Implicit retrieval of credentials:

    p = plotly; 
    

    retrieves creds from file and sets as persistent variables in session, or
    throws an error if not found, prompting user to call setplotlycredentials,
    or plotlysignin.

• plotlysignin(username, api_key)

• plotlysetup(username, api_key)

• p = getplotlyfig(username, id) % returns a plotlyfig object

  • p = getplotlyfig(url) % p = plotlygetfig('https://plot.ly/~chris/34')

• p = fig2plotly() % returns a plotlyfig object, doesn't call plotly

  • p = fig2plotly(fig_handle)
  • p = fig2plotly(get(fig_handle))

Plot Scripting and hold on

Option 1 - fig2plotly

plot(x, y)
title('my title')
plot(fig2plotly());

Option 2 - store figure calls in p object, and re-call on every command

p = plotlyfig('my plotly filename');
plot(p, x, y); % calls plot(x,y), then fig2plotly();
title(p, 'my title'); % calls plot(x,y); title('my title'); then fig2plotly();

p might also hold the reference to the figure, so that:

p = plotlyfig;
plot(p, x, y);
plot(p, x, y*2);

would create 2 plots, but

p = plotlyfig;
hold on
plot(p, x, y);
plot(p, x, y*2);

would graph on the same plot (each command would make a call to plotly's servers)

Filenames

Workflow

%%%%%%%
%% When messing around, and not ready to save multiple figures, do:

p = plotlyfig('mess around'); % implicitly sets `file_opt` to `overwrite`

plot(p, x, sin(x)); % saves to e.g. https://plot.ly/~chris/12

plot(p, x, 2*sin(x)); % new figure, same url (https://plot.ly/~chris/12)

%%%%%%%
%% When making several plots that you want to save in a row

plot(plotlyfig('first figure'), x, sin(x));

plot(plotlyfig('second figure'), x, 2*sin(x));

% alternatively

p = plotlyfig;
p.filename = 'first figure';
plot(p, x, sin(x));

p.filename = 'second figure';
plot(p, x, 2*sin(x));

`step(sys)` and `impulse(sys)` don't convert

subplot(211), step(sys)
subplot(212), impulse(sys)

leads to empty plots: https://plot.ly/~chris/2714

Plotly SSL certificate

Hi

I am trying to use MATLAB-api on Octave 4.0. But when I try a simple test script:
x=[1 2 3]
y = [2 4 6]
plotly(x,y)

I got the following error message:
error: urlread: Peer certificate cannot be authenticated with given CA certificates
error: called from
makecall at line 24 column 14
plotly at line 28 column 10

Signin function did not return any error message before.

Calling plotlyhelp error

Hey @BRONSOLO,

The MATLAB API is amazing. Just took it for a spin, got some tips from @chriddyp, and whoa is it cool. Nice work.

I got the following error when I called plotlyhelp. Might have been on my end.

Plotly in Octave 3.8.0 on OS X

Hello,

I just installed plotly on my octave 3.8.0 on OSX yosemite. It installed flawlessly, however, when I tried the first example on the plotly website:

[X,Y,Z] = peaks;
contour(X,Y,Z,20)
fig2plotly()

that was the response I got:

error: invalid use of script /Users/KSalim/Desktop/plotly/plotly/plotlyfig.m in index expression
error: called from:
error: /Users/KSalim/Desktop/plotly/plotly/fig2plotly.m at line 44, column 3
2015-09-27 16:47:17.645 octave-gui[6108:2318329] modalSession has been exited prematurely - check for a reentrant call to endModalSession:

Help, anyone?

Candlestick charts don't convert

load disney;
candle(dis_HIGH(end-20:end), dis_LOW(end-20:end), dis_CLOSE(end-20:end),...
dis_OPEN(end-20:end), 'b');

Do not revert 3D scatter to 2D if multiple 3D plots present in figure.

A user wrote in with a figure that contained a 3D surface + contour line projected onto the z=0 xy-plane. The parser interpreted these projections as 2D because of this: https://github.com/plotly/MATLAB-api/blob/master/plotly/plotlyfig_aux/handlegraphics/updateScattergroup.m#L86-L90 (a workaround for some 2D plots that contain Z data which is set to be entirely zero). We do not support 2D + 3D mixed plots so this figure did not render. We could probably get around this by checking to see if the figure contains multiple 3D plots and if so, trying to render everything as 3D.

Plotly in Octave 3.8.

Add fig2plotly support for polar coordinate plot types: (polar(), rose(), compass() functions)

Plots in polar coordinates (polar(), rose(), compass() functions) post to plotly without polar coordinate axes

Helper function to add caption-like annotations

scatter and scatter3 don't format correctly

% In matlab r2014b,
[X,Y,Z] = sphere(16);
x = [0.5*X(:); 0.75*X(:); X(:)];
y = [0.5*Y(:); 0.75*Y(:); Y(:)];
z = [0.5*Z(:); 0.75*Z(:); Z(:)];
% 2d scatter
scatter(x,y,6,'go')
hold on
scatter(x,y,72,'ko')
fig2plotly()
% 3d scatter
hold off
scatter3(x,y,z,6,'bo')
hold on
scatter3(x,y,z,36,'go')
fig2plotly()

Use plotly titles over annotations when appropriate.

Currently we are using annotations for all titles because of the flexibility with positioning.

2d quiver plots aren't showing arrows

Here's the code

u = cos(x)._y;
v = sin(x)._y;

figure
quiver(x,y,u,v)
fig2plotly()```

Here's the result

![image](https://cloud.githubusercontent.com/assets/1865834/8791575/9964391a-2f2a-11e5-85f2-5b435b184109.png)
https://plot.ly/~jackp/9543

This is the vanilla example in the MATLAB docs:
http://www.mathworks.com/help/matlab/ref/quiver.html

Running this on the 2014b version:
![image](https://cloud.githubusercontent.com/assets/1865834/8791570/8e7d636e-2f2a-11e5-8310-936415a2a3cb.png)

mispelled attribute 'tiltefont' is created in convertFigure

Plotly's hiccups on MATLAB dendrogram plots

These fellows: http://www.mathworks.com/help/stats/dendrogram.html

Traceback:

Reference to non-existent field 'Title' for figures with colorbar

A basic plot with colorbar produces the following error on my MATLAB 2015a version:

surf(peaks)
colorbar
fig2plotly(gcf)

Reference to non-existent field 'Title'.

Error in updateColorbar (line 77)
colorbar_title = colorbar_data.Title;

Error in plotlyfig/update (line 533)
updateColorbar(obj,n);

Error in plotlyfig (line 186)
obj.update;

Error in fig2plotly (line 44)
p = plotlyfig(varargin{:});

plotly in Octave

When I run plotlysetup in Octave in Windows 7, I get the following error:
\nOctave users: Automatic Plotly API embedding coming soon!\n

Saving username/api_key credentials ... warning: unrecognized escape sequence '\U' -- converting to '
U'
warning: unrecognized escape sequence '\B' -- converting to 'B'
warning: unrecognized escape sequence '\D' -- converting to 'D'
warning: unrecognized escape sequence '\w' -- converting to 'w'
warning: unrecognized escape sequence '\M' -- converting to 'M'
warning: unrecognized escape sequence '\p' -- converting to 'p'
warning: unrecognized escape sequence '\p' -- converting to 'p'
warning: unrecognized escape sequence '\m' -- converting to 'm'

parse error near line 37 of file C:UsersBehzadDropboxworkspaceMATLAB-apiplotlyplotly_auxm2json.m

syntax error

    disp [val ' iselse'];
             ^

Welcome to Plotly! If you are new to Plotly please enter: >> plotlyhelp to get started!

quiver3() reshape error

quiver3() always seems to get this error for me:

>> fig2plotly()
To RESHAPE the number of elements must not change.
We had trouble parsing the quiver object.
This trace might not render properly.

% Create a grid of x,y, and z values
[x, y, z] = meshgrid(-0.8:0.2:0.8, -0.8:0.2:0.8, -0.8:0.8:0.8);

% Calculate homogenous turbulence values at each (x,y,z)
u = sin(pi*x).*cos(pi*y).*cos(pi*z);
v = -cos(pi*x).*sin(pi*y).*cos(pi*z);
w = sqrt(2/3)*cos(pi*x).*cos(pi*y).*sin(pi*z);

% Draw a 3 dimensional quiver plot using the quiver3 function
figure
quiver3(x, y, z, u, v, z)

% Set the axis limits
axis([-1 1 -1 1 -1 1])

% Add title and axis labels
title('Turbulence Values')
xlabel('x')
ylabel('x')
zlabel('z')

describe and visualize getplotlyfig

getplotlyfig is really awesome.

It'd be pretty slick to illustrate both in the getplotlyfig page in the docs and perhaps in the sweet user guide you've made what it does when you run it. Maybe just a screenshot and couple sentence description about what we return when you call the figure and how you could use it might be cool?

Save Figures Using the Offline Package

Can one export a figure to PNG using the Offline API?
Can you show an example?

Thank You.

title not parsed correctly

Use a title String as follows: {'a','b'} wont work...
Get this message:
Sorry - we could not successfully parse the TeX/LaTeX within your MATLAB string.

Save image in offline mode without sending to Plotly server

Currently saveplotlyfig() sends the plot to Plot.ly servers to render which is not ideal for offline mode (eg people want their charts private). Would it be possible to make the rendering on the client side (eg like the PNG snapshot JS feature)? This may not be possible for pdf, but at least png could be supported (may need the browser to appear).

In the meantime, I think a documentation update that explains that offline mode is not supported for saveplotlyfig would be useful.

Thanks. (Particularly - thanks for making Plotly.js open source!)

(some?) empty objects in fig2plotly are JSON-ified as [] instead of {}

In this example, marker is JSON-ified as [] instead of {}:

% some random points
data1 = normrnd(5,1,100,1);
data2 = normrnd(6,1,100,1);

% a simple box plot with two boxes
figure;
boxplot([data1,data2])

response = fig2plotly();

In this example, colorbar is JSON-ified as [] instead of {}

[X,Y,Z] = peaks;
contour(X,Y,Z,20)

response = fig2plotly();

same thing with this example:

x = linspace(-2*pi,2*pi);
y = linspace(0,4*pi);
[X,Y] = meshgrid(x,y);
Z = sin(X)+cos(Y);

figure
contour(X,Y,Z)

the unfortunate impact of this is that our python validation of these objects fails, which is something that we're using for our automatic doc generation right now!

Realtime stream does not work with timeseries

I am trying to stream data as a function of time with Matlab. I am fairly sure that the following example should work (at least it does when the x point is replaced with a number instead of a date string):

TOKEN = 'token';

MAXPOINTS = 300;
UPDATEPERIOD = 1; %sec

%----SETUP-----%
data{1}.x = [];
data{1}.y = [];
data{1}.type = 'scatter';
data{1}.stream.token = TOKEN;
data{1}.stream.maxpoints = MAXPOINTS;
args.filename = 'Streaming Test';
args.fileopt = 'overwrite';

%----PLOTLY-----%
resp = plotly(data,args);
URL_OF_PLOT = resp.url

ps = plotlystream(TOKEN);
ps.open();

for n = 1:30
    m.x = cellstr(datetime('now'),'yyyy-MM-dd HH:mm:ss'); % Work when replaced with "n" only
    m.y = n/2;
    ps.write(m);
    pause(UPDATEPERIOD);
end

ps.close();

To clarify the problem, when the example is run, only one point appears at a time and the y value never changes (it is stuck on the first one which in the example is 0.5).

MATLAB > 2014b histogram function support

Currently only parsing of the MATLAB < 2014b hist function is supported.