speasy.products package

class speasy.products.Catalog(name: str, meta: dict = None, events: List[Event] = None)

Bases: SpeasyProduct

The Catalog class allows to manipulate a goup of events like a simple Python list of Event plus some meta data.

Attributes:

namestr

Catalog name

metadict

All additional Catalog meta data

Methods

append:	Append an Event or a list of Event to the end of the Catalog
pop:	Remove and return Event at index (default last)

See also

speasy.products.catalog.Event

speasy.products.timetable.TimeTable

Examples

>>> import speasy
>>> from speasy.products import Catalog, Event
>>> my_catalog = Catalog(name='MyCatalog', meta={'tags':['demo', 'docstrings']}, events=[])
>>> my_catalog.append(Event('2018-01-01', '2018-01-02', meta={'name':'My first event!'}))
>>> my_catalog += Event('2019-01-01', '2019-01-02', meta={'name':'My second event!'})
>>> for e in my_catalog:
...     print(e)
...
<Event: 2018-01-01T00:00:00+00:00 -> 2018-01-02T00:00:00+00:00 | {'name': 'My first event!'}>
<Event: 2019-01-01T00:00:00+00:00 -> 2019-01-02T00:00:00+00:00 | {'name': 'My second event!'}>

append(events: Event) → None

Append an Event or a list of Event to the end of the Catalog.

Parameters:

eventsEvent or List[Event]

Raises:

TypeError

If events is neither an Event or a list of Event

See also

Catalog.pop

meta

name

pop(index: int = -1) → Event

Remove and return Event at index (default last).

Parameters:

indexint

Returns:

Event

The removed event

Raises:

IndexError

if list is empty or index is out of range.

to_dataframe() → DataFrame

class speasy.products.DataContainer(values: array, meta: Dict = None, name: str = None, is_time_dependent: bool = True)

Bases: DataContainerProtocol[DataContainer]

copy(name=None)

property dtype

static empty_like(other: DataContainer) → DataContainer

static from_dictionary(dictionary: ~typing.Dict[str, str | ~typing.Dict[str, str] | ~typing.List], dtype=<class 'numpy.float64'>) → DataContainer

property is_time_dependent: bool

property meta

property name

property nbytes: int

property ndim

static ones_like(other: DataContainer) → DataContainer

static reserve_like(other: DataContainer, length: int = 0) → DataContainer

reshape(new_shape) → DataContainer

select(indices, inplace=False) → DataContainer

property shape

to_dictionary(array_to_list=False) → Dict[str, object]

property unit: str

unit_applied(unit: str = None) → DataContainer

property values: array

view(index_range: slice | ndarray)

static zeros_like(other: DataContainer) → DataContainer

class speasy.products.Dataset(name: str, variables: dict, meta: dict)

Bases: SpeasyProduct

A Dataset is basically a collection of SpeasyVariables

meta

name

plot(ax=None, **kwargs)

time_range() → DateTimeRange | None

variables

class speasy.products.Event(start_time: datetime, stop_time: datetime, meta=None)

Bases: DateTimeRange

The Event class is a DatetimeRange with some meta data. It is supposed to be used with Catalog

Attributes:

start_timedatetime.datetime

stop_timedatetime.datetime

metadict

Additional event data

See also

speasy.products.catalog.Catalog

speasy.core.datetime_range.DateTimeRange

Notes

This class support the same operations as a speasy.common.datetime_range.DateTimeRange.

meta

class speasy.products.SpeasyVariable(axes: List[VariableAxis], values: DataContainer, columns: List[str] | None = None)

Bases: SpeasyProduct

SpeasyVariable object. Base class for storing variable data.

Attributes:

time: numpy.ndarray

time vector (x-axis data)

values: numpy.ndarray

data

meta: Optional[dict]

metadata

columns: Optional[List[str]]

column names, might be empty for spectrograms or 3D+ data

axes: List[np.ndarray]

Collection composed of time axis plus eventual additional axes according to values’ shape

axes_labels: List[str]

Axes names

unit: str

Values physical unit

name: str

SpeasyVariable name

nbytes: int

memory usage in bytes

fill_value: Any

fill value if found in meta-data

