Showing:

0

143

3mos ago

8

0

GNU GPLv3

# A python toolbox for uncertainty quantification and sensitivity analysis tailored towards computational neuroscience.

Uncertainpy is a python toolbox for uncertainty quantification and sensitivity analysis tailored towards computational neuroscience.

Uncertainpy is model independent and treats the model as a black box where the model can be left unchanged. Uncertainpy implements both quasi-Monte Carlo methods and polynomial chaos expansions using either point collocation or the pseudo-spectral method. Both of the polynomial chaos expansion methods have support for the rosenblatt transformation to handle dependent input parameters.

Uncertainpy is feature based, i.e., if applicable, it recognizes and calculates the uncertainty in features of the model, as well as the model itself. Examples of features in neuroscience can be spike timing and the action potential shape.

Uncertainpy is tailored towards neuroscience models, and comes with several common neuroscience models and features built in, but new models and features can easily be implemented. It should be noted that while Uncertainpy is tailored towards neuroscience, the implemented methods are general, and Uncertainpy can be used for many other types of models and features within other fields.

## Example

Examples for how to use Uncertainpy can be found in the examples folder as well as in the documentation. Here we show an example, found in examples/coffee_cup, where we examine the changes in temperature of a cooling coffee cup that follows Newton’s law of cooling:

$\frac{dT(t)}{dt}&space;=&space;-\kappa(T(t)&space;-&space;T_{env})$

This equation tells how the temperature $T$ of the coffee cup changes with time $t$, when it is in an environment with temperature $T_{env}$. $\kappa$ is a proportionality constant that is characteristic of the system and regulates how fast the coffee cup radiates heat to the environment. For simplicity we set the initial temperature to a fixed value, $95^\circ\text{C}&space;$, and let $\kappa$ and $T_{env}$ be uncertain input parameters.

We start by importing the packages we use:

``````import uncertainpy as un
import numpy as np                   # For the time array
import chaospy as cp                 # To create distributions
from scipy.integrate import odeint   # To integrate our equation
``````

To create the model we define a Python function `coffee_cup` that takes the uncertain parameters `kappa` and `T_env` as input arguments. Inside this function we solve our equation by integrating it using `scipy.integrate.odeint`, before we return the results. The implementation of the model is:

``````# Create the coffee cup model function
def coffee_cup(kappa, T_env):
# Initial temperature and time array
time = np.linspace(0, 200, 150)            # Minutes
T_0 = 95                                   # Celsius

# The equation describing the model
def f(T, time, kappa, T_env):
return -kappa*(T - T_env)

# Solving the equation by integration.
temperature = odeint(f, T_0, time, args=(kappa, T_env))[:, 0]

# Return time and model output
return time, temperature
``````

We could use this function directly in `UncertaintyQuantification`, but we would like to have labels on the axes when plotting. So we create a `Model` with the above run function and labels:

``````# Create a model from the coffee_cup function and add labels
model = un.Model(run=coffee_cup, labels=["Time (min)", "Temperature (C)"])
``````

The next step is to define the uncertain parameters. We give the uncertain parameters in the cooling coffee cup model the following distributions:

\begin{align*} \kappa&=\mathrm{Uniform}(0.025,0.075),\\ T_{env}&=\mathrm{Uniform}(15,25). \end{align*}

We use Chaospy to create the distributions, and create a parameter dictionary:

``````# Create the distributions
kappa_dist = cp.Uniform(0.025, 0.075)
T_env_dist = cp.Uniform(15, 25)

# Define the parameter dictionary
parameters = {"kappa": kappa_dist, "T_env": T_env_dist}
``````

We can now calculate the uncertainty and sensitivity using polynomial chaos expansions with point collocation, which is the default option of `quantify`:

``````# Set up the uncertainty quantification
UQ = un.UncertaintyQuantification(model=model,
parameters=parameters)

# Perform the uncertainty quantification using
# polynomial chaos with point collocation (by default)
data = UQ.quantify()
``````

Here you see an example on how the results might look:

