Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Feature 2628 documentation updates #2817

Open
wants to merge 49 commits into
base: develop
Choose a base branch
from
Open

Feature 2628 documentation updates #2817

wants to merge 49 commits into from

Conversation

CPKalb
Copy link
Contributor

@CPKalb CPKalb commented Dec 9, 2024 •
edited
Loading

Pull Request Testing

  • Describe testing already performed for these changes:

    Tested that the documentation builds successfully and also read the documentation to check that they

  • Recommend testing for the reviewer(s) to perform, including the location of input datasets, and any additional instructions:

    Read the documentation for the use cases that were updated and check that they use the new format and also check to see if there are typos or text that does not make sense. The use cases that were updated are:

s2s_mid_lat:
UserScript_fcstGFS_obsERA_Blocking
UserScript_obsERA_obsOnly_Blocking
UserScript_fcstGFS_obsERA_WeatherRegime
UserScript_obsERA_obsOnly_WeatherRegime

s2s_mjo:
UserScript_fcstGFS_obsERA_OMI
UserScript_obsERA_obsOnly_OMI
UserScript_obsERA_obsOnly_RMM
UserScript_obsERA_obsOnly_PhaseDiagram

s2s_stratosphere:
UserScript_fcstGFS_obsERA_StratosphereBias
UserScript_fcstGFS_obsERA_StratospherePolar
UserScript_fcstGFS_obsERA_StratosphereQBO

Link to the updated documentation: https://metplus.readthedocs.io/en/feature_2628_documentation_updates/generated/model_applications/index.html#subseasonal-to-seasonal-mid-latitude

  • Do these changes include sufficient documentation updates, ensuring that no errors or warnings exist in the build of the documentation? [Yes or No]
    Yes

  • Do these changes include sufficient testing updates? [Yes or No]
    ??

  • Will this PR result in changes to the test suite? [Yes or No]

    If yes, describe the new output and/or changes to the existing output:

    No

  • Do these changes introduce new SonarQube findings? [Yes or No]

    If yes, please describe:
    No

  • Please complete this pull request review by [Fill in date].

Pull Request Checklist

See the METplus Workflow for details.

  • Add any new Python packages to the METplus Components Python Requirements table.
  • For any new datasets, an entry to the METplus Verification Datasets Guide.
  • Review the source issue metadata (required labels, projects, and milestone).
  • Complete the PR definition above.
  • Ensure the PR title matches the feature or bugfix branch name.
  • Define the PR metadata, as permissions allow.
    Select: Reviewer(s) and Development issue
    Select: Milestone as the version that will include these changes
    Select: Coordinated METplus-X.Y Support project for bugfix releases or METplus-Wrappers-X.Y.Z Development project for official releases
  • After submitting the PR, select the ⚙️ icon in the Development section of the right hand sidebar. Search for the issue that this PR will close and select it, if it is not already selected.
  • After the PR is approved, merge your changes. If permissions do not allow this, request that the reviewer do the merge.
  • Close the linked issue and delete your feature or bugfix branch from GitHub.