valid_range: Tuple[Any, Any]

valid range if found in meta-data

Methods

view:	Returns a view of the current variable within the desired index_range
to_dataframe:	Converts the variable to a pandas.DataFrame object
from_dataframe:	Builds a SpeasyVariable from a pandas.DataFrame object
to_astropy_table:	Converts the variable to an astropy.table.Table
unit_applied:	Returns a copy where values are astropy.units.Quantity
filter_columns:	Returns a copy only containing selected columns
replace_fillval_by_nan:	Returns a SpeasyVaraible with NaN instead of fill value if fill value is set in meta data
plot:	Plot the data with matplotlib by default
to_dictionary:	Converts a SpeasyVariable to a Python dictionary, mostly used for serialization purposes
copy:	Returns a copy

property axes: List[VariableTimeAxis]

SpeasyVariable axes, axis 0 is always a VariableTimeAxis, there should be the same number of axes than values dimensions

Returns:

List[VariableTimeAxis or VariableAxis]

list of variable axes

property axes_labels: List[str]

Axes names respecting axes order

Returns:

List[str]

list of axes names

clamp_with_nan(inplace=False, valid_min=None, valid_max=None) → SpeasyVariable

Replaces values outside valid range by NaN, valid range is taken from metadata fields “VALIDMIN” and “VALIDMAX”

Parameters:

inplacebool, optional

Modifies source variable when true else modifies and returns a copy, by default False

valid_minFloat, optional

Optional minimum valid value, takes metadata field “VALIDMIN” if not provided, by default None

valid_maxFloat, optional

Optional maximum valid value, takes metadata field “VALIDMAX” if not provided, by default None

Returns:

SpeasyVariable

source variable or copy with values clamped by NaN

See also

replace_fillval_by_nan

replaces fill values by NaN

sanitized

removes fill and invalid values

property columns: List[str]

SpeasyVariable columns names when it makes sense

Returns:

List[str]

list of columns names

copy(name=None) → SpeasyVariable

Makes a deep copy the variable

Parameters:

name: str, optional

new variable name, by default None, keeps the same name

Returns:

SpeasyVariable

deep copy the variable

property dtype

static empty_like(other: SpeasyVariable) → SpeasyVariable

Create a SpeasyVariable with the same properties than given variable but unset values

Parameters:

otherSpeasyVariable

variable used as reference for shape and meta-data

Returns:

SpeasyVariable

a SpeasyVariable similar to given one

property fill_value: Any | None

SpeasyVariable fill value if found in meta-data

Returns:

Any

fill value if found in meta-data

filter_columns(columns: List[str]) → SpeasyVariable

Builds a SpeasyVariable with only selected columns

Parameters:

columnsList[str]

list of column names to keep

Returns:

SpeasyVariable

a SpeasyVariable with only selected columns

static from_dataframe(df: DataFrame) → SpeasyVariable

Load from pandas.DataFrame object.

Parameters:

df: pandas.DataFrame

Input DataFrame to convert

Returns:

SpeasyVariable:

Variable created from DataFrame

See also

to_dataframe

exports a SpeasyVariable to a pandas DataFrame

to_astropy_table

exports a SpeasyVariable to an astropy.Table object

static from_dictionary(dictionary: Dict[str, object]) → SpeasyVariable

Builds a SpeasyVariable from a well formed dictionary

Returns:

SpeasyVariable or None

See also

to_dictionary

exports SpeasyVariable to dictionary

property meta: Dict

SpeasyVariable meta-data

Returns:

Dict

SpeasyVariable meta-data

property name: str

SpeasyVariable name

Returns:

str

SpeasyVariable name

property nbytes: int

SpeasyVariable’s values and axes memory usage

Returns:

int

number of bytes used to store values and axes

property ndim

static ones_like(other: SpeasyVariable) → SpeasyVariable

Create a SpeasyVariable with the same properties than given variable but filled with ones

Parameters:

otherSpeasyVariable

variable used as reference for shape and meta-data

Returns:

SpeasyVariable

a SpeasyVariable similar to given one filled with ones

property plot

Plot the variable, tries to do its best to detect variable type and to populate plot labels

