Sensitivity Analysis Library (SALib)
====================================

Python implementations of commonly used sensitivity analysis methods.
Useful in systems modeling to calculate the effects of model inputs or
exogenous factors on outputs of interest.

**Documentation:** `ReadTheDocs <http://salib.readthedocs.org>`__

**Requirements:** `NumPy <http://www.numpy.org/>`__,
`SciPy <http://www.scipy.org/>`__,
`matplotlib <http://matplotlib.org/>`__,
`pandas <http://https://pandas.pydata.org/>`__,
Python 3 (from SALib v1.2 onwards SALib does not officially support Python 2)

**Installation:** ``pip install SALib`` or ``pip install .`` or ``conda install SALib``

**Build Status:** |Build Status| **Test Coverage:** |Coverage Status|

Included methods
----------------

* Sobol Sensitivity Analysis (`Sobol 2001 <http://www.sciencedirect.com/science/article/pii/S0378475400002706>`__,
  `Saltelli 2002 <http://www.sciencedirect.com/science/article/pii/S0010465502002801>`__,
  `Saltelli et al. 2010 <http://www.sciencedirect.com/science/article/pii/S0010465509003087>`__)

* Method of Morris, including groups and optimal trajectories (`Morris
  1991 <http://www.tandfonline.com/doi/abs/10.1080/00401706.1991.10484804>`__,
  `Campolongo et al. 2007 <http://www.sciencedirect.com/science/article/pii/S1364815206002805>`__,
  `Ruano et al. 2012 <https://doi.org/10.1016/j.envsoft.2012.03.008>`__)

* extended Fourier Amplitude Sensitivity Test (eFAST) (`Cukier et al. 1973 <http://scitation.aip.org/content/aip/journal/jcp/59/8/10.1063/1.1680571>`__,
  `Saltelli et al. 1999 <http://amstat.tandfonline.com/doi/abs/10.1080/00401706.1999.10485594>`__, `Pujol (2006) in Iooss et al., (2021) <http://scitation.aip.org/content/aip/journal/jcp/59/8/10.1063/1.1680571>`__)

* Random Balance Designs - Fourier Amplitude Sensitivity Test (RBD-FAST) (`Tarantola et al. 2006 <https://hal.archives-ouvertes.fr/hal-01065897/file/Tarantola06RESS_HAL.pdf>`__,
  `Plischke 2010 <https://doi.org/10.1016/j.ress.2009.11.005>`__,
  `Tissot et al. 2012 <https://doi.org/10.1016/j.ress.2012.06.010>`__)

* Delta
  Moment-Independent Measure (`Borgonovo 2007 <http://www.sciencedirect.com/science/article/pii/S0951832006000883>`__,
  `Plischke et al. 2013 <http://www.sciencedirect.com/science/article/pii/S0377221712008995>`__)

* Derivative-based Global Sensitivity Measure (DGSM) (`Sobol and
  Kucherenko 2009 <http://www.sciencedirect.com/science/article/pii/S0378475409000354>`__)

* Fractional Factorial Sensitivity Analysis
  (`Saltelli et al. 2008 <http://www.wiley.com/WileyCDA/WileyTitle/productCd-0470059974.html>`__)

* High-Dimensional Model Representation (HDMR)
  (`Rabitz et al. 1999 <https://doi.org/10.1016/S0010-4655(98)00152-0>`__, `Li et al. 2010 <https://doi.org/10.1021/jp9096919>`__)

* PAWN (`Pianosi and Wagener 2018 <10.1016/j.envsoft.2018.07.019>`__, `Pianosi and Wagener 2015 <https://doi.org/10.1016/j.envsoft.2015.01.004>`__)


**Contributing:** see `here <CONTRIBUTING.md>`__

Quick Start
-----------

Procedural approach
~~~~~~~~~~~~~~~~~~~

.. code:: python

    from SALib.sample import saltelli
    from SALib.analyze import sobol
    from SALib.test_functions import Ishigami
    import numpy as np

    problem = {
      'num_vars': 3,
      'names': ['x1', 'x2', 'x3'],
      'bounds': [[-np.pi, np.pi]]*3
    }

    # Generate samples
    param_values = saltelli.sample(problem, 1024)

    # Run model (example)
    Y = Ishigami.evaluate(param_values)

    # Perform analysis
    Si = sobol.analyze(problem, Y, print_to_console=True)
    # Returns a dictionary with keys 'S1', 'S1_conf', 'ST', and 'ST_conf'
    # (first and total-order indices with bootstrap confidence intervals)

It's also possible to specify the parameter bounds in a file with 3
columns:

::

    # name lower_bound upper_bound
    P1 0.0 1.0
    P2 0.0 5.0
    ...etc.

Then the ``problem`` dictionary above can be created from the
``read_param_file`` function:

.. code:: python

    from SALib.util import read_param_file
    problem = read_param_file('/path/to/file.txt')
    # ... same as above

Lots of other options are included for parameter files, as well as a
command-line interface. See the `advanced
section in the documentation <https://salib.readthedocs.io/en/latest/advanced.html>`__.


Method chaining approach
~~~~~~~~~~~~~~~~~~~~~~~~

Chaining calls is supported from SALib v1.4

