16. Hovmoeller Plot

16.1. Description

A Hovmoeller plot is a 2D contour plot with time along one axis and a spatial dimension along the other axis. Typically the spatial dimension not shown has been averaged over some domain. The current METplotpy Hovmoeller class supports only time along the vertical axis and longitude along the horizontal axis. This can be generalized in future releases to allow, for instance, time on the horizontal and latitude on the vertical. The examples are based on tropical diagnostics applications, so a meridional average of precipitation from 5 S to 5 N has been set up in the default configuration.

Please refer to the METplus use case documentation for instructions on how to generate a Hovmoeller diagram.

16.2. Required Packages:

  • metcalcpy

  • netcdf4 1.5.7 or above

  • numpy 1.22.3

  • pandas 1.4.2

  • plotly 5.7.0 or above

  • scipy 1.8.0 or above

  • xarray 2022.3.0

16.3. Example

16.3.1. Sample Data

The sample data used to create an example Hovmoeller plot is available in the s2s METplus data tar file in the directory model_applications/s2s/UserScript_obsPrecip_obsOnly_Hovmoeller.

Save this file in a directory where you have read and write permissions, such as $WORKING_DIR/data/hovmoeller, where $WORKING_DIR is the path to the directory where you will save input data.

16.3.2. Configuration Files

There is a YAML config file located in $METPLOTPY_BASE/metplotpy/plots/config/hovmoeller_defaults.yaml

plot_filename: erai_precip.png
input_data_file: ./precip.erai.sfc.1p0.2x.2014-2016.nc

plot_height: 800
plot_width: 1200
# plot title
title: ERAI Precipitation

# Font size for the x-axis and y-axis labels and the title font size
xy_label_font_size: 20
title_size: 20

# xaxis title
xaxis: Longitude
# yaxis title
yaxis: Time

date_start: 2016-01-01
date_end: 2016-03-31

lat_max: 5
lat_min: -5

var_name: precip
var_units: mm / day
unit_conversion: 250

contour_min: 0.2
contour_max: 1.6
contour_del: 0.2
colorscale: 'BuPu'

log_level: ERROR
log_filename: stdout

$METPLOTPY_BASE is the directory where the METplotpy code is saved:

e.g.

/usr/path/to/METplotpy if the source code was cloned or forked from the Github repository

or

/usr/path/to/METplotpy-x.y.z if the source code was downloaded as a zip or gzip’d tar file from the Release link of the Github repository. The x.y.z is the release number.

The Hovmoeller plot utilizes YAML configuration files to indicate where input data is located and to set plot attributes, and logging preferences. YAML is a recursive acronym for “YAML Ain’t Markup Language” and according to yaml.org, it is a “human-friendly data serialization language”.

It is commonly used for configuration files and in applications where data is being stored or transmitted. Two configuration files are required. The first is a default configuration file, hovmoeller_defaults.yaml. This is found in the $METPLOTPY_BASE/metplotpy/plots/config directory. All default configuration files are located in the $METPLOTPY_BASE/metplotpy/plots/config directory. Default configuration files are automatically loaded by the plotting code and do not need to be explicitly specified when generating a plot.

The second, required YAML configuration file is a user-supplied “custom” configuration file that is used to customize/override the default settings in the hovmoeller_defaults.yaml file. The custom configuration file can be an empty file if all default settings are to be applied.

16.3.3. Default Configuration File

The following is the mandatory, hovmoeller_defaults.yaml configuration file, which serves as a starting point for creating a Hovmoeller plot.

NOTE: This default configuration file is automatically loaded by hovmoeller.py.

plot_filename: erai_precip.png
input_data_file: ./precip.erai.sfc.1p0.2x.2014-2016.nc

plot_height: 800
plot_width: 1200
# plot title
title: ERAI Precipitation

# Font size for the x-axis and y-axis labels and the title font size
xy_label_font_size: 20
title_size: 20

# xaxis title
xaxis: Longitude
# yaxis title
yaxis: Time

