Merge pull request #77 from dhadka/master

Merged Sphinx/ReadTheDocs documentation into SALib

.travis.yml

@@ -6,8 +6,6 @@ python:
 - "3.3"
 
 env: 
- - DEPS="numpy=1.8.0 scipy matplotlib"
- - DEPS="numpy=1.9.0 scipy matplotlib"
  - DEPS="numpy scipy matplotlib"
 
 install:
@@ -36,4 +34,4 @@ script:
 after_success:
  - coveralls
 notifications:
- email: false
+ email: false

README.md

@@ -1,6 +1,8 @@
 ##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.
+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/)
 

SALib/analyze/delta.py

@@ -9,12 +9,47 @@
 from ..util import read_param_file
 
 
-# Perform Delta moment-independent Analysis on file of model results
-# Returns a dictionary with keys 'delta', 'delta_conf', 'S1', and 'S1_conf'
-# Where each entry is a list of size D (the number of parameters)
-# Containing the indices in the same order as the parameter file
 def analyze(problem, X, Y, calc_second_order=True, num_resamples=10,
             conf_level=0.95, print_to_console=False):
+    """Perform Delta Moment-Independent Analysis on model outputs.
+    
+    Returns a dictionary with keys 'delta', 'delta_conf', 'S1', and 'S1_conf',
+    where each entry is a list of size D (the number of parameters) containing
+    the indices in the same order as the parameter file.
+    
+    Parameters
+    ----------
+    problem : dict
+        The problem definition
+    X: numpy.matrix
+        A NumPy matrix containing the model inputs
+    Y : numpy.array
+        A NumPy array containing the model outputs
+    calc_second_order : bool
+        Not used
+    num_resamples : int
+        The number of resamples when computing confidence intervals (default 10)
+    conf_level : float
+        The confidence interval level (default 0.95)
+    print_to_console : bool
+        Print results directly to console (default False)
+        
+    References
+    ----------
+    .. [1] Borgonovo, E. (2007). "A new uncertainty importance measure."
+           Reliability Engineering & System Safety, 92(6):771-784,
+           doi:10.1016/j.ress.2006.04.015.
+           
+    .. [2] Plischke, E., E. Borgonovo, and C. L. Smith (2013). "Global
+           sensitivity measures from given data." European Journal of
+           Operational Research, 226(3):536-550, doi:10.1016/j.ejor.2012.11.047.
+           
+    Examples
+    --------
+    >>> X = latin.sample(problem, 1000)
+    >>> Y = Ishigami.evaluate(X)
+    >>> Si = delta.analyze(problem, X, Y, print_to_console=True)
+    """
 
     D = problem['num_vars']
     N = Y.size

SALib/analyze/dgsm.py

@@ -9,12 +9,37 @@
 from ..util import read_param_file
 
 
-# Calculate DGSM from file of model results
-# Returns a dictionary with keys 'vi', 'vi_std', 'dgsm', and 'dgsm_conf'
-# Where each entry is a list of size D (the number of parameters)
-# Containing the indices in the same order as the parameter file
 def analyze(problem, X, Y, num_resamples=1000,
             conf_level=0.95, print_to_console=False):
+    """Calculates Derivative-based Global Sensitivity Measure on model outputs.
+    
+    Returns a dictionary with keys 'vi', 'vi_std', 'dgsm', and 'dgsm_conf',
+    where each entry is a list of size D (the number of parameters) containing
+    the indices in the same order as the parameter file.
+          
+    Parameters
+    ----------
+    problem : dict
+        The problem definition
+    X : numpy.matrix
+        The NumPy matrix containing the model inputs
+    Y : numpy.array
+        The NumPy array containing the model outputs
+    num_resamples : int
+        The number of resamples used to compute the confidence
+        intervals (default 1000)
+    conf_level : float
+        The confidence interval level (default 0.95)
+    print_to_console : bool
+        Print results directly to console (default False)
+        
+    References
+    ----------
+    .. [1] Sobol, I. M. and S. Kucherenko (2009). "Derivative based global
+           sensitivity measures and their link with global sensitivity
+           indices." Mathematics and Computers in Simulation, 79(10):3009-3017,
+           doi:10.1016/j.matcom.2009.01.023.
+    """
 
     D = problem['num_vars']
 

