HermesData

class hermes_core.timedata.HermesData(timeseries: TimeSeries, support: dict[Quantity | NDData] | None = None, spectra: NDCollection | None = None, meta: dict | None = None)

Bases: object

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

Parameters:

• timeseries (astropy.timeseries.TimeSeries) – The time series of data. Columns 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 time series in an ISTP-compliant format.

Examples

>>> 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
>>> from hermes_core.timedata import HermesData
>>> # 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))
... }
>>> # Create Global Metadata Attributes
>>> input_attrs = HermesData.global_attribute_template("eea", "l1", "1.0.0")
>>> # Create HermesData Object
>>> hermes_data = HermesData(timeseries=ts, support=support_data, spectra=spectra, meta=input_attrs)

Raises:

• ValueError – If the number of columns is less than 2 or the required ‘time’ column is missing.:

• TypeError – If any column, excluding ‘time’, is not an astropy.units.Quantity object with units.:

• ValueError – If the elements of a TimeSeries column are multidimensional:

• TypeError – If any supoport data elements are not type astropy.nddata.NDData:

• TypeError – If spectra is not an NDCollection object.:

References

• Astropy TimeSeries

• Astropy Quantity and Units

• Astropy Time

• Astropy NDData

• Sunpy NDCube and NDCollection

• Space Physics Guidelines for CDF (ISTP)

Attributes Summary

data	(dict) A dict containing each of timeseries and support.
meta	(collections.OrderedDict) 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) 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.
append(timeseries)	Add additional measurements to an existing column.
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 HERMES CDF file.

Attributes Documentation

data

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

meta

(collections.OrderedDict) 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) A TimeSeries representing one or more measurements as a function of time.

Methods Documentation

add_measurement(measure_name: str, data: Quantity, meta: dict | None = None)

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 = None)

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)

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.:

append(timeseries: TimeSeries)

Add additional measurements to an existing column.

Parameters:

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

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

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: str)

Load data from a file.

Parameters:

file_path (str) – A fully specificed file path.

Returns:

data (HermesData) – A HermesData 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

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)

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)

Remove an existing measurement or support data array.

Parameters:

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

save(output_path: str | None = None, overwrite: bool = False)

Save the data to a HERMES CDF file.

Parameters:

• output_path (str, optional) – A string path to the directory where file is to be saved. If not provided, saves to the current directory.

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

Returns:

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