20. Taylor Diagram

20.1. Description

The Taylor diagram was invented by Karl E. Taylor in 1994 and is useful in quantifying the correspondence between models and a “reference” based on the Pearson correlation coefficient, the root-mean-square error (RMSE), and the standard deviation. Taylor diagrams have been widely used for climate and other Earth science models but can be useful in the evaluation of models from other domains.

For more information on Taylor diagrams, please refer to the METviewer documentation.

Examples of Taylor diagrams are shown below.

A Taylor diagram of sample Downward Longwave Radiative Flux (DLWR) data displaying only positive correlation values:

../_images/taylor_pos_corr_plot.png

A Taylor diagram of sample Downward Longwave Radiative Flux (DLWR) data displaying negative and positive correlation values:

../_images/taylor_neg_and_pos_corr_plot.png

20.2. Example

20.2.1. Sample Data

The continuous statistics line type CNT, from the MET tool’s Point-Stat or Grid-Stat tools is required for creating a Taylor diagram, where the data is text output in columnar format and the FSTDEV, OSTDEV, and PR_CORR statistics are available for plotting. The sample data used to create these plots is available in the METplotpy repository, where the Taylor diagram scripts are located:

$METPLOTPY_BASE/test/taylor_diagram/dlwr_sample.data

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

20.2.2. Configuration Files

The Taylor diagram utilizes YAML configuration files to indicate where input data is located and to set plot attributes. These plot attributes correspond to values that can be set via the METviewer tool. 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, taylor_diagram_defaults.yaml, which is found in the $METPLOTPY_BASE/metplotpy/plots/config directory. $METPLOTPY_BASE indicates the directory where the METplotpy source code has been saved. 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 configuration file is a user-supplied “custom” configuration file. This file is used to customize/override the default settings in the taylor_diagram_defaults.yaml file. The custom configuration file can be an empty file if all default settings are to be applied.

20.3. METplus Configuration

20.3.1. Default Configuration File

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

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

---
# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
# "Default" settings for the Taylor diagram plot
# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

# caption settings
plot_caption: "Caption -Taylor Diagram default settings"
caption_weight: 4
caption_col: "#333333"
# relative magnification of caption size
caption_size: "8"
# axis perpendicular location adjustment
# (up/down)
caption_offset: 0
# axis parallel location adjustment (left/right)
caption_align: 0

# hexadecimal or color name
colors:
  - "#ff0000" # red
  - "#ffd400" # goldenrod
  - "#55ff00" # lime green
  - "#00ff7f"  # green
  - "#00aaff" # light blue
  - "#1500ff" # royal blue
  - "#7f00ff" # purple

fcst_var_val_1: {DLWRF}

legend_box: 'box'

legend_inset:
  x: 0.1
  y: -0.25
legend_ncol: 4
legend_size: 0.8

log_filename: STDOUT
log_level: ERROR

# Turn on/off plotting of specific points/series
plot_disp:
  - 'True'
  - 'True'
  - 'True'
  - 'True'
  - 'True'
  - 'True'
  - 'True'

# output file/plot
plot_filename: ./taylor_diagram_default.png

# size and resolution of the plot.
plot_width: 11
plot_height: 9
# plot resolution in dpi (dots per inch)
plot_res: 72

series_order:
  - 1
  - 2
  - 3
  - 4
  - 5
  - 6
  - 7

# Other supported symbols: small circle = ".", ring/hexagon = "H", rhombus/diamond="d"
series_symbols:
  # point
  - "d"
  - "."
  - "."
  - "."
  - "."
  - "."
  - "."

series_val_1:
  # series_var_1
  model:
    - suite3_MEDIAN
  # series_var2
  vx_mask:
    - Bondville
    - Desert_Rock
    - Fort_Peck
    - Goodwin_Creek
    - Penn_State
    - Sioux_Falls
    - Table_Mountain

# input file
stat_input: ../../../test/taylor_diagram/plot_dlwr_sample.data

# Draw the standard deviation arcs on the diagram
taylor_show_gamma: 'True'

# Show only positive values of correlation
taylor_voc: 'False'

title: Downward Longwave Radiative Flux Taylor Diagram
title_weight: 4
title_size: 1.8

