Giter Club home page Giter Club logo

uncertainsci's Introduction

UncertainSCI

A Python-based toolkit that harnesses modern techniques to estimate model and parametric uncertainty, with a particular emphasis on needs for biomedical simulations and applications. This toolkit enables non-intrusive integration of these techniques with well-established biomedical simulation software.

UncertainSCI

All Builds Coverage Status status DOI

Overview

UncertainSCI is an open-source tool designed to make modern uncertainty quantification (UQ) techniques more accessible in biomedical simulation applications. UncertainSCI uses noninvasive UQ techniques, specifically polynomial Chaos estimation (PCE), with a similarly noninvasive interface to external modeling software that can be called in diverse ways. PCE and UncertainSCI allows users to propagate the effect of input uncertainty on model results, providing essential context for model stability and confidence needed in many modeling fields. Users can run UncertainSCI by setting input distributions for a model parameters, setting up PCE, sampling the parameter space, running the samples sets within the target model, and compiling output statistics based on PCE. This process is breifly describe in the getting started guide, and more fully explained in the API documentation, and supplied demos and tutorials.

Documentation

https://uncertainsci.readthedocs.io

Getting Started Guide

https://uncertainsci.readthedocs.io/en/latest/user_docs/getting_started.html

License

Distributed under the MIT license. See LICENSE for more information.

Publications

  • Akil Narayan, Zexin Liu, Jake Bergquist, Chantel Charlebois, Sumientra Rampersad, Lindsay Rupp, Dana Brooks, Dan White, Jess Tate, and Rob S MacLeod. UncertainSCI: Uncertainty quantification for com- putational models in biomedicine and bioengineering. Available at SSRN 4049696, 2022.
  • Kyle M. Burk, Akil Narayan, and Joseph A. Orr. Efficient sampling for polynomial chaos-based uncertainty quantification and sensitivity analysis using weighted approximate fekete points. International Journal for Numerical Methods in Biomedical Engineering, 36(11):e3395, 2020.
  • Jake Bergquist, Brian Zenger, Lindsay Rupp, Akil Narayan, Jess Tate, and Rob MacLeod. Uncertainty quantification in simulations of myocardial ischemia. In Computing in Cardiology, volume 48, September 2021.
  • Lindsay C Rupp, Jake A Bergquist, Brian Zenger, Karli Gillette, Akil Narayan, Jess Tate, Gernot Plank, and Rob S. MacLeod. The role of myocardial fiber direction in epicardial activation patterns via uncertainty quantification. In Computing in Cardiology, volume 48, September 2021.
  • Lindsay C Rupp, Zexin Liu, Jake A Bergquist, Sumientra Rampersad, Dan White, Jess D Tate, Dana H. Brooks, Akil Narayan, and Rob S. MacLeod. Using uncertainSCI to quantify uncertainty in cardiac simu- lations. In Computing in Cardiology, volume 47, September 2020.
  • Jess Tate, Sumientra Rampersad, Chantel Charlebois, Zexin Liu, Jake Bergquist, Dan White, Lindsay Rupp, Dana Brooks, Akil Narayan, and Rob MacLeod. Uncertainty quantification in brain stimulation using uncertainSCI. Brain Stimulation: Basic, Translational, and Clinical Research in Neuromodulation, 14(6):1659–1660, January 2021.
  • Jess D. Tate, Wilson W. Good, Nejib Zemzemi, Machteld Boonstra, Peter van Dam, Dana H. Brooks, Akil Narayan, and Rob S. MacLeod. Uncertainty quantification of the effects of segmentation variability in ECGI. In Functional Imaging and Modeling of the Heart, pages 515–522. Springer-Cham, Palo Alto, USA, 2021.
  • Jess D Tate, Nejib Zemzemi, Shireen Elhabian, Beáta Ondrusǔvá, Machteld Boonstra, Peter van Dam, Akil Narayan, Dana H Brooks, and Rob S MacLeod. Segmentation uncertainty quantification in cardiac propagation models. In 2022 Computing in Cardiology (CinC), volume 498, pages 1–4, 2022.

