1. Installing hstaxe

Note

As of current testing, HSTaXe does not support Windows. Please use our legacy instructions for attempting to use HSTaXe on Windows

1.1. Preparing Your Local Environment

We recommend using Anaconda to manage your hstaxe environment.

You may want to consider installing hstaxe in a new virtual or conda environment to avoid version conflicts with other packages you may have installed.

Start by creating an empty conda environment:

conda create --name hstaxe-env "python>=3.8, <3.11"
conda activate hstaxe-env

1.1.1. Build Prerequisites

Because the core modules of hstaxe are written in C, we require some additional prerequisites to be installed before attempting to install hstaxe:

conda install gsl cfitsio make automake autoconf libtool pkg-config -y
conda install wcstools -c https://conda.anaconda.org/conda-forge/ --override-channels -y

Some architectures (for example systems with Apple M1 processors) may not have a wheel available for tables. This can manifest as a failure to install tables during the next hstaxe installation step and can be solved by running the following (which allows tables to build from source) before repeating the failed install step:

conda install hdf5 -c conda-forge

Some users have also reported needing to install openblas in order to get a successful install working. If you have followed the rest of the hstaxe installation instructions and are still having problems, it may be worth adding the following command at this step:

conda install openblas -c conda-forge

1.2. Installing HSTaXe

hstaxe is distributed through PyPI. To install the latest release of hstaxe:

pip install hstaxe --no-cache-dir

The --no-cache-dir flag is optional, but it ensures that you are getting the most up-to-date versions of dependencies, rather than using anything cached on your local system.

To instead install the latest development version, you can either install from our GitHub repository directly:

pip install git+https://github.com/spacetelescope/hstaxe.git

or alternatively, clone the repository locally and install the clone:

git clone https://github.com/spacetelescope/hstaxe.git
cd hstaxe
pip install .

If you want to run the example notebooks, you will also need to install Jupyter:

pip install jupyter

1.3. Legacy Astroconda Installation

For historical preservation, we provide the original installation instructions for installing hstaxe via Astroconda. We preserved a premade conda environment yaml in the repository for reproducability:

conda create --name hstaxe-env --file legacy_astroconda_environment.yml
conda activate hstaxe-env
conda install hstaxe -c https://ssb.stsci.edu/astroconda --override-channels

1.4. Package Structure

The hstaxe software is composed of a combination of routines written in ANSI-C and python. Many of the python modules use the C executables to do their work, while some perform all operations within the python module itself. The C executables reside in the cextern directory, while the python source routines reside in hstaxe tree.

1.5. Validating the aXe installation

Jupyter notebooks for validation (and as examples of using HSTaXe) are available at https://github.com/spacetelescope/hstaxe/tree/main/cookbooks. We recommend cloning the repository as described above, and creating a new environment by running the following in the directory with the cookbook_env.yml file:

conda env create -f cookbook_env.yml

This will set up an environment called hstaxe_cookbook_acs_wfc3 that has some packages installed that are needed to run the notebooks but are not strictly necessary for hstaxe itself, such as hstcal and acstools. Once this environment is activated, you will need to download some data and configuration files as detailed in the Introduction section of each notebook, after which the notebooks should run all the way through without any other changes if hstaxe has been installed successfully.