Installation¶
The easiest way to install OpenGHG is using pip, first ensure you have a recent version of Python installed.
Checking your Python installation¶
OpenGHG is developed and tested on Linux and MacOS, support for Windows is planned.
To install OpenGHG, you first need to install Python >= 3.10. To check if you have Python 3.10 installed type;
python -V
This should print out the version number of the Python you have available.
If the version number is 2.x then you must use the python3 command, if this this is the case, try;
python3 -V
and see if you have a Python 3 that has a version number >= 3.10. If so, please use python3 instead of python.
If you don’t have Python >= 3.10 installed, then you can install Python either via your package manager if using Linux or Homebrew on MacOS. An alternative for both platforms is anaconda.
Installation¶
We highly recommend creating a separate virtual environment for openghg. This ensures the correct versions
of libraries can be installed without making changes to versions of libraries needed for other projects / programs.
Pixi¶
Pixi is the recommended development install when working with NetCDF,
HDF5, or Zarr data. OpenGHG reads and writes these data through
xarray, h5netcdf, h5py, netcdf4, and zarr. The Pixi
workspace in this repository installs the compiled scientific,
HDF5, and NetCDF stack from conda-forge and installs the local
OpenGHG checkout in editable mode.
Install Pixi directly with one of the following commands.
On macOS or Linux, use the official installer:
curl -fsSL https://pixi.sh/install.sh | sh
If curl is unavailable, use wget:
wget -qO- https://pixi.sh/install.sh | sh
On macOS with Homebrew:
brew install pixi
Then create the editable OpenGHG development environment from a cloned checkout:
git clone https://github.com/openghg/openghg.git
cd openghg
pixi install -e dev
pixi run -e dev python -c "import openghg, h5py, h5netcdf, netCDF4, xarray, zarr"
Useful development commands:
pixi run -e dev test
pixi run -e dev test-storage
pixi run -e dev lint
pixi run -e dev typecheck
Avoid running commands such as pip install -U h5py h5netcdf netcdf4
inside the Pixi environment. That can replace Pixi’s conda-forge
HDF5/NetCDF packages with PyPI wheels and reintroduce binary
incompatibilities.
pip¶
First create a virtual environment and activate it
python -m venv /path/to/env/openghg_env
source /path/to/env/bin/activate
Here change /path/to/env with your own path.
Next install OpenGHG
pip install openghg
conda¶
First create and activate a conda environment
conda create --name openghg_env
conda activate openghg_env
Next install OpenGHG from our conda channel
conda install --channel conda-forge --channel openghg openghg
Configuration¶
OpenGHG needs to know where to create the object store it uses to store data, it does this by reading a configuration file in your home
directory. As part of the setup process we need to create this configuration file using either the openghg.util.create_config function
or the command line interface.
Python¶
You can use the create_config function to help you make a config file. First import
In [1]: from openghg.util import create_config
In [2]: create_config()
OpenGHG configuration
---------------------
Enter path for object store (default /home/gareth/openghg_store):
INFO:openghg.util:Creating config at /home/gareth/.config/openghg/openghg.conf
INFO:openghg.util:Configuration written to /home/gareth/.config/openghg/openghg.conf
Here I left the path to the object store blank to use the default path in my home directory.
Command line¶
You can also use the openghg command line tool to get the configuration file setup.
openghg --quickstart
OpenGHG configuration
---------------------
Enter path for object store (default /home/gareth/openghg_store):
INFO:openghg.util:Creating config at /home/gareth/.config/openghg/openghg.conf
INFO:openghg.util:Configuration written to /home/gareth/.config/openghg/openghg.conf
A configuration file has been created and you’re ready to run OpenGHG. If you ever want to modify the configuration file
you can find it at ~/.config/openghg/openghg.conf. My configuration file looks like this
user_id = "47363762-2963-4a2d-8afc-dejh05380f19"
[object_store]
local_store = "/home/gareth/openghg_store"
Deprecation of OPENGHG_PATH¶
If you’ve previously used OpenGHG and worked through our tutorials you might have encountered
the need to set the OPENGHG_PATH environment variable. Now that we’ve moved to a configuration
file this is not longer used. If you previously set a custom path using the variable please update
the configuration file as below.
Developers¶
For developers please see the Getting setup documentation.