This plot shows the mean, variance, and 90% prediction interval (A), and the first-order Sobol indices (B), which shows the sensitivity of the model to each parameter, for the cooling coffee cup model. As the mean (blue line) in A shows, the cooling gives rise to an exponential decay in the temperature, towards the temperature of the environment $T_{env}$. From the sensitivity analysis (B) we see that T is most sensitive to $\kappa$ early in the simulation, and to $T_{env}$ towards the end of the simulation. This is as expected, since $\kappa$ determines the rate of the cooling, while $T_{env}$ determines the final temperature. After about 150 minutes, the cooling is essentially completed, and the uncertainty in T exclusively reflects the uncertainty of $T_{env}$.

## Documentation

The documentation for Uncertainpy can be found at http://uncertainpy.readthedocs.io, and the Uncertainpy paper here: Tennøe S, Halnes G and Einevoll GT (2018) Uncertainpy: A Python Toolbox for Uncertainty Quantification and Sensitivity Analysis in Computational Neuroscience. Front. Neuroinform. 12:49. doi: 10.3389/fninf.2018.00049.

## Installation

Uncertainpy works with Python 3. Uncertainpy can easily be installed using pip. The minimum install is:

``````pip install uncertainpy
``````

To install all requirements you can write:

``````pip install uncertainpy[all]
``````

Specific optional requirements can also be installed, see below for an explanation. Uncertainpy can also be installed by cloning the Github repository:

``````\$ git clone https://github.com/simetenn/uncertainpy
\$ cd /path/to/uncertainpy
\$ python setup.py install
``````

`setup.py` are able to install different set of dependencies. For all options run::

``````\$ python setup.py --help
``````

Alternatively, Uncertainpy can be easily installed (minimum install) with conda using conda-forge channel::

``````\$ conda install -c conda-forge uncertainpy
``````

The above installation within a conda environment is only compatible with Python 3.x. By using conda, the installation will solves compatibility issues automatically.

### Dependencies

Uncertainpy has the following dependencies:

• `chaospy`
• `tqdm`
• `h5py`
• `multiprocess`
• `numpy`
• `scipy`
• `seaborn`
• `matplotlib`
• `xvfbwrapper`
• `six`
• `SALib`
• `exdir`

These are installed with the minimum install.

`xvfbwrapper` requires `xvfb`, which can be installed with:

``````sudo apt-get install xvfb
``````

Additionally Uncertainpy has a few optional dependencies for specific classes of models and for features of the models.

#### EfelFeatures

`uncertainpy.EfelFeatures` requires the Python package

• `efel`

which can be installed with:

``````pip install uncertainpy[efel_features]
``````

or:

``````pip install efel
``````

#### NetworkFeatures

`uncertainpy.NetworkFeatures` requires the Python packages

• `elephant`
• `neo`
• `quantities`

which can be installed with:

``````pip install uncertainpy[network_features]
``````

or:

``````pip install elephant, neo, quantities
``````

#### NeuronModel

`uncertainpy.NeuronModel` requires the external simulator Neuron (with Python), a simulator for neurons. Neuron must be installed by the user.

#### NestModel

`uncertainpy.NestModel` requires the external simulator Nest (with Python), a simulator for network of neurons. Nest must be installed by the user.

### Test suite

Uncertainpy comes with an extensive test suite that can be run with the `test.py` script. For how to use test.py run:

``````\$ python test.py --help
``````

`test.py` has all dependencies of Uncertainpy in addition to:

• `click`

These can be installed with pip:

``````pip install uncertainpy[tests]
``````

In addition, the following program must be installed:

• `hdf5-tools`

## Commit messages

The style mostly used:

``````API:         an (incompatible) API change
Benchmark:   changes to the benchmark suite
Build:       related to building
Bug:         bug fix
Deprecate:   deprecate something, or remove a deprecated object
Doc:         documentation
[ blank ]:   enhancement
Refactor:    maintenance commit (refactoring, typos, etc.)
Revert:      revert an earlier commit
Style:       fix (whitespace, PEP8)
Test:        addition or modification of tests
Release:     related to releasing
Tool:        development tool or utility
WIP:         Work-in-progress
``````

## Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100