1. Introduction

The level-2 time-variable gravity fields obtained from Gravity Recovery and Climate Experiment (GRACE) and its Follow-On (GRACE-FO) mission are widely used in multi-discipline geo-science studies. However, the post-processing of those gravity fields to obtain a desired signal is rather challenging for users that are not familiar with the level-2 products. In addition, the error assessment/quantification of those derived signals, which is of increasing demand in science application, is still a challenging issue even among the professional GRACE(-FO) users. In this effort, the common post-processing steps and the assessment of complicated error (uncertainty) of GRACE(-FO), are integrated into an open-source, cross-platform and Python-based toolbox called SAGEA (SAtellite Gravity Error Assessment). With diverse options, SAGEA provides flexibility to generate signal along with the full error from level-2 products, so that any non-expert user can easily obtain advanced experience of GRACE(-FO) processing. Please contact Shuhao Liu (liushuhao@hust.edu.cn) and Fan Yang (fany@plan.aau.dk) for more information.

When referencing this work, please cite:

Liu, S., Yang, F., & Forootan, E. (2025). SAGEA: A toolbox for comprehensive error assessment of GRACE and GRACE-FO based mass changes. Computers & Geosciences, 196, 105825. https://doi.org/10.1016/j.cageo.2024.105825

2. Features

• Auto-collecting GRACE(-FO) level-2 products and related auxiliary files.
• Commony used methodologies and technologies of GRACE(-FO)'s post-processing.
• Types of Error assessment/quantification of GRACE(-FO) based mass change.
• User interface (under construction).

3. Installation

This program homepage is: https://github.com/NCSGgroup/SaGEA.

Use this code to download this project.

git clone https://github.com/NCSGgroup/SaGEA

This project is developed based on Python 3.9 and the dependencies are listed in requirements.txt.

Use these coded to download the dependencies:

python -m pip install -r requirements.txt

To ensure the successful running and validation of programs, please collect the corresponding auxiliary files and verification files at https://zenodo.org/records/14087017 and place folders data and validation in the project folder by running this code:

python ./demo/data_collecting/demoCollectAuxiliary.py

4. Quick Start

Several demo programs are under the direction ./demo/ for users to quickly use and verify. Users can config the relevant parameters in the corresponding location or an independent JSON file. Detailed module usage and related scientific explanations will be provided in later chapters.

1. ./demo/data_collecting/demoCollectL2Data.py provides an example of collecting GRACE Level 2 products, including auxiliary files such as GAX and low-degrees products. Users can config the collecting parameters from the jason file in ./setting/data_collection/CollectL2Data.json.
2. ./demo/post_processing/demoPostProcessing.py provides an example for the post-processing of GRACE data.
3. ./demo/uncertainty_estimation/demoErrorI.py provides an example for the propagation of GRACE error ( variance-covariance matrix) during the post-processing.
4. ./demo/uncertainty_estimation/demoErrorII.py provides an example for the estimation of between-group errors through TCH (Three Corner Hat) technology on GRACE signals.
5. ./demo/uncertainty_estimation/demoErrorIII.py provides an example to gain the post-processing statistical uncertainty of GRACE signals.

5. Overview of Functional Modules and Usages

Fig. 1: Data structure of SaGEA Toolbox. Arrows represent dependency relationships.

SaGEA Toolbox is used for post-processing and error assessment of GRACE level-2 data, with the latter relying on the former, see Fig. 1. Thus post-processing is the core function of SaGEA toolbox.

SaGEA provides comprehensive post-processing methods. For ease to use, we have packaged each method as a function of two data classes:

1. SHC, representing spherical harmonic coefficients (SHCs);
2. GRID, representing gridded data.

Supporting that users may not be very familiar with the methods and principles we recommend calling the post-processing function through SHC or GRID instead of using them directly, as indicated by the circle in Fig. 1.

Here are listed the attributes and some commonly used methods in SHC() and GRID():

Attributes in SHC()

