openghg 0.18.0

OpenGHG - a Cloud Platform for Greenhouse Gas Data Analysis and Collaboration

OpenGHG is a platform for collaboration and analysis of greenhouse gas (GHG) data, inspired by the HUGS platform. It allows researchers to analyze and collaborate on large datasets using the scalability of the cloud.

For more information, please visit our documentation.

Install OpenGHG

OpenGHG supports Python 3.10 and later on Linux or MacOS. To install the package, you can use either uv (recommended for its environment management abilities) or conda.

Installing with uv

uv simplifies environment creation and dependency management, making it easy to manage your setup. To install OpenGHG using uv:

1. Install uv:

   The uv tool from Astral streamlines Python management, virtual environments, and package installation. Follow the recommended steps from the official uv docs:

   1. Install from linkuv (Recommended "robust, Python-independent"):
   • macOS/Linux:

     curl -LsSf https://astral.sh/uv/install.sh | sh
     

   2. Install from pip (Alternative "requires existing Python + pip"):

      pip install uv
      

2. Create and activate an environment for OpenGHG:

   uv venv openghg-env
   

   Additionally, a specific python version can be specified while creating the environment as follows.

   uv venv openghg-env --python 3.11
   

   To activate:

   source openghg-env/bin/activate
   

3. Install OpenGHG:

   uv pip install openghg
   

This installs OpenGHG and its core dependencies.

Installing with conda

To get OpenGHG installed using conda, follow these steps:

1. Create and activate a conda environment:

   conda create --name openghg_env
   conda activate openghg_env
   

2. Install OpenGHG and its dependencies using the conda-forge and openghg channels:

   conda install --channel conda-forge --channel openghg openghg
   

Note: The optional xesmf library is pre-installed when using conda. No additional steps are required for regridding functionality.

Quickstart Configuration

Once OpenGHG is installed, you need to configure the object store and user data. OpenGHG stores its configuration file by default at: ~/.config/openghg/openghg.conf.

Configure via CLI:

openghg --quickstart

Configure via Python:

from openghg.util import create_config

create_config()

When prompted, you can specify the path to the object store. Leave the field blank to use the default directory at ~/openghg_store.

Developers

If you'd like to contribute to OpenGHG, here are the steps to set up a development environment. You can use either uv or conda.

Using uv for Development

1. Clone the repository:

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

2. Create and activate an environment for OpenGHG:

   uv venv
   

   A python environment with name can also be created, as showed in non-developer instance previously. Additionally, a specific python version can be specified while creating the environment as follows.

   uv venv --python 3.11
   

   Note: If the virtual environment is not named, the .venv folder is created at the directory level, and using commands like "uv add" or "uv pip install" will automatically detect the environment and install the packages.

   To activate:

   source .venv/bin/activate
   

3. Install development dependencies and the package in editable mode:

   uv sync --all-extras
   

   This ensures that the local repository is installed in editable mode, meaning changes to the source code are immediately reflected. It will also ensure that all the dev and documentation dependencies are installed in the environment.

   For more details, please refer to the UV Documentation (sync).

Using conda for Development

1. Clone the repository:

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

2. Create and activate a conda environment:

   conda create --name openghg-dev python=3.12
   conda activate openghg-dev
   

3. Install development dependencies:

   pip install --upgrade pip wheel setuptools
   pip install -e ".[dev]"
   

Running Tests

OpenGHG uses pytest for testing. After setting up the development environment, you can run tests as follows:

pytest -v tests/

Additional Testing:

• CF Checker Tests: Install the udunits2 library for certain tests:

  sudo apt-get install libudunits2-0
  pytest -v --run-cfchecks tests/
  

• ICOS Tests: These tests access the ICOS Carbon Portal and should be run sparingly:

  pytest -v --run-icos tests/
  

If you encounter issues, please open a GitHub issue.

Additional Functionality

OpenGHG's optional functionality includes the xesmf module for map regridding.

Note that xesmf is not installed by default with the core OpenGHG package.

• When using uv, install it explicitly, for example:

  uv add xesmf
  

• For conda install of xesmf

  conda install -c conda-forge xesmf
  

For further details, refer to our documentation.

Community and Contributions

We encourage contributions and are happy to assist where needed. Raise issues and pull requests in our repository.

For further information, check out our documentation.