PySHbundle: A Python implementation of GRACE Spherical Harmonics Synthesis MATLAB codes SHbundle

This package, PySHbundle provides tools to process GRACE data, such as, the computation of anomalies, substitution of poor quality low degree coefficients, reducing noise in GRACE data using filtering approaches, signal leakage correction using GDDC, etc. In addition, the package provides a flexibility for future development and addition of further processing choices for handling GRACE data for hydrological application.

PySHBundle is a tool to process GRACE L2 data and re-implements the popular SHBundle and DataDrivenCorrection Bundle tools originally written using MATLAB.

Usage

Read and Load level-2 spherical harmonic data
Create basin time series for TWS
Perform grace data driven correction
Plot spherical harmonic related plots

1. How to install

1.1 For Users

The simplest way to install is via pip:

$ pip install pyshbundle

To also access the example notebooks and data, clone the repository:

# Clone the repository
$ git clone https://github.com/GESS-research-group/pyshbundle.git
$ cd pyshbundle

# Create and activate a virtual environment
$ python3 -m venv <name-env>
$ source <name-env>/bin/activate  # On Windows: <name-env>\Scripts\activate

# Install the package
$ pip install .

1.2 For Devs/Contributors

# Clone the repository
$ git clone https://github.com/GESS-research-group/pyshbundle.git
$ cd pyshbundle

# Create and activate a virtual environment
$ python3 -m venv <name-env>
$ source <name-env>/bin/activate  # On Windows: <name-env>\Scripts\activate

# Install the package in editable mode with dev dependencies
$ pip install -r requirements-dev.txt
$ pip install -e .

# To build a source distribution
$ python -m build

Trying it out

Data for trying out this new tool is included in the repo. After installing and cloning the repo, go to the notebooks directory in order to find explainatory ipython jupyter notebooks. Simply activate the virtual environment and fire up these jupyter notebooks. Available notebooks:

Introduction to Spherical Harmonics
Loading the data
Visualizations
Terrestrial Water Storage (TWS) Time Series
Tests and Validation notebook

Docs

Please find the docs here - PySHBundle

Testing

The test suite validates the accuracy of the TWS computation against a MATLAB reference solution.

Framework

Tests are written in pytest and live in the tests/ directory.

Running the tests

# From the project root
pytest tests/ -v

By default, the tests look for GRACE input data in data/JPL_input/. You can override this with an environment variable:

PYSHBUNDLE_DATA_DIR=/path/to/your/data pytest tests/ -v

What is tested

The suite runs 6 tests using 60 months of JPL GRACE RL06 data compared against a MATLAB-generated reference TWS field (tws_sh.mat):

| Test | Description | Threshold | |---|---|---| | test_tws_output_shape | Computed and reference arrays have identical shape | — | | test_tws_output_dtype | Output is float32 | — | | test_gridwise_rmse | Gridwise RMSE (mm) between computed and reference TWS | < 1e-3 | | test_gridwise_nrmse | Gridwise NRMSE (normalised by reference std) | < 1e-5 | | test_no_nan_in_output | No NaN values in computed TWS | — | | test_no_nan_in_reference | No NaN values in MATLAB reference (sanity check) | — |

Continuous Integration

Tests run automatically on every push via GitHub Actions across 6 combinations:

OS: Ubuntu, macOS, Windows
Python: 3.9, 3.12

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at GitHub Issues

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with bug and help wanted is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with enhancement and help wanted is open to whoever wants to implement it.

Write Documentation

pyshbundle could always use more documentation, whether as part of the official pyshbundle docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at GitHub Issues

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :).

License Statement

This file is part of PySHbundle. PySHbundle is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Acknowledgement:

Please note that PySHbundle has adapted the following code packages,both licensed under GNU General Public License

SHbundle: https://www.gis.uni-stuttgart.de/en/research/downloads/shbundle/
Downscaling GRACE Total Water Storage Change using Partial Least Squares Regression: https://springernature.figshare.com/collections/downscaling_GRACE_Total_Water_Storage_Change_using_Partial_Least_Squares_Regression/5054564

Key Papers Referred:

Vishwakarma, B. D., Horwath, M., Devaraju, B., Groh, A., & Sneeuw, N. (2017). A data‐driven approach for repairing the hydrological catchment signal damage due to filtering of GRACE products. Water Resources Research, 53(11), 9824-9844. https://doi.org/10.1002/2017WR021150
Vishwakarma, B. D., Zhang, J., & Sneeuw, N. (2021). Downscaling GRACE total water storage change using partial least squares regression. Scientific data, 8(1), 95. https://doi.org/10.1038/s41597-021-00862-6

How to Cite?

Coming soon!

Follow the Research Group

Pyshbundle

Install / Use

README

PySHbundle: A Python implementation of GRACE Spherical Harmonics Synthesis MATLAB codes SHbundle <br>