speasy package

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

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[source]

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[source]

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[source]

class speasy.Dataset(name: str, variables: dict, meta: dict)[source]

Bases: SpeasyProduct

A Dataset is basically a collection of SpeasyVariables

meta

name

plot(ax=None, **kwargs)[source]

time_range() → DateTimeRange | None[source]

variables

class speasy.Event(start_time: datetime, stop_time: datetime, meta=None)[source]

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.SpeasyVariable(axes: List[VariableAxis], values: DataContainer, columns: List[str] | None = None)[source]

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

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

property columns: List[str]

SpeasyVariable columns names when it makes sense

Returns:

List[str]: list of columns names

copy() → SpeasyVariable[source]

Makes a deep copy the variable

Returns:

SpeasyVariable: deep copy the variable

property dtype

static empty_like(other: SpeasyVariable) → SpeasyVariable[source]

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

filter_columns(columns: List[str]) → SpeasyVariable[source]

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[source]

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[source]

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[source]

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[source]

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

static reserve_like(other: SpeasyVariable, length: int = 0) → SpeasyVariable[source]

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

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[source]

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[source]

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][source]

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 = None, copy=True) → SpeasyVariable[source]

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

property values: array

SpeasyVariable values

Returns:

np.array: SpeasyVariable values

view(index_range: slice) → SpeasyVariable[source]

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[source]

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.TimeTable(name: str, meta: dict | None = None, dt_ranges: List[DateTimeRange] | None = None)[source]

Bases: SpeasyProduct

A TimeTable is basically a collection of DateTimeRange

append(dt_range: DateTimeRange)[source]

meta

name

pop(index=-1)[source]

to_dataframe() → DataFrame[source]

speasy.get_data(*args, **kwargs) → SpeasyProduct | List[SpeasyProduct] | None[source]

Retrieve requested product(s). Speasy gives access to two kind of products, time-dependent products such as physical measurements or trajectories and products such as timetables or event catalogs. So depending on which product you want to retrieve speasy.get_data() accepts different sets of arguments:

For time-independent products:

get_data(product_or_products, **kwargs)

For time-dependent products:

get_data(product_or_products, start_time, stop_time, **kwargs)
get_data(product_or_products, datetime_range_or_datetime_range, **kwargs)

Since get_data accepts both at the same time a list of products and a list of ranges, it will always iterate first on products then on datetime ranges. In other words, all products will be retrieved for all given datetime ranges.

Parameters:

args

Either a time independent or a list of time independent indexes or any combination of time dependent or list of time dependent indexes plus a datetime range or a list of datetime ranges. See examples below for more details.

kwargs

For webservice specific keyword arguments check Web services.

disable_proxy: bool
ignore proxy configuration and always bypass proxy server when True (default: False).
disable_cache: bool
ignore cache content when True (default: False).
progress: bool
show progress bar when True (default: False).

Returns:

requested product(s) according to given parameters, either a single product or a collection of products.

Examples

A simple parameter request on a single tile range:

>>> import speasy as spz
>>> spz.get_data("amda/imf_gsm", "2016-10-10", "2016-10-11")
<speasy.products.variable.SpeasyVariable object at ...>

Same with a catalog using Speasy dynamic inventory:

>>> import speasy as spz
>>> amda_catalogs = spz.inventories.tree.amda.Catalogs
>>> spz.get_data(amda_catalogs.SharedCatalogs.EARTH.model_regions_plasmas_cluster_2005)
<Catalog: model_regions_plasmas_cluster_2005>

You can also request a collection of catalogs:

>>> import speasy as spz
>>> amda_catalogs = spz.inventories.tree.amda.Catalogs
>>> spz.get_data([amda_catalogs.SharedCatalogs.EARTH.model_regions_plasmas_cluster_2005,
...               amda_catalogs.SharedCatalogs.EARTH.model_regions_plasmas_mms_2019])
[<Catalog: model_regions_plasmas_cluster_2005>, <Catalog: model_regions_plasmas_mms_2019>]

You can also request a parameter for several intervals:

>>> import speasy as spz
>>> spz.get_data("amda/imf_gsm", [["2016-10-10", "2016-10-11"],
...                               ["2017-10-10", "2017-10-11"]])
[<speasy.products.variable.SpeasyVariable object at ...>, <speasy.products.variable.SpeasyVariable object at ...>]

Several products on a single interval:

>>> import speasy as spz
>>> spz.get_data(["amda/imf_gsm", spz.inventories.tree.ssc.Trajectories.wind],
...              "2016-10-10", "2016-10-11")
[<speasy.products.variable.SpeasyVariable object at ...>, <speasy.products.variable.SpeasyVariable object at ...>]

Several products for several time ranges:

>>> import speasy as spz
>>> data= spz.get_data(["amda/imf_gsm",
...                  spz.inventories.tree.ssc.Trajectories.wind],
...              [["2016-10-10", "2016-10-11"],
...               ["2017-10-10", "2017-10-11"]])
>>> len(data), len(data[0])
(2, 2)

A catalog or a timetable can also be used as time ranges collection to download a product:

>>> import speasy as spz
>>> amda_shared_tt = spz.inventories.tree.amda.TimeTables.SharedTimeTables
>>> mex_inventory = spz.inventories.tree.amda.Parameters.MEX
>>> mgs_inventory = spz.inventories.tree.amda.Parameters.MGS
>>> conj_mex_mgs = spz.get_data(amda_shared_tt.MARS.conjonctions_mex_mgs_2004_0)
>>> data = spz.get_data(
...                     [mex_inventory.ELS.mex_els_all.mex_els_spec,
...                      mgs_inventory.MAG.mgs_mag_mso.b_mgs_mso],
...                     conj_mex_mgs)
>>> len(data), len(data[0])
(2, 28)

Can even pass a CatalogIndex or a TimeTableIndex directly:

>>> import speasy as spz
>>> amda_shared_tt = spz.inventories.tree.amda.TimeTables.SharedTimeTables
>>> mex_inventory = spz.inventories.tree.amda.Parameters.MEX
>>> mgs_inventory = spz.inventories.tree.amda.Parameters.MGS
>>> data = spz.get_data(
...                     [mex_inventory.ELS.mex_els_all.mex_els_spec,
...                      mgs_inventory.MAG.mgs_mag_mso.b_mgs_mso],
...                     amda_shared_tt.MARS.conjonctions_mex_mgs_2004_0)
>>> len(data), len(data[0])
(2, 28)

speasy package

Subpackages