Metadata-Version: 2.1
Name: emsarray
Version: 0.5.0
Summary: xarray extension that supports multiple geometry conventions
Author: "Coastal Environmental Modelling team, Oceans and Atmosphere, CSIRO"
Author-email: "coasts@csiro.au"
License: "BSD-3-Clause"
Project-URL: Documentation, https://emsarray.readthedocs.io/
Project-URL: Release notes, https://emsarray.readthedocs.io/en/stable/releases/0.5.0/
Project-URL: Source, https://github.com/csiro-coasts/emsarray/
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bottleneck >=1.3
Requires-Dist: geojson >=2.5.0
Requires-Dist: importlib-metadata >=4.0.0
Requires-Dist: netcdf4 >=1.5.3
Requires-Dist: numpy >=1.22.0
Requires-Dist: packaging >=21.3
Requires-Dist: shapely >=2.0.0
Requires-Dist: pyshp >=2.3.0
Requires-Dist: xarray[parallel] >=0.21.0
Provides-Extra: complete
Requires-Dist: cartopy >=0.21.1 ; extra == 'complete'
Requires-Dist: matplotlib >=3.5.2 ; extra == 'complete'
Requires-Dist: pykdtree >=1.3.5 ; extra == 'complete'
Requires-Dist: pooch >=1.3.0 ; extra == 'complete'
Provides-Extra: docs
Requires-Dist: sphinx ~=6.2.1 ; extra == 'docs'
Requires-Dist: sphinx-book-theme ~=1.0.1 ; extra == 'docs'
Requires-Dist: livereload ~=2.6.3 ; extra == 'docs'
Provides-Extra: plot
Requires-Dist: cartopy >=0.21.1 ; extra == 'plot'
Requires-Dist: matplotlib >=3.5.2 ; extra == 'plot'
Requires-Dist: pykdtree >=1.3.5 ; extra == 'plot'
Provides-Extra: testing
Requires-Dist: cartopy >=0.21.1 ; extra == 'testing'
Requires-Dist: matplotlib >=3.5.2 ; extra == 'testing'
Requires-Dist: pykdtree >=1.3.5 ; extra == 'testing'
Requires-Dist: pooch >=1.3.0 ; extra == 'testing'
Requires-Dist: sphinx ~=6.2.1 ; extra == 'testing'
Requires-Dist: sphinx-book-theme ~=1.0.1 ; extra == 'testing'
Requires-Dist: livereload ~=2.6.3 ; extra == 'testing'
Requires-Dist: pytest ; extra == 'testing'
Requires-Dist: pytest-cov ; extra == 'testing'
Requires-Dist: mypy ; extra == 'testing'
Requires-Dist: pandas-stubs ; extra == 'testing'
Requires-Dist: types-pytz ; extra == 'testing'
Requires-Dist: flake8 ; extra == 'testing'
Requires-Dist: isort ; extra == 'testing'
Requires-Dist: tox ; extra == 'testing'
Provides-Extra: tutorial
Requires-Dist: pooch >=1.3.0 ; extra == 'tutorial'

# emsarray

[![Binder](https://mybinder.org/badge_logo.svg)][emsarray-binder]
[![Documentation Status](https://readthedocs.org/projects/emsarray/badge/?version=latest)](https://emsarray.readthedocs.io/en/latest/?badge=latest)
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/emsarray.svg)](https://anaconda.org/conda-forge/emsarray)

The `emsarray` package provides a common interface
for working with the many model geometry conventions used at CSIRO.
It enhances [`xarray`][xarray] Datasets
and provides a set of common operations for manipulating datasets.

To use, open the dataset using the `emsarray.open_dataset()` function
and use the `dataset.ems` attribute:

```python
import emsarray
from shapely.geometry import Point

dataset = emsarray.tutorial.open_dataset('gbr4')
capricorn_group = Point(151.869, -23.386)
point_data = dataset.ems.select_point(capricorn_group)
```

Some methods take a DataArray as a parameter:

```python
# Plot the sea surface temperature for time = 0
temp = dataset['temp'].isel(time=0, k=-1)
dataset.ems.plot(temp)
```

![Plot of sea surface temperature from the GBR4 example file](docs/_static/images/gbr4_temp.png)

A number of operations provide further functionality to manipulate datasets,
export geometry, and select subsets of data:

```python
from emsarray.operations import geometry
geometry.write_geojson(dataset, './gbr4.geojson')
geometry.write_shapefile(dataset, './gbr4.shp')
```

## Links

* [Source code on Github][emsarray-source-code]
* [Documentation on Read The Docs][emsarray-documentation]
* [emsarray on PyPI][emsarray-pypi]
* [emsarray on conda-forge][emsarray-conda-forge]

## Examples

Examples of using `emsarray` are available in the [emsarray-notebooks][emsarray-notebooks] repository.
You can [explore these notebooks online][emsarray-binder] with Binder.


## Developing

To get set up for development, make a virtual environment and install the dependencies:

```shell
$ python3 -m venv
$ source venv/bin/activate
$ pip install --upgrade pip>=21.3
$ pip install -e . -r continuous-integration/requirements.txt
```

## Tests

To run the tests, install and run `tox`:

```shell
$ python3 -m venv
$ source venv/bin/activate
$ pip install --upgrade pip>=21.3 tox
$ tox
```

## Documentation

[The documentation for the current stable version of emsarray is available on Read The Docs][emsarray-documentation].

To build the documentation, install the development requirements as above and invoke Sphinx:

```shell
$ make -C docs/ html
```

While updating or adding to the documentation,
run the `live` target to automatically rebuild the docs whenever anything changes.
This will serve the documentation via a [`livereload`][livereload] server.

```shell
$ make -C docs/ live
```

You can the view the docs at <http://localhost:5500>

[emsarray-binder]: https://mybinder.org/v2/gh/csiro-coasts/emsarray-notebooks/HEAD
[emsarray-conda-forge]: https://anaconda.org/conda-forge/emsarray/
[emsarray-documentation]: https://emsarray.readthedocs.io
[emsarray-notebooks]: https://github.com/csiro-coasts/emsarray-notebooks
[emsarray-pypi]: https://pypi.org/project/emsarray/
[emsarray-source-code]: https://github.com/csiro-coasts/emsarray
[livereload]: https://livereload.readthedocs.io/en/latest/
[xarray]: https://xarray.pydata.org/