Acknowledgements

This project was supported by grants from the National Institute of Biomedical Imaging and Bioengineering (U24EB029012) from the National Institutes of Health.

uncertainsci's People

Contributors

akilnarayan avatar dcwhite avatar dependabot[bot] avatar jab0707 avatar jessdtate avatar kellyrowland avatar nids2001 avatar zexinliu avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

uncertainsci's Issues

Feature Request: Expose running of the pce emulator after it is built

I would like an easy way to run the PCE emulator once it has been created on any arbitrary new sample Iw ould like to examine. Something like this:

#For some modelFunction with three input parameters
pce.build()
newSample = np.array([0,5,2])
emulatorOutput = pce.emulator.sample(newSample)
modelOutput = modleFunction(newSample)
compareOutputs(emulatorOutput, modelOutput)

Fast idistinv for Jacobi Polys bug

The following script produces an x less than -1:

from UncertainSCI.families import JacobiPolynomials

J = JacobiPolynomials(alpha=1.553,beta=2.270)

u = 4.6808507655704545e-05
x = J.fidistinv(u, 0)

Probably a bug in how the degree-0 fast approximation is constructed.

Inverse induced distribution divide by zero

from families import JacobiPolynomials

J = JacobiPolynomials(alpha=0,beta=0)
J.idistinv(0,0)

should be -1, but throws a divide-by-zero error stemming from JacobiPolynomials.idist_medapprox

Discrete orthogonal polynomials (finite state space)

Implement generic univariate orthogonal polynomials for generic discrete distributions. Finite state space for now, so that we can easily do induced distribution stuff. Should support general probability mass function.

