pyeee - Efficient parameter screening of computational models

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

About pyeee

pyeee is a Python library for performing parameter screening of computational models. It uses the extension of Morris’ method of Elementary Effects of 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:

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 using, for example, the Python library pyjams, giving the Elementary Effects (mu*):

from pyjams import ee

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 = ee(ishigami1, lb, ub, 10)   # mu*
print("{:.1f} {:.1f} {:.1f}".format(*out[:, 0]))
# gives: 173.1 0.6 61.7

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:

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 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.

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 also their parallel execution. See the userguide for details. A trivial example is the use of partialwrap for the above function wrapping:

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:

pip install pyeee

or via conda:

conda install -c conda-forge pyeee

Requirements

License

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

The project structure is based on a template provided by Sebastian Müller.

Metadata

Release files for pyeee 4.1.12

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyeee 4.1.12
File	Size	Uploaded	Provenance
pyeee-4.1.12.tar.gz	19.4 kB	Mar 8, 2024	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for pyeee 4.1.12
File	Interpreter	ABI	Platform	Reset
pyeee-4.1.12-py3-none-any.whl 14.0 kB Mar 8, 2024 Without provenance	Python 3	none	any	Details

Total release size: 33.4 kB

Release files / pyeee-4.1.12.tar.gz

Download URL	pyeee-4.1.12.tar.gz
Size	19.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`14239057a22a9c7b43a0c304c5245b529a817eecaec065b08eb6083ad99933c9`
BLAKE2b-256 checksum How to use checksums	`35d06a89b4cbd4cdd8ccdbf0da7e1ae88e40fa7171b94ff43fa511514959331c`
Upload date	Mar 8, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.0.0 CPython/3.12.2`

Release files / pyeee-4.1.12-py3-none-any.whl

Download URL	pyeee-4.1.12-py3-none-any.whl
Size	14.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`954e76c5592730fc77540b22fb51f549438afda0336292abd7dde9e2a1f8349c`
BLAKE2b-256 checksum How to use checksums	`1f3b2d37b1eeb174445539af5d28d5321b5de6d8b27b1082b653119a118c9b15`
Upload date	Mar 8, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.0.0 CPython/3.12.2`

Security for pyeee 4.1.12

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.