Utilities

Time Conversions

Most routines in PySPEDAS will accept or produce times in one of two representations: either as floating-point values interpreted as a count of seconds since the Unix epoch 1970-01-01/00:00 (often called “Unix time”), or as strings, for example ‘2018-04-01/12:00:00.001’.

The PySPEDAS time_string(), time_float(), and time_double() can be used to convert single timestamps, or lists or arrays of timestamps, between these representations.

The format of PySPEDAS timestamps is somewhat flexible…basically enything that can be handled via the dateutil.parser parse() or isoparse() utilities.

Internally, PySPEDAS currently uses Numpy datetime64() objects with nanosecond precision as the time representation of tplot variables and Matplotlib plots. This is an implementation detail that should not be relied on in user code! The PySPEDAS get_data and store_data() routines (described below) for using and creating tplot variables do the appropriate conversions between the internal time representation and the Unix times or string timestamps used elsewhere in PySPEDAS.

The use of Unix times in much of PySPEDAS (and indeed, Python in general) leads to potential pitfalls when dealing with leap seconds, which are by definition ignored when converting between Unix times and string timestamps. This is a bit of a sore point in the scientific Python community. The Astropy package has one of the few fully leap-second-aware time representations, but the lack of support for it in commonly used scientific Python packages (e.g. Numpy, Pandas, xarray) are a hindrance to adopting it as a common time representation in PySPEDAS and elsewhere in the PyHC ecosystem.

pyspedas.time_string(float_time=None, fmt=None)[source]

Transforms a list of float daytime values into a list of string representations.

Parameters:

  • float_time (floats, or list of floats, optional) – The input time(s) as float(s). If not provided, the current time is used. Any string inputs are returned as-is.

  • fmt (str, optional) – The format string for time conversion. The default format is ‘%Y-%m-%d %H:%M:%S.%f’.

Returns:

The datetimes as strings formatted according to fmt. If float_time is not provided, returns the current datetime formatted as specified. If float_time is a single float, returns a single datetime string.

Return type:

str or list of str

Examples

>>> time_string(1679745600.0)
'2023-03-25 12:00:00.000000'

>>> time_string([1679745600.0, 1679832000.0], "%Y-%m-%d %H:%M:%S")
['2023-03-25 12:00:00', '2023-03-26 12:00:00']

>>> time_string()
#'Returns the current datetime in the default format'

Notes

Compare to https://www.epochconverter.com/

Example

from pyspedas import time_string
time_string(1444953600.0)

'2015-10-16 00:00:00.000000'
pyspedas.time_double(str_time=None)[source]

Transform a list of datetimes from string to decimal.

Parameters:

str_time (str or list of str, optional) – The input datetime(s) as a string or a list of strings. If not provided the current time is used.

Returns:

time_list – The decimal representation of the input datetime(s) as a list of floats. If the input is a single datetime string, the list will contain only one element. The current local datetime is used if no input is provided.

Return type:

list of float or float

Examples

>>> from pyspedas import time_double
>>> time_double(['2023-03-25 12:00:00', '2023-03-26 12:00:00'])
[1679745600.0, 1679832000.0]

>>> time_double('2023-03-25 12:00:00')
1679745600.0

>>> time_double()
# Returns the current timestamp as a list containing one float.

Note

This function is an alilas of time_float. This function is to time_double.pro in IDL SPEDAS.

Example

from pyspedas import time_double
time_double('2015-10-16/14:00')

1445004000.0

There may be occasions (for example, when passing times to routines in other packages) when it might be useful to convert to/from Python datetime objects. time_datetime() accepts either Unix times or strings, and returns Python datetime objects.

pyspedas.time_datetime(time=None, tz=None)[source]

Transforms a list of float daytime values or strings to a list of pythonic datetime.datetime objects.

Parameters:

  • time (float, list of floats, str, or list of strs, optional) – The input time(s) as float(s) representing UNIX timestamps or strings. If not provided, the current time is used.

  • tz (datetime.timezone, optional) – The timezone for the datetime object(s). If not provided, UTC is used.

Returns:

The datetimes as datetime.datetime objects. If time is a single value, returns a single datetime.datetime object; if time is a list, returns a list of datetime.datetime objects. If time is None, returns the current datetime in UTC.

Return type:

datetime.datetime or list of datetime.datetime

Examples

>>> from pyspedas import time_datetime
>>> from datetime import timezone, timedelta
>>> time_datetime(1679745600.0)
# or
>>> time_datetime('2023-03-25 12:00:00')
# Returns a datetime object for 2023-03-25 12:00:00 UTC
datetime.datetime(2023, 3, 25, 12, 0, tzinfo=datetime.timezone.utc)

>>> time_datetime([1679745600.0, 1679832000.0])
# or
>>> time_datetime(['2023-03-25 12:00:00', '2023-03-26 12:00:00'])
# Returns a list of datetime objects for 2023-03-25 12:00:00 UTC and 2023-03-26 12:00:00 UTC
[datetime.datetime(2023, 3, 25, 12, 0, tzinfo=datetime.timezone.utc), datetime.datetime(2023, 3, 26, 12, 0, tzinfo=datetime.timezone.utc)]

>>> time_datetime()
# Returns the current datetime object in UTC

>>> time_datetime(1679745600.0, tz=timezone(timedelta(hours=-6)))
# Returns a datetime object for 2023-03-25 06:00:00 in a timezone that is -6 hour from UTC
datetime.datetime(2023, 3, 25, 6, 0, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=64800)))

Example

from pyspedas import time_datetime
time_datetime('2015-10-16/14:00')

datetime.datetime(2015, 10, 16, 14, 0, tzinfo=datetime.timezone.utc)
pyspedas.time_ephemeris(t, et2ut=False)[source]

Convert between unix time and ephemeris time, based on the IDL routine by Davin Larson

Parameters:

  • t (float) – Input time to convert, by default unix time (seconds since 1970-01-01)

  • et2ut (bool) – If True, convert ephemeris time (seconds since 2000-01-01/11:58:55 UTC) to unix time (Default: False)

Examples

>>> strdate='2025-01-01/00:00:00'
>>> ut = pyspedas.time_double(strdate)
>>> et = pyspedas.time_ephemeris(ut)
>>> print(et)
788961669.184

Creating and Managing Tplot Variables

pyspedas.get_data(name, xarray=False, metadata=False, dt=False, units=False, data_quant_in=None, ensure_writeable=False)[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 dependencies prior to returning

  • ensure_writeable (bool, optional) – Ensure that returned arrays are writeable, rather than (for example) read-only views of pandas data frame indices. Specify ‘True’ if you need to modify the returned arrays. Defaults to ‘False’ for efficiency.

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)

A few notes about get_data:

The type of the return value will differ depending on what is being requested. If metadata=True is passed, the return value will be a dictionary containing the various metadata attributes, CDF metadata, plot options, and so forth. Otherwise, the returned value will be a Python tuple, with a number of named fields. The first two fields returned will always be ‘times’ (the timestamps or X values), and ‘y’ (the data values). There may be additional fields, depending on whether v, v1, v2 (etc) attributes are defined for higher dimensional data types. So be cautious about constructs like this:

mytimes, myvals = get_data('some_tplot_variable')

If ‘some_tplot_variable’ contains ‘v’, ‘v1’. ‘v2’, or other DEPEND_N attributes, this will cause errors or warnings like ‘too many values to unpack’. Unless you already know how much metadata to expect, it’s safer to do this:

mydata = get_data('some_tplot_variable')

then reference mydata.times, mydata.y, mydata.v, etc.