.value: 2-dimension numpy.ndarray that describes multiple sets of SHCs in shape of (n, (lmax+1)^2), where n represents the number of sets, lmax represents the maximum degree of SHCs. The arrangement of SHCs in the second dimension is like [C(0,0), S(1,1), C(1,0), C(1,1), S(2,2), S(2,1), C(2,0), C(2,1), C(2,2), S(3,3), ... ]

Methods in SHC()

.is_series(): to determine whether the stored SHCs are multiple sets.

.get_lmax(): to get the maximum degree/order of the SHCs.

.get_degree_rms(): to get degree-RMS.

.replace_low_degs(*params): to replace low-degree SHCs with others.

.filter(*params): to apply a spectral filtering on the SHCs.

.convert_type(*params): to convert SHCs from one physical dimension to another.

.geometric(*params): to apply a geometric correction on the SHCs.

.de_background(*params): to deduct a background field.

.add(*params): to add another SHC(), e.g., that of GAD.

.subtract(*params): to subtract another SHC(), e.g., that of GIA.

.expand(*params): to expand the stored SHCs as a linear trend to signals at time epochs (e.g., from GIA trend to signals).

.synthesis(*params): to harmonic synthesis the stored SHCs into spatial distribution in optional physical dimensions.

.to_grid(*params): pure harmonic synthesis.

Attributes in GRID()

.value: 3-dimension numpy.ndarray that describes multiple sets of SHCs in shape of (n, nlat, nlon), where n represents the number of sets, nlat and nlon represents the latitudes and the longitudes of grids.

.lat: 1-dimension numpy.ndarray that describes the geometry latitudes in unit degree.

.lon: 1-dimension numpy.ndarray that describes the geometry longitude in unit degree.

Methods in GRID()

.filter(*params): to apply a spatial filtering on the SHCs (under construction).

.leakage(*params): to apply a leakage reduction.

.seismic(*params): to apply a seismic correction.

.de_aliasing(*params): to fit and deduct long-term aliasing signals.

.integral(*params): to integral in globe or basin and get the results.

.limiter(*params): to set all signals to 1 or 0 according to the threshold.

.to_file(*params) to store as a file (.nc, .hdf5, etc.) locally.

6. Contributing

Fan Yang (fany@plan.aau.dk) led the scientific research and conducted rigorous data validation.

Shuhao Liu (liushuhao@hust.edu.cn) contributed to the software architecture design and core functionality implementation.

7. License

MIT License

Copyright (c) 2024 NCSG -- Numerical Computation and Satellite Geodesy research group

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

8. Additional Scientific Descriptions

8.1 Data Collection

GRACE and GRACE-FO level-2 products can be obtained at open source FTP server ftp://isdcftp.gfz-potsdam.de/. Level-2 products includes GSM, GAA, GAB, GAC, and GAD (The last four products are collectively referred to as GAX.), which are given in fully normalized spherical harmonic coefficients (SHCs) of gravity potential.

• GSM products represent the estimate of Earth's mean gravity field during the specified timespan derived from GRACE mission measurements.

• GAA products represent the anomalous contributions of the non-tidal atmosphere to the Earth's mean gravity field during the specified timespan.

• GAB products represent the anomalous contributions of the non-tidal dynamic ocean to ocean bottom pressure during the specified timespan.

• GAC products represent the sum of the GAA and GAB coefficients during the specified timespan.

• GAD products give the SHCs that are zero over the continents, and provide the anomalous simulated ocean bottom pressure that includes non-tidal air and water contributions elsewhere during the specified timespan.

The most used GSM solutions are given by three processing centers, that is, Center for Space Research (CSR), University of Texas at Austin, Jet Propulsion Laboratory (JPL), NASA, and German Research for Geosciences (GFZ), German.

8.2 Loading local GRACE level-2 products and replacing low-degree coefficients

GRACE level-2 GSM solutions lack the three degree-1 coefficients, which are proportional to geocenter motion and can not been ignored for a complete representation of the mass redistribution in the Earth system (Sun et al., 2016). The GRACE-based C20 coefficient is subject to large uncertainties (Chen et al., 2016). Besides, The C30 coefficient is also shown to be poorly observed by GRACE/GRACE-FO when eithe