2. Software Installation

2.1. Introduction

This chapter describes how to download and set up METplus Wrappers.

2.2. Supported architectures

METplus Wrappers was developed on Debian Linux and is supported on this platform. Each release listed on the METplus Downloads page includes a link to the Existing Builds and Docker for that version. The METplus team supports the installation of the METplus components on several operational and research high performance computing platforms, including those at NCAR, NOAA, and other community machines. Pre-built METplus images on DockerHub are also provided.

2.3. Programming/scripting languages

METplus Wrappers is written in Python 3.6.3. It is intended to be a tool for the modeling community to use and adapt. As users make upgrades and improvements to the tools, they are encouraged to offer those upgrades to the broader community by offering feedback to the developers or coordinating for a GitHub pull. For more information on contributing code to METplus Wrappers, please create a post in the METplus GitHub Discussions Forum.

2.4. Requirements

2.4.1. Software Requirements

Minimum Requirements

The following software is required to run METplus Wrappers:

Wrapper Specific Requirements

  • TCMPRPlotter wrapper

    • R version 3.2.5

  • SeriesAnalysis wrapper

    • convert (ImageMagick) utility - if generating plots and/or animated images from the output

  • PlotDataPlane wrapper

    • convert (ImageMagick) utility - if generating images from the Postscript output

2.4.2. Python Package Requirements

The version number listed next to any Python package corresponds to the version that was used for testing purposes. Other versions of the packages may still work but it is not guaranteed. Please install these packages using pip or conda.

Minimum Requirements

To run most of the METplus wrappers, the following packages are required:

  • dateutil (2.8)

Using pip:

pip3 install python-dateutil==2.8

Using conda:

conda install -c conda-forge python-dateutil=2.8

MET Python Embedding Requirements

If running use cases that use Python embedding, the MET executables must be installed with Python enabled and the following Python packages installed:

  • xarray (0.17.0)

  • numpy (1.19.2)

  • pandas (1.0.5)

  • netCDF4 (1.5.4)

See Appendix F Python Embedding section in the MET User’s Guide for more information.

Wrapper Specific Requirements

The following wrappers require that additional Python packages be installed to run.

  • SeriesAnalysis wrapper

    • netCDF4 (1.5.4)

  • MakePlots wrapper

    • cartopy (0.17.0)

    • pandas (1.0.5)

  • CyclonePlotter wrapper

    • cartopy (0.17.0)

    • matplotlib (3.3.4)

Cartopy, one of the dependencies of CyclonePlotter, attempts to download shapefiles from the internet to complete successfully. So if CyclonePlotter is run on a closed system (i.e. no internet), additional steps need to be taken. First, go to the Natural Earth Data webpage and download the small scale (1:110m) cultural and physical files that will have multiple extensions (e.g. .dbf, .shp, .shx). Untar these files in a noted location. Finally, create an environment variable in the user-specific system configuration file for CARTOPY_DIR, setting it to the location where the shapefiles are located.

2.5. Getting the METplus Wrappers source code

The METplus Wrappers source code is available for download from the public GitHub repository. The source code can be retrieved either through a web browser or the command line.

2.5.1. Get the source code via Web Browser

../_images/metplus_repo_releases_page.png
  • Click on the ‘Source code’ link (either the zip or tar.gz) under Assets and when prompted, save it to the directory.

  • Uncompress the source code (on Linux/Unix: gunzip for zip file or tar xvfz for the tar.gz file)

2.5.2. Get the source code via Command Line

  • Open a shell terminal

  • Clone the DTCenter/METplus GitHub repository:

SSH:

git clone git@github.com:dtcenter/metplus

HTTPS:

git clone https://github.com/dtcenter/metplus

2.6. Obtain sample input data

The use cases provided with the METplus release have sample input data associated with them. This step is optional but is required to be able to run the example use cases, which illustrate how the wrappers work.

  • Create a directory to put the sample input data. This will be the directory to set for the value of INPUT_BASE in the METplus Configuration.

  • Go to the web page with the sample input data.

  • Click on the vX.Y version directory that corresponds to the release to install, i.e. v4.0 directory for the v4.0.0 release.

  • Click on the sample data tgz file for the desired use case category or categories run and when prompted, save the file to the directory created above.

Note

Files with the version number in the name, i.e. sample_data-data_assimilation-4.0.tgz, have been updated since the last major release. Files without the version number in the file name have not changed since the last major release and can be skipped if the data have already been obtained with a previous release.

2.7. METplus Wrappers directory structure

The METplus Wrappers source code contains the following directory structure:

METplus/
  build_components/
  ci/
  docs/
  environment.yml
  internal_tests/
  manage_exernals/
  metplus/
  parm/
  produtil/
  README.md
  requirements.txt
  setup.py
  ush/

The top-level METplus Wrappers directory consists of a README.md file and several subdirectories.

The build_components/ directory contains scripts that use manage_externals and files available on dtcenter.org to download MET and start the build process.

The ci/ directory contains scripts that are used for creating Docker images and scripts that are used internally for automation.

The docs/ directory contains documentation for users and contributors (HTML) and Doxygen files that are used to create the METplus wrapper API documentation. The Doxygen documentation can be created and viewed via web browser if the developer has Doxygen installed on the host. The Doxygen documentation is useful to contributors and is not necessary for METplus end-users.

The internal_tests/ directory contains test scripts that are only relevant to METplus developers and contributors.

The manage_externals/ directory contains scripts used to facilitate the downloading and management of components that METplus interacts with such as MET and METviewer.

The metplus/ directory contains the wrapper scripts and utilities.

The parm/ directory contains all the configuration files for MET and METplus Wrappers.

The produtil/ directory contains part of the external utility produtil.

The ush/ directory contains the run_metplus.py script that is executed to run use cases.

2.8. External Components

2.8.1. GFDL Tracker

2.9. Add ush directory to shell path (optional)

To call the run_metplus.py script from any directory, add the ush directory to the path. The following commands can be run in a terminal. They can also be added to the shell run commands file (.cshrc for csh/tcsh or .bashrc for bash). For the following commands, change /path/to to the actual path to the METplus directory on the local file system.

csh/tcsh:

# Add METplus to path
set path = (/path/to/METplus/ush $path)

bash/ksh:

# Add METplus to path
export PATH=/path/to/METplus/ush:$PATH

2.10. Set Default Configuration File for Shared Install

The default METplus configurations are found in parm/metplus_config/defaults.conf. If configuring METplus Wrappers in a common location for multiple users, it is recommended that the values for MET_INSTALL_DIR and INPUT_BASE are set in the default configuration file. More information on how to set these values can be found in the Default Configuration File section in the next chapter.