More RTD updates for GCPy 1.5.0

docs/source/Compare-Diags.rst docs/source/Hemco-Formatting.rst docs/source/Single-Panel.rst docs/source/Six-Panel.rst docs/source/Test-Plot.rst - Fixed broken references and incorrect text - Now use more concise script location section - Changed "Calling Sequence" to "Usage" docs/source/Known-Bugs.rst - Edited the resolved bugs link so as to avoid a duplicate name warning docs/source/Plotting.rst docs/source/Guide-to-Useful-Capabilities.rst - Replace ref "plot-csl-and-czm" with separate refs "plot-csl" and "plot-czm" docs/source/ObsPack.rst - Added text docs/source/Plot-Timeseries.rst - Removed, as the example script no longer exists docs/source/index.rst - Removed ref to Plot-Timeseries.rst docs/source/conf.py - Bump version number up to 1.5.0 gcpy/community/create_obspack_coords_file.py - Moved here from gcpy/examples/diagnostics folder Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>
geoschem · May 28, 2024 · ceeb4c9 · ceeb4c9
1 parent 54c4f33
commit ceeb4c9
Show file tree

Hide file tree

Showing 14 changed files with 774 additions and 506 deletions.
diff --git a/docs/source/Benchmarking.rst b/docs/source/Benchmarking.rst
diff --git a/docs/source/Compare-Diags.rst b/docs/source/Compare-Diags.rst
@@ -32,7 +32,7 @@ files.
    SpeciesConcVV_ASOG1  : 8.251855e-08           | 8.251855e-08           | 0.0 
    . . .
 		
-as well as optional :ref:`six-panel plots <six-panel plots>`.  This
+as well as optional :ref:`six-panel plots <six-panel>`.  This
 allows you to determine if two GEOS-Chem simulations have yielded
 identical results or not.
 
@@ -42,17 +42,18 @@ identical results or not.
 Source code
 ===========
 
-This example script may be found at
-`gcpy/examples/diagnostics/compare_diags.py
+**Script location:** `gcpy/examples/diagnostics/compare_diags.py
 <https://github.com/geoschem/gcpy/blob/main/gcpy/examples/plotting/plot_comparisons.py>`_
-with associated configuration file
-`gcpy/examples/diagnostics/compare_diags.yml <https://github.com/geoschem/gcpy/blob/main/gcpy/examples/diagnostics/compare_diags.yml>`_
 
-.. _comp-diags-call:
+**Related configuration file:**
+`gcpy/examples/diagnostics/compare_diags.yml
+<https://github.com/geoschem/gcpy/blob/main/gcpy/examples/diagnostics/compare_diags.yml>`_ 
 
-================
-Calling sequence
-================
+.. _comp-diags-usage:
+
+=====
+Usage
+=====
 
 Make sure that you :ref:`specified the proper Matplotlib backend
 <mpl-backend>` for  your system.
@@ -61,7 +62,7 @@ First, copy the :file:`compare_diags.yml` file to your local folder.
 
 .. code-block:: console
 
-   $ cp /path/to/gcpy/gcpy/examples/diagnostics/compare_diags.yml .
+   $ cp /path/to/GCPy/gcpy/examples/diagnostics/compare_diags.yml .
 
 .. tip::
 
@@ -79,7 +80,7 @@ zonal mean plots.
    paths:
      main_dir: /path/to/your/data   # Add the path to your output here
      plots_dir: ./Results
-     weights_dir: /n/holyscratch01/external_repos/GEOS-CHEM/gcgrid/gcdata/ExtData/GCHP/RegriddingWeights
+     weights_dir: /path/to/regridding/weights/folder
    
    data:
      ref:
@@ -116,4 +117,4 @@ Then, run the script with:
 
 .. code-block:: console
 
