Quickstart - developer

This quickstart guide will get you quickly setup with a development environment so you can use and contribute to OpenGHG. The main repository for OpenGHG can be found on GitHub.

Setting up your computer

You’ll need git and Python >= 3.8, so please make sure you have both installed before continuing further.

Clone OpenGHG

First we’ll clone the repository and make sure we’re on the devel branch. This makes sure we’re on the most up to date version of OpenGHG.

git clone https://github.com/openghg/openghg.git
cd openghg
git checkout devel

Next we’ll get a virtual environment setup using either pip or conda.

Environments

Here we cover the creation of an environment and the installation of OpenGHG into it. Installation here means adding OpenGHG to the environment. We’ll install it in developer mode so that any changes you make to the code will automatically be available when you run commands. Similarly, if you run a git pull on the devel branch all changes made will be available to you straight away, without having to reinstall or update OpenGHG within the environment.

pip

It is recommended that you develop OpenGHG in a Python virtual environment. Here we’ll create a new folder called envs in our home directory and create a new openghg_devel environment in it.

mkdir -p ~/envs/openghg_devel
python -m venv ~/envs/openghg_devel

Virtual environments provide sandboxes which make it easier to develop and test code. They also allow you to install Python modules without interfering with other Python installations.

We activate our new environment using

source ~/envs/openghg_devel/bin/activate

We’ll first install and update some of the installation tools

pip install --upgrade pip wheel setuptools

Now, making sure we’re in the root of the OpenGHG repository we just cloned, install OpenGHG’s requirements and its developer requirements.

pip install -r requirements.txt -r requirements-dev.txt

Finally install OpenGHG itself. The -e / --editable flag here tells pip to install the OpenGHG repo in develop mode.

pip install -e .

OpenGHG should now be installed, you can check this by opening ipython and running

In [1]: import openghg

conda

Making sure you’re in the openghg repository folder run

conda env create -f environment.yaml

Once conda finishes its installation process you can activate the enironment

conda activate openghg_env

Next install conda-build which allows us to install packages in develop mode

conda install conda-build

And finally install OpenGHG

conda develop .

OpenGHG should now be installed, you can check this by opening ipython and running

In [1]: import openghg

The object store

The object store is where OpenGHG stores its information. Metadata and binary data are stored with in a key-value setup. As you’ll be using OpenGHG locally this means all data will be stored on your local or network file system.

When you first import OpenGHG it creates a file in your home directory at ~/.config/openghg/openghg.conf. Open this file with your chosen text editor and you’ll see the contents of a TOML file that looks like this

[object_store]
local_store = "/home/gareth/openghg_store"

By default the object store will be created in your home directory, if you want to move it just change that path.

Jupyter

If you want to use Jupyter notebooks to interact with OpenGHG, you can install jupyterlab.

pip install jupyterlab

Then just run jupyter notebook to get started.

What next?

Now you’ve got OpenGHG setup please take a look at our tutorials section and if you’d like to start contributing to OpenGHG open an issue and submit a pull request!