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)[source]

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

Parameters:: name – str, optional 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, dt=False, units=False, data_quant_in=None)[source]

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

Parameters:

name – str Name of the tplot variable
xarray – bool, optional Keep the variable as an xarray object
metadata – bool, optional Return the metadata of the object (the attr dictionary) instead of the actual data
dt – bool, optional Return the times as np.datetime64[ns] objects instead of unix times (significantly faster)
units – bool, optional Attach the astropy units to the data and dependencioes prior to returning

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")
>>> metadata = pytplot.get_data("Variable1", metadata=True)

pytplot.tplot_copy(old_name, new_name)[source]

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)[source]

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

Parameters:

tplot_name (str) – The name of the tplot variable.
new_data (array_like) – The new data to replace the existing data. This can be any object that can be converted into an np.array.

Return type:

None

Examples

>>> # Replace data into an existing variable
>>> import pytplot
>>> pytplot.store_data("v1", data={'x':[1,2,3,4],'y':[1,2,3,4]})
>>> print(pytplot.get_data('v1'))
>>> pytplot.replace_data("v1",[5,6,7,8])
>>> print(pytplot.get_data('v1'))

pytplot.get_timespan(name)[source]

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_endfloat: 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)[source]

Extracts the y-limits from the Tplot Variables stored in memory.

Parameters:

name (str) – Name of the tplot variable.
trg (list, optional) – The time range to look in.

Returns:

ymin (int, float, numeric type of pytplot data) – The minimum value of y.
ymax (int, float, numeric type of pytplot data) – The maximum value of y.

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})
>>> y1, y2 = pytplot.get_ylimits("Variable1")

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

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 – float/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')[source]

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 (float or 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 (float) – The time duration of the plots. Default is number of days.
keyword (str, optional) – Sets the units of the “dt” variable. Days, hours, minutes, and seconds are all accepted. Default is ‘days’.

Return type:

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)