SWXData

class swxsoc.swxdata.SWXData(timeseries: TimeSeries | dict[str, TimeSeries], support: dict[Quantity | NDData] | None = None, spectra: NDCollection | None = None, meta: dict | None = None, schema: SWXSchema | None = None)[source]

Bases: object

A generic object for loading, storing, and manipulating space weather time series data.

Parameters:

  • timeseries (Union[astropy.timeseries.TimeSeries, Dict[str, astropy.timeseries.TimeSeries]]) – The time-series data. This can be a single astropy.timeseries.TimeSeries object or a dictionary of str to astropy.timeseries.TimeSeries objects. If a dictionary, one key must be named ‘epoch’, the primary time axis. If non-index/time columns are included in any of the TimeSeries objects, they must be Quantity arrays.

  • support (Optional[dict[Union[astropy.units.Quantity, astropy.nddata.NDData]]]) – Support data arrays which do not vary with time (i.e. Non-Record-Varying data).

  • spectra (Optional[ndcube.NDCollection]) – One or more ndcube.NDCube objects containing spectral or higher-dimensional timeseries data.

  • meta (Optional[dict]) – The metadata describing the data in an ISTP-compliant format.

  • schema (Optional[SWXSchema]) – An optional SWXSchema instance for metadata derivation. If not provided, a default SWXSchema will be created.

Examples

>>> import os
>>> import numpy as np
>>> import astropy.units as u
>>> from astropy.timeseries import TimeSeries
>>> from ndcube import NDCube, NDCollection
>>> from astropy.wcs import WCS
>>> from astropy.nddata import NDData
>>> import swxsoc
>>> from swxsoc.swxdata import SWXData
>>> # Set mission to HERMES for this example (eea is a HERMES instrument)
>>> os.environ["SWXSOC_MISSION"] = "hermes"
>>> swxsoc._reconfigure()
>>> # Create a TimeSeries structure
>>> data = u.Quantity([1, 2, 3, 4], "gauss", dtype=np.uint16)
>>> ts = TimeSeries(time_start="2016-03-22T12:30:31", time_delta=3 * u.s, data={"Bx": data})
>>> # Create a Spectra structure
>>> spectra = NDCollection(
...     [
...         (
...             "test_spectra",
...             NDCube(
...                 data=np.random.random(size=(4, 10)),
...                 wcs=WCS(naxis=2),
...                 meta={"CATDESC": "Test Spectra Variable"},
...                 unit="eV",
...             ),
...         )
...     ]
... )
>>> # Create a Support Structure
>>> support_data = {
...     "data_mask": NDData(data=np.eye(100, 100, dtype=np.uint16), meta={"CATDESC": "Data Mask", "VAR_TYPE": "metadata"})
... }
>>> # Create Global Metadata Attributes
>>> input_attrs = SWXData.global_attribute_template("eea", "l1", "1.0.0")
>>> # Create SWXData Object
>>> sw_data = SWXData(timeseries=ts, support=support_data, spectra=spectra, meta=input_attrs)
Raises:

References

Attributes Summary

data

(dict) A dict containing each of timeseries, spectra and support.

meta

(dict) Global metadata associated with the measurement data.

spectra

(ndcube.NDCollection]) A NDCollection object containing high-dimensional spectra data.

support

(dict[Union[astropy.units.Quantity, astropy.nddata.NDData]]) A dict containing one or more non-time-varying support variables.

time

(astropy.time.Time) The times of the measurements.

time_range

(tuple) The start and end times of the times.

timeseries

(astropy.timeseries.TimeSeries or dict) A TimeSeries representing one or more measurements as a function of time.

Methods Summary

add_measurement(measure_name, data[, meta])

Add a new time-varying scalar measurement (column).

add_spectra(name, data[, meta])

Add a new time-varying vector measurement.

add_support(name, data[, meta])

Add a new non-time-varying data array.

add_timeseries(epoch_key, timeseries)

Add a new TimeSeries object to the collection of epochs.

append(timeseries)

Add additional measurements to an existing column.

get_timeseres_epoch_key(timeseries, var_data)

Function to determine the TimeSeries Epoch for a Record-Varying Variable.

global_attribute_template([instr_name, ...])

Function to generate a template of the required ISTP-compliant global attributes.

load(file_path)

Load data from a file.

measurement_attribute_template()

Function to generate a template of the required measurement attributes.

plot([axes, columns, subplots])

Plot the measurement data.

remove(measure_name)

Remove an existing measurement or support data array.

save([output_path, overwrite])

Save the data to a CDF file.

Attributes Documentation

data

(dict) A dict containing each of timeseries, spectra and support.

meta

(dict) Global metadata associated with the measurement data.

spectra

(ndcube.NDCollection]) A NDCollection object containing high-dimensional spectra data.