CPKalb added 30 commits July 3, 2024 15:30
@CPKalb
Updating Blocking GFS/ERA documentation
de96807
@CPKalb
Updating ERA/GFS blocking documentation for weird formatting
d6b2c18
@CPKalb
Updating formatting again
8c96164
@CPKalb
Separating line
c3a6554
@CPKalb
More formatting
e2d8006
@CPKalb
Updates to ERA blocking documentation
bcda8a6
@CPKalb
Updating error
7a66b37
@CPKalb
Fixing indent error
4fefd85
@CPKalb
Adding line break
9cbd7cf
@CPKalb
Text updates
a414cdf
@CPKalb
Updating list
52f4d0f
@CPKalb
Final updates to blocking documentation
2d120f6
@CPKalb
Updating some documentation
f641111
@CPKalb
Trying to fix error
277eeb1
@CPKalb
Testing errors
85d2a6e
@CPKalb
More testing
0201fab
@CPKalb
Fixing one file
5c74b08
@CPKalb
Trying to fix other file
fc8ef97
@CPKalb
more fixes
21367a2
@CPKalb
File testing
e63d9ed
@CPKalb
Testing
adec0ac
@CPKalb
Fixing typo
74e2c0e
@CPKalb
Updates
5488bd4
@CPKalb
Updating stratosphere documentation
95dcc39
@CPKalb
Testing updates
eeef9c7
@CPKalb
Updating indents
b25453f
@CPKalb
changing indent
f83f9c5
@CPKalb
Updating RMM
a38da1b
@CPKalb
Updating indent
92a87d0
@CPKalb
Edit typo
3e5cf22
jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
.../use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.py
# and then runs another UserScript, bias_plot_driver.py, to create the bias plots.
# This use case calls UserScript first, Series-Analysis, and then UserScript
# a second time. METcalcpy, METplotpy, and METdataio are needed for this use case to run.
# The metcalcpy scripts accessed include the following:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# The metcalcpy scripts accessed include the following:
# The METcalcpy scripts accessed include the following:

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
.../use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.py
# then it loads any configuration files passed to METplus via the command line
# with the -c option, i.e. -c parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.conf
# then it loads any configuration files passed to METplus via the command line,
# i.e. parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.conf.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# i.e. parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.conf.
# i.e. parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.conf

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
.../use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.py
# This use case uses a Python embedding script to read in the zonal mean data to Series-Analysis
# This use case uses a Python embedding script to read in the semi-structured zonal mean data to Series-Analysis. Inputs to
# this script include the filename to be read in, variable name, and the axis over which the mean is taken. The script
# returns a numpy array containing the zonal mean data (semi structured grid).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# returns a numpy array containing the zonal mean data (semi structured grid).
# returns a numpy array containing the zonal mean data (semi-structured grid).

"semi-structured" was previously hyphenated. Add a hyphen for consistency.

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
.../use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.py
# METcalcpy. It writes the zonal mean data to output netCDF files.
#
# The bias plot driver reads output netCDF files from Series-Analysis and creates plots of the bias over
# latitude and pressure level. Inputs to both of the python scripts can be found in the [user_env_vars]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# latitude and pressure level. Inputs to both of the python scripts can be found in the [user_env_vars]
# latitude and pressure level. Inputs to both of the Python scripts can be found in the [user_env_vars]

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
...use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py
@@ -1,54 +1,94 @@
"""
Bias Plot on Polar Cap Temperature and Polar Vortex U: UserScript, Stat-Analysis
================================================================================
UserScript and StatAnalysis: Compute Polar Cap Temperature and Polar Vortex U and create Plots
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
UserScript and StatAnalysis: Compute Polar Cap Temperature and Polar Vortex U and create Plots
UserScript and StatAnalysis: Compute Polar Cap Temperature and Polar Vortex U and Create Plots

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
...use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py
Bias Plot on Polar Cap Temperature and Polar Vortex U: UserScript, Stat-Analysis
================================================================================
UserScript and StatAnalysis: Compute Polar Cap Temperature and Polar Vortex U and create Plots
==============================================================================================

model_applications/
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
model_applications/
model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py

The template has the full path on one line.

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
...use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py
Bias Plot on Polar Cap Temperature and Polar Vortex U: UserScript, Stat-Analysis
================================================================================
UserScript and StatAnalysis: Compute Polar Cap Temperature and Polar Vortex U and create Plots
==============================================================================================

model_applications/
s2s_stratosphere/
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
s2s_stratosphere/

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
...use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py
Bias Plot on Polar Cap Temperature and Polar Vortex U: UserScript, Stat-Analysis
================================================================================
UserScript and StatAnalysis: Compute Polar Cap Temperature and Polar Vortex U and create Plots
==============================================================================================

model_applications/
s2s_stratosphere/
UserScript_fcstGFS_obsERA_StratospherePolar.py
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
UserScript_fcstGFS_obsERA_StratospherePolar.py

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
...use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py
##############################################################################
# Scientific Objective
# --------------------
#
# Many common modes of variability in the troposphere have stratospheric teloconnection
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# Many common modes of variability in the troposphere have stratospheric teloconnection
# Many common modes of variability in the troposphere have stratospheric teleconnection

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
...use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py
# bias_rmse_plot_driver.py, to create the plots.
# This use case runs UserScript twice and Stat-Analysis once. The UserScripts compute
# polar cap temperature and polar vortex wind and create plots. METcalcpy, METplotpy,
# and METdataio are needed for this use case. The metcalcpy scripts accessed include
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# and METdataio are needed for this use case. The metcalcpy scripts accessed include
# and METdataio are needed for this use case. The METcalcpy scripts accessed include

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
...use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py
#
# .. literalinclude:: ../../../../parm/met_config/STATAnalysisConfig_wrapped

##############################################################################
# Python Embedding
# ----------------
#
# This use case does not use python embedding
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# This use case does not use python embedding
# This use case does not use python embedding.

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
...use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py
#
# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.conf -c /path/to/user_system.conf
# There are two python scripts in the is use case. The first, polar_t_u_driver.py reads in netCDF files for the
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# There are two python scripts in the is use case. The first, polar_t_u_driver.py reads in netCDF files for the
# There are two Python scripts in the is use case. The first, polar_t_u_driver.py reads in netCDF files for the

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
...use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py
#
# 2) Modifying the configurations in parm/metplus_config, then passing in UserScript_fcstGFS_obsERA_StratospherePolar.conf:
# The second python script, bias_rmse_plot_driver reads in the output of Stat-Analysis and creates plots of bias
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# The second python script, bias_rmse_plot_driver reads in the output of Stat-Analysis and creates plots of bias
# The second python script, bias_rmse_plot_driver.py reads in the output of Stat-Analysis and creates plots of bias

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py
@@ -1,13 +1,19 @@
"""
QBO Phase plots and QBO Index: UserScript, Stat-Analysis
================================================================================
UserScript and StatAnalysis: Compute QBO Phase plots and QBO Index
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
UserScript and StatAnalysis: Compute QBO Phase plots and QBO Index
UserScript and StatAnalysis: Compute QBO Phase Plots and QBO Index

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py
QBO Phase plots and QBO Index: UserScript, Stat-Analysis
================================================================================
UserScript and StatAnalysis: Compute QBO Phase plots and QBO Index
==================================================================