.. code:: python

    from SALib import ProblemSpec
    from SALib.test_functions import Ishigami

    import numpy as np


    # By convention, we assign to "sp" (for "SALib Problem")
    sp = ProblemSpec({
      'names': ['x1', 'x2', 'x3'],   # Name of each parameter
      'bounds': [[-np.pi, np.pi]]*3,  # bounds of each parameter
      'outputs': ['Y']               # name of outputs in expected order
    })

    (sp.sample_saltelli(1024, calc_second_order=True)
       .evaluate(Ishigami.evaluate)
       .analyze_sobol(print_to_console=True))

    print(sp)

    # Samples, model results and analyses can be extracted:
    print(sp.samples)
    print(sp.results)
    print(sp.analysis)

    # Basic plotting functionality is also provided
    sp.plot()


The above is equivalent to the procedural approach shown previously.

Also check out the `FAQ <https://github.com/SALib/SALib/tree/main/FAQ.MD>`__ and
`examples <https://github.com/SALib/SALib/tree/main/examples>`__ for a
full description of options for each method.


How to cite SALib
-----------------

If you would like to use our software, please cite it using the following:

    Iwanaga, T., Usher, W., & Herman, J. (2022).
    Toward SALib 2.0: Advancing the accessibility and interpretability of global sensitivity analyses.
    Socio-Environmental Systems Modelling, 4, 18155.
    doi:10.18174/sesmo.18155

    Herman, J. and Usher, W. (2017) SALib: An open-source Python library for
    sensitivity analysis. Journal of Open Source Software, 2(9).
    doi:10.21105/joss.00097

|paper status|

If you use BibTeX, cite using the following entries::

    @article{Iwanaga2022,
      title = {Toward {SALib} 2.0: {Advancing} the accessibility and interpretability of global sensitivity analyses},
      volume = {4},
      url = {https://sesmo.org/article/view/18155},
      doi = {10.18174/sesmo.18155},
      journal = {Socio-Environmental Systems Modelling},
      author = {Iwanaga, Takuya and Usher, William and Herman, Jonathan},
      month = may,
      year = {2022},
      pages = {18155},
    }

    @article{Herman2017,
      doi = {10.21105/joss.00097},
      url = {https://doi.org/10.21105/joss.00097},
      year  = {2017},
      month = {jan},
      publisher = {The Open Journal},
      volume = {2},
      number = {9},
      author = {Jon Herman and Will Usher},
      title = {{SALib}: An open-source Python library for Sensitivity Analysis},
      journal = {The Journal of Open Source Software}
    }


Projects that use SALib
-----------------------

Many projects now use the Global Sensitivity Analysis features provided by
SALib. Here is a selection:

Software
~~~~~~~~

* `The City Energy Analyst <https://github.com/architecture-building-systems/CEAforArcGIS>`_
* `pynoddy <https://github.com/flohorovicic/pynoddy>`_
* `savvy <https://github.com/houghb/savvy>`_
* `rhodium <https://github.com/Project-Platypus/Rhodium>`_
* `pySur <https://github.com/MastenSpace/pysur>`_
* `EMA workbench <https://github.com/quaquel/EMAworkbench>`_
* `Brain/Circulation Model Developer <https://github.com/bcmd/BCMD>`_
* `DAE Tools <http://daetools.com/>`_
* `agentpy <https://github.com/JoelForamitti/agentpy>`_
* `uncertainpy <https://github.com/simetenn/uncertainpy>`_
* `CLIMADA <https://github.com/CLIMADA-project/climada_python>`_

Blogs
~~~~~

* `Sensitivity Analyis in Python <http://www.perrygeo.com/sensitivity-analysis-in-python.html>`_
* `Sensitivity Analysis with SALib <http://keyboardscientist.weebly.com/blog/sensitivity-analysis-with-salib>`_
* `Running Sobol using SALib <https://waterprogramming.wordpress.com/2013/08/05/running-sobol-sensitivity-analysis-using-salib/>`_
* `Extensions of SALib for more complex sensitivity analyses <https://waterprogramming.wordpress.com/2014/02/11/extensions-of-salib-for-more-complex-sensitivity-analyses/>`_

Videos
~~~~~~

* `PyData Presentation on SALib <https://youtu.be/gkR_lz5OptU>`_

If you would like to be added to this list, please submit a pull request,
or create an issue.

Many thanks for using SALib.


How to contribute
-----------------

See `here <CONTRIBUTING.md>`__ for how to contribute to SALib.


License
-------

Copyright (C) 2012-2019 Jon Herman, Will Usher, and others. Versions v0.5 and
later are released under the `MIT license <LICENSE.md>`__.

.. |Build Status| image:: https://travis-ci.com/SALib/SALib.svg?branch=master
   :target: https://travis-ci.com/SALib/SALib
.. |Coverage Status| image:: https://img.shields.io/coveralls/SALib/SALib.svg
   :target: https://coveralls.io/r/SALib/SALib
.. |Code Issues| image:: https://www.quantifiedcode.com/api/v1/project/ed62e70f899e4ec8af4ea6b2212d4b30/badge.svg
   :target: https://www.quantifiedcode.com/app/project/ed62e70f899e4ec8af4ea6b2212d4b30
.. |paper status| image:: http://joss.theoj.org/papers/431262803744581c1d4b6a95892d3343/status.svg
   :target: http://joss.theoj.org/papers/431262803744581c1d4b6a95892d3343