replace_fillval_by_nan(inplace=False) → SpeasyVariable

Replaces fill values by NaN, non float values are automatically converted to float. Fill value is taken from metadata field “FILLVAL”

Parameters:

inplacebool, optional

Modifies source variable when true else modifies and returns a copy, by default False

Returns:

SpeasyVariable

source variable or copy with fill values replaced by NaN

See also

clamp_with_nan

replaces values outside valid range by NaN

sanitized

removes fill and invalid values

static reserve_like(other: SpeasyVariable, length: int = 0) → SpeasyVariable

Create a SpeasyVariable of given length and with the same properties than given variable but unset values

Parameters:

otherSpeasyVariable

variable used as reference for shape and meta-data

lengthint, optional

output variable length, by default 0

Returns:

SpeasyVariable

a SpeasyVariable similar to given one of given length

sanitized(drop_fill_values=True, drop_out_of_range_values=True, drop_nan_and_inf=True, inplace=False, valid_min=None, valid_max=None) → SpeasyVariable

Returns a copy of the variable with fill values and invalid values removed

Parameters:

drop_fill_valuesbool, optional

Remove fill values, by default True

drop_out_of_range_valuesbool, optional

Remove values outside valid range, by default True

drop_nan_and_infbool, optional

Remove NaN and Infinite values, by default True

inplacebool, optional

Modifies source variable when true else modifies and returns a copy, by default False

valid_minFloat, optional

Minimum valid value, takes metadata field “VALIDMIN” if not provided, by default None

valid_maxFloat, optional

Maximum valid value, takes metadata field “VALIDMAX” if not provided, by default None

Returns:

SpeasyVariable

source variable or copy with fill and invalid values removed

See also

replace_fillval_by_nan

replaces fill values by NaN

clamp_with_nan

replaces values outside valid range by NaN

property shape

property time: array

Time axis values, equivalent to var.axes[0].values

Returns:

np.array

time axis values as numpy array of datetime64[ns]

to_astropy_table() → Table

Convert the variable to an astropy.Table object.

Parameters:

datetime_index: bool

boolean indicating that the index is datetime

Returns:

astropy.Table:

Variable converted to astropy.Table

See also

from_dataframe

builds a SpeasyVariable from a pandas DataFrame

to_dataframe

exports a SpeasyVariable to a pandas DataFrame

to_dataframe() → DataFrame

Convert the variable to a pandas.DataFrame object.

Returns:

pandas.DataFrame:

Variable converted to Pandas DataFrame

See also

from_dataframe

builds a SpeasyVariable from a pandas DataFrame

to_astropy_table

exports a SpeasyVariable to an astropy.Table object

to_dictionary(array_to_list=False) → Dict[str, object]

Converts SpeasyVariable to dictionary

Parameters:

array_to_listbool, optional

Converts numpy arrays to Python Lists when true, by default False

Returns:

Dict[str, object]

See also

from_dictionary

builds variable from dictionary

property unit: str

SpeasyVariable unit if found in meta-data

Returns:

str

unit if found in meta-data

unit_applied(unit: str = None, copy=True) → SpeasyVariable

Returns a SpeasyVariable with given or automatically found unit applied to values

Parameters:

unitstr or None, optional

Use given unit or gets one from variable metadata, by default None

copybool, optional

Preserves source variable and returns a modified copy if true, by default True

Returns:

SpeasyVariable

SpeasyVariable identic to source one with values converted to astropy.units.Quantity according to given or found unit

See also

unit

returns variable unit if found in meta-data

Notes

This interface assume that there is only one unit for the whole variable since all stored in the same array

property valid_range: Tuple[Any, Any] | None

SpeasyVariable valid range if found in meta-data

Returns:

Tuple[Any, Any]

valid range if found in meta-data

property values: array

SpeasyVariable values

Returns:

np.array

SpeasyVariable values

view(index_range: slice | ndarray) → SpeasyVariable

Return view of the current variable within the desired index_range.

Parameters:

index_range: slice

index range

Returns:

speasy.common.variable.SpeasyVariable

view of the variable on the given range

static zeros_like(other: SpeasyVariable) → SpeasyVariable

