Last modified: Wed August 10 13:24 2016.

# Directory Listing of Routines

# pytplot

- del_data
  Deletes the data structure associated with the name handle
- get_data
  Retrieves the data and/or limit structure associated with a name handle.
- get_names
  Lists current stored data names that can be plotted with the TPLOT routines.
- get_timespan
- get_ylimits
  Calculates appropriate ylimits for a single "TPLOT" variable or a list of "TPLOT" variables.
- options
  Add (or change) options of individual plots.
- store_data
  Store time series structures in static memory for later retrieval.
- timebar
  Plot vertical (or horizontal) lines on TPLOTs at specified times (or values).
- timespan
  Define a time span for the "tplot" routine.
- timestamp
  Adds current date and time to plot when "tplot" routine is called.
- tlimit
- tplot
  Creates a time series plot of user defined quantities.
- tplot_options
  Sets global options for the "tplot" routine.
- tplot_rename
  Renames a tplot variable without copy.
- tplot_restore
  Restores tplot data, limits, and name handles. (working on options and settings)
- tplot_save
  Store tplot data in a file.
- xlim
  To set plotting limits for plotting routines.
- ylim
  Sets y-axis limits for plotting routines.
- zlim
  To set plotting limits for plotting routines.

# Routine Descriptions

## del_data

[Next Routine] [List of Routines]

    PROCEDURE: del_data(name)
    PURPOSE:
      Deletes the data structure associated with the name handle.
      This procedure is used by the "TPLOT" routines.
    INPUT:
      name  Scalar string or index of TPLOT variable.

## get_data

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: get_data(name)
    PURPOSE:
      Retrieves the data and/or limit structure associated with a name handles.
      This procedure is used by the "TPLOT" routines.
    INPUT:
      name  Scalar string or index of TPLOT variable.
    OUTPUT:
      time_val  A numpy array of seconds since epoch
      data_val	A numpy array of data values

## get_timespan

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: get_timespan(name)
    PURPOSE:
      To get timespan of tplot data.
    INPUT:
      name  Scalar string or index of TPLOT variable.
    OUTPUT:
      time_array A list of the start and end times in seconds since epoch

## get_ylimits

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: get_ylimits(name, trg = None)
    PURPOSE:
      Calculates appropriate ylimits for either one "TPLOT" variable or a list of "TPLOT" variables to be plotted in the same panel.
    INPUT:
      name  TPLOT variable string or number or a list of TPLOT variable strings or numbers.
      trg   (Optional) Time range over which to calculate the limits; Double[2].
    OUTPUT:
      ymin	The minimum y value
      ymax	The maximum y value

