pyeee.eee

Function eee for Efficient/Sequential Elementary Effects, an extension of Morris’ method of Elementary Effects by Cuntz, Mai et al. (Water Res Research, 2015).

This function was written by Matthias Cuntz while at Institut National de Recherche pour l’Agriculture, l’Alimentation et l’Environnement (INRAE), Nancy, France.

Copyright (c) 2017-2021 Matthias Cuntz - mc (at) macu (dot) de Released under the MIT License; see LICENSE file for details.

The following functions are provided

see(func, *args, **kwargs) Wrapper function for eee().
eee(func, *args, **kwargs) Parameter screening using Efficient/Sequential Elementary Effects of Cuntz, Mai et al.
History
  • Written Nov 2017 by Matthias Cuntz (mc (at) macu (dot) de)
  • Added weight option, Jan 2018, Matthias Cuntz
  • Added plotfile and made docstring sphinx compatible option, Jan 2018, Matthias Cuntz
  • x0 optional; added verbose keyword; distinguish iterable and array_like parameter types, Jan 2020, Matthias Cuntz
  • Rename ntsteps to nsteps to be consistent with screening/ee; and check if logfile is string rather thean checking for file handle, Feb 2020, Matthias Cuntz
  • Sample not only from uniform distribution but allow all distributions of scipy.stats, Mar 2020, Matthias Cuntz
  • Use pyjams package, Oct 2021, Matthias Cuntz
  • Make flake8 compatible, Oct 2021, Matthias Cuntz
eee(func, *args, **kwargs)[source]

Parameter screening using Efficient/Sequential Elementary Effects of Cuntz, Mai et al. (Water Res Research, 2015).

Note, the input function must be callable as func(x).

Parameters:
  • func (callable) – Python function callable as func(x) with x the function parameters.
  • lb (array_like) –

    Lower bounds of parameters or lower fraction of percent point function ppf if distribution given.

    Be aware that the percent point function ppf of most continuous distributions is infinite at 0.

  • ub (array_like) –

    Upper bounds of parameters or upper fraction of percent point function ppf if distribution given.

    Be aware that the percent point function ppf of most continuous distributions is infinite at 1.

  • x0 (array_like, optional) – Parameter values used with mask==0.
  • mask (array_like, optional) – Include (1,True) or exclude (0,False) parameters in screening (default: include all parameters).
  • ntfirst (int, optional) – Number of trajectories in first step of sequential elementary effects (default: 5).
  • ntlast (int, optional) – Number of trajectories in last step of sequential elementary effects (default: 5).
  • nsteps (int, optional) – Number of intervals for each trajectory (default: 6)
  • dist (list, optional) –

    List of None or scipy.stats distribution objects for each factor having the method ppf, Percent Point Function (Inverse of CDF) (default: None)

    If None, the uniform distribution will be sampled from lower bound lb to upper bound ub.

    If dist is scipy.stats.uniform, the ppf will be sampled from the lower fraction given in lb and the upper fraction in ub. The sampling interval is then given by the parameters loc=lower and scale=interval=upper-lower in distparam. This means dist=None, lb=a, ub=b corresponds to lb=0, ub=1, dist=scipy.stats.uniform, distparam=[a,b-a]

  • distparam (list, optional) –

    List with tuples with parameters as required for dist (default: (0,1)).

    All distributions of scipy.stats have location and scale parameters, at least. loc and scale are implemented as keyword arguments in scipy.stats. Other parameters such as the shape parameter of the gamma distribution must hence be given first, e.g. (shape,loc,scale) for the gamma distribution.

    distparam is ignored if dist is None.

    The percent point function ppf is called like this: dist(*distparam).ppf(x)

  • weight (boolean, optional) –

    If False, use the arithmetic mean mu* for each parameter if function has multiple outputs, such as the mean mu* of each time step of a time series (default).

    If True, return weighted mean mu*, weighted by sd.

  • seed (int or array_like) – Seed for numpy’s random number generator (default: None).
  • processes (int, optinal) – The number of processes to use to evaluate objective function and constraints (default: 1).
  • pool (schwimmbad pool object, optinal) –

    Generic map function used from module schwimmbad, which provides, serial, multiprocessor, and MPI mapping functions (default: None).

    The pool is chosen with:

    schwimmbad.choose_pool(mpi=True/False, processes=processes).

    The pool will be chosen automatically if pool is None.

    MPI pools can only be opened and closed once. If you want to use screening several times in one program, then you have to choose the pool, pass it to eee, and later close the pool in the calling program.

  • verbose (int, optional) – Print progress report during execution if verbose>0 (default: 0).
  • logfile (File handle or logfile name) – File name of possible log file (default: None = no logfile will be written).
  • plotfile (Plot file name) – File name of possible plot file with fit of logistic function to mu* of first trajectories (default: None = no plot produced).
Returns:

mask – (len(lb),) mask with 1=informative and 0=uninformative model parameters, to be used with ‘&’ on input mask.
Return type:

ndarray

See also

screening() : Elementary Effects, same as

ee() : Elementary Effects

Examples

>>> from functools import partial
>>> import numpy as np
>>> import scipy.stats as stats
>>> from pyjams.functions import G
>>> from partialwrap import function_wrapper
>>> seed = 1234
>>> np.random.seed(seed=seed)
>>> func   = G
>>> npars  = 6
>>> params = [78., 12., 0.5, 2., 97., 33.] # G
>>> arg   = [params]
>>> kwarg = {}
>>> obj = partial(function_wrapper, func, arg, kwarg)
>>> lb = np.zeros(npars)
>>> ub = np.ones(npars)
>>> ntfirst = 10
>>> ntlast  = 5
>>> nsteps  = 6
>>> out = eee(obj, lb, ub, mask=None, ntfirst=ntfirst, ntlast=ntlast,
...           nsteps=nsteps, processes=4)
>>> print(np.where(out)[0] + 1)
[2 3 4 6]
see(func, *args, **kwargs)[source]

Wrapper function for eee().