CMOR /PrePARE documentation improvements

[taylor13]

We need to make sure that all the documentation is correct and up-to-date.

I don't think it is clear for CMIP6 where one should obtain the example input file and in general what CMOR needs. Please review and correct the following text for accuracy and then modify the documentation.

1. I think we should move https://github.com/PCMDI/cmor/blob/master/Test/CMOR_input_example.json to https://github.com/PCMDI/cmip6-cmor-tables/tree/master/Tables .

2. In its description of "Arguments", the function cmor_dataset_json(), documented in https://cmor.llnl.gov/mydoc_cmor3_api/ , currently points to https://raw.githubusercontent.com/PCMDI/cmor/master/Test/test2.json i . It should point to: https://github.com/PCMDI/cmip6-cmor-tables/tree/master/Tables .

3. Address the following issues 58, 55, 38, and 36 in https://github.com/PCMDI/cmor3_documentation/issues.
   Please insert the following text just before the paragraph that begins "Converting data with CMOR typically involves the following steps ...".

4. Most importantly, In the documentation on the "getting started overview page" at https://cmor.llnl.gov/ , please insert the following text just before the paragraph that begins "Converting data with CMOR typically involves the following steps ...". (First carefully check for correctness.)

The following input files are typically needed by CMOR:

---

• the "User Input File" (e.g., CMOR_input_example.json), which provides user-supplied metadata and configuration directives.
• A "controlled vocabulary file" (e.g., "CMIP6_CV.json), which concatenates into a single file most of the CMIP6 controlled vocabularies archived at https://github.com/WCRP-CMIP/CMIP6_CVs . This file is updated frequently as additional models and institutions register to participate in CMIP6.
• a "CMOR Table" (e.g., CMIP6_amon.json), which provides for each variable that might be written by CMOR much of the required metatdata. It also provides additional information that CMOR uses to correctly write the data and to enable certain QC checks.
• a "Vertical Coordinate Formula Terms Table" (e.g., CMIP6_formula_terms.json)
• a "Coordinates Table" (e.g., CMIP6_coordinate.json) CMIP6
• CMIP6_grids.json supplements the Coordinates Table with axis information that is sometimes needed in the treatment of unstructured grids.

The files used by CMOR for CMIP6 are archived in https://github.com/PCMDI/cmip6-cmor-tables/tree/master/Tables, and all but the CMOR_input_example.json file must not be modifed by the user. The CMOR_input_example.json file must be edited to accurately reflect the output being written by the user (but do not modify the lines of text appearing after the comment line, "#note": " **** The following will be obtained from the CV and do not need to be defined here"). Note that the CMIP6_CV.json file found in https://github.com/PCMDI/cmip6-cmor-tables/tree/master/Tables are updated whenever new models and institutions are registered to participate in CMIP6.

---

[mauzey1]

So CMOR_input_example.json should be placed in the Tables directory of CMOR, and have all tests point to this new location?

For issue #55, if we change the name from "Control Vocabulary" to "Controlled Vocabulary" should the user input attribute _control_vocabulary_file be changed to _controlled_vocabulary_file?

[taylor13]

Yes "Controlled Vocabulary" or "Controlled Vocabularies" is preferred in reference to the CVs, but this is not absolutely essential if it is a lot of work.

The idea of moving the CMIP_input_example.json file to the Tables repository is that then a user can download all the input files needed by CMOR from a single location: the CMOR tables, the CMIP6_CV.json file, and an example of a CMIP_input.json file. Does that seem like it would be a good idea?

Perhaps a replica should also be included in the Test repository so that if someone wants to perform the tests they won't have to obtain the file from the Tables repository. What do you think?

[taylor13]

In the documentation, we should try to make it clear how to do what Claire (@hot007) is trying to do as described in PCMDI/cmor#436 . I think this is probably a common "use case".

[mauzey1]

@taylor13 I have made changes to the documentation (#88) that add instructions for running tests with the Anaconda install of CMOR, which should address PCMDI/cmor#436.

I think all of the items in this issue have been resolved. Should we close this issue?

[taylor13]

Yes, I think it can be closed. By the way, is the default build with or without CDMS, genutil, and such, are are these optional now when running CMOR?

[mauzey1]

@taylor13 CMOR does not have cdms2 or genutil as part of its default build.

[taylor13]

thanks.