model_applications/
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
model_applications/
model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py

The template has the full path on one line.

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py
QBO Phase plots and QBO Index: UserScript, Stat-Analysis
================================================================================
UserScript and StatAnalysis: Compute QBO Phase plots and QBO Index
==================================================================

model_applications/
s2s_stratosphere/
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
s2s_stratosphere/

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py
QBO Phase plots and QBO Index: UserScript, Stat-Analysis
================================================================================
UserScript and StatAnalysis: Compute QBO Phase plots and QBO Index
==================================================================

model_applications/
s2s_stratosphere/
UserScript_fcstGFS_obsERA_StratosphereQBO.py
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
UserScript_fcstGFS_obsERA_StratosphereQBO.py

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py
# in METcalcpy, METplotpy, and METdataio. For it to run, the following versions of those
# repositories are needed, METcalcpy 3.0.0, METplotpy 3.0.0, and METdataio 2.1.
# This use case calls UserScript once and StatAnalysis once. Additionally, METcalcpy,
# METplotpy, and METdataio are required to run. The metcalcpy scripts accessed include
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# METplotpy, and METdataio are required to run. The metcalcpy scripts accessed include
# METplotpy, and METdataio are required to run. The METcalcpy scripts accessed include

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py
# User Scripting
# --------------
#
# This use case runs the stratosphere_qbo_driver.py python script, which first
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# This use case runs the stratosphere_qbo_driver.py python script, which first
# This use case runs the stratosphere_qbo_driver.py Python script, which first

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py
# computes zonal and meridional means using directional_means.py in METcalcpy on U from
# -10 S to 10N latitude. Then, an EOF analysis is performed on this zonal and meridional
# mean data, and two phase diagrams of QBO are created using the plot_qbo_phase_circuits and
# plot_qbo_phase_space functions from stratosphere_plots.py in METplotpy. Additionally the
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# plot_qbo_phase_space functions from stratosphere_plots.py in METplotpy. Additionally the
# plot_qbo_phase_space functions from stratosphere_plots.py in METplotpy. Additionally, the

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py
# plot_qbo_phase_space functions from stratosphere_plots.py in METplotpy. Additionally the
# zonal and meridional mean at 30 and 50mb are output as time series in MET's matched pair
# (MPR) format using write_mpr.py in METcalcpy. They are also plotted as timeseries using the
# plot_u_timeseries function from stratosphere_plots.py in METplotpy. Finally StatAnalysis is
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# plot_u_timeseries function from stratosphere_plots.py in METplotpy. Finally StatAnalysis is
# plot_u_timeseries function from stratosphere_plots.py in METplotpy. Finally, StatAnalysis is

