diff --git a/.dockerignore b/.dockerignore deleted file mode 100644 index 0d888ac2..00000000 --- a/.dockerignore +++ /dev/null @@ -1,35 +0,0 @@ -# Python Build # -################ -__pycache__ -build/ -dist/ -develop-eggs/ -run/ -wheels/ -*.egg-info/ -.installed.cfg -*.egg -.pytest_cache -pythonenv*/ -setup.cfg -# Jupyter # -########### -notebooks/ -.ipynb_checkpoints -Untitled.ipynb -# Documentation # -################# -requirements-dev.txt -environment.yml -readthedocs.yml -codecov.yml -postBuild -test/ -doc/ -# OS generated files # -###################### -.DS_Store -.DS_Store? -._* -.Spotlight-V100 -.Trashes diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..dd2dac53 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,123 @@ +# Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +- Offensive comments related to gender, gender identity and expression, sexual orientation, + disability, mental illness, physical appearance, body size, race, or religion +- Deliberate misgendering or use of "dead" or rejected names +- The use of sexualized language or imagery, and sexual attention or + advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Incitement or threats of violence towards any individual, + including encouraging a person to commit suicide or to engage in self-harm +- Publishing others' private information, such as a physical or email + address, without their explicit permission +- Advocating for, or encouraging, any of the above behavior +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior can be +reported to the organizational leaders responsible for enforcement. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This code of conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/) +[Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html) and +the [Geek Feminism](http://geekfeminism.wikia.com) +[Community Anti-Harassment Policy](http://geekfeminism.wikia.com/wiki/Community_anti-harassment/Policy). + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +We have adapted these documents for our own use under the terms of the +[Creative Commons Attribution License](https://creativecommons.org/licenses/by/4.0/). diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md new file mode 100644 index 00000000..6facbbfd --- /dev/null +++ b/CONTRIBUTORS.md @@ -0,0 +1,4 @@ +- Hugo Lecomte +- Yara Mohajerani +- [Tyler Sutterley (University of Washington)](http://psc.apl.uw.edu/people/investigators/tyler-sutterley/) +- [Isabella Velicogna (University of California, Irvine)](https://www.ess.uci.edu/~velicogna/pi.html) diff --git a/CONTRIBUTORS.rst b/CONTRIBUTORS.rst deleted file mode 100644 index 5bf3294e..00000000 --- a/CONTRIBUTORS.rst +++ /dev/null @@ -1,4 +0,0 @@ -- Hugo Lecomte (University of Strasbourg) -- `Yara Mohajerani (University of Washington) `_ -- `Tyler Sutterley (University of Washington) `_ -- `Isabella Velicogna (University of California, Irvine) `_ diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index 34543169..00000000 --- a/Dockerfile +++ /dev/null @@ -1,46 +0,0 @@ -FROM python:3.9-slim-buster - -LABEL Tyler Sutterley "tsutterl@uw.edu" - -ENV DEBIAN_FRONTEND="noninteractive" TZ="America/Los_Angeles" - -RUN useradd --create-home --shell /bin/bash gravity - -RUN apt-get update -y && \ - apt-get install -y --no-install-recommends \ - ca-certificates \ - git \ - libgeos-dev \ - libhdf5-dev \ - libnetcdf-dev \ - libproj-dev \ - libxml2-dev \ - libxslt1-dev \ - openssl \ - proj-data \ - proj-bin && \ - apt-get clean - -WORKDIR /home/gravity - -RUN pip3 install --no-cache-dir --no-binary=cartopy \ - cartopy \ - future \ - geoid-toolkit \ - h5py \ - lxml \ - matplotlib \ - netCDF4 \ - numpy \ - python-dateutil \ - pyyaml \ - scipy - -COPY . . - -RUN --mount=source=.git,target=.git,type=bind \ - pip install --no-cache-dir --no-deps . - -USER gravity - -CMD ["bash"] diff --git a/scripts/cnes_grace_sync.py b/access/cnes_grace_sync.py similarity index 100% rename from scripts/cnes_grace_sync.py rename to access/cnes_grace_sync.py diff --git a/scripts/esa_costg_swarm_sync.py b/access/esa_costg_swarm_sync.py similarity index 100% rename from scripts/esa_costg_swarm_sync.py rename to access/esa_costg_swarm_sync.py diff --git a/scripts/gfz_icgem_costg_ftp.py b/access/gfz_icgem_costg_ftp.py similarity index 100% rename from scripts/gfz_icgem_costg_ftp.py rename to access/gfz_icgem_costg_ftp.py diff --git a/scripts/gfz_isdc_dealiasing_ftp.py b/access/gfz_isdc_dealiasing_ftp.py similarity index 100% rename from scripts/gfz_isdc_dealiasing_ftp.py rename to access/gfz_isdc_dealiasing_ftp.py diff --git a/scripts/gfz_isdc_grace_ftp.py b/access/gfz_isdc_grace_ftp.py similarity index 100% rename from scripts/gfz_isdc_grace_ftp.py rename to access/gfz_isdc_grace_ftp.py diff --git a/scripts/itsg_graz_grace_sync.py b/access/itsg_graz_grace_sync.py similarity index 100% rename from scripts/itsg_graz_grace_sync.py rename to access/itsg_graz_grace_sync.py diff --git a/scripts/podaac_cumulus.py b/access/podaac_cumulus.py similarity index 100% rename from scripts/podaac_cumulus.py rename to access/podaac_cumulus.py diff --git a/scripts/aod1b_geocenter.py b/dealiasing/aod1b_geocenter.py similarity index 100% rename from scripts/aod1b_geocenter.py rename to dealiasing/aod1b_geocenter.py diff --git a/scripts/aod1b_oblateness.py b/dealiasing/aod1b_oblateness.py similarity index 100% rename from scripts/aod1b_oblateness.py rename to dealiasing/aod1b_oblateness.py diff --git a/scripts/dealiasing_global_uplift.py b/dealiasing/dealiasing_global_uplift.py similarity index 100% rename from scripts/dealiasing_global_uplift.py rename to dealiasing/dealiasing_global_uplift.py diff --git a/scripts/dealiasing_monthly_mean.py b/dealiasing/dealiasing_monthly_mean.py similarity index 100% rename from scripts/dealiasing_monthly_mean.py rename to dealiasing/dealiasing_monthly_mean.py diff --git a/doc/source/_assets/logo.png b/doc/source/_assets/logo.png new file mode 100644 index 00000000..23d0366b Binary files /dev/null and b/doc/source/_assets/logo.png differ diff --git a/doc/source/_static/style.css b/doc/source/_static/style.css index ecc98701..86f33a89 100644 --- a/doc/source/_static/style.css +++ b/doc/source/_static/style.css @@ -1,3 +1,18 @@ +/* color adjustments to fit logo theme */ +.wy-menu > .caption > span.caption-text { + color: #7acea3; +} +.wy-nav-top { + background-color: #7acea3; + color: #ffffff; +} +.wy-side-nav-search { + background-color: #7acea3; +} +.wy-side-nav-search input[type="text"] { + border-color: #281a2c; +} + /* fix for position of equation numbers * https://github.com/rtfd/sphinx_rtd_theme/issues/301 */ @@ -14,6 +29,7 @@ visibility: visible; margin-right: -0.7em; } + /* fix for property line spacing * https://github.com/rtfd/sphinx_rtd_theme/issues/1301 */ @@ -21,4 +37,9 @@ display: block !important; padding-right: 8px; max-width: 100%; -} \ No newline at end of file +} + +/* caption positions for tables and figures */ +.docutils caption { + caption-side: bottom; +} diff --git a/doc/source/api_reference/cnes_grace_sync.rst b/doc/source/api_reference/access/cnes_grace_sync.rst similarity index 81% rename from doc/source/api_reference/cnes_grace_sync.rst rename to doc/source/api_reference/access/cnes_grace_sync.rst index 15e2daf7..ee58cae7 100644 --- a/doc/source/api_reference/cnes_grace_sync.rst +++ b/doc/source/api_reference/access/cnes_grace_sync.rst @@ -7,7 +7,7 @@ cnes_grace_sync.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/cnes_grace_sync.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/access/cnes_grace_sync.py Calling Sequence ################ diff --git a/doc/source/api_reference/esa_costg_swarm_sync.rst b/doc/source/api_reference/access/esa_costg_swarm_sync.rst similarity index 82% rename from doc/source/api_reference/esa_costg_swarm_sync.rst rename to doc/source/api_reference/access/esa_costg_swarm_sync.rst index 2e63e482..eef1663b 100644 --- a/doc/source/api_reference/esa_costg_swarm_sync.rst +++ b/doc/source/api_reference/access/esa_costg_swarm_sync.rst @@ -7,7 +7,7 @@ esa_costg_swarm_sync.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/esa_costg_swarm_sync.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/access/esa_costg_swarm_sync.py Calling Sequence ################ diff --git a/doc/source/api_reference/gfz_icgem_costg_ftp.rst b/doc/source/api_reference/access/gfz_icgem_costg_ftp.rst similarity index 82% rename from doc/source/api_reference/gfz_icgem_costg_ftp.rst rename to doc/source/api_reference/access/gfz_icgem_costg_ftp.rst index df9f4e47..6dd2edaa 100644 --- a/doc/source/api_reference/gfz_icgem_costg_ftp.rst +++ b/doc/source/api_reference/access/gfz_icgem_costg_ftp.rst @@ -7,7 +7,7 @@ gfz_icgem_costg_ftp.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/gfz_icgem_costg_ftp.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/access/gfz_icgem_costg_ftp.py Calling Sequence ################ diff --git a/doc/source/api_reference/gfz_isdc_dealiasing_ftp.rst b/doc/source/api_reference/access/gfz_isdc_dealiasing_ftp.rst similarity index 82% rename from doc/source/api_reference/gfz_isdc_dealiasing_ftp.rst rename to doc/source/api_reference/access/gfz_isdc_dealiasing_ftp.rst index 923466a8..ca9af1e0 100644 --- a/doc/source/api_reference/gfz_isdc_dealiasing_ftp.rst +++ b/doc/source/api_reference/access/gfz_isdc_dealiasing_ftp.rst @@ -7,7 +7,7 @@ gfz_isdc_dealiasing_ftp.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/gfz_isdc_dealiasing_ftp.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/access/gfz_isdc_dealiasing_ftp.py Calling Sequence ################ diff --git a/doc/source/api_reference/gfz_isdc_grace_ftp.rst b/doc/source/api_reference/access/gfz_isdc_grace_ftp.rst similarity index 86% rename from doc/source/api_reference/gfz_isdc_grace_ftp.rst rename to doc/source/api_reference/access/gfz_isdc_grace_ftp.rst index f6f14ccd..033e5cc5 100644 --- a/doc/source/api_reference/gfz_isdc_grace_ftp.rst +++ b/doc/source/api_reference/access/gfz_isdc_grace_ftp.rst @@ -10,7 +10,7 @@ gfz_isdc_grace_ftp.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/gfz_isdc_grace_ftp.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/access/gfz_isdc_grace_ftp.py Calling Sequence ################ diff --git a/doc/source/api_reference/itsg_graz_grace_sync.rst b/doc/source/api_reference/access/itsg_graz_grace_sync.rst similarity index 82% rename from doc/source/api_reference/itsg_graz_grace_sync.rst rename to doc/source/api_reference/access/itsg_graz_grace_sync.rst index 4862ffe0..65fcfd9a 100644 --- a/doc/source/api_reference/itsg_graz_grace_sync.rst +++ b/doc/source/api_reference/access/itsg_graz_grace_sync.rst @@ -7,7 +7,7 @@ itsg_graz_grace_sync.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/itsg_graz_grace_sync.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/access/itsg_graz_grace_sync.py Calling Sequence ################ diff --git a/doc/source/api_reference/podaac_cumulus.rst b/doc/source/api_reference/access/podaac_cumulus.rst similarity index 84% rename from doc/source/api_reference/podaac_cumulus.rst rename to doc/source/api_reference/access/podaac_cumulus.rst index 2d680b18..274b5f56 100644 --- a/doc/source/api_reference/podaac_cumulus.rst +++ b/doc/source/api_reference/access/podaac_cumulus.rst @@ -8,7 +8,7 @@ podaac_cumulus.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/podaac_cumulus.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/access/podaac_cumulus.py Calling Sequence ################ diff --git a/doc/source/api_reference/aod1b_geocenter.rst b/doc/source/api_reference/dealiasing/aod1b_geocenter.rst similarity index 86% rename from doc/source/api_reference/aod1b_geocenter.rst rename to doc/source/api_reference/dealiasing/aod1b_geocenter.rst index 0d2524d6..14ca6606 100644 --- a/doc/source/api_reference/aod1b_geocenter.rst +++ b/doc/source/api_reference/dealiasing/aod1b_geocenter.rst @@ -12,7 +12,7 @@ aod1b_geocenter.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/aod1b_geocenter.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/dealiasing/aod1b_geocenter.py Calling Sequence ################ diff --git a/doc/source/api_reference/aod1b_oblateness.rst b/doc/source/api_reference/dealiasing/aod1b_oblateness.rst similarity index 86% rename from doc/source/api_reference/aod1b_oblateness.rst rename to doc/source/api_reference/dealiasing/aod1b_oblateness.rst index e6a7b87d..8fceda7d 100644 --- a/doc/source/api_reference/aod1b_oblateness.rst +++ b/doc/source/api_reference/dealiasing/aod1b_oblateness.rst @@ -12,7 +12,7 @@ aod1b_oblateness.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/aod1b_oblateness.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/dealiasing/aod1b_oblateness.py Calling Sequence ################ diff --git a/doc/source/api_reference/dealiasing_global_uplift.rst b/doc/source/api_reference/dealiasing/dealiasing_global_uplift.rst similarity index 92% rename from doc/source/api_reference/dealiasing_global_uplift.rst rename to doc/source/api_reference/dealiasing/dealiasing_global_uplift.rst index 92e0111b..0705b115 100644 --- a/doc/source/api_reference/dealiasing_global_uplift.rst +++ b/doc/source/api_reference/dealiasing/dealiasing_global_uplift.rst @@ -6,7 +6,7 @@ dealiasing_global_uplift.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/dealiasing_global_uplift.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/dealiasing/dealiasing_global_uplift.py Calling Sequence ################ diff --git a/doc/source/api_reference/dealiasing_monthly_mean.rst b/doc/source/api_reference/dealiasing/dealiasing_monthly_mean.rst similarity index 88% rename from doc/source/api_reference/dealiasing_monthly_mean.rst rename to doc/source/api_reference/dealiasing/dealiasing_monthly_mean.rst index 30f76257..ba27f356 100644 --- a/doc/source/api_reference/dealiasing_monthly_mean.rst +++ b/doc/source/api_reference/dealiasing/dealiasing_monthly_mean.rst @@ -12,7 +12,7 @@ dealiasing_monthly_mean.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/dealiasing_monthly_mean.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/dealiasing/dealiasing_monthly_mean.py Calling Sequence ################ diff --git a/doc/source/api_reference/calc_degree_one.rst b/doc/source/api_reference/geocenter/calc_degree_one.rst similarity index 97% rename from doc/source/api_reference/calc_degree_one.rst rename to doc/source/api_reference/geocenter/calc_degree_one.rst index d69fa4ab..0692a5d9 100644 --- a/doc/source/api_reference/calc_degree_one.rst +++ b/doc/source/api_reference/geocenter/calc_degree_one.rst @@ -6,7 +6,7 @@ calc_degree_one.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/calc_degree_one.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/geocenter/calc_degree_one.py Calling Sequence ################ diff --git a/doc/source/api_reference/monte_carlo_degree_one.rst b/doc/source/api_reference/geocenter/monte_carlo_degree_one.rst similarity index 97% rename from doc/source/api_reference/monte_carlo_degree_one.rst rename to doc/source/api_reference/geocenter/monte_carlo_degree_one.rst index 59d6f039..17810600 100644 --- a/doc/source/api_reference/monte_carlo_degree_one.rst +++ b/doc/source/api_reference/geocenter/monte_carlo_degree_one.rst @@ -7,7 +7,7 @@ monte_carlo_degree_one.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/monte_carlo_degree_one.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/geocenter/monte_carlo_degree_one.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_AIS_GrIS_maps.rst b/doc/source/api_reference/mapping/plot_AIS_GrIS_maps.rst similarity index 78% rename from doc/source/api_reference/plot_AIS_GrIS_maps.rst rename to doc/source/api_reference/mapping/plot_AIS_GrIS_maps.rst index 9d310fac..7d8e0028 100644 --- a/doc/source/api_reference/plot_AIS_GrIS_maps.rst +++ b/doc/source/api_reference/mapping/plot_AIS_GrIS_maps.rst @@ -6,7 +6,7 @@ plot_AIS_GrIS_maps.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_GrIS_maps.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_AIS_GrIS_maps.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_AIS_grid_3maps.rst b/doc/source/api_reference/mapping/plot_AIS_grid_3maps.rst similarity index 79% rename from doc/source/api_reference/plot_AIS_grid_3maps.rst rename to doc/source/api_reference/mapping/plot_AIS_grid_3maps.rst index 4e072445..47968ade 100644 --- a/doc/source/api_reference/plot_AIS_grid_3maps.rst +++ b/doc/source/api_reference/mapping/plot_AIS_grid_3maps.rst @@ -6,7 +6,7 @@ plot_AIS_grid_3maps.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_grid_3maps.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_AIS_grid_3maps.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_AIS_grid_4maps.rst b/doc/source/api_reference/mapping/plot_AIS_grid_4maps.rst similarity index 79% rename from doc/source/api_reference/plot_AIS_grid_4maps.rst rename to doc/source/api_reference/mapping/plot_AIS_grid_4maps.rst index 4ecf1ee8..41b45f43 100644 --- a/doc/source/api_reference/plot_AIS_grid_4maps.rst +++ b/doc/source/api_reference/mapping/plot_AIS_grid_4maps.rst @@ -6,7 +6,7 @@ plot_AIS_grid_4maps.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_grid_4maps.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_AIS_grid_4maps.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_AIS_grid_maps.rst b/doc/source/api_reference/mapping/plot_AIS_grid_maps.rst similarity index 79% rename from doc/source/api_reference/plot_AIS_grid_maps.rst rename to doc/source/api_reference/mapping/plot_AIS_grid_maps.rst index 1400daee..6eba7179 100644 --- a/doc/source/api_reference/plot_AIS_grid_maps.rst +++ b/doc/source/api_reference/mapping/plot_AIS_grid_maps.rst @@ -6,7 +6,7 @@ plot_AIS_grid_maps.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_grid_maps.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_AIS_grid_maps.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_AIS_grid_movie.rst b/doc/source/api_reference/mapping/plot_AIS_grid_movie.rst similarity index 79% rename from doc/source/api_reference/plot_AIS_grid_movie.rst rename to doc/source/api_reference/mapping/plot_AIS_grid_movie.rst index 43fecb5c..83d41c15 100644 --- a/doc/source/api_reference/plot_AIS_grid_movie.rst +++ b/doc/source/api_reference/mapping/plot_AIS_grid_movie.rst @@ -6,7 +6,7 @@ plot_AIS_grid_movie.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_grid_movie.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_AIS_grid_movie.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_AIS_regional_maps.rst b/doc/source/api_reference/mapping/plot_AIS_regional_maps.rst similarity index 79% rename from doc/source/api_reference/plot_AIS_regional_maps.rst rename to doc/source/api_reference/mapping/plot_AIS_regional_maps.rst index 4bcd8b8f..2ecbceef 100644 --- a/doc/source/api_reference/plot_AIS_regional_maps.rst +++ b/doc/source/api_reference/mapping/plot_AIS_regional_maps.rst @@ -6,7 +6,7 @@ plot_AIS_regional_maps.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_regional_maps.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_AIS_regional_maps.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_AIS_regional_movie.rst b/doc/source/api_reference/mapping/plot_AIS_regional_movie.rst similarity index 80% rename from doc/source/api_reference/plot_AIS_regional_movie.rst rename to doc/source/api_reference/mapping/plot_AIS_regional_movie.rst index fcd604bd..39ed1b42 100644 --- a/doc/source/api_reference/plot_AIS_regional_movie.rst +++ b/doc/source/api_reference/mapping/plot_AIS_regional_movie.rst @@ -6,7 +6,7 @@ plot_AIS_regional_movie.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_AIS_regional_movie.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_AIS_regional_movie.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_GrIS_grid_3maps.rst b/doc/source/api_reference/mapping/plot_GrIS_grid_3maps.rst similarity index 80% rename from doc/source/api_reference/plot_GrIS_grid_3maps.rst rename to doc/source/api_reference/mapping/plot_GrIS_grid_3maps.rst index 122c7fb8..729bf1c5 100644 --- a/doc/source/api_reference/plot_GrIS_grid_3maps.rst +++ b/doc/source/api_reference/mapping/plot_GrIS_grid_3maps.rst @@ -6,7 +6,7 @@ plot_GrIS_grid_3maps.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_GrIS_grid_3maps.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_GrIS_grid_3maps.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_GrIS_grid_5maps.rst b/doc/source/api_reference/mapping/plot_GrIS_grid_5maps.rst similarity index 80% rename from doc/source/api_reference/plot_GrIS_grid_5maps.rst rename to doc/source/api_reference/mapping/plot_GrIS_grid_5maps.rst index 1e840e3d..6760dd29 100644 --- a/doc/source/api_reference/plot_GrIS_grid_5maps.rst +++ b/doc/source/api_reference/mapping/plot_GrIS_grid_5maps.rst @@ -6,7 +6,7 @@ plot_GrIS_grid_5maps.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_GrIS_grid_5maps.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_GrIS_grid_5maps.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_GrIS_grid_maps.rst b/doc/source/api_reference/mapping/plot_GrIS_grid_maps.rst similarity index 79% rename from doc/source/api_reference/plot_GrIS_grid_maps.rst rename to doc/source/api_reference/mapping/plot_GrIS_grid_maps.rst index eaca7b98..7103e776 100644 --- a/doc/source/api_reference/plot_GrIS_grid_maps.rst +++ b/doc/source/api_reference/mapping/plot_GrIS_grid_maps.rst @@ -6,7 +6,7 @@ plot_GrIS_grid_maps.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_GrIS_grid_maps.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_GrIS_grid_maps.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_GrIS_grid_movie.rst b/doc/source/api_reference/mapping/plot_GrIS_grid_movie.rst similarity index 80% rename from doc/source/api_reference/plot_GrIS_grid_movie.rst rename to doc/source/api_reference/mapping/plot_GrIS_grid_movie.rst index 89ed454f..c93ffb24 100644 --- a/doc/source/api_reference/plot_GrIS_grid_movie.rst +++ b/doc/source/api_reference/mapping/plot_GrIS_grid_movie.rst @@ -6,7 +6,7 @@ plot_GrIS_grid_movie.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_GrIS_grid_movie.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_GrIS_grid_movie.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_global_grid_3maps.rst b/doc/source/api_reference/mapping/plot_global_grid_3maps.rst similarity index 81% rename from doc/source/api_reference/plot_global_grid_3maps.rst rename to doc/source/api_reference/mapping/plot_global_grid_3maps.rst index 6c0ba94c..9f01781a 100644 --- a/doc/source/api_reference/plot_global_grid_3maps.rst +++ b/doc/source/api_reference/mapping/plot_global_grid_3maps.rst @@ -6,7 +6,7 @@ plot_global_grid_3maps.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_global_grid_3maps.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_global_grid_3maps.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_global_grid_4maps.rst b/doc/source/api_reference/mapping/plot_global_grid_4maps.rst similarity index 81% rename from doc/source/api_reference/plot_global_grid_4maps.rst rename to doc/source/api_reference/mapping/plot_global_grid_4maps.rst index 80dbf72d..556d6f98 100644 --- a/doc/source/api_reference/plot_global_grid_4maps.rst +++ b/doc/source/api_reference/mapping/plot_global_grid_4maps.rst @@ -6,7 +6,7 @@ plot_global_grid_4maps.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_global_grid_4maps.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_global_grid_4maps.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_global_grid_5maps.rst b/doc/source/api_reference/mapping/plot_global_grid_5maps.rst similarity index 81% rename from doc/source/api_reference/plot_global_grid_5maps.rst rename to doc/source/api_reference/mapping/plot_global_grid_5maps.rst index 8b217506..b0538d79 100644 --- a/doc/source/api_reference/plot_global_grid_5maps.rst +++ b/doc/source/api_reference/mapping/plot_global_grid_5maps.rst @@ -6,7 +6,7 @@ plot_global_grid_5maps.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_global_grid_5maps.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_global_grid_5maps.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_global_grid_9maps.rst b/doc/source/api_reference/mapping/plot_global_grid_9maps.rst similarity index 81% rename from doc/source/api_reference/plot_global_grid_9maps.rst rename to doc/source/api_reference/mapping/plot_global_grid_9maps.rst index de3c0543..1b8c55cb 100644 --- a/doc/source/api_reference/plot_global_grid_9maps.rst +++ b/doc/source/api_reference/mapping/plot_global_grid_9maps.rst @@ -6,7 +6,7 @@ plot_global_grid_9maps.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_global_grid_9maps.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_global_grid_9maps.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_global_grid_maps.rst b/doc/source/api_reference/mapping/plot_global_grid_maps.rst similarity index 81% rename from doc/source/api_reference/plot_global_grid_maps.rst rename to doc/source/api_reference/mapping/plot_global_grid_maps.rst index af5419ac..a2286b4b 100644 --- a/doc/source/api_reference/plot_global_grid_maps.rst +++ b/doc/source/api_reference/mapping/plot_global_grid_maps.rst @@ -6,7 +6,7 @@ plot_global_grid_maps.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_global_grid_maps.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_global_grid_maps.py Calling Sequence ################ diff --git a/doc/source/api_reference/plot_global_grid_movie.rst b/doc/source/api_reference/mapping/plot_global_grid_movie.rst similarity index 82% rename from doc/source/api_reference/plot_global_grid_movie.rst rename to doc/source/api_reference/mapping/plot_global_grid_movie.rst index 0461c659..a8818f5b 100644 --- a/doc/source/api_reference/plot_global_grid_movie.rst +++ b/doc/source/api_reference/mapping/plot_global_grid_movie.rst @@ -6,7 +6,7 @@ plot_global_grid_movie.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/plot_global_grid_movie.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/mapping/plot_global_grid_movie.py Calling Sequence ################ diff --git a/doc/source/api_reference/calc_harmonic_resolution.rst b/doc/source/api_reference/scripts/calc_harmonic_resolution.rst similarity index 100% rename from doc/source/api_reference/calc_harmonic_resolution.rst rename to doc/source/api_reference/scripts/calc_harmonic_resolution.rst diff --git a/doc/source/api_reference/calc_mascon.rst b/doc/source/api_reference/scripts/calc_mascon.rst similarity index 100% rename from doc/source/api_reference/calc_mascon.rst rename to doc/source/api_reference/scripts/calc_mascon.rst diff --git a/doc/source/api_reference/calc_sensitivity_kernel.rst b/doc/source/api_reference/scripts/calc_sensitivity_kernel.rst similarity index 100% rename from doc/source/api_reference/calc_sensitivity_kernel.rst rename to doc/source/api_reference/scripts/calc_sensitivity_kernel.rst diff --git a/doc/source/api_reference/combine_harmonics.rst b/doc/source/api_reference/scripts/combine_harmonics.rst similarity index 100% rename from doc/source/api_reference/combine_harmonics.rst rename to doc/source/api_reference/scripts/combine_harmonics.rst diff --git a/doc/source/api_reference/convert_harmonics.rst b/doc/source/api_reference/scripts/convert_harmonics.rst similarity index 100% rename from doc/source/api_reference/convert_harmonics.rst rename to doc/source/api_reference/scripts/convert_harmonics.rst diff --git a/doc/source/api_reference/grace_mean_harmonics.rst b/doc/source/api_reference/scripts/grace_mean_harmonics.rst similarity index 100% rename from doc/source/api_reference/grace_mean_harmonics.rst rename to doc/source/api_reference/scripts/grace_mean_harmonics.rst diff --git a/doc/source/api_reference/grace_raster_grids.rst b/doc/source/api_reference/scripts/grace_raster_grids.rst similarity index 100% rename from doc/source/api_reference/grace_raster_grids.rst rename to doc/source/api_reference/scripts/grace_raster_grids.rst diff --git a/doc/source/api_reference/grace_spatial_error.rst b/doc/source/api_reference/scripts/grace_spatial_error.rst similarity index 100% rename from doc/source/api_reference/grace_spatial_error.rst rename to doc/source/api_reference/scripts/grace_spatial_error.rst diff --git a/doc/source/api_reference/grace_spatial_maps.rst b/doc/source/api_reference/scripts/grace_spatial_maps.rst similarity index 100% rename from doc/source/api_reference/grace_spatial_maps.rst rename to doc/source/api_reference/scripts/grace_spatial_maps.rst diff --git a/doc/source/api_reference/mascon_reconstruct.rst b/doc/source/api_reference/scripts/mascon_reconstruct.rst similarity index 100% rename from doc/source/api_reference/mascon_reconstruct.rst rename to doc/source/api_reference/scripts/mascon_reconstruct.rst diff --git a/doc/source/api_reference/piecewise_grace_maps.rst b/doc/source/api_reference/scripts/piecewise_grace_maps.rst similarity index 100% rename from doc/source/api_reference/piecewise_grace_maps.rst rename to doc/source/api_reference/scripts/piecewise_grace_maps.rst diff --git a/doc/source/api_reference/regress_grace_maps.rst b/doc/source/api_reference/scripts/regress_grace_maps.rst similarity index 100% rename from doc/source/api_reference/regress_grace_maps.rst rename to doc/source/api_reference/scripts/regress_grace_maps.rst diff --git a/doc/source/api_reference/run_sea_level_equation.rst b/doc/source/api_reference/scripts/run_sea_level_equation.rst similarity index 100% rename from doc/source/api_reference/run_sea_level_equation.rst rename to doc/source/api_reference/scripts/run_sea_level_equation.rst diff --git a/doc/source/api_reference/scale_grace_maps.rst b/doc/source/api_reference/scripts/scale_grace_maps.rst similarity index 100% rename from doc/source/api_reference/scale_grace_maps.rst rename to doc/source/api_reference/scripts/scale_grace_maps.rst diff --git a/doc/source/api_reference/make_grace_index.rst b/doc/source/api_reference/utilities/make_grace_index.rst similarity index 78% rename from doc/source/api_reference/make_grace_index.rst rename to doc/source/api_reference/utilities/make_grace_index.rst index a3b77b82..b0f732e6 100644 --- a/doc/source/api_reference/make_grace_index.rst +++ b/doc/source/api_reference/utilities/make_grace_index.rst @@ -6,7 +6,7 @@ make_grace_index.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/make_grace_index.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/utilities/make_grace_index.py Calling Sequence ################ diff --git a/doc/source/api_reference/quick_mascon_plot.rst b/doc/source/api_reference/utilities/quick_mascon_plot.rst similarity index 77% rename from doc/source/api_reference/quick_mascon_plot.rst rename to doc/source/api_reference/utilities/quick_mascon_plot.rst index 557f634c..da0911b2 100644 --- a/doc/source/api_reference/quick_mascon_plot.rst +++ b/doc/source/api_reference/utilities/quick_mascon_plot.rst @@ -6,7 +6,7 @@ quick_mascon_plot.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/quick_mascon_plot.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/utilities/quick_mascon_plot.py Calling Sequence ################ diff --git a/doc/source/api_reference/quick_mascon_regress.rst b/doc/source/api_reference/utilities/quick_mascon_regress.rst similarity index 77% rename from doc/source/api_reference/quick_mascon_regress.rst rename to doc/source/api_reference/utilities/quick_mascon_regress.rst index 75082f3e..5b951bcc 100644 --- a/doc/source/api_reference/quick_mascon_regress.rst +++ b/doc/source/api_reference/utilities/quick_mascon_regress.rst @@ -6,7 +6,7 @@ quick_mascon_regress.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/quick_mascon_regress.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/utilities/quick_mascon_regress.py Calling Sequence ################ diff --git a/doc/source/api_reference/run_grace_date.rst b/doc/source/api_reference/utilities/run_grace_date.rst similarity index 85% rename from doc/source/api_reference/run_grace_date.rst rename to doc/source/api_reference/utilities/run_grace_date.rst index 6f34775c..4638677f 100644 --- a/doc/source/api_reference/run_grace_date.rst +++ b/doc/source/api_reference/utilities/run_grace_date.rst @@ -10,7 +10,7 @@ run_grace_date.py `Source code`__ -.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/scripts/run_grace_date.py +.. __: https://github.com/tsutterley/gravity-toolkit/blob/main/utilities/run_grace_date.py Calling Sequence ################ diff --git a/doc/source/getting_started/Background.rst b/doc/source/background/Background.rst similarity index 56% rename from doc/source/getting_started/Background.rst rename to doc/source/background/Background.rst index 945a4526..db3ae4a1 100644 --- a/doc/source/getting_started/Background.rst +++ b/doc/source/background/Background.rst @@ -2,84 +2,6 @@ Background ========== - -This documentation is intended to explain how to compute spatial and time series -estimates using GRACE/GRACE-FO time-variable gravity measurements. -``gravity-toolkit`` is a Python-based geophysical software that reads -GRACE/GRACE-FO time-variable gravity solutions for estimating regional mass change. -A suite of geophysical corrections can be applied to the gravity solutions to -optimize the GRACE/GRACE-FO data for particular applications. -This software was developed with the goal of supporting science applications for -time-variable gravity. -``gravity-toolkit`` provides data access utilities for ascii, netCDF4, HDF5 and gfc file formats. -``gravity-toolkit`` also provides some very high-level plotting programs through the -use of `Jupyter Notebooks <../user_guide/Examples.html>`_. - -.. graphviz:: - :caption: Data Processing Framework - :align: center - - digraph { - G [label="GRACE/GRACE-FO\ntime-variable gravity" - fontname="Lato" - fontsize=11 - shape=box - style="filled" - color="#7570b3"] - A [label="Non-tidal Ocean and\nAtmospheric Variation" - fontname="Lato" - fontsize=11 - shape=box - style="filled" - color="#7570b3"] - I [label="Glacial Isostatic\nAdjustment" - fontname="Lato" - fontsize=11 - shape=box - style="filled" - color="#7570b3"] - W [label="Terrestrial Water\nStorage" - fontname="Lato" - fontsize=11 - shape=box - style="filled" - color="#7570b3"] - R [label="gravity-toolkit" - fontname="Lato" - fontsize=11 - shape=box - style="filled" - color="gray"] - S [label="Spatial Maps" - fontname="Lato" - fontsize=11 - shape=box - style="filled" - color="#1b9e77" - URL="Spatial-Maps.html"] - T [label="Time Series Analysis" - fontname="Lato" - fontsize=11 - shape=box - style="filled" - color="#1b9e77" - URL="Time-Series-Analysis.html"] - D [label="Geocenter Variation" - fontname="Lato" - fontsize=11 - shape=box - style="filled" - color="#1b9e77" - URL="Geocenter-Variations.html"] - G -> R [arrowsize=0.8] - A -> R [arrowsize=0.8] - I -> R [arrowsize=0.8] - W -> R [arrowsize=0.8] - R -> S [arrowsize=0.8] - R -> T [arrowsize=0.8] - R -> D [arrowsize=0.8] - } - Measurement Principle ##################### @@ -91,12 +13,14 @@ Data from these instruments are combined to estimate the distance between the tw the positions of the satellites in space, the pointing vector of the satellites and any non-gravitational accelerations the satellites experience. -GRACE/GRACE-FO senses changes in gravity by measuring the change in distance between the two twin satellites: +.. admonition:: The Big Idea + + GRACE/GRACE-FO senses changes in gravity by measuring the change in distance between the two twin satellites: -1) As the satellites approach a mass anomaly: leading satellite "feels" a greater gravitational attraction and accelerates |rarr| **distance increases** -2) As the trailing satellite approaches: greater gravitational attraction |rarr| accelerated by the mass anomaly |rarr| **distance decreases** -3) Leading satellite passes the anomaly: gravitational attraction pulls backwards |rarr| decelerated by the mass anomaly |rarr| **distance decreases** -4) When the trailing satellite passes the anomaly and leading satellite is far from the anomaly: trailing satellite decelerated by mass anomaly |rarr| **distance increases back to standard separation** + 1) As the satellites approach a mass anomaly: leading satellite "feels" a greater gravitational attraction and accelerates |rarr| **distance increases** + 2) As the trailing satellite approaches: greater gravitational attraction |rarr| accelerated by the mass anomaly |rarr| **distance decreases** + 3) Leading satellite passes the anomaly: gravitational attraction pulls backwards |rarr| decelerated by the mass anomaly |rarr| **distance decreases** + 4) When the trailing satellite passes the anomaly and leading satellite is far from the anomaly: trailing satellite decelerated by mass anomaly |rarr| **distance increases back to standard separation** All the onboard measurements are combined with estimates of the background gravity field, atmospheric and oceanic variability, and tides to create the `Level-2 spherical harmonic product of GRACE and GRACE-FO`__. @@ -114,9 +38,11 @@ the `Jet Propulsion Laboratory (JPL) `_. GRACE/GRACE-FO data is freely available in the US from the `NASA Physical Oceanography Distributed Active Archive Center (PO.DAAC) `_ and internationally from the `GFZ Information System and Data Center (ISDC) `_. -There are programs within this repository that can sync with both of these data archives: -``podaac_cumulus.py`` for `PO.DAAC AWS `_ and -``gfz_isdc_grace_ftp.py`` for the `GFZ ISDC `_. + +.. tip:: + There are programs within this repository that can sync with both of these data archives: + ``podaac_cumulus.py`` for `PO.DAAC AWS `_ and + ``gfz_isdc_grace_ftp.py`` for the `GFZ ISDC `_. Geoid Height ############ diff --git a/doc/source/getting_started/Geocenter-Variations.rst b/doc/source/background/Geocenter-Variations.rst similarity index 91% rename from doc/source/getting_started/Geocenter-Variations.rst rename to doc/source/background/Geocenter-Variations.rst index 7650c04a..b6f3d548 100644 --- a/doc/source/getting_started/Geocenter-Variations.rst +++ b/doc/source/background/Geocenter-Variations.rst @@ -14,9 +14,12 @@ For most science applications of time-variable gravity, a coordinate system with an origin coinciding with the Earth's center of figure (CF) is required. Geocenter variations are represented by the degree one spherical harmonic terms. -The exclusion of degree one terms can have a significant impact on estimates -of ocean mass, ice sheet mass change, and terrestrial hydrology due to -far-field signals leaking into each regional estimate :cite:p:`Velicogna:2009ft`. + +.. important:: + + The exclusion of degree one terms can have a significant impact on estimates + of ocean mass, ice sheet mass change, and terrestrial hydrology due to + far-field signals leaking into each regional estimate :cite:p:`Velicogna:2009ft`. ``calc_degree_one.py`` calculates coefficients of degree one by combining GRACE/GRACE-FO spherical harmonic products with estimates of @@ -35,7 +38,7 @@ land and ocean components using a land-function The oceanic components of the change in degree one spherical harmonics (:math:`\Delta C^{ocean}_{10}`, :math:`\Delta C^{ocean}_{11}`, and :math:`\Delta S^{ocean}_{11}`) can then be calculated from the changes in ocean mass, -:math:`\Delta\sigma_{ocean}(\theta,\phi),Swenson:2008cr,Wahr:1998hy`. +:math:`\Delta\sigma_{ocean}(\theta,\phi)` :cite:p:`Swenson:2008cr,Wahr:1998hy`. If the oceanic contributions to degree one variability (:math:`\Delta C^{ocean}_{10}`, :math:`\Delta C^{ocean}_{11}`, and :math:`\Delta S^{ocean}_{11}`) can be estimated from an ocean model, then the unknown complete degree one terms diff --git a/doc/source/getting_started/Spatial-Maps.rst b/doc/source/background/Spatial-Maps.rst similarity index 93% rename from doc/source/getting_started/Spatial-Maps.rst rename to doc/source/background/Spatial-Maps.rst index bbb618d8..f6126a5b 100644 --- a/doc/source/getting_started/Spatial-Maps.rst +++ b/doc/source/background/Spatial-Maps.rst @@ -9,8 +9,10 @@ To calculate accurate maps of spatial variability, several processing steps need to convert the data into the proper reference frame, reduce the impact of noisy data, remove unwanted sources of gravitational variability, and convert to appropriate units. -The ``grace_spatial_maps.py`` program will output spatial files in ascii, netCDF4 or HDF5 format -for each GRACE/GRACE-FO month. +.. tip:: + + The ``grace_spatial_maps.py`` program will output spatial files in ascii, netCDF4 or HDF5 format + for each GRACE/GRACE-FO month. Load Love Numbers ################# @@ -54,8 +56,11 @@ is adjusted by setting the ``--reference`` command line option to ``'CF'``. Low-Degree Harmonics #################### -For both GRACE and GRACE-FO, there have been operational issues that have affected the -quality of the time-variable gravity fields. +.. important:: + + For both GRACE and GRACE-FO, there have been operational issues that have affected the + quality of the time-variable gravity fields. + During the late stages of the GRACE mission, procedures were enacted to preserve the battery life of the GRACE satellites and extend the mission lifetime. This included turning off the accelerometer and microwave ranging instrument (MWI) to @@ -111,8 +116,11 @@ These mass transport processes include but are not limited to terrestrial water glacier and ice sheet mass, atmospheric and oceanic circulation and geodynamic processes. In order to isolate the mass change of a single process, each of the other processes needs to be independently estimated and removed from the GRACE/GRACE-FO data. -Uncertainties in the components removed from the GRACE/GRACE-FO data will directly -impact the precision of the final mass balance estimate. + +.. important:: + + Uncertainties in the components removed from the GRACE/GRACE-FO data will directly + impact the precision of any final mass balance estimate. Filtering ######### diff --git a/doc/source/getting_started/Time-Series-Analysis.rst b/doc/source/background/Time-Series-Analysis.rst similarity index 96% rename from doc/source/getting_started/Time-Series-Analysis.rst rename to doc/source/background/Time-Series-Analysis.rst index 3eb2f7af..86f5234e 100644 --- a/doc/source/getting_started/Time-Series-Analysis.rst +++ b/doc/source/background/Time-Series-Analysis.rst @@ -62,6 +62,6 @@ The ``calc_mascon.py`` program additionally calculates the GRACE/GRACE-FO error harmonics following :cite:t:`Wahr:2006bx`. The ``calc_mascon.py`` program will output a text file of the time series for each mascon -(format: GRACE/GRACE-FO month, mid-month date in decimal-year format, -estimated monthly mass anomaly [Gt], estimated monthly error [Gt], -mascon area [km\ :sup:`2`]). +with columns: GRACE/GRACE-FO month, mid-month date in decimal-year format, +estimated monthly mass anomaly [Gt], estimated monthly error [Gt], and +mascon area [km\ :sup:`2`]. diff --git a/doc/source/conf.py b/doc/source/conf.py index 6ae6ba79..a6316112 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -86,11 +86,14 @@ # a list of builtin themes. # html_theme = 'sphinx_rtd_theme' -html_theme_options = {} +html_theme_options = { + "logo_only": True, +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". +html_logo = "_assets/logo.png" html_static_path = ['_static'] repository_url = f"https://github.com/tsutterley/gravity-toolkit" html_context = { diff --git a/doc/source/getting_started/Code-of-Conduct.rst b/doc/source/getting_started/Code-of-Conduct.rst new file mode 100644 index 00000000..eea72ab3 --- /dev/null +++ b/doc/source/getting_started/Code-of-Conduct.rst @@ -0,0 +1,2 @@ +.. include:: ../../../CODE_OF_CONDUCT.md + :parser: commonmark \ No newline at end of file diff --git a/doc/source/getting_started/Contributing.rst b/doc/source/getting_started/Contributing.rst index 43bff6cf..e0f8ac3b 100644 --- a/doc/source/getting_started/Contributing.rst +++ b/doc/source/getting_started/Contributing.rst @@ -2,9 +2,16 @@ Contribution Guidelines ======================= -We welcome and invite contributions from anyone at any career stage and with any amount of coding experience towards the development of ``gravity-toolkit``. -We appreciate any and all contributions made to the project. -You will be recognized for your work by being listed as one of the `project contributors <./Citations.html#contributors>`_. +``gravity-toolkit`` is an open source project. +We welcome any help in maintaining and developing the software and documentation. +Anyone at *any career stage and with any level of coding experience* can contribute towards the development of ``gravity-toolkit``. +Please read our `code of conduct <./Code-of-Conduct.html>`_ before contributing to ``gravity-toolkit`` development. +You will be recognized for your work by being listed as one of the `project contributors <../project/Contributors.html>`_. + +.. note:: + + If you have found a problem in ``gravity-toolkit``, or you would like to suggest an improvement or modification, + please submit a `GitHub issue `_ and we will get back to you. Ways to Contribute ------------------ @@ -29,10 +36,10 @@ If not, *please* submit a new issue so that we are made aware of the problem. Please provide as much detail as possible when writing the description of your bug report. Providing information and examples will help us resolve issues faster. -Contributing Code or Examples ------------------------------ +Contributing Code +----------------- We follow a standard Forking Workflow for code changes and additions. -Submitted code goes through the pull request process for `continuous integration (CI) testing <./Contributing.html#continuous-integration>`_ and comments. +Submitted code goes through the pull request process for `continuous integration (CI) testing <../project/Testing.html#continuous-integration>`_ and comments. General Guidelines ^^^^^^^^^^^^^^^^^^ @@ -60,21 +67,10 @@ Adding Examples Examples may be in the form of executable scripts or interactive `Jupyter Notebooks <../user_guide/Examples.html>`_. Fully working (but unrendered) examples should be submitted with the same steps as above. -Continuous Integration -^^^^^^^^^^^^^^^^^^^^^^ -We use `GitHub Actions `_ continuous integration (CI) services to build and test the project on Linux (Ubuntu) and Mac Operating Systems. -The configuration files for this service are in `.github/workflows `_. -The workflows rely on the `environment.yml `_ and test `requirements.txt `_ files to install the required dependencies. - -The GitHub Actions jobs include: - -* Running `flake8 `_ to check the code for style and compilation errors -* Running the test suite on multiple combinations of OS and Python version - Semantic Commit Messages ^^^^^^^^^^^^^^^^^^^^^^^^ -Commit messages should follow the `Conventional Commits `_ specification: +Please follow the `Conventional Commits `_ specification for your commit messages to help organize the pull requests: .. code-block:: bash @@ -89,5 +85,5 @@ where ```` is one of the following: - ``docs``: changing the documentation - ``style``: changing the line order or adding comments - ``refactor``: changing the names of variables or programs -- ``ci``: changing the `continuous integration <./Contributing.html#continuous-integration>`_ configuration files or scripts -- ``test``: adding or updating `continuous integration tests <./Contributing.html#continuous-integration>`_ +- ``ci``: changing the `continuous integration <../project/Testing.html#continuous-integration>`_ configuration files or scripts +- ``test``: adding or updating `continuous integration tests <../project/Testing.html#continuous-integration>`_ diff --git a/doc/source/getting_started/Getting-Started.rst b/doc/source/getting_started/Getting-Started.rst index 3bf60a9c..b42b5866 100644 --- a/doc/source/getting_started/Getting-Started.rst +++ b/doc/source/getting_started/Getting-Started.rst @@ -2,6 +2,88 @@ Getting Started =============== + + +This documentation is intended to explain how to compute spatial and time series +estimates using GRACE/GRACE-FO time-variable gravity measurements. +``gravity-toolkit`` is a Python-based geophysical software that reads +GRACE/GRACE-FO time-variable gravity solutions for estimating regional mass change. +A suite of geophysical corrections can be applied to the gravity solutions to +optimize the GRACE/GRACE-FO data for particular applications. +This software was developed with the goal of supporting science applications for +time-variable gravity. +``gravity-toolkit`` provides data access utilities for ascii, netCDF4, HDF5 and gfc file formats. +``gravity-toolkit`` also provides some very high-level plotting programs through the +use of `Jupyter Notebooks <../user_guide/Examples.html>`_. + +.. graphviz:: + :caption: Data Processing Framework + :align: center + + digraph { + G [label="GRACE/GRACE-FO\ntime-variable gravity" + fontname="Lato" + fontsize=11 + shape=box + style="filled" + color="#7570b3"] + A [label="Non-tidal Ocean and\nAtmospheric Variation" + fontname="Lato" + fontsize=11 + shape=box + style="filled" + color="#7570b3"] + I [label="Glacial Isostatic\nAdjustment" + fontname="Lato" + fontsize=11 + shape=box + style="filled" + color="#7570b3"] + W [label="Terrestrial Water\nStorage" + fontname="Lato" + fontsize=11 + shape=box + style="filled" + color="#7570b3"] + R [label="gravity-toolkit" + fontname="Lato" + fontsize=11 + shape=box + style="filled" + color="gray"] + S [label="Spatial Maps" + fontname="Lato" + fontsize=11 + shape=box + style="filled" + color="#1b9e77" + URL="Spatial-Maps.html"] + T [label="Time Series Analysis" + fontname="Lato" + fontsize=11 + shape=box + style="filled" + color="#1b9e77" + URL="Time-Series-Analysis.html"] + D [label="Geocenter Variation" + fontname="Lato" + fontsize=11 + shape=box + style="filled" + color="#1b9e77" + URL="Geocenter-Variations.html"] + G -> R [arrowsize=0.8] + A -> R [arrowsize=0.8] + I -> R [arrowsize=0.8] + W -> R [arrowsize=0.8] + R -> S [arrowsize=0.8] + R -> T [arrowsize=0.8] + R -> D [arrowsize=0.8] + } + +Steps to Get Started +#################### + - `Register at NASA Earthdata <./NASA-Earthdata.html>`_ - Run `podaac_cumulus.py `_ program with your NASA Earthdata credentials to acquire GRACE/GRACE-FO and auxiliary data diff --git a/doc/source/getting_started/NASA-Earthdata.rst b/doc/source/getting_started/NASA-Earthdata.rst index 1fa7c01b..441ec213 100644 --- a/doc/source/getting_started/NASA-Earthdata.rst +++ b/doc/source/getting_started/NASA-Earthdata.rst @@ -21,13 +21,13 @@ provides data and related information pertaining to the physical processes and c including measurements of ocean winds, temperature, topography, salinity, circulation and currents, and sea ice. PO.DAAC hosts -PO.DAAC is `migrating its data archive to the Earthdata Cloud `_, +PO.DAAC has `migrated its data archive to the Earthdata Cloud `_, which is hosted in Amazon Web Services (AWS). -GRACE/GRACE-FO spherical harmonic data is currently scheduled to be "cloud enabled" -during Phase 4 and Phase 5 of the transition, slated for April and July 2022 respectively. -If any problems contact JPL PO.DAAC support at `podaac@podaac.jpl.nasa.gov `_ -or the NASA EOSDIS support team `support@earthdata.nasa.gov `_. +.. tip:: + + If any problems contact JPL PO.DAAC support at `podaac@podaac.jpl.nasa.gov `_ + or the NASA EOSDIS support team `support@earthdata.nasa.gov `_. Steps to Sync from PO.DAAC -------------------------- diff --git a/doc/source/index.rst b/doc/source/index.rst index ffc38f8e..8a32f1fa 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -2,26 +2,94 @@ gravity-toolkit =============== -Python tools for obtaining and working with Level-2 spherical harmonic -coefficients from the NASA/DLR Gravity Recovery and Climate Experiment (GRACE) -and the NASA/GFZ Gravity Recovery and Climate Experiment Follow-On (GRACE-FO) -missions +Welcome to the documentation for ``gravity-toolkit``, a set of Python tools for working with time-variable gravity fields. + +This documentation is intended to explain how to obtain and work with the Level-2 spherical harmonic +coefficients from the NASA/DLR Gravity Recovery and Climate Experiment (GRACE) and +the NASA/GFZ Gravity Recovery and Climate Experiment Follow-On (GRACE-FO) missions. + +Introduction +------------ + +.. grid:: 2 2 4 4 + :padding: 0 + + .. grid-item-card:: Installation + :text-align: center + :link: ./getting_started/Install.html + + :material-outlined:`download;5em` + + .. grid-item-card:: Getting Started + :text-align: center + :link: ./getting_started/Getting-Started.html + + :material-outlined:`hiking;5em` + + .. grid-item-card:: Background + :text-align: center + :link: ./background/Background.html + + :material-outlined:`library_books;5em` + + .. grid-item-card:: Examples + :text-align: center + :link: ./user_guide/Examples.html + + :material-outlined:`apps;5em` + +Contribute +---------- + +.. grid:: 2 2 4 4 + :padding: 0 + + .. grid-item-card:: Guidelines + :text-align: center + :link: ./getting_started/Contributing.html + + :material-outlined:`groups;5em` + + .. grid-item-card:: Code of Conduct + :text-align: center + :link: ./getting_started/Code-of-Conduct.html + + :material-outlined:`gavel;5em` + + .. grid-item-card:: Discussions + :text-align: center + :link: https://github.com/tsutterley/gravity-toolkit/discussions + + :material-outlined:`forum;5em` + + .. grid-item-card:: Citation Information + :text-align: center + :link: ./project/Citations.html + + :material-outlined:`alternate_email;5em` .. toctree:: :maxdepth: 2 + :hidden: :caption: Getting Started getting_started/Install.rst - getting_started/Background.rst getting_started/Getting-Started.rst getting_started/NASA-Earthdata.rst getting_started/GRACE-Data-File-Formats.rst - getting_started/Spatial-Maps.rst - getting_started/Time-Series-Analysis.rst - getting_started/Geocenter-Variations.rst getting_started/Contributing.rst + getting_started/Code-of-Conduct.rst getting_started/Resources.rst - getting_started/Citations.rst + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Background + + background/Background.rst + background/Spatial-Maps.rst + background/Time-Series-Analysis.rst + background/Geocenter-Variations.rst .. toctree:: :maxdepth: 1 @@ -86,72 +154,100 @@ missions .. toctree:: :maxdepth: 1 :hidden: - :caption: Utilities + :caption: Access + + api_reference/access/cnes_grace_sync.rst + api_reference/access/esa_costg_swarm_sync.rst + api_reference/access/gfz_icgem_costg_ftp.rst + api_reference/access/gfz_isdc_dealiasing_ftp.rst + api_reference/access/gfz_isdc_grace_ftp.rst + api_reference/access/itsg_graz_grace_sync.rst + api_reference/access/podaac_cumulus.rst + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Dealiasing + + api_reference/dealiasing/aod1b_geocenter.rst + api_reference/dealiasing/aod1b_oblateness.rst + api_reference/dealiasing/dealiasing_global_uplift.rst + api_reference/dealiasing/dealiasing_monthly_mean.rst + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Geocenter - api_reference/cnes_grace_sync.rst - api_reference/esa_costg_swarm_sync.rst - api_reference/gfz_icgem_costg_ftp.rst - api_reference/gfz_isdc_dealiasing_ftp.rst - api_reference/gfz_isdc_grace_ftp.rst - api_reference/itsg_graz_grace_sync.rst - api_reference/make_grace_index.rst - api_reference/podaac_cumulus.rst + api_reference/geocenter/calc_degree_one.rst + api_reference/geocenter/monte_carlo_degree_one.rst .. toctree:: :maxdepth: 1 :hidden: :caption: Use Cases - api_reference/aod1b_geocenter.rst - api_reference/aod1b_oblateness.rst - api_reference/calc_degree_one.rst - api_reference/calc_mascon.rst - api_reference/calc_harmonic_resolution.rst - api_reference/calc_sensitivity_kernel.rst - api_reference/combine_harmonics.rst - api_reference/convert_harmonics.rst - api_reference/dealiasing_global_uplift.rst - api_reference/dealiasing_monthly_mean.rst - api_reference/grace_mean_harmonics.rst - api_reference/grace_raster_grids.rst - api_reference/grace_spatial_error.rst - api_reference/grace_spatial_maps.rst - api_reference/mascon_reconstruct.rst - api_reference/monte_carlo_degree_one.rst - api_reference/quick_mascon_regress.rst - api_reference/piecewise_grace_maps.rst - api_reference/regress_grace_maps.rst - api_reference/run_grace_date.rst - api_reference/run_sea_level_equation.rst - api_reference/scale_grace_maps.rst + api_reference/scripts/calc_mascon.rst + api_reference/scripts/calc_harmonic_resolution.rst + api_reference/scripts/calc_sensitivity_kernel.rst + api_reference/scripts/combine_harmonics.rst + api_reference/scripts/convert_harmonics.rst + api_reference/scripts/grace_mean_harmonics.rst + api_reference/scripts/grace_raster_grids.rst + api_reference/scripts/grace_spatial_error.rst + api_reference/scripts/grace_spatial_maps.rst + api_reference/scripts/mascon_reconstruct.rst + api_reference/scripts/piecewise_grace_maps.rst + api_reference/scripts/regress_grace_maps.rst + api_reference/scripts/run_sea_level_equation.rst + api_reference/scripts/scale_grace_maps.rst .. toctree:: :maxdepth: 1 :hidden: - :caption: Graphing - - api_reference/plot_AIS_grid_maps.rst - api_reference/plot_AIS_grid_3maps.rst - api_reference/plot_AIS_grid_4maps.rst - api_reference/plot_AIS_grid_movie.rst - api_reference/plot_AIS_GrIS_maps.rst - api_reference/plot_AIS_regional_maps.rst - api_reference/plot_AIS_regional_movie.rst - api_reference/plot_global_grid_maps.rst - api_reference/plot_global_grid_3maps.rst - api_reference/plot_global_grid_4maps.rst - api_reference/plot_global_grid_5maps.rst - api_reference/plot_global_grid_9maps.rst - api_reference/plot_global_grid_movie.rst - api_reference/plot_GrIS_grid_maps.rst - api_reference/plot_GrIS_grid_3maps.rst - api_reference/plot_GrIS_grid_5maps.rst - api_reference/plot_GrIS_grid_movie.rst - api_reference/quick_mascon_plot.rst + :caption: Mapping + + api_reference/mapping/plot_AIS_grid_maps.rst + api_reference/mapping/plot_AIS_grid_3maps.rst + api_reference/mapping/plot_AIS_grid_4maps.rst + api_reference/mapping/plot_AIS_grid_movie.rst + api_reference/mapping/plot_AIS_GrIS_maps.rst + api_reference/mapping/plot_AIS_regional_maps.rst + api_reference/mapping/plot_AIS_regional_movie.rst + api_reference/mapping/plot_global_grid_maps.rst + api_reference/mapping/plot_global_grid_3maps.rst + api_reference/mapping/plot_global_grid_4maps.rst + api_reference/mapping/plot_global_grid_5maps.rst + api_reference/mapping/plot_global_grid_9maps.rst + api_reference/mapping/plot_global_grid_movie.rst + api_reference/mapping/plot_GrIS_grid_maps.rst + api_reference/mapping/plot_GrIS_grid_3maps.rst + api_reference/mapping/plot_GrIS_grid_5maps.rst + api_reference/mapping/plot_GrIS_grid_movie.rst + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Utilities + + api_reference/utilities/make_grace_index.rst + api_reference/utilities/quick_mascon_plot.rst + api_reference/utilities/quick_mascon_regress.rst + api_reference/utilities/run_grace_date.rst + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Project Details + + project/Contributors.rst + project/Licenses.rst + project/Testing.rst + project/Citations.rst .. toctree:: :maxdepth: 1 :hidden: :caption: Bibliography - getting_started/Bibliography.rst + project/Bibliography.rst diff --git a/doc/source/getting_started/Bibliography.rst b/doc/source/project/Bibliography.rst similarity index 100% rename from doc/source/getting_started/Bibliography.rst rename to doc/source/project/Bibliography.rst diff --git a/doc/source/getting_started/Citations.rst b/doc/source/project/Citations.rst similarity index 80% rename from doc/source/getting_started/Citations.rst rename to doc/source/project/Citations.rst index 7a0b4ccd..256ce6c7 100644 --- a/doc/source/getting_started/Citations.rst +++ b/doc/source/project/Citations.rst @@ -27,33 +27,15 @@ original works, which is allowed under the `publisher's permissions policies for authors `_ or through the `Creative Commons licensing `_ of the work. -If you have used ``gravity-toolkit`` in your work, please consider citing our library: +.. admonition:: Please consider citing our library T. C. Sutterley, et al., "gravity-toolkit: Python tools for obtaining and working with data from the GRACE and GRACE Follow-On missions", (2020). `doi: 10.5281/zenodo.5156864 `_ -Contributors -############ - -.. include:: ../../../CONTRIBUTORS.rst - -Development -########### -This is an open source project. -We welcome any help in maintaining and developing the software and documentation. -Anyone at any career stage and with any level of coding experience can contribute. -Please see the `Contribution Guidelines <./Contributing.html>`_ for more information. - -Problem Reports -############### -If you have found a problem in these programs, or you would like to suggest -an improvement or modification, please submit a -`GitHub issue `_ -and we will get back to you. - Dependencies ############ + This software is also dependent on other commonly used Python packages: - `cartopy: Python package designed for geospatial data processing `_ @@ -71,11 +53,14 @@ This software is also dependent on other commonly used Python packages: Disclaimer ########## + This program is not sponsored or maintained by the Universities Space Research Association (USRA), the Center for Space Research at the University of Texas (UTCSR), the Jet Propulsion Laboratory (JPL), the German Research Centre for Geosciences (GeoForschungsZentrum, GFZ) or NASA. -It is provided here for your convenience but *with no guarantees whatsoever*. + +.. caution:: + This software is provided here for your convenience but *with no guarantees whatsoever*. This product includes software developed at: @@ -86,7 +71,8 @@ This product includes software developed at: Acknowledgements ################ -Much of this software stems from the work of the late `John Wahr (1951--2015) `_, + +Much of this software stems from the work of `John Wahr (1951--2015) `_, who made immeasurable contributions towards time-variable gravity research and was an inspiration. .. |euml| unicode:: U+00EB .. LATIN SMALL LETTER E WITH DIAERESIS diff --git a/doc/source/project/Contributors.rst b/doc/source/project/Contributors.rst new file mode 100644 index 00000000..4dab9c9a --- /dev/null +++ b/doc/source/project/Contributors.rst @@ -0,0 +1,6 @@ +============ +Contributors +============ + +.. include:: ../../../CONTRIBUTORS.md + :parser: commonmark \ No newline at end of file diff --git a/doc/source/project/Licenses.rst b/doc/source/project/Licenses.rst new file mode 100644 index 00000000..5e71e5a7 --- /dev/null +++ b/doc/source/project/Licenses.rst @@ -0,0 +1,15 @@ +======== +Licenses +======== + +MIT License +=========== + +The source code of ``gravity-toolkit`` is licensed under a MIT license: + +.. include:: ../../../LICENSE + +Other Licenses +============== + +The content of ``gravity-toolkit`` including documentation and notebooks is licensed under a `Creative Commons Attribution 4.0 Attribution license `_ (CC BY 4.0). diff --git a/doc/source/project/Testing.rst b/doc/source/project/Testing.rst new file mode 100644 index 00000000..49a01167 --- /dev/null +++ b/doc/source/project/Testing.rst @@ -0,0 +1,26 @@ +======= +Testing +======= + +``gravity-toolkit`` uses the ``pytest`` framework to run tests and verify outputs. + +Running the Test Suite +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + pytest --directory test/ + +The test suite is run in verbose mode as a default. + +Continuous Integration +^^^^^^^^^^^^^^^^^^^^^^ +We use `GitHub Actions `_ continuous integration (CI) services to build and test the project on Linux (``ubuntu-latest``), Mac (``macos-latest``) and Windows (``windows-latest``) Operating Systems. +The configuration files for this service are in the `GitHub workflows `_ directory. +The workflows use ``mamba`` and the `environment.yml `_ file to install the required dependencies and build the environment. + +The GitHub Actions jobs include: + +* Running `flake8 `_ to check the code for style and compilation errors +* Running the test suite on multiple combinations of OS and Python version +* Uploading source and wheel distributions to `PyPI `_ (on releases) diff --git a/scripts/calc_degree_one.py b/geocenter/calc_degree_one.py similarity index 100% rename from scripts/calc_degree_one.py rename to geocenter/calc_degree_one.py diff --git a/scripts/geocenter_compare_tellus.py b/geocenter/geocenter_compare_tellus.py similarity index 100% rename from scripts/geocenter_compare_tellus.py rename to geocenter/geocenter_compare_tellus.py diff --git a/scripts/geocenter_monte_carlo.py b/geocenter/geocenter_monte_carlo.py similarity index 100% rename from scripts/geocenter_monte_carlo.py rename to geocenter/geocenter_monte_carlo.py diff --git a/scripts/geocenter_ocean_models.py b/geocenter/geocenter_ocean_models.py similarity index 100% rename from scripts/geocenter_ocean_models.py rename to geocenter/geocenter_ocean_models.py diff --git a/scripts/geocenter_processing_centers.py b/geocenter/geocenter_processing_centers.py similarity index 100% rename from scripts/geocenter_processing_centers.py rename to geocenter/geocenter_processing_centers.py diff --git a/scripts/monte_carlo_degree_one.py b/geocenter/monte_carlo_degree_one.py similarity index 100% rename from scripts/monte_carlo_degree_one.py rename to geocenter/monte_carlo_degree_one.py diff --git a/scripts/plot_AIS_GrIS_maps.py b/mapping/plot_AIS_GrIS_maps.py similarity index 100% rename from scripts/plot_AIS_GrIS_maps.py rename to mapping/plot_AIS_GrIS_maps.py diff --git a/scripts/plot_AIS_grid_3maps.py b/mapping/plot_AIS_grid_3maps.py similarity index 100% rename from scripts/plot_AIS_grid_3maps.py rename to mapping/plot_AIS_grid_3maps.py diff --git a/scripts/plot_AIS_grid_4maps.py b/mapping/plot_AIS_grid_4maps.py similarity index 100% rename from scripts/plot_AIS_grid_4maps.py rename to mapping/plot_AIS_grid_4maps.py diff --git a/scripts/plot_AIS_grid_maps.py b/mapping/plot_AIS_grid_maps.py similarity index 100% rename from scripts/plot_AIS_grid_maps.py rename to mapping/plot_AIS_grid_maps.py diff --git a/scripts/plot_AIS_grid_movie.py b/mapping/plot_AIS_grid_movie.py similarity index 100% rename from scripts/plot_AIS_grid_movie.py rename to mapping/plot_AIS_grid_movie.py diff --git a/scripts/plot_AIS_regional_maps.py b/mapping/plot_AIS_regional_maps.py similarity index 100% rename from scripts/plot_AIS_regional_maps.py rename to mapping/plot_AIS_regional_maps.py diff --git a/scripts/plot_AIS_regional_movie.py b/mapping/plot_AIS_regional_movie.py similarity index 100% rename from scripts/plot_AIS_regional_movie.py rename to mapping/plot_AIS_regional_movie.py diff --git a/scripts/plot_GrIS_grid_3maps.py b/mapping/plot_GrIS_grid_3maps.py similarity index 100% rename from scripts/plot_GrIS_grid_3maps.py rename to mapping/plot_GrIS_grid_3maps.py diff --git a/scripts/plot_GrIS_grid_5maps.py b/mapping/plot_GrIS_grid_5maps.py similarity index 100% rename from scripts/plot_GrIS_grid_5maps.py rename to mapping/plot_GrIS_grid_5maps.py diff --git a/scripts/plot_GrIS_grid_maps.py b/mapping/plot_GrIS_grid_maps.py similarity index 100% rename from scripts/plot_GrIS_grid_maps.py rename to mapping/plot_GrIS_grid_maps.py diff --git a/scripts/plot_GrIS_grid_movie.py b/mapping/plot_GrIS_grid_movie.py similarity index 100% rename from scripts/plot_GrIS_grid_movie.py rename to mapping/plot_GrIS_grid_movie.py diff --git a/scripts/plot_QML_grid_3maps.py b/mapping/plot_QML_grid_3maps.py similarity index 100% rename from scripts/plot_QML_grid_3maps.py rename to mapping/plot_QML_grid_3maps.py diff --git a/scripts/plot_global_grid_3maps.py b/mapping/plot_global_grid_3maps.py similarity index 100% rename from scripts/plot_global_grid_3maps.py rename to mapping/plot_global_grid_3maps.py diff --git a/scripts/plot_global_grid_4maps.py b/mapping/plot_global_grid_4maps.py similarity index 100% rename from scripts/plot_global_grid_4maps.py rename to mapping/plot_global_grid_4maps.py diff --git a/scripts/plot_global_grid_5maps.py b/mapping/plot_global_grid_5maps.py similarity index 100% rename from scripts/plot_global_grid_5maps.py rename to mapping/plot_global_grid_5maps.py diff --git a/scripts/plot_global_grid_9maps.py b/mapping/plot_global_grid_9maps.py similarity index 100% rename from scripts/plot_global_grid_9maps.py rename to mapping/plot_global_grid_9maps.py diff --git a/scripts/plot_global_grid_maps.py b/mapping/plot_global_grid_maps.py similarity index 100% rename from scripts/plot_global_grid_maps.py rename to mapping/plot_global_grid_maps.py diff --git a/scripts/plot_global_grid_movie.py b/mapping/plot_global_grid_movie.py similarity index 100% rename from scripts/plot_global_grid_movie.py rename to mapping/plot_global_grid_movie.py diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000..2f0faa9d --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,113 @@ +[build-system] +requires = ["setuptools>=64"] +build-backend = "setuptools.build_meta" + +[project] +name = "gravity-toolkit" +version = "1.2.4" +description = "Python tools for working with time-variable gravity fields" +keywords = [ + "GRACE", + "GRACE-FO", + "Gravity", + "satellite geodesy", + "spherical harmonics", +] + +authors = [ + {name = "Tyler Sutterley"}, + {name = "Hugo Lecomte"}, + {name = "Yara Mohajerani"}, + {name = "Isabella Velicogna"}, + {email = "tsutterl@uw.edu"} +] +maintainers = [{ name = "gravity-toolkit contributors" }] +license = {file = "LICENSE"} +readme = "README.rst" + +requires-python = "~=3.6" +dependencies = [ + "boto3", + "future", + "lxml", + "matplotlib", + "netCDF4", + "numpy", + "python-dateutil", + "pyyaml", + "scipy>=1.10.1", +] + +classifiers=[ + "Development Status :: 3 - Alpha", + "Intended Audience :: Science/Research", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.6", + "Programming Language :: Python :: 3.7", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Topic :: Scientific/Engineering :: Physics", +] + +[project.urls] +Homepage = "https://gravity-toolkit.readthedocs.io" +Documentation = "https://gravity-toolkit.readthedocs.io" +Repository = "https://github.com/tsutterley/gravity-toolkit" +Issues = "https://github.com/tsutterley/gravity-toolkit/issues" + +[project.optional-dependencies] +doc = ["docutils", "fontconfig", "freetype", "graphviz", "ipympl", "markupsafe", "myst-nb", "numpydoc", "sphinx", "sphinx-argparse>=0.4", "sphinxcontrib-bibtex", "sphinx-design", "sphinx_rtd_theme"] +all = ["cartopy", "geoid-toolkit", "h5py", "jupyterlab", "jupyterlab_widgets", "notebook", "shapely"] +dev = ["flake8", "pytest>=4.6", "pytest-cov"] + +[tool.setuptools.packages.find] +exclude = ["test*", "run*"] + +[tool.pytest.ini_options] +minversion = "2.0" +norecursedirs = ".git" +addopts = "--verbose --capture=no" +python_files = [ + "test*.py" +] +testpaths = [ + "test" +] + +[tool.coverage.run] +branch = true +source = [ + "gravity-toolkit", + "test", +] +omit = [ + "setup.py", + "conf.py", + "access/*", + "dealiasing/*", + "geocenter/*", + "mapping/*", + "scripts/*", + "utilities/*", +] + +[tool.coverage.report] +show_missing = true +precision = 2 + +[tool.ruff] +line-length = 80 +indent-width = 4 + +[tool.ruff.lint.pydocstyle] +convention = "numpy" + +[tool.ruff.format] +quote-style = "single" +indent-style = "space" +docstring-code-format = false diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index dab10e5b..00000000 --- a/requirements.txt +++ /dev/null @@ -1,9 +0,0 @@ -boto3 -future -lxml -matplotlib -netCDF4 -numpy -python-dateutil -pyyaml -scipy diff --git a/setup.cfg b/setup.cfg deleted file mode 100644 index fcc8d9d3..00000000 --- a/setup.cfg +++ /dev/null @@ -1,20 +0,0 @@ -[tool:pytest] -minversion = 2.0 -norecursedirs = .git -python_files = test*.py -testpaths = - test - -[coverage:run] -branch = true -source = - gravity_toolkit - test -omit = - setup.py - conf.py - scripts/* - -[coverage:report] -show_missing = true -precision = 2 diff --git a/setup.py b/setup.py index f5034de6..855306c3 100644 --- a/setup.py +++ b/setup.py @@ -1,53 +1,14 @@ import os from setuptools import setup, find_packages -# package description and keywords -description = ('Python tools for obtaining and working with spherical harmonic' - 'coefficients from the NASA/DLR GRACE and NASA/GFZ GRACE Follow-on missions') -keywords = 'GRACE, GRACE-FO, Gravity, satellite geodesy, spherical harmonics' -# get long_description from README.rst -with open("README.rst", mode="r", encoding='utf8') as fh: - long_description = fh.read() -long_description_content_type = "text/x-rst" - -# get install requirements -with open('requirements.txt', encoding='utf8') as fh: - install_requires = [line.split().pop(0) for line in fh.read().splitlines()] - -# get version -with open('version.txt', encoding='utf8') as fh: - version = fh.read() - # list of all scripts to be included with package -scripts=[os.path.join('scripts',f) for f in os.listdir('scripts') if f.endswith('.py')] +scripts = [] +for dir in ['access','dealiasing','geocenter','mapping','scripts','utilities']: + scripts.extend([os.path.join(dir,f) for f in os.listdir(dir) if f.endswith('.py')]) scripts.append(os.path.join('gravity_toolkit','grace_date.py')) scripts.append(os.path.join('gravity_toolkit','grace_months_index.py')) setup( name='gravity-toolkit', - version=version, - description=description, - long_description=long_description, - long_description_content_type=long_description_content_type, - url='https://github.com/tsutterley/gravity-toolkit', - author='Tyler Sutterley', - author_email='tsutterl@uw.edu', - license='MIT', - classifiers=[ - 'Development Status :: 3 - Alpha', - 'Intended Audience :: Science/Research', - 'Topic :: Scientific/Engineering :: Physics', - 'License :: OSI Approved :: MIT License', - 'Programming Language :: Python :: 3', - 'Programming Language :: Python :: 3.6', - 'Programming Language :: Python :: 3.7', - 'Programming Language :: Python :: 3.8', - 'Programming Language :: Python :: 3.9', - 'Programming Language :: Python :: 3.10', - ], - keywords=keywords, - packages=find_packages(), - install_requires=install_requires, scripts=scripts, - include_package_data=True, ) diff --git a/scripts/make_grace_index.py b/utilities/make_grace_index.py similarity index 100% rename from scripts/make_grace_index.py rename to utilities/make_grace_index.py diff --git a/scripts/quick_mascon_plot.py b/utilities/quick_mascon_plot.py similarity index 100% rename from scripts/quick_mascon_plot.py rename to utilities/quick_mascon_plot.py diff --git a/scripts/quick_mascon_regress.py b/utilities/quick_mascon_regress.py similarity index 100% rename from scripts/quick_mascon_regress.py rename to utilities/quick_mascon_regress.py diff --git a/scripts/run_grace_date.py b/utilities/run_grace_date.py similarity index 100% rename from scripts/run_grace_date.py rename to utilities/run_grace_date.py diff --git a/version.txt b/version.txt deleted file mode 100644 index e8ea05db..00000000 --- a/version.txt +++ /dev/null @@ -1 +0,0 @@ -1.2.4