gravitools 0.3.0

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
• Tilt calibration analysis via dashboard
• Coriolis effect measurements analysis via dashboard
• Collimator scan analysis via dashboard
• Maintenance views of internal components and logfiles via dashboard
• Compatible with the new AQG GUI >= 2.0 (and the partly new structure of the raw data files)
• Creation of PDF-reports for all of the above standard analysis

Planned

• Handling of Scintrex CG6 data and standard analyses (to be evaluated)
• Including on-the-fly tide time series generation
• Approach to combine (and store) North/South AQG measurements

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

• jupyter (BSD license)
• mkdocstrings (ISC license)
• mkdocstrings-python (ISC license)
• nbconvert (BSD license)
• zensical (MIT license)

Unit tests

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

Installation

As for all python packages, we recommend installing into a virtual environment (to conserve system integrity as for python installs). This is especially true if you plan on using the GUI directly on the AQG laptop. If you use or plan to use different python verions, we recommend pyenv. Otherwise, the standard python-provided method works as follows:

    # setup
    $ python -m venv nameOfEnvironment

    # activate (Windows)
    $ nameOfEnvironment\Scripts\activate

    # activate (Linux/Mac)
    $ source nameOfEnvironment/bin/activate

Then proceed to install as described below.

For the latest stable release, install from PyPI.org

    $ pip install gravitools

or via conda-forge

    $ conda install gravitools --channel conda-forge

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.

Important note

after successfuly installation, please run the commandline command download_eop_data. This will download necessary Earth Orientation Data (EOP) to a local directory. Without this data, the package will not work properly. You can also do this download manually, please see the EOP documenation.

Getting started with AQG data processing

An extensive overview is provided in the official documentation.

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 was primarily included with the intention 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 in oder to 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. With the recent version, it is now also possible to process datasets for tilt calibration, coriolis evaluation and collimator scans. Furthermore, a protocol tab was included that provides the possibility to carry out documentation on the measurement directly.

More information on this, including all offered options, are addressed in the documentation.

To use the dashboard, install gravitools with the optional dependencies for the dashboard, preferably in an isolated virtual environment.

    $ pip install 'gravitools[dashboard]'

or via conda-forge

    $ conda install gravitools-dashboard --channel conda-forge

Run the dashboard

    $ gt-aqg-dash

First installation / usage of dashboard

If an error is shown when starting the dashboard This application failed to start because no Qt platform plugin could be initialized., there is a missing development library of the underlying operating system (usually Linux Debian). Install the missing library via the command below:

    $ sudo apt-get install -y libxcb-cursor-dev

Documentation

The official, stable documenation is available at gravitools.readthedocs.io/stable/.

There is also up-to-date documentation of the develoment version which is build on the git respository here.

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 (jupyter notebooks have to be converted first):

    $ jupyter nbconvert --to markdown --execute docs/aqg_1_raw.ipynb --output-dir docs/
    $ jupyter nbconvert --to markdown --execute docs/aqg_2_nc.ipynb --output-dir docs/
    $ jupyter nbconvert --to markdown --execute docs/aqg_cmd.ipynb --output-dir docs/
    $ jupyter nbconvert --to markdown --execute docs/aqg_tilt_calib.ipynb --output-dir docs/
    $ jupyter nbconvert --to markdown --execute docs/aqg_coriolis_calib.ipynb --output-dir docs/
    $ zensical build --clean

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