Metadata-Version: 2.1
Name: emsarray
Version: 0.3.0
Summary: xarray extension that supports EMS model formats
Author: "Coastal Environmental Modelling team, Oceans and Atmosphere, CSIRO"
Author-email: "coasts@csiro.au"
License: "CSIRO Open Source Software Licence Agreement (variation of the BSD / MIT License)"
Project-URL: Documentation, https://emsarray.readthedocs.io/
Project-URL: Release notes, https://emsarray.readthedocs.io/en/stable/releases/
Project-URL: Source, https://github.com/csiro-coasts/emsarray/
Description-Content-Type: text/markdown
License-File: LICENCE
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.18.0)
Requires-Dist: packaging (>=21.3)
Requires-Dist: shapely (>=1.8.0)
Requires-Dist: pyshp (>=2.3.0)
Requires-Dist: xarray[parallel] (>=0.18.2)
Provides-Extra: complete
Requires-Dist: cartopy (>=0.20.0) ; extra == 'complete'
Requires-Dist: matplotlib (>=3.4.3) ; extra == 'complete'
Requires-Dist: pykdtree (>=1.2.2) ; extra == 'complete'
Requires-Dist: pooch (>=1.3.0) ; extra == 'complete'
Provides-Extra: docs
Requires-Dist: sphinx (~=4.3.1) ; extra == 'docs'
Requires-Dist: sphinx-book-theme (~=0.3.2) ; extra == 'docs'
Requires-Dist: livereload (~=2.6.3) ; extra == 'docs'
Provides-Extra: plot
Requires-Dist: cartopy (>=0.20.0) ; extra == 'plot'
Requires-Dist: matplotlib (>=3.4.3) ; extra == 'plot'
Requires-Dist: pykdtree (>=1.2.2) ; extra == 'plot'
Provides-Extra: testing
Requires-Dist: cartopy (>=0.20.0) ; extra == 'testing'
Requires-Dist: matplotlib (>=3.4.3) ; extra == 'testing'
Requires-Dist: pykdtree (>=1.2.2) ; extra == 'testing'
Requires-Dist: pooch (>=1.3.0) ; extra == 'testing'
Requires-Dist: sphinx (~=4.3.1) ; extra == 'testing'
Requires-Dist: sphinx-book-theme (~=0.3.2) ; 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 formats 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')
```

## 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

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-notebooks]: https://github.com/csiro-coasts/emsarray-notebooks
[emsarray-binder]: https://mybinder.org/v2/gh/csiro-coasts/emsarray-notebooks/HEAD
[xarray]: https://xarray.pydata.org/
[livereload]: https://livereload.readthedocs.io/en/latest/
