Installation

Installation#

Prerequisites#

  1. Familiarity with xarray

    We highly recommend visiting the xarray tutorial and xarray documentation pages if you aren’t familiar with xarray.

  2. xCDAT is distributed on the Conda platform, which is available through Anaconda and Miniforge.

    We recommend following the Quick command line install steps in the Miniforge docs to install Miniforge. Those steps are also provided below for Unix-like platforms (macOS & Linux).

    >>> # macOS
>>> curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
>>> bash Miniforge3-$(uname)-$(uname -m).sh
>>> rm -rf Miniforge3-$(uname)-$(uname -m).sh

    >>> # Linux
>>> wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
>>> bash Miniforge3-$(uname)-$(uname -m).sh
>>> rm -rf Miniforge3-$(uname)-$(uname -m).sh

    Then follow the instructions for installation. To have conda added to your path you will need to type yes in response to "Do you wish the installer to initialize Miniforge3 by running conda init?" (we recommend that you do this). Note that this will modify your shell profile (e.g., ~/.bashrc) to add conda to your path.

    Note

    After installation completes you may need to type bash to restart your shell (if you use bash). Alternatively, you can log out and log back in.

  3. Add the conda-forge channel.

    xCDAT is hosted on the conda-forge channel, which is the standard channel for most scientific Python packages. By default, Miniforge is pre-configured to use conda-forge. You can also add the channel manually by running:

    >>> conda config --add channels conda-forge
>>> conda config --set channel_priority strict

Instructions#

  1. Create a Conda environment from scratch with xcdat (conda create)

    We recommend using the Conda environment creation procedure to install xcdat. The advantage with following this approach is that Conda will attempt to resolve dependencies for compatibility.

    To create an xcdat Conda environment, run:

    >>> conda create -n <ENV_NAME> -c conda-forge xcdat
>>> conda activate <ENV_NAME>

  2. Install xcdat in an existing Conda environment (conda install)

    You can also install xcdat in an existing Conda environment, granted that Conda is able to resolve the compatible dependencies.

    >>> conda activate <ENV_NAME>
>>> conda install -c conda-forge xcdat

  3. [Optional] Some packages that are commonly used with xcdat can be installed either in step 1 or step 2 above:

    • pooch: a library for downloading and managing data files, used by the xcdat.tutorial.open_dataset module.

    • jupyterlab: a web-based interactive development environment for notebooks, code, and data. This package also includes ipykernel.

    • matplotlib: a library for creating visualizations in Python.

    • nc-time-axis is an optional dependency required for matplotlib to plot cftime coordinates.

    • cartopy: an add-on package for matplotlib and specialized for geospatial data processing.

Updating#

New versions of xcdat will be released periodically. We recommend you use the latest stable version of xcdat for the latest features and bug fixes.

>>> conda activate <ENV_NAME>
>>> conda update xcdat

To update to a specific version of xcdat:

>>> conda activate <ENV_NAME>
>>> conda update xcdat=<MAJOR.MINOR.PATCH>
>>> # Example: conda update xcdat=0.6.1

Jupyter Users set ESMFMKFILE env variable#

If you are a Jupyter user, the ESMFMKFILE environment variable will need to be set either directly on the machine or through your Jupyter Notebook.

This env variable is normally set when calling conda activate with the conda environment that has xesmf. However, Jupyter does not run conda activate when using the Python kernel associated with the environment so ESMFMKFILE is not set, resulting in ImportError: The ESMFMKFILE environment variable is not available. (related GitHub Issue).

To set the ESMFMKFILE in a Jupyter Notebook add:

>>> import os
>>> os.environ['ESMFMKFILE'] = 'conda-envs/xcdat/lib/esmf.mk'
>>>
>>> import xcdat
Contents