2. Line Plot
2.1. Description
The line plot is a scatter plot where each point is connected by a line. It is used by METviewer for generating series plots. Refer to the METviewer documentation for details on how this plot is utilized.
2.2. Example
2.2.1. Sample Data
The data is text output from MET in columnar format. The sample data used to create an example line plot is available in the METplotpy repository, where the line plot tests are located:
$METPLOTPY_BASE/metplotpy/test/line/line.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.
2.2.2. Configuration Files
The line plot 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, line_defaults.yaml, which is found in the $METPLOTPY_BASE/metplotpy/plots/config directory. All default configuration files are located in the $METPLOTPY_BASE/metplotpy/plots/config directory. $METPLOTPY_BASE is base directory where the METplotpy source code has been saved. 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 line_defaults.yaml file. The custom configuration file can be an empty file if all default settings are to be applied.
Note
The YAML configuration files do not support expanding environment variables. If you see an environment variable referenced in this documentation for a YAML configuration item, please be aware the full value of that environment variable must be used.
2.3. METplus Configuration
2.3.1. Default Configuration File
The following is the mandatory, line_defaults.yaml configuration file, which serves as a good starting point for creating a line plot as it represents the default values set in METviewer.
NOTE: This default configuration file is automatically loaded by line.py.
alpha: 0.05
caption_align: 0.0
caption_col: '#333333'
caption_offset: 3
caption_size: 0.8
caption_weight: 1
cex: 1
colors: []
con_series: []
derived_series_1: []
derived_series_2: []
dump_points_1: 'False'
dump_points_2: 'False'
event_equal: 'False'
fcst_var_val_1: {}
fcst_var_val_2: {}
fixed_vars_vals_input: {}
grid_col: '#f5274a'
grid_lty: 3
grid_lwd: 1
grid_on: 'True'
grid_x: listX
indy_stagger_1: 'False'
indy_stagger_2: 'False'
indy_vals: []
indy_var: ''
legend_box: o
legend_inset:
x: 0.0
y: -0.25
legend_ncol: 3
legend_size: 0.8
line_type: N/A
list_stat_1: []
list_stat_2: []
log_filename: stdout
log_level: ERROR
mar:
- 8
- 4
- 5
- 4
method: ''
mgp:
- 1
- 1
- 0
num_iterations: 1
num_threads: -1
plot_caption: 'Caption'
plot_ci: []
plot_disp: []
plot_filename: ./line_default.png
plot_height: 8.5
plot_res: 72
plot_stat: median
plot_type: png16m
plot_units: in
plot_width: 11.0
random_seed: null
series_line_style: []
series_line_width: []
series_order: []
series_symbols: []
series_type: []
series_val_1: {}
series_val_2: {}
show_nstats: 'False'
show_signif: []
start_from_zero: 'False'
stat_input: ../../../test/line/line.data
sync_yaxes: 'False'
title: test title
title_align: 0.5
title_offset: -2
title_size: 1.4
title_weight: 2.0
user_legend: []
variance_inflation_factor: 'True'
vert_plot: 'False'
x2lab_align: 0.5
x2lab_offset: -0.5
x2lab_size: 0.8
x2lab_weight: 1
x2tlab_horiz: 0.5
x2tlab_orient: 1
x2tlab_perp: 1
x2tlab_size: 0.8
xaxis: test x_label
xaxis_reverse: 'False'
xlab_align: 0.5
xlab_offset: 2
xlab_size: 1
xlab_weight: 1
xlim: []
xtlab_decim: 0
xtlab_horiz: 0.5
xtlab_orient: 1
xtlab_perp: -0.75
xtlab_size: 1
y2lab_align: 0.5
y2lab_offset: 1
y2lab_size: 1
y2lab_weight: 1
y2lim: []
y2tlab_horiz: 0.5
y2tlab_orient: 1
y2tlab_perp: 1
y2tlab_size: 1.0
yaxis_1: test y_label
yaxis_2: ''
ylab_align: 0.5
ylab_offset: -2
ylab_size: 1
ylab_weight: 1
ylim: []
ytlab_horiz: 0.5
ytlab_orient: 1
ytlab_perp: 0.5
ytlab_size: 1
In the default config file, logging is set to stdout and the log level is ERROR (i.e. any 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.
2.3.2. Custom Configuration File
A second, mandatory configuration file is required, which is used to customize the settings to the line plot. The custom_line.yaml file is included with the source code. If the user wishes to use all the default settings defined in the line_defaults.yaml file, an empty custom configuration file can be specified instead.
alpha: 0.05
box_avg: 'False'
box_boxwex: 0.2
box_notch: 'False'
box_outline: 'True'
box_pts: 'False'
caption_align: 0.0
caption_col: '#333333'
caption_offset: 3.0
caption_size: 0.8
caption_weight: 1
cex: 1
colors:
- '#ff0000'
- '#55ff00'
- '#00aaff'
- '#0040ff'
- '#c3ff00'
con_series:
- 1
- 1
- 1
- 1
- 1
create_html: 'False'
derived_series_1:
- - CONTROL RH MAE
- GTS RH MAE
- DIFF
derived_series_2: []
dump_points_1: 'False'
dump_points_2: 'False'
event_equal: 'True'
fcst_var_val_1:
RH:
- MAE
fcst_var_val_2:
TMP:
- ME
fixed_vars_vals_input:
fcst_lev:
fcst_lev_0:
- Z02
grid_col: '#cccccc'
grid_lty: 3
grid_lwd: 1
grid_on: 'True'
grid_x: listX
indy_label:
- '6'
- '12'
- '18'
indy_stagger_1: 'True'
indy_stagger_2: 'False'
indy_vals:
- '60000'
- '120000'
- '180000'
indy_var: fcst_lead
legend_box: o
legend_inset:
x: 0.0
y: -0.25
legend_ncol: 3
legend_size: 0.8
line_type: None
list_stat_1:
- MAE
list_stat_2:
- ME
list_static_val:
fcst_var: ME
mar:
- 8
- 4
- 5
- 4
method: bca
mgp:
- 1
- 1
- 0
num_iterations: 1
num_threads: -1
plot_caption: Caption
plot_ci:
- std
- std
- std
- std
- std
plot_disp:
- 'True'
- 'True'
- 'True'
- 'True'
- 'True'
plot_filename: ./line.png
plot_height: 8.5
plot_res: 72
plot_stat: median
plot_type: png16m
plot_units: in
plot_width: 11.0
# Optional, uncomment and set to directory to store the .points1 file
# that is used by METviewer (created when dump_points_1 is set to True)
# if dump_points_1 is True and this is uncommented, the points1 file
# will be saved in the default location (i.e. where the input data file is stored).
#points_path: /dir_to_save_points1_file
random_seed: null
series_line_style:
- '-'
- '-'
- '-'
- '-'
- '-'
series_line_width:
- 1
- 1
- 1
- 1
- 1
series_order:
- 1
- 2
- 3
- 4
- 5
series_symbols:
- .
- .
- .
- .
- .
series_type:
- b
- b
- b
- b
- b
series_val_1:
model:
- CONTROL
- GTS
series_val_2:
model:
- CONTROL
- GTS
show_nstats: 'True'
show_signif:
- 'False'
- 'False'
- 'False'
- 'False'
- 'False'
stat_input: ./line.data
sync_yaxes: 'False'
title: test title
title_align: 0.5
title_offset: -2
title_size: 1.4
title_weight: 2.0
user_legend: []
variance_inflation_factor: 'False'
vert_plot: 'False'
x2lab_align: 0.5
x2lab_offset: -0.5
x2lab_size: 0.8
x2lab_weight: 1
x2tlab_horiz: 0.5
x2tlab_orient: 1
x2tlab_perp: 1
x2tlab_size: 0.8
xaxis: test x_label
xaxis_reverse: 'False'
xlab_align: 0.5
xlab_offset: 2
xlab_size: 1
xlab_weight: 1
xlim: []
xtlab_decim: 0
xtlab_horiz: 0.5
xtlab_orient: 1
xtlab_perp: -0.75
xtlab_size: 1
y2lab_align: 0.5
y2lab_offset: 1
y2lab_size: 1
y2lab_weight: 1
y2lim: []
y2tlab_horiz: 0.5
y2tlab_orient: 1
y2tlab_perp: 1
y2tlab_size: 1.0
yaxis_1: test y_label
yaxis_2: ''
ylab_align: 0.5
ylab_offset: -2
ylab_size: 1
ylab_weight: 1
ylim: []
ytlab_horiz: 0.5
ytlab_orient: 1
ytlab_perp: 0.5
ytlab_size: 1
lines:
- color: '#8000ff'
line_width: '2'
position: '11'
type: horiz_line
line_style: '--'
- line_style: '-'
color: '#000000'
line_width: 1
position: "18"
type: vert_line
# 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: ./line.log
# To change the log level, specify a log level: debug, info, warning, error and uncomment the line below.
# Debug and info log level 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/line/custom_line.yaml $WORKING_DIR/custom_line.yaml
Modify the stat_input setting in the $METPLOTPY_BASE/test/line/custom_line.yaml file to explicitly point to the $METPLOTPY_BASE/test/line directory (where the custom config files and sample data reside). Replace the relative path ./line.data with the full path $METPLOTPY_BASE/test/line/line.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/line/line.data
plot_filename: /username/working_dir/output_plots/line.png
This is where /username/myworkspace/METplotpy corresponds to $METPLOTPY_BASE and /username/working_dir corresponds to $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/line_defaults.yaml configuration file will be used.
To save the intermediate .points1 file (used by METviewer and is useful for debugging but not required), set the dump_points_1 setting to True. Uncomment or add (if it doesn’t exist) the points_path setting.
dump_points_1: ‘True’
points_path: ‘/dir_to_save_points1_file’
Replace the /dir_to_save_points1_file to the same directory where the .points1 file is saved. If points_path is commented out (indicated by a ‘#’ symbol in front of it), remove the ‘#’ symbol to uncomment the points_path so that it will be used by the code. Make sure that this directory exists and has the appropriate read and write permissions. NOTE: the points_path setting is optional and does not need to be defined in the configuration file unless saving the intermediate .points1 file is desired.
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).
2.3.3. Using Defaults
To use the default settings defined in the line_defaults.yaml file, specify a minimal custom configuration file (minimal_line.yaml), which consists of only a comment block, but can be any empty file (if the user has write permissions for the output filename path corresponding to the plot_filename setting in the default configuration file. Otherwise the user will need to specify a plot_filename in the minimal_line.yaml file):
# minimal config file
# leave "empty" to use all the settings in the line_default.yaml
# as long as you have write permissions for the directory specified in the `plot_filename`
# setting.
#Otherwise, specify an appropriate plot_filename setting here (below this comment block)
Copy this file to the working directory:
cp $METPLOTPY_BASE/test/line/minimal_line.yaml $WORKING_DIR/minimal_line.yaml
Add the stat_input (input data) and plot_filename (output file/plot path) settings to the $WORKING_DIR/minimal_line.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/line/line.data and set the plot_filename to $WORKING_DIR/output_plots/line_default.png (making sure to replace environment variables with their actual values):
stat_input: $METPLOTPY_BASE/test/line/line.data
plot_filename: $WORKING_DIR/output_plots/line_default.png
$WORKING_DIR is the working directory where all the custom configuration files are being saved. NOTE: If the plot_filename (output directory) is specified to a directory other than the $WORKING_DIR/output_plots, the user must have read and write permissions to that directory.
NOTE: This default plot does not display any of the data points. It is to be used as a template for setting up margins, captions, label sizes, etc.
2.4. Run from the Command Line
The custom_line.yaml configuration file, in combination with the line_defaults.yaml configuration file, generate a plot of five series:
To generate the above plot using the line_defaults.yaml and custom_line.yaml config files, perform the following:
If using the conda environment, verify the conda environment is running and 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
Recall that $METPLOTPY_BASE is the directory path indicating where the METplotpy source code was saved.
To generate the above “custom” plot (i.e using some custom configuration settings), use the custom configuration file, custom_line.yaml.
Enter the following command:
python $METPLOTPY_BASE/metplotpy/plots/line/line.py $WORKING_DIR/custom_line.yaml
A line.png output file will be created in the directory specified in the plot_filename configuration setting in the line.yaml config file.
To generate the “defaults” plot below (i.e using default configuration settings), use the “minimal” custom configuration file, minimal_line.yaml.
Enter the following command:
python $METPLOTPY_BASE/metplotpy/plots/line/line.py $WORKING_DIR/minimal_line.yaml
A line_default.png output file will be created in the directory specified in the plot_filename configuration setting in the line_defaults.yaml config file.
NOTE: This default plot does not display any of the data points. It is to be used as a template for setting up margins, captions, label sizes, etc.