Create a SpeasyVariable with the same properties than given variable but filled with zeros

Parameters:

otherSpeasyVariable

variable used as reference for shape and meta-data

Returns:

SpeasyVariable

a SpeasyVariable similar to given one filled with zeros

class speasy.products.TimeTable(name: str, meta: dict = None, dt_ranges: List[DateTimeRange] = None)

Bases: SpeasyProduct

A TimeTable is basically a collection of DateTimeRange

append(dt_range: DateTimeRange)

meta

name

pop(index=-1)

to_dataframe() → DataFrame

class speasy.products.VariableAxis(values: array = None, meta: Dict = None, name: str = '', is_time_dependent: bool = False, data: DataContainer = None)

Bases: DataContainerProtocol[VariableAxis]

static from_dictionary(dictionary: Dict[str, str | Dict[str, str] | List], time=None) → VariableAxis

property is_time_dependent: bool

property meta: Dict

property name: str

property nbytes: int

static reserve_like(other: VariableAxis, length: int = 0) → VariableAxis

select(indices, inplace=False) → VariableAxis

property shape

to_dictionary(array_to_list=False) → Dict[str, object]

property unit: str

property values: array

view(index_range: slice | ndarray) → VariableAxis

class speasy.products.VariableTimeAxis(values: array = None, meta: Dict = None, name: str = 'time', data: DataContainer = None)

Bases: DataContainerProtocol[VariableTimeAxis]

static from_dictionary(dictionary: Dict[str, str | Dict[str, str] | List], time=None) → VariableTimeAxis

property is_time_dependent: bool

property meta: Dict

property name: str

property nbytes: int

static reserve_like(other: VariableTimeAxis, length: int = 0) → VariableTimeAxis

select(indices, inplace=False) → VariableTimeAxis

property shape

to_dictionary(array_to_list=False) → Dict[str, object]

property unit: str

property values: array

view(index_range: slice | ndarray) → VariableTimeAxis

Submodules

• speasy.products.base_product module
  • SpeasyProduct
    • SpeasyProduct.request_params
• speasy.products.catalog module
  • Catalog
    • Catalog.append()
    • Catalog.meta
    • Catalog.name
    • Catalog.pop()
    • Catalog.to_dataframe()
  • Event
    • Event.meta
• speasy.products.dataset module
  • Dataset
    • Dataset.meta
    • Dataset.name
    • Dataset.plot()
    • Dataset.time_range()
    • Dataset.variables
• speasy.products.timetable module
  • TimeTable
    • TimeTable.append()
    • TimeTable.meta
    • TimeTable.name
    • TimeTable.pop()
    • TimeTable.to_dataframe()
• speasy.products.variable module
  • SpeasyVariable
    • SpeasyVariable.axes
    • SpeasyVariable.axes_labels
    • SpeasyVariable.clamp_with_nan()
    • SpeasyVariable.columns
    • SpeasyVariable.copy()
    • SpeasyVariable.dtype
    • SpeasyVariable.empty_like()
    • SpeasyVariable.fill_value
    • SpeasyVariable.filter_columns()
    • SpeasyVariable.from_dataframe()
    • SpeasyVariable.from_dictionary()
    • SpeasyVariable.meta
    • SpeasyVariable.name
    • SpeasyVariable.nbytes
    • SpeasyVariable.ndim
    • SpeasyVariable.ones_like()
    • SpeasyVariable.plot
    • SpeasyVariable.replace_fillval_by_nan()
    • SpeasyVariable.reserve_like()
    • SpeasyVariable.sanitized()
    • SpeasyVariable.shape
    • SpeasyVariable.time
    • SpeasyVariable.to_astropy_table()
    • SpeasyVariable.to_dataframe()
    • SpeasyVariable.to_dictionary()
    • SpeasyVariable.unit
    • SpeasyVariable.unit_applied()
    • SpeasyVariable.valid_range
    • SpeasyVariable.values
    • SpeasyVariable.view()
    • SpeasyVariable.zeros_like()
  • from_dataframe()
  • from_dictionary()
  • merge()
  • same_time_axis()
  • to_dataframe()
  • to_dictionary()