-
Notifications
You must be signed in to change notification settings - Fork 50
Plotting Scripts
A set of functions has been developed to simplify the generation of plots, which are at the heart of making comparisons between the computation results and the experimental data. The functions are written in Python (developed in Python 3.7). If you are new to Python, do not fear, we will go step by step through the process of creating plots.
The first thing you will need is a functioning version of Python with Matplotlib. Therefore, unless you otherwise have a preference, I recommend using pip to manage your Python distribution.
Once installed you should have a working version of Python. Confirm this by opening a command shell and typing:
$ python --version
Python 3.7.4
Note that you may need to add or modify the path in your startup script (Linux, macOS).
There are two easy ways to launch the plotting scripts that I will describe here (there is a third via interactive mode that I will not go into). The first method is simply to invoke Python from the shell command line as follows. First, cd to the directory where the script lives. This should be where your computational results are stored. Then simply type python3 followed by the name of your plotting script. We will use macfp-db/Buoyant_Plumes/Sandia_Helium_Plume/Computational_Results/2021/NIST/ as an example.
$ cd <path to macfp-db>/macfp-db/Buoyant_Plumes/Sandia_Helium_Plume/Computational_Results/2021/NIST/
$ python3 NIST_plot_results.py
We will go into more detail about writing the plotting script later. The script will call a function that reads your configuration file and then generates the plots and saves them in the Plots directory for the case.
The other option, which I use most of the time, is to run an IPython interactive shell. To do this, simply type ipython at the command line.
$ipython
Python 3.7.4 (default, Aug 13 2019, 15:17:50)
Type 'copyright', 'credits' or 'license' for more information
IPython 7.8.0 -- An enhanced Interactive Python. Type '?' for help.
In [1]:
This is very similar to the interactive mode of Python or Matlab, but I find running the scripts to be more intuitive from IPython. To run the plotting script, again, cd to the working directory, then type run and the name of the script.
In [2]: cd <path to macfp-db>/macfp-db/Buoyant_Plumes/Sandia_Helium_Plume/Computational_Results/2021/NIST
In [3]: run NIST_plot_results.py
In [4]:
Note: You need not use the Python plotting utilities to submit computational results to MaCFP. It is sufficient to submit the results in a comma-delimited (*.csv) ACII text file together with a configuration file (discussed below) listing the plots to be made (email them to Randy McDermott). The main purpose behind using the plotting scripts is to test to make sure the results and configuration files are free from errors.
The plotting package is broken up into different levels. You may use any or all, depending on your comfort level with Python and on what level of flexibility you would like in the final product.
The top level function is called dataplot. This function reads a configuration file, which we will discuss below, to make a series of plots. An example configuration file is given here. Generally, a user will write their own Python script to call dataplot. A simple example wrapper script is provided here. This script uses dataplot to read the configuration file. Then, dataplot uses the low-level function plot_to_fig to plot both the experimental data and computational results, as specified in the configuration file.
wrapper script (for example, plot_results.py)
|
|---> loads macfp, matplotlib modules
|---> sets directory structure
|---> calls macfp.dataplot
|
|---> reads configuration file
|---> calls plot_to_fig for experimental data
|---> calls plot_to_fig for computational results
|---> prints figure to a file
-
The macfp.plot_to_fig utility, at present, only works for linear plots (log plots will be added shortly).
-
The general philosophy in setting up the scripts is that you will be comparing computational results against experimental data. Thus, each line of a the configuration file is set to plot Exp vs. Cmp. If you wish to include more than one set of experimental data on a given plot, this is possible, but you need to treat the extra sets of data like computational results. That is, pick one data set to be Exp for all the lines of the configuration file (for that particular plot), then extra datasets can be added and customized as Cmp results. There is an example of this in NIST_Pool_Fires for Methanol_30_cm_HF_radial2.pdf, which plots both the Klassen 1994 and Kim 2019 data on a single plot.
-
Note that the directories expdir, cmpdir, pltdir may be omitted and the paths included in the filenames Exp_Filename and Cmp_Filename. This will be necessary, for example, when we want to make comparisons between various results or experimental data series.
-
Please do not use commas,
,, or quotation marks,"or', for header labels or values in the configuration file. Given that we are reading a "comma delimited" spreadsheet file, this simplifies parsing of the file.
| Parameter | Type | Description |
|---|---|---|
| config_filename | String | (required) comma-delimited ASCII text file with plot parameters; each row represents a separate line plot (x,y), see Configuration File Parameters; to include more than one line on a single plot, on consecutive rows give the same Plot_Filename. |
| Keyword Arguments | Type | Description |
|---|---|---|
| institute | String | (optional) [None] If present, this string is printed at the top-left of the plot axes |
| revision | String | (optional) [None] If present, this string is printed at the top-right of the plot axes |
| configdir | String | (optional) [current directory] Configuration file directory |
| expdir | String | (optional) [current directory] Experimental data directory |
| cmpdir | String | (optional) [current directory] Computational results directory |
| pltdir | String | (optional) [current directory] Plots directory, created if does not exist |
| close_figs | Boolean | (optional) [False] Set to True will close all open figures after each plot is made. This can be used to suppress the warning that Python gives for having more than 20 figures open at one time. |
| verbose | Boolean | (optional) [False] Set to True to print current Plot_Filename while processing. |
| plot_range | Range | (optional) [range(10000)] A Python range type that can be used to slice the dataframe imported by dataplot for a specific range of rows. The start and stop for plot_range should match the rows in your *.csv file, where the header is assumed to be row 1. This is not "Pythonic" but it is much clearer (IMHO) when trying to link dataplot with the configuration file (more of a Matlab philosophy). Example: plot_range=range(20,30). Note that plot_range is much faster than plot_list (next) because it does not have to first read and do string comparisons for the whole configuration file. |
| plot_list | List of Strings | (optional) ['all'] A list of Plot_Filename's. Use this to process individual rows of the configuration file. Example: plot_list=['plot1.pdf','plot2.pdf']
|
Example:
macfp.dataplot(config_filename='NIST_macfp_config.csv',
institute='NIST test',
revision='MaCFP-3, Tsukuba, 2023',
expdir='../../../Experimental_Data/',
pltdir='./Plots/')
Here we give a description of each of the column headings of the configuration file. These headings set the keyword arguments (**kwargs) for plot_to_fig called by dataplot for both the experimental data and computational results. An example configuration file may be found here.
Note: some column headers are required, while others will take on default values if left out of the configuration file. Err on the side of being explicit if you want to control the parameters of the plots.
Note: quotes are not needed for strings (including filenames) within the configuration file. For example, a data label will be given as Exp, instead of "Exp" or 'Exp'. Again, please reference the example here if there is any confusion.
Note: you may comment out a line of the configuration file using a hashtag #.
| Column heading | Description |
|---|---|
| Exp_Filename | (required) Filename of the ASCII *.csv file for the experimental data (excluding path, if expdir is used as a kwarg in dataplot, which is recommended to better organize the config file.) |
| Exp_Header_Row | (optional) [1] Integer value of the row used for column headers in the experimental data file. This may vary (usually 1 or 2) depending on the convention used for placement of units. |
| Exp_Data_Row | (optional) [Exp_Header_Row+1] Integer value of the row used for start of experimental data values. |
| Exp_x_Col_Name | (required) Column header for experimental independent data (x axis). |
| Exp_y_Col_Name | (required) Column header for experimental dependent data (y axis). |
| Exp_y_Error_Col_Name | (optional) [None] Column header for experimental data vertical (y axis) uncertainty bands |
| Exp_Data_Markevery | (optional) [1] If greater than 1, skip data to make plots more legible. |
| Exp_Error_Absolute | (optional) [0.] Absolute data uncertainty range, drawn as transparent band; may be combined with Exp_Error_Relative. Error_Bound = y_data*(1+/-Exp_Error_Relative)+/-Exp_Error_Absolute. |
| Exp_Error_Relative | (optional) [0.] Relative data uncertainty range, drawn as transparent band; may be combined with Exp_Error_Absolute. Error_Bound = y_data*(1+/-Exp_Error_Relative)+/-Exp_Error_Absolute. |
| Exp_Data_Label | (optional) [Exp] Label used in legend for experimental data (quotes not needed for strings). |
| Exp_Marker_Style | (optional) [o] Experimental data marker style. Examples: [leave blank], None, o, ^, ., +, *, etc. Note: If you add the Exp_Marker_Style column to your configuration file, then the default will change to whatever you put in that column; a blank will be treated as None. |
| Exp_Marker_Edge_Color | (optional) [black] Experimental data marker edge color; thickness of edge controlled by Exp_Line_Width below. Examples: black, red, blue, green
|
| Exp_Marker_Fill_Color | (optional) [black] Experimental data marker fill color. Examples: black, red, blue, green
|
| Exp_Marker_Size | (optional) [6] Experimental data marker size. Examples: 0, 1, ..., 10
|
| Exp_Line_Style | (optional) [None] Experimental data line style. Examples: [leave blank], None, -, --, -., :
|
| Exp_Line_Color | (optional) [None] Experimental data line color. Examples: black, red, blue, green
|
| Exp_Line_Width | (optional) [1] Experimental data line width; also controls marker edge thickness. Examples: 0, 1, ..., 10
|
| Cmp_Filename | (required) Filename of the ASCII *.csv file for the computational results |
| Cmp_Header_Row | (optional) [1] Integer value of the row used for column headers in the computational results file. This may vary (usually 1 or 2) depending on the convention used for placement of units. |
| Cmp_Data_Row | (optional) [Cmp_Header_Row+1] Integer value of the row used for start of computational results values. |
| Cmp_x_Col_Name | (required) Column header for computational independent data (x axis). |
| Cmp_y_Col_Name | (required) Column header for computational dependent data (y axis). |
| Cmp_Data_Markevery | (optional) [1] If greater than 1, skip data to make plots more legible. |
| Cmp_Data_Label | (optional) [Cmp] Label used in legend for computational data (quotes not needed for strings). |
| Cmp_Marker_Style | (optional) [None] Computational data marker style. Examples: [leave blank], None, o, ^, ., +, *, etc. |
| Cmp_Marker_Edge_Color | (optional) [None] Computational data marker edge color; thickness of edge controlled by Cmp_Line_Width below. Examples: black, red, blue, green
|
| Cmp_Marker_Fill_Color | (optional) [None] Computational data fill marker color. Examples: black, red, blue, green
|
| Cmp_Marker_Size | (optional) [0] Computational data marker size. Examples: 0, 1, ..., 10
|
| Cmp_Line_Style | (optional) [-] Computational data line style. Examples: [leave blank], None, -, --, -., :
|
| Cmp_Line_Color | (optional) [black] Computational data line color. Examples: black, red, blue, green
|
| Cmp_Line_Width | (optional) [1] Computational data line width; also controls marker edge thickness. Examples: 0, 1, ..., 10
|
| Plot_Title | (optional) [ ] Title of the plot, upper-left corner |
| Plot_Subtitle | (optional) [ ] Subtitle of the plot, below title |
| Plot_x_Label | (optional) [x] x axis label |
| Plot_y_Label | (optional) [y] y axis label |
| Plot_x_Min | (optional) [min(x_data)-5%] Minimum value on x axis |
| Plot_x_Max | (optional) [max(x_data)+5%] Maximum value on x axis |
| Plot_x_Tick | (optional) Tick mark spacing on x axis |
| Plot_x_Nticks | (optional) Number of ticks on x axis (instead of Plot_x_Tick) |
| Plot_y_Min | (optional) [min(y_data)-5%] Minimum value on y axis |
| Plot_y_Max | (optional) [max(y_data)+5%] Maximum value on y axis |
| Plot_y_Tick | (optional) Tick mark spacing on y axis |
| Plot_y_Nticks | (optional) Number of ticks on y axis (instead of Plot_y_Tick) |
| Plot_Left_Adjust | (optional) Float between 0. and 0.95 used to adjust left side of plot if y axis or tick labels are cutoff; suggest about 0.15, if needed |
| Plot_Bottom_Adjust | (optional) Float between 0. and 0.95 used to adjust bottom side of plot if x axis or tick labels are cutoff; suggest about 0.15, if needed |
| Plot_Right_Adjust | (optional) Float between 0. and 0.95 used to adjust right side of plot if when needed for outside legend; suggest about 0.68, if needed |
| Plot_Top_Adjust | (optional) Float between 0. and 0.95 used to adjust top side of plot if when needed |
| Plot_Figure_Width | (optional) [8] Usually only needed for Plot_Legend_Location outside; suggest 12 if needed |
| Plot_Figure_Height | (optional) [6] |
| Plot_Flip_Axis | (optional) boolean: True or [False]; set to True to transpose x and y axes data and labels |
| Plot_Show_Legend | (optional) boolean: [True] or False
|
| Plot_Legend_Location | (optional) [best] See matplotlib.pyplot.legend. Examples: best, upper right, upper left, lower right, lower left, right, center left, center right, lower center, upper center, center,outside. Note: when using outside see Plot_Right_Adjust and Plot_Figure_Width
|
| Plot_Filename | (required) Plot filename (excluding path, if pltdir is used as a kwarg in dataplot, which is recommended to better organize the config file); equivalent to fname in matplotlib.pyplot.savefig; include filename extension. Examples: myplot.pdf, myplot.png
|
This function is a lower level function that uses Matplotlib Pyplot to generate a simple x,y plot and then returns the figure handle. You can then use plt.show() to view the figure and/or plt.save_fig() to save the figure (this is done automatically by dataplot).
| Parameter | Type | Description |
|---|---|---|
| x_data | Numeric | (required) x data read from csv file using pandas.read_csv() |
| y_data | Numeric | (required) y data (same size as x data) read from csv file |
| Keyword Arguments | Type | Description |
|---|---|---|
| data_markevery | Integer | (optional) [1] Skip this number of points when plotting. |
| data_label | String | (optional) [None] Label for data in legend. |
| y_error_absolute | Numeric | (optional) [0.] Absolute error |
| y_error_relative | Numeric | (optional) [0.] Relative error, may be used in place of absolute error |
| y_error_vector | Numeric | (optional) [0.] y data error, must be same size as y_data
|
| x_label | String | (optional) [None] Label for x axis |
| y_label | String | (optional) [None] Label for y axis |
| marker_style | String | (optional) [None] Examples: o, *, +, >, <, ^, v, ., s (square), etc.
|
| marker_edge_color | String | (optional) [black] Examples: black, red, blue, green
|
| marker_fill_color | String | (optional) [None] Examples: black, red, blue, green
|
| marker_size | Integer | (optional) [6] 0, 1, etc. |
| line_style | String | (optional) [None] Examples: -, --, -., :
|
| line_color | String | (optional) [None] Examples: black, red, blue, green
|
| line_width | Integer | (optional) [1] 0, 1, etc. |
| x_min | Numeric | (optional) [None] Minimum value on x axis |
| x_max | Numeric | (optional) [None] Maximum value on x axis |
| n_xticks | Integer | (optional) [None] Number of ticks on x axis |
| y_min | Numeric | (optional) [None] Minimum value on y axis |
| y_max | Numeric | (optional) [None] Maximum value on y axis |
| n_yticks | Integer | (optional) [None] Number of ticks on y axis |
| show_legend | String | (optional) [None] boolean: True or [False] |
| legend_location | String | (optional) [None] Examples: best, upper right, upper left,outside (only outside right available; see figure_right_adjust; apply to all calls to plot_to_fig with the same figure handle) |
| legend_framealpha | Numeric | (optional) [0.8] Alpha (opposite of transparency) of legend background. Change to 1.0 for no transpency. |
| ticklabel_fontsize | Integer | (optional) [16], 24, etc. |
| axeslabel_fontsize | Integer | (optional) [18], 24, etc. |
| title_fontsize | Integer | (optional) [18], 24, etc. |
| subtitle_fontsize | Integer | (optional) [16], 24, etc. |
| legend_fontsize | Integer | (optional) [16], 24, etc. |
| plot_title | String | (optional) [None] Plot title upper left |
| plot_subtitle | String | (optional) [None] Plot subtitle below title |
| institute_label | String | (optional) [None] Stamp upper left above axes |
| figure_size | Numeric Tuple | (optional) [(8,6)] (Width, Height) in inches |
| figure_handle | Integer | (optional) plot to a specific figure |
| figure_left_adjust | Numeric | (optional) 0<x<0.95; use to adjust left if y axis or tick labels are cut off |
| figure_bottom_adjust | Numeric | (optional) 0<x<0.95; use to adjust bottom if x axis or tick labels are cut off |
| figure_right_adjust | Numeric | (optional) 0<x<0.95; use to adjust right with using legend_location='outside'
|
| figure_top_adjust | Numeric | (optional) 0<x<0.95; use to adjust top |