Using the Matlab script dataplot.m

There is a useful Matlab script called dataplot.m that is used to create plots for the various CFAST and FDS manuals. It is highly recommended that you use this script when making plots for the Verification or Validation Guides because it has built in tolerance checking and it works with another Matlab script called scatplot.m to create scatter plots like those in the CFAST and FDS Validation Guides.

The advantage of dataplot.m is that all the fonts, line widths, etc., are handled automatically. To make a plot via dataplot, you must add a line to the spreadsheet FDS_validation_dataplot_inputs.csv, FDS_verification_dataplot_inputs.csv, or the analogous CFAST spreadsheets.

To best understand all of the columns in the file FDS_validation_dataplot_inputs.csv, just use an existing line as an example. Each line names the experimental data file, the CFAST or FDS output file, and the various plot parameters. A short explanation of the columns is listed below.

The key is to note the column where the plot will be saved. It will be saved in the Manuals directory, NOT the Validation or Verification directory. For validation cases, the plot should be printed to Manuals/FDS_Validation_Guide/SCRIPT_FIGURES/[Series Name]/plotname.pdf. For verification cases, the plot should be printed to Manuals/FDS_Verification_Guide/SCRIPT_FIGURES/plotname.pdf or to Manuals/FDS_User_Guide/SCRIPT_FIGURES/plotname.pdf. Note: DO NOT COMMIT THE PDF PLOTS TO THE fds or cfast repository. They are generated automatically by scripts that run each night.

Plots that may change when the code is modified are stored in SCRIPT_FIGURES. Other images that are needed in the guides are permanently archived in the FIGURES directory.

Each line of the FDS_validation_dataplot_inputs.csv or FDS_verification_dataplot_inputs.csv file produces a single plot with one or more pairs of curves that are to be compared. The difference between each pair of curves produces a single point on a single scatter plot for the given output quantity of interest. Following is a brief explanation of the columns in the dataplot input file.

switch_id

Code that indicates whether the row is to skipped (s), processed (d), or is a follow-up to the previous row (f).

Dataname

A text string that would appear in the legend of the scatter plots. This is typically the name of the set of experiments. This text string is important if you want to run dataplot.m for only this set of experiments. To do this, edit FDS_validation_script.m or CFAST_validation_script.m and change the following line:

[saved_data,drange] = dataplot(Dataplot_Inputs_File, Working_Dir, Working_Dir, Manuals_Dir);

to this:

[saved_data,drange] = dataplot(Dataplot_Inputs_File, Working_Dir, Working_Dir, Manuals_Dir, `My experiments`);

d1_Filename

Name of the file where the experimental data is stored.

d1_Col_Name_Row

Row number in the experimental data file where the column names are listed.

d1_Data_Row

Row number in the experimental data file where the data values start.

d1_Ind_Col_Name

Column name of the independent variable for the plot.

d1_Dep_Col_Name

Column name of the dependent variable for the plot.

d1_Key

Text string for the experimental data in the plot legend.

If the switch_id is f, meaning that the current row is a continuation of the row above, and the experimental data for this row has already been invoked on the previous row, then put the word blank in this field. This tells dataplot that it does not need to add an entry in the legend for this plot. It is redundant.

d1_Style

Matlab symbol indicating the style of the plot curve for the experimental data.

If the switch_id is f, meaning that the current row is a continuation of the row above, and the experimental data for this row has already been invoked on the previous row, then put the word blank in this field. This tells dataplot that it does not need to plot this curve. It is redundant.

d1_Start and d1_End

Time to start and stop plotting the experimental curve.

d1_Tick

Rarely used, leave blank.

d1_Comp_Start and d1_Comp_End

Time to start and stop compiling accuracy statistics for experimental data. Typically these are set so that all the data is included.

d1_Dep_Comp_Start and d1_Dep_Comp_End

These two parameters limit the range of the dependent variable over which the chosen metric is applied. These can be useful, for example, if you are taking the slope of the time history, in which case you might want to limit the bounds of both the independent and dependent variables.

d1_Initial_Value

The initial value of the experimental data, usually 0.

d2_Filename

Name of the CFAST or FDS output file.

d2_Col_Name_Row

Row number in the output file where the column names are listed.

d2_Data_Row

Row number in the output file where the data values start.

d2_Ind_Col_Name

Column name of the independent variable for the plot.

d2_Dep_Col_Name

Column name of the dependent variable for the plot.

