diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml index 0af1c868..ae771cba 100644 --- a/.github/workflows/documentation.yaml +++ b/.github/workflows/documentation.yaml @@ -12,6 +12,7 @@ on: - docs/** pull_request: types: [opened, reopened, synchronize] + workflow_dispatch: jobs: documentation: @@ -21,11 +22,10 @@ jobs: - uses: actions/checkout@v6 - uses: actions/setup-python@v6 with: - python-version: '3.10' + python-version: '3.12' - name: Install dependencies run: | - python -m pip install --upgrade python-dateutil requests sphinx \ - sphinx-gallery matplotlib Pillow sphinx_rtd_theme + python -m pip install --upgrade python-dateutil requests matplotlib Pillow python -m pip install -r docs/requirements.txt - name: Build docs run: ./.github/jobs/build_documentation.sh @@ -40,3 +40,9 @@ jobs: name: documentation_warnings.log path: artifact/doc_warnings.log if-no-files-found: ignore + - name: Check links + uses: dtcenter/metplus-action-linkcheck@v1 + with: + fail-on-broken-links: 'true' + upload-artifact: 'true' + install-package: 'true' diff --git a/.github/workflows/linkcheck.yml b/.github/workflows/linkcheck.yml deleted file mode 100644 index 305c6dce..00000000 --- a/.github/workflows/linkcheck.yml +++ /dev/null @@ -1,19 +0,0 @@ -name: Linkcheck -on: - schedule: - - cron: '0 6 * * 1' - pull_request: - paths: - - 'docs/**' - workflow_dispatch: {} - -jobs: - linkcheck: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v6 - - uses: dtcenter/metplus-action-linkcheck@v1 - with: - fail-on-broken-links: 'true' - upload-artifact: 'true' - install-package: 'true' \ No newline at end of file diff --git a/docs/Contributors_Guide/github_repository.rst b/docs/Contributors_Guide/github_repository.rst index cfe4ea7c..72fc6800 100644 --- a/docs/Contributors_Guide/github_repository.rst +++ b/docs/Contributors_Guide/github_repository.rst @@ -1,5 +1,5 @@ ********************************************* -Organization of Code in the Github Repository +Organization of Code in the GitHub Repository ********************************************* The relevant plotting code resides in one of two directories diff --git a/docs/Contributors_Guide/pull_request.rst b/docs/Contributors_Guide/pull_request.rst index a2eb01e0..cab70e3c 100644 --- a/docs/Contributors_Guide/pull_request.rst +++ b/docs/Contributors_Guide/pull_request.rst @@ -1,5 +1,5 @@ *********************** -Pull Requests in Github +Pull Requests in GitHub *********************** Please refer to the `Open a Pull Request diff --git a/docs/Contributors_Guide/tests_github_actions.rst b/docs/Contributors_Guide/tests_github_actions.rst index 033892bf..74ce7db4 100644 --- a/docs/Contributors_Guide/tests_github_actions.rst +++ b/docs/Contributors_Guide/tests_github_actions.rst @@ -1,5 +1,5 @@ **************************************** -Generate Tests and Add to Github Actions +Generate Tests and Add to GitHub Actions **************************************** Create a subdirectory under the *test* directory @@ -11,9 +11,8 @@ Add sample data (see applicable information in the `_ section). -Use the pytest framework to generate tests. For more information review -this `pytest documentation `_ for -more information. +Use the pytest framework to generate tests. For more information, review +this `pytest documentation `_. Add an entry for the test in the *.github/workflows/unit_tests.yaml* file. diff --git a/docs/Contributors_Guide/third_party_packages.rst b/docs/Contributors_Guide/third_party_packages.rst index 475c7f56..9d91f7d9 100644 --- a/docs/Contributors_Guide/third_party_packages.rst +++ b/docs/Contributors_Guide/third_party_packages.rst @@ -1,5 +1,5 @@ *************************************************************** -Add Additional Third-Party Packages to the Github actions tests +Add Additional Third-Party Packages to the GitHub Actions tests *************************************************************** If necessary, modify the **requirements.txt** file diff --git a/docs/Contributors_Guide/user_doc.rst b/docs/Contributors_Guide/user_doc.rst index 3401e842..52e03ecd 100644 --- a/docs/Contributors_Guide/user_doc.rst +++ b/docs/Contributors_Guide/user_doc.rst @@ -1,6 +1,6 @@ -********************* -Add User Documenation -********************* +********************** +Add User Documentation +********************** Documentation should be added in the *docs/Users_Guide* directory. @@ -29,10 +29,10 @@ Add images. Review and check for errors in the automatically generated documentation. Once the documentation has been committed and pushed to GitHub, - GitHub actions will automatically create the online documentation. + GitHub Actions will automatically create the online documentation. Contributors will be able to view the run for the build of the documentation - in the GitHub actions section of the METplotpy repository, which will + in the GitHub Actions section of the METplotpy repository, which will be named with the text of the last commit message and the text “Documentation” underneath. diff --git a/docs/Users_Guide/bar.rst b/docs/Users_Guide/bar.rst index 4c84c8ae..5c52e60e 100644 --- a/docs/Users_Guide/bar.rst +++ b/docs/Users_Guide/bar.rst @@ -8,7 +8,7 @@ A bar plot shows comparisons among discrete categories. One axis of the chart shows the specific categories being compared, while the other represents some measured value. The heights or lengths are proportional to the values that they represent. Bar plots are simple and flexible, unlike -some other METview plot types. Rather than using prescribed statistics in +some other METviewer plot types. Rather than using prescribed statistics in a specific way, the user can select both axes. Bar plots are distinct from histograms and the two are not interchangeable. @@ -40,12 +40,12 @@ The data is text output from MET in columnar format. e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. Configuration Files @@ -62,7 +62,7 @@ required. The first is a default configuration file, **bar_defaults.yaml**, which is found in the *$METPLOTPY_BASE/metplotpy/plots/config* directory. All default configuration files are located in the -*$METPLOTPY_BASE/metplotpy/plots/config* directory. *$METPLOTPY_BASE* is base directory where the +*$METPLOTPY_BASE/metplotpy/plots/config* directory. *$METPLOTPY_BASE* is the base directory where the METplotpy source code has been saved. **Default configuration files are automatically loaded by the plotting code and do not need to be explicitly specified when generating a plot**. @@ -79,7 +79,7 @@ Default Configuration File -------------------------- The following is the *mandatory*, **bar_defaults.yaml** configuration file, -which serves as a good starting point for creating a line +which serves as a good starting point for creating a bar plot as it represents the default values set in METviewer. **NOTE**: This default configuration file is automatically loaded by @@ -126,7 +126,7 @@ For example: This is where */username/myworkspace/METplotpy* corresponds to $METPLOTPY_BASE and */username/working_dir* corresponds to $WORKING_DIR. Make sure that the -$WORKING_DIR directory that is specifed exists and has the appropriate +$WORKING_DIR directory that is specified exists and has the appropriate read and write permissions. The path listed for *plot_filename* may be changed to the output directory of one’s choosing. If this is not set, then the *plot_filename* setting @@ -143,7 +143,7 @@ the *points_path* setting. *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the same directory where +Replace the */dir_to_save_points1_file* with the same directory where the **.points1** file is saved. If points_path is commented out (indicated by a '#' symbol in front of it), remove the '#' symbol to uncomment @@ -155,7 +155,7 @@ file is desired. To save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -171,7 +171,7 @@ The **custom_bar.yaml** configuration file, in combination with the To generate the above bar plot, perform the following: * If using the conda environment, - verify the conda environment is running and has has the required + verify the conda environment is running and has the required Python packages outlined in the `requirements section `_. @@ -197,7 +197,7 @@ To generate the above bar plot, perform the following: * Enter the following command: .. code-block:: ini - + python $METPLOTPY_BASE/metplotpy/plots/bar/bar.py $WORKING_DIR/custom_bar.yaml * A **bar.png** output file will be created in the directory that was diff --git a/docs/Users_Guide/box.rst b/docs/Users_Guide/box.rst index d70c9c13..c7355cb4 100644 --- a/docs/Users_Guide/box.rst +++ b/docs/Users_Guide/box.rst @@ -43,12 +43,12 @@ METplotpy repository, where the box plot tests are located: e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. Configuration Files @@ -83,7 +83,7 @@ Default Configuration File -------------------------- The following is the *mandatory*, **box_defaults.yaml** configuration file, -which serves as a good starting point for creating a line +which serves as a good starting point for creating a box plot as it represents the default values set in METviewer. .. literalinclude:: ../../metplotpy/plots/config/box_defaults.yaml @@ -103,7 +103,7 @@ Copy this custom config file from the directory where the source code was saved to the working directory: .. code-block:: ini - + cp $METPLOTPY_BASE/test/box/custom_box.yaml $WORKING_DIR/custom_box.yaml Modify the *stat_input* setting in the @@ -144,7 +144,7 @@ setting to True. Uncomment or add (if it doesn't exist) the *points_path: '/dir_to_save_points1_file'* -Replace the **/dir_to_save_points1_file** to the same directory where +Replace the **/dir_to_save_points1_file** with the same directory where the **.points1** file is saved. If *points_path* is commented out (indicated by a '#' symbol in front of it), remove the '#' symbol to uncomment the points_path so that it will be used @@ -155,7 +155,7 @@ unless saving the intermediate **.points1** file is desired. To save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -191,7 +191,7 @@ files are located. Set the *stat_input* to *plot_filename: $WORKING_DIR/output_plots/box_default.png* -Where *$WORKING_DIR* is the working directory where where all the custom +Where *$WORKING_DIR* is the working directory where all the custom configuration files are being saved. **NOTE**: If the *plot_filename* (output directory) is specified to a directory other than the *$WORKING_DIR/output_plots*, the user must have read and write permissions @@ -253,7 +253,7 @@ Perform the following to generate the plots: .. image:: figure/box_default.png - To generate the above *"defaults"* plot (i.e using default configuration + To generate the above *"defaults"* plot (i.e. using default configuration settings), use the "minimal" custom configuration file, **minimal_box.yaml**. @@ -265,4 +265,4 @@ Perform the following to generate the plots: * A **box_default.png** output file will be created in the directory specified in the *plot_filename* configuration setting in - the **box_minimal.yaml** config file. + the **minimal_box.yaml** config file. diff --git a/docs/Users_Guide/contour.rst b/docs/Users_Guide/contour.rst index 4581e337..e721a83b 100644 --- a/docs/Users_Guide/contour.rst +++ b/docs/Users_Guide/contour.rst @@ -34,12 +34,12 @@ repository: e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. @@ -51,7 +51,7 @@ input data is located and to set plot attributes. These plot attributes correspond to values that can be set via the METviewer tool. YAML is a recursive acronym for "YAML Ain't Markup Language" and according to `yaml.org `_, -it is a "human-friendly data serialization language. It is commonly used for +it is a "human-friendly data serialization language". It is commonly used for configuration files and in applications where data is being stored or transmitted. Two configuration files are required. The first is a default configuration file, **contour_defaults.yaml**, @@ -143,7 +143,7 @@ Uncomment or add (if it doesn't exist) the *points_path* setting: *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the same directory where the +Replace the */dir_to_save_points1_file* with the same directory where the **.points1** file is saved. If *points_path* is commented out (indicated by a '#' symbol in front of it), remove the '#' symbol to uncomment @@ -155,7 +155,7 @@ file unless saving the intermediate **.points1** file is desired. To save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -170,7 +170,7 @@ perform the following: * If using the conda environment, verify the conda environment - is running and has has the required Python packages outlined in the + is running and has the required Python packages outlined in the `requirements section `_. @@ -180,13 +180,13 @@ perform the following: For the ksh environment: .. code-block:: ini - + export METPLOTPY_BASE=$METPLOTPY_BASE For the csh environment: .. code-block:: ini - + setenv METPLOTPY_BASE $METPLOTPY_BASE Recall that *$METPLOTPY_BASE* is the directory path indicating where the METplotpy source code was saved. diff --git a/docs/Users_Guide/difficulty_index.rst b/docs/Users_Guide/difficulty_index.rst index 5c8c2574..e87dca4c 100644 --- a/docs/Users_Guide/difficulty_index.rst +++ b/docs/Users_Guide/difficulty_index.rst @@ -16,11 +16,11 @@ will not address here is undiagnosed systematic error, which adds uncertainty in The challenge is combining these factors into a continuous function that allows the user to assess relative risk. The code for calculating and plotting the difficulty index was developed by Bill Campbell and Liz Satterfield of the -Navy Research Lab (NRL) and modified by NCAR. +Naval Research Lab (NRL) and modified by NCAR. For more information on calculating the difficulty index, please refer to this METplus use case: -`METviewer documentation +`UserScript_fcstGEFS_Difficulty_Index use case `_. Example @@ -61,7 +61,7 @@ Configuration Files All the settings for the example difficulty index plot are incorporated in the mycolormaps.py and plot_difficulty_index.py code. The example_difficulty_index.py script imports these modules to -create six sample plots. The location of where these plots are saved are determined by settings in the +create six sample plots. The location of where these plots are saved is determined by settings in the example_difficulty_index.yaml configuration file: .. literalinclude:: ../../test/difficulty_index/example_difficulty_index.yaml @@ -100,7 +100,7 @@ Run from the Command Line To generate the sample difficulty index plots, perform the following: * If using the conda environment, verify the conda environment - is running and has has the required Python packages outlined in the **Required Packages** section above. + is running and has the required Python packages outlined in the **Required Packages** section above. Where $METPLOTPY_BASE is the directory where you saved the METplotpy source code and $WORKING_DIR is the directory diff --git a/docs/Users_Guide/eclv.rst b/docs/Users_Guide/eclv.rst index 5fcebb7d..32e0d122 100644 --- a/docs/Users_Guide/eclv.rst +++ b/docs/Users_Guide/eclv.rst @@ -1,5 +1,5 @@ ************************************* -Economic Cost/Lost Value (ECLV) Plots +Economic Cost/Loss Value (ECLV) Plots ************************************* Description @@ -36,12 +36,12 @@ repository, where the ECLV plot scripts are located: e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. Configuration Files @@ -52,7 +52,7 @@ input data is located and to set plot attributes. These plot attributes correspond to values that can be set via the METviewer tool. YAML is a recursive acronym for "YAML Ain't Markup Language" and according to `yaml.org `_, -it is a "human-friendly data serialization language. It is commonly used for +it is a "human-friendly data serialization language". It is commonly used for configuration files and in applications where data is being stored or transmitted. Two configuration files are required. The first is a default configuration file, **eclv_defaults.yaml**, @@ -113,7 +113,7 @@ Modify the *stat_input* setting in the file to explicitly point to the *$METPLOTPY_BASE/test/eclv/* directory (where the custom config files and sample data reside). -Replace the relative path *.eclv.data* +Replace the relative path *./eclv.data* with the full path *$METPLOTPY_BASE/test/eclv/eclv.data* (including replacing *$METPLOTPY_BASE* with the full path to the METplotpy @@ -145,7 +145,7 @@ Uncomment or add (if it doesn't exist) the *points_path* setting: *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the same directory where the +Replace the */dir_to_save_points1_file* with the same directory where the **.points1** file is saved. If *points_path* is commented out (indicated by a '#' symbol in front of it), remove the '#' symbol to uncomment @@ -157,7 +157,7 @@ files unless saving the intermediate **.points1** file is desired. To save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -165,7 +165,7 @@ Using Defaults -------------- There isn't a set of "default" values to create a meaningful ECLV plot. Use the combination of the -default_eclv.yaml and custom_eclv.yaml file to create a sample ECLV plot. +eclv_defaults.yaml and custom_eclv.yaml file to create a sample ECLV plot. Run from the Command Line @@ -177,7 +177,7 @@ perform the following: * If using the conda environment, verify the conda environment - is running and has has the required Python packages outlined in the + is running and has the required Python packages outlined in the `requirements section `_. @@ -187,13 +187,13 @@ perform the following: For the ksh environment: .. code-block:: ini - + export METPLOTPY_BASE=$METPLOTPY_BASE For the csh environment: .. code-block:: ini - + setenv METPLOTPY_BASE $METPLOTPY_BASE Recall that *$METPLOTPY_BASE* is the directory path indicating where the METplotpy source code was saved. diff --git a/docs/Users_Guide/ens_ss.rst b/docs/Users_Guide/ens_ss.rst index e077f3ad..d8949558 100644 --- a/docs/Users_Guide/ens_ss.rst +++ b/docs/Users_Guide/ens_ss.rst @@ -5,7 +5,7 @@ Ensemble Spread-Skill Plot Description =========== The theory is that RMSE of the ensemble mean should have roughly a 1-1 -relationship with the ensemble spread (I.e. standard deviation of the +relationship with the ensemble spread (i.e. standard deviation of the ensemble member values). Ensemble spread-skill plot measures that relationship. Example @@ -25,12 +25,12 @@ repository, where the Ensemble spread-skill plot tests are located: e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. @@ -70,7 +70,7 @@ Default Configuration File -------------------------- The following is the *mandatory*, **ens_ss_defaults.yaml** configuration -file, which serves as a good starting point for creating a line +file, which serves as a good starting point for creating an ensemble spread-skill plot as it represents the default values set in METviewer. .. literalinclude:: ../../metplotpy/plots/config/ens_ss_defaults.yaml @@ -136,7 +136,7 @@ For example: *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the directory where +Replace the */dir_to_save_points1_file* with the directory where the **.points1** file is saved. If points_path is commented out (indicated by a '#' symbol in front of it), remove the '#' symbol to uncomment @@ -147,7 +147,7 @@ to be defined unless saving the intermediate **.points1** file is desired. To save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -163,7 +163,7 @@ The **custom_ens_ss.yaml** configuration file, in combination with the Perform the following: * If the conda environment is being used, - verify the conda environment is running and has has the required + verify the conda environment is running and has the required Python packages outlined in the `requirements section `_. diff --git a/docs/Users_Guide/fv3_physics.rst b/docs/Users_Guide/fv3_physics.rst index 0da39d7f..a91ac4e9 100644 --- a/docs/Users_Guide/fv3_physics.rst +++ b/docs/Users_Guide/fv3_physics.rst @@ -43,7 +43,7 @@ Required input: #. FV3 3-D history file with physics and dynamics tendencies (fv3_history.nc) -#. FV3 2-D grid specification file with latititude and longitude of each grid point (grid_spec.nc) +#. FV3 2-D grid specification file with latitude and longitude of each grid point (grid_spec.nc) Click here to access the METplus releases page and download sample data for the appropriate release: https://github.com/dtcenter/METplus/releases. Links to input data directories are in the description of each release. The file to download is named *sample_data\-short_range-x.y.tgz* (where x.y represents the version). @@ -60,7 +60,7 @@ Default tendency variable names Default tendency variable names are below. The tendencies that are available depend on the physics suite that the user selects when running FV3; more specifically, its contents are determined by the diag_table file that the user sets up. The history file that we -use our example is for a specific diag_table and so may change with different FV3 configurations. +use in our example is for a specific diag_table and so may change with different FV3 configurations. The user must make sure the names in the configuration file *$METPLOTPY_BASE/test/fv3_physics_tend/fv3_physics_tend_defaults.yaml* match the names used in fv3_history.nc for their case. @@ -120,7 +120,7 @@ If time window overlaps initialization time ------------------------------------------- The history file does not necessarily have the temperature, moisture, or wind at the exact -time of model initialization. It is usally the next timestep (e.g. 180 seconds later). +time of model initialization. It is usually the next timestep (e.g. 180 seconds later). This means you cannot derive the actual change in temperature starting at the model initialization time. You must choose a later valid time and/or a shorter time window that does not overlap the initialization time. In other words, it is a problem if your model initialization time is 0z, your diff --git a/docs/Users_Guide/histogram.rst b/docs/Users_Guide/histogram.rst index 2237edf8..304a352d 100644 --- a/docs/Users_Guide/histogram.rst +++ b/docs/Users_Guide/histogram.rst @@ -48,12 +48,12 @@ repository, where the histogram test scripts are located: e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. @@ -65,7 +65,7 @@ input data is located and to set plot attributes. These plot attributes correspond to values that can be set via the METviewer tool. YAML is a recursive acronym for "YAML Ain't Markup Language" and according to `yaml.org `_, -it is a "human-friendly data serialization language. It is commonly used for +it is a "human-friendly data serialization language". It is commonly used for configuration files and in applications where data is being stored or transmitted. Two configuration files are required. The first is a default configuration file, **hist_defaults.yaml**, @@ -110,7 +110,7 @@ Custom Configuration File A second, *mandatory* configuration file is required, which is used to customize the settings to generate each of the specialized histograms. -The **rank_hist.yaml** , **rank_hist.yaml**, and **rank_hist.yaml** files are included with the +The **rank_hist.yaml**, **prob_hist.yaml**, and **rel_hist.yaml** files are included with the source code and look like the following: **Rank histogram config file:** @@ -172,7 +172,7 @@ In the *$METPLOTPY_BASE/test/histogram/rank_hist.yaml* file, replace the relative path *./rank_hist.data* with the full path *$METPLOTPY_BASE/test/histogram/rank_hist.data* for the rank histogram config file (including replacing *$METPLOTPY_BASE* with the full path to the METplotpy -installation on the system).. +installation on the system). In the *$METPLOTPY_BASE/test/histogram/prob_hist.yaml* file, replace the relative path *./prob_hist.data* with the full path @@ -190,7 +190,7 @@ for the relative frequency histogram config file. Modify the *plot_filename* setting to point to the output path where the plot will be saved, including the name of the plot. -For example +For example: For the **rank histogram**: @@ -230,7 +230,7 @@ Uncomment or add (if it doesn't exist) the *points_path* setting: *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the same directory where the +Replace the */dir_to_save_points1_file* with the same directory where the **.points1** file is saved. If *points_path* is commented out (indicated by a '#' symbol in front of it), remove the '#' symbol to uncomment @@ -243,7 +243,7 @@ file unless saving the intermediate **.points1** file is desired. For each of the histogram custom config files (rank, probability, and relative frequency), to save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -258,7 +258,7 @@ perform the following: * If using the conda environment, verify the conda environment - is running and has has the required Python packages outlined in the + is running and has the required Python packages outlined in the `requirements section `_. @@ -268,13 +268,13 @@ perform the following: For the ksh environment: .. code-block:: ini - + export METPLOTPY_BASE=$METPLOTPY_BASE For the csh environment: .. code-block:: ini - + setenv METPLOTPY_BASE $METPLOTPY_BASE Recall that *$METPLOTPY_BASE* is the directory path indicating where the METplotpy source code was saved. @@ -290,7 +290,7 @@ perform the following: This will create a PNG file, **rank_hist.png**, in the directory that was specified in the *plot_filename* - setting of the **minimal_histogram.yaml** config file: + setting of the **rank_hist.yaml** config file: .. image:: figure/rank_hist.png @@ -298,7 +298,7 @@ perform the following: command using the **prob_hist.yaml** file: .. code-block:: ini - + python $METPLOTPY_BASE/metplotpy/plots/histogram/prob_hist.py $WORKING_DIR/prob_hist.yaml .. image:: figure/prob_hist.png @@ -318,9 +318,9 @@ perform the following: in the **rank_hist.yaml** config file. * A **prob_hist.png** output file will be - created in the the directory that was specified in the *plot_filename* config setting + created in the directory that was specified in the *plot_filename* config setting in the **prob_hist.yaml** config file. * A **rel_hist.png** output file will be - created in the the directory that was specified in the *plot_filename* config setting + created in the directory that was specified in the *plot_filename* config setting in the **rel_hist.yaml** config file. diff --git a/docs/Users_Guide/histogram_2d.rst b/docs/Users_Guide/histogram_2d.rst index 4f3d20c2..922d9b0f 100644 --- a/docs/Users_Guide/histogram_2d.rst +++ b/docs/Users_Guide/histogram_2d.rst @@ -28,12 +28,12 @@ METplotpy repository, where the **histogram_2d.py** code is located: e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. Configuration File @@ -44,7 +44,7 @@ input data is located and to set plot attributes. **NOTE**: The histogram_2d plot is currently **not** integrated into the METviewer tool, and as a result the configuration file has fewer settings than the other plot types that are available through the METviewer tool. YAML is -a recursive acroynym for "YAML Ain't Markup Language" and according to +a recursive acronym for "YAML Ain't Markup Language" and according to `yaml.org `_, it is a "human-friendly data serialization language". It is commonly used for configuration files and in applications where data is being stored or transmitted. Two configuration files are @@ -135,7 +135,7 @@ The *points_path*, *dump_points_1*, and *dump_points_2* settings are intermediate files that are used by METviewer are currently not being generated (this plot type is currently not integrated into the METviewer tool which is why these intermediate files are not being -generated). The *points_path*, *dump_points_1*, and *dump_points2* +generated). The *points_path*, *dump_points_1*, and *dump_points_2* settings can be commented out (i.e. line begins with a '#'): *# points_path: /path/to/your/directory* @@ -146,7 +146,7 @@ settings can be commented out (i.e. line begins with a '#'): To save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -211,14 +211,14 @@ Perform the following: * Clone the METplotpy repository from GitHub. First, make the directory: .. code-block:: ini - + mkdir $METPLOTPY_BASE -* *$METPLOTPY_BASE* is the directory where the source code is66TAW saved. +* *$METPLOTPY_BASE* is the directory where the source code is saved. Enter the following: .. code-block:: ini - + cd $METPLOTPY_BASE git clone https://github.com/dtcenter/METplotpy @@ -239,7 +239,7 @@ Perform the following: Replace *$METPLOTPY_BASE* with the directory where the source code is saved. - To generate the above **"defaults"** plot (i.e using default configuration + To generate the above **"defaults"** plot (i.e. using default configuration settings), use the "minimal" custom configuration file, **minimal_histogram_2d.yaml**. diff --git a/docs/Users_Guide/hovmoeller.rst b/docs/Users_Guide/hovmoeller.rst index ede5175f..85f5a781 100644 --- a/docs/Users_Guide/hovmoeller.rst +++ b/docs/Users_Guide/hovmoeller.rst @@ -64,12 +64,12 @@ There is a YAML config file located in e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. The Hovmoeller plot utilizes YAML configuration files to indicate where input data is located and to set plot attributes, and logging preferences. @@ -142,7 +142,7 @@ For example: This is where */username/working_dir* is *$WORKING_DIR*. Make sure that the *$WORKING_DIR* directory that is specified exists and has the appropriate -read and write permissions.The path listed for *plot_filename* may be +read and write permissions. The path listed for *plot_filename* may be changed to the output directory of one’s choosing. If this is not set, then the *plot_filename* setting specified in the *$METPLOTPY_BASE/metplotpy/plots/config/hovmoeller_defaults.yaml* @@ -150,7 +150,7 @@ configuration file will be used. To save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -212,13 +212,13 @@ the **hovmoeller_defaults.yaml** configuration file looks like the following: Perform the following: * To use the conda environment, verify the conda environment - is running and has has the required + is running and has the required Python packages outlined in the `Python Requirements section `_ - (and from the Requirements Packages section above). + (and from the Required Packages section above). * Set the PYTHONPATH environment variable: -*$METCALCPY_SOURCE* is the path downloaded/cloned METcalcpy code. *$METPLOTPY_SOURCE* is the path of the +*$METCALCPY_SOURCE* is the path of the downloaded/cloned METcalcpy code. *$METPLOTPY_SOURCE* is the path of the downloaded/cloned METplotpy code. **Command for csh:** @@ -254,7 +254,7 @@ downloaded/cloned METplotpy code. METplotpy source code was saved. - To generate the above **"defaults"** plot (i.e using default configuration settings), use the "minimal" custom + To generate the above **"defaults"** plot (i.e. using default configuration settings), use the "minimal" custom configuration file, **minimal_hovmoeller.yaml**. * Enter the following command: diff --git a/docs/Users_Guide/index.rst b/docs/Users_Guide/index.rst index 79c26946..50656b1b 100644 --- a/docs/Users_Guide/index.rst +++ b/docs/Users_Guide/index.rst @@ -53,12 +53,12 @@ Available `here `_. We thank all of the METplus sponsors including: Developmental Testbed Center (DTC) partners (NOAA, NCAR, USAF, and NSF), along with NOAA/Office of Atmospheric Research (OAR), NOAA/National Weather Service, -NOAA/Joint Technology Transfer Program (JTTI), +NOAA/Joint Technology Transfer Initiative (JTTI), NOAA/Subseasonal to Seasonal (S2S) Project, NOAA/Unified Forecast System Research to Operations Project (UFS R2O), Met Office and the Naval Research Laboratory (NRL). Thanks also go to the staff at the DTC for their help, advice, and many types of support. Finally, the National Center for -Atmospheric Research (NCAR), sponsored by National Science Foundation. +Atmospheric Research (NCAR) is sponsored by NSF. .. toctree:: diff --git a/docs/Users_Guide/installation.rst b/docs/Users_Guide/installation.rst index fec8f9a1..8f516057 100644 --- a/docs/Users_Guide/installation.rst +++ b/docs/Users_Guide/installation.rst @@ -28,7 +28,7 @@ The METplotpy source code can be retrieved using the web browser. Begin by enter https://github.com/dtcenter/METplotpy in the web browser's navigation bar. On the right-hand side of the web page for the METplotpy repository, click on the `Releases` link. This leads to a page where all available releases are available. The latest release will be -located at the top of the page. Scroll to the release of interest and below it's title is an `Assets` link in small +located at the top of the page. Scroll to the release of interest and below its title is an `Assets` link in small text. Click on the inverted triangle to the left of the `Assets` text to access the menu. To download the source code, click on either the zip or tar.gz version of the source code and save it to a directory where the METplotpy source code will reside (e.g. /home/someuser/). @@ -47,11 +47,11 @@ base directory, then run the following commands. $ conda activate metplotpy (metplotpy)$ pip install -e . -This will install METplotpy into the conda env, along with all the dependancies +This will install METplotpy into the conda env, along with all the dependencies listed above in **requirements.txt**. -If you already have an environment setup, or want to install METplotpy without -the dependancies, add the `--no-deps` argument to pip. +If you already have an environment set up, or want to install METplotpy without +the dependencies, add the `--no-deps` argument to pip. .. code-block:: ini @@ -75,7 +75,7 @@ find the **setup.py** script. From the command line run: .. code-block:: ini - + pip install -e . Do NOT forget the ending period **'.'** This indicates the **setup.py** @@ -89,10 +89,10 @@ code. Setting up the PYTHONPATH ------------------------- -This is a workaround for users who can not or do not have permission to +This is a workaround for users who cannot or do not have permission to create conda environments. -*$METCALCPY_SOURCE* is the path downloaded/cloned METcalcpy code. *$METPLOTPY_SOURCE* is the path of the +*$METCALCPY_SOURCE* is the path of the downloaded/cloned METcalcpy code. *$METPLOTPY_SOURCE* is the path of the downloaded/cloned METplotpy code. **Command for csh:** diff --git a/docs/Users_Guide/line.rst b/docs/Users_Guide/line.rst index 45549dba..0aab9cb3 100644 --- a/docs/Users_Guide/line.rst +++ b/docs/Users_Guide/line.rst @@ -27,12 +27,12 @@ create an example line plot is available in the e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. Configuration Files @@ -51,7 +51,7 @@ configuration file, **line_defaults.yaml**, which is found in the *$METPLOTPY_BASE/metplotpy/plots/config* directory. All default configuration files are located in the *$METPLOTPY_BASE/metplotpy/plots/config* directory. -*$METPLOTPY_BASE* is base directory where the +*$METPLOTPY_BASE* is the base directory where the METplotpy source code has been saved. **Default configuration files are automatically loaded by the plotting code and do not need to be explicitly specified when generating a plot**. @@ -103,7 +103,7 @@ Copy this custom config file from the directory where the source code was saved to the working directory: .. code-block:: ini - + cp $METPLOTPY_BASE/test/line/custom_line.yaml $WORKING_DIR/custom_line.yaml @@ -142,7 +142,7 @@ setting to True. Uncomment or add (if it doesn't exist) the *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the same directory where +Replace the */dir_to_save_points1_file* with the same directory where the **.points1** file is saved. If *points_path* is commented out (indicated by a '#' symbol in front of it), remove the '#' symbol to uncomment the points_path so that it will be @@ -153,7 +153,7 @@ unless saving the intermediate **.points1** file is desired. To save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -206,7 +206,7 @@ Run from the Command Line ========================= The **custom_line.yaml** configuration file, in combination with the -**line_defaults.yaml** configuration file, generate a plot of +**line_defaults.yaml** configuration file, generates a plot of five series: .. image:: figure/line.png @@ -225,7 +225,7 @@ To generate the above plot using the **line_defaults.yaml** and For the ksh environment: .. code-block:: ini - + export METPLOTPY_BASE=$METPLOTPY_BASE For the csh environment: @@ -236,7 +236,7 @@ To generate the above plot using the **line_defaults.yaml** and Recall that *$METPLOTPY_BASE* is the directory path indicating where the METplotpy source code was saved. - To generate the above **"custom"** plot (i.e using some custom + To generate the above **"custom"** plot (i.e. using some custom configuration settings), use the custom configuration file, **custom_line.yaml**. @@ -248,10 +248,10 @@ To generate the above plot using the **line_defaults.yaml** and * A **line.png** output file will be created in the directory specified in - the *plot_filename* configuration setting in the **line.yaml** config file. + the *plot_filename* configuration setting in the **custom_line.yaml** config file. - To generate the **"defaults"** plot below (i.e using default configuration + To generate the **"defaults"** plot below (i.e. using default configuration settings), use the "minimal" custom configuration file, **minimal_line.yaml**. @@ -264,7 +264,7 @@ To generate the above plot using the **line_defaults.yaml** and * A **line_default.png** output file will be created in the directory specified in the *plot_filename* configuration setting - in the **line_defaults.yaml** config file. + in the **minimal_line.yaml** config file. .. image:: figure/line_default.png diff --git a/docs/Users_Guide/make_maki_enso.rst b/docs/Users_Guide/make_maki_enso.rst index f1ee973e..8de15511 100644 --- a/docs/Users_Guide/make_maki_enso.rst +++ b/docs/Users_Guide/make_maki_enso.rst @@ -18,7 +18,7 @@ There are `METplus use cases `_ which illustrate how to generate the MaKE MaKI plot: -* To generate a MaKE MaKI, follow the instructions in the METplus users guide on the UserScript_obsCFSR_obsOnly_MJO_ENSO use case: +* To generate a MaKE MaKI plot, follow the instructions in the METplus User's Guide on the `UserScript_obsCFSR_obsOnly_MJO_ENSO `__ use case. Instructions for obtaining sample data and all necessary configuration files diff --git a/docs/Users_Guide/mjo_rmm_omi.rst b/docs/Users_Guide/mjo_rmm_omi.rst index 0ac64ac4..45a3acc2 100644 --- a/docs/Users_Guide/mjo_rmm_omi.rst +++ b/docs/Users_Guide/mjo_rmm_omi.rst @@ -5,10 +5,10 @@ MJO Plots Description =========== -The **compute_mjo_indices.py** code (found in the METplotpy repository) +The **compute_mjo_indices.py** code (found in the METcalcpy repository, in metcalcpy/contributed/rmm_omi) supports the generation of RMM (Real-time Multivariate MJO), OMI (OLR based MJO Index), and phase diagrams from MJO -(Madden-Julien Oscillation) indices. +(Madden-Julian Oscillation) indices. These indices are calculated by **compute_mjo_indices.py** in the METcalcpy repository. These modules are used as part of METplus use cases on generating these three diagrams. diff --git a/docs/Users_Guide/performance_diagram.rst b/docs/Users_Guide/performance_diagram.rst index fcdd85b4..63b2fc4c 100644 --- a/docs/Users_Guide/performance_diagram.rst +++ b/docs/Users_Guide/performance_diagram.rst @@ -10,7 +10,7 @@ statistics, with axes representing detection and success (1 - false alarm) rates (:ref:`Roebber, 2009`). The simplest input to the performance diagram is the MET contingency table statistics (CTS) output. This output can be produced by many of -the MET tools (Point-Stat, Grid-Stat, etc.) +the MET tools (Point-Stat, Grid-Stat, etc.). For more information on Performance diagrams, please refer to the `METviewer documentation `_. @@ -41,12 +41,12 @@ repository, where the performance diagram scripts are located: e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. @@ -59,7 +59,7 @@ input data is located and to set plot attributes. These plot attributes correspond to values that can be set via the METviewer tool. YAML is a recursive acronym for "YAML Ain't Markup Language" and according to `yaml.org `_, -it is a "human-friendly data serialization language. It is commonly used for +it is a "human-friendly data serialization language". It is commonly used for configuration files and in applications where data is being stored or transmitted. Two configuration files are required. The first is a default configuration file, **performance_diagram_defaults.yaml**, @@ -154,7 +154,7 @@ Uncomment or add (if it doesn't exist) the *points_path* setting: *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the same directory where the +Replace the */dir_to_save_points1_file* with the same directory where the **.points1** file is saved. If *points_path* is commented out (indicated by a '#' symbol in front of it), remove the '#' symbol to uncomment @@ -166,7 +166,7 @@ file unless saving the intermediate **.points1** file is desired. To save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -177,7 +177,7 @@ Using Defaults To use the *default* settings defined in the **performance_diagram_defaults.yaml** file, specify a minimal custom configuration file -(**minimal_performance_diagram_defaults.yaml**), which consists of only +(**minimal_performance_diagram.yaml**), which consists of only a comment block, but it can be any empty file (write permissions for the output filename path corresponding to the *plot_filename* setting in the default configuration file will be needed. Otherwise, specify @@ -188,7 +188,7 @@ a *plot_filename* in the **minimal_performance_diagram.yaml** file): Copy this file to the working directory: .. code-block:: ini - + cp $METPLOTPY_BASE/test/performance_diagram/minimal_performance_diagram.yaml $WORKING_DIR/minimal_performance_diagram.yaml Add the *stat_input* (input data) and *plot_filename* @@ -211,7 +211,7 @@ Replace *$METPLOTPY_BASE* with the full path to the METplotpy installation on the system. **NOTE**: The *plot_filename* (output directory) may be specified to a directory other than the *$WORKING_DIR/output_plots*, as long as -it is an existing directory where the author has read and write permissions. +it is an existing directory where the user has read and write permissions. To save the intermediate **.points1** file (used by METviewer and useful for debugging), add the following lines to the @@ -222,8 +222,8 @@ for debugging), add the following lines to the *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the same directory where -the **.points** file is saved. Make sure that this directory exists +Replace the */dir_to_save_points1_file* with the same directory where +the **.points1** file is saved. Make sure that this directory exists and has the appropriate read and write permissions. @@ -236,7 +236,7 @@ perform the following: * If using the conda environment, verify the conda environment - is running and has has the required Python packages outlined in the + is running and has the required Python packages outlined in the `requirements section `_. * Set the METPLOTPY_BASE environment variable to point to @@ -245,13 +245,13 @@ perform the following: For the ksh environment: .. code-block:: ini - + export METPLOTPY_BASE=$METPLOTPY_BASE For the csh environment: .. code-block:: ini - + setenv METPLOTPY_BASE $METPLOTPY_BASE Replacing the $METPLOTPY_BASE with the directory where the @@ -273,7 +273,7 @@ perform the following: command using the **custom_performance_diagram.yaml** file: .. code-block:: ini - + python $METPLOTPY_BASE/metplotpy/plots/performance_diagram/performance_diagram.py $WORKING_DIR/custom_performance_diagram.yaml .. image:: figure/performance_diagram_custom.png diff --git a/docs/Users_Guide/polar_plot.rst b/docs/Users_Guide/polar_plot.rst index 76fb6837..25e3fb83 100644 --- a/docs/Users_Guide/polar_plot.rst +++ b/docs/Users_Guide/polar_plot.rst @@ -6,7 +6,7 @@ Description =========== A Polar Ice plot is a 2D plot using a polar stereographic projection. There is a specific example found in the polar_ice_plot which plots -sea ice area averages +sea ice area averages. To generate the polar_ice_plot edit the polar_ice.yaml and have your input file point to either the example or one of your choosing and then run @@ -64,12 +64,12 @@ There is a YAML config file located in e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. Copy this configuration file from where you saved the METplotpy source code to your working directory: @@ -99,11 +99,11 @@ To generate the example Polar Ice plot (i.e. using settings in the **polar_ice.yaml** configuration file) perform the following: * If using the conda environment, verify the conda environment - is running and has has the required Python packages specified in the + is running and has the required Python packages specified in the **Required Packages** section above. * Set the METPLOTPY_BASE environment variable to point to - *$METPLOTPY_BASE*. where $METPLOTPY_BASE is the directory where you saved the + *$METPLOTPY_BASE*, where $METPLOTPY_BASE is the directory where you saved the METplotpy source code (e.g. /home/someuser). For the ksh environment: @@ -131,7 +131,7 @@ copied the config file. The polar_ice_plot.py script looks for the polar_ice.ya directory. -Three plots named **20210305_120000_fcst_ice_north.png** **20210305_120000_ice_diff_north.png** **20210305_120000_observation_ice_north.png** will be generated in the sub directory ice_plots from where you ran the above command: +Three plots named **20210305_120000_fcst_ice_north.png** **20210305_120000_ice_diff_north.png** **20210305_120000_observation_ice_north.png** will be generated in the subdirectory ice_plots from where you ran the above command: .. image:: figure/fcst_ice_north.png .. image:: figure/ice_diff_north.png diff --git a/docs/Users_Guide/references.rst b/docs/Users_Guide/references.rst index df2b45a0..c81ddb00 100644 --- a/docs/Users_Guide/references.rst +++ b/docs/Users_Guide/references.rst @@ -4,9 +4,8 @@ References .. _Hoaglin: -| Hoaglin, D. C., Mosteller F. and Tukey, J. W., 1983: *Understanding robust* +| Hoaglin, D. C., Mosteller, F. and Tukey, J. W., 1983: *Understanding robust* | *and exploratory data analysis.* Hoboken, NJ: Wiley. -| doi: https://doi.org/10.2307/2988240 | .. _Richardson: @@ -18,7 +17,7 @@ References .. _Roebber: -| Roebber, P.J., 2009: Visualizing Multiple Measures of Forecast Quality +| Roebber, P.J., 2009: Visualizing Multiple Measures of Forecast Quality. | *Weather and Forecasting*, 24, 601-608. | doi: https://doi.org/10.1175/2008WAF2222159.1 diff --git a/docs/Users_Guide/release-notes.rst b/docs/Users_Guide/release-notes.rst index 741a0f29..09e078d0 100644 --- a/docs/Users_Guide/release-notes.rst +++ b/docs/Users_Guide/release-notes.rst @@ -19,7 +19,7 @@ METplotpy Version 13.0.0-beta2 release notes (20260507) * **Remove plotly dependency** (`#555 `_) * Remove plotly: Create copy of base/common functionality using matplotlib (`#556 `_) * Remove scikit-image package from nco_requirements.txt and requirements.txt (`#565 `_) - * Remove plotly: Update bar, box, and histogramm plot (`#558 `_) + * Remove plotly: Update bar, box, and histogram plot (`#558 `_) * Remove plotly: Update ROC diagram, Reliability diagram, and ens_ss plots (`#569 `_) * Remove plotly: Update contour plot (`#572 `_) * Remove plotly: Wind Rose, MPR, Hovmoeller, TCMPR, 2D Histogram (`#574 `_) @@ -69,6 +69,6 @@ This section summarizes and highlights important changes to METplotpy since vers .. note:: - Plots that originally utilized the Python Plotly plotting package are now using Matplotlib. As a result, all plots in this repository utilize Matplotlib. This removes the dependency on chrome by the kaleido module in Plotly. The kaleido/chrome dependency required run-time downloading of chrome and also broke existing functionality. + Plots that originally utilized the Python Plotly plotting package are now using Matplotlib. As a result, all plots in this repository utilize Matplotlib. This removes the dependency on Chrome by the kaleido module in Plotly. The kaleido/Chrome dependency required run-time downloading of Chrome and also broke existing functionality. The version numbering for METplotpy has been updated to 13.0.0 to provide consistency and clarity with all METplus components. View the requirements.txt/nco_requirements.txt file at the top level of the repository for version numbers for the corresponding third-party packages. diff --git a/docs/Users_Guide/reliability_diagram.rst b/docs/Users_Guide/reliability_diagram.rst index b23bd1f5..eac13ab4 100644 --- a/docs/Users_Guide/reliability_diagram.rst +++ b/docs/Users_Guide/reliability_diagram.rst @@ -25,12 +25,12 @@ in the METplotpy repository, where the reliability diagram code is located: e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. @@ -52,7 +52,7 @@ configuration files are located in the **Note**: *$METPLOTPY_BASE* is the user-specified directory where the METplotpy source code has been saved. **Default configuration files are automatically loaded by the plotting code and do not need to -be explicitly specified when generating a plot** +be explicitly specified when generating a plot**. The second required configuration file is a user-supplied “custom” configuration file. This file is used to customize/override the default @@ -77,7 +77,7 @@ plot as it represents the default values set in METviewer. In the default config file, logging is set to stdout and the log level is ERROR (i.e. only log messages of type ERROR will be logged). If the log_filename and log_level are -not specified in the custom configuration file, these settings will be used +not specified in the custom configuration file, these settings will be used. Custom Configuration File @@ -86,7 +86,7 @@ Custom Configuration File A second, *mandatory* configuration file is required, which is used to customize the settings to the reliability diagram plot. The **custom_reliability.yaml** -file is included with the source code an looks like the following: +file is included with the source code and looks like the following: .. literalinclude:: ../../test/reliability_diagram/custom_reliability_diagram.yaml @@ -122,7 +122,7 @@ This is where */username/myworkspace/METplotpy* is *$METPLOTPY_BASE* and read and write permissions. The path listed for *plot_filename* may be changed to the output directory of one's choosing. If this is not set, then the *plot_filename* setting specified in the -*$METPLOTPY_BASE/metplotpy/plots/config/reliability_diagram_defaults.yaml* +*$METPLOTPY_BASE/metplotpy/plots/config/reliability_defaults.yaml* configuration file will be used. To save the intermediate **.points1** file (used by METviewer and useful @@ -133,7 +133,7 @@ Uncomment or add (if it doesn't exist) the *points_path* setting: *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the directory where +Replace the */dir_to_save_points1_file* with the directory where the **.points1** file is saved. If points_path is commented out (indicated by a '#' symbol in front of it), remove the '#' symbol to uncomment the points_path so that it will be @@ -144,7 +144,7 @@ file unless saving the intermediate **.points1** file is desired. To save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -158,7 +158,7 @@ If the user wishes to use all the default settings defined in the as the user has write permissions for the output filename path corresponding to the *plot_filename* setting in the default configuration file. Otherwise, this will need to be specified in -*plot_filename* in the **minimal_box.yaml** file): +*plot_filename* in the **minimal_reliability.yaml** file): .. literalinclude:: ../../test/reliability_diagram/minimal_reliability.yaml @@ -197,7 +197,7 @@ for debugging), add the following lines to the *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the same directory where the +Replace the */dir_to_save_points1_file* with the same directory where the **.points1** file is located. Make sure that this directory exists and has the appropriate read and write permissions. **NOTE**: the *points_path* setting @@ -219,7 +219,7 @@ the "empty" custom configuration file and the Perform the following: * Clone the code from the `METplotpy repository - `_ (To see the page, login to Github): + `_ (To see the page, log in to GitHub): .. code-block:: ini @@ -227,7 +227,7 @@ Perform the following: git clone https://github.com/dtcenter/METplotpy * If using the conda environment, verify the conda environment is - running and has has the required Python packages outlined in + running and has the required Python packages outlined in the `requirements section `_. * Set the METPLOTPY_BASE environment variable to point to @@ -267,7 +267,7 @@ Perform the following: * Enter the following command: .. code-block:: ini - + python $METPLOTPY_BASE/metplotpy/plots/reliability_diagram/reliability.py $WORKING_DIR/custom_reliability_diagram.yaml In this example, this custom config file changes the color of the boxes. diff --git a/docs/Users_Guide/roc_diagram.rst b/docs/Users_Guide/roc_diagram.rst index a1672869..97828934 100644 --- a/docs/Users_Guide/roc_diagram.rst +++ b/docs/Users_Guide/roc_diagram.rst @@ -41,12 +41,12 @@ is installed. (e.g. */username/myworkspace*): e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. Configuration Files @@ -59,7 +59,7 @@ acronym for "YAML Ain't Markup Language" and according to `yaml.org `_, it is a "human-friendly data serialization language". It is commonly used for configuration files and in applications where data is being stored or transmitted. Two configuration files are -required. The first is a default configuration file, the first is a +required. The first is a default configuration file, **roc_diagram_defaults.yaml** that is found in the *$METPLOTPY_BASE/metplotpy/plots/config* directory. All default configuration files are located in the @@ -141,7 +141,7 @@ For example: This is where */username/myworkspace/METplotpy* is *$METPLOTPY_BASE* and */username/working_dir* is *$WORKING_DIR*. Make sure that the *$WORKING_DIR* directory that is specified exists and has the appropriate -read and write permissions.The path listed for *plot_filename* may be +read and write permissions. The path listed for *plot_filename* may be changed to the output directory of one’s choosing. If this is not set, then the *plot_filename* setting specified in the *$METPLOTPY_BASE/metplotpy/plots/config/roc_diagram_defaults.yaml* @@ -155,7 +155,7 @@ add (if it doesn't exist) the *points_path* setting. *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the directory where +Replace the */dir_to_save_points1_file* with the directory where the **.points1** file is saved. If points_path is commented out (indicated by a '#' symbol in front of it), remove the '#' symbol to uncomment the points_path so that it will be used by the code. Make sure that @@ -166,7 +166,7 @@ be defined in the configuration file unless saving the intermediate To save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -223,7 +223,7 @@ useful for debugging), add the following lines to the *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the same directory where +Replace the */dir_to_save_points1_file* with the same directory where the **.points1** file is saved. Make sure that this directory exists and has the appropriate read and write permissions. **NOTE**: the *points_path* setting is **optional** and does not need to be defined @@ -242,7 +242,7 @@ the **roc_diagram_defaults.yaml** configuration file looks like the following: Perform the following: * To use the conda environment, verify the conda environment - is running and has has the required + is running and has the required Python packages outlined in the `Python Requirements section `_. @@ -265,7 +265,7 @@ Perform the following: METplotpy source code was saved. - To generate the above **"defaults"** plot (i.e using default + To generate the above **"defaults"** plot (i.e. using default configuration settings), use the "minimal" custom configuration file, **minimal_roc_diagram.yaml**. @@ -288,7 +288,7 @@ Perform the following: * Enter the following command: .. code-block:: ini - + python $METPLOTPY_BASE/metplotpy/plots/roc_diagram/roc_diagram.py $WORKING_DIR/custom_roc_diagram.yaml In this example, this custom config file changes the title and axis diff --git a/docs/Users_Guide/scatter.rst b/docs/Users_Guide/scatter.rst index b940df77..aa66f7c5 100644 --- a/docs/Users_Guide/scatter.rst +++ b/docs/Users_Guide/scatter.rst @@ -11,7 +11,7 @@ This plot was developed to support plotting MPR (matched pair) data from the MET This MET output data must first be reformatted into a format that can be read in by the scatter plot code. This reformatting was accomplished through the METdataio METreformat module. The reformatted data - consists solely of MPR linetype data and all the column headers are labelled according to the + consists solely of MPR linetype data and all the column headers are labeled according to the MPR linetype column names specified in the Point-Stat section of the MET User's Guide in `Table 11.20 `_ "Format information for SEEPS (Stable Equitable Error in Probability Space) output line type". @@ -36,12 +36,12 @@ The sample data for creating the example scatter plot is available in the e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. .. note:: @@ -64,7 +64,7 @@ configuration file, **scatter_defaults.yaml**, which is found in the *$METPLOTPY_BASE/metplotpy/plots/config* directory. All default configuration files are located in the *$METPLOTPY_BASE/metplotpy/plots/config* directory. -*$METPLOTPY_BASE* is base directory where the +*$METPLOTPY_BASE* is the base directory where the METplotpy source code has been saved. **Default configuration files are automatically loaded by the plotting code and do not need to be explicitly specified when generating a plot**. In addition, the default configuration file @@ -123,16 +123,16 @@ Copy this custom config file from the directory where the source code was saved to the working directory: .. code-block:: ini - + cp $METPLOTPY_BASE/test/scatter/test_scatter_mpr.yaml $WORKING_DIR/custom_scatter.yaml Modify the *stat_input* setting in the -*$METPLOTPY_BASE/test/scatter/custom_scatter.yaml* file to +*$WORKING_DIR/custom_scatter.yaml* file to explicitly point to the *$METPLOTPY_BASE/test/scatter* directory (where the custom config files and sample data reside). -Replace the relative path *./scatter.data* with the full path -*$METPLOTPY_BASE/test/scatter/scatter.data* +Replace the relative path *./reformatted_data_for_scatter.data* with the full path +*$METPLOTPY_BASE/test/scatter/reformatted_data_for_scatter.data* (including replacing *$METPLOTPY_BASE* with the full path to the METplotpy installation on the system). @@ -165,7 +165,7 @@ Modify the *points_path* setting or add it (if it doesn't exist). *points_path: '/dir_to_save_plot_points_file'* -Replace the */dir_to_save_plot_points_file* to the same directory where +Replace the */dir_to_save_plot_points_file* with the same directory where the **plot_points.txt** file is saved. Make sure that this directory has the appropriate read and write permissions. @@ -173,7 +173,7 @@ To save the log output to a file, uncomment the *log_filename* entry and specify name of the log file. Select a directory with the appropriate read and write privileges. -To modify the verbosity of logging than what is set in the default config +To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -186,7 +186,7 @@ The **custom_scatter.yaml** configuration file, in combination with the **scatter_defaults.yaml** configuration file, generates a plot of the matched pair (MPR) linetype data for the TMP variable and the two continuous variables FCST and OBS. -The data has been further filtered based on the interpolation method and forecast level ( via the +The data has been further filtered based on the interpolation method and forecast level (via the *fixed_vars_vals_input* setting). The grid lines and trendline are turned on, the FCST, OBS, and OBS_LAT points are saved to a text file, and the @@ -208,7 +208,7 @@ To generate the above plot using the **scatter_defaults.yaml** and For the ksh environment: .. code-block:: ini - + export METPLOTPY_BASE=$METPLOTPY_BASE For the csh environment: @@ -228,7 +228,7 @@ To generate the above plot using the **scatter_defaults.yaml** and * A **scatter_mpr_tmp_obs_lat.png** output file will be created in the directory specified in - the *plot_filename* configuration setting in the **scatter.yaml** config file. + the *plot_filename* configuration setting in the **custom_scatter.yaml** config file. .. image:: figure/scatter_mpr_tmp_obs_lat.png diff --git a/docs/Users_Guide/skew_t.rst b/docs/Users_Guide/skew_t.rst index ffc1544e..1f07e020 100644 --- a/docs/Users_Guide/skew_t.rst +++ b/docs/Users_Guide/skew_t.rst @@ -4,7 +4,7 @@ Skew-T Log-P Diagram Description =========== -A skew-T log-P plot (skew-T for short) is a thermodynamic diagram used for plotting upper air observations. This skew-T plotting capability was developed to read in and the plot the ASCII output of tropical cyclone diagnostic (TC-Diag) sounding data generated by a diagnostics code set developed by Colorado Institute for Research in the Atmosphere (CIRA). The TC-Diag data are currently derived along a projected or specified track of the center of a tropical cyclone and are meant to represent the thermodynamic environment that the storm will be in if it follows the given track. This TC-Diag code set is in the process of being incorporated into the METplus suite and will be available in an upcoming release. This chapter explains how to create skew-T plots from TC-Diag output using METplotpy's Python-based plotter. +A skew-T log-P plot (skew-T for short) is a thermodynamic diagram used for plotting upper air observations. This skew-T plotting capability was developed to read in and plot the ASCII output of tropical cyclone diagnostic (TC-Diag) sounding data generated by a diagnostics code set developed by the Cooperative Institute for Research in the Atmosphere (CIRA). The TC-Diag data are currently derived along a projected or specified track of the center of a tropical cyclone and are meant to represent the thermodynamic environment that the storm will be in if it follows the given track. This TC-Diag code set is in the process of being incorporated into the METplus suite and will be available in an upcoming release. This chapter explains how to create skew-T plots from TC-Diag output using METplotpy's Python-based plotter. For more information on the skew-T log-P plot, please refer to the following: @@ -27,12 +27,12 @@ where *$METPLOTPY_BASE* is the directory where the METplotpy code is saved. e.g., -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. For background information on the CIRA TC model diagnostics, please refer to: diff --git a/docs/Users_Guide/stratosphere_diagnostics.rst b/docs/Users_Guide/stratosphere_diagnostics.rst index 18d0e1c7..18673e85 100644 --- a/docs/Users_Guide/stratosphere_diagnostics.rst +++ b/docs/Users_Guide/stratosphere_diagnostics.rst @@ -131,7 +131,7 @@ Run from the Command Line Perform the following: * To use the conda environment, verify the conda environment - is running and has has the required + is running and has the required Python packages specified in the **Required Packages** section above. * Set the METPLOTPY_BASE environment variable to point to diff --git a/docs/Users_Guide/stratosphere_plots.rst b/docs/Users_Guide/stratosphere_plots.rst index 6fc7def0..22f48016 100644 --- a/docs/Users_Guide/stratosphere_plots.rst +++ b/docs/Users_Guide/stratosphere_plots.rst @@ -6,15 +6,15 @@ Description =========== The **stratosphere_plots.py** script contains the plotting portion for -three Stratosphere use cases. One use case creates a ME plot in latitude and pressure, +three Stratosphere use cases. One use case creates an ME plot in latitude and pressure, another which creates ME and RMSE plots for lead time and pressure, and a third which -creates two phase diagrams and a time series of U for at 50mb and 30mb. -The three METplus use cases, illustrate how to use these plotting scripts for `zonal mean biases +creates two phase diagrams and a time series of U at 50mb and 30mb. +The three METplus use cases illustrate how to use these plotting scripts for `zonal mean biases `_, creating bias and RMSE for `polar cap temperature and polar vortex U `_, and creating `phase diagrams and time series for QBO `_. These files are used by the image comparison test: -* **GFS_ERA_ME_2018_02_zonal_mean_T.png**: Run "plot_zonal_bias" in **stratosphere_plots.py.py** +* **GFS_ERA_ME_2018_02_zonal_mean_T.png**: Run "plot_zonal_bias" in **stratosphere_plots.py** to create this plot. * **GFS_ERA_ME_2018_02_zonal_mean_U.png**: Run "plot_zonal_bias" in **stratosphere_plots.py** @@ -23,7 +23,7 @@ These files are used by the image comparison test: * **ME_2018_02_polar_cap_T.png**: Run "plot_polar_bias" in **stratosphere_plots.py** to create this plot. -* **ME_2018_02_polar_vortex_U.png**: Rn "plot_polar_bias" in **stratosphere_plots.py** +* **ME_2018_02_polar_vortex_U.png**: Run "plot_polar_bias" in **stratosphere_plots.py** to create this plot. * **RMSE_2018_02_polar_cap_T.png**: Run "plot_polar_rmse" in **stratosphere_plots.py** @@ -88,8 +88,8 @@ arrays (except outfile, ptitle, and plevs). **bias:** A numpy array containing the bias. -**obar:** A numpy array of the size wrnum containing the frequency of -occurrence of each cluster. +**obar:** A numpy array containing the observed mean, plotted as +contour lines over the bias. **outfile:** The full path and filename of the output plot file, a **.png** version will be written. @@ -211,7 +211,7 @@ Invoke the plotting functions: plot_u_timeseries(obs_dt,obs_u,fcst_dt,fcst_u,ptitle,outfile) -The output will be **.png** version of all requested plots and will +The output will be a **.png** version of all requested plots and will be located based on what was specified (path and name) in the **outfile**. diff --git a/docs/Users_Guide/taylor_diagram.rst b/docs/Users_Guide/taylor_diagram.rst index 8b29dea8..2b898f07 100644 --- a/docs/Users_Guide/taylor_diagram.rst +++ b/docs/Users_Guide/taylor_diagram.rst @@ -11,7 +11,7 @@ models and a "reference" based on the Pearson correlation coefficient, the root- error (RMSE), and the standard deviation. Taylor diagrams have been widely used for climate and other Earth science models but can be useful in the evaluation of models from other domains. -The normalized standard deviation and Pearson's Correlation coefficient are the only two values used to plot the +The normalized standard deviation and Pearson's correlation coefficient are the only two values used to plot the point and grid lines for the RMS. For more information on Taylor diagrams, please refer to the @@ -45,18 +45,18 @@ the FSTDEV, OSTDEV, and PR_CORR statistics are available for plotting. The sample data used to create these plots is available in the METplotpy repository, where the Taylor diagram scripts are located: -*$METPLOTPY_BASE/test/taylor_diagram/dlwr_sample.data* +*$METPLOTPY_BASE/test/taylor_diagram/plot_dlwr_sample.data* *$METPLOTPY_BASE* is the directory where the METplotpy code is saved: e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. @@ -68,7 +68,7 @@ input data is located and to set plot attributes. These plot attributes correspond to values that can be set via the METviewer tool. YAML is a recursive acronym for "YAML Ain't Markup Language" and according to `yaml.org `_, -it is a "human-friendly data serialization language. It is commonly used for +it is a "human-friendly data serialization language". It is commonly used for configuration files and in applications where data is being stored or transmitted. Two configuration files are required. The first is a default configuration file, **taylor_diagram_defaults.yaml**, @@ -131,11 +131,11 @@ code was saved to the working directory: Modify the *stat_input* setting in the *$METPLOTPY_BASE/test/taylor_diagram/taylor_diagram_custom.yaml* file to explicitly point to the -*$METPLOTPY_BASE/test/taylor_diagram/taylor_diagram* +*$METPLOTPY_BASE/test/taylor_diagram* directory (where the custom config files and sample data reside). -Replace the relative path *./dlwr_sample.data* +Replace the relative path *./plot_dlwr_sample.data* with the full path -*$METPLOTPY_BASE/test/taylor_diagram/dlwr_sample.data* +*$METPLOTPY_BASE/test/taylor_diagram/plot_dlwr_sample.data* (including replacing *$METPLOTPY_BASE* with the full path to the METplotpy installation on the system). Modify the *plot_filename* setting to point to the output path where the @@ -143,7 +143,7 @@ plot will be saved, including the name of the plot. For example: -*stat_input: /username/myworkspace/METplotpy/test/taylor_diagram/dlwr_sample.data* +*stat_input: /username/myworkspace/METplotpy/test/taylor_diagram/plot_dlwr_sample.data* *plot_filename: /username/working_dir/output_plots/taylor_diagram_custom.png* @@ -162,7 +162,7 @@ The *dump_points_1* setting is expected by METviewer and is set to False in the To save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -173,7 +173,7 @@ Using Defaults To use the *default* settings defined in the **taylor_diagram_defaults.yaml** file, specify a minimal custom configuration file -(**minimal_taylor_diagram_defaults.yaml**), which consists of only +(**minimal_taylor_diagram.yaml**), which consists of only a comment block, but it can be any empty file (write permissions for the output filename path corresponding to the *plot_filename* setting in the default configuration file will be needed. Otherwise, specify @@ -184,7 +184,7 @@ a *plot_filename* in the **minimal_taylor_diagram.yaml** file): Copy this file to the working directory: .. code-block:: ini - + cp $METPLOTPY_BASE/test/taylor_diagram/minimal_taylor_diagram.yaml $WORKING_DIR/minimal_taylor_diagram.yaml If the *stat_input* and *plot_filename* settings (output file/plot path) are missing, add @@ -192,11 +192,11 @@ these settings to the *$WORKING_DIR/minimal_taylor_diagram.yaml* file (anywhere below the comment block). The *stat_input* setting explicitly indicates where the sample data and custom configuration files are located. Set the *stat_input* to -*$METPLOTPY_BASE/test/taylor_diagram/dlwr_sample.data* and set the +*$METPLOTPY_BASE/test/taylor_diagram/plot_dlwr_sample.data* and set the *plot_filename* to *$WORKING_DIR/output_plots/taylor_diagram_default.png*: -*stat_input: $METPLOTPY_BASE/test/taylor_diagram/dlwr_sample.data* +*stat_input: $METPLOTPY_BASE/test/taylor_diagram/plot_dlwr_sample.data* *plot_filename: $WORKING_DIR/output_plots/taylor_diagram_default.png* @@ -204,7 +204,7 @@ files are located. Set the *stat_input* to the custom configuration files are being saved. **NOTE**: The *plot_filename* (output directory) may be specified to a directory other than the *$WORKING_DIR/output_plots*, as long as -it is an existing directory where the author has read and write permissions. +it is an existing directory where the user has read and write permissions. Run from the Command Line @@ -216,7 +216,7 @@ perform the following: * If using the conda environment, verify the conda environment - is running and has has the required Python packages outlined in the + is running and has the required Python packages outlined in the `requirements section `_. @@ -226,13 +226,13 @@ perform the following: For the ksh environment: .. code-block:: ini - + export METPLOTPY_BASE=$METPLOTPY_BASE For the csh environment: .. code-block:: ini - + setenv METPLOTPY_BASE $METPLOTPY_BASE Replacing the $METPLOTPY_BASE with the directory where the @@ -254,7 +254,7 @@ perform the following: command (below) using the **taylor_diagram_custom.yaml** file: .. code-block:: ini - + python $METPLOTPY_BASE/metplotpy/plots/taylor_diagram/taylor_diagram.py $WORKING_DIR/taylor_diagram_custom.yaml diff --git a/docs/Users_Guide/tcmpr_plots.rst b/docs/Users_Guide/tcmpr_plots.rst index b0091190..34d4093f 100644 --- a/docs/Users_Guide/tcmpr_plots.rst +++ b/docs/Users_Guide/tcmpr_plots.rst @@ -23,7 +23,7 @@ Use the same release versions for METplotpy and METcalcpy (i.e. if using a vx.y. same version for METcalcpy). -There are numerous TCMPR plots that can be generated within **one** YAML configuration files: +There are numerous TCMPR plots that can be generated within **one** YAML configuration file: * mean line plot * median line plot @@ -59,12 +59,12 @@ The sample data used to create various TCMPR plots is available in the e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. Configuration Files @@ -248,7 +248,7 @@ Copy this custom config file from the directory where the source code was saved to the working directory: .. code-block:: ini - + cp $METPLOTPY_BASE/test/tcmpr_plots/tcmpr_multi_plots.yaml $WORKING_DIR/tcmpr_multi_plots.yaml Set up the custom configuration file: @@ -285,7 +285,7 @@ For this example, the only settings requiring changes are: **tcst_dir**, **plot_ plot_dir: '/path/to/output_dir' - Replace */path/to/output_dir* to an existing directory that has the appropriate read and write privileges. + Replace */path/to/output_dir* with an existing directory that has the appropriate read and write privileges. .. dropdown:: **Specify the log level and log file** (optional): @@ -298,11 +298,11 @@ For this example, the only settings requiring changes are: **tcst_dir**, **plot_ log_filename: /path/to/output/tcmpr_log.out - Replace */path/to/output* to an existing directory with the appropriate read and write permissions. + Replace */path/to/output* with an existing directory with the appropriate read and write permissions. By default, the log level is set to ERROR (the least verbose) and logging is directed to STDOUT. The following - log levels are available (from most verbose to least): INFO, DEBUG, WARNING, ERROR. + log levels are available (from most verbose to least): DEBUG, INFO, WARNING, ERROR. -.. dropdown:: *Specify the baseline_file and column_info_file**: +.. dropdown:: **Specify the baseline_file and column_info_file**: .. code-block:: ini @@ -321,7 +321,7 @@ For this example, the only settings requiring changes are: **tcst_dir**, **plot_ - 'green' .. note :: - Make sure the number of columns specified corresponds to the number of series + Make sure the number of colors specified corresponds to the number of series being generated. .. dropdown :: *Specify the appearance of the symbols, lines, etc.* @@ -359,7 +359,7 @@ Below are descriptions of the settings used in this example: - H221 - M221 - Specify a key (AMODEL) and a list of one or more values of interest (e.g. the H221 and M221 models) + Specify a key (AMODEL) and a list of one or more values of interest (e.g. the H221 and M221 models). The above example will produce a plot with **two** lines/series, one for each AMODEL. The number of series/lines dictates the number of required plot settings. In this case, **two** values are needed for plot settings such as colors, symbols, series order, plot display (on/off), line widths, line styles, symbol appearance @@ -368,7 +368,7 @@ Below are descriptions of the settings used in this example: produced. The following settings are necessary for generating the plot types for this data set. -The settings will override the defaults in the tcmpr_defaults.yaml +The settings will override the defaults in the tcmpr_defaults.yaml. .. dropdown:: **Specify the independent (i.e. x-axis) variable, series, values and labels**: @@ -545,14 +545,14 @@ The settings will override the defaults in the tcmpr_defaults.yaml xaxis: 'Lead Time(h)' The *xaxis* setting is absent in the custom config file, tcmpr_multi_plots.yaml. When a setting is absent in - the custom config file. the default value is used. + the custom config file, the default value is used. If a different setting is desired, add the xaxis setting in the custom config file (anywhere in the file), tcmpr_multi_plots.yaml and set it to the desired text (surrounded by single or double quotes). The above settings define the creation of a boxplot, mean line plot, median line plot, rank plot, median skill plot, and mean skill plot for ABS(AMAX_WIND-BMAX_WIND) and TK_ERR. Each plot contains the lines/boxes for - the AMODEL M221 and H221, resulting in a total of fourteen plots. The plot titles, y-axis label,and output + the AMODEL M221 and H221, resulting in a total of fourteen plots. The plot titles, y-axis label, and output filenames are generated by the code. @@ -597,7 +597,7 @@ The **tcmpr_multi_plots.yaml** configuration file, in combination with the Generate plots with separate, specific configuration files: ----------------------------------------------------------- -This is an example of generating single plot types with titles axis labels specific to +This is an example of generating single plot types with titles and axis labels specific to that plot type. Two plot types will be generated, a boxplot and a relative performance plot. The line colors, series, independent values and labels, etc. are the same as those used in the tcmpr_multi_plots.yaml custom config file. @@ -690,25 +690,25 @@ Run from the Command Line .. code-block:: ini - export METPLOTPY_BASE=/path/to/METplotpy_source_cod + export METPLOTPY_BASE=/path/to/METplotpy_source_code For the csh environment: .. code-block:: ini - setenv METPLOTPY_BASE /path/to/METplotpy_source_cod + setenv METPLOTPY_BASE /path/to/METplotpy_source_code -Replace /path/to/METplotpy_source_code to the directory path where the METplotpy source code is saved. +Replace /path/to/METplotpy_source_code with the directory path where the METplotpy source code is saved. * Set the METCALCPY_BASE environment variable to point to where the METcalcpy source code resides, for example: .. code-block:: ini - export METPLOTPY_BASE=/home/username/METplotpy + export METCALCPY_BASE=/home/username/METcalcpy .. code-block:: ini - setenv METPLOTPY_BASE=/home/username/METplotpy + setenv METCALCPY_BASE /home/username/METcalcpy For the ksh environment: @@ -723,7 +723,7 @@ For the csh environment: setenv METCALCPY_BASE /path/to/METcalcpy_source_code -Replace /path/to/METcalcpy_source_code to the directory path where the METcalcpy source code is saved, for +Replace /path/to/METcalcpy_source_code with the directory path where the METcalcpy source code is saved, for example: .. code-block:: ini @@ -796,7 +796,7 @@ To generate the seven plot types using the **tcmpr_defaults.yaml** and * TK_ERR_skill_mn.png -NOTE: Some of the titles are cut-off in some of the plots. The default title_size can be overridden by adding the +NOTE: Some of the titles are cut off in some of the plots. The default title_size can be overridden by adding the title_size setting to the tcmpr_multi_plots.yaml file (anywhere in the file) and reducing it from the default value of 1.4: diff --git a/docs/Users_Guide/tcrmw_cross_section.rst b/docs/Users_Guide/tcrmw_cross_section.rst index 89e1edbf..aa1ef129 100644 --- a/docs/Users_Guide/tcrmw_cross_section.rst +++ b/docs/Users_Guide/tcrmw_cross_section.rst @@ -10,7 +10,7 @@ from the METcalcpy vertical interpolation module, *vertical_interpolation.py*: https://metplus.readthedocs.io/projects/metcalcpy/en/latest/Users_Guide/vertical_interpolation.html -**NOTE**:Data must have the following **required fields**: **temperature**, **relative humidity**, and **surface pressure**. These are required by the METcalcpy vertical_interpolation module to compute pressure indices. +**NOTE**: Data must have the following **required fields**: **temperature**, **relative humidity**, and **surface pressure**. These are required by the METcalcpy vertical_interpolation module to compute pressure indices. Example ======= @@ -55,7 +55,7 @@ file, the plot that will be created will be named example.png and example.pdf. There are configuration settings to set the labels to the x-axis and y-axis, the plot size, plot resolution, contour colors, etc. -To generate a cross-section plot for a different field, replace the 'TMP' with the any other +To generate a cross-section plot for a different field, replace the 'TMP' with any other available field name from the input file (*tc_rmw_example_vertical_interp.nc*). diff --git a/docs/Users_Guide/weather_regime.rst b/docs/Users_Guide/weather_regime.rst index 85c3ae76..a3e212af 100644 --- a/docs/Users_Guide/weather_regime.rst +++ b/docs/Users_Guide/weather_regime.rst @@ -6,7 +6,7 @@ Description =========== The **plot_weather_regime.py** script contains the plotting portion for -three scripts (**elbow.py, Calc_EOF.py**, and **K_means.py**) +three scripts (**elbow.py, Calc_EOF.py**, and **K_means.py**). These were originally created by Doug Miller at the University of Illinois. A `METplus use case `_ @@ -65,7 +65,7 @@ For plot_elbow -------------- In the code, generate the following as numpy -arrays (except K, pot_title, and output_plotname). +arrays (except K, plot_title, and output_plotname). **K:** A range beginning at 1 and ending with the number of clusters used in the weather regime analysis. @@ -143,7 +143,7 @@ Invoke the plotting functions: pwr.plot_K_means(kmeans,wrnum,lons,lats,perc,plot_outname,plevels) -The output will be **.png** version of the elbow line plot, eof contour map +The output will be a **.png** version of the elbow line plot, eof contour map plots, and weather regime map plots, if all three are requested. The output will be located based on what was specified (path and name) in the **output_plotname**. diff --git a/docs/Users_Guide/wind_rose.rst b/docs/Users_Guide/wind_rose.rst index fd769a1d..1d1a7320 100644 --- a/docs/Users_Guide/wind_rose.rst +++ b/docs/Users_Guide/wind_rose.rst @@ -11,7 +11,7 @@ time. The diagram consists of radiating spokes that represent the wind direction in terms of the cardinal wind directions of North, East, South, and West. Each spoke indicates how often the wind blows from each direction and -the color bands on each spoke represents the wind speed range (bins). +the color bands on each spoke represent the wind speed range (bins). The wind rose diagram is based on a polar coordinate system, with data plotted at a distance away from the origin at an angle that is relative to North. @@ -30,20 +30,18 @@ line type. The sample data used to create these plots is available in the METplotpy repository, where the wind rose diagram test scripts are located: -*$METPLOTPY_BASE/test/wind rose_diagram/point_stat_mpr.txt* - -*$METPLOTPY_BASE* is the directory where the METplotpy code is saved: +*$METPLOTPY_BASE/test/wind_rose/point_stat_mpr.txt* *$METPLOTPY_BASE* is the directory where the METplotpy code is saved: e.g. -*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository +*/usr/path/to/METplotpy* if the source code was cloned or forked from the GitHub repository or */usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of -the Github repository. The *x.y.z* is the release number. +the GitHub repository. The *x.y.z* is the release number. @@ -55,10 +53,10 @@ input data is located and to set plot attributes. These plot attributes correspond to values that can be set via the METviewer tool. YAML is a recursive acronym for "YAML Ain't Markup Language" and according to `yaml.org `_, -it is a "human-friendly data serialization language. It is commonly used for +it is a "human-friendly data serialization language". It is commonly used for configuration files and in applications where data is being stored or transmitted. Two configuration files are required. The first is a -default configuration file, **wind_rose_diagram_defaults.yaml**, +default configuration file, **wind_rose_defaults.yaml**, which is found in the *$METPLOTPY_BASE/metplotpy/plots/config* directory. *$METPLOTPY_BASE* indicates the directory where the METplotpy @@ -86,7 +84,7 @@ configuration file, which serves as a starting point for creating a wind rose diagram plot. **NOTE**: This default configuration file is automatically loaded by -**wind_rose_diagram.py.** +**wind_rose.py**. .. literalinclude:: ../../metplotpy/plots/config/wind_rose_defaults.yaml @@ -112,7 +110,7 @@ code was saved to the working directory: cp $METPLOTPY_BASE/test/wind_rose/wind_rose_custom.yaml $WORKING_DIR/wind_rose_custom.yaml -Notice that this has many of the same settings found in the the wind_rose_default.yaml file. We will simply change +Notice that this has many of the same settings found in the wind_rose_defaults.yaml file. We will simply change the title of the custom plot to customize the plot. **NOTE**: You do not need to include all the configuration settings in your custom configuration file. You only need to include the settings you wish to override. @@ -160,7 +158,7 @@ Uncomment or add (if it doesn't exist) the *points_path* setting: *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the same directory where the +Replace the */dir_to_save_points1_file* with the same directory where the **.points1** file is saved. If *points_path* is commented out (indicated by a '#' symbol in front of it), remove the '#' symbol to uncomment @@ -172,7 +170,7 @@ file unless saving the intermediate **.points1** file is desired. To save the log output to a file, uncomment the *log_filename* entry and specify the path and name of the log file. Select a directory with the appropriate read and write -privileges. To modify the verbosity of logging than what is set in the default config +privileges. To modify the verbosity of logging from what is set in the default config file, uncomment the *log_level* entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity). @@ -183,7 +181,7 @@ Using Defaults To use the *default* settings defined in the **wind_rose_defaults.yaml** file, specify a minimal custom configuration file -(**minimal_wind_rose_defaults.yaml**), which consists of only +(**minimal_wind_rose.yaml**), which consists of only a comment block, but it can be any empty file (write permissions for the output filename path corresponding to the *plot_filename* setting in the default configuration file will be needed. Otherwise, specify @@ -194,7 +192,7 @@ a *plot_filename* in the **minimal_wind_rose.yaml** file): Copy this file to the working directory: .. code-block:: ini - + cp $METPLOTPY_BASE/test/wind_rose/minimal_wind_rose.yaml $WORKING_DIR/minimal_wind_rose.yaml Add the *stat_input* (input data) and *plot_filename* @@ -215,7 +213,7 @@ files are located. Set the *stat_input* to the custom configuration files are being saved. **NOTE**: The *plot_filename* (output directory) may be specified to a directory other than the *$WORKING_DIR/output_plots*, as long as -it is an existing directory where the author has read and write permissions. +it is an existing directory where the user has read and write permissions. To save the intermediate **.points1** file (used by METviewer and useful for debugging), add the following lines to the @@ -226,20 +224,20 @@ for debugging), add the following lines to the *points_path: '/dir_to_save_points1_file'* -Replace the */dir_to_save_points1_file* to the same directory where +Replace the */dir_to_save_points1_file* with the same directory where the **.points** file is saved. Make sure that this directory exists and has the appropriate read and write permissions. Run from the Command Line ========================= -To generate a default performance diagram (i.e. using settings in the +To generate a default wind rose diagram (i.e. using settings in the **wind_rose_defaults.yaml** configuration file), perform the following: * If using the conda environment, verify the conda environment - is running and has has the required Python packages outlined in the + is running and has the required Python packages outlined in the `requirements section `_. @@ -249,13 +247,13 @@ perform the following: For the ksh environment: .. code-block:: ini - + export METPLOTPY_BASE=$METPLOTPY_BASE For the csh environment: .. code-block:: ini - + setenv METPLOTPY_BASE $METPLOTPY_BASE Replacing the $METPLOTPY_BASE with the directory where the @@ -277,12 +275,12 @@ perform the following: command using the **wind_rose_custom.yaml** file: .. code-block:: ini - + python $METPLOTPY_BASE/metplotpy/plots/wind_rose/wind_rose.py $WORKING_DIR/wind_rose_custom.yaml .. image:: figure/wind_rose_custom.png * A **wind_rose_custom.png** output file will be created in the directory that was specified in the *plot_filename* config setting - in the **custom_performance_diagram.yaml** config file. The title will match what you set in the - *title* setting of your custom_performance_diagram.yaml file. + in the **wind_rose_custom.yaml** config file. The title will match what you set in the + *title* setting of your wind_rose_custom.yaml file. diff --git a/docs/conf.py b/docs/conf.py index f01bea26..c61bb552 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -106,16 +106,8 @@ linkcheck_workers = 8 linkcheck_ignore = [ - # add regex patterns for URLs that should be skipped, e.g.: - # r'https://dtcenter\.org/.*', # if this site blocks automated requests - # r'https://matplotlib\.org/.*', # occasionally rate-limits automated clients - # r'https://scitools\.org\.uk/cartopy/.*', # occasionally slow - r'https://doi\.org/.*', # DOI redirectors often 403 non-browser requests - # bmcnoldy.rsmas.miami.edu sends an incomplete SSL certificate chain - # (missing intermediate cert). Browsers work around this via AIA - # fetching; curl/Python do not. Confirmed 2026-07 via curl -v - # ("SSL certificate problem: unable to get local issuer certificate"). - # Re-check periodically and remove once fixed server-side. + # incomplete TLS certificate chain that browsers tolerate but Python does not, + # and often unreachable; check by hand r'https://bmcnoldy\.rsmas\.miami\.edu/.*', ] diff --git a/docs/index.rst b/docs/index.rst index 87641ca9..cd901489 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,7 +22,7 @@ whose verification libraries formed the basis of MET and whose mathematical brilliance, passion for maps, grid projections, and graphics enriched and inspired new capabilities. -To `Venita Hagerty `_, +To **Venita Hagerty**, for her pivotal expertise, support, and attention to detail that ensured the success of METdataio and METexpress. @@ -42,7 +42,7 @@ and analysis tools to provide the same primary functionality as the EMC VSDB system, and also included a spatial verification package called MODE. Over the years, MET and VSDB packages grew in complexity. Verification -capability at other NOAA laboratories, such as ESRL, were also under heavy +capability at other NOAA laboratories, such as ESRL, was also under heavy development. An effort to unify verification capability was first started under the HIWPP project and led by NOAA ESRL. In 2015, the NGGPS Program Office started working groups to focus on several aspects of the @@ -83,15 +83,15 @@ follows: components of METplus tools for statistical aggregation, event equalization, and other analysis needs * **METplotpy** - suite of Python-based scripts to plot MET output, - and in come cases provide additional post-processing of output prior + and in some cases provide additional post-processing of output prior to plotting -* **METdatadb** - database to store MET output and to be used by both +* **METdataio** - database to store MET output and to be used by both METviewer and METexpress The umbrella repository will be brought together by using a software package called `manage_externals `_ developed by the Community Earth System Modeling (CESM) team, hosted at NCAR -and NOAA Earth System's Research Laboratory. The manage_externals package +and NOAA Earth System Research Laboratory. The manage_externals package was developed because CESM is comprised of a number of different components that are developed and managed independently. Each component also may have additional "external" dependencies that need to be maintained independently. @@ -107,10 +107,10 @@ Acronyms * **VSDB** - Verification Statistics Data Base * **MODE** - Method for Object-Based Diagnostic Evaluation * **UFS** - Unified Forecast System -* **SIMA** -System for Integrated Modeling of the Atmosphere -* **ESRL** - Earth Systems Research Laboratory -* **HIWPP** - High Impact Weather Predication Project -* **NGGPS** - Next Generation Global Predicatio System +* **SIMA** - System for Integrated Modeling of the Atmosphere +* **ESRL** - Earth System Research Laboratory +* **HIWPP** - High Impact Weather Prediction Project +* **NGGPS** - Next Generation Global Prediction System * **GSD** - Global Systems Division Authors diff --git a/docs/requirements.txt b/docs/requirements.txt index 5f87dce1..742c23d2 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ -sphinx-gallery==0.14.0 +sphinx-gallery==0.19.0 sphinxcontrib-bibtex==2.6.1 -sphinx==5.3.0 -sphinx-design==0.3.0 -sphinx_rtd_theme==1.3.0 +sphinx==8.2.3 +sphinx-design==0.6.1 +sphinx-rtd-theme==3.0.1