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.
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!'}>
- 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)
- 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
- meta
- name
- class speasy.Dataset(name: str, variables: dict, meta: dict)[source]
Bases:
SpeasyProduct
A Dataset is basically a collection of SpeasyVariables
- meta
- name
- 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
Notes
This class support the same operations as a speasy.common.datetime_range.DateTimeRange.
- Attributes:
- start_timedatetime.datetime
- stop_timedatetime.datetime
- metadict
Additional event data
- 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 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
- 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)
Subpackages
- speasy.config package
- speasy.core package
AllowedKwargs
EnsureUTCDateTime
all_of_type()
datetime64_to_epoch()
deprecation()
epoch_to_datetime64()
fix_name()
is_collection()
listify()
make_utc_datetime()
make_utc_datetime64()
mkdir()
pack_kwargs()
progress_bar()
- Subpackages
- Submodules
- speasy.inventories package
- speasy.plotting package
- speasy.products package
Catalog
DataContainer
DataContainer.dtype
DataContainer.empty_like()
DataContainer.from_dictionary()
DataContainer.is_time_dependent
DataContainer.meta
DataContainer.name
DataContainer.nbytes
DataContainer.ndim
DataContainer.ones_like()
DataContainer.replace_val_by_nan()
DataContainer.reserve_like()
DataContainer.reshape()
DataContainer.shape
DataContainer.to_dictionary()
DataContainer.unit
DataContainer.unit_applied()
DataContainer.values
DataContainer.view()
DataContainer.zeros_like()
Dataset
Event
SpeasyVariable
SpeasyVariable.axes
SpeasyVariable.axes_labels
SpeasyVariable.columns
SpeasyVariable.copy()
SpeasyVariable.dtype
SpeasyVariable.empty_like()
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.shape
SpeasyVariable.time
SpeasyVariable.to_astropy_table()
SpeasyVariable.to_dataframe()
SpeasyVariable.to_dictionary()
SpeasyVariable.unit
SpeasyVariable.unit_applied()
SpeasyVariable.values
SpeasyVariable.view()
SpeasyVariable.zeros_like()
TimeTable
VariableAxis
VariableTimeAxis
- Submodules
- speasy.signal package
- speasy.webservices package