SALib.sample.morris package

Submodules

SALib.sample.morris.brute module

class SALib.sample.morris.brute.BruteForce

Bases: Strategy

Implements the brute force optimisation strategy

Methods

brute_force_most_distant(input_sample, ...)	Use brute force method to find most distant trajectories
check_input_sample(input_sample, num_params, ...)	Check the input_sample is valid
compile_output(input_sample, num_samples, ...)	Picks the trajectories from the input
compute_distance(m, l)	Compute distance between two trajectories
compute_distance_matrix(input_sample, ...[, ...])	Computes the distance between each and every trajectory
find_maximum(scores, N, k_choices)	Finds the k_choices maximum scores from scores
find_most_distant(input_sample, num_samples, ...)	Finds the 'k_choices' most distant choices from the 'num_samples' trajectories contained in 'input_sample'
mappable(combos, pairwise, distance_matrix)	Obtains scores from the distance_matrix for each pairwise combination held in the combos array
nth(iterable, n[, default])	Returns the nth item or a default value
run_checks(number_samples, k_choices)	Runs checks on k_choices
sample(input_sample, num_samples, ...[, ...])	Computes the optimum k_choices of trajectories from the input_sample.

grouper

brute_force_most_distant(input_sample: ndarray, num_samples: int, num_params: int, k_choices: int, num_groups: int = None) → List

Use brute force method to find most distant trajectories

Parameters:

• input_sample (numpy.ndarray)

• num_samples (int) – The number of samples to generate

• num_params (int) – The number of parameters

• k_choices (int) – The number of optimal trajectories

• num_groups (int, default=None) – The number of groups

Return type:

list

find_maximum(scores, N, k_choices)

Finds the k_choices maximum scores from scores

Parameters:

• scores (numpy.ndarray)

• N (int)

• k_choices (int)

Return type:

list

find_most_distant(input_sample: ndarray, num_samples: int, num_params: int, k_choices: int, num_groups: int = None) → ndarray

Finds the ‘k_choices’ most distant choices from the ‘num_samples’ trajectories contained in ‘input_sample’

Parameters:

• input_sample (numpy.ndarray)

• num_samples (int) – The number of samples to generate

• num_params (int) – The number of parameters

• k_choices (int) – The number of optimal trajectories

• num_groups (int, default=None) – The number of groups

Return type:

numpy.ndarray

static grouper(n, iterable)

static mappable(combos, pairwise, distance_matrix)

Obtains scores from the distance_matrix for each pairwise combination held in the combos array

Parameters:

• combos (numpy.ndarray)

• pairwise (numpy.ndarray)

• distance_matrix (numpy.ndarray)

static nth(iterable, n, default=None)

Returns the nth item or a default value

Parameters:

• iterable (iterable)

• n (int)

• default (default=None) – The default value to return

SALib.sample.morris.local module

class SALib.sample.morris.local.LocalOptimisation

Bases: Strategy

Implements the local optimisation algorithm using the Strategy interface

Methods

add_indices(indices, distance_matrix)	Adds extra indices for the combinatorial problem.
check_input_sample(input_sample, num_params, ...)	Check the input_sample is valid
compile_output(input_sample, num_samples, ...)	Picks the trajectories from the input
compute_distance(m, l)	Compute distance between two trajectories
compute_distance_matrix(input_sample, ...[, ...])	Computes the distance between each and every trajectory
find_local_maximum(input_sample, N, ...[, ...])	Find the most different trajectories in the input sample using a local approach
get_max_sum_ind(indices_list, distances, i, m)	Get the indices that belong to the maximum distance in distances
run_checks(number_samples, k_choices)	Runs checks on k_choices
sample(input_sample, num_samples, ...[, ...])	Computes the optimum k_choices of trajectories from the input_sample.
sum_distances(indices, distance_matrix)	Calculate combinatorial distance between a select group of trajectories, indicated by indices

add_indices(indices: Tuple, distance_matrix: ndarray) → List

Adds extra indices for the combinatorial problem.

Parameters:

• indices (tuple)

• distance_matrix (numpy.ndarray (M,M))

Examples

>>> add_indices((1,2), numpy.array((5,5)))
[(1, 2, 3), (1, 2, 4), (1, 2, 5)]

