diff --git a/paper.bib b/paper.bib index af6939a3..9667801a 100644 --- a/paper.bib +++ b/paper.bib @@ -5,7 +5,7 @@ @article{humphrey2023using pages={1--29}, year={2023}, publisher={Springer}, - doi={https://doi.org/10.1007/s10712-022-09754-9}, + doi={doi.org/10.1007/s10712-022-09754-9}, } @@ -43,7 +43,7 @@ @misc{gravity-toolkit title = {GitHub - {Tsutterley}/gravity-toolkit: Python tools for obtaining and working with data from the {GRACE} and {GRACE} {Follow}-{On} missions}, howpublished = "\url{https://github.com/tsutterley/gravity-toolkit}", year = 2023, - doi={https://doi.org/10.5281/zenodo.8075728}, + doi={doi.org/10.5281/zenodo.8075728}, } @@ -51,7 +51,7 @@ @article{vishwakarma2017understanding title={Understanding and repairing the signal damage due to filtering of mass change estimates from the GRACE satellite mission}, author={Vishwakarma, Bramha Dutt}, year={2017}, - doi={http://dx.doi.org/10.18419/opus-9193}, + doi={dx.doi.org/10.18419/opus-9193}, } @article{vishwakarma2017data, @@ -63,7 +63,7 @@ @article{vishwakarma2017data pages={9824--9844}, year={2017}, publisher={Wiley Online Library}, - doi={https://doi.org/10.1002/2017WR021150}, + doi={doi.org/10.1002/2017WR021150}, } @@ -76,7 +76,7 @@ @article{wahr1998time pages={30205--30229}, year={1998}, publisher={Wiley Online Library}, - doi={https://doi.org/10.1029/98JB02844}, + doi={doi.org/10.1029/98JB02844}, } @article{wieczorek2018shtools, @@ -88,5 +88,5 @@ @article{wieczorek2018shtools pages={2574--2592}, year={2018}, publisher={Wiley Online Library}, - doi={https://doi.org/10.1029/2018GC007529}, + doi={doi.org/10.1029/2018GC007529}, } \ No newline at end of file diff --git a/paper.md b/paper.md index d5e80be9..c58a15ba 100644 --- a/paper.md +++ b/paper.md @@ -63,15 +63,15 @@ bibliography: paper.bib # Summary -`GRACE` (Gravity Recovery and Climate Experiment) satellite mission has been mapping mass changes near the surface of the Earth since 2002. Since mass redistribution at shorter temporal scales is dominated by hydrology, GRACE has transformed our understanding of changes in the hydrosphere. GRACE data has been used for monitoring and studying groundwater depletion, floods, droughts, etc. GRACE satellite products are typically released at various levels of complexity, often referred to as processing levels. Level 1 is the satellite instrument data that is processed to obtain GRACE Spherical Harmonics data level 2( `L2`). `L2` data: represents the mean monthly gravity field of the Earth. `L2` are further processed to obtain level 3 products; global gridded mass change estimates (`L3`) expressed as terrestrial water storage anomalies (`TWSA`). `L2` data are unconstrained gravity field solutions and are noisy, which are filtered and corrected for known artifacts and signals from solid Earth processes to obtain `L3` products that are useful for hydrology. Processing choices, such as filter properties and type, have a significant impact on the accuracy and the resolution of final gridded output. Therefore, `L3` users must be cautious when using GRACE data for specific applications. Since, majority of the GRACE data user community is not well versed with `L2` data processing, they often use off the shelf product with doubts on the efficacy of GRACE mission. Here we developed an open-source processing toolbox to provide users with more control over processing choices. A python module, called PySHbundle, is developed that converts GRACE `L2` Spherical Harmonics data products to `L3` `TWSA` products while applying the data-driven correction algorithm for reducing the impact of filtering on signal. With this contribution, we hope to enable further usage of GRACE data for Earth system science. +`GRACE` (Gravity Recovery and Climate Experiment) satellite mission has been mapping mass changes near the surface of the Earth since 2002. Since mass redistribution at shorter temporal scales is dominated by water mass transfer, GRACE has transformed Geosciences. GRACE satellite products are typically released at various levels of complexity, often referred to as processing levels. Level 1 is the satellite instrument data that is processed to obtain level 2 GRACE Spherical Harmonics data. `L2` are further processed to obtain level 3 products; global gridded mass change estimates (`L3`) expressed as terrestrial water storage anomalies (`TWSA`). `L2` data are noisy, which are filtered and corrected for known artifacts and signals from solid Earth processes to obtain `L3` products that are useful for hydrology. Processing choices, such as filter properties and type, have a significant impact on the accuracy and the resolution of final gridded output. Therefore, `L3` users must be cautious when using GRACE data for specific applications. Majority of the GRACE data user community is not well versed with `L2` data processing, and often use off the shelf `L3` product. Here we developed an open-source processing toolbox to provide users with more control over processing choices. A python module, called PySHbundle, is developed that converts GRACE `L2` Spherical Harmonics data products to `L3` `TWSA` products. With this contribution, we hope to enable further usage of GRACE data for Earth system science. # Introduction -The mission measures changes in the inter-satellite distance with a microwave ranging system that gives an accuracy in the range of micrometers [@wahr1998time]. When the satellite system comes in the vicinity of a temporal mass anomaly, the relative inter-satellite distance changes and it can be inverted to estimate the mass change near the surface of the Earth. Over the continental land surface, the hydrological processes are the major driver of the variation in mass anomaly at monthly to decadal scales. However various other signals such as oceanic and atmospheric variations, high frequency tidal mass changes, systemic correlated errors, etc. are also part of the obtained GRACE signals [@humphrey2023using]. +GRACE Satellite mission measures changes in the inter-satellite distance with a microwave ranging system micrometer precision [@wahr1998time]. When the satellite system comes in the vicinity of a temporal mass anomaly, the relative inter-satellite distance changes and it can be inverted to estimate the mass change near the surface of the Earth. Over the continental land surface, the hydrological processes are the major driver of the variation in mass anomaly at monthly to decadal scales. However various other signals such as oceanic and atmospheric variations, high frequency tidal mass changes, systemic correlated errors, etc. are also part of the obtained GRACE signals [@humphrey2023using]. -Obtaining `L3` products from GRACE data requires isolating the hydrological signal from GRACE signal, filtering to reduce noise to obtain `L2` data. Finally, the methods applied to convert the spherical harmonics data to mass changes introduces more subtle differences, potentially affecting the results. + several researchers in Jio sciences use level three GRACE data, which is obtained from `L2` Spherical harmonic coefficients. The procedure to convert `L2` to `L3` is called spherical harmonic synthesis. However, there are several pre-processing steps; such as anomaly calculation, replacing poor quality low degree coefficients, filtering, and correcting for signal damage due to filtering. -Some GRACE data processing tools are available based on the python programming language. These include [`gravity-toolkit`](https://gravity-toolkit.readthedocs.io/en/latest/) [@gravity-toolkit], [`ggtools`](https://pypi.org/project/ggtools/1.1.0/) [@ggtools] and [`GRACE-filter`](https://github.com/strawpants/GRACE-filter) [@GRACEfilter]. General tools for spheric harmonic analysis are also available, such as [`SHTools`](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2018GC007529) [@wieczorek2018shtools]. [`SHbundle`](https://www.gis.uni-stuttgart.de/en/research/downloads/shbundle) provide MATLAB scripts for Spheric Harmonic Synthesis and Spheric Harmonic Analysis. The first version of the code was developed in 1994 while the latest version with upgrades can be found dated 2018. +A few GRACE data processing tools are available based on the python programming language. These include [`gravity-toolkit`](https://gravity-toolkit.readthedocs.io/en/latest/) [@gravity-toolkit], [`ggtools`](https://pypi.org/project/ggtools/1.1.0/) [@ggtools] and [`GRACE-filter`](https://github.com/strawpants/GRACE-filter) [@GRACEfilter]. General tools for spheric harmonic analysis are also available, such as [`SHTools`](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2018GC007529) [@wieczorek2018shtools]. [`SHbundle`](https://www.gis.uni-stuttgart.de/en/research/downloads/shbundle) provide MATLAB scripts for Spheric Harmonic Synthesis and Spheric Harmonic Analysis. The first version of the code was developed in 1994 while the latest version with upgrades can be found dated 2018. # Statement of need @@ -85,14 +85,14 @@ By using Python and the GNU license, the package is accessible globally and alig # Implementation -Obtaining gridded fields from GRACE spherical harmonic coefficients consists of several steps, including obtaining the spherical harmonic coefficients from the data providers, replacement of poor coefficients, reducing noise using filtering approaches, etc. Mathematical details of the steps involved can be referred in [@vishwakarma2017understanding]. + Mathematical details of the steps involved can be referred in [@vishwakarma2017understanding]. Accordingly, the package consists of four main modules, `io`, `vizutils`, `pysh_core` and `shutils`. -1. `io`: extract the `L2` coefficients from any of `JPl`, `CSR` and `ITGZ` solutions. Followed by replacing the poorly measured degree 1, 2 and 3 spherical harmonics coefficients with data from Satellite Laser Ranging missions. And other pre-processing operations. +1. `io`: extract the `L2` coefficients from any of `JPl`, `CSR` and `ITGZ` solutions. Followed by replacing the poorly measured degree 1, 2 and 3 spherical harmonics coefficients with recommended datasets. 2. `vizutils`: plots the `L2` data to visually understand the coefficients, their uncertainties, mathematical functions used for further processing. -3. `pysh_core`: Scripts for the global spherical harmonics synthesis `gshs` to convert the `L2` data to global gridded `TWSA` data (`L3`). Others, calculating signal leakage (`gddc`) and basin-scale average (`Basinaverage`). +3. `pysh_core`: Scripts for the global spherical harmonics synthesis `gshs` to convert the `L2` data to global gridded `TWSA` data (`L3`). Calculating signal leakage (`gddc`), and basin-scale average (`Basinaverage`). 4. `shutils`: Helper scripts for applying `pysh_core`. Based on the main modules, we provide examples as jupyter notebooks for understanding and using spherical harmonics data and the package. diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000..8fcf65ce --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,53 @@ +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + + +[project] +name = "pyshbundle" +version = "0.3.0" +dependencies=[ + "pip", + "numpy", + "pandas", + "netCDF4", + "scipy", + "xarray", + "julian", + "scipy", + "geopandas", + "matplotlib", + "rasterio", + "shapely", + "tqdm", + "cartopy", + "ipykernel", + "jupyterlab", + "rioxarray", +] +authors = [ + { name="Amin Shakya", email="aminshk50@outlook.com"}, +] +maintainers = [ + {name="Abhishek Mhamane", email="vabhi.mhamane30@gmail.com"}, + {name="Vivek Kumar Yadav", email="viveky@iisc.ac.in"}, +] + +description = "PySHbundle: A Python implementation of GRACE Spherical Harmonics Synthesis MATLAB codes SHbundle" +readme = "README.md" +requires-python = ">=3.9" +classifiers=[ + 'Development Status :: 4 - Beta', + 'Intended Audience :: Science/Research', + 'License :: OSI Approved :: GNU General Public License v3 (GPLv3)', + 'Natural Language :: English', + 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.12', +] +keywords = ["Spherical Harmonics", "Geodesy", "Hydrology"] +license={file = "LICENSE.md"} + + +[project.urls] +Homepage = "https://github.com/lsmvivek/pyshbundle" +Issues = "https://github.com/lsmvivek/pyshbundle/issues" \ No newline at end of file