Input/Output

Export and import data from other sources and formats.

Xarray

barotropic.io.as_dataset(states, fields=('u', 'v'), concat_dim='time')

Export a collection of states to an xarray dataset.

Parameters:

• states (iterable of State) – states to include in the created dataset.

• fields (str | iterable | dict) – fields extracted and placed in the dataset. If a name or list of names is specified, the correspondingly named attributes of the provided states are extracted. Alternatively, a mapping from names to attributes or callables can be specified. Fields are then extracted by accessing the attribute or calling the provided callable on all states and placed in the dataset under the names specified in the mapping.

• concat_dim (str) – The dimension used to index the fields in the output dataset. By default, the time dimension is used as an index. Alternatively, a different dimension can be specified. If all states have a corresponding attribute, the attribute’s values are used to construct a coordinate. Otherwise the coordinate is generated with numpy.arange().

Returns:

xarray.Dataset

Note

Export of spectral fields is currently not supported.

Requrires xarray.

>>> states
<StateList with 9 states>
>>> bt.io.as_dataset(states, fields={ "avo": "avo", "ubar": lambda s: s.u.mean(axis=bt.ZONAL) })
<xarray.Dataset>
Dimensions:    (latitude: 73, longitude: 144, time: 9)
Coordinates:
  * latitude   (latitude) float64 ...
  * longitude  (longitude) float64 ...
  * time       (time) float64 ...
Data variables:
    avo        (time, latitude, longitude) float32 ...
    ubar       (time, latitude) float32 ...

An empty list of states returns an empty dataset:

>>> bt.io.as_dataset([])
<xarray.Dataset>
Dimensions:  ()
Data variables:
    *empty*

Added in version 3.1.

See also

StateList.as_dataset().

barotropic.io.from_dataset(ds, names=None, grid_kwargs=None, time_fill=0)

Turn an xarray dataset into a collection of states.

Parameters:

• ds (Dataset | DataArray) – Input data containing the field(s) from which to construct the State objects.

• names (dict | None) – Name overrides for variable detection. Expects a mapping of reference variable names to actual variable names as occurring in the datset. See below for the list of reference names.

• grid_kwargs (dict | None) – Keyword arguments given to the Grid constructor.

• time_fill (number | datetime) – Fill value for State.time if a value cannot be extracted from the dataset.

Returns:

StateList with all dimensions (other than longitude and latitude) flattened.

The built-in variable detection recognizes the following names:

Init.	Ref.	Detected Variable Names	Description
	lon	longitude, lon	longitude coordinate (mandatory)
	lat	latitude, lat	latitude coordinate (mandatory)
	time	time	time coordinate for State.time (optional)
A	u	u, ugrd, eastward_wind	zonal wind component
A	v	v, vgrd, northward_wind	meridional wind component
B	vo	vo, relv, vorticity, relative_vorticity	relative vorticity
C	avo	avo, absv, absolute_vorticity, pv	absolute vorticity (barotropic PV)

If the associated variable(s) are detected, the output State objects are constructed with the following order of priority:

1. From horizontal wind components (u, v), using State.from_wind().

2. From relative vorticity (vo), using State.from_vorticity().

3. From absolute vorticity (avo), using the default State constructor.

Only the first available construction is used. To enforce a specific initialization path, only supply the variable(s) required for that construction. The reference names can be mapped to custom variable names via the names argument.

Note

While pv is used throughout this package to refer to absolute vorticity, it may refer to Ertel or QG PV in other datasets. Therefore, names explicitly referring to absolute vorticity are given priority in the detection.

If the dimensions of the initialization fields do not end with latitude and longitude, transpose the data first.

>>> ds
<xarray.Dataset>
Dimensions:    (time: 6, latitude: 181, longitude: 360)
Coordinates:
  * longitude  (longitude) float32 0.0 1.0 2.0 3.0 ... 356.0 357.0 358.0 359.0
  * latitude   (latitude) float32 90.0 89.0 88.0 87.0 ... -88.0 -89.0 -90.0
  * time       (time) datetime64[ns] ...
Data variables:
    u          (time, latitude, longitude) float32 ...
    v          (time, latitude, longitude) float32 ...
>>> bt.io.from_dataset(ds)
<StateList with 6 states>

Added in version 3.1.