find_local_maximum(input_sample: ndarray, N: int, num_params: int, k_choices: int, num_groups: int = None) → List

Find the most different trajectories in the input sample using a local approach

An alternative by Ruano et al. (2012) for the brute force approach as originally proposed by Campolongo et al. (2007). The method should improve the speed with which an optimal set of trajectories is found tremendously for larger sample sizes.

Parameters:

• input_sample (np.ndarray)

• N (int) – The number of trajectories

• num_params (int) – The number of factors

• k_choices (int) – The number of optimal trajectories to return

• num_groups (int, default=None) – The number of groups

Return type:

list

get_max_sum_ind(indices_list: List[Tuple], distances: ndarray, i: str | int, m: str | int) → Tuple

Get the indices that belong to the maximum distance in distances

Parameters:

• indices_list (list) – list of tuples

• distances (numpy.ndarray) – size M

• i (int)

• m (int)

Return type:

list

sum_distances(indices: Tuple, distance_matrix: ndarray) → ndarray

Calculate combinatorial distance between a select group of trajectories, indicated by indices

Parameters:

• indices (tuple)

• distance_matrix (numpy.ndarray (M,M))

Return type:

numpy.ndarray

Notes

This function can perhaps be quickened by calculating the sum of the distances. The calculated distances, as they are right now, are only used in a relative way. Purely summing distances would lead to the same result, at a perhaps quicker rate.

SALib.sample.morris.morris module

SALib.sample.morris.morris.sample(problem: Dict, N: int, num_levels: int = 4, optimal_trajectories: int = None, local_optimization: bool = True, seed: int = None) → ndarray

Generate model inputs using the Method of Morris.

Three variants of Morris’ sampling for elementary effects is supported:

• Vanilla Morris (see [1]) when optimal_trajectories is None/False and local_optimization is False

• Optimised trajectories when optimal_trajectories=True using

  Campolongo’s enhancements (see [2]) and optionally Ruano’s enhancement (see [3]) when local_optimization=True

• Morris with groups when the problem definition specifies groups of parameters

Results from these model inputs are intended to be used with SALib.analyze.morris.analyze().

Notes

Campolongo et al., [2] introduces an optimal trajectories approach which attempts to maximize the parameter space scanned for a given number of trajectories (where optimal_trajectories \(\in {2, ..., N}\)). The approach accomplishes this aim by randomly generating a high number of possible trajectories (500 to 1000 in [2]) and selecting a subset of r trajectories which have the highest spread in parameter space. The r variable in [2] corresponds to the optimal_trajectories parameter here.

Calculating all possible combinations of trajectories can be computationally expensive. The number of factors makes little difference, but the ratio between number of optimal trajectories and the sample size results in an exponentially increasing number of scores that must be computed to find the optimal combination of trajectories. We suggest going no higher than 4 levels from a pool of 100 samples with this “brute force” approach.

Ruano et al., [3] proposed an alternative approach with an iterative process that maximizes the distance between subgroups of generated trajectories, from which the final set of trajectories are selected, again maximizing the distance between each. The approach is not guaranteed to produce the most optimal spread of trajectories, but are at least locally maximized and significantly reduce the time taken to select trajectories. With local_optimization = True (which is default), it is possible to go higher than the previously suggested 4 levels from a pool of 100 samples.

Parameters:

• problem (dict) – The problem definition

• N (int) – The number of trajectories to generate

• num_levels (int, default=4) – The number of grid levels (should be even)

• optimal_trajectories (int) – The number of optimal trajectories to sample (between 2 and N)

• local_optimization (bool, default=True) – Flag whether to use local optimization according to Ruano et al. (2012) Speeds up the process tremendously for bigger N and num_levels. If set to False brute force method is used, unless gurobipy is available

• seed (int) – Seed to generate a random number

Returns:

sample_morris – Array containing the model inputs required for Method of Morris. The resulting matrix has \((G/D+1)*N/T\) rows and \(D\) columns, where \(D\) is the number of parameters, \(G\) is the number of groups (if no groups are selected, the number of parameters). \(T\) is the number of trajectories \(N\), or optimal_trajectories if selected.

Return type:

np.ndarray

References

1. Morris, M.D., 1991. Factorial Sampling Plans for Preliminary Computational Experiments. Technometrics 33, 161-174. https://doi.org/10.1080/00401706.1991.10484804