date_start: 2016-01-01
date_end: 2016-03-31

lat_max: 5
lat_min: -5

var_name: precip
var_units: mm / day
unit_conversion: 250

contour_min: 0.2
contour_max: 1.6
contour_del: 0.2
colorscale: 'BuPu'

log_level: ERROR
log_filename: stdout

In the default config file, logging is set to stdout and the log level is ERROR (i.e. only log messages of type ERROR will be logged). If the log_filename and log_level are not specified in the custom configuration file, these settings will be used.

16.3.4. Custom Configuration File

A second, mandatory configuration file is required, which is used to customize the settings to the Hovmoeller plot. The custom_hovmoeller.yaml file is included with the source code and looks like the following:

plot_filename: ./hovmoeller_custom_plot.png
input_data_file: /path/to/WorkingDir/precip.erai.sfc.1p0.2x.2014-2016.nc
plot_height: 400
plot_width: 600
title: Custom ERAI Precip
title_size: 10
xy_label_font_size: 10

date_start: 2016-02-01
date_end: 2016-03-03

lat_max: 4
lat_min: -4

var_name: precip
var_units: mm / day
unit_conversion: 250

contour_min: 0.2
contour_max: 1.6
contour_del: 0.2
colorscale: 'BuPu'

# To save your log output to a file, specify a path and filename and uncomment the line below.  Make sure you have
# permissions to the directory you specify.  The default, as specified in the default config file is stdout.
#log_filename: ./hovmoeller.log

# To change the log level, specify a log level: debug, info, warning, error and uncomment the line below.
# The debug and info log levels will produce more log output.
#log_level: WARNING

Copy this custom config file from the directory where the source code was saved to the working directory:

cp $METPLOTPY_BASE/test/hovmoeller/custom_hovmoeller.yaml $WORKING_DIR/custom_hovmoeller.yaml

Modify the input_data_file setting in the $WORKING_DIR/custom_hovmoeller.yaml file to explicitly point to the $WORKING_DIR directory (where the custom config files and sample data reside). Replace the relative path ./precip.erai.sfc.1p0.2x.2014-2016.nc with the full path $WORKING_DIR/data/hovmoeller/precip.erai.sfc.1p0.2x.2014-2016.nc (including replacing $WORKING_DIR with the full path to the working directory). Modify the plot_filename setting to point to the output path where the plot will be saved, including the name of the plot.

For example:

input_data_file: /username/working_dir/data/hovmoeller/precip.erai.sfc.1p0.2x.2014-2016.nc

plot_filename: /username/working_dir/output_plots/hovmoeller_custom_plot.png

This is where /username/working_dir is $WORKING_DIR. Make sure that the $WORKING_DIR directory that is specified exists and has the appropriate read and write permissions.The path listed for plot_filename may be changed to the output directory of one’s choosing. If this is not set, then the plot_filename setting specified in the $METPLOTPY_BASE/metplotpy/plots/config/hovmoeller_defaults.yaml configuration file will be used.

To save the log output to a file, uncomment the log_filename entry and specify the path and name of the log file. Select a directory with the appropriate read and write privileges. To modify the verbosity of logging than what is set in the default config file, uncomment the log_level entry and specify the log level (debug and info are higher verbosity, warning and error are lower verbosity).

16.3.5. Using Defaults

If the user wishes to use all the default settings defined in the hovmoeller_defaults.yaml file, specify a minimal custom configuration file (minimal_hovmoeller.yaml), which can consist of only a comment block or it can be any empty file (as long as the user has write permissions for the output filename path corresponding to the plot_filename setting in the default configuration file). Otherwise, specify the output plot path and name in the plot_filename setting in the minimal_hovmoeller.yaml file:

# minimal, use all the settings in the default except specify
# input data file path and location of the output plot.
input_data_file: /path/to/WorkingDir/precip.erai.sfc.1p0.2x.2014-2016.nc
plot_filename: ./hovmoeller_default_plot.png

