University of FloridaDepartment of Agricultural & Biological Engineering

 

Morris SU (Sampling Uniformity) code

 

Download the Matlab code, sample inputs and documentation:

Description

EE_SensitivityMeasures_Package is a set of Matlab functions that calculates sensitivity measures for the method of Elementary Effects/Morris method (Morris, 1991). Function ‘EE_SenMea_Calc.m’ is the main function that user needs to call from MATLAB commandline. Calculated measures include modified sensitivity measures - μ* and σ (based on (Campolongo et al. 2007) and original measure μ proposed by Morris (1991).

Program Usage & Output

Syntax
EE_SenMea_Calc ('Example_Sample.xlsx','Example_SampleChar.txt','Example_Output.xlsx')

Inputs:
(1) Fac_Sam_File: This is an ExcelTM '*.xlsx' file containing factor/parameter samples. This file is generated by SU Fac_Sampler package for factor sample generation.

(2) Fac_Sam_Char: This is a text '*.txt' file which contains following information
     (a) Sampling Strategy (line 1)
     (b) Over Sampling Size (line 2)
     (c) Number of factor levels (line 3)
     (d) Number of trajectories (line 4)
     (e) Number of factors (line 5)
This file is generated along with ‘Factor_Sample.xlsx’ file by Factor_Sampler_Mapper package for factor sample generation

(3) Mod_Out_File: This is an ExcelTM '*.xlsx' file containing model outputs arranged column-wise. Output names should be specified in the first row. Currently this code can analyze only scalar outputs. In future provisions will be made for the time series outputs.

Outputs:
(1) EE_SA_Measures.txt: Sensitivity measures based on the method of Elementary Effects/ Morris method are saved in this text file, for each model output.

(2) Plots: Two figures/subplots are produced for each model output. The first subplot is a plot of μ* vs σ while the second one consists of μ vs σ. We additionally plot 1:1 line (in blue color) and μ* = 2 σ/sqrt(r) line (in red) in the first subplot. In the second subplot μ = +/- 2σ/sqrt(r) lines are plotted (red colour). μ = +/-2 σ/sqrt(r) lines were proposed by Morris (1991) to identify factor with dominant non-additive/non-linear effects. Plots are automatically saved as PDF files in the working directory.

Folder Structure:

This package consists of 3 Matlab functions (i.e. m files namely (a) EE_SenMea_Calc, (b) EE_Plots and (c) Morris_Measure_Groups, respectively) saved in folder ‘EE_SensitivityMeasures’. Output files – ‘EE_SA_Measures.txt’ and plots (PDFs) will be saved in the package folder.

Input/Output Example

Example 1                                                 

Let model ‘EXAMPLE’ be a 10 parameter model (called P1, P2, …, P10). First 3 parameters have unit normal distribution, P4 to P7 have uniform distributions in [0,1], and P8 to P10 have LogNormal distributions with mean = 0 and std. = 1. EXAMPLE has three outputs Y1, Y2, and Y3 as follows,

 

 

 

Sample file was generated using EE_Sampler_Mapper package with SU sampling strategy, NumTraj = 10, NumLev = 4, and OverSamSiz = 300. Sample file was renamed ‘Example_Sample’ while FacSamChar file was renamed ‘Example_SampleChar’. EXAMPLE was run using external source and Y1, Y2, and Y3 were saved to ‘Example_Output.xlsx’. All three files were then copied to EE_SensitivityMeasures package.

To calculate EE sensitivity measures for EAMPLE outputs execute EE_SenMea_Calc function from the Matlab command window with the following syntax (also shown in Figure 1).

EE_SenMea_Calc (‘Example_Sample.xlsx’,’Example_SampleChar.txt’,’Example_Output.xlsx’)

 

Figure 1

 This will produce three figures as shown in Figure 2. They are also saved in PDF format in EE_SensitivityMeasures_Package.

Figure 2

 Sensitivity measures will be written to ‘EE_SA_Measures.txt’ (Figure 3) and saved in EE_SensitivityMeasures_Package

Figure 3

Program License

This package is developed by Dr. Khare under the doctoral advising of Dr. Muñoz-Carpena. The Matlab function that calculates elementary effects ‘Morris_Measure_Groups’ was adopted from by the Joint Research Center EU and is available as a free download at http://ipsc.jrc.ec.europa.eu/index.php?id=756

We highly encourage to use this package for the EE sensitivity measures calculations along with EE Sampler Mapper package for the sample generation for EE [especially using Sampling for Uniformity strategy (Khare et al., 2015)]. If you use this package, kindly acknowledge our effort. Also, if you have any question in usage of this package, please contact us on the above email address.

This program is distributed as Freeware/Public Domain under the terms of GNU-License. If the program is found useful the authors ask that acknowledgment is given to its use in any resulting publication and the authors notified. The source code is available from the authors upon request:

© Copyright 2014  Yogesh Khare & Rafael Muñoz-Carpena


Return to top

References

  • Khare, Y.P.*, Muñoz-Carpena, R., Rooney, R.W., Martinez, C.J. A multi-criteria trajectory-based parameter sampling strategy for the screening method of elementary effects. Environmental Modelling & Software 64:230-239. doi:10.1016/j.envsoft.2014.11.013.

Return to top

This page was last updated on February 29, 2016.