Python and Python Packages¶
Our 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.
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 the Python Package Index (PyPI). Unlike commerical numerical computing environments like Matlab and IDL, Python is free for everyone to use. In addition, Python code can be run on just any platform whether Windows, Linux, or OS X.
Here are some links to help you learn more about Python.
Installing Python and the Anaconda Distribution¶
Python code can be written in any text editor and run from the command line. Third-party modules can be manually installed from the command line using the pip package manager.
Python code can also be written and executed in an interactive environment (integrated development environment, IDE) similar to the Matlab console. 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
Installing Required Python Packages¶
After installing Anaconda the following packages must be installed: netcdf4, cartopy, pyresample, xarray, xmitgcm, xgcm
Below are two options or installing these packages. PICK ONE!
Option 1: Conda¶
Conda is recommended because it automatically installs the GEOS (Geometry Engine, Open Source) library which is needed to make projection plots.
conda install geos conda install cmocean conda install -c conda-forge pyresample conda install -c conda-forge xarray dask netCDF4 bottleneck conda install -c conda-forge xmitgcm conda install -c conda-forge xgcm conda install -c conda-forge cartopy
Option 2: pip alone (not recommended)¶
The Python module Cartopy requires the GEOS (Geometry Engine, Open Source) library. Instructions for installing this library can be found on the geos website. Some users have reported difficulties installing GEOS libraries on their platforms. For that reason, we recommend using Conda (Option 1).
pip install netcdf4 pip install pyresample pip install cartopy pip install xarray pip install xmitgcm pip install xgcm pip install cmocean
Downloading the ecco_v4_py Python Package¶
The ecco_v4_py package is a library of routines that are helpful for analyzing the ECCO v4 state estimate. It is stored on the github repository
Below are three options or installing the ecco_v4_py Python package.
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 the ecco_v4_py source code
- you can improve the source code and 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 (not recommended)¶
This method gets you the source code but if you make changes it is harder to share those changes with the community.
> mkdir ~/ECCOv4-py > cd ~/ECCOv4-py > wget https://github.com/ECCO-GROUP/ECCOv4-py/archive/master.zip > unzip master.zip > rm master.zip
Of course you may want to use this method if you don’t have access to git.
Option 3: Use the pip Python package tool (not recommended)¶
If you use pip to install the ecco_v4_py package the source code will be installed in your Python library directory from https://pypi.org/project/ecco-v4-py/. This method is OK if you don’t plan to look at or modify the library code.
pip install ecco_v4_py
Using the ecco_v4_py Python Package in your programs¶
If you use Options 1 or 2 to download the ecco_v4_py source code then you must tell Python the location of the files before Python can it. This is easy, you just you just have to remember to do it at the top of all of 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 used Method 3 (pip install) 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