In some cases, due to the internal represenation of tplot variables as xarray and pandas objects, the arrays returned by get_data may be read-only views of pandas indexes or other parts of the data structure. At this writing (January 2026), if pandas-3.0.0 or above is installed in the PySPEDAS environment, the time and data arrays returned by get_data should always be writeable, but the v, v1`, v2 (etc) elements might be read-only. In the (somewhat rare) case where you need to modify the returned arrays, you can specify ensure_writeable=True in the get_data call. In this case, get_data will return read-write copies of the arrays, rather than read-only views. The default setting is ensure_writeable=False, to avoid unnecessary copies and save memory.

pyspedas.store_data(name, data=None, delete=False, newname=None, attr_dict={})[source]

Create a “Tplot Variable” (similar to the IDL SPEDAS concept) based on the inputs, and stores this data in memory. Tplot Variables store all of the information needed to generate a plot.

Parameters:

  • name (str) – Name of the tplot variable that will be created

  • data (dict or list[str]) – A python dictionary object for creating a single variable, or a list of base variables to combine them into a ‘pseudovariable’

    ‘x’ should be a 1-dimensional array that represents the data’s x axis. If x is a numeric type, it is interpreted as seconds since the Unix epoch. x can also be passed as Pandas Series object, datetime.datetime, numpy.datetime64, or strings. represented in seconds since epoch (January 1st 1970)

    ‘y’ should be the data values. This can be 2 dimensions if multiple lines or a spectrogram are desired.

    ‘v’ is optional, and is only used for spectrogram plots. This will be a list of bins to be used. If this is provided, then ‘y’ should have dimensions of x by z.

    ‘v1/v2/v3/etc’ are also optional, and are only used for to spectrogram plots. These will act as the coordinates for ‘y’ if ‘y’ has numerous dimensions. By default, ‘v2’ is plotted in spectrogram plots.

  • delete (bool, optional) – If True, deletes the tplot variable matching the “name” parameter Default: False

  • newname (str) – If set, renames TVar to new name Default: False

  • attr_dict (dict) – A dictionary object of attributes (these do not affect routines in pyspedas, this is merely to keep metadata alongside the file) Default: {} (empty dictionary)

Note

If you want to combine multiple tplot variables into one, simply supply the list of tplot variables to the “data” parameter. This will cause the data to overlay when plotted.

Returns:

True if successful, False otherwise

Return type:

bool

Examples

>>> # Store a single line
>>> 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})

>>> # Store two lines
>>> x_data = [1,2,3,4,5]
>>> y_data = [[1,5],[2,4],[3,3],[4,2],[5,1]]
>>> pyspedas.store_data("Variable2", data={'x':x_data, 'y':y_data})

>>> # Store a spectrogram
>>> 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})

>>> # Combine two different line plots
>>> pyspedas.store_data("Variable1and2", data=['Variable1', 'Variable2'])

>>> #Rename TVar
>>> pyspedas.store_data('a', data={'x':[0,4,8,12,16], 'y':[1,2,3,4,5]})
>>> pyspedas.store_data('a',newname='f')
pyspedas.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
pyspedas.tnames(pattern=None, regex=None)[source]

Find tplot names matching a wildcard pattern.

Parameters:

  • pattern (str or list of str, optional) – Pattern(s) to search for. It can be a string or a list of strings (multiple patterns). Each pattern can contain wildcards such as * and ?, using unix-style matching. The default is None

  • regex (str, optional) – Regular expression pattern to search for. If regex is provided, the pattern argument is ignored. The default is None. If both pattern and regex are None, all tplot names are returned.

Returns:

name_list – List of tplot variables.

Return type:

list of str

Examples

>>> import pyspedas
>>> import pyspedas
>>> from pyspedas.projects.themis import fgm
>>> fgm(trange=['2007-03-23','2007-03-24'], probe='a')
>>> pyspedas.tnames('tha_fgs*')
>>> pyspedas.tnames('th?_fgs_gsm')
pyspedas.join_vec(tvars, newname=None, merge=False)[source]

Joins 1D tplot variables into one tplot variable.

Note

This analysis routine assumes the data is no more than 2 dimensions. If there are more, they may become flattened!

Parameters:

  • tvars (list of str) – Name of tplot variables to join together.

  • newname (str, optional) – The name of the new tplot variable. If not specified (the default), a name will be assigned.

  • merge (bool, optional) – Whether or not to merge the created variable into an older variable. Default is False.

Return type:

None

Examples

>>> import pyspedas
>>> import numpy as np
>>> pyspedas.store_data('d', data={'x':[2,5,8,11,14,17,21], 'y':[[1,1,50],[2,2,3],[100,4,47],[4,90,5],[5,5,99],[6,6,25],[7,7,-5]]})
>>> pyspedas.store_data('e', data={'x':[2,5,8,11,14,17,21], 'y':[[np.nan,1,1],[np.nan,2,3],[4,np.nan,47],[4,np.nan,5],[5,5,99],[6,6,25],[7,np.nan,-5]]})
>>> pyspedas.store_data('g', data={'x':[0,4,8,12,16,19,21], 'y':[[8,1,1],[100,2,3],[4,2,47],[4,39,5],[5,5,99],[6,6,25],[7,-2,-5]]})
>>> pyspedas.join_vec(['d','e','g'],newname='deg')
pyspedas.split_vec(tvar, polar=False, newname=None, new_name=None, columns='all', suffix=None)[source]

Splits up 2D data into many 1D tplot variables. Takes a stored tplot vector like Vp and stores tplot variables Vp_x, Vp_y, Vp_z

Parameters:

  • tvar (str) – Name of tplot variable to split up

  • polar (bool, optional) – If True, the input data is in polar coordinates. Suffix will be set to [‘_mag’, ‘_th’, ‘_phi’]. Default: False

  • new_name (int/list, optional (Deprecated)) – The names of the new tplot variables. This must be the same length as the number of variables created.

  • newname (int/list, optional) – The names of the new tplot variables. This must be the same length as the number of variables created. Default: None

  • columns (list of ints, optional) – The specific column numbers to grab from the data. Default: ‘all’ (splits all columns)

  • suffix (str) – Suffix str to be added to end of tplot variable name Default: None

Returns:

List of variables created

Return type:

list[str]

Examples

>>> pyspedas.store_data('b', data={'x':[2,5,8,11,14,17,20], 'y':[[1,1,1,1,1,1],[2,2,5,4,1,1],[100,100,3,50,1,1],[4,4,8,58,1,1],[5,5,9,21,1,1],[6,6,2,2,1,1],[7,7,1,6,1,1]]})
>>> pyspedas.split_vec('b')
pyspedas.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")
pyspedas.data_exists(tvar)[source]

Checks if a tplot variable exists

Parameters:

tvar (str) – Name of tplot variable to check

Returns:

Retrun True if tplot variable exists.

Return type:

bool

Example

>>> import pyspedas
>>> pyspedas.store_data('a', data={'x': range(10), 'y': range(10)})
>>> pyspedas.data_exists('a')
pyspedas.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")
pyspedas.tres(tplot_var)[source]

Returns the time resolution of a tplot variable, defined as the median value of the differences between time values from the data points, e.g., median(d.x[1:*]-d.x). Can be used for multiple variables.

Parameters:

- tplot_var (int or str or list) (A tplot variable name or number, or a list of such names.)

Returns:

- delta_t (float or list) – does not exist, or does not return a median, then the result is -1. If multiple tplot variables are provided, returns a list of median values.

Return type:

The time resolution, a median value. If the data variable

Examples

>>> import pyspedas
>>> import pyspedas
>>> import pyspedas
>>> fgm_vars = pyspedas.projects.themis.fgm(probe='d', trange=['2013-11-5', '2013-11-6'])
>>> dt = pyspedas.tres('thd_fgs_gse')
>>> dts = pyspedas.tres(fgm_vars)
pyspedas.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 pyspedas data) – The minimum value of y.

  • ymax (int, float, numeric type of pyspedas 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")
pyspedas.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'))
pyspedas.replace_metadata(tplot_name, new_metadata)[source]

This function will replace all the metadata in a tplot variable.

Parameters:

  • tplot_name (str) – The name of the tplot variable.

  • new_metadata (dict) – A dictionary with metadata values. A deep copy will be performed so that no references to new_metadata are retained.

Return type:

None

Examples

>>> # Copy Variable 1 metadata into Variable 2, which must already exist
>>> import pyspedas
>>> meta = pyspedas.get_data('Variable1', metadata=True)
>>> pyspedas.replace_metadata("Variable2", meta)
pyspedas.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")
pyspedas.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")
pyspedas.tplot_wildcard_expand(patterns, case_sensitive=True, quiet=False)[source]

Return tplot variable names matching one or more wildcard patterns

Parameters:

  • patterns (str, int, list(str!int)) – One or more patterns, which may contain wildcard characters, to be matched against the master list Integers are converted to strings using tname_byindex()

  • case_sensitive (bool) – A boolean flag indicating whether case-sensitive matching should be performed. Default: True

  • quiet (bool) – A boolean flag indicating “no match found” log messages should be suppressed. Default: False

Returns:

A list of tplot variable names that match at least one of the input patterns. Duplicate values in the output will be removed.

Return type:

list of str

Tplot Variable Metadata Getters/Setters

Some PySPEDAS routines (for example, coordinate transforms and magnetic field models) need access to certain metadata to operate properly. When loading from external data sources, this is often taken care of automatically, but if your code needs to create its own tplot variables or inspect metadata for input variables, these routines can help.

pyspedas.get_coords(name)[source]

This function returns the coordinate system of a tplot variable

Parameters:

name (str) – name of the tplot variable

Notes

The coordinate system is stored in the variable’s metadata at:

metadata[‘data_att’][‘coord_sys’]

See pyspedas.get_coords() to update the coordinate system

Returns:

  • Coordinate system of the tplot variable

  • or

  • None if the coordinate system isn't set

Examples

>>> import pyspedas
>>> pyspedas.projects.themis.state(trange=['2007-06-23', '2007-06-24'], probe='a')
>>> pyspedas.get_coords('tha_pos')
pyspedas.set_coords(name, coords)[source]

This function sets the coordinate system of a tplot variable, and updates legend names and axis labels if they include the coordinate system.

Parameters:

  • name (str or list[str]) – names of tplot variables to update (wildcards accepted)

  • coord (str) – Abbreviated name of the coordinate system (upper case recommended)

Notes

The coordinate system is stored in the variable’s metadata at:

metadata[‘data_att’][‘coord_sys’]

See pyspedas.get_coords() to return the coordinate system

Returns:

bool

Return type:

True/False depending on if the operation was successful

Examples

>>> import pyspedas
>>> pyspedas.projects.themis.state(trange=['2007-06-23', '2007-06-24'], probe='a')
>>> pyspedas.set_coords('tha_pos', 'GEI')
pyspedas.rotmat_set_coords(varname: str, in_coords: str, out_coords: str)[source]

Set input and output coordinates on a rotation matrix

Parameters:

  • varname (str) – Variable name of the rotation matrix

  • in_coords (str) – Input coordinates for the vectors to be rotated

  • out_coords – Output coordinates for the vectors to be rotated

Return type:

None

pyspedas.rotmat_get_coords(varname: str)[source]

Get input and output coordinates on a rotation matrix

Parameters:

varname (str) – Variable name of the rotation matrix

Returns:

  • (str, str)

  • Tuple containing the input and output coordinates (or None if not set)

pyspedas.get_units(name)[source]

This function returns the units of a tplot variable

Parameters:

name (str) – name of the tplot variable

Notes

The units string is stored in the variable’s metadata at:

metadata[‘data_att’][‘units’]

See set_units to update the coordinate system

Returns:

  • Units of the tplot variable

  • or

  • None if the coordinate system isn't set

Examples

>>> import pyspedas
>>> pyspedas.projects.themis.state(trange=['2007-06-23', '2007-06-24'], probe='a')
>>> pyspedas.get_units('tha_pos')
pyspedas.set_units(name, units)[source]

This function sets the units of a tplot variable, and updates legend names and axis labels if they include the units.

Parameters:

  • name (str or list[str]) – names of the tplot variables to update (wildcards accepted)

  • coord (str) – Units

Notes

The units are stored in the variable’s metadata at:

metadata[‘data_att’][‘units’]

See get_units to return the units

Returns:

bool

Return type:

True/False depending on if the operation was successful

Examples

>>> import pyspedas
>>> pyspedas.projects.themis.state(trange=['2007-06-23', '2007-06-24'], probe='a')
>>> pyspedas.set_units('tha_pos', 're')

Arithmetic

pyspedas.add(tvar1, tvar2, newname=None)[source]

Adds two tplot variables together. Will interpolate if the two are not on the same time cadence.

Parameters:

  • tvar1 – str Name of first tplot variable.

  • tvar2 – int/float Name of second tplot variable

  • newname – str Name of new tvar for added data. If not set, then the data in tvar1 is replaced.

Returns:

None

Examples

>>> pyspedas.store_data('a', data={'x':[0,4,8,12,16], 'y':[1,2,3,4,5]})
>>> pyspedas.store_data('c', data={'x':[0,4,8,12,16,19,21], 'y':[1,4,1,7,1,9,1]})
>>> pyspedas.add('a','c',newname='a+c')
>>> pyspedas.get_data('a+c')
pyspedas.subtract(tvar1, tvar2, newname=None)[source]

Subtracts two tplot variables. Will interpolate if the two are not on the same time cadence.

Parameters:

  • tvar1 (str) – Name of first tplot variable.

  • tvar2 (int/float) – Name of second tplot variable

  • newname (str) – Name of new tvar for added data. Default: None. If not set, then the data in tvar1 is replaced.

Return type:

None

Examples

>>> pyspedas.store_data('a', data={'x':[0,4,8,12,16], 'y':[1,2,3,4,5]})
>>> pyspedas.store_data('c', data={'x':[0,4,8,12,16,19,21], 'y':[1,4,1,7,1,9,1]})
>>> pyspedas.subtract('a','c',newname='a-c')
pyspedas.multiply(tvar1, tvar2, newname=None)[source]

Multiplies two tplot variables. Will interpolate if the two are not on the same time cadence.

Parameters:

  • tvar1 (str) – Name of first tplot variable.

  • tvar2 (int/float) – Name of second tplot variable.

  • newname (str) – Name of new tplot variable. If not set, then the data in tvar1 is replaced.

Return type:

None

Examples

>>> x1 = [0, 4, 8, 12, 16]
>>> x2 = [0, 4, 8, 12, 16, 19, 21]
>>> time1 = [pyspedas.time_float("2020-01-01") + i for i in x1]
>>> time2 = [pyspedas.time_float("2020-01-01") + i for i in x2]
>>> pyspedas.store_data("a", data={"x": time1, "y": [1, 2, 3, 4, 5]})
>>> pyspedas.store_data("c", data={"x": time2, "y": [1, 4, 1, 7, 1, 9, 1]})
>>> n = pyspedas.multiply("a", "c", newname="a_x_c")
>>> print('new tplot variable:', n)
>>> ac = pyspedas.get_data(n)
>>> print(ac)
pyspedas.divide(tvar1, tvar2, newname=None)[source]

Divides two tplot variables. Will interpolate if the two are not on the same time cadence.

Parameters:

  • tvar1 (str) – Name of first tplot variable.

  • tvar2 (int/float) – Name of second tplot variable

  • newname (str) – Name of new tvar for divided data. If not set, then the data in tvar1 is replaced.

Return type:

None

Examples

>>> pyspedas.store_data('a', data={'x':[0,4,8,12,16], 'y':[1,2,3,4,5]})
>>> pyspedas.store_data('c', data={'x':[0,4,8,12,16,19,21], 'y':[1,4,1,7,1,9,1]})
>>> pyspedas.divide('a','c','a_over_c')
pyspedas.add_across(tvar, column_range=None, newname=None)[source]

Adds across columns in the tplot variable

Note

This analysis routine assumes the data is no more than 2 dimensions. If there are more, they may become flattened!

Parameters:

  • tvar (str) – Name of tplot variable.

  • column_range (list of ints) – The columns to add together. For example, if [1,4] is given here, columns 1, 2, 3, and 4 will be added together. If not set, then every column is added.

  • newname (str) – Name of new tvar for averaged data. If not set, then the variable is replaced

Return type:

None

Examples

>>> #Add across every column in the data
>>> pyspedas.store_data('d', data={'x':[2,5,8,11,14,17,21], 'y':[[1,1,50],[2,2,3],[100,4,47],[4,90,5],[5,5,99],[6,6,25],[7,7,-5]]})
>>> pyspedas.add_across('d',newname='d_aa')

>>> #Add across specific columns in the data
>>> pyspedas.store_data('b', data={'x':[2,5,8,11,14,17,20], 'y':[[1,1,1,1,1,1],[2,2,5,4,1,1],[100,100,3,50,1,1],[4,4,8,58,1,1],[5,5,9,21,1,1],[6,6,2,2,1,1],[7,7,1,6,1,1]]})
>>> pyspedas.add_across('b',column_range=[[1,2],[3,4]],newname='b_aap')
pyspedas.avg_data(names, trange=None, res=None, width=None, newname=None, suffix=None, overwrite=False)[source]

Get a new tplot variable with averaged data.

Parameters:

  • names (str/list of str) – List of pytplot names.

  • trange (list of float, optional) – Start time, end time. If empty, the data start and end time will be used.

  • res (float, optional) – Time resolution in seconds for averaging data. It can be less than 1 sec. Default is 60 sec.

  • width (int, optional) – Number of values for the averaging window. If res is set, then width is ignored.

  • newname (str/list of str, optional) – List of new names for tplot variables. If not given, then a suffix is applied.

  • suffix (str, optional) – A suffix to apply. Default is ‘-avg’.

  • overwrite (bool, optional) – Replace the existing tplot name. Default is False.

Returns:

n_names – List of new pytplot names.

Return type:

str/list of str

pyspedas.derive(tvar, newname=None)[source]

Takes the derivative of the tplot variable.

Parameters:

  • tvar (str) – Name of tplot variable.

  • newname (str) – Name of new tplot variable. If not set, then the data in tvar is replaced.

Return type:

None

Examples

>>> pyspedas.store_data('b', data={'x':[2,5,8,11,14,17,20], 'y':[[1,1,1,1,1,1],[2,2,5,4,1,1],[100,100,3,50,1,1],[4,4,8,58,1,1],[5,5,9,21,1,1],[6,6,2,2,1,1],[7,7,1,6,1,1]]})
>>> pyspedas.derive('b','dbdt')
pyspedas.deriv_data(names, newname=None, suffix=None, overwrite=None, edge_order=1)[source]

Compute the derivative.

Parameters:

  • names (str/list of str) – List of pytplot names.

  • newname (str/list of str, optional) – List of new names for tplot variables. If not given, then a suffix is applied.

  • suffix (str, optional) – A suffix to apply. Default is ‘-avg’.

  • overwrite (bool, optional) – Replace the existing tplot name.

  • edge_order (int, optional) – A value passed to np.gradient that specifies how boundaries are treated

Return type:

None.

pyspedas.tkm2re(name, km=False, newname=None, suffix='')[source]

Converts a tplot variable to Re or Km

Parameters:

  • name (str or list of str) – Names of tplot variables to convert (wildcards accepted)

  • km (bool, optional) – If True, convert Re to Km. If False, convert Km to Re. Default: False

  • newname (str or list of str, optional) – Output variable names; if not set, the names of the input variables are used + ‘_re’ or ‘_km’ Default: None

  • suffix (str, optional) – Specify to append a suffix to each variable (only valid if newname is not specified) Default: ‘’

Return type:

List of the tplot variables created

Examples

>>> import pyspedas
>>> pyspedas.store_data('a', data={'x':[0,4,8,12,16], 'y':[1,2,3,4,5]})
>>> pyspedas.tkm2re('a', km = True)
pyspedas.avg_res_data(tvar, res, newname=None)[source]

Averages the variable over a specified period of time.

Parameters:

  • tvar (str) – Name of tplot variable.

  • res (int/float) – The new data resolution

  • newname (str) – Name of new tvar for averaged data. If not set, then the data in tvar is replaced.

Return type:

None

Note

This routine uses the xarray coarsen() method to reduce the time resolution. It will only work if the data is evenly gridded, and the res parameter evenly divides the number of samples. For most purposes, it is more appropriate to use pyspedas.avg_data() instead.

Examples

>>> #Average the data over every two seconds
>>> pyspedas.store_data('d', data={'x':[2,5,8,11,14,17,21], 'y':[[1,1,50],[2,2,3],[100,4,47],[4,90,5],[5,5,99],[6,6,25],[7,7,-5]]})
>>> pyspedas.avg_res_data('d',2,'d2res')
pyspedas.subtract_average(names, newname=None, suffix=None, overwrite=None, median=None)[source]

Subtracts the average or median from data.

Parameters:

  • names (str/list of str) – List of tplot variable names to process (wildcards accepted)

  • newname (str/list of str, optional) – List of new names for tplot variables. Default: None. If not given, then a suffix is applied.

  • suffix (str, optional) – A suffix to apply. Default: ‘-d’.

  • overwrite (bool, optional) – If set, then tplot variables are replaced. Default: None

  • median (float, optional) – If it is 0 or not set, then it computes the mean. Otherwise, it computes the median. Default: None.

Returns:

List of new tplot variables created

Return type:

list of str

Examples

>>> pyspedas.store_data('a', data={'x':[0,4,8,12,16], 'y':[1,2,3,4,5]})
>>> pyspedas.subtract_average('a')
>>> pyspedas.tplot(['a','a-d'])
pyspedas.subtract_median(names, newname=None, suffix=None, overwrite=None)[source]

Subtracts the median from data.

Parameters:

  • names (str/list of str) – List of pyspedas names.

  • newname (str/list of str, optional) – List of new names for tplot variables. Default: None. If not given, then a suffix is applied.

  • suffix (str, optional) – A suffix to apply. Default: ‘-d’.

  • overwrite (bool, optional) – If set, then tplot variables are replaced. Default: None

Returns:

Returns a list of new tplot variables created

Return type:

list of str

Examples

>>> from pyspedas import subtract_median
>>> pyspedas.store_data('a', data={'x':[0,4,8,12,16], 'y':[1.,2.,3.,4.,5.]})
>>> pyspedas.subtract_median('a')

Matrix/Vector Operations

pyspedas.tdotp(variable1, variable2, newname=None)[source]

Calculate the sample-by-sample dot product of two tplot variables

Parameters:

  • variable1 (str) – First tplot variable

  • variable2 (str) – Second tplot variable

  • newname (str) – Name of the output variable Default: variable1_dot_variable2

Returns:

Name of the tplot variable created

Return type:

str

Examples

>>> # Compute the dot products of a given time series
>>> import pyspedas
>>> x1 = [0, 4, 8]
>>> x2 = [0, 4, 8]
>>> time1 = [pyspedas.time_float("2020-01-01") + i for i in x1]
>>> time2 = [pyspedas.time_float("2020-01-01") + i for i in x2]
>>> pyspedas.store_data("a", data={"x": time1, "y": [[1, 2, 3],[2, 3, 4],[3, 4, 5]]})
>>> pyspedas.store_data("c", data={"x": time2, "y": [[1, 4, 1],[2, 5, 2],[3, 5, 3]]})
>>> n = pyspedas.tdotp("a", "c", newname="a_dot_c")
>>> print('new tplot variable:', n)
>>> ac = pyspedas.get_data(n)
>>> print(ac)
pyspedas.tcrossp(v1, v2, newname=None, return_data=False)[source]

Calculates the cross product of two tplot variables

Parameters:

  • v1 (str) – First tplot variable

  • v2 (str) – Second tplot variable

  • newname (str, optional) – Name of the output variable Default: v1_cross_v2

  • return_data (bool) – Returns the data as an ndarray instead of creating a tplot variable Default: False

Returns:

Name of the tplot variable created

Return type:

str

Examples

>>> # Compute the cross product of two time series
>>> import pyspedas
>>> x1 = [0, 4, 8]
>>> x2 = [0, 4, 8]
>>> time1 = [pyspedas.time_float("2020-01-01") + i for i in x1]
>>> time2 = [pyspedas.time_float("2020-01-01") + i for i in x2]
>>> pyspedas.store_data("a", data={"x": time1, "y": [[1, 2, 3],[2, 3, 4],[3, 4, 5]]})
>>> pyspedas.store_data("c", data={"x": time2, "y": [[1, 4, 1],[2, 5, 2],[3, 5, 3]]})
>>> n = pyspedas.tcrossp("a", "c", newname="a_cross_c")
>>> print('new tplot variable:', n)
>>> ac = pyspedas.get_data(n)
>>> print(ac)
pyspedas.tnormalize(variable, newname=None, return_data=False)[source]

Normalize all the vectors stored in a tplot variable

Parameters:

  • variable (str or np.ndarray) – tplot variable (or numpy array) containing the vectors to be normalized

  • newname (str, optional) – name of the output variable; If not set, output name will be variable + ‘_normalize’ Default: None

  • return_data (bool, optional) – If true, return the normalized vectors instead of creating a tplot variable Default: False

Returns:

name of the tplot variable created or normalized vectors if return_data is set

Return type:

str or ndarray of float

Examples

>>> import pyspedas
>>> pyspedas.store_data('a', data={'x':[1, 2, 3], 'y':[[1,2,3],[4,5,6],[7,8,9]]})
>>> pyspedas.tnormalize('a')
pyspedas.tvector_rotate(mat_var_in, vec_var_in, newname=None)[source]

Rotates tplot vector data by a set of coordinate ransformation matrices and outputs tplot variables. This is designed mainly for use with fac_matrix_make, but can be used for more general purposes. The input variable containing the rotation matrices is automatically interpolated to the timestamps in the vec_var_in variables, using the qslerp (Quaternion Spherical Linear intERPolation) routine from the PySPEDAS quaternion library.

Parameters:

  • mat_var_in (str) – Tplot variable containing the transformation matrices

  • vec_var_in (str or list of str) – Tplot variables to be transformed

  • newname (str or list of str) – Name of the output tplot variables

Return type:

Names of the variables created.

pyspedas.tvectot(tvars: str | List[str], newname=None, suffix=None, join_component=True) → str | List[str][source]

Computes the magnitude of a vector time series.

Parameters:

  • tvars (str or list[str]) – Names of the tplot variables.

  • newname (str or list[str]) – Names for the resultant magnitude tplot variables. If not provided, it appends the suffix to tvars.

  • suffix (str) – The suffix to append to tvars to form newname if newname is not provided.

  • join_component (bool) – If True, the magnitude tplot variable is joined with the component tplot variables.

Returns:

Names of the magnitude tplot variables.

Return type:

str or list[str]

Data Cleanup Operations

pyspedas.clean_spikes(names, nsmooth=10, thresh=0.3, sub_avg=False, newname=None, suffix=None, overwrite=None)[source]

Clean spikes from data.

Parameters:

  • names (str/list of str) – List of pyspedas names (wildcards accepted)

  • newname (str/list of str, optional) – List of new names for tplot variables. If not given, then a suffix is applied.

  • suffix (str, optional) – A suffix to apply. Default is ‘-avg’.

  • overwrite (bool, optional) – Replace the existing tplot name.

  • nsmooth (int, optional) – the number of data points for smoothing

  • thresh (float, optional) – threshold value

  • sub_avg (bool, optional) – if set, subtract the average value of the data prior to checking for spikes

Return type:

None.

pyspedas.clip(tvar, ymin, ymax, newname=None)[source]

Change out-of-bounds data to NaN.

Parameters:

  • tvar (str or list[str]) – tplot variable names to clip (wildcards accepted)

  • ymin (int/float) – Minimum value to keep (inclusive)

  • ymax (int/float) – Maximum value to keep (inclusive)

  • newname (str) – Name of new tvar for clipped data storage. If not specified, tvar will be replaced THIS is not an option for multiple variable input, for multiple or pseudo variables, the data is overwritten.

Return type:

None

Examples

>>> Make any values below 2 and above 6 equal to NaN.
>>> pyspedas.store_data('d', data={'x':[2,5,8,11,14,17,21], 'y':[[1,1],[2,2],[100,100],[4,4],[5,5],[6,6],[7,7]]})
>>> pyspedas.clip('d',2,6,'e')
pyspedas.crop(tvar1, tvar2, replace=True)[source]

Crops both tplot variable so that their times are the same. This is done automatically by other processing routines if times do not match up.

Parameters:

  • tvar1 (str) – Name of the first tplot variable

  • tvar2 (str) – Name of the second tplot variable

  • replace (bool, optional) – If true, the data in the original tplot variables are replaced. Otherwise, new variables are created.

Return type:

None

Examples

>>> pyspedas.store_data('a', data={'x':[0,4,8,12,16], 'y':[1,2,3,4,5]})
>>> pyspedas.store_data('b', data={'x':[2,5,8,11,14,17,20], 'y':[[1,1,1,1,1,1],[2,2,5,4,1,1],[100,100,3,50,1,1],[4,4,8,58,1,1],[5,5,9,21,1,1],[6,6,2,2,1,1],[7,7,1,6,1,1]]})
>>> pyspedas.crop('a','b')
pyspedas.time_clip(names, time_start, time_end, newname=None, suffix='-tclip', overwrite=False, interior_clip=False)[source]

Clip data from time_start to time_end.

Parameters:

  • names (str/list of str) – List of tplot variable names to time clip (wildcards accepted)

  • time_start (float or string) – Start time.

  • time_end (float or string) – End time.

  • newname (str/list of str, optional) – List of new names for tplot variables. Default: None. If not given, then a suffix is applied or the variables are overwritten

  • suffix (str, optional) – A suffix to apply. Default: ‘-tclip’

  • overwrite (bool, optional) – If true, overwrite the existing tplot variable. Default: False

  • interior_clip (bool, optional) – If true, reverse sense of operation and clip out times within the start/end range, for example, when manually despiking data. Default: False

Returns:

Returns a list of tplot variables created or changed

Return type:

list of str

Example

>>> # Clip time
>>> import pyspedas
>>> x1 = [0, 4, 8, 12, 16]
>>> time1 = [pyspedas.time_float("2020-01-01") + i for i in x1]
>>> pyspedas.store_data("a", data={"x": time1, "y": [[1, 2, 3],[2, 3, 4],[3, 4, 5],[4, 5, 6],[5, 6,7]]})
>>> time_start=time1[0]
>>> time_end=time1[2]
>>> pyspedas.time_clip('a',time_start,time_end)
>>> ac = pyspedas.get_data('a-tclip')
>>> print(ac)
pyspedas.deflag(tvar, flag=None, newname=None, method=None, fillval=None)[source]

Replace NaN or other ‘flag’ values in arrays with interpolated or other values.

Parameters:

  • tvar (str or list[str]) – Names of tplot variables to deflag (wildcards accepted)

  • flag (int,list) – Flagged data will be converted to NaNs.

  • method (str, optional) –

    Method to apply. Valid options:

    'repeat': Repeat last good value
'linear': Interpolate linearly over gap
'replace': Replace flagged values with fillval, or NaN if fillval not specified
'remove_nan': Remove timestamps and values with a NaN in any dimension

  • newname (str) – Name of new tvar for deflagged data storage. If not specified, then the data in tvar1 will be replaced. This is not an option for multiple variable input, for multiple or pseudo variables, the data is overwritten.

  • fillval (int, float (optional)) – Value to use as replacement when method=’replace’

Notes

deflag only works for 1 or 2-d data arrays; ntimes or (ntimes, nspectral_bins)

Return type:

None

Examples

>>> pyspedas.store_data('d', data={'x':[2,5,8,11,14,17,21], 'y':[[1,1],[2,2],[100,4],[4,90],[5,5],[6,6],[7,7]]})
>>> # Remove any instances of [100,90,7,2,57] from 'd', store in 'e'.
>>> pyspedas.deflag('d',[100,90,7,2,57],newname='e')
pyspedas.degap(tvar, dt=None, margin=0.25, maxgap=None, func='nan', newname=None, onenanpergap=False, twonanpergap=False)[source]

Fills gaps in the data either with NaNs or the last number.

Parameters:

  • tvar (str or list[str]) – Names of tplot variables to degap (wildcards accepted)

  • dt (int/float) – Step size of the data in seconds, default is to use the median time interval

  • margin (int/float, optional, default is 0.25 seconds) – The maximum deviation from the step size allowed before degapping occurs. In other words, if you’d like to fill in data every 4 seconds but occasionally the data is 4.1 seconds apart, set the margin to .1 so that a data point is not inserted there.

  • maxgap (int|float, optional) – Maximum gap length (in seconds) that will be filled. If None, defaults to entire time range (i.e. all gaps with length > (dt+margin) will be filled)

  • func (str, optional) – Either ‘nan’ or ‘ffill’, which overrides normal interpolation with NaN substitution or forward-filled values.

  • newname (str, optional) – The new tplot variable name to store the data into. If None, then the data is overwritten. This is not an option for multiple variable input, for multiple or pseudo variables, the data is overwritten.

  • onenanpergap (bool) – if set to True, then only insert one NaN value, rather than adding NaN values at dt resolution

  • twonanpergap (bool) – if set to True, then only insert one NaN value, rather than adding NaN values at dt resolution

Returns:

Creates a new tplot variable with the degap data

Return type:

None

Examples

>>> import pyspedas
>>> time = [pyspedas.time_float("2020-01-01") + i for i in [1, 2, 3, 4, 5, 6, 9, 10, 11]]
>>> y = [1, 2, 3, 4, 5, 6, 9, 10, 11]
>>> pyspedas.store_data("a", data={"x": time, "y": y})
>>> degap("a", newname="b")
>>> b = pyspedas.get("b")
>>> print(b)
pyspedas.makegap(var_data, dt=None, margin=0.0, func='nan')[source]

Fill gaps in the data either with NaNs or the last number. This is identical to degap, except operates directly on the data and time arrays, rather than the tplot variable. This is intended for use with the data_gap option. This version actually puts the data into a temporary tplot variable, and call degap, then extracts that data into the proper form.

Parameters:

  • var_data (named tuple) – The data for the tplot variable, a structure that contains at least, tags for ‘y’ and ‘times’

  • dt (int/float) – Step size of the data in seconds, default is to use the median time interval

  • margin (int/float, optional, default is 0.0 seconds (there is no margin in the IDL tplot makegap)) – The maximum deviation from the step size allowed before degapping occurs. In other words, if you’d like to fill in data every 4 seconds but occasionally the data is 4.1 seconds apart, set the margin to .1 so that a data point is not inserted there.

  • func (str, optional) – Either ‘nan’ or ‘ffill’, which overrides normal interpolation with NaN substitution or forward-filled values.

Returns:

A tuple returned by calling get_data() on the degapped temp variable

Return type:

tuple

Examples

>>> import pyspedas
>>> time = [pyspedas.time_float("2020-01-01") + i for i in [1, 2, 3, 4, 5, 6, 9, 10, 11]]
>>> y = [1, 2, 3, 4, 5, 6, 9, 10, 11]
>>> pyspedas.store_data("a", data={"x": time, "y": y})
>>> a = pyspedas.get_data("a")
>>> print(a)
>>> b = pyspedas.makegap(a)
>>> print(b)
pyspedas.tsmooth(names, width=10, median=None, preserve_nans=None, newname=None, suffix=None, overwrite=None)[source]

Smooths a tplot variable.

Parameters:

  • names (str/list of str) – List of tplot variable names to be smoothed (wildcards accepted)

  • width (int, optional) – Data window to use for smoothing. The default is 10.

  • median (bool, optional) – Apply the median as well. The default is None.

  • preserve_nans (bool, optional) – If None, then replace NaNs. The default is None.

  • newname (str/list of str, optional) – List of new names for tplot variables. If not given, then a suffix is applied. The default is None.

  • suffix (str, optional) – A suffix to apply. Default is ‘-s’. The default is None.

  • overwrite (bool, optional) – Replace the existing tplot name. The default is None.

Returns:

Returns list of tplot variables created or changed

Return type:

list of str

Example

>>> import pyspedas
>>> import numpy as np
>>> pyspedas.store_data('a', data={'x': range(100), 'y': np.random.random(100)})
>>> pyspedas.tsmooth('a')

Interpolation Tools

There are several routines for performing interpolation in PySPEDAS, each designed for slightly different use cases.

pyspedas.interpol() operates directly on arrays, not tplot variables. It is a wrapper around scipy.interpolate.interp1d().

pyspedas.interpol(data, data_times, out_times, fill_value='extrapolate')[source]

Interpolate data.

Parameters:

  • data (list of float) – Data array.

  • data_times (list of float) – Time array.

  • out_times (list of float) – Time array to interpolate to

  • fill_value (str, optional) – Default: “extrapolate”

Return type:

Interpolated data

Examples

>>> import pyspedas
>>> x1 = [0, 4, 8, 12]
>>> time1 = [pyspedas.time_float("2020-01-01") + i for i in x1]
>>> x2=[0, 2, 4, 6, 8, 10, 12]
>>> y1=[10, 20, 30, 40]
>>> time2 = [pyspedas.time_float("2020-01-01") + i for i in x2]
>>> pyspedas.interpol(y1, time1, time2)

pyspedas.tinterpol() operates on tplot variables, and uses the xarray interp() method (which itself uses scipy.interp1d) internally. It can take a list of tplot variables and perform the interpolation on all of them.

pyspedas.tinterpol(names, interp_to, method=None, newname=None, extrapolate=False, suffix=None)[source]

Interpolate data to times in interp_to.

Parameters:

  • names (array_like or str) – List of tplot variables to interpolate. Allowed wildcards are ? for a single character, * from multiple characters.

  • interp_to (array_like or str) – String containing the tplot variable with the time stamps to interpolate to.

  • method (str, optional) – Interpolation method. Default is ‘linear’. Specifies the kind of interpolation as a string (‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’, ‘previous’, ‘next’) where ‘zero’, ‘slinear’, ‘quadratic’ and ‘cubic’ refer to a spline interpolation of zeroth, first, second or third order; ‘previous’ and ‘next’ simply return the previous or next value of the point) or as an integer specifying the order of the spline interpolator to use.

  • newname (str or list of str, optional) – List of new names for tplot variables. If ‘’, then tplot variables are replaced. If not given, then a suffix is applied.

  • extrapolate (bool) – If true, extrapolate beyond the start/end times of the interp_to variable. Default is False (for now)

  • suffix (str, optional) – A suffix to apply. Default is ‘-itrp’.

Returns:

This function works in-place or creates new tplot variables depending on the ‘newname’ parameter.

Return type:

None

Notes

Uses xarray interp method to interpolate data to the times in interp_to. See: https://docs.xarray.dev/en/latest/generated/xarray.DataArray.interp.html Similar to tinterpol.pro in IDL SPEDAS.

‘linear’ vs. ‘slinear’ methods: Due to a quirk in the implmentation of the scipy interp1d routine (used internally by xarray.interp),’linear’ interpolation may yield unexpected results under certain conditions. In particular, when using 32-bit floating point data, if an output time exactly matches one of the input times, the interpolated value may differ slightly (on the order of 1 ULP) from the input value at that timestamp. This can cause problems for downstream calculations: for example, if the input is strictly non-negative, but contains zero values, the interpolated data may contain small negative values. The ‘slinear’ method does not appear to suffer from this issue, but may be slightly slower.

Examples

>>> import numpy as np
import pyspedas
>>> import pyspedas

>>> # Create some time series data
>>> times = np.array(['2002-02-03T04:05:00', '2002-02-03T04:05:05', '2002-02-03T04:05:10'], dtype='datetime64')
>>> data = np.array([0.0, 5.0, 10.0])

>>> # Store the data as a tplot variable
>>> pyspedas.store_data('variable1', data={'x': times, 'y': data})

>>> # Create some new times to interpolate to
>>> new_times = np.array(['2002-02-03T04:05:07', '2002-02-03T04:05:08', '2002-02-03T04:05:09'], dtype='datetime64')
>>> new_data = np.array([11.0, 12.0, 13.0])

>>> # Store the new times in a tplot variable, the new_data will be ignored in this example
>>> pyspedas.store_data('variable2', data={'x': new_times, 'y': new_data})

>>> # Interpolate 'variable1' to the new times using the default linear method
>>> pyspedas.tinterpol(names='variable1', interp_to='variable2')

>>> # The interpolated data is now stored in 'variable1-itrp'
>>> interpolated_data = pyspedas.get_data('variable1-itrp')
>>> print(interpolated_data)

pyspedas.interp_nan() operates on single tplot variables, and uses the xarray interpolat_na() method to perform interpolation, while ignoring sufficiently short runs of NaN values.

pyspedas.interp_nan(tvar, newname=None, s_limit=None)[source]

Interpolates the tplot variable through NaNs in the data. This is basically just a wrapper for xarray’s interpolate_na function.

Note

This analysis routine assumes the data is no more than 2 dimensions. If there are more, they may become flattened!

Parameters:

  • tvar (str) – Name of tplot variable.

  • newname (str) – Name of new tvar for added data. If not set, then the original tvar is replaced.

  • s_limit (int or float, optional) – The maximum size of the gap in seconds to not interpolate over. I.e. if there are too many NaNs in a row, leave them there.

Return type:

None

Examples

>>> import pyspedas
>>> import numpy as np
>>> pyspedas.store_data('e', data={'x':[2,5,8,11,14,17,21], 'y':[[np.nan,1,1],[np.nan,2,3],[4,np.nan,47],[4,np.nan,5],[5,5,99],[6,6,25],[7,np.nan,-5]]})
>>> pyspedas.interp_nan('e','e_nonan',s_limit=5)

pyspedas.tinterp() operates on single tplot variables, using the xarray interp_like() method internally.

pyspedas.tinterp(tvar1, tvar2, replace=False)[source]

Interpolates one tplot variable to another one’s time cadence. This is done automatically by other processing routines.

Parameters:

  • tvar1 (str) – Name of first tplot variable whose times will be used to interpolate tvar2’s data.

  • tvar2 (str) – Name of second tplot variable whose data will be interpolated.

  • replace (bool, optional) – If true, the data in the original tplot variable is replaced. Otherwise, a variable is created.

Returns:

Name of the new tplot variable

Return type:

str

Examples

>>> pyspedas.store_data('a', data={'x':[0,4,8,12,16], 'y':[1,2,3,4,5]})
>>> pyspedas.store_data('c', data={'x':[0,4,8,12,16,19,21], 'y':[1,4,1,7,1,9,1]})
>>> pyspedas.tinterp('a','c')

Wave, Polarization, Power Spectrum operations

pyspedas.dpwrspc(time, quantity, nboxpoints=256, nshiftpoints=128, bin=3, tbegin=-1.0, tend=-1.0, noline=False, nohanning=False, notperhz=False, notmvariance=False, tm_sensitivity=None)[source]

Compute power spectra.

Parameters:

  • time (list of float) – Time array.

  • quantity (list of float) – Data array.

  • nboxpoints (int, optional) – The number of points to use for the hanning window. The default is 256.

  • nshiftpoints (int, optional) – The number of points to shift for each spectrum. The default is 128.

  • bin (int, optional) – Size for binning of the data along the frequency domain. The default is 3.

  • tbegin (float, optional) – Start time for the calculation. If -1.0, the start time is the first time in the time array.

  • tend (float, optional) – End time for the calculation. If -1.0, the end time is the last time in the time array.

  • noline (bool, optional) – If True, no straight line is subtracted. The default is False.

  • nohanning (bool, optional) – If True, no hanning window is applied to the input. The default is False.

  • notperhz (bool, optional) – If True, the output units are the square of the input units. The default is False.

  • notmvariance (bool, optional) – If True, replace output spectrum for any windows that have variable cadence with NaNs. The default is False.

  • tm_sensitivity (float, optional) – If noTmVariance is set, this number controls how much of a dt anomaly is accepted. The default is None.

Returns:

tdps: array of float

The time array for the dynamic power spectrum, the center time of the interval used for the spectrum.

fdps: array of float

The frequency array (units =1/time units).

dps: array of float

The power spectrum, (units of quantity)^2/frequency_units.

Return type:

tuple

Examples

>>> # Compute the power spectrum of a given time series
>>> import numpy as np
>>> time = range(3000)
>>> quantity = np.random.random(3000)
>>> power = pyspedas.dpwrspc(time, quantity)
pyspedas.twavpol(tvarname, prefix='', nopfft=-1, steplength=-1, bin_freq=-1)[source]

Apply wavpol to a tplot variable.

Creates multiple tplot variables: ‘_powspec’,’_degpol’, ‘_waveangle’, ‘_elliptict’, ‘_helict’, ‘_pspec3_x’, ‘_pspec3_y’, ‘_pspec3_z’

Parameters:

  • tvarname (string) – Name of tplot variable.

  • prefix (string, optional) – Prefix for tplot variables created.

  • nopfft (int, optional) – Number of points in FFT. The default is 256.

  • steplength (int, optional) – The amount of overlap between successive FFT intervals. The default is -1 which means nopfft/2.

  • bin_freq (int, optional) – Number of bins in frequency domain. The default is 3.

Returns:

result – Returns 1 if completed successfully. Returns 0 if it encountered problems and exited.

Return type:

bool

pyspedas.pwr_spec(tvar, nbp=256, nsp=128, newname=None)[source]

Calculates the power spectrum of a line, and adds a tplot variable for this new spectrogram

Parameters:

  • tvar (str) – Name of tvar to use

  • nbp (int, optional) – The number of points to use when calculating the FFT

  • nsp (int, optional) – The number of points to shift over to calculate the next FFT

  • newname (str, optional) – The name of the new tplot variable created,

Return type:

None

Examples

>>> import pyspedas
>>> import math
>>> time = [pyspedas.time_float("2020-01-01") + i for i in range(10000)]
>>> quantity = [math.sin(i) for i in range(10000)]
>>> pyspedas.store_data("dp", data={"x": time, "y": quantity})
>>> pyspedas.pwr_spec("dp", newname="dp_pwrspec")
>>> pyspedas.tplot("dp_pwrspec")
pyspedas.pwrspc(time, quantity, noline=False, nohanning=False, bin=3, notperhz=False)[source]

Compute the power spectrum of a given time series.

Parameters:

  • time (array) – The time array.

  • quantity (array) – The data array for which the power spectrum is to be computed. Should be one dimensional and the same length as time.

  • noline (bool) – If True, straight line is not subtracted from the data.

  • nohanning (bool) – If True, no Hanning window is applied to the data.

  • bin (int) – Bin size for binning the data. Default is 3.

  • notperhz (bool) – If True, the output units are the square of the input units.

Returns:

  • tuple –

    Tuple containing:
    • freq (array):

      The frequency array.

    • power (array):

      The computed power spectrum.

  • Notes – This is similar to IDL pwrspc.pro routine.

    A Hanning window is applied to the input data, and its power is divided out of the returned spectrum. A straight line is subtracted from the data to reduce spurious power due to sawtooth behavior of a background. Units are (units)^2 where units are the units of the input quantity. Frequency is in 1/time units. Thus, the output represents the mean squared amplitude of the signal at each specific frequency. The total (sum) power under the curve is equal to the mean (over time) power of the oscillation in the time domain. If the keyword notperhz is True, then power is in units^2. If notperhz is False (default), power is in units^2/Hz.

Examples

>>> # Compute the power spectrum of a given time series
>>> from pyspedas import pwrspc
>>> time = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> quantity = [1,2,3,1,2,3,1,2,3,1]
>>> freq, power = pwrspc(time, quantity)
>>> print(freq, power)
pyspedas.tpwrspc(varname, newname=None, overwrite=False, noline=False, nohanning=False, bin=3, notperhz=False, trange=None, axis=0)[source]

This function is a wrapper for pwrspc. It applies pwrspc to a tplot variable and stores the result in a new tplot variable.

Parameters:

  • varname (str) – Name of the tplot variable.

  • newname (str, optional) – New name for the output tplot variable. If not set, default output variable will be Default: None

  • overwrite (bool, optional) – If True, overwrite the existing tplot variable. If True, then the newname keyword has no effect. Default: False

  • noline (bool, optional) – If True, straight line is not subtracted from the data. Default: False

  • nohanning (bool, optional) – If True, no Hanning window is applied to the data. Default: False

  • bin (int, optional) – Bin size for binning the data. Default: 3

  • notperhz (bool, optional) – If True, the output units are the square of the input units. Default: False

  • trange (list, optional) – Time range for the data extraction. Default: None

  • axis (int, optional) – If the input variable is multi-dimensional, this specifies the axis to operate along. Default: 0, first axis.

Returns:

Name of the new tplot variable created by this function. The output variable contains a single data point, frequency as v, and power as y.

Return type:

str

Examples

>>> import pyspedas
>>> import numpy as np
>>> pyspedas.store_data('a', data={'x': range(100), 'y': np.random.random(100)})
>>> pyspedas.tpwrspc('a')
>>> pyspedas.get_data('a_pwrspc')
pyspedas.tdpwrspc(varname, newname=None, trange=['0.0', '0.0'], nboxpoints=None, nshiftpoints=None, polar=False, bin=3, nohanning=False, noline=False, notperhz=False, notmvariance=False)[source]

Compute power spectra for a tplot variable.

Parameters:

  • varname (str) – Name of tplot variable.

  • newname (str, optional) – Name of new tplot variable to save data to. Default: None. If newname is not set ‘_dpwrspc’ will be appended to the varname

  • trange (list of float, optional) – Start and end times for the calculation.

  • nboxpoints (int, optional) – The number of points to use for the hanning window. Default: 256

  • nshiftpoints (int, optional) – The number of points to shift for each spectrum. Default: 128

  • polar (bool, optional) – If True, the input data is in polar coordinates. Default: False

  • bin (int, optional) – Size for binning of the data along the frequency domain. Default: 3

  • nohanning (bool, optional) – If True, no hanning window is applied to the input. Default: False

  • noline (bool, optional) – If True, no straight line is subtracted. Default: False

  • notperhz (bool, optional) – If True, the output units are the square of the input units. Default: False

  • notmvariance (bool, optional) – If True, replace output spectrum for any windows that have variable. cadence with NaNs. Default: False

Returns:

Name of new tplot variable.

Return type:

str

Example

>>> # Compute the power spectrum of a given time series
>>> import pyspedas
>>> import numpy as np
>>> pyspedas.store_data('a', data={'x': range(3000), 'y': np.random.random(3000)})
>>> pyspedas.tdpwrspc('a')
pyspedas.spec_mult(tvar, newname=None)[source]

Multiplies the data by the stored spectrogram bins and created a new tplot variable

Note::

This analysis routine assumes the data is no more than 2 dimensions. If there are more, they may become flattened!

Parameters:

  • tvar (str) – Name of tplot variable

  • newname (str) – Name of new tvar in which to store interpolated data. Default: If none is specified, a name will be created of the form tvar_specmult.

Return type:

None

Examples

>>> pyspedas.store_data('h', data={'x':[0,4,8,12,16,19,21], 'y':[[8,1,1],[100,2,3],[4,2,47],[4,39,5],[5,5,99],[6,6,25],[7,-2,-5]],'v':[[1,1,50],[2,2,3],[100,4,47],[4,90,5],[5,5,99],[6,6,25],[7,7,-5]]})
>>> pyspedas.spec_mult('h')

Download utilities

pyspedas.download(remote_path='', remote_file='', local_path='', local_file='', headers={}, username=None, password=None, verify=True, session=None, no_download=False, last_version=False, basic_auth=False, regex=False, no_wildcards=False, text_only=None, force_download=False)[source]

Download one or more remote files and return their local paths.

Parameters:

  • remote_path (str) – String consisting of a common URL base for all remote files.

  • remote_file (str or list of str) – String or string array of URLs to remote files.

  • local_path (str) – String consisting of a common local path for all local files.

  • local_file (str or list of str) – String or string array of local destination file names.

  • headers (dict) – Dictionary containing the headers to be passed to the requests get call.

  • username (str, optional) – Username to be used in HTTP authentication.

  • password (str, optional) – Password to be used in HTTP authentication.

  • basic_auth (bool, optional) – Flag to indicate that the remote server uses basic authentication instead of digest authentication.

  • verify (bool, optional) – Flag indicating whether to verify the SSL/TLS certificate.

  • session (requests.Session object, optional) – Requests session object that allows you to persist things like HTTP authentication through multiple calls.

  • no_download (bool, optional) – Flag to not download remote files.

  • last_version (bool, optional (default is True)) – Flag to only download the last in file in a lexically sorted list when multiple matches are found using wildcards.

  • regex (bool, optional) – Flag to allow regular expressions in the file name matching, instead of unix style matching.

  • no_wildcards (bool, optional) – Flag to assume no wild cards in the requested url/filename.

  • text_only (bool, optional) – If True, save the response content as utf-8 encoded text. If False, treat as a stream of bytes. If None, try to infer the correct format from the filename suffix. Defaults to None.

  • force_download (bool, optional) – Flag to indicate if the file should be downloaded even if a local version exists. This causes the local version of the file to be overwritten.

  • Cloud Awareness

  • —————

  • In support of URIs passed as inputs, priority is given to streaming from a URI source

  • rather than downloading the file(s). This behavior is separate from web-based urls

  • that would become overloaded. The package fsspec is used to simulate a filesystem

  • functionality for several URI protocols.

Returns:

String list specifying the full local path to all requested files.

Return type:

list of str

Examples

>>> from pyspedas import download
>>> remote_path = "https://spdf.gsfc.nasa.gov/pub/data/omni/omni_cdaweb/hro_5min/2012/"
>>> remote_files = ["omni_hro_5min_20121101_v01.cdf", "omni_hro_5min_20121201_v01.cdf"]
>>> local_path = "/tmp/omni/"
>>> files = download(remote_path=remote_path, remote_file=remote_files, local_path=local_path)
>>> print(files)
['/tmp/omni/omni_hro_5min_20121101_v01.cdf', '/tmp/omni/omni_hro_5min_20121201_v01.cdf']
pyspedas.download_ftp(ftp_server, remote_path, remote_file, local_path, local_file=None, username='anonymous', password='anonymous@', force_download=False)[source]

Download a file from an FTP server.

Parameters:

  • ftp_server (str) – FTP server name or IP address.

  • remote_path (str) – Path on the FTP server where the file is located.

  • remote_file (str) – Name of the file to download.

  • local_path (str) – Local directory to save the file.

  • local_file (str, optional) – Name of the file to save locally. If not provided, the name of the remote file is used.

  • username (str, optional) – Username for the FTP server. Default is ‘anonymous’.

  • password (str, optional) – Password for the FTP server. Default is ‘anonymous@’.

  • force_download (bool, optional) – Force the download even if the remote file is not newer than the local file. Default is False.

Returns:

A list containing the path of the downloaded file.

Return type:

list

Raises:

Exception – If the remote file is not found on the FTP server.

Examples

>>> from pyspedas import download_ftp
>>> ftp_site = "ftp.gfz-potsdam.de"
>>> kp_dir = "/pub/home/obs/kp-ap/wdc/yearly/"
>>> remote_file = "kp2012.wdc"
>>> local_dir = "/tmp/"
>>> files = download_ftp(ftp_site, kp_dir, remote_file, local_dir)
>>> print(files)
['/tmp/kp2012.wdc']
pyspedas.dailynames(directory='', trange=None, res=86400.0, hour_res=False, file_format='%Y%m%d', prefix='', suffix='', return_times=False)[source]

Creates a list of file names using a time range, resoution and file format Based on Davin Larson’s file_dailynames in IDL SPEDAS

Parameters:

  • directory – str String containing the directory for the generated file names Default: ‘’. If directory is not specified the names will be written to the current working directory

  • trange – list of str, list of datetime or list of floats Two-element list containing the start and end times for the file names Default: Current date. If the date range is not specified the routine will use the current date.

  • res – float File name resolution in seconds Default: 24*3600., i.e., daily)

  • file_format – str Format of the file names using strftime directives; for reference: https://strftime.org Default: %Y%m%d, i.e., daily

  • prefix – str file name prefix Default: ‘’

  • suffix – str file name suffix Default: ‘’

Returns:

List containing filenames

Example

>>> from pyspedsas import time_float
>>> time_range = time_float(['2021-01-01','2021-01-03'])
>>> pyspedas.dailynames(trange=time_range)
pyspedas.load_leap_table(reload=False)[source]

Loads the leap second table for converting TAI to unix times

Parameters:

reload (bool) – Re-load the leap second table, even if it exists locally.

This shouldn’t be needed until at least 2035:

https://www.scientificamerican.com/article/the-leap-seconds-time-is-up-world-votes-to-stop-pausing-clocks/

Returns:

A dictionary containing ‘dates’ with array of Julian dates corresponding to the leap seconds in the ‘leaps’ array

Return type:

dict

File Format Readers/Writers

pyspedas.tplot_ascii(tvar, filename=None, extension='.csv')[source]

Save a single tplot variable in CSV format.

This routine converts the internal tplot data structure into a Pandas data frame, then uses the Pandas to_csv() function to save it in CSV format.

If the tplot variable includes spectral bin metadata, it will be written to a separate file with a “_v” inserted after the filename and before the “.csv” suffix.

Parameters:

  • tvar (str) – tplot variable name

  • filename (str) – Base filename to use. If spec_bin data is present, it will be written to a separate file with “_v” appended to the base filename. The file extension suffix should not be included here (it will be added internally).

  • extension (str) – File extension suffix to apply to the base filename. Default: “.csv” (no other file formats are supported).

Examples

>>> import pyspedas
>>> pyspedas.projects.themis.state(probe='a', trange=['2007-03-23', '2007-03-24'])
>>> pyspedas.tplot_ascii('tha_pos',filename='themis_a_position')
pyspedas.tplot_save(names, filename=None)[source]

This function will save tplot variables into a single file by using the python “pickle” function. This file can then be “restored” using tplot_restore. This is useful if you want to end the pyspedas session, but save all of your data/options. All variables and plot options can be read back into tplot with the “tplot_restore” command.

Parameters:

  • names – str/list A string or a list of strings of the tplot variables you would like saved.

  • filename – str, optional The filename where you want to save the file.

Returns:

None

Examples

>>> # Save a single tplot variable
>>> 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)
>>> pyspedas.tplot_save('Variable1', filename='C:/temp/variable1.pyspedas')
pyspedas.cdf_to_tplot(filenames, mastercdf=None, varformat=None, exclude_format=None, get_support_data=False, get_metadata=False, get_ignore_data=False, string_encoding='ascii', prefix='', suffix='', plot=False, merge=False, center_measurement=False, notplot=False, varnames=None)[source]

This function will automatically create tplot variables from CDF files. In general, the files should be ISTP compliant for this importer to work. Each variable is read into a new tplot variable (a.k.a an xarray DataArray), and all associated file/variable metadata is read into the attrs dictionary.

Note

Variables must have an attribute named “VAR_TYPE”. If the attribute entry is “data” (or “support_data”), then they will be added as tplot variables. Additionally, data variables should have attributes named “DEPEND_TIME” or “DEPEND_0” that describes which variable is x axis. If the data is 2D, then an attribute “DEPEND_1” must describe which variable contains the secondary axis.

Parameters:

  • filenames – str/list of str The file names and full paths of CDF files.

  • mastercdf – str The file name of a master CDF to be used, if any

  • varformat – str or list[str] The file variable formats to load into tplot. Wildcard character “*” is accepted. By default, all variables are loaded in.

  • exclude_format – str or list[str] The file variable formats to exclude from loading into tplot. Wildcard character “*” is accepted. By default, no variables are excluded.

  • get_support_data – bool Data with an attribute “VAR_TYPE” with a value of “support_data” will be loaded into tplot. By default, only loads in data with a “VAR_TYPE” attribute of “data”.

  • prefix – str The tplot variable names will be given this prefix. By default, no prefix is added.

  • suffix – str The tplot variable names will be given this suffix. By default, no suffix is added.

  • plot – bool The data is plotted immediately after being generated. All tplot variables generated from this function will be on the same plot.

  • merge – bool If True, then data from different cdf files will be merged into a single tplot variable.

  • get_ignore_data – bool Data with an attribute “VAR_TYPE” with a value of “ignore_data” will be loaded into tplot. By default, only loads in data with a “VAR_TYPE” attribute of “data”.

  • center_measurement – bool If True, the CDF epoch variables are time-shifted to the middle of the accumulation interval by their DELTA_PLUS_VAR and DELTA_MINUS_VAR variable attributes

  • notplot – bool If True, then data are returned in a hash table instead of being stored in tplot variables (useful for debugging, and access to multi-dimensional data products)

  • varnames – str or list of str Load these variables only. If None or [] or [‘*’], then load everything.

Returns:

List of tplot variables created (unless notplot keyword is used).

pyspedas.netcdf_to_tplot(filenames, time='', prefix='', suffix='', plot=False, merge=False, strict_time=True)[source]

Create tplot variables from netCDF files.

Parameters:

  • filenames (str or list of str) – The file names and full paths of netCDF files.

  • time (str, optional) – This is not used anymore. Remains here for backward compatibility. Currently, the name of the time variable is found in the netCDF variables themselves.

  • prefix (str, optional) – The tplot variable names will be given this prefix. By default, no prefix is added.

  • suffix (str, optional) – The tplot variable names will be given this suffix. By default, no suffix is added.

  • plot (bool, optional) – If True, the data is plotted immediately after being generated. All tplot variables generated from this function will be on the same plot. By default, a plot is not created.

  • merge (bool, optional) – If True, then data from ‘filenames’ will be merged into existing tplot variables. If False (default), then data from ‘filenames’ will overwrite existing tplot variables. Data in ‘filenames’ will always be merged/combined by themselves.

  • strict_time (bool, optional) – If True (default), variables will be loaded into tplot variables only if their data length matches the time length. If False, all variables will be loaded. This is useful because some variables may contain general information, like satellite longitude.

Returns:

stored_variables – List of tplot variables created.

Return type:

list of str

Examples

Create tplot variables from a GOES netCDF file:

>>> import pyspedas
>>> file = "/Users/user_name/goes_files/g15_epead_a16ew_1m_20171201_20171231.nc"
>>> pyspedas.netcdf_to_tplot(file, prefix='mvn_')

Add a prefix, and plot immediately:

>>> import pyspedas
>>> file = "/Users/user_name/goes_files/g15_epead_a16ew_1m_20171201_20171231.nc"
>>> pyspedas.netcdf_to_tplot(file, prefix='goes_prefix_', plot=True)
pyspedas.sts_to_tplot(filenames=None, prefix='', suffix='', merge=False, notplot=False)[source]

Convert STS files to tplot variables.

Parameters:

  • filenames (str or list of str, optional) – The full path(s) to the STS file(s). If a single string is provided, it will be treated as a single file path. If a list of strings is provided, each string will be treated as a separate file path. Default is None.

  • prefix (str, optional) – A prefix to be added to the variable names when creating tplot variables. Default is an empty string.

  • suffix (str, optional) – A suffix to be added to the variable names when creating tplot variables. Default is an empty string.

  • merge (bool, optional) – If True, then data from ‘filenames’ will be merged into existing tplot variables. If False (default), then data from ‘filenames’ will overwrite existing tplot variables. Data in ‘filenames’ will always be merged/combined by themselves.

  • notplot (bool, optional) – If True, the STS data will be returned as a dictionary without creating tplot variables. If False, tplot variables will be created. Default is False.

Returns:

Returns a list of the tplot variables created. If notplot is True, a dictionary containing the STS data is returned.

Return type:

list of str or dict

Notes

The .sts file format is a text file format used by the MAVEN mission. It is a simple format that contains a header section with metadata and a data section with the actual data. This function reads the data section of the STS file and converts it to tplot variables.

Examples

>>> f = ["/maven/data/sci/mag/l2/2015/01/mvn_mag_l2_2015002ss1s_20150102_v01_r01.sts",
         "/maven/data/sci/mag/l2/2015/01/mvn_mag_l2_2015001ss1s_20150101_v01_r01.sts"]
>>> vars = sts_to_tplot(filenames=f)
>>> print(vars)
['DDAY', 'OB_N', 'POSN', 'OB_BDPL']
pyspedas.tplot_restore(filename)[source]

Restore tplot variables that have been saved to a file.

If the filename has a suffix “.tplot”, it is assumed to be in the IDL .sav format as written by the IDL tplot_save routine. In this case, it is read using the scipy.io.readsav() routine.

For any other filename suffix, the file is assumed to be a Python pickle file, as written by the PySPEDAS tplot_save routine.

Most of the metadata (units, coordinate systems, CDF attributes etc.) should be correctly represented in the tplot variables created by tplot_restore.

Some IDL plot options may not have direct counterparts in the PySPEDAS matplotlib-based plot options.

For multidimensional variables (spectra, particle distributions, etc.), the IDL v, v1, v2 (etc.) attributes should also be correctly represented in the output tplot variables.

Parameters:

filename (str) – The path to the “.tplot” file created by IDL tplot_save, or for any other suffix, the pickle file created by PySPEDAS tplot_save.

Return type:

None

Examples

>>> # Restore the saved data from the tplot_save example
>>> import pyspedas
>>> pyspedas.tplot_restore('C:/temp/variable1.pyspedas')

Miscellaneous utilities

pyspedas.find_datasets(mission=None, instrument=None, label=False, quiet=False)[source]

Find datasets from the Coordinated Data Analysis System (CDAS) based on mission and/or instrument criteria.

This function queries the CDAS for datasets, optionally filtering by mission and instrument. It can also display labels for the datasets.

Parameters:

  • mission (str, optional) – The name of the mission to filter the datasets. If None, datasets are not filtered by mission.

  • instrument (str, optional) – The name of the instrument to filter the datasets. If None, datasets are not filtered by instrument.

  • label (bool, default False) – If True, the function prints both the dataset ID and label. If False, only the dataset ID is printed.

  • quiet (bool, default False) – If True, suppresses printing of dataset IDs (and labels) found

Returns:

List of datasets found

Return type:

list of str

Examples

>>> from pyspedas import find_datasets
>>> find_datasets(mission='MMS', instrument='FGM')
MMS1_FGM_BRST_L2
MMS1_FGM_SRVY_L2
...

>>> # Suppress printed output
>>> from pyspedas import find_datasets
>>> mms_list = find_datasets(mission='MMS', quiet=True)
>>> print(mms_list[0:3])
pyspedas.find_ip_address()[source]

Uses api.ipify.org to get the public IP address, useful for troubleshooting data access issues in test suites

pyspedas.is_gzip(file_path)[source]

Check if a file is gzip-compressed.

Parameters:

file_path (str) – Path to the file to be checked

Returns:

True if first two bytes are ‘0x1f 0x8b’, false otherwise

Return type:

bool

pyspedas.libs(function_name, package=None)[source]

Search for a specified function by exact name, substring, or wildcard within a given package and its submodules.

Parameters:

  • function_name (str) – The name or partial name of the function to search for. If “*” or “?” are found in the function name, a case-insensitive wildcard match is performed, otherwise function_name is treated as a substring to match.

  • package (module, optional) (The Python package in which to search for the function.) – Default is the pyspedas package. This should be a Python module object.

Note

All submodules of pyspedas are imported during the search. The package option is simply narrows the search. The function specifically searches for functions, not classes or other objects. If multiple functions with the same name exist in different modules within the package, it will list them all. The function handles ImportError exceptions by printing an error message and continuing the search.

Example

>>> from pyspedas import libs
>>> libs('fgm')
>>> libs('fgm', package=pyspedas.projects.mms)
pyspedas.wildcard_expand(master_list, patterns, case_sensitive=True, split_whitespace=True, quiet=False)[source]

Find elements in master list matching one or more wild card patterns

Parameters:

  • master_list (str or list of str) – One or more strings (for example, the set of all tplot variable names)

  • patterns (str or list of str) – One or more patterns, which may contain wildcard characters, to be matched agains the master list

  • case_sensitive (bool) – A boolean flag indicating whether case-sensitive matching should be performed. Default: True

  • split_whitespace (bool) – A boolean flag indicating that master_list or patterns should be treated as space-delimited lists. Set to False if embedded spaces are to be matched. Default: True

  • quiet (bool) – A boolean flag indicating whether to suppress “match not found” warnings. Default: False

Returns:

A list of elements from master_list that match at least one of the input patterns. Duplicates in the output will be removed.

Return type:

list of str

Examples

>>> from pyspedas import wildcard_expand
>>> master_list = ['mms1_mec_r_sm', 'mms2_mec_r_sm', 'mms3_mec_r_gsm', 'tha_pos_gsm']
>>> wildcard_expand(master_list,'*')
['mms1_mec_r_sm', 'mms2_mec_r_sm', 'mms3_mec_r_gsm', 'tha_pos_gsm']
>>> wildcard_expand(master_list, ['mms?_mec_r_sm'])
['mms1_mec_r_sm', 'mms2_mec_r_sm']
>>>wildcard_expand(master_list, ['*SM'], case_sensitive=False)
['mms1_mec_r_sm', 'mms2_mec_r_sm', 'mms3_mec_r_gsm', 'tha_pos_gsm']
>>> wildcard_expand(master_list,'tha_pos_gsm')
['tha_pos_gsm']
pyspedas.mpause_2(xmp=None, ymp_west=None, short=False, xmp_max=10.78)[source]

Calculate the magnetopause (X, Y) locations based on the Fairfield model (JGR, 1971). An aberration of 4 degrees is assumed.

Parameters:

  • xmp (array-like, optional) – Spacecraft position, x component (defaults to a range if not provided).

  • ymp_west (deprecated, unused) – This parameter is kept for compatibility with the IDL version, but it is unused.

  • short (bool, optional) – If True, the function returns a shorter version of the magnetopause (defaults to False).

  • xmp_max (float, optional) – Maximum value of xmp (defaults to 10.78, the value from the Fairfield paper).

Returns:

tuple – xmp (numpy.ndarray): The x coordinates of the magnetopause. ymp (numpy.ndarray): The y coordinates of the magnetopause.

Return type:

A tuple containing two elements:

Notes

Similar to mpause_2.pro in IDL SPEDAS.

pyspedas.mpause_t96(pd, xgsm=None, ygsm=None, zgsm=None)[source]

Calculate the location of the magnetopause using the Tsyganenko 1996 (T96) model.

Parameters:

  • pd (float) – Solar wind ram pressure in nanopascals.

  • xgsm, ygsm, zgsm (array-like) – Coordinates of points in Earth radii (Re) to check whether they are inside or outside the magnetopause.

Returns:

  • xmgnp, ymgnp, zmgnp (array-like) – Locations of the magnetopause boundary in Earth radii (Re).

  • id (array-like) – Array flagging whether the given points are inside (1), outside (-1), or not checked (np.nan).

  • distan (array-like) – Distance from the given points to the nearest point on the magnetopause boundary.

Notes

The pressure-dependent magnetopause that is used in the T96_01 model (TSYGANENKO, JGR, V.100, P.5599, 1995; ESA SP-389, P.181, O;T. 1996)

Similar to mpause_t96.pro in IDL SPEDAS.