How To Begin
These instructions are for complete beginners to MELODIES MONET to help you get started. We will go over the following concepts:
Python, GitHub, and Conda
The source code for MELODIES MONET is stored and managed on GitHub: https://github.com/NCAR/MELODIES-MONET. MELODIES MONET uses MONET for pairing, plotting, and statistical calculations, which is also on on GitHub: https://github.com/NOAA-OAR-ARL/MONET and uses MONETIO for reading in model and observational datasets into a standard format, which is also on GitHub: https://github.com/NOAA-OAR-ARL/MONETIO.
MELODIES MONET is primarily written in Python and as such uses a number of Python packages, which are described here: Installation/Requirements. It is recommended to use Conda, Pip, or another Python package management system to handle these dependencies. All of our instructions are for Conda, but you are welcome to adapt these instructions for other Python package management systems.
It is highly recommended that you have a general understanding of GitHub, Python, and Conda to use and especially develop MELODIES MONET. If these tools are new to you, we highly recommend you follow the tutorials described on New To Python, GitHub, or Conda before going further in these instructions.
User Guide
Please read through our “User’s Guide” section, prior to using our tool. This guide provides lots of useful information on a basic Introduction and Description including how we connect with MONET and MONETIO. Supported models and observations are described in the Supported Datasets section. Supported diagnostics like calculating regulatory metrics are described in the Supported Diagnostics section. Supported plots and statistics available in MELODIES MONET are described in Supported Plots and Supported Statistics sections. Also more complex capabilities are described in the Time Chunking, Gridded Datasets, and Selecting regions sections.
Installation
The general installation and requirements are explained in the Installation/Requirements section. There are also machine specific installation instructions in the “Help and Reference” section under Machine-specific Install for the NCAR HPC Derecho/Casper and the NOAA HPC Hera machines, which describe unique considerations for these systems. Occasionally, our package dependencies become outdated. We do our best to keep these packages updated. If you run into errors using a Python package, please refer to the Installation/Requirements section on our develop version of ReadTheDocs to check for updates.
Running Tutorial Examples
The best way to get started with MELODIES MONET is to run our tutorial examples. Please refer to our Description of Tutorial Examples page to learn about these examples and how to run them on your own system. These examples will automatically download observation and model datasets for you, so you do not need to do this as an initial step. It is strongly recommended that users test and run these tutorial examples prior to using MELODIES MONET to evaluate their own datasets, so that they can better understand the YAML input format, how to run MELODIES MONET, and the various capabilities available. We are working on adding more tutorial examples for later versions of MELODIES MONET.
Downloading Observations
Prior to running MELODIES MONET to evaluate your own model data, you must download the observations relevant for your use case. Please refer to Downloading Observations to learn how to download observations for your observation type. To learn which observations are available in MELODIES MONET, please refer to Supported Datasets in our “User’s Guide” Section.
Running Other Examples
Now that you have observation datasets and your own model results, you can test using MELODIES MONET to evaluate your own model output. It is strongly recommended to copy an example for a similar type of analysis either from our tutorial examples described above or our more general examples on our GitHub repository under the folder called examples. Note that these examples unlike our tutorial examples, do not have archived model and observation datasets for you to automatically download and instead are just examples for how to run different capabilities of the tool for you to adapt for use with your own datasets.
You can learn more about how to adapt these examples for your needs by referring to our very comprehensive Description of All YAML Options in the “Help and Reference” section and you can learn how MELODIES MONET works in connection with the YAML file format in the Software Architecture section.
Then follow instructions in How To Run for first testing your model evaluation for a subset of the data by running in a Jupyter Notebook and then submitting a job for longer analysis periods.
Where To Get More Help
Recent tutorials and workshops are listed in the Tutorials & Workshops section. In particular, the MELODIES MONET hybrid Tutorial on October 15-16, 2024, provided lectures on MELODIES MONET capabilities, hands on exercises for users to learn the tool, and break out sessions with the MELODIES MONET development team to learn how to add new features into the tool. The slides and recordings are all on the public Tutorial Agenda Website. Please refer to these comprehensive slides for greater understanding about MELODIES MONET.
Please refer to the API, to learn more about each submodule. You can use any of the submodules in MELODIES MONET, MONET, or MONETIO directly in your own Python routines if you wish.
How to Contribute
Now that you know how to use MELODIES MONET, you may wish to add new features. For a summary of how to get involved refer to our How to Get Involved? section. If you would like to learn how to add new datasets, please refer to our Adding New Datasets section and if you would like to contribute to the code or docs development, please refer to our Developer’s Guide section. Please learn about our current developers by visiting our Development Team section and let us know if you would like to join our development team!