SALib/analyze/fast.py

@@ -10,11 +10,43 @@
 from ..util import read_param_file
 
 
-# Perform FAST Analysis on file of model results
-# Returns a dictionary with keys 'S1' and 'ST'
-# Where each entry is a list of size D (the number of parameters)
-# Containing the indices in the same order as the parameter file
 def analyze(problem, Y, M=4, print_to_console=False):
+    """Performs the Fourier Amplitude Sensitivity Test (FAST) on model outputs.
+    
+    Returns a dictionary with keys 'S1' and 'ST', where each entry is a list of
+    size D (the number of parameters) containing the indices in the same order
+    as the parameter file.
+    
+    Parameters
+    ----------
+    problem : dict
+        The problem definition
+    Y : numpy.array
+        A NumPy array containing the model outputs
+    M : int
+        The interference parameter, i.e., the number of harmonics to sum in
+        the Fourier series decomposition (default 4)
+    print_to_console : bool
+        Print results directly to console (default False)
+        
+    References
+    ----------
+    .. [1] Cukier, R. I., C. M. Fortuin, K. E. Shuler, A. G. Petschek, and J. H.
+           Schaibly (1973).  "Study of the sensitivity of coupled reaction
+           systems to uncertainties in rate coefficients."  J. Chem. Phys.,
+           59(8):3873-3878, doi:10.1063/1.1680571.
+           
+    .. [2] Saltelli, A., S. Tarantola, and K. P.-S. Chan (1999).  "A
+          Quantitative Model-Independent Method for Global Sensitivity
+          Analysis of Model Output."  Technometrics, 41(1):39-56,
+          doi:10.1080/00401706.1999.10485594.
+          
+    Examples
+    --------
+    >>> X = fast_sampler.sample(problem, 1000)
+    >>> Y = Ishigami.evaluate(X)
+    >>> Si = fast.analyze(problem, Y, print_to_console=False)
+    """
 
     D = problem['num_vars']
 

SALib/analyze/morris.py

@@ -9,16 +9,57 @@
 from ..util import read_param_file
 
 
-# Perform Morris Analysis on file of model results
-# Returns a dictionary with keys 'mu', 'mu_star', 'sigma', and 'mu_star_conf'
-# Where each entry is a list of size num_vars (the number of parameters)
-# Containing the indices in the same order as the parameter file
 def analyze(problem, X, Y,
             num_resamples=1000,
             conf_level=0.95,
             print_to_console=False,
             grid_jump=2,
             num_levels=4):
+    """Perform Morris Analysis on model outputs.
+    
+    Returns a dictionary with keys 'mu', 'mu_star', 'sigma', and 'mu_star_conf',
+    where each entry is a list of size D (the number of parameters) containing
+    the indices in the same order as the parameter file.
+          
+    Parameters
+    ----------
+    problem : dict
+        The problem definition
+    X : numpy.matrix
+        The NumPy matrix containing the model inputs
+    Y : numpy.array
+        The NumPy array containing the model outputs
+    num_resamples : int
+        The number of resamples used to compute the confidence
+        intervals (default 1000)
+    conf_level : float
+        The confidence interval level (default 0.95)
+    print_to_console : bool
+        Print results directly to console (default False)
+    grid_jump : int
+        The grid jump size, must be identical to the value passed
+        to :func:`SALib.sample.morris.sample` (default 2)
+    num_levels : int
+        The number of grid levels, must be identical to the value
+        passed to SALib.sample.morris (default 4)
+        
+    References
+    ----------
+    .. [1] Morris, M. (1991).  "Factorial Sampling Plans for Preliminary
+           Computational Experiments."  Technometrics, 33(2):161-174,
+           doi:10.1080/00401706.1991.10484804.
+    .. [2] Campolongo, F., J. Cariboni, and A. Saltelli (2007).  "An effective
+           screening design for sensitivity analysis of large models."
+           Environmental Modelling & Software, 22(10):1509-1518,
+           doi:10.1016/j.envsoft.2006.10.004.
+           
+    Examples
+    --------
+    >>> X = morris.sample(problem, 1000, num_levels=4, grid_jump=2)
+    >>> Y = Ishigami.evaluate(X)
+    >>> Si = morris.analyze(problem, X, Y, conf_level=0.95, 
+    >>>                     print_to_console=True, num_levels=4, grid_jump=2)
+    """
 
     # Assume that there are no groups
     groups = None

