gravitools

A collection of tools to analyze gravimeter data.

This Python package is a collaborative effort by the gravity metrology group at the German Federal Agency for Carthography and Geoesy (BKG) and the hydrology section at GFZ Helmholtz Centre for Geosciences.

When used or referenced, please cite as follows:

"Glässel, Julian; Reich, Marvin (2025): gravitools - A collection of tools to analyze gravimeter data. GFZ Data Services. https://doi.org/10.5880/GFZ.RDOQ.2025.001"

Features

• Read and process raw data of the Exail Absolute Quantum Gravimeter (AQG)
• Apply standardized or customized AQG data processing and outlier detection
• Read and write processed datasets with metadata to .nc-files in NETCDF4-format
• Handle Earth orientation parameters (EOP) from iers.org for polar motion correction
• Evaluate tilt calibration measurements and Coriolis effect estimations
• Visualize data with matplotlib
• CLI for standard processing of AQG raw data to .nc-file
• Dashboard for real-time processing and visualization during measurements (on AQG laptop)
• Dashboard includes a proposed standard template for a measurement protocol

Planned

• Handling of Scintrex CG6 data and standard analyses
• Tilt calibration analysis within GUI
• Coriolis effect measurements analysis within GUI
• Generation of PDF-report for tilt calibration analyses
• Generation of PDF-report for Coriolis measurement analyses

Dependencies

• Python 3.8 or later
• allantools (LGPLv3+ license)
• fpdf2 (LGPLv3)
• matplotlib (PSF license)
• netcdf4-python (MIT license)
• numpy (BSD license)
• pandas (BSD license)
• pyyaml (MIT license)
• requests (Apache 2 license)
• xarray (Apache 2 license)

Optional

AQG dashboard

• PySide6 (LGPLv3 license)
• pyqtgraph (MIT license)

Documentation

• mkdocs (BSD license)
• mkdocstrings-python (ISC license)
• mkdocs-material (MIT license)
• mkdocs-jupyter (Apache 2 license)

Unit tests

• pytest (MIT license)
• pytest-cov (MIT license)

Installation

For the latest stable release, install from PyPI.org

    $ pip install gravitools

For the latest (development) version, install from Git repository

    $ pip install git+https://gitlab.opencode.de/bkg/gravitools.git

For further install instructions please see the respective section in the documentation. Especially, please read about the necessary EOP data here, as gravitools will throw errors if they are not present locally in your file system.

Getting started with AQG data processing

Example usage:

    from gravitools.aqg import read_aqg_raw_dataset

    # Read raw data to an AQGRawData object (which wraps a pandas.DataFrame)
    raw = read_aqg_raw_dataset("20240620_163341.zip")

    # Apply standard processing
    raw.process()

    # Finalize processing by converting to an AQGDataset (which wraps an
    # xarray.Dataset)
    dataset = raw.to_dataset()

    # Save processed dataset to file in NETCDF-4 format
    dataset.to_nc("20240620_163341.nc")

    # Generate and save a measurement report in PDF format
    dataset.save_report("report_20240620_163341.pdf")

AQG dashboard

The AQG dashboard is a graphical user application to process and visualize AQG datasets. It is primarily intended to run on the AQG control laptop and expand upon the control software by providing additional data processing (such as outlier removal) and preliminary results for a running measurement, and enhance the operator's ability to monitor data quality, especially for field measurements. For instance, it helps the operator decide the minimum required measurement duration. The dashboard can also be used to process completed datasets. More information on this, including all offered options, are addressed in the documentation.

Install gravitools with the optional dependencies for the dashboard, preferably in an isolated virtual environment.

    $ pip install 'gravitools[dashboard]'

Run the dashboard

    $ gt-aqg-dash

Documentation

The documenation is available at gravitools.readthedocs.io.

To build the documentation, clone the repository and install gravitools with the necessary dependencies into a virtual environment.

    $ git clone https://gitlab.opencode.de/bkg/gravitools.git
    $ cd gravitools/
    $ python -m venv venv
    $ source venv/bin/activate
    $ pip install -e .[docs]

Build the documentation

    $ mkdocs build

The documentation can be accessed at public/index.html.

Conventions

Data

• All corrections are subtracted from the measured gravity value.
• Units are assumed as follows (if not provided and parameters are passed only as numbers). Input data in other units is converted.
  • Gravity: nm s^-2^
  • Gravity gradient: nm s^-2^ m^-1^
  • Heights: m
  • Tilt angle: rad
  • Polar angles: arcsec
  • Coordinates: degree
  • Orientation of sensor: degree from North
• Timestamps are always UTC.

Terminology

Point : A precisely defined measurement location, usually identified by a point code. For example, the gravimeter lab at the Geodetic Observatory Wettzell has points WET_CA, WET_DA, WET_EA, and WET_FA. The vertical gravity gradient is a property of each point. An Earth tide model can apply to multiple points.

site_name : The AQG control software has an input field for the measurement site name. It is recored in the metadata (.info file) as measurement_site_name. Here, this parameter name is shortened to site_name and its value kept unchanged. Since this field can contain supplementary metadata, such as sensor orientation, it is not necessarily identical to the point code. When reading a dataset, Gravitools attempts to guess the point code and sensor orientation from the site_name by a formatting pattern.