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 plottingudunits2
, viacfunits <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