jprestop
jprestop reviewed Dec 10, 2024
View reviewed changes
docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py
@@ -127,22 +176,25 @@
#
# INFO: METplus has successfully finished running.
#
# There should be 4 graphics output to the plot directory in the location set as OUTPUT_DIR
# in the [user_env_vars] section of the configuration file:
# # Refer to the value set for **OUTPUT_BASE** to find where the output data was generated.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# # Refer to the value set for **OUTPUT_BASE** to find where the output data was generated.
# Refer to the value set for **OUTPUT_BASE** to find where the output data was generated.

jprestop
jprestop requested changes Dec 10, 2024
View reviewed changes
Copy link
Collaborator

@jprestop jprestop left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

HI @CPKalb. Thank you for all of your work on these. I think the content looks detailed and fantastic! I really appreciate all of your effort. I made some minor grammatical/spelling suggestions. Let me know once those are in order, and I'll re-review and approve.

@jprestop
Copy link
Collaborator

HI @CPKalb. I see that at least one of the tests is failing (9 in progress checks at this time):

Summary:


ERROR: Some differences were found
file not found (in truth but missing now)
A:/data/truth/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking/plots/FV3_ERA_IBL_Freq_DJF.png
B:

file not found (in truth but missing now)
A:/data/truth/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking/plots/FV3_ERA_IBL_Freq_DJF.pdf
B:

file not found (new output)
A:
B:/data/output/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking/plots/GFS_ERA_IBL_Freq_DJF.pdf

file not found (new output)
A:
B:/data/output/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking/plots/GFS_ERA_IBL_Freq_DJF.png

Finished comparing directories

Does anything need to be done to resolve this error? I see it's due to the renaming, but I am not sure exactly how this testing works and if files should be updated somewhere. I am hoping you'll know.

@CPKalb
Copy link
Contributor Author

CPKalb commented Dec 10, 2024 •
edited
Loading

Weird.... I don't think I changed the name of these in this branch since it should have just been documentation updates. However, the new names are the correct ones. So, maybe this update was missed somewhere along the way. I know there is a way to update the truth data but I can't remember how to do it. @georgemccabe, how do we update truth data?

Tina

@jprestop
Copy link
Collaborator

@CPKalb Hopefully this is the section of the Contributor's Guide that you need for updating truth data: https://metplus.readthedocs.io/en/develop/Contributors_Guide/continuous_integration.html#update-truth-data-update-truth-yml

@georgemccabe
Copy link
Collaborator

@CPKalb, it looks like the IBL_PLOT_OUTPUT_NAME was changed in the conf file for this PR, which I'm guessing is the cause of the name change. After you merge this PR, you can follow the instructions from the page that @jprestop provided to update the truth data. Let me know if you have any questions or run into any issues.

@CPKalb
Copy link
Contributor Author

CPKalb commented Dec 11, 2024

@georgemccabe, thanks. I must be crazy. I'm guessing I saw it was incorrectly named and changed it and then forgot I did that.. I'll follow those instructions after the pr to update the truth.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jprestop jprestop jprestop requested changes

Requested changes must be addressed to merge this pull request.

Assignees
No one assigned
Labels
component: documentation Documentation issue requestor: Navy/NRL Naval Research Laboratory
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Update Scientific Objective Documentation for some S2S Use Cases
3 participants
@CPKalb @jprestop @georgemccabe