Helper Functions

These are functions that help get or set attributes of the data. All of these were basically mapped one-to-one from IDL routines.

pytplot.del_data(name=None)

This function will delete tplot variables that are already stored in memory.

Parameters:name – str Name of the tplot variable to be deleted. If no name is provided, then all tplot variables will be deleted. Returns:None

Examples

>>> # Delete Variable 1
>>> import pytplot
>>> pytplot.del_data("Variable1")

pytplot.get_data(name, xarray=False, metadata=False)

This function extracts the data from the tplot Variables stored in memory.

Parameters:

• name – str Name of the tplot variable
• xarray – bool Keep the variable as an xarray object
• metadata – bool Return the metadata of the object (the attr dictionary) instead of the actual data

Returns: tuple of data/dimensions/metadata stored in pytplot

time_val : numpy array of seconds since 1970 data_val : n-dimensional array of data spec_bins_val (if exists) : spectral bins if the plot is a spectrogram v1_val (if exists) : numpy array of v1 dimension coordinates v2_val {if exists} : numpy array of v2 dimension coordinates v3_val (if exists) : numpy array of v3 dimension coordinates

Examples

>>> # Retrieve the data from Variable 1
>>> import pytplot
>>> x_data = [1,2,3,4,5]
>>> y_data = [1,2,3,4,5]
>>> pytplot.store_data("Variable1", data={'x':x_data, 'y':y_data})
>>> time, data = pytplot.get_data("Variable1")

pytplot.tplot_copy(old_name, new_name)

This function will copy a tplot variables that is already stored in memory.

Parameters:

• name – str Old name of the Tplot Variable
• new_name – str Name of the copied Tplot Variable

Returns:

None

Examples

>>> # Copy Variable 1 into a new Variable 2
>>> import pytplot
>>> pytplot.tplot_copy("Variable1", "Variable2")

pytplot.replace_data(tplot_name, new_data)

This function will replace all of the data in a tplot variable

Parameters:

• tplot_name – str The name of the tplot variable
• new_data – np array (or something that can be converted to a np.array) The data to replace the

Returns:

None

Examples

>>> # Copy Variable 1 into a new Variable 2
>>> import pytplot
>>> pytplot.replace_data("Variable1", [[1,2,3,4],[5,6,7,8]])

pytplot.get_timespan(name)

This function extracts the time span from the Tplot Variables stored in memory.

Parameters:name – str Name of the tplot variable Returns:

float

The beginning of the time series

time_end : float

The end of the time series

Return type:time_begin

Examples

>>> # Retrieve the time span from Variable 1
>>> import pytplot
>>> x_data = [1,2,3,4,5]
>>> y_data = [1,2,3,4,5]
>>> pytplot.store_data("Variable1", data={'x':x_data, 'y':y_data})
>>> time1, time2 = pytplot.get_timespan("Variable1")

pytplot.get_ylimits(name, trg=None)

This function will get extract the y-limits from the Tplot Variables stored in memory.

Parameters:

• name – str Name of the tplot variable
• trg – list, optional The time range that you would like to look in

Returns:

float

The minimum value of y

ymax : float

The maximum value of y

Return type:

ymin

Examples

>>> # Retrieve the y-limits from Variable 1
>>> import pytplot
>>> x_data = [1,2,3,4,5]
>>> y_data = [1,2,3,4,5]
>>> pytplot.store_data("Variable1", data={'x':x_data, 'y':y_data})
>>> y1, y2 = pytplot.get_ylimits("Variable1")

pytplot.timebar(t, varname=None, databar=False, delete=False, color='black', thick=1, dash=False)

This function will add a vertical bar to all time series plots. This is useful if you want to bring attention to a specific time.

Parameters:

• t – flt/list The time in seconds since Jan 01 1970 to place the vertical bar. If a list of numbers are supplied, multiple bars will be created. If “databar” is set, then “t” becomes the point on the y axis to place a horizontal bar.
• varname – str/list, optional The variable(s) to add the vertical bar to. If not set, the default is to add it to all current plots.
• databar – bool, optional This will turn the timebar into a horizontal data bar. If this is set True, then variable “t” becomes the point on the y axis to place a horizontal bar.
• delete – bool, optional If set to True, at lease one varname must be supplied. The timebar at point “t” for variable “varname” will be removed.
• color – str The color of the bar
• thick – int The thickness of the bar
• dash – bool If set to True, the bar is dashed rather than solid

Returns:

None

Examples

>>> # Place a green time bar at 2017-07-17 00:00:00
>>> import pytplot
>>> pytplot.timebar(1500249600, color='green')

