Identify errors, typos in METplus v3.0 documentation

[bikegeek]

Replace italics below with details for this issue.

Describe the Task

Identify any errors, typos, content that needs editing in the METplus v3.0 User's documentation

Time Estimate

Estimate the amount of work required here.
Issues should represent approximately 1 to 3 days of work.

Sub-Issues

Consider breaking the task down into sub-issues.

• should we add env instructions for ksh in addition to bash and csh???
• Wrappers configurations file need to update the README in the code to account for the
  addition of the logging config file
• put a note/warning that on some systems, may need to replace the // with # for
  comments in the config file whenever you observe parsing error message that
  corresponds to the lines where the comments reside.
• Search all METplus .conf files in the repo and replace '//' comments with '#' and fix docs in METplus User's Guide 2.1 section 2.9.
• bottom of page 21 in e.g. box for csh instructions for set path, missing }???
• In METplus/parm/README file references either 2 or 3 directories... but that count is not accurate. When possible, remove specific number to avoid having to keep them accurate.
• Rob Darvell alerted use that he also gets mpi warnings from the produtil code. Would be great in the refactor of produtil (2 to 3) to get rid of these warnings!
• Master_metplus.py still has ToDo’s that should be removed and become GitHub issues
• Remove the point stat documentation odt and pdf from the repository
• pg 57 Chapter 4 Refer to MET user’s manual chapter x for a description of the grib_level, and other “extras”
• pg 60 provide more explanation for the fifth file in the example
• Change the A-Z glossary to Appendix

Relevant Deadlines

List relevant project deadlines here or state NONE.

Funding Source

Define the source of funding and account keys here or state NONE.

Define the Metadata

Assignee

• Select engineer(s) or no engineer required
• Select scientist(s) or no scientist required

Labels

• Select component(s)
• Select priority
• Select requestor(s)

Projects and Milestone

• Review projects and select relevant Repository and Organization ones
• Select milestone

Define Related Issue(s)

Consider the impact to the other METplus components.

• METplus, [MET]

Task Checklist

See the METplus Workflow for details.

• Complete the issue definition above.
• Fork this repository or create a branch of develop.
  Branch name: feature_<Issue Number>_<Description>
• Complete the task and verify your changes.
• Add/update unit tests.
• Add/update documentation.
• Push local changes to GitHub.
• Submit a pull request to merge into develop.
  Pull request: feature <Issue Number> <Description>
• Iterate until the reviewer(s) accept and merge your changes.
• Delete your fork or branch.
• Close this issue.

[bikegeek]

https://ncar.github.io/METplus/Users_Guide/met_tool_wrapper/PointStat/PointStat.html#sphx-glr-users-guide-met-tool-wrapper-pointstat-pointstat-py

Section 5.1.11.1 Point Stat example:
The Scientific Objective talks about a rainfall example, whereas when you examine the datasets and subsequent info this appears to be a wind/temperature example. In addition there is a typo on prepBUFR (observation dataset line, spelt prepBURF on page)

[robdarvell]

Attempt to include my first comment (there will be a few!): Hope all goes well.
Have been through the METplus document (Users Guide part of it) now to make sure all of the examples work on the version which I downloaded with the MET9 version I created on our system.
Didn't run any of the GEMPak examples (not deemed relevant at this point in time)

Some of them may appear a little annoying (small typos). Apologies for those ones.

[robdarvell]

Section 2.5.1:
In the 'Model Applications' list there are now more than the 4 listed example tar files. Should the others get included in order to be able to run all of the examples?

[robdarvell]

Section 2.6:
Towards the bottom it talks about a /src directory. I couldn't find this. Have I missed something?

[robdarvell]

Section 2.11:
In the first text box for 'Example 1' there is a typo at :
"# Otherwise -et ..." (missing s in set?)

[robdarvell]

Section 3.3.1.2:
Format for the VALID_END variable appears different to all others. Others have description starting alongside variable name whereas this variable starts a new section

[robdarvell]

Section 3.3.1.4:
Starting from "If LOOP_BY = INIT" the date of 2019-02-01 is incorrectly written

Also in the INIT_SEQ part:
I am a little confused with how what is written in the first text box then relates to the forecast range list in the words which follow (going as far as 30 etc). Is this relating to something else written above?

[robdarvell]

Section 3.3.4.5:
Typo on following (folloing)

[robdarvell]

Section 3.3.4.4:
The last couple of text boxes with the example text in them. I understand that the obs for P750 would come from the (1,,), but I can't see why both of the fcst rows calls [ level="P500" ]. Is it a case you always need to refer to the first element, and then it will find the second element from the ob reference? Perhaps a little more explanation?

[robdarvell]

Section 3.3.5.5
Is there a bit of text missing to aid users who read this example? In order for the time window given in the example to work with the observation files it suggests that it isn't an exact 7200-7200 window which gets used, it appears to be -7200->7199 or >=-7200 and <7200. First times I have read through it it seems a little confusing without that extra info (unless I have mis-interpreted it).