-   $ python -m gcpy.examples.diagnostics.compare_diags.py compare_diags.yml
+   $ python -m gcpy.examples.diagnostics.compare_diags compare_diags.yml
diff --git a/docs/source/Guide-to-Useful-Capabilities.rst b/docs/source/Guide-to-Useful-Capabilities.rst
@@ -241,8 +241,8 @@ and B coefficients of the hybrid vertical grid
 <wiki.seas.harvard.edu/geos-chem/index.php/GEOS-Chem_vertical_grids>`__.
 
 When plotting data of differing grid types or horizontal resolutions
-using :ref:`compare_single_level() <plot-csl-and-czm>`
-or :ref:`compare_zonal_mean() <plot-csl-and-czm>`, you
+using :ref:`compare_single_level() <plot-csl>`
+or :ref:`compare_zonal_mean() <plot-czm>`, you
 can specify a comparison resolution using the :literal:`cmpres`
 argument. This resolution will be used for the difference panels in
 each plot (the bottom four panels rather than the top two raw data

diff --git a/docs/source/Hemco-Formatting.rst b/docs/source/Hemco-Formatting.rst
@@ -4,3 +4,57 @@
 Format netCDF files for input to HEMCO
 ######################################
 
+This community contribution script formats a netCDF file so that its
+global and variable attributes are COARDS-compliant.  This is a
+requirement for input to `GEOS-Chem
+<https://geos-chem.readthedocs.io>`_ via the `Harmonized Emission
+Component (HEMCO) <https://hemco.readthedocs.io>`_.
+
+Please reach out to the author directly if you have questions about
+using this script:
+
+   +-----------------+-----------------+
+   | Author          | GitHub Handle   |
+   +=================+=================+
+   | Hannah Nesser   | @hannahnesser   |
+   +-----------------+-----------------+
+
+.. _hco-fmt-code:
+
+===========
+Source code
+===========
+
+**Script location:** `gcpy/community/format_hemco_data.py <https://github.com/geoschem/gcpy/blob/main/gcpy/community/format_hemco_data.py>`_
+
+**Related example script:**  `gcpy/examples/hemco/format_hemco_demo.py
+<https://github.com/geoschem/gcpy/blob/main/gcpy/community/format_hemco_demo.py>`_
+
+.. _hco-fmt-usage:
+
+=====
+Usage
+=====
+
+Navigate to a local directory where you will run the script.  Then
+download this data file from the AWS :file:`s3://gcgrid` bucket:
+
+.. code-block:: console
+
+   $ wget https://gcgrid.s3.amazonaws.com/HEMCO/GCClassic_Output/14.0.0/2019/GEOSChem.ProdLoss.20190101_0000z.nc4
+
+and rename it to :file:`HEMCO_demonstration_file.nc`:
+
+.. code-block:: console
+
+   $ mv GEOSChem.ProdLoss.20190101_0000z.nc4 HEMCO_demonstration_file.nc
+
+Then you may run the demonstration script:
+
+.. code-block:: console
+
+   $ python -m gcpy.examples.hemco.format_hemco_demo
+
+You can view the :file:`gcpy/examples/hemco/format_hemco_demo.py`
+script in your favorite editor to see the individual commands that
+are executed.
diff --git a/docs/source/Known-Bugs.rst b/docs/source/Known-Bugs.rst
@@ -20,4 +20,6 @@ are currently unresolved. We hope to fix these in future releases.
 Bugs that have been resolved
 ============================
 
-These `bug reports (on GitHub) <https://github.com/geoschem/gcpy/issues?q=+label%3A%22category%3A+Bug+Fix%22+>`_ have been resolved.
+These `previously-reported bugs (on GitHub)
+<https://github.com/geoschem/gcpy/issues?q=+label%3A%22category%3A+Bug+Fix%22+>`_
+have since been resolved.
diff --git a/docs/source/ObsPack.rst b/docs/source/ObsPack.rst
@@ -1,7 +1,78 @@
 .. _obspack:
 
-#########################################################
-Create an input file for the GEOS-Chem ObsPack diagnostic
-#########################################################
+##############################################################
+Create a coordinates file for the GEOS-Chem ObsPack diagnostic
+##############################################################
 
+This community contribution script generates a netCDF file containing
+longitude, latitude, and altitude values at which
+`GEOS-Chem ObsPack diagnostic output
+<https://geos-chem.readthedocs.io/en/latest/gcclassic-user-guide/obspack.html>`_
+will be archived.
 
+Please reach out to the author directly if you have questions about
+using this script:
+
+   +-----------------+---------------+
+   | Author          | GitHub Handle |
+   +=================+===============+
+   | Alli Moon       | @alli-moon    |
+   +-----------------+---------------+
+   | Yuk Yun Chan    | @yc-chan      |
+   +-----------------+---------------+
+
+.. _obspack-code:
+
+===========
+Source code
+===========
+
+**Script location:** `gcpy/community/create_obspack_coords_file.py <https://github.com/geoschem/gcpy/blob/main/gcpy/community/create_obspack_coords_file.py>`_
+
+.. _obspack-usage:
+
+=====
+Usage
+=====
+
+Navigate to a local directory where you will run the script.  Then
+copy :file:`gcpy/community/create_obspack_coords_file.py` there:
+
+.. code-block:: console
+
+   $ cd /path/to/my/local/directory
+
+   $ cp /path/to/gcpy/gcpy/community/create_obspack_coords_file.py .
+
+Open :file:`create_obspack_coords_file.py` in your favorite editor and
+edit the configurable settings for your particular use case:
+
+.. code-block:: python
+
+   # ==================================================================
+   # Configurable settings -- edit for your own use case!
+   DATASET_ID = 'GC-MODEL'
+   OUTPUT_DIR = './'
+
+   SAMPLING_DATES_SUMMER = pd.date_range(
+       start='2022-05-31',
+       end='2022-07-01',
+       freq='d'
+   )
+   SAMPLING_DATES_WINTER = pd.date_range(
+       start='2023-01-13',
+       end='2023-2-13',
+       freq='d'
+   )
+
+   SITE_LAT = 32.2644
+   SITE_LON = -64.8767
+   SITE_ALT = 0
+   ASSUMED_INLET_HEIGHT_ABOVE_GROUND = 30 # Unit:m
+   # ==================================================================
+
+Once you have done this, you may run the script:
+
+.. code-block:: console
+
+   $ python -m create_obspack_coords_file