## options

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: options(name, option, value)
    PURPOSE:
      Add (or change) options for individual plots.
    INPUT:
      name    Scalar string or index of TPLOT variable.
      option  String with name of plot option to be changed.
      value   Value to be put into the option being changed.
    OPTIONS:
      color         Color of plot lines to same value color.
                    value: String of color value.
                    default: Black
      colormap      Color mapping for spectrograms.  Recommend 'magma', 'viridis', 'plasma', or 'inferno'.
                    value: String of color value.  Accepts all names listed here
                    default: 'inferno'
      legend_names  Creates a legend for multi-line plots
                    value: List of strings (ex- ['MSO_X', 'MSO_Y', 'MSO_Z'])
                    default: None
      line_style    Changes pattern of plot lines.
                    value: Enum('solid_line', 'dot', 'dash', 'dash_dot', dash_dot_dot_dot', 'long_dash').
                    default: 'solid_line'
      name          Name of plot.
                    value: String.
                    default: None
      nodata        Does not show the data plotted.
                    value: True or False.
                    default: False
      panel_size    Size of panel compared to others.
                    value: Float (fraction of size of other panes).
                    default: 1
      spec          Toggles spectrograms versus multi-line plots
                    value: 0 or 1, 0: multi-line, 1: spectrogram.
                    default: 1 if 'v' was supplied in store_data, 0 otherwise
      thick         Thickness of plot lines.
                    value: Integer.
                    default: 1
      transparency  Transparency of plot lines.
                    value: Integer in range (0, 100).
                    default: 100
      ylog          Y-axis presented as linear or log.
                    value: 0 or 1, 0: linear, 1: log.
                    default: 0
      yrange        Range of y-axis.
                    value: two element list [min, max].
                    default: None (calculated at time of plotting)
      ytitle        Title displayed on y-axis.
                    value: String.
                    default: None
      zlog          Z-axis presented as linear or log.
                    value: 0 or 1, 0: linear, 1: log.
                    default: 0
      ztitle        Title displayed on z-axis.
                    value: String.
                    default: 0

## store_data

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: store_data(name, data=None, delete=False)
    PURPOSE:
      Store time series structures in static memory for later retrieval by the tplot routine.
    INPUT:
      name    String name to be associated with the data structure passed in.
      data    A data structure that contains the x and y data. Tested data types include lists, numpy arrays, and pandas dataframes.  (Optional) Include 'v' data in order for a spectrogram to be plotted.
      delete  (Optional) True: deletes tplot variable(s) of name, no data required. In this case, name can be a single variable, or a list of variables. False: store_data creates tplot variable
    EXAMPLE:
      store_data('one_line', data={'x':[1,2,3,4], 'y':[1,2,3,4]})
      store_data('three_lines', data={'x':[1,2,3,4], 'y':[[1,5,9],[2,6,10],[3,7,11],[4,8,12]})
      store_data(['one_line', three_lines'], delete=True)

## timebar

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: timebar(t, varname = None, databar = False, delete = False, color = 'black', thick = 1)
    PURPOSE:
      Plot vertical (or horizontal) lines on TPLOTs at specified times (or values).
    INPUT:
      t        Time or list of times at which to draw vertical lines.
      varname  (Optional) Name of specific plots to apply timebar to, otherwise all plots.
      databar  (Optional) True: horizontal bar, False: vertical bar.
      delete   (Optional) True: deletes all bars matching the t, databar, and varname inputs. False: creates bars as normal.
      color    (Optional) Color of timebar, default black.
      thick    (Optional) Thickness of timebar.

## timespan

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: timespan(t1, dt, keyword = None)
    PURPOSE:
      Define a time span for the "tplot" routine.
    INPUT:
      t1       Starting time (seconds since 1970).
      dt       Duration of time span (Days is default).
      keyword  (Optional) Set dt value to different time quantities.
               'seconds', 'minutes', 'hours', 'days' (default)

## timestamp

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: timestamp(val)
    PURPOSE:
      Include date and time the plot was created on the plot when the "tplot" routine is called.
    INPUT:
      val  'on' or 'off'

## tlimit

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: tlimit(arg)
    PURPOSE:
      Defines time range for "tplot".
    INPUT:
      arg  Two element list of minimum and maximum time of time range (seconds since 1970).
           'full'  Use plot's original (full) limits.
           'last'  Use plot's previous limits.

## tplot_names

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: tplot_names()
    PURPOSE:
      Lists current stored data names that can be plotted with the TPLOT routines.
    INPUT: None
    OUTPUT:
      prints the names currently in memory

## tplot_options

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: tplot_options(option, value)
    PURPOSE:
      Sets global options for the "tplot" routine.
    INPUT:
      option  Name of option to be set (string).
      value   Value to be given to the option.
    OPTIONS:
      title       Title of entire plot.
                  value: String
      title_size  Size of title font.
                  value: Integer
      wsize       Size of plot window.
                  value: Two-element list of number of pixels for width and height of window (Integers). [width, height]

## tplot_rename

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: tplot_rename(old_name, new_name)
    PURPOSE:
      Renames a tplot variable without copy. Tplot number stays the same.
    INPUT:
      old_name  Current name or index of the variable to be changed(string or integer).
      new_name  Name the variable will have after the procedure call(string).

## tplot_restore

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: tplot_restore(file_name)
    PURPOSE:
      Restores tplot data, limits, and name handles from '.pytplot' files. Restores tplot data from '.tplot' files.
    INPUT:
      file_name  File name to restore.

## tplot_save

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: tplot_save(name, filename=None)
    PURPOSE:
      Store tplot data, options and limits into a .pytplot file.  This data can be restored with tplot_restore.
    INPUT:
      name      Tplot handle to save.
      filename  (Optional) File name in which to save data. If none is provided, a filename will be constructed using the tplot handle.

## tplot

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: tplot(name, var_label = None, interactive=False, nb=False)
    PURPOSE:
      Creates a time series plot of user defined quantities.
    INPUT:
      name         A single string or list of strings associated with TPLOT variables previously stored with the "store_data" routine.
                   Can alternatively be an integer or list of integers associated with a TPLOT variable.
      var_label    (Optional)String of TPLOT variable to include as label along the bottom.
      interactive  (Optional)If interactive is True, a spectrogram plot will also display an addition plot that shows slices of the data when the
      			   mouse hovers over the spectrogram
      nb		   (Optional)If nb is set to True, then the plots will display inside the jupyter notebook
    OUTPUT:
      An HTML file is generated in the current directory.  This file is opened automatically after it is created.

## xlim

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: xlim(min, max)
    PURPOSE:
      Sets x-axis limits for plotting routines.
    INPUT:
      min  Minimum value of range.
      max  Maximum value of range.

## ylim

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: ylim(name, min, max)
    PURPOSE:
      Sets y-axis limits for plotting routines.
    INPUT:
      name     Name or tplot number of TPLOT variable to be changed.
      min      Minimum value of yrange.
      max      Maximum value of yrange.

## zlim

[Previous Routine] [List of Routines]

    PROCEDURE: zlim(name, min, max)
    PURPOSE:
      Sets z-axis limits for plotting routines.
    INPUT:
      name     Name or tplot number of TPLOT variable to be changed.
      min      Minimum value of zrange.
      max      Maximum value of zrange.