Installation Guide

Installation Guide#

This page describes different ways to install PyEathTools depending on intended usage:

users or developers at NCI,
install all PyEarthTools packages and tutorials (recommended for new users),
install PyEarthTools packages as dependencies in your Python project,
install PyEarthTools in developer mode in order to contribute.

These installation instructions have been tested on Linux, macOS and Windows. If you encounter any difficulties, please raise an issue.

Using or Developing PyEarthTools at NCI#

Many of the users of PyEarthTools work on the NCI supercomputing environment. Users here should request access to project code dk92. The modules environment /g/data/dk92/apps/Modules/modulefiles can then be specified, and the module pet/2025.05 can be used (noting this module name will change with each new update). This will make the most recent update of PyEarthTools available.

For developers of PyEarthTools at NCI, this is the recommended approach, not a virtual environment. Users can then use pip install -e to check out the latest code from the repository, and Python will install the development packages into a userspace install directory.

Installation of PyEarthTools (including tutorials)#

This section details how to install PyEarthTools to be able run notebooks from the Tutorial Gallery. This installation procedure uses a Conda environment (see the corresponding section for more information about virtual environments).

First, make sure to have Git and Conda installed on your system.

Then, clone the PyEarthTools repository:

git clone https://github.com/ACCESS-Community-Hub/PyEarthTools.git
cd PyEarthTools

Create a Conda environment including Python and Graphviz, and activate it:

conda create -y -p ./venv python graphviz
conda activate ./venv

Next, install PyEarthTools and all its dependencies:

pip install -r requirements.txt

Finally, start a JupyterLab instance to run the example notebooks:

jupyter-lab notebooks/

Note

Alternatively, you can install a Jupyter kernel to run notebooks in a pre-existing JupyterLab installation:

# after activating the Conda environment
python -m ipykernel install --user --name PET-tutorial

See the IPython documentation for additional information regarding the IPython kernel installation.

Installing Individual PyEarthTools Sub-Packages#

PyEarthTools comprises multiple, modular sub-packages within a shared namespace that inter-operate in order to provide the overall functionality of the framework.

It is not necessary to install all of them, and it is envisioned that many users are likely to want only some parts of the framework.

Each PyEarthTools sub-package can be installed separately using pip, directly from GitHub. For example, to install the utils sub-package, use:

pip install "pyearthtools[utils] @ git+https://github.com/ACCESS-Community-Hub/PyEarthTools.git"

Other available sub-packages are data, pipeline, training, tutorial and zoo.

To install all PyEarthTools packages, including all their optional dependencies, use:

pip install "pyearthtools[all] @ git+https://github.com/ACCESS-Community-Hub/PyEarthTools.git"

Developer Installation#

PyEarthTools code is organised as a monorepo, each sub-package lies in a different sub-directory in the packages directory.

Developers of PyEarthTools will most likely want to check out the entire monorepo and work on changesets which may span sub-packages.

The following instructions detail how to install PyEarthTools in editable mode, making it easier to implement and test changes iteratively.

Tip

Each sub-package is versioned separately, so bugfixes or updates in a single sub-package can be performed independently without requiring a new release of the entire ecosystem.

First clone the PyEarthTools repository:

git clone https://github.com/ACCESS-Community-Hub/PyEarthTools.git
cd PyEarthTools

Create a Virtual Environment and activate it.

Conda environment

conda create -y -p ./venv python graphviz
conda activate ./venv

Python virtual environment

python3 -m venv ./venv
source venv/bin/activate

Then install all packages in “editable” mode with

pip install -r requirements.txt

or install a specific package <package-name> in editable mode using

pip install -e packages/<package-name>

Virtual Environments#

Users installing PyEarthTools for themselves (such as on their own workstation or laptop) are recommended to use a virtual environment.

Virtual environments are isolated, dedicated copies of Python, which are separate from the version of Python which may be present and used by other software or your operating system. Using a virtual environment avoids the need for root or Administrator access, and also lowers the risk of corrupting the system if there are any problems with the installation. Industry standard practice for software development is to use virtual environments in this way.

We recommend using conda to create a virtual environment.

You can also use virtualenv (also referred to as pipenv and venv) to create a virtual environment. However, if you use virtualenv you will most likely want to manually install graphviz. While there is a package called graphviz in pip, it only supplies Python wrappers around the core package which must be installed separately. Note, graphviz is used for the display of pipelines, but is not core to PyEarthTools functionality, so choosing not to install graphviz should not result in unhandled exceptions. Additionally, if you wish to build your own copy of the documentation locally you will also need to manually install pandoc.

Users in shared computing environments (as is common in HPC and other research facilities) may or may not be able to use virtual environments easily, regardless of the choice between conda and virtualenv, and you may need to use or set up a modules environment.

Creating a Virtual Environment

We recommend using conda to create a virtual environment.

Here is a command to create and activate a new virtual environment with conda:

conda create --name <my-env> python
conda activate <my-env>

Here is a command to create and activate a new virtual environment with conda, into a specified directory (often required when on shared computing facilities):

conda create -p <path_to_environment> python
conda activate -p <path_to_environment>

You can also use virtualenv to create a virtual environment, but please see the virtual environments section above for information about dependencies you may then wish to install manually.

Here is a command to create and activate a new virtual environment with venv:

python -m venv <path_to_environment>
source <path_to_environment>/bin/activate

These approaches will all create a new virtual environment, with the Python interpreter installed, but no additional packages yet.