pyeee - Efficient parameter screening of computational models

.. pandoc -f rst -t html -o README.html README.rst

A Python library for parameter screening of computational models using Morris' method of Elementary Effects and its extension of Efficient or Sequential Elementary Effects by Cuntz, Mai et al. (Water Res Research, 2015).

|DOI| |PyPI version| |Conda version| |License| |Build Status| |Coverage Status|

About pyeee

pyeee is a Python library for performing parameter screening of computational models. It uses Morris' method of Elementary Effects and its extension, the so-called Efficient or Sequential Elementary Effects published by

Cuntz, Mai et al. (2015) Computationally inexpensive identification of noninformative model parameters by sequential screening, Water Resources Research 51, 6417-6441, doi: 10.1002/2015WR016907_.

pyeee can be used with Python functions but also with external programs, using for example the library partialwrap. Function evaluation can be distributed with Python's multiprocessing module or via the Message Passing Interface (MPI_).

Documentation

The complete documentation for pyeee is available at Github Pages:

https://mcuntz.github.io/pyeee/

Quick usage guide

Simple Python function ^^^^^^^^^^^^^^^^^^^^^^

Consider the Ishigami-Homma function: y = sin(x_0) + a * sin(x_1)^2 + b * x_2^4 * sin(x_0).

Taking a = b = 1 gives:

.. code:: python

import numpy as np def ishigami1(x): return np.sin(x[0]) + np.sin(x[1])**2 + x[2]**4 * np.sin(x[0])

The three paramters x_0, x_1, x_2 follow uniform distributions between -pi and +pi.

Morris' Elementary Effects can then be calculated as:

.. code:: python

from pyeee import screening

npars = 3

lower boundaries

lb = np.ones(npars) * (-np.pi)

upper boundaries

ub = np.ones(npars) * np.pi

Elementary Effects

np.random.seed(seed=1023) # for reproducibility of examples out = screening(ishigami1, lb, ub, 10) # mu*, mu, sigma print("{:.1f} {:.1f} {:.1f}".format(*out[:, 0]))

gives: 173.1 0.6 61.7

which gives the Elementary Effects mu*.

Sequential Elementary Effects distinguish between informative and uninformative parameters using several times Morris' Elementary Effects, returning a logical ndarray with True for the informative parameters and False for the uninformative parameters:

.. code:: python

from pyeee import eee

screen

np.random.seed(seed=1023) # for reproducibility of examples out = eee(ishigami1, lb, ub, ntfirst=10) print(out) [ True False True]

Python function with extra parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The function for the routines in pyeee must be of the form func(x). Use Python's partial_ from the functools_ module to pass other function parameters. For example pass the parameters a and b to the Ishigami-Homma function.

.. code:: python

import numpy as np from pyeee import eee from functools import partial

def ishigami(x, a, b): return np.sin(x[0]) + a * np.sin(x[1])**2 + b * x[2]**4 * np.sin(x[0])

def call_ishigami(func, a, b, x): return func(x, a, b)

Partialise function with fixed parameters

a = 0.5 b = 2.0 func = partial(call_ishigami, ishigami, a, b)

npars = 3

lower boundaries

lb = np.ones(npars) * (-np.pi)

upper boundaries

ub = np.ones(npars) * np.pi

Elementary Effects

np.random.seed(seed=1023) # for reproducibility of examples out = eee(func, lb, ub, ntfirst=10)

Figuratively speaking, partial_ passes a and b to the function call_ishigami already during definition so that eee can then simply call it as func(x), where x is passed to call_ishigami then as well.

Function wrappers ^^^^^^^^^^^^^^^^^

We recommend to use our package partialwrap_ for external executables, which allows easy use of external programs and their parallel execution. See the userguide_ for details. A trivial example is the use of partialwrap_ for the above function wrapping:

.. code:: python

from partialwrap import function_wrapper

args = [a, b] kwargs = {} func = partial(func_wrapper, ishigami, args, kwargs)

screen

out = eee(func, lb, ub, ntfirst=10)

Installation

The easiest way to install is via pip:

.. code-block:: bash

pip install pyeee

or via conda:

.. code-block:: bash

conda install -c conda-forge pyeee

Requirements

• NumPy <https://www.numpy.org>__
• SciPy <https://www.numpy.org>__
• schwimmbad <https://github.com/adrn/schwimmbad>__

License

pyeee is distributed under the MIT License. See the LICENSE_ file for details.

Copyright (c) 2019-2024 Matthias Cuntz, Juliane Mai

The project structure is based on a template_ provided by Sebastian Müller_.

.. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3620909.svg :target: https://doi.org/10.5281/zenodo.3620909 .. |PyPI version| image:: https://badge.fury.io/py/pyeee.svg :target: https://badge.fury.io/py/pyeee .. |Conda version| image:: https://img.shields.io/conda/vn/conda-forge/pyeee.svg :target: https://anaconda.org/conda-forge/pyeee .. |License| image:: http://img.shields.io/badge/license-MIT-blue.svg?style=flat :target: https://github.com/mcuntz/pyeee/blob/master/LICENSE .. |Build Status| image:: https://github.com/mcuntz/pyeee/actions/workflows/master.yml/badge.svg :target: https://github.com/mcuntz/pyeee/actions/workflows/master.yml .. |Coverage Status| image:: https://coveralls.io/repos/github/mcuntz/pyeee/badge.svg?branch=master :target: https://coveralls.io/github/mcuntz/pyeee?branch=master

.. _10.1002/2015WR016907: http://doi.org/10.1002/2015WR016907 .. _LICENSE: https://github.com/mcuntz/pyeee/LICENSE .. _MPI: https://bitbucket.org/mpi4py/mpi4py .. _Sebastian Müller: https://github.com/MuellerSeb .. _functools: https://docs.python.org/3/library/functools.html .. _multiprocessing: https://docs.python.org/3/library/multiprocessing.html .. _partial: https://docs.python.org/3/library/functools.html#functools.partial .. _partialwrap: https://mcuntz.github.io/partialwrap/ .. _template: https://github.com/MuellerSeb/template .. _userguide: https://mcuntz.github.io/pyeee/html/userguide.html