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 or list[str]) – Names of the tplot variables to be deleted. If no name is provided, then all tplot variables will be deleted. (wildcards accepted)
Return type:: None

Examples

>>> # Delete Variable 1
>>> import pyspedas
>>> pyspedas.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:

times (ndarray[float]) – numpy array of seconds since 1970
y (ndarray) – n-dimensional numpy array of the data values
v (ndarray) – If exists, an array of bin values for 1-D data types
spec_bins (ndarray) – If exists, an array of the spectrogram bins for the bin values
v1 (ndarray) – If exists, numpy array of the v1 dimension coordinates
v2 (ndarray) – If exists, numpy array of the v2 dimension coordinates
v3 (ndarray) – If exists, numpy array of the v3 dimension coordinates

Notes:

If metadata==True, the return value is a dict containing variable attributes and plot options. Otherwise, the return value is a named tuple with the fields described above.

Examples

>>> # Retrieve the data from Variable 1
>>> import pyspedas
>>> x_data = [1,2,3,4,5]
>>> y_data = [1,2,3,4,5]
>>> pyspedas.store_data("Variable1", data={'x':x_data, 'y':y_data})
>>> time, data = pyspedas.get_data("Variable1")
>>> metadata = pyspedas.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:

old_name (str) – Old name of the Tplot Variable
new_name (str) – Name of the copied Tplot Variable

Return type:

None

Examples

>>> # Copy Variable 1 into a new Variable 2
>>> import pyspedas
>>> pyspedas.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 pyspedas
>>> pyspedas.store_data("v1", data={'x':[1,2,3,4],'y':[1,2,3,4]})
>>> print(pyspedas.get_data('v1'))
>>> pyspedas.replace_data("v1",[5,6,7,8])
>>> print(pyspedas.get_data('v1'))

pytplot.get_timespan(name=None)[source]

This function extracts the time span from the Tplot Variables stored in memory. If called with no arguments, return the global timespan set by timespan(), or None if none has been set.

Parameters:

name (str) – Name of the tplot variable

Returns:

time_beginfloat: The beginning of the time series
time_endfloat: The end of the time series

Return type:

list of float

Examples

>>> # Retrieve the time span from Variable 1
>>> import pyspedas
>>> x_data = [1,2,3,4,5]
>>> y_data = [1,2,3,4,5]
>>> pyspedas.store_data("Variable1", data={'x':x_data, 'y':y_data})
>>> time1, time2 = pyspedas.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 pyspedas
>>> x_data = [1, 2, 3, 4, 5]
>>> y_data = [1, 2, 3, 4, 5]
>>> pyspedas.store_data("Variable1", data={'x': x_data, 'y': y_data})
>>> y1, y2 = pyspedas.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 or 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 or list, optional) – The variable(s) to add the vertical bar to. If not set, the default is to add it to all current plots. (wildcards accepted)
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 least 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.

Return type:

None

Examples

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

>>> # Place a dashed data bar at 5500 on the y axis
>>> pyspedas.timebar(5500, dash=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
>>> pyspedas.timebar([1451107201,1451117200,1451119999],'sgx',color='m',thick=5)

pytplot.timespan(t1=None, dt=None, units='days', keyword=None, reset=False)[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.
units (str, optional) – Sets the units of the “dt” variable. Days, hours, minutes, and seconds and reasonable abbreviations are all accepted. Default is ‘days’.
keyword (str, optional) – Synonym for units keyword
reset (bool, optional) – If True, clears all previously set time ranges.

Return type:

None

Examples

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

>>> # The same as above, but using different inputs
>>> pyspedas.timespan("2017-07-17 00:00:00", 24, units='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’.
Return type:: None

Examples

>>> # Turn on the timestamp
>>> import pyspedas
>>> pyspedas.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:: A list of all Tplot Variables stored in the memory
Return type:: list of str

Examples

>>> import pyspedas
>>> x_data = [1,2,3,4,5]
>>> y_data = [1,2,3,4,5]
>>> pyspedas.store_data("Variable1", data={'x':x_data, 'y':y_data})
>>> tnames = pyspedas.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

Return type:

None

Examples

>>> # Rename Variable 1 to Variable 2
>>> import pyspedas
>>> pyspedas.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”

Return type:

None

Examples:

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

>>> # The same as above, but using different inputs
>>> pyspedas.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, int, list of str, list of int) – The names, indices, or wildcard patterns 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.

Return type:

None

Examples

>>> # Change the y range of Variable1
>>> import pyspedas
>>> x_data = [1,2,3,4,5]
>>> y_data = [1,2,3,4,5]
>>> pyspedas.store_data("Variable1", data={'x':x_data, 'y':y_data})
>>> pyspedas.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, int, list of str, list of int) – The names, indices, or wildcard patterns 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.

Return type:

None

Examples

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