1.0

[chriddyp]

#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 chris@plot.ly 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));

[okomarov]

I have two comments at the moment:

• I do recommend to promote the plot(p, ...) syntax over the p.plot(...) simply because in the former case the Matlab help tooltips will contain all suggestions (which often saves you time), while in the latter case you will get only plot(plotlyfig obj...).
• It's a Matlab convention to name properties with first Uppercase and method all lowercase.

[chriddyp]

@okomarov thanks! Just updated the original comment with:

• capitalized properties (e.g. p.data -> p.Data, p.plot_options -> p.PlotOptions with the exception of the plotlyfig.Data and plotlyfig.Layout properties like plotlyfig.Layout.title which need to directly match Plotly's JSON format
• plotly(p, ...)

[BRONSOLO]

Hey @okomarov! The new class approach to the Plotly wrapper (with slight modifications + additions to the description above) has been merged to master - you should take it for a spin! and let us know what you think. Run plotlyupdate.m if your plotly_version > 1.3.12 otherwise you have to grab the .zip directly! Feel free to contact me directly: chuck@plot.ly.