Python and Python Packages¶

The ECCO Python tutorial is compatible with Python 3. It relies on several packages including ecco_v4-py which include codes to facilitate loading, plotting, and performing calculations on ECCOv4 state estimate fields.

Why Python?¶

Python is an easy to learn open source programming language. In addition to the standard language library, there are thousands of free third-party modules (code libraries) available on code repositories such as Python Package Index (PyPI), _Conda and Conda Forge. Unlike commerical numerical computing environments like Matlab and IDL, Python is free for everyone to use. In addition, Python code can be run on multiple platforms such as Windows, Linux, and OS X.

Here are some links to help you learn more about Python.

Installing Python¶

There are several ways of installing Python on your machine. You can install compiled binaries directly from the Python website, or one can install via a package manager such as Anaconda or Miniconda. I personally find the Anaconda or Miniconda route to be simplest.

Anaconda¶

For scientific computing, the Anaconda Python distribution is quite convenient because it comes with a large collection of useful modules, a good open source IDE, Spyder., and the ability to open and execute Jupyter Notebooks

The latest installers for the Anaconda Distribution can be found on the Anaconda website

Downloading the ecco_v4_py Python Package¶

The ecco_v4_py package is a library of routines for analyzing the ECCO the Version 4 state estimate. The latest version can always be found on our github repository

Below are three options or installing the ecco_v4_py Python package.

Attention

Use only one of the options below!

Option 1: Clone into the repository using git (recommended)¶

Cloning into the ecco_v4_py repository using git is recommended because

you can easily see and modify source code
you share your improvements with the community.

To use git to clone into the project simply run the following commands (in the example below the Python files will go into ~/ECCOv4-py/)

> mkdir ~/ECCOv4-py
> cd ~/ECCOv4-py
> git clone https://github.com/ECCO-GROUP/ECCOv4-py.git

Option 2: Download the repository using git (less recommended)¶

This method downloads the source code but if you make changes it is harder to share those changes with the community using git.

> mkdir ~/ECCOv4-py
> cd ~/ECCOv4-py
> wget https://github.com/ECCO-GROUP/ECCOv4-py/archive/master.zip
> unzip master.zip
> rm master.zip

Option 3: Use the conda package manager (less recommended)¶

ecco_v4_py is available via the conda package management system (see https://anaconda.org/conda-forge/ecco_v4_py ) Installing using conda should install all of the required dependencies.

conda install ecco_v4_py

If for some reason the above command returns an error, include the -c option to point to the channel where the package is found (conda-forge).

conda install -c conda-forge ecco_v4_py

Option 4: Use the pip package manager (not at all recommended)¶

ecco_v4_py is available via the pip package manager (see https://pypi.org/project/ecco-v4-py/ ) Before using pip, you must first install the PROJ and GEOS libraries (see next section).

pip install ecco_v4_py

Installing Dependencies¶

Danger

While conda is recommended because it automatically installs the required the GEOS (Geometry Engine) and PROJ (generic coordinate transformation software) binary libraries, you can install those libraries yourself.

Instructions for installing the GEOS library can be found on the geos website.

Instructions for installing the PROJ library can be found on the proj website.

Some users have reported difficulties installing these libraries on their platforms. For that reason, we recommend using Options 1-3.

Using the ecco_v4_py in your programs¶

Assuming you downloaded the ecco_v4_py routines to /home/username/ECCOv4-py then simply add these three lines to the top of your Python programs (or Jupyter Notebooks)

import sys
sys.path.append('/home/username/ECCOv4-py')
import ecco_v4_py as ecco

If you you installed the package using pip then the ecco_v4_py library will be automatically installed and will be ready to import into your Python program via the following commands:

import ecco_v4_py as ecco