2. Campolongo, F., Cariboni, J., & Saltelli, A. 2007. An effective screening design for sensitivity analysis of large models. Environmental Modelling & Software, 22(10), 1509-1518. https://doi.org/10.1016/j.envsoft.2006.10.004

3. Ruano, M.V., Ribes, J., Seco, A., Ferrer, J., 2012. An improved sampling strategy based on trajectory design for application of the Morris method to systems with many input factors. Environmental Modelling & Software 37, 103-109. https://doi.org/10.1016/j.envsoft.2012.03.008

SALib.sample.morris.strategy module

Defines a family of algorithms for generating samples

The sample a for use with SALib.analyze.morris.analyze, encapsulate each one, and makes them interchangeable.

Example

>>> localoptimisation = LocalOptimisation()
>>> context = SampleMorris(localoptimisation)
>>> context.sample(input_sample, num_samples, num_params, k_choices, groups)

class SALib.sample.morris.strategy.SampleMorris(strategy)

Bases: object

Computes the optimum k_choices of trajectories from the input_sample.

Parameters:

strategy (Strategy)

Methods

sample(input_sample, num_samples, ...)

Computes the optimum k_choices of trajectories from the input_sample.

sample(input_sample, num_samples, num_params, k_choices, num_groups)

Computes the optimum k_choices of trajectories from the input_sample.

Parameters:

• input_sample (numpy.ndarray)

• num_samples (int) – The number of samples to generate

• num_params (int) – The number of parameters

• k_choices (int) – The number of optimal trajectories

• num_groups (int) – The number of groups

Returns:

An array of optimal trajectories

Return type:

numpy.ndarray

class SALib.sample.morris.strategy.Strategy

Bases: object

Declare an interface common to all supported algorithms. SampleMorris uses this interface to call the algorithm defined by a ConcreteStrategy.

Methods

check_input_sample(input_sample, num_params, ...)	Check the input_sample is valid
compile_output(input_sample, num_samples, ...)	Picks the trajectories from the input
compute_distance(m, l)	Compute distance between two trajectories
compute_distance_matrix(input_sample, ...[, ...])	Computes the distance between each and every trajectory
run_checks(number_samples, k_choices)	Runs checks on k_choices
sample(input_sample, num_samples, ...[, ...])	Computes the optimum k_choices of trajectories from the input_sample.

static check_input_sample(input_sample, num_params, num_samples)

Check the input_sample is valid

Checks input sample is:

• the correct size

• values between 0 and 1

Parameters:

• input_sample (numpy.ndarray)

• num_params (int)

• num_samples (int)

compile_output(input_sample, num_samples, num_params, maximum_combo, num_groups=None)

Picks the trajectories from the input

Parameters:

• input_sample (numpy.ndarray)

• num_samples (int)

• num_params (int)

• maximum_combo (list)

• num_groups (int)

static compute_distance(m, l)

Compute distance between two trajectories

Parameters:

• m (np.ndarray)

• l (np.ndarray)

Return type:

numpy.ndarray

compute_distance_matrix(input_sample, num_samples, num_params, num_groups=None, local_optimization=False)

Computes the distance between each and every trajectory

Each entry in the matrix represents the sum of the geometric distances between all the pairs of points of the two trajectories

If the groups argument is filled, then the distances are still calculated for each trajectory,

Parameters:

• input_sample (numpy.ndarray) – The input sample of trajectories for which to compute the distance matrix

• num_samples (int) – The number of trajectories

• num_params (int) – The number of factors

• num_groups (int, default=None) – The number of groups

• local_optimization (bool, default=False) – If True, fills the lower triangle of the distance matrix

Returns:

distance_matrix

Return type:

numpy.ndarray

static run_checks(number_samples, k_choices)

Runs checks on k_choices

sample(input_sample, num_samples, num_params, k_choices, num_groups=None)

Computes the optimum k_choices of trajectories from the input_sample.

Parameters:

• input_sample (numpy.ndarray)

• num_samples (int) – The number of samples to generate

• num_params (int) – The number of parameters

• k_choices (int) – The number of optimal trajectories

• num_groups (int, default=None) – The number of groups

Return type:

numpy.ndarray

Module contents