[robdarvell]

Section 3.4:
Use case example 1: Is there a format issue after the '-set MET_INSTALL_DIR' row ? (with how the 'where' and subsequent row appear)

[robdarvell]

Section 3.4: Track and Intensity use case
2(g) : The METplus_Data part of the directory path doesn't appear to exist when you unzip the tarball?
3(b): Last row, should this also be metplus_config ?
3(d): Extra METplus appeared in the path (before parm) ?
3(d) - 1(b): Following comment from 2(g) above not sure path is correct (METplus_Data part)
4(a(2)): Is there an = missing on the export row ?

[robdarvell]

Section 5.1.2.1:
In the 'Running METplus' section it talks about a user_data.conf file, but it doesn't seem to introduce this file anywhere that I could spot (and don't think it was required when I ran it)
In the 'Expected Output' section, the output seems to go into a 'cyclone' directory rather than a 'tc_pairs' directory

[robdarvell]

Section 5.1.6.1:
In the 'Running METplus' section - In point 2 there is a typo on forecast
In the 'Expected Output' section - Output for the use_case isn't grid_stat/2005080700 relative to OUTPUT_BASE it is met_tool_wrapper/GridStat/GridStat_multiple_config/2005080700. In addition the filenames which you find are different (WRF rather than QPF and MC_PCP rather than QPE)

[robdarvell]

Section 5.1.6.2:
Firstly, was thinking whether or not a 'Basic' use_case should come before the more complicated example?
In the 'Expected Output' section the link to the output in relation to the OUTPUT_BASE is incorrect (it seems to go to met_tool_wrapper/GridStat/GridStat/2005080700). Also as with Section 5.1.6.1 the filenames of the output contain WRF rather than QPF and MC_PCP rather than QPE.

[robdarvell]

Section 5.1.8.2:
Similar question as to section 5.1.6.2 above as to whether this 'Basic' case should be the first one in the section, building up to the other examples?

[robdarvell]

Section 5.1.15.1:
In the 'Running METplus' section the text box to run the script just contains /path/to/StatAnalysis.conf whereas other sections include things like /path/to/METplus/parm... Is this in error?

[robdarvell]

Section 5.1.16.1:
In the 'Expected Output' section, the path to the output in relation to OUTPUT_BASE doesn't look right. I think grid_stat/2005080700 needs to be replaced by tcmpr_plots/

[robdarvell]

Section 5.1.17.1:
In the 'Running METplus' section, in the text box, the format for where to find TCPairs_tropical.conf isn''t the same as in other sections.
Also in the 'Expected Output' section, the idea of where to find the output doesn't follow the same pattern as with other sections.

[robdarvell]

General comment in the 'Datasets' section. It refers to the 'Running METplus' section. Is it missing the word 'Wrappers'? (Section 2.11)

[robdarvell]

Section 5.1.18.1:
In the 'METplus Workflow' section, what does the TCST represent (and is the * supposed to represent something?)
Underneath the MET configuration config file text box there isn't the same level of description of variable names as in other examples?
In the 'Expected Output' section there is output referencing to tc_pairs and then later tc_stat. I think the tc_pairs reference is incorrect?
In the output file tc_stat_summary.tcst the formatting goes a little astray at times. Is this simply down to the browser I am using?
tc_stat_output.txt

[robdarvell]

Section 5.2.1.1:
In the 'External Dependencies' section there is a typo of tool (written too)

[robdarvell]

