Installing#

The easiest way of installing emsarray is using Conda. emsarray is published on the conda-forge channel. You can install it in your Conda environment with:

$ conda install -c conda-forge emsarray

This will install emsarray with all its optional dependencies. Alternately you install only the core dependencies by installing the emsarray-core package instead.

If you prefer, emsarray can be installed using pip.

$ pip install emsarray

Before installing emsarray via pip you have to ensure that the non-Python dependencies are met. There are some optional dependencies for emsarray. You can install these by choosing some extras at install time.

Dependencies#

Most of the dependencies of emsarray are installable via pip, however some dependencies require non-Python components that must be installed using some other method. emsarray uses the following libraries that can not be installed via pip:

  • geos, via cartopy. This is used for plotting

  • udunits2, via

  • cfunits <https://ncas-cms.github.io/cfunits/installation.html>. This is used for plotting.

These can be installed via your package manager or via conda. Installing from conda is the recommended approach as these packages are often more up-to-date than the system packages and it guarantees that compatible versions are installed.

$ conda create -n my-env
$ conda activate my-env
$ conda install cartopy cfunits

If geos is installed using your system package manager, and cartopy is installed via pip, you must ensure that you install versions of cartopy that are compatible with geos. pip will not check for these version constraints for you. A version mismatch between the Python and non-Python libraries can lead to the installation failing, or Python crashing when calling cartopy functions.

Building#

On any computer, run the following commands from the root of the emsarray source directory to build a package:

$ python3 -m venv venv
$ source venv/bin/activate
$ pip3 install --upgrade pip build
$ rm -rf dist/
$ python3 -m build

Two new files will be created in the dist/ directory. This is the Python package you can install in other environments. Use either one of them when installing emsarray in your chosen environment:

$ cd /path/to/other-project
$ python3 -m venv venv
$ source venv/bin/activate
$ pip3 install /path/to/emsarray/dist/emsarray-*-py3-none-any.whl

Extras#

When installed via pip, emsarray can be installed with “extras”. These extra packages are optional.

For conda installs, the emsarray package contains all the extras and is equivalent to emsarray[complete]. emsarray-core is equivalent to emsarray without any extras.

plot#

$ pip install emsarray[plot]

Allows emsarray to produce plots, using Convention.plot().

tutorial#

$ pip install emsarray[tutorial]

Installs packages required to access the tutorial datasets, accessible via the emsarray.tutorial.open_dataset() method.

complete#

$ pip install emsarray[complete]

Includes all extras. Use this for the complete emsarray experience.

testing#

The testing extras are intended for development. When setting up a development environment for emsarray, clone the repository and install emsarray in editable mode with the testing extras:

$ pip install -e .[testing]
$ pytest  # Run the test suite
$ make -C docs html  # Build the docs