Copy this file to the working directory:

cp $METPLOTPY_BASE/test/hovmoeller/minimal_hovmoeller.yaml $WORKING_DIR/minimal_hovmoeller.yaml

Edit the input_data_file (input data) and plot_filename (output file/plot path) settings in the $WORKING_DIR/minimal_hovmoeller.yaml file (anywhere below the comment block). The input_data_file setting explicitly indicates where the sample data and custom configuration files are located. Set the input_data_file to $WORKING_DIR/data/hovmoeller/precip.erai.sfc.1p0.2x.2014-2016.nc and set the input_data_file and plot_filename settings:

input_data_file: $WORKING_DIR/data/hovmoeller/precip.erai.sfc.1p0.2x.2014-2016.nc

plot_filename: $WORKING_DIR/output_plots/hovmoeller_default.png

$WORKING_DIR is the working directory where all the custom configuration files are being saved. NOTE: Specifying the plot_filename (output directory) to a directory other than the $WORKING_DIR/output_plots can be done as long as it is an existing directory where the user has read and write permissions.

In the default config file, logging is set to stdout and the log level is ERROR (i.e. only log messages of type ERROR will be logged). If the log_filename and log_level are not specified in the custom configuration file, these settings will be used.

16.4. Run from the Command Line

The Hovmoeller plot that uses only the default values defined in the hovmoeller_defaults.yaml configuration file looks like the following:

../_images/hovmoeller_default.png

Perform the following:

  • To use the conda environment, verify the conda environment is running and has has the required Python packages outlined in the Python Requirements section (and from the Requirements Packages section above):

  • Set the PYTHONPATH environment variable:

$METCALCPY_SOURCE is the path downloaded/cloned METcalcpy code. $METPLOTPY_SOURCE is the path of the downloaded/cloned METplotpy code.

Command for csh:

setenv PYTHONPATH $METCALCPY_SOURCE/METcalcpy:$METCALCPY_SOURCE/METcalcpy/util:$METPLOTPY_SOURCE/METplotpy${PYTHONPATH}

Command for bash:

export PYTHONPATH=\
$METCALCPY_SOURCE/METcalcpy:$METCALCPY_SOURCE/METcalcpy/util:$METPLOTPY_SOURCE/METplotpy${PYTHONPATH}
  • Set the METPLOTPY_BASE environment variable to point to $METPLOTPY_BASE

    For the ksh environment:

    export METPLOTPY_BASE=$METPLOTPY_BASE
    

    For the csh environment:

    setenv METPLOTPY_BASE $METPLOTPY_BASE
    

    Replacing the $METPLOTPY_BASE with the directory where the METplotpy source code was saved.

    To generate the above “defaults” plot (i.e using default configuration settings), use the “minimal” custom configuration file, minimal_hovmoeller.yaml.

  • Enter the following command:

    python $METPLOTPY_BASE/metplotpy/plots/hovmoeller/hovmoeller.py $WORKING_DIR/minimal_hovmoeller.yaml
    
  • A hovmoeller_default.png output file will be created in the directory specified in the plot_filename configuration setting in the minimal_hovmoeller.yaml config file.

    To generate a customized Hovmoeller plot (i.e. some or all default configuration settings are to be overridden), use the custom_hovmoeller.yaml config file.

  • Enter the following command:

    python $METPLOTPY_BASE/metplotpy/plots/hovmoeller/hovmoeller.py $WORKING_DIR/custom_hovmoeller.yaml
    

    In this example, this custom config file changes the title (title name, font size), the axis label font size, and the date_start and date_end values. These changes are evident in the drastically different plot shown below. The user can experiment with the values in the custom_hovmoeller.yaml configuration file to achieve the desired appearance.

    ../_images/hovmoeller_custom_plot.png
  • A custom_hovmoeller.png output file will be created in the directory that was specified in the plot_filename configuration setting in the custom_hovmoeller.yaml config file.