Section 5.5.1.2:
In the 'Datasets' section. Is the third bullet required? (Doesn't make sense in relation to the other two). Would it look better with 'data' adding at the end of the Observations bullet?
In the 'Expected Output' section, the pathname to the output is missing an Ensemble_Stat before the timestamp part.

[robdarvell]

Section 5.2.1.3:
In the 'Expected Output' section, the path to the output files is incorrect. It goes into a 'hailtest' directory from the OUTPUT_BASE.

[robdarvell]

Section 5.2.2.1:
In the 'Datasets' -> 'Observation Dataset', first bullet. I think the final operator is supposed to be a > rather than a < ?
In the 'Running METplus' section does it require the user_config file to be referenced as well (as seen in all the other examples)?
In the 'Expected Output' section, typo in the first text box, running rather than runing?
Should 'as and example' just be 'as an example'?
Is more information (as with other sections) required to set up where the output directory is found in relation to OUTPUT_BASE?

[robdarvell]

Section 5.2.3.1:
In the Scientific Objective section: Is there a typo with sumes rather than sums ?

[robdarvell]

Section 5.2.3.2:
Just before the 'Running METplus' section we shouldn't really have a TODO bit?

[robdarvell]

Section 5.2.3.3:
In the 'Scientific Description' section, typo of eatures which I think should be features?
In the 'Datasets' section, is the last bullet required?
In the 'Expected Output' section:
Path to the output should include series_analysis_lead in relation to OUTPUT_BASE
In the Day1 subdirectory list, the second file should be FCST_FILES_... rather than FCST_ASCII_FILES_... (ie no ASCII)
There is also data generated in a Day2 directory (document suggests not)?

[robdarvell]

Section 5.2.3.4:
In the 'Expected Output' section, path to the output in relation to OUTPUT_BASE not correct. Appears to contain uswrp/met_out ...

[robdarvell]

Section 5.2.3.5:
In the Datasets section, is the last bullet point required ?
In the 'METplus Workflow' section, is the last forecast range supposed to be 42 rather than 40?

[robdarvell]

Section 5.2.4.1:
In the Datasets section, is the last bullet point required ?
In the 'Expected Output' section it says the directory will contain the following files, but then there are no files listed?

[robdarvell]

Section 5.2.4.2:
In the Datasets section, is the last bullet point required ?

[robdarvell]

Section 5.2.4.3:
In the Datasets section, is the last bullet point required ?
In the 'Expected Output' section it says the directory will contain the following files, but then there are no files listed?

[robdarvell]

Section 5.2.4.4:
In the 'Expected Output' section, there is no grid_stat in the pathname as to where to find the output? Think it should be uswrp/met_out/{MODEL}/precip

[robdarvell]

Section 5.2.4.7:
In the Datasets section, is the last bullet point required ?

[robdarvell]

Section 5.2.7.2:
Don't know whether this was just me, but I could only get this example to work if the tc_pairs directory was empty to begin with (ie no other example output in it). If this is the case then it may be worth including that information for users somewhere?

[robdarvell]

Section 8:
Not going to entirely go through this. Some may well be how the documentation gets built. Some summary comments mind you. Maybe worth someone looking through it?

• CUSTOM_LOOP_LIST: Underneath the text box the first letter of the next couple of paragraphs are missing
• CUT: Space missing after Linux
• EXTRACT_TILES_DLAT: Maybe my understanding of the variable, but should it be similar to the corresponding DLON one, just one is latitude, and the other longitude. If it is then the sections could be similar.
• FCAST_IS_PROB: Space before Acceptable
• FHR_GROUP_BEG: Format of example used could be improved?
• LOG_LEVEL: Perhaps some , between options?
• MAKE_PLOTS_STATS_LIST: Are all the options available listed here, or is this just a selection?
• OBS_MTD_... section: Some 'Used by' missing ? ; Some 'Defaults' missing ?

So generally, formatting of some of the entries could be improved upon. Those mentioned above cover most of the different examples I have seen, but they don't cover all of the cases spotted.

[robdarvell]

OK, think that covers everything that I have written down in my notes. Not saying I haven't missed things.
Hope that it is of some use to you.

[j-opatz]

Copied over "open" issues from #238, which has largely been completed. Will continue to check for status of those first, close that issue when appropriate, then begin work on above comments.

[bikegeek]

Questions/Still some of Rob's comments not addressed

1. Not sure which version is correct, as Rob's comments on 5.2.3.4 :
   Section 5.2.3.4:
   In the 'Expected Output' section, path to the output in relation to OUTPUT_BASE not correct. Appears to contain uswrp/met_out ...

The previous version is indicating expected output as gather_by_date/stat_analysis/grid2grid/sfc (relative to OUTPUT_BASE), but latest version is indicating uswrp/met-out/{MODEL}/sfc (relative to OUTPUT_BASE). Which one is correct??

2. Section 5.2.3.5:
   last forecast lead should be 42, not 40

3. Section 5.2.4.2 (previously 5.2.4.1)
   Remove last bullet (Sources of data (links, contacts, etc...)

4. Section 8 still has some formatting issues:

• CUSTOM_LOOP_LIST: Underneath the text box the first letter of the next couple of paragraphs are missing

• FHR_GROUP_BEG: Format of example used could be improved???

• no 'Used by' for MTD_OBS_CONV_THRESH and MTD_OBS_CONV_RADIUS

[georgemccabe]

1. You should refer to the current conf file to see what the value is set to.

grep OUTPUT_DIR ~/METplus/parm/use_cases/model_applications/medium_range/GridStat_fcstGFS_obsGFS_Sfc_MultiField.conf
GRID_STAT_OUTPUT_DIR = {OUTPUT_BASE}/met_out/{MODEL}/sfc

[j-opatz]

Reviewed comments and corrected 1), it seems 2) and 3) were already corrected in initial submission. 4) has formatting issues beyond quick fix; may be related to alphabetical reordering of entries/behind the scene website build issues, as the entries themselves look identical to those without issues, and paragraphs have the beginning letters for CUSTOM_LOOP_LIST. My knowledge of MTD_OBS_CONV_THRESH and MTD_OBS_CONV_RADIUS is limited; filled in with MTD for "used by" but needs fact checking.

[j-opatz]

Branch has been reviewed and merged with Develop.