13. Histogram_2d plot

13.1. Description

The output from the MET grid_diag tool can be visualized as a 2D-histogram by invoking the histogram_2d.py plotting script from the command line.

For more information about the MET grid_diag tool, please refer to the documentation.

13.2. Example

13.2.1. Sample Data

The data is in netCDF format. The sample data used to create an example 2d histogram is available in the METplotpy repository, where the histogram_2d.py code is located:

$METPLOTPY_BASE/test/histogram_2d/grid_diag_temperature.nc

$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.

13.2.2. Configuration File

The histogram_2d utilizes YAML configuration files to indicate where input data is located and to set plot attributes. NOTE: The histogram_2d plot is currently not integrated into the METviewer tool, and as a result the configuration file has fewer settings than the other plot types that are available through the METviewer tool. YAML is a recursive acroynym 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, histogram_2d_defaults.yaml that 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 histogram_2d_defaults.yaml file. The custom configuration file can be an empty file if all the default settings are to be applied.

13.3. METplus Configuration

13.3.1. Default Configuration File

The following is the mandatory, histogram_2d_defaults.yaml configuration file, which serves as a starting point for creating a histogram_2d diagram plot, as it represents the default values set in METviewer.

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

plot_filename: 'tmp_z2_p500.png'

height: 800
width: 1200
font_size: 20

# use this var_name when running with --test (create test data)
# argument, otherwise, set it to correspond to the variable of interest
# in your data set if you want something other than hist_x_y
#var_name: 'hist_x_y'
var_name: 'hist_TMP_Z2_TMP_P500'


# Use for running with --test
#title: 'Probability Distribution Function'
title: '2D Histogram of TMP Z2 and TMP_P500 values '
xaxis_title: 'x'
yaxis_title: 'y'

normalize_to_pdf: False

pdf_min: 0.0
pdf_max: 4.0

13.3.2. Custom Configuration File

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

# replace with the location and name of your choosing:
plot_filename: ../../../test/histogram_2d/custom_tmp_z2_p500.png

height: 800
width: 1200
font_size: 15

var_name: 'hist_TMP_Z2_TMP_P500'


title: 'Customized 2D Histogram of TMP Z2 and TMP_P500 values '
xaxis_title: 'x'
yaxis_title: 'y'

normalize_to_pdf: False

pdf_min: 0.0
pdf_max: 4.0

# The points_path is optional and no intermediate file is created in this plot type.
# This plot type is not integrated into METviewer, so no .points1 file is expected.
# In addition, the dump_points_1 and dump_points_2 settings are unused as they are
# also unused.
# points_path: /directory/to/write/intermediate-file
# dump_points_1: 'False'
# dump_points_2: 'False'

# the input data file (replace ./ with the full path)
stat_input: ./grid_diag_temperature.nc

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

cp $METPLOTPY_BASE/test/histogram_2d/custom_histogram_2d.yaml $WORKING_DIR/custom_histogram_2d.yaml

Modify the stat_input setting in the $METPLOTPY_BASE/test/histogram_2d/custom_histogram_2d.yaml file to explicitly point to the $METPLOTPY_BASE/test/histogram_2d directory (where the custom config files and sample data reside). Replace the relative path ./grid_diag_temperature.nc with the full path $METPLOTPY_BASE/test/histogram_2d/grid_diag_temperature.nc (including replacing $METPLOTPY_BASE with the full path to the METplotpy installation on the system). 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:

stat_input: /username/myworkspace/METplotpy/test/histogram_2d/grid_diag_temperature.nc

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

This is where /username/myworkspace/METplotpy is $METPLOTPY_BASE and /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/histogram_2d_defaults.yaml configuration file will be used. NOTE: This may cause issues if the user does not have write permissions for the plot_filename directory in the histogram_2d_defaults.yaml configuration file.

The points_path, dump_points_1, and dump_points_2 settings are unused and do not need to be defined in the configuration file, as the intermediate files that are used by METviewer are currently not being generated (this plot type is currently not integrated into the METviewer tool which is why these intermediate files are not being generated). The points_path, dump_points_1, and dump_points2 settings can be commented out (i.e. line begins with a ‘#’):

# points_path: /path/to/your/directory

# dump_points_1: False

# dump_points_2: False

13.3.3. Using Defaults

To use the default settings defined in the histogram_2d_defaults.yaml file, specify a minimal custom configuration file (minimal_histogram_2d.yaml), which consists of only a comment block, but can be any empty file. NOTE: If the user has write permissions for the output filename path corresponding to the plot_filename setting in the default configuration file, the user can use the minimal_histogram_2d.yaml configuration file unaltered. Otherwise the user will need to specify a plot_filename in the minimal_histogram_2d.yaml file:

# minimal custom config file.  Use all default settings in the histogram_2d_defaults.yaml
# configuration file

#stat_input: <your-path-to>/METplotpy/test/histogram_2d/grid_diag_temperature.nc
#plot_filename: <your-path-to>/METplotpy/test/histogram_2d/tmp_z2_p500.png

Copy this file to the working directory:

cp $METPLOTPY_BASE/test/histogram_2d/minimal_histogram_2d.yaml $WORKING_DIR/minimal_histogram_2d.yaml

Add the stat_input (input data) and plot_filename (output file/plot path) setting to the $WORKING_DIR/minimal_histogram_2d.yaml file (anywhere below the comment block). The stat_input setting explicitly indicates where the sample data and custom configuration files are located. Set the stat_input to $METPLOTPY_BASE/test/histogram_2d/grid_diag_temperature.nc and set the plot_filename to $WORKING_DIR/output_plots/tmp_z2_p500.png:

stat_input: $METPLOTPY_BASE/test/histogram_2d/grid_diag_temperature.nc

plot_filename: $WORKING_DIR/output_plots/tmp_z2_p500.png

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

13.4. Run from the Command Line

The histogram_2d_defaults.yaml configuration file, in combination with the grid_diag_temperature.nc netCDF data file (generated from the MET tool grid_diag), generates a 2D-histogram plot of the hist_TMP_Z2_TMP_P500 variable:

../_images/tmp_z2_p500.png

Perform the following:

  • If using a conda environment, verify that the conda environment is running and has the required Python packages outlined in the Python Requirements section:

  • Clone the METplotpy repository from GitHub. First, make the directory:

    mkdir $METPLOTPY_BASE
    
  • $METPLOTPY_BASE is the directory where the source code is66TAW saved. Enter the following:

    cd $METPLOTPY_BASE
    git clone https://github.com/dtcenter/METplotpy
    
  • Set the PYTHONPATH to point to the location of the METplotpy code:

    For the csh environment:

    setenv PYTHONPATH $METPLOTPY_BASE/metplotpy:$METPLOTPY_BASE/metplotpy/plots
    

    For the ksh environment:

    export PYTHONPATH=$METPLOTPY_BASE/metplotpy:$METPLOTPY_BASE/metplotpy/plots
    

    Replace $METPLOTPY_BASE with the directory where the source code is saved.

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

  • Enter the following command:

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

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

  • Enter the following command:

    python $METPLOTPY_BASE/metplotpy/plots/histogram_2d/histogram_2d.py $WORKING_DIR/custom_histogram_2d.yaml
    

    In this example, this custom config file changes the title and font size.

    ../_images/custom_tmp_z2_p500.png
  • A custom_tmp_z2_p500.png output file will be created in the directory specified in the plot_filename configuration setting in the custom_histogram_2d.yaml config file.