openghg

KO | EN

gitlite — search

#python #rust #ai #mcp #typescript #openai #llm #java #react #nextjs #claude-code #cybersecurity

★ 46 Open GitHub ↗

A platform for greenhouse gas (GHG) data analysis and collaboration.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![OpenGHG logo](https://github.com/openghg/logo/raw/main/OpenGHG_Logo_Landscape.png)

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

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![OpenGHG tests](https://github.com/openghg/openghg/workflows/OpenGHG%20tests/badge.svg?branch=master)

OpenGHG is a platform for collaboration and analysis of greenhouse gas (GHG) data, inspired by the [HUGS platform](https://github.com/hugs-cloud/hugs). It allows researchers to analyze and collaborate on large datasets using the scalability of the cloud.

For more information, please visit [our documentation](https://docs.openghg.org/).

---

## Install OpenGHG

OpenGHG supports Python 3.10 and later on Linux or MacOS. To install the released package, you can use `uv` or `conda`. For development installs from a local checkout, you can also use `pixi`.

### Installing with Pixi for development

OpenGHG reads and writes NetCDF/HDF5 data through `xarray`, `h5netcdf`, `h5py`, `netcdf4`, and `zarr`. The Pixi environment 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:

```bash
curl -fsSL https://pixi.sh/install.sh | sh
```

If `curl` is unavailable, use `wget`:

```bash
wget -qO- https://pixi.sh/install.sh | sh
```

On macOS with Homebrew:

```bash
brew install pixi
```

Then create the editable OpenGHG development environment from a cloned checkout:

```bash
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:

```bash
pixi run -e dev test
pixi run -e dev test-storage
pixi run -e dev lint
pixi run -e dev typecheck
```

Do not run 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.

### 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 link`uv` (Recommended "robust, Python-independent"):
   - macOS/Linux:
     ```bash
     curl -LsSf https://astral.sh/uv/install.sh | sh
     ```

2. Install from pip (Alternative "requires existing Python + pip"):
      ```bash
      pip install uv
      ```

2. **Create and activate an environment for OpenGHG:**
   ```bash
   uv venv openghg-env
   ```
   Additionally, a specific python version can be specified while creating the
   environment as follows.
   ```bash
   uv venv openghg-env --python 3.11
   ```
   To activate:
   ```bash
   source openghg-env/bin/activate
   ```

3. **Install OpenGHG:**
   ```bash
   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:**
   ```bash
   conda create --name openghg_env
   conda activate openghg_env
   ```

2. **Install OpenGHG and its dependencies using the `conda-forge` and `openghg` channels:**
   ```bash
   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:
```bash
openghg --quickstart
```

### Configure via Python:
```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. Pixi is recommended when working with NetCDF, HDF5, or Zarr data because it keeps the compiled data stack on `conda-forge`. You can also use `uv` or `conda`.

### Using Pixi for Development

1. **Clone the repository:**
   ```bash
   git clone https://github.com/openghg/openghg.git
   cd openghg
   ```

2. **Install the development environment:**
   ```bash
   pixi install -e dev
   ```

This installs the local OpenGHG repository in editable mode.

3. **Run checks:**
   ```bash
   pixi run -e dev test-storage
   pixi run -e dev lint
   ```

### Using `uv` for Development

1. **Clone the repository:**
   ```bash
   git clone https://github.com/openghg/openghg.git
   cd openghg
   ```

2. **Create and activate an environment for OpenGHG:**
   ```bash
   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.
   ```bash
   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:
      ```bash
      source .venv/bin/activate
      ```

3. **Install development dependencies and the package in editable mode:**
   ```bash
   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)](https://docs.astral.sh/uv/concepts/projects/sync/#syncing-the-environment).

### Using `conda` for Development

1. **Clone the repository:**
   ```bash
   git clone https://github.com/openghg/openghg.git
   cd openghg
   ```

2. **Create and activate a `conda` environment:**
   ```bash
   conda create --name openghg-dev python=3.12
   conda activate openghg-dev
   ```

3. **Install development dependencies:**
   ```bash
   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:
```bash
pytest -v tests/
```

#### Additional Testing:

- **CF Checker Tests:** Install the `udunits2` library for certain tests:
   ```bash
   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:
   ```bash
   pytest -v --run-icos tests/
   ```

If you encounter issues, please [open a GitHub issue](https://github.com/openghg/openghg/issues/new).

---

## 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:
  ```bash
  uv add xesmf

- For conda install of xesmf
  ```bash
  conda install -c conda-forge xesmf

For further details, refer to [our documentation](https://docs.openghg.org/).

---

## Community and Contributions

We encourage contributions and are happy to assist where needed. Raise issues and pull requests in [our repository](https://github.com/openghg/openghg).

For further information, check out [our documentation](https://docs.openghg.org/).

openghg

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README