SALib.sample.morris package

Submodules

SALib.sample.morris.brute module

class SALib.sample.morris.brute.BruteForce[source]

Bases: SALib.sample.morris.strategy.Strategy

Implements the brute force optimisation strategy

brute_force_most_distant(input_sample, num_samples, num_params, k_choices, num_groups=None)[source]

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
Returns:

Return type:

list

find_maximum(scores, N, k_choices)[source]

Finds the k_choices maximum scores from scores

Parameters:
  • scores (numpy.ndarray) –
  • N (int) –
  • k_choices (int) –
Returns:

Return type:

list

find_most_distant(input_sample, num_samples, num_params, k_choices, num_groups=None)[source]

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
Returns:

Return type:

numpy.ndarray

static grouper(n, iterable)[source]
static mappable(combos, pairwise, distance_matrix)[source]

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)[source]

Returns the nth item or a default value

Parameters:
  • iterable (iterable) –
  • n (int) –
  • default (default=None) – The default value to return

SALib.sample.morris.gurobi module

Finds optimal trajectories using a global optimisation method

Example

Run using

>>> optimal_trajectories.py -n=10     -p=esme_param.txt -o=test_op.txt     -s=12892 --num-levels=4 --grid-jump=2     --k-choices=4
SALib.sample.morris.gurobi.timestamp(num_params, p_levels, k_choices, N)[source]

Returns a uniform timestamp with parameter values for file identification

SALib.sample.morris.local module

class SALib.sample.morris.local.LocalOptimisation[source]

Bases: SALib.sample.morris.strategy.Strategy

Implements the local optimisation algorithm using the Strategy interface

add_indices(indices, distance_matrix)[source]

Adds extra indices for the combinatorial problem.

Parameters:
  • indices (tuple) –
  • distance_matrix (numpy.ndarray (M,M)) –

Example

>>> add_indices((1,2), numpy.array((5,5)))
[(1, 2, 3), (1, 2, 4), (1, 2, 5)]
find_local_maximum(input_sample, N, num_params, k_choices, num_groups=None)[source]

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
Returns:

Return type:

list

get_max_sum_ind(indices_list, distances, i, m)[source]

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) –
Returns:

Return type:

list

sum_distances(indices, distance_matrix)[source]

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

Parameters:
  • indices (tuple) –
  • distance_matrix (numpy.ndarray (M,M)) –
Returns:

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.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)[source]

Bases: object

Computes the optimum k_choices of trajectories from the input_sample.

Parameters:strategy (Strategy) –
sample(input_sample, num_samples, num_params, k_choices, num_groups)[source]

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[source]

Bases: object

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

static check_input_sample(input_sample, num_params, num_samples)[source]

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)[source]

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)[source]

Compute distance between two trajectories

Returns:
Return type:numpy.ndarray
compute_distance_matrix(input_sample, num_samples, num_params, num_groups=None, local_optimization=False)[source]

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)[source]

Runs checks on k_choices

sample(input_sample, num_samples, num_params, k_choices, num_groups=None)[source]

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
Returns:

Return type:

numpy.ndarray

Module contents

Generate a sample using the Method of Morris

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

  • Vanilla Morris
  • Optimised trajectories when optimal_trajectories=True (using
    Campolongo’s enhancements from 2007 and optionally Ruano’s enhancement from 2012; local_optimization=True)
  • Groups with optimised trajectories when optimal_trajectories=True and
    the problem definition specifies groups (note that local_optimization must be False)

At present, optimised trajectories is implemented using either a brute-force approach, which can be very slow, especially if you require more than four trajectories, or a local method based which is much faster. Both methods now implement working with groups of factors.

Note that 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 from a pool of 100 samples with the brute force approach. With local_optimization = True (which is default), it is possible to go higher than the previously suggested 4 from 100.

SALib.sample.morris.sample(problem, N, num_levels=4, optimal_trajectories=None, local_optimization=True)[source]

Generate model inputs using the Method of Morris

Returns a NumPy matrix containing the model inputs required for Method of Morris. The resulting matrix has (G+1)*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. These model inputs are intended to be used with SALib.analyze.morris.analyze().

Parameters:
  • problem (dict) – The problem definition
  • N (int) – The number of trajectories to generate
  • num_levels (int, default=4) – The number of grid levels
  • 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
Returns:

sample – Returns a numpy.ndarray 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.

Return type:

numpy.ndarray