ESA CCI Toolbox (Cate) Python package, API and CLI.
setup.py- main build script to be run with Python 3.5
cate/- main package and production code
test/- test package and test code
doc/- documentation in Sphinx/RST format
Installation from Sources
We recommend installing Cate into an isolated Python 3 environment, because this approach avoids clashes with existing versions of Cate's 3rd-party Python package requirements. For example, using (Miniconda or Anaconda) which will usually also avoid platform-specific issues caused by module native binaries.
The first step is to clone latest Cate code and step into the check out directory:
$ git clone https://github.com/CCI-Tools/cate.git $ cd cate
Conda is the package manager used by the Miniconda or Anaconda Python distributions.
Creating a new Python environment for Cate will require around 2.2 GB disk space on Linux/Darwin and and 1.2
GB on Windows. To create a new Conda environment
cate-env in your Anaconda/Miniconda installation directory, type:
$ conda env create
If you want the environment to be installed in another location, e.g. due to disk space limitations, type:
$ conda env create --prefix some/other/location/for/cate
Next step is to activate the new environment. On Linux/Darwin type:
$ source activate cate-env
In case you used another location use it instead of the name
Windows users can omit the
source command and just type
> activate cate-env
You can now safely install Cate sources into the new
(cate) $ python setup.py install
Using Standard Python
If you run it with the standard CPython installation, make sure you use a 64-bit version. Cate relies on new Python language features and therefore requires Python 3.5+.
Cate can be run from sources directly, once the following module requirements are resolved:
The most up-to-date list of module requirements is found in the project's
To install Cate into an existing Python 3.5+ environment just for the current user, use
$ python3 setup.py install --user
To install Cate for development and for the current user, use
$ python3 setup.py develop --user
There is a known issue on Windows when installing into an existing Python environment. Installation may
fail due to an unresolved dependency to the
h5py package, which expects pre-installed
HDF-5 C-libraries to be present on your computer. You may get around this by pre-installing the Cate dependencies (which you'll find in
on your own, for example by using Christoph Gohlke's
Unofficial Windows Binaries for Python Extension Packages.
For Linux and MacOS environment, there may be an issue when starting a webapi due to unavailable json-c shared object file. When this happens, please downgrade the json-c library by running the following command inside cate-env:
$ conda install -c conda-forge json-c=0.12.1
To test the installation, first run the Cate command-line interface. Type
$ cate -h
IPython notebooks for various Cate use cases are on the way, they will appear in the project's notebooks folder.
To use them interactively, you'll need to install Jupyter and run its Notebook app:
$ conda install jupyter $ jupyter notebook
notebooks folder and select a use case.
There is a dedicated repository cate-conda which provides scripts and configuration files to build Cate's Conda packages and a stand-alone installer.
Contributors are asked to read and adhere to our Developer Guide.
For unit testing we use
pytest and its coverage plugin
To run the unit-tests with coverage, type
$ export NUMBA_DISABLE_JIT=1 $ py.test --cov=cate test
We need to set environment variable
NUMBA_DISABLE_JIT to disable JIT compilation by
numba, so that
coverage reaches the actual Python code. We use Numba's JIT compilation to speed up numeric Python
number crunching code.
Other recognized environment variables to customize the unit-level tests are
CATE_DISABLE_WEB_TESTS=1 CATE_DISABLE_PLOT_TESTS=1 CATE_DISABLE_GEOPANDAS_TESTS=1 CATE_DISABLE_CLI_UPDATE_TESTS=1
Generating the Documentation
$ cd cate $ conda env create -f environment-rtd.yml
To regenerate the HTML docs, type
$ cd doc $ make html
The CCI Toolbox is distributed under terms and conditions of the MIT license.