[develop]: Add Tutorial Chapter for the SRW App #556
Conversation
This reverts commit b839658.
…-app into text/tutorial
gspetro-NOAA
requested review from
willmayfield,
dmwright526,
natalie-perlin,
EdwardSnyder-NOAA and
MichaelLueken
as code owners
There was a problem hiding this comment.
@gspetro-NOAA Excellent work on the new tutorials! I'm excited to see the rest of the tutorial cases added to the new Tutorials chapter. I saw no issues with spelling, grammar, or the content of the documentation, so I will go ahead and approve these changes.
|
The necessary approvals for this PR have been given. I would like to give others the opportunity to review this work before it is merged. So, please look these changes over before the close of business today and I will merge this work tomorrow morning. Thanks! |
| task_run_post: | ||
| WTIME_RUN_POST: 00:20:00 | ||
|
|
||
| Lastly, users must set the ``COMOUT_REF`` variable in the ``task_plot_allvars:`` section to create difference plots that compare output from the two experiments. ``COMOUT_REF`` is a template variable, so it references other workflow variables within it (see :numref:`Section %s <TemplateVars>` for details on template variables). ``COMOUT_REF`` should provide the path to the ``control`` experiment forecast output using single quotes as shown below: |
There was a problem hiding this comment.
I searched the current documentation for what COMOUT is short for or what meaning it's trying to convey ("common output directory"? If so, what's "common" about it?) but didn't see anything. In the past, I've tried to find this out from operations people at EMC but failed. Have you been able to find out? It would be great to have this (and other NCO variables) documented so users can form a better mental image of the NCO directory structure and the logic behind it. Just last week I was talking to a user and they told me it was very confusing -- not just this variable but other operational ones like NET -- because their nomenclature/purpose is not explained well (and he was an experienced modeler but not from the operations side).
There was a problem hiding this comment.
Unfortunately, I haven't been able to find out... About the best I've got is a reference to the NCO Implementation Standards in the ConfigWorkflow chapter where we define all the relevant NCO-specific variables (https://srw-ug.readthedocs.io/en/text-tutorial/ConfigWorkflow.html#nco-specific-variables). I just added the same reference where I talk about COMOUT_REF in case users come across that first. I agree that it would be useful to know/explain more, but it seems like we've both hit a bit of a brick wall on this one... Part of me wonders if the issue is that the logic behind the naming is lost to the annals of history (i.e., operations folks just use it without necessarily knowing/wondering where the names came from originally). Will update if I find anything more though!
There was a problem hiding this comment.
@gspetro-NOAA Yeah I think you're right about it being lost to the annals of history. In the plot_all_vars task, it seems like we can rename this variable to something more straightforward like POST_OUTPUT_DIR because as far as I can tell, this task isn't something that EMC/NCO runs and so doesn't require NCO-compliant names like COMOUT_.... Would that require a separate PR?
There was a problem hiding this comment.
@gsketefian I think it would be a separate PR, although I like the suggestion. That said, I believe the name was selected by @danielabdi-noaa, and he may have had reasons for selecting that name.
|
@gspetro-NOAA Please let me know if you are okay with this PR as is, or if you would like some time to apply additional changes from @gsketefian before merging this work into develop. Thanks! |
|
@MichaelLueken I think I'm good with the PR as is. I've addressed most of @gsketefian 's comments, and I think the one remaining would be best in a separate PR. |
|
This commit has quadrupled the size of the repository (from 12MB to 56MB) with the addition of several large .gif files. While probably not enough of a concern to consider a history re-write, we should be more careful with what files we allow into the repository in the future. |
Oh dear! Didn't realize the .gifs would have such a dramatic effect. Did you run into a problem because of it? Regardless, I will see if I can reduce the size of the .gifs (e.g., by including fewer frames). Sorry! |
|
Changing the files will only increase the size of the repository further due to how git history is stored. I think it's best to discuss the best way forward at the next Thursday meeting. |
|
And for the record, no this hasn't caused any problems yet. Sorry if my wording was a bit terse: I don't expect everyone to know the nuances of git and we haven't explicitly covered this in our contributor's guide or other guidelines. This is a problem that many repositories have fallen into over the years, and I just wanted to bring it up as an issue ASAP so it can potentially be nipped in the bud. |
This PR adds a Tutorial chapter to the SRW App (and several plotting/png files, which makes this PR look much bigger than it is!). The Tutorial chapter outlines 5 severe weather cases. A complete tutorial is available for the first case. The hope is to fill out the others with each new SRW App release. To supplement the tutorial, a document on SSH access and data transfer was added to help users download plots from an HPC/cloud system to their local device. Additionally, a few Glossary updates were needed for the tutorial, as well as minor corrections to the plotting/TemplateVars explanations. 2023-02-02 NOTE: This commit has been re-written to remove binary image files from the repository. --------- Co-authored-by: gspetro <[email protected]>
This PR adds a Tutorial chapter to the SRW App (and several plotting/png files, which makes this PR look much bigger than it is!). The Tutorial chapter outlines 5 severe weather cases. A complete tutorial is available for the first case. The hope is to fill out the others with each new SRW App release. To supplement the tutorial, a document on SSH access and data transfer was added to help users download plots from an HPC/cloud system to their local device. Additionally, a few Glossary updates were needed for the tutorial, as well as minor corrections to the plotting/TemplateVars explanations. --------- Co-authored-by: gspetro <[email protected]>
DESCRIPTION OF CHANGES:
This PR adds a Tutorial chapter to the SRW App (and several plotting/png files, which makes this PR look much bigger than it is!). The Tutorial chapter outlines 5 severe weather cases. A complete tutorial is available for the first case. The hope is to fill out the others with each new SRW App release. To supplement the tutorial, a document on SSH access and data transfer was added to help users download plots from an HPC/cloud system to their local device. Additionally, a few Glossary updates were needed for the tutorial, as well as minor corrections to the plotting/TemplateVars explanations.
I am particularly interested in having someone with subject matter expertise review the section of the tutorial comparing plots. I think with some expert advice, the descriptions could be refined/improved. I'm hoping there aren't any errors, but it would be important to catch those, too!
Type of change
TESTS CONDUCTED:
None required. I ran through my own instructions on Jet and NOAA Cloud (AWS). I also viewed the RTD version in my fork: https://srw-ug.readthedocs.io/en/text-tutorial/Tutorial.html
DEPENDENCIES:
PR #560
Some functionality is dependent on resolution of Issue #551 (addition of data to the standardized locations).
DOCUMENTATION:
All documentation.
ISSUE:
Resolves Issue #550.
Suggest closing Issue #551 before merging.
CHECKLIST
CONTRIBUTORS (optional):
@EdwardSnyder-NOAA