d2_Key

Text string for the output in the plot legend.

If the switch_id is f, meaning that the current row is a continuation of the row above, and the model data for this row has already been invoked on the previous row, then put the word blank in this field. This tells dataplot that it does not need to add an entry in the legend for this plot. It is redundant.

d2_Style

Matlab symbol indicating the style of the plot curve for the CFAST or FDS output.

If the switch_id is f, meaning that the current row is a continuation of the row above, and the model data for this row has already been invoked on the previous row, then put the word blank in this field. This tells dataplot that it does not need to plot this data. It is redundant.

d2_Start and d2_End

Time to start and stop plotting the CFAST or FDS curve.

d2_Tick

Rarely used, leave blank.

d2_Comp_Start and d2_Comp_End

Time to start and stop compiling accuracy statistics for CFAST or FDS output.

d2_Dep_Comp_Start and d2_Dep_Comp_End

These two parameters limit the range of the dependent variable over which the chosen metric is applied. These can be useful, for example, if you are taking the slope of the time history, in which case you might want to limit the bounds of both the independent and dependent variables.

d2_Initial_Value

The initial value of the CFAST or FDS output variable, usually 0. For oxygen concentration, it would typically be 0.21. For HGL depth, it is the room height.

Plot_Title

Text string that appears on the plot.

Ind_Title

Label for independent axis of the plot.

Dep_Title

Label for dependent axis of the plot.

Min_Ind, Max_Ind, Scale_Ind

Minimum, maximum value and scaling factor for independent axis.

Min_Dep, Max_Dep, Scale_Dep

Minimum, maximum value and scaling factor for dependent axis.

Flip_Axis

yes or no as to whether to put the independent variable on the vertical axis.

Title_Position

Relative x,y position of the start of the title string on the plot.

Key_Position

Location of the plot legend, in terms of compass settings.

Legend_XYWidthHeight

Leave blank

Paper_Width_Factor

Usually 1, but larger for cases where the plot legend is placed outside the plot.

VerStr_Filename

Name of the file containing the FDS version string. 0 if no file exists.

Plot_Type

linear, semilogx, semilogy, loglog

Plot_Filename

Name and directory of the PDF plot file.

Quantity

This is the name of the scatter plot that will contain the given comparison point(s). For the validation process, this name has to match exactly the entry in the file called FDS_validation_scatterplot_inputs.csv or CFAST_validation_scatterplot_inputs.csv. For the verification process, this name is either Relative Error or Absolute Error and it indicates how the Error_Tolerance is to be interpreted.

Metric

• all: Compares the values of all points along each curve. This is only appropriate when there are 10 or less points making up the curve.

• area: Compares the value of the area under each curve.

• end: Compares the value of the last point on each curve.

• end_x_y: Compares the value of the last point on each specified curve, where x is the number of the expected curve that you want to compare to curve y of the predicted metric. The values x and y correspond to the order that the curves are listed in the d1_Dep_Col_Name and d2_Dep_Col_Name columns. For example, to compare the end points of curves 1 and 3, you would specify end_1_3.

• max: Compares the maximum (peak) value of each curve.

• mean: Compares the mean value of each curve.

• mean_x_y: Compares the mean value on each specified curve, where x is the number of the expected curve that you want to compare to curve y of the predicted metric. For example, to compare the mean of curves 2 and 2, you would specify mean_2_2.

• min: Compares the minimum value of each curve.

• threshold: Compares the independent value when the dependent value reaches some threshold. For example, to compare the time to threshold temperature for cables, the d1_Comp_Start value is set to the threshold temperature, and then the time at which this temperature is attained is reported.

• tolerance: Compares the dependent absolute value against the tolerance value, the check passes if the value is below the tolerance.

• slope: The slope of the curve within a window bounded by dn_Comp_Start/End and dn_Dep_Comp_Start/End, where n is 1 for the experimental data and 2 for FDS. The slope is determined by a fitting algorithm over all points within the window.

Error_Tolerance

This is not used for validation work. Just put 0. For verification, indicate the desired relative or absolute error.

Group_Key_Label

The name of the test series, as you want it to appear on the validation scatter plots. For verification, this label just indicates the name of the directory where the case resides.

Group_Style

The color and shape of the symbol on the scatter plot. Each test series has a unique identifier. For example, the series ATF Corridors uses ro, a red circle.

Fill_Color

You can opt to fill the symbol defined by Group_Style.