gsw-xarray: Wrapper for gsw that adds CF attributes#

CI Status Documentation Status pypi package conda forge

gsw-xarray is a wrapper for gsw python that will add CF attributes to xarray.DataArray outputs. It is meant to be a drop in wrapper for the upstream GSW-Python library and will only add these attributes if one argument to a function is an xarray.DataArray.

You can find the documentation on gsw-xarray.readthedocs.io.

Usage#

import gsw_xarray as gsw

# Create a xarray.Dataset
import numpy as np
import xarray as xr
ds = xr.Dataset()
id = np.arange(3)
ds['id'] = xr.DataArray(id, coords={'id':id})
ds['CT'] = ds['id'] * 10
ds['CT'].attrs = {'standard_name':'sea_water_conservative_temperature'}
ds['SA'] = ds['id'] * 0.1 + 34
ds['SA'].attrs = {'standard_name':'sea_water_absolute_salinity'}

# Apply gsw functions
sigma0 = gsw.sigma0(SA=ds['SA'], CT=ds['CT'])
print(sigma0.attrs)

Outputs

{'standard_name': 'sea_water_sigma_t', 'units': 'kg/m^3'}

Don’t worry about usage with non xarray array objects, just use in all places you would the upstream library:

sigma0 = gsw.sigma0(id * 10, id * 0.1 + 34)
print(type(sigma0), sigma0)

Outputs

<class 'numpy.ndarray'> [-5.08964499  2.1101098   9.28348219]

We support (and convert the unit if necessary) the usage of pint.Quantities and the usage of xarray wrapped Quantities. Support for pint requires the installation of two optional dependencies: pint and pint-xarray. If all the inputs to a gsw function are Quantities, the returned object will also be a Quantity belonging to the same UnitRegistry.

Warning

Quantities must all belong to the same pint.UnitRegistry, a ValueError will be thrown if there are mixed registries.

Warning

If one input is a Quantity, all inputs must be Quantities (and/or xarray wrapped Quantities), except for the axis and interp_method arguments. For mixed usage of Quantities and non Quantities, a ValueError will be thrown.

import pint_xarray
import gsw_xarray as gsw

# Create a xarray.Dataset
import numpy as np
import xarray as xr
ds = xr.Dataset()
id = np.arange(3)
ds['id'] = xr.DataArray(id, coords={'id':id})
ds['CT'] = ds['id'] * 10
# make sure there are unit attrs this time
ds['CT'].attrs = {'standard_name':'sea_water_conservative_temperature', 'units': 'degC'}
ds['SA'] = ds['id'] * 0.1 + 34
ds['SA'].attrs = {'standard_name':'sea_water_absolute_salinity', 'units': 'g/kg'}

# use the pint accessor to quantify things
ds = ds.pint.quantify()

# Apply gsw functions
sigma0 = gsw.sigma0(SA=ds['SA'], CT=ds['CT'])
# outputs are now quantities!
print(sigma0)

Outputs

<xarray.DataArray 'sigma0' (id: 3)>
<Quantity([27.17191038 26.12820162 24.03930887], 'kilogram / meter ** 3')>
Coordinates:
  * id       (id) int64 0 1 2
Attributes:
    standard_name:  sea_water_sigma_t

The usage of xarray wrapped Quantities is not required, you can use pint directly (though the pint-xarray dep still needs to be installed).

import gsw_xarray as gsw
import pint
ureg = pint.UnitRegistry()
SA = ureg.Quantity(35, ureg("g/kg"))
CT = ureg.Quantity(10, ureg.degC)
sigma0 = gsw.sigma0(SA=SA, CT=CT)
print(sigma0)

Outputs

26.824644457868317 kilogram / meter ** 3

As gsw-xarray converts arguments to the proper unit when Quantities are used, we can e.g. use the temperature in Kelvin:

CT = ureg.Quantity(10, ureg.degC).to('kelvin')
sigma0 = gsw.sigma0(SA=SA, CT=CT)
print(sigma0)

Outputs

26.824644457868317 kilogram / meter ** 3

Note

If you do not wish to use the unit conversion ability, you need to pass dequantified Quantities (e.g. da.pint.dequantify() for pint-xarray or arg.magnitude for pint.Quantity).

Warning

On the opposite, gsw-xarray will not check the units if non Quantity arguments are used. If you wish to use unit conversion, please pass quantified arguments (if your xarray.Dataset / xarray.DataArray has the ‘units’ attribute, you can use da.pint.quantify())

Note

We recommend that you use the cf-xarray registry for units, as it implements geophysical units as degree_north, degrees_north, etc. gsw-xarray internally uses degree_north and degree_east for latitude and longitude unit names. If they are not found in the unit registry, they will be replaced by degree.

The function gsw.SP_from_SK uses part per thousand for SK. ‘ppt’ is already used for picopint, so the expected unit is replaced by ‘1’.

Installation#

Pip#

pip install gsw-xarray

Conda#

Inside a conda environment: conda install -c conda-forge gsw-xarray.

Pipenv#

Inside a pipenv environment: pipenv install gsw-xarray.

Contributor guide#

All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. If you notice a bug or are missing a feature, fell free to open an issue in the GitHub issues page.

In order to contribute to gsw-xarray, please fork the repository and submit a pull request. A good step by step tutorial for starting with git can be found in the xarray contributor guide. A main difference is that we do not use conda as python environment, but poetry.

Set up the environment#

You will first need to install poetry. Then go to your local clone of gsw-xarray and launch installation:

cd /path/to/your/gsw-xarray
poetry install

You can then activate the environment by launching a shell within the virtual environment:

poetry shell

You can check that the tests pass locally:

pytest gsw_xarray/tests

Release (for maintainers only)#

TODO…

For the specific list of what attributes are added for each function, see the Added Attributes and Expected Input Units section.

Contents#

Indices and tables#