SALib/analyze/sobol.py

@@ -17,13 +17,52 @@
     from itertools import izip_longest as zip_longest
 
 
-# Perform Sobol Analysis on a vector of model results
-# Returns a dictionary with keys 'S1', 'S1_conf', 'ST', and 'ST_conf'
-# Where each entry is a list of size D (the number of parameters)
-# Containing the indices in the same order as the parameter file
 def analyze(problem, Y, calc_second_order=True, num_resamples=100,
             conf_level=0.95, print_to_console=False, parallel=False,
             n_processors=None):
+    """Perform Sobol Analysis on model outputs.
+    
+    Returns a dictionary with keys 'S1', 'S1_conf', 'ST', and 'ST_conf', where
+    each entry is a list of size D (the number of parameters) containing the
+    indices in the same order as the parameter file.  If calc_second_order is
+    True, the dictionary also contains keys 'S2' and 'S2_conf'.
+    
+    Parameters
+    ----------
+    problem : dict
+        The problem definition
+    Y : numpy.array
+        A NumPy array containing the model outputs
+    calc_second_order : bool
+        Calculate second-order sensitivities (default True)
+    num_resamples : int
+        The number of resamples (default 100)
+    conf_level : float
+        The confidence interval level (default 0.95)
+    print_to_console : bool
+        Print results directly to console (default False)
+        
+    References
+    ----------
+    .. [1] Sobol, I. M. (2001).  "Global sensitivity indices for nonlinear
+           mathematical models and their Monte Carlo estimates."  Mathematics
+           and Computers in Simulation, 55(1-3):271-280,
+           doi:10.1016/S0378-4754(00)00270-6.
+    .. [2] Saltelli, A. (2002).  "Making best use of model evaluations to
+           compute sensitivity indices."  Computer Physics Communications,
+           145(2):280-297, doi:10.1016/S0010-4655(02)00280-1.
+    .. [3] Saltelli, A., P. Annoni, I. Azzini, F. Campolongo, M. Ratto, and
+           S. Tarantola (2010).  "Variance based sensitivity analysis of model
+           output.  Design and estimator for the total sensitivity index."
+           Computer Physics Communications, 181(2):259-270,
+           doi:10.1016/j.cpc.2009.09.018.
+           
+    Examples
+    --------
+    >>> X = saltelli.sample(problem, 1000)
+    >>> Y = Ishigami.evaluate(X)
+    >>> Si = sobol.analyze(problem, Y, print_to_console=True)
+    """
 
     D = problem['num_vars']
 

SALib/sample/fast_sampler.py

@@ -8,8 +8,24 @@
 from .. util import scale_samples, read_param_file
 
 
-# Generate N x D matrix of extended FAST samples (Saltelli 1999)
 def sample(problem, N, M=4):
+    """Generate model inputs for the Fourier Amplitude Sensitivity Test (FAST).
+    
+    Returns a NumPy matrix containing the model inputs required by the Fourier
+    Amplitude sensitivity test.  The resulting matrix contains N rows and D
+    columns, where D is the number of parameters.  The samples generated are
+    intended to be used by :func:`SALib.analyze.fast.analyze`.
+    
+    Parameters
+    ----------
+    problem : dict
+        The problem definition
+    N : int
+        The number of samples to generate
+    M : int
+        The interference parameter, i.e., the number of harmonics to sum in the
+        Fourier series decomposition (default 4)
+    """
 
     D = problem['num_vars']
 

SALib/sample/latin.py

@@ -6,9 +6,22 @@
 from ..util import scale_samples, read_param_file
 
 
-# Generate N x D matrix of latin hypercube samples
 def sample(problem, N):
-
+    """Generate model inputs using Latin hypercube sampling (LHS).
+    
+    Returns a NumPy matrix containing the model inputs generated by Latin
+    hypercube sampling.  The resulting matrix contains N rows and D columns,
+    where D is the number of parameters.
+    
+    Parameters
+    ----------
+    problem : dict
+        The problem definition
+    N : int
+        The number of samples to generate
+    calc_second_order : bool
+        Calculate second-order sensitivities (default True)
+    """
     D = problem['num_vars']
 
     result = np.empty([N, D])