support

(dict[Union[astropy.units.Quantity, astropy.nddata.NDData]]) A dict containing one or more non-time-varying support variables.

time

(astropy.time.Time) The times of the measurements.

time_range

(tuple) The start and end times of the times.

timeseries

(astropy.timeseries.TimeSeries or dict) A TimeSeries representing one or more measurements as a function of time. If there are multiple TimeSeries, a dictionary is returned.

Methods Documentation

add_measurement(measure_name: str, data: Quantity, meta: dict = None)[source]

Add a new time-varying scalar measurement (column).

Parameters:

  • measure_name (str) – Name of the measurement to add.

  • data (astropy.units.Quantity) – The data to add. Must have the same time stamps as the existing data.

  • meta (dict, optional) – The metadata associated with the measurement.

Raises:

  • TypeError – If var_data is not of type Quantity.:

  • ValueError – If data has more than one dimension:

add_spectra(name: str, data: NDCube, meta: dict = None)[source]

Add a new time-varying vector measurement. This include higher-dimensional time-varying data.

Parameters:

  • name (str) – Name of the measurement to add.

  • data (ndcube.NDCube) – The data to add. Must have the same time stamps as the existing data.

  • meta (dict, optional) – The metadata associated with the measurement.

Raises:

TypeError – If var_data is not of type NDCube.:

add_support(name: str, data: Quantity | NDData, meta: dict | None = None)[source]

Add a new non-time-varying data array.

Parameters:

  • name (str) – Name of the data array to add.

  • data (Union[astropy.units.Quantity, astropy.nddata.NDData],) – The data to add.

  • meta (Optional[dict], optional) – The metadata associated for the data array.

Raises:

TypeError – If var_data is not of type NDData.:

add_timeseries(epoch_key: str, timeseries: TimeSeries)[source]

Add a new TimeSeries object to the collection of epochs.

Parameters:
append(timeseries: TimeSeries)[source]

Add additional measurements to an existing column.

Parameters:

timeseries (astropy.timeseries.TimeSeries) – The data to be appended (rows) as a TimeSeries object.

static get_timeseres_epoch_key(timeseries, var_data, var_meta: dict = None)[source]

Function to determine the TimeSeries Epoch for a Record-Varying Variable.

Parameters:

  • timeseries (dict[str, astropy.timeseries.TimeSeries]) – A dictionary of str to astropy.timeseries.TimeSeries objects. Each TimeSeries object represents a different epoch.

  • var_data (astropy.units.Quantity) – The variable data that we want to find the epoch for.

  • var_meta (dict, optional) – The metadata associated with the variable data.

static global_attribute_template(instr_name: str = '', data_level: str = '', version: str = '') → OrderedDict[source]

Function to generate a template of the required ISTP-compliant global attributes.

Parameters:

  • instr_name (str) – The instrument name. Must be “eea”, “nemisis”, “merit” or “spani”.

  • data_level (str) – The data level of the data. Must be “l0”, “l1”, “ql”, “l2”, “l3”, “l4”

  • version (str) – Must be of the form X.Y.Z.

Returns:

template (collections.OrderedDict) – A template for required global attributes.

classmethod load(file_path: Path)[source]

Load data from a file.

Parameters:

file_path (pathlib.Path) – A fully specified file path of the data file to load.

Returns:

data (SWXData) – A SWXData object containing the loaded data.

Raises:

ValueError – If the file type is not recognized as a file type that can be loaded.:

static measurement_attribute_template() → OrderedDict[source]

Function to generate a template of the required measurement attributes.

Returns:

template (collections.OrderedDict) – A template for required variable attributes that must be provided.

plot(axes=None, columns=None, subplots=True, **plot_args)[source]

Plot the measurement data.

Parameters:

  • axes (Axes, optional) – If provided the image will be plotted on the given axes. Defaults to None and creates a new axis.

  • columns (list[str], optional) – If provided, only plot the specified measurements otherwise try to plot them all.

  • subplots (bool) – If set, all columns are plotted in their own plot panel.

  • **plot_args (dict, optional) – Additional plot keyword arguments that are handed to Axes.

Returns:

Axes – The plot axes.

remove(measure_name: str)[source]

Remove an existing measurement or support data array.

Parameters:

measure_name (str) – Name of the variable to remove.

save(output_path: Path = None, overwrite: bool = False)[source]

Save the data to a CDF file.

Parameters:

  • output_path (pathlib.Path, optional) – Path to save location. Can be: - A directory: saves using Logical_file_id from metadata as filename - A full file path (with .cdf extension): saves using that filename If not provided, saves to the current directory with Logical_file_id.

  • overwrite (bool) – If set, overwrites existing file of the same name.

Returns:

path (str) – A path to the saved file.