>>> # Place a dashed data bar at 5500 on the y axis
>>> pytplot.timebar(5500, dashed=True, databar=True)

>>> Place 3 magenta time bars of thickness 5
    at [2015-12-26 05:20:01, 2015-12-26 08:06:40, 2015-12-26 08:53:19]
    for variable 'sgx' plot
>>> pytplot.timebar([1451107201,1451117200,1451119999],'sgx',color='m',thick=5)

pytplot.timespan(t1, dt, keyword='days')

This function will set the time range for all time series plots. This is a wrapper for the function “xlim” to better handle time axes.

Parameters:

• t1 – flt/str The time to start all time series plots. Can be given in seconds since epoch, or as a string in the format “YYYY-MM-DD HH:MM:SS”
• dt – flt The time duration of the plots. Default is number of days.
• keyword – str Sets the units of the “dt” variable. Days, hours, minutes, and seconds are all accepted.

Returns:

None

Examples

>>> # Set the timespan to be 2017-07-17 00:00:00 plus 1 day
>>> import pytplot
>>> pytplot.timespan(1500249600, 1)

>>> # The same as above, but using different inputs
>>> pytplot.timespan("2017-07-17 00:00:00", 24, keyword='hours')

pytplot.timestamp(val)

This function will turn on a time stamp that shows up at the bottom of every generated plot.

Parameters

val str

A string that can either be ‘on’ or ‘off’.

Returns

None

Examples

# Turn on the timestamp import pytplot pytplot.timestamp(‘on’)

pytplot.tplot_names(quiet=False)

This function will print out and return a list of all current Tplot Variables stored in the memory.

Parameters:quiet – bool If True, does not print out the variables (only returns the list variables) Returns:

list of str

A list of all Tplot Variables stored in the memory

Return type:list

Examples

>>> import pytplot
>>> x_data = [1,2,3,4,5]
>>> y_data = [1,2,3,4,5]
>>> pytplot.store_data("Variable1", data={'x':x_data, 'y':y_data})
>>> tnames = pyplot.tplot_names()
0 : Variable 1

pytplot.tplot_rename(old_name, new_name)

This function will rename tplot variables that are already stored in memory.

Parameters:

• old_name – str Old name of the Tplot Variable
• new_name – str New name of the Tplot Variable

Returns:

None

Examples

>>> # Rename Variable 1 to Variable 2
>>> import pytplot
>>> pytplot.tplot_rename("Variable1", "Variable2")

pytplot.xlim(min, max)

This function will set the x axis range for all time series plots

Parameters:

• min – flt The time to start all time series plots. Can be given in seconds since epoch, or as a string in the format “YYYY-MM-DD HH:MM:SS”
• max – flt The time to end all time series plots. Can be given in seconds since epoch, or as a string in the format “YYYY-MM-DD HH:MM:SS”

Returns:

None

Examples

>>> # Set the timespan to be 2017-07-17 00:00:00 plus 1 day
>>> import pytplot
>>> pytplot.xlim(1500249600, 1500249600 + 86400)

>>> # The same as above, but using different inputs
>>> pytplot.xlim("2017-07-17 00:00:00", "2017-07-18 00:00:00")

pytplot.ylim(name, min, max)

This function will set the y axis range displayed for a specific tplot variable.

Parameters:

• name – str The name of the tplot variable that you wish to set y limits for.
• min – flt The start of the y axis.
• max – flt The end of the y axis.

Returns:

None

Examples

>>> # Change the y range of Variable1
>>> import pytplot
>>> x_data = [1,2,3,4,5]
>>> y_data = [1,2,3,4,5]
>>> pytplot.store_data("Variable1", data={'x':x_data, 'y':y_data})
>>> pytplot.ylim('Variable1', 2, 4)

pytplot.zlim(name, min, max)

This function will set the z axis range displayed for a specific tplot variable. This is only used for spec plots, where the z axis represents the magnitude of the values in each bin.

Parameters:

• name – str The name of the tplot variable that you wish to set z limits for.
• min – flt The start of the z axis.
• max – flt The end of the z axis.

Returns:

None

Examples

>>> # Change the z range of Variable1
>>> import pytplot
>>> x_data = [1,2,3]
>>> y_data = [ [1,2,3] , [4,5,6], [7,8,9] ]
>>> v_data = [1,2,3]
>>> pytplot.store_data("Variable3", data={'x':x_data, 'y':y_data, 'v':v_data})
>>> pytplot.zlim('Variable1', 2, 3)