Repository files navigation

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

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

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

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

• Example
• Documentation
• Installation
• Dependencies
• Citation

Examples for how to use Uncertainpy can be found in theexamples folderas well as in thedocumentation.Here we show an example,found inexamples/coffee_cup,where we examine the changes in temperature of a cooling coffee cup thatfollows Newton’s law of cooling:

This equation tells how the temperatureof the coffee cup changes with time,when it is in an environment with temperature. is a proportionalityconstant that is characteristic of the system and regulates how fast the coffeecup radiates heat to the environment.For simplicity we set the initial temperature to a fixed value,,and let and be uncertain input parameters.

We start by importing the packages we use:

importuncertainpyasunimportnumpyasnp# For the time arrayimportchaospyascp# To create distributionsfromscipy.integrateimportodeint# To integrate our equation

To create the model we define a Python functioncoffee_cup thattakes the uncertain parameterskappa andT_env as input arguments.Inside this function we solve our equation by integrating it usingscipy.integrate.odeint,before we return the results.The implementation of the model is:

# Create the coffee cup model functiondefcoffee_cup(kappa,T_env):# Initial temperature and time arraytime=np.linspace(0,200,150)# MinutesT_0=95# Celsius# The equation describing the modeldeff(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 outputreturntime,temperature

We could use this function directly inUncertaintyQuantification,but we would like to have labels on the axes when plotting.So we create aModel with the above run function and labels:

# Create a model from the coffee_cup function and add labelsmodel=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 followingdistributions:

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

# Create the distributionskappa_dist=cp.Uniform(0.025,0.075)T_env_dist=cp.Uniform(15,25)# Define the parameter dictionaryparameters= {"kappa":kappa_dist,"T_env":T_env_dist}

We can now calculate the uncertainty and sensitivity using polynomial chaosexpansions with point collocation,which is the default option ofquantify:

# Set up the uncertainty quantificationUQ=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.From the sensitivity analysis (B) we see that T is mostsensitive toearly in the simulation,and to towards the end of the simulation.This is as expected, sincedetermines the rate of the cooling,while determines the final temperature.After about 150 minutes,the cooling is essentially completed,and the uncertainty in T exclusively reflects the uncertainty of.

The documentation for Uncertainpy can be found athttp://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.

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

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 requiresxvfb, which can be installed with:

sudo apt-get install xvfb

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

uncertainpy.EfelFeatures requires the Python package

• efel

which can be installed with:

pip install uncertainpy[efel_features]

or:

pip install efel

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

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

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

Uncertainpy comes with an extensive test suite that can be run with thetest.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

If you use Uncertainpy in your work, please cite: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.

The style mostly used:

API:         an (incompatible) API changeBenchmark:   changes to the benchmark suiteBuild:       related to buildingBug:         bug fixDeprecate:   deprecate something, or remove a deprecated objectDoc:         documentation[ blank ]:   enhancementRefactor:    maintenance commit (refactoring, typos, etc.)Revert:      revert an earlier commitStyle:       fix (whitespace, PEP8)Test:        addition or modification of testsRelease:     related to releasingTool:        development tool or utilityWIP:         Work-in-progress