Infinite state space stuff (e.g., Poisson RV's et al) can be done later.

Checkpointing for looping of SCIRun calls

PolynomialChaosExpanation.build() doesn't have any way for the user to restart interrupted looping for model calls.

Also, user cannot get WAFP points and run model on their own.

Index set docs

Write basic technical documentation for HyperbolicCrossSet and LpSet.

Make updates on the branch index-set-docs that is already pushed to github. That branch has the TotalDegreeSet docs implemented for reference. See UncertainSCI/indexing.py.

To locally compile the documentation to check your changes, see https://uncertainsci.readthedocs.io/en/latest/dev_docs/HowToTutorial.html#testing-locally. After you re-build the documentation locally, your changes will appear in your local copy of the page https://uncertainsci.readthedocs.io/en/latest/api_docs/spaces.html

investigate rtd warnings

there are several warnings in the sphinx build, including missing references. These should trigger a build fail on PR.

Feature Request: Access PCE sample weights

I would like to be able to access the weights of the PCE samples that are used to make the emulator. Something like:

samples = pce.samples
weights = pce.weights
assert len(samples) == len(weights), "There should be one weight per sample"

Installing UncertainSCI

I am trying a minimal installation of UnvertainSCI but it fails.
Flowing the documentation python 3 should be used. The requirements need to be installed with pip and the package itself. The first observation is, that the python version 3.9 will fail to install the requirements. Thus, I use python version 3.8.
To install UncertainSCI, I use the official python 3.8 docker image and follow the instructions from your documentation. This results in the Dockerfile, which is saved in the root folder of this repo.

FROM python:3.8
RUN useradd -ms /bin/bash User # Add a user so we do not run as root
USER User
WORKDIR /home/User

COPY ./ /opt/UncertainSCI  # Let's assume we build from the root folder of the repo
COPY demos /home/User/code/demos # Copy them in a place which is accessible by the user

RUN pip install -r /opt/UncertainSCI/requirements.txt  # Install requirements
RUN pip install /opt/UncertainSCI/UncertainSCI # Install UncertainSCI
CMD python

I can build this Dockerfile, plus minus a few expected warnings

docker build -t uncertainsci ./

From the python console
docker run -it --rm uncertainsci:latest
I try to import UnvertainSCI

>>> import UncertainSCI.distributions
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ModuleNotFoundError: No module named 'UncertainSCI'
>>> 

Which is not available.

Using the same container, but with bash
docker run -it --rm uncertainsci:latest /bin/bash
and reinstalling UncertainSCI, shows first that it is already installed and then that, a reinstallation does not solve the problem.

The question is, where do I go wrong in the installation?

Quantiles float input

Inputting a float for a quantile level in PolynomialChaosExpansion.quantile produces an error. The intended input is a numpy array, but float should be casted on input.

setup file does not set the correct environment libraries

I am having issues installing the UncertainSCI package in my environment and running the demo examples.

After following the installation instructions in the documentation the UncrertainSCI package does not get installed in the environment.
To clarify, I ran the "pip install ." command without any errors being reported.
Afterwards, I tried running a demo script and ipython throws error when trying to load the packages:

  3 from scipy import sparse as sprs
  4  ##

----> 5 from UncertainSCI.families import JacobiPolynomials, HermitePolynomials, LaguerrePolynomials
6 from UncertainSCI.families import DiscreteChebyshevPolynomials
7 from UncertainSCI.opolynd import TensorialPolynomials

ModuleNotFoundError: No module named 'UncertainSCI'

I tried to install the software on two computers (mac and ubuntu), bith with python 3.8 installed

Any idea what could be the issue?

Thanks for your help!
Jaume

Demos docs

Documentation (text + pics walkthrough?) for

  • build_pce
  • build_pce_normal
  • discrete_uniform

Update documentation for setup.py

Issue solved.

The documentation is incorrect. The 'setup.py' file needs to be run from the root folder of the UncertainSCI tree. In the documentation it currently reads as it should be run from the UncertainSCI folder within the installation

Originally posted by @jcollfont in #83 (comment)

Software checklist/questions

  • Slack/Github integration. Send to separate channel?
  • Github action build. What tests to run?
  • Python version constraints?
  • Need a list of dependencies with versions
  • Branching model and team/collaborator permissions

Quantiles plotting issue

Plotting in quantiles demo doesn't properly reshape median arrays, resulting in matplotlib error
Screen Shot 2020-09-26 at 23 11 19

SCIRun module wrapper

We could keep the algorithm code in Python, and just write a C++ wrapper as a SCIRun module. The new looping framework in SCIRun would let the model be filled with whatever output data SCIRun can generate. When the SCIRun part is done, the output of this new module could be displayed with a Qwt graph module (replacing matplotlib).

Mean, cov, stdev statistics

Implement

  • mean
  • cov
  • stdev
  • pdf

methods for NormalDistribution, ExponentialDistribution, and DiscreteUniformDistribution. (For DiscreteUniformDistribution implement pmf instead of pdf.)

Jacobi induced distribution error

import numpy as np
from families import JacobiPolynomials

alpha = -0.95703125
beta = -0.8710937500000002

J = JacobiPolynomials(alpha=alpha,beta=beta)

print(J.idist(-1, 0)) # Should be 0

Outputs [0.11839635] instead of 0.

This also causes issues downstream when inverting these distributions. (Does the matlab code work for this case?)

Distribution Bounds not working correctly

The distribution bounds does not seem to actually scale the distribution from its default [0,1]. Example code below produces pce.samples that are [0,1].

dimension = 3
alpha = 2.#a = b = 2 makes a normal dist
beta = 2.
bounds = np.zeros([2,3])
bounds[0,0],bounds[1,0] = -3, 3
bounds[0,1],bounds[1,1] = -3, 3
bounds[0,2],bounds[1,2] = -3, 3

dist = BetaDistribution(alpha=alpha, beta=beta, dim=dimension,domain = bounds)

Distributions docs

Documentation for

  • ExponentialDistribution
  • GaussianDistribution
  • DiscreteChebyshevDistribution

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.