*This post was updated on January 16, 2015 to correct a few errors and update the SALib module structure, and again in 2017.*

The Sensitivity Analysis Library (SALib) is an open-source Python library for common sensitivity analysis routines, including the Sobol, Morris, and FAST methods. In 2017 it was published in the Journal of Open Source Software:

This post describes how to use the command-line interface of the library to run the Method of Morris (also known as the Elementary Effects Method). The Github page gives an example of the Python interface. The default use case for SALib is to perform decoupled sensitivity analysis, i.e. the sampling and analysis steps are performed separately, and the model evaluations that occur in between are left to the user.

**Step 0: Get the library**

The easiest approach is to `pip install SALib`

, which will pull the latest version from the Python package index. Or, you can download at the above link as a zip/tar file and run `python setup.py install`

. If you’re interested in contributing, you can clone the git repository:

git clone https://github.com/SALib/SALib .

**Step 1: Choose sampling bounds for your parameters**

Create a simple text file with the form `[parameter] [lower bound] [upper bound]`. For example, such a file for the “Sobol G” test function might look like this:

x1 0.0 1.0 x2 0.0 1.0 x3 0.0 1.0 x4 0.0 1.0 x5 0.0 1.0 x6 0.0 1.0 x7 0.0 1.0 x8 0.0 1.0

The bounds are used to sample parameter values. The variable names will only appear in the printed output, and they will not affect the method itself. Let’s call this file `params.txt`.

**Step 2: Generate parameter sets**

Put your `params.txt` file in the same directory as the SALib folder. Move to this directory and type the following command:

python -m SALib.sample.morris -n 1000 -p params.txt -o my_samples_file.txt

The -n flag specifies the number of trajectories to generate. The -p flag specifies the parameter bounds file that you created in the first step. Finally, the -o flag tells the program where to output the matrix of parameter samples. A total of `N(p+1)` samples will be generated; in this case, `N = 1000` and `p = 8`, leading to a total of 9000 model evaluations.

The sampling command also has two options that aren’t required, `--num-levels` and `--grid-jump`. By default, these are set to 4 and 2, respectively.

**Step 3: Run the parameter sets through your model**

The parameter sets are now saved in `my_samples_file.txt`. Run these parameter sets through your model, and save the output(s) to a text file. The output file should contain one row of output values for each model run. This process is performed outside of SALib, so the details will be language-specific. Be careful to read in your parameter sets in the same order they were sampled.

**Step 4: Calculate Morris Indices**

You now have the output values for all of your model runs saved to a file. For the sake of example, let’s call that file `SGOutput.txt` (the output from the Sobol G function). We need to send this information back to SALib to compute the sensitivity indices, using following command:

python -m SALib.analyze.morris -p params.txt -X my_samples_file.txt -Y SGOutput.txt -c 0

The options here are: the parameter file (-p), the file containing calculated outputs (-Y), and the column of the objective values file to read (-c). The columns are assumed to be zero-indexed; if you have calculated multiple objective values, you would continue on to `-m 1`, etc., repeating the same command as above. By default, this will print sensitivity indices to the command line. You may want to print them to a file using the “>” operator.

**Step 5: Interpret your results**

Say that you saved the indices from the above command into the file `morrisIndices.txt`. If you open this file in a text editor, it will look something like this:

Parameter Mu Sigma Mu_Star x1 0.040674 2.573977 2.077549 x2 -0.113902 1.514879 1.109394 x3 -0.025667 0.620538 0.454424 x4 -0.001532 0.324167 0.229770 x5 -0.001736 0.032333 0.023077 x6 -0.000858 0.032265 0.022693 x7 -0.000976 0.032779 0.022949 x8 -0.000224 0.034278 0.024575

The parameter names will match the ones you specified in `params.txt`. The mean and variance of each parameter’s elementary effects are given by `mu` and `sigma`, respectively. `Mu_star` is the mean of the absolute values of the elementary effects, following Campolongo et al. (2007). This `Mu_star` value is the best approximation of “total” sensitivity provided by the Morris method. Note that these indices do not have a direct interpretation as an “attribution of variance”, like we saw in the example results from the Sobol method. Instead, they should be used to understand the ranking of the most sensitive parameters, and to provide an approximate quantification of sensitivity.

For a full description of available methods and options, please consult the readme in the Github repository or on the SALib website. Github users can also post issues or submit pull requests. Thanks for reading!

Hi Jon,

Is it OK to set –num-levels and –grid-jump to deafualt values (4 and 2 ), even if the sampling size, “N” and number of parameter, “P” are very large?

Suraj

Hi Suraj, good question. These defaults have done reasonably well for the problems I’ve worked with. I’d guess that changing the number of parameters (P) shouldn’t matter too much, since the defaults represent a coarse sampling that can scale to higher dimensions.

If you are running a very large sample size (N), you may be able to increase num_levels to get a more diverse set of sample points. Note that Morris’s recommendation is to set grid_jump equal to num_levels/2.

Thanks Jon!

This blog is very helpful for my research. I followed this blog for doing my sensitivity (sobol) analysis and optimization (Borg).

if I give a negative range like -4 to -0.4 the example is crashing ..can you please suggest what could be wrong..also how can i control the sampled values,that is i don’t want decimal points,but integers

Thank you Professor Herman for the informative blog post.

Just to understand if value of Mu_star is more, than the corresponding parameter will be more sensitivity? In above example, is the x1 more sensitive compared to x5 variable?

Is this sensitivity meant, varying x1, vary output more compare to varying x5 of same degree? What if x1 and x5 are not of the same scale or of different units?

Hi aviruch,

Yes, that is the right interpretation of the sensitivity indices. Varying x1 results in more change in the output than varying x5.

If the x’s have different orders of magnitude, there may be an effect on the results. But this just means they influence the output more, which makes sense. All of the code is on github, so you can read how the elementary effects are calculated here:

https://github.com/SALib/SALib/blob/master/SALib/analyze/morris.py#L204

Pingback: Water Programming Blog Guide (Part I) – Water Programming: A Collaborative Research Blog

Thank you professor Herman for your blog post. I have still some questions.

The cost of computation is N(k+1). If the sampling is trajectory design, the number of trajectories(r) must be chosed instead of sample size. I am a bit confused regarding N (sample size) and r (trajectory). Can a random sample size of 1000 be chosen but the independent drawn samples out of these 1000 be 8 ?

My other question is regarding the bounds. Must the input range be in the interval (0:1)?

Hi Maryam,

– Yes, the total number of samples is N(k+1). k is the number of parameters, and N is the number of trajectories. See the function description here:

https://github.com/SALib/SALib/blob/master/SALib/sample/morris/__init__.py#L68

– The input range can be specified with any upper and lower bounds, it does not have to be [0,1]. See the example on the README page:

https://github.com/SALib/SALib

-Jon

Thank you Prof. Herman!