swarmpal.io

class swarmpal.io.PalDataItem(fetcher: DataFetcherBase)

Bases: object

An Item (i.e. dataset) that will be stored within a PalData object

Intended use is through the .from_… creator tools

Parameters:

fetcher (DataFetcherBase) –

Examples

>>> from swarmpal.io import PalDataItem
>>>
>>> # Create the item with a configuration
>>> params = dict(
>>>     collection="SW_OPER_MAGA_LR_1B",
>>>     measurements=["F", "B_NEC"],
>>>     start_time="2016-01-01T00:00:00",
>>>     end_time="2016-01-02T00:00:00",
>>>     server_url="https://vires.services/ows",
>>> )
>>> item = PalDataItem.from_vires(**params)
>>> # "Initialise" - triggers the expensive part, fetching the data
>>> item.initialise()
>>> # Data is available as an xarray.Dataset
>>> item.xarray
>>> # or as a DataTree
>>> item.datatree

property analysis_window: tuple[datetime]

The start and end times of the analysis window (considering optional padding

property dataset_name: str

Name of the dataset, used as the datatree label

property datatree: DataTree

A datatree containing the dataset labelled with the dataset name

static from_file(filename: PathLike | None = None, group: str | None = None, **params) → PalDataItem

Create a PalDataItem from a file

Parameters:

• filename (PathLike) – Path to the (netCDF) file to load

• group (str) – Group name within the (netCDF) file

Return type:

PalDataItem

static from_hapi(**params) → PalDataItem

Create PalDataItem from HAPI source

Parameters:

• server (str) –

• dataset (str) –

• parameters (str) –

• start (str) –

• stop (str) –

• options (dict) –

• pad_times (tuple[timedelta]) – This is handled specially by SwarmPAL and not passed to hapiclient

static from_manual(xarray_dataset: Dataset | None = None, **params) → PalDataItem

Create a PalDataItem manually from an existing xarray Dataset

Parameters:

xarray_dataset (Dataset) – An existing xarray.Dataset

Return type:

PalDataItem

static from_vires(**params) → PalDataItem

Create PalDataItem from VirES source

Parameters:

• collection (str) –

• measurements (list[str]) –

• start_time (str | datetime) –

• end_time (str | datetime) –

• models (list[str]) –

• auxiliaries (list[str]) –

• sampling_step (str) –

• filters (list[str]) –

• options (dict) –

• server_url (str) – defaults to “https://vires.services/ows”

• pad_times (tuple[timedelta]) – This is handled specially by SwarmPAL and not passed to viresclient

initialise()

Trigger the fetching of the data and attach PAL metadata

property magnetic_models: dict

Dictionary of model names and details

property xarray: Dataset | None

xarray.Dataset containing the data, generated if not already present

class swarmpal.io.PalDataTreeAccessor(datatree)

Bases: object

Provide custom attributes and methods on XArray DataTrees for SwarmPAL functionality.

See e.g. Unidata/MetPy

apply(palprocess: PalProcess) → DataTree

property magnetic_model_name: str

Model name if one and only one has been set

property magnetic_model_names: list[str]

List of the model names used in the dataset

magnetic_residual(model: str = '') → DataArray

Magnetic data-model residual in NEC frame

property pal_meta: dict

class swarmpal.io.PalProcess(config: dict | None = None, active_tree: str = '/', inplace: bool = True)

Bases: ABC

Abstract class to define processes to act on datatrees

property active_tree: str

Defines which branch of the datatree will be used

property config: dict

Dictionary that configures the process behaviour

abstract property process_name: str

abstract set_config(**kwargs) → None

swarmpal.io.create_paldata(*paldataitems: PalDataItem, **paldataitems_kw: PalDataItem) → DataTree

Generates a Datatree from a number of PalDataItems

Returns:

A Datatree containing Datasets defined from each PalDataItem

Return type:

Datatree

Examples

>>> from swarmpal.io import create_paldata, PalDataItem
>>>
>>> # Parameters to control a particular data request
>>> data_params = dict(
>>>     collection="SW_OPER_MAGA_LR_1B",
>>>     measurements=["B_NEC"],
>>>     models=["IGRF"],
>>>     start_time="2016-01-01T00:00:00",
>>>     end_time="2016-01-01T03:00:00",
>>>     server_url="https://vires.services/ows",
>>>     options=dict(asynchronous=False, show_progress=False),
>>> )
>>> # Create the datatree from a list of items
>>> data = create_paldata(
>>>     PalDataItem.from_vires(**data_params)
>>> )
>>> # Create the datatree from labelled items
>>> data = create_paldata(
>>>     one=PalDataItem.from_vires(**data_params),
>>>     two=PalDataItem.from_vires(**data_params),
>>> )