# legend settings
user_legend:
  - ""
  - ""
  - ""
  - ""
  - ""
  - ""
  - ""


#
# UNSUPPORTED or UNUSED settings BUT REQUIRED/USED by METviewer
#  Do not modify the settings below this section
#

# Unsupported actions by Matplotlib.

# Matplotlib align choices are left, right, center (default) and
# offset is automatically chosen to avoid labels and ticks on the topmost
# x-axis
# To work around what METviewer is expecting (a numerical value),
# set title_align to -1.5 for 'left', 1.5 for 'right', any other value for 'center'
title_align: 0.5
title_offset: -2

# x-axis ticks
#these are unsupported
xtlab_orient: 1
xtlab_size: 1
xtlab_perp: -0.75
xtlab_horiz: 0.5
xtlab_freq: 0
x2tlab_orient: 1
x2tlab_size: 0.8
x2tlab_perp: 1
x2tlab_horiz: 0.5

# y-axis ticks
# these are unsupported
ytlab_perp: 0.5
ytlab_horiz: 0.5
y2tlab_orient: 1
y2tlab_perp: 0.5
y2tlab_horiz: 0.5
y2tlab_size: 1

# second y-axis ticks
# these are unsupported as this diagram doesn't have
# a second y-axis
y2lab_size: 1
y2lab_offset: 1
y2lab_align: 0.5

# second x-axis settings, not necessary
# for this diagram, expected by METviewer
x2lab_size: 0.8
x2lab_offset: -0.5
x2lab_align: 0.5

# magnification
cex: 1

# margins (Matplotlib doesn't have this level of granularity for margins)
mar:
  - 8
  - 4
  - 5
  - 4

# create html relevant only for Plotly interactivity in METviewer, not
# applicable for Matplotlib plotting.
create_html: 'False'


# Event equalization to check for missing data
# not applicable for this plot, but METviewer expects this
# setting
event_equal: 'False'

dump_points_1: 'False'
dump_points_2: 'False'
# not relevant since there aren't any intermediate files being
# created
points_path: ''
vert_plot: 'False'
x_reverse: 'False'
num_stats: 'False'
indy1_stag: 'False'
indy2_stag: 'False'
sync_axes: 'False'
log_y1: 'False'
log_y2: 'False'

# used in the calculation of confidence intervals but not used here
variance_inflation_factor: False

series_type:
  - "b"
  - "b"
  - "b"
  - "b"
  - "b"
  - "b"
  - "b"

# line width (no lines in Taylor diagram, only points)
lwd:
  - 5
  - 5
  - 5
  - 5
  - 5
  - 5
  - 5

# x-axis labels
xaxis: Standard Deviation
xlab_size:  1
#up-down positioning
xlab_align: .5
#left-right positioning
xlab_offset: 2
# text weight: plain text, bold, italic, bold italic
xlab_weight: 1

# y-axis labels
yaxis_1: Standard Deviation
ylab_size: 1
#left-right positioning
ylab_align: 0.5
#up-down positioning
ylab_offset:  -2
# text weight: plain text, bold, italic, bold italic
ylab_weight: 1

# y-axis ticks
ytlab_orient: 1
ytlab_size: 1.3


# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
# The underlying Taylor diagram (grid lines, etc.)
# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
#

# These are expected/used by METviewer but cannot
# be applied to the underlying Taylor diagram plot. Grid
# linestyle and colors cannot be changed.
grid_lty: "--"
# Hexadecimal value or color name
grid_col: "#cccccc"
grid_linewidth: 1
grid_x: "listX"


# other option is mm (millimeters)
plot_units: in
# only png plots are generated, this setting is expected by METviewer
plot_type: png16m
plot_ci:
# No confidence intervals plotted in Taylor diagram, so these settings have no effect
  - None
  - None
  - None
  - None
  - None
  - None
  - None


con_series:
# Only useful for line plots where consecutive points may be interspersed with NA values
# these values have no use for the Taylor diagram.
  - 1
  - 1
  - 1
  - 1
  - 1
  - 1
  - 1

# not relevant for this plot, these values are expected by METviewer
show_signif:
  - 'False'
  - 'False'
  - 'False'
  - 'False'
  - 'False'
  - 'False'
  - 'False'

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.

20.3.2. Custom Configuration File

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

---
# custom config file to override some of the settings in the
# default config file taylor_diagram_defaults.yaml
stat_input: ./plot_dlwr_sample.data
plot_filename: ./taylor_diagram_custom.png

# change the caption text
plot_caption: "Custom caption"

# change the title
title: Custom Taylor Diagram - DLWR
title_weight: 1
title_size: 1.2

# change the symbols
# Other supported symbols: small circle = ".", ring/hexagon = "H", rhombus/diamond="d"
series_symbols:
  # point
  - "H"
  - "."
  - "."
  - "d"
  - "."
  - "."
  - "H"

# 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: ./taylor_diagram.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/taylor_diagram/taylor_diagram_custom.yaml $WORKING_DIR/taylor_diagram_custom.yaml

Modify the stat_input setting in the $METPLOTPY_BASE/test/taylor_diagram/taylor_diagram_custom.yaml file to explicitly point to the $METPLOTPY_BASE/test/taylor_diagram/taylor_diagram directory (where the custom config files and sample data reside). Replace the relative path ./dlwr_sample.data with the full path $METPLOTPY_BASE/test/taylor_diagram/dlwr_sample.data (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/taylor_diagram/dlwr_sample.data

plot_filename: /username/working_dir/output_plots/taylor_diagram_custom.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/taylor_diagram_defaults.yaml configuration file will be used.

No intermediate files (i.e. .points1 file) are generated by the Taylor diagram. The dump_points_1 setting is expected by METviewer and is set to False in the configuration file.

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

20.3.3. Using Defaults

To use the default settings defined in the taylor_diagram_defaults.yaml file, specify a minimal custom configuration file (minimal_taylor_diagram_defaults.yaml), which consists of only a comment block, but it can be any empty file (write permissions for the output filename path corresponding to the plot_filename setting in the default configuration file will be needed. Otherwise, specify a plot_filename in the minimal_taylor_diagram.yaml file):

# minimal yaml file, replace the path-to to the
stat_input: path-to/plot_dlwr_sample.data
plot_filename: path-to/plot_dlwr_sample.png

Copy this file to the working directory:

cp $METPLOTPY_BASE/test/taylor_diagram/minimal_taylor_diagram.yaml $WORKING_DIR/minimal_taylor_diagram.yaml

If the stat_input and plot_filename settings (output file/plot path) are missing, add these settings to the $WORKING_DIR/minimal_taylor_diagram.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/taylor_diagram/dlwr_sample.data and set the plot_filename to $WORKING_DIR/output_plots/taylor_diagram_default.png:

stat_input: $METPLOTPY_BASE/test/taylor_diagram/dlwr_sample.data

plot_filename: $WORKING_DIR/output_plots/taylor_diagram_default.png

$WORKING_DIR is the working directory where all of the custom configuration files are being saved. NOTE: The plot_filename (output directory) may be specified to a directory other than the $WORKING_DIR/output_plots, as long as it is an existing directory where the author has read and write permissions.

20.4. Run from the Command Line

To generate a default Taylor diagram (i.e. using settings in the taylor_diagram_defaults.yaml configuration file), perform the following:

  • If using the conda environment, verify the conda environment is running and has has the required Python packages outlined in the requirements section.

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

  • Run the following on the command line:

    python $METPLOTPY_BASE/metplotpy/plots/taylor_diagram/taylor_diagram.py $WORKING_DIR/minimal_taylor_diagram.yaml
    

    This will create a PNG file, taylor_diagram_default.png, in the directory that was specified in the plot_filename setting of the minimal_taylor_diagram.yaml config file:

    ../_images/taylor_diagram_default.png

    To generate a slightly modified, customized plot, run the command (below) using the taylor_diagram_custom.yaml file:

    python $METPLOTPY_BASE/metplotpy/plots/taylor_diagram/taylor_diagram.py $WORKING_DIR/taylor_diagram_custom.yaml
    
  • A taylor_diagram_custom.png output file will be created in the directory that was specified in the plot_filename config setting in the taylor_diagram_custom.yaml config file. This customized plot has a different output filename, title text, title size, title font style, caption text, and different symbols than the default plot, as shown below:

../_images/taylor_diagram_custom.png