diff --git a/README.md b/README.md index 3402eb49..b7f7908e 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Scientific computations are surrounded by various forms of uncertainty, requiring appropriate treatment to maximise the credibility of computations. Empirical information is often scarce, vague, conflicting and imprecise, requiring expressive uncertainty structures for trustful representation, aggregation and propagation. -This package is underpinned by a framework of ***uncertain number*** which allows for a closed computation ecosystem whereby trustworthy computations can be conducted in a rigorous manner. It provides capabilities across the typical uncertainty analysis pipeline, encompassing characterisation, aggregation, propagation, and applications including reliability analysis and optimisation under uncertainty, especially with a focus on imprecise probabilities. +This package is underpinned by a framework of ***uncertain number*** which allows for a closed computation ecosystem whereby trustworthy computations can be conducted in a rigorous manner. It provides capabilities across the typical uncertainty analysis pipeline, encompassing characterisation, aggregation, propagation, model updating, and applications including reliability analysis and optimisation under uncertainty, especially with a focus on imprecise probabilities. > ***Uncertain Number*** refers to a generalised representation that unifies several uncertainty constructs including real numbers, intervals, probability distributions, interval bounds on probability distributions (i.e. [probability boxes](https://en.wikipedia.org/wiki/Probability_box)), and [finite DempsterShafer structures](https://en.wikipedia.org/wiki/Dempster–Shafer_theory). It is mostly suitable for managing mixed types of uncertainties. @@ -22,7 +22,7 @@ This package is underpinned by a framework of ***uncertain number*** which allow Explore the [documentation](https://pyuncertainnumber.readthedocs.io/en/latest/index.html) to get started, featuring hands-on [tutorials](https://pyuncertainnumber.readthedocs.io/en/latest/tutorials/index.html) and in-depth [examples](https://pyuncertainnumber.readthedocs.io/en/latest/examples/index.html) that showcase the power of the package. ->`pyuncertainnumber` exposes APIs at different levels. It features high-level APIs best suited for new users to quickly start with uncertainty computations with [*uncertain numbers*](https://pyuncertainnumber.readthedocs.io/en/latest/tutorials/what_is_un.html), and also low-level APIs allowing experts to have additional controls over mathematical constructs such as p-boxes, Dempster Shafer structures, probability distributions, etc. +>`pyuncertainnumber` [exposes APIs at different levels](file:///Users/lesliec/Documents/Github_repos/pyuncertainnumber/docs/_build/html/tutorials/getting_started.html). It features **high-level APIs** best suited for new users to quickly start with uncertainty computations with [*uncertain numbers*](https://pyuncertainnumber.readthedocs.io/en/latest/tutorials/what_is_un.html), and also **low-level APIs** allowing experts to have additional controls over mathematical constructs such as p-boxes, Dempster Shafer structures, probability distributions, etc. ## Installation @@ -47,8 +47,7 @@ pip install pyuncertainnumber ## UQ multiverse -UQ is a big world (like Marvel multiverse) consisting of abundant theories and software implementations on multiple platforms. We focus mainly on the imprecise probability frameworks. Some notable examples include [OpenCossan](https://github.com/cossan-working-group/OpenCossan), [UQlab](https://www.uqlab.com/) in Matlab and [UncertaintyQuantification.jl](https://github.com/FriesischScott/UncertaintyQuantification.jl), [ProbabilityBoundsAnalysis.jl](https://github.com/AnderGray/ProbabilityBoundsAnalysis.jl) in Julia, and many others of course. -`PyUncertainNumber` is rooted in Python and has close ties with the Python scientific computing ecosystem, it builds upon and greatly extends a few pioneering projects, such as [intervals](https://github.com/marcodeangelis/intervals), [scipy-stats](https://docs.scipy.org/doc/scipy/tutorial/stats.html) and [pba-for-python](https://github.com/Institute-for-Risk-and-Uncertainty/pba-for-python) to generalise probability and interval arithmetic. Beyond arithmetic, `PyUncertainNumber` has offered a wide spectrum of algorithms and methods for uncertainty characterisation, propagation, surrogate modelling, and optimisation under uncertainty, allowing imprecise uncertainty analysis in both intrusive and non-intrusive manner. `PyUncertainNumber` is under active development and will continue to be dedicated to support imprecise analysis in engineering using Python. +UQ is a big world (like Marvel multiverse) consisting of abundant theories and software implementations on multiple platforms. Some notable examples include [OpenCossan](https://github.com/cossan-working-group/OpenCossan) [UQlab](https://www.uqlab.com/) in Matlab and [ProbabilityBoundsAnalysis.jl](https://github.com/AnderGray/ProbabilityBoundsAnalysis.jl) in Julia, and many others of course. We focus mainly on the imprecise probability frameworks. `PyUncertainNumber` is rooted in Python and has close ties with the Python scientific computing ecosystem, it builds upon and greatly extends a few pioneering projects, such as [intervals](https://github.com/marcodeangelis/intervals), [scipy-stats](https://docs.scipy.org/doc/scipy/tutorial/stats.html) and [pba-for-python](https://github.com/Institute-for-Risk-and-Uncertainty/pba-for-python) to generalise probability and interval arithmetic. Beyond arithmetic calculations, `PyUncertainNumber` has offered a wide spectrum of algorithms and methods for uncertainty characterisation, propagation, surrogate modelling, and optimisation under uncertainty, allowing imprecise uncertainty analysis in both intrusive and non-intrusive manner. `PyUncertainNumber` is under active development and will continue to be dedicated to support imprecise analysis in engineering using Python. ## Citation diff --git a/docs/source/_static/distribution_expert.png b/docs/source/_static/distribution_expert.png new file mode 100644 index 00000000..14cd1601 Binary files /dev/null and b/docs/source/_static/distribution_expert.png differ diff --git a/docs/source/_static/pbox_array.png b/docs/source/_static/pbox_array.png new file mode 100644 index 00000000..1b40017e Binary files /dev/null and b/docs/source/_static/pbox_array.png differ diff --git a/docs/source/_static/pbox_imprecise_measurements.png b/docs/source/_static/pbox_imprecise_measurements.png new file mode 100644 index 00000000..48e55a05 Binary files /dev/null and b/docs/source/_static/pbox_imprecise_measurements.png differ diff --git a/docs/source/_static/propagation_flowchart.png b/docs/source/_static/propagation_flowchart.png new file mode 100644 index 00000000..9541b92e Binary files /dev/null and b/docs/source/_static/propagation_flowchart.png differ diff --git a/docs/source/_static/uc_diagram_smaller.png b/docs/source/_static/uc_diagram_smaller.png new file mode 100644 index 00000000..54cd59a8 Binary files /dev/null and b/docs/source/_static/uc_diagram_smaller.png differ diff --git a/docs/source/examples/calibration/2dof_tmcmc_demo.ipynb b/docs/source/examples/calibration/2dof_tmcmc_demo.ipynb index 1995d3a4..5676108c 100644 --- a/docs/source/examples/calibration/2dof_tmcmc_demo.ipynb +++ b/docs/source/examples/calibration/2dof_tmcmc_demo.ipynb @@ -160,30 +160,16 @@ " # standard deviations (5% noise on true eigenvalues λ1=0.382, λ2=2.618)\n", " sig1 = 0.0191 # 0.05 * 0.382\n", " sig2 = 0.1309 # 0.05 * 2.618\n", - "\n", - " # compute eigenvalues λ1(q1, q2) and λ2(q1, q2) for the 2×2 system\n", - " # characteristic equation: λ^2 - (q1 + 2 q2) λ + q1 q2 = 0\n", - " # closed-form solution:\n", - " # λ₁,₂ = (q1/2 + q2) ∓ sqrt((q1/2 + q2)^2 - q1 q2)\n", " center = q1 / 2.0 + q2\n", " disc = center**2 - q1 * q2\n", " if disc < 0:\n", - " # if the discriminant is negative, eigenvalues are complex -> impossible here physically\n", - " # give a very low likelihood\n", " return -np.inf\n", "\n", " sqrt_disc = np.sqrt(disc)\n", " lambda1_s = center - sqrt_disc\n", " lambda2_s = center + sqrt_disc\n", "\n", - " # Gaussian likelihood for 5 measurements of λ1 and 5 of λ2\n", - " # p(d | θ) ∝ exp( -1/(2σ1²) Σ (λ1_s - d1_m)² - 1/(2σ2²) Σ (λ2_s - d2_m)² )\n", - " # log p(d | θ) = const - 0.5/σ1² Σ (λ1_s - d1_m)² - 0.5/σ2² Σ (λ2_s - d2_m)²\n", - "\n", - " # constant term (same form as in your Case 3 implementation)\n", " const_term = np.log((2 * np.pi * sig1 * sig2) ** -5)\n", - "\n", - " # misfit terms\n", " misfit1 = -0.5 * (sig1**-2) * np.sum((lambda1_s - data1) ** 2)\n", " misfit2 = -0.5 * (sig2**-2) * np.sum((lambda2_s - data2) ** 2)\n", "\n", diff --git a/docs/source/examples/characterisation/characterise_what_you_know.ipynb b/docs/source/examples/characterisation/characterise_what_you_know.ipynb index 0f22d951..1fd567cd 100644 --- a/docs/source/examples/characterisation/characterise_what_you_know.ipynb +++ b/docs/source/examples/characterisation/characterise_what_you_know.ipynb @@ -23,7 +23,7 @@ "metadata": {}, "source": [ "
\n", - " \n", + " \n", "
Empirical knowledge serving as constraints in characterising an uncertain number
\n", "
" ] diff --git a/docs/source/examples/characterisation/example_dependency_dev_purpose.ipynb b/docs/source/examples/characterisation/example_dependency_dev_purpose.ipynb index 50eafe07..5c4964f0 100644 --- a/docs/source/examples/characterisation/example_dependency_dev_purpose.ipynb +++ b/docs/source/examples/characterisation/example_dependency_dev_purpose.ipynb @@ -37,7 +37,7 @@ "metadata": {}, "source": [ "
\n", - " \n", + " \n", "
Dependency structures
\n", "
" ] diff --git a/docs/source/examples/characterisation/repeated_variable.ipynb b/docs/source/examples/characterisation/repeated_variable.ipynb index 2712fc6d..90218e21 100644 --- a/docs/source/examples/characterisation/repeated_variable.ipynb +++ b/docs/source/examples/characterisation/repeated_variable.ipynb @@ -147,7 +147,7 @@ "\n", "\n", "
\n", - " \n", + " \n", "
\n", "\n", "Mathematically, under ordinary arithmetic, we can write in a few equivalent manners:\n", diff --git a/docs/source/guides/uc.md b/docs/source/guides/uc.md index 68ead84c..f1eec8c2 100644 --- a/docs/source/guides/uc.md +++ b/docs/source/guides/uc.md @@ -1,22 +1,20 @@ # Uncertainty characterisation -### variability and incertitude +## Variability and incertitude -Modern risk analysts distinguish between variability and incertitude. Variability (also called randomness, aleatory uncertainty, or irreducible uncertainty) arises from natural stochasticity, environmental or structural variation across space or time, manufacturing heterogeneity among components or individuals. Incertitude, also called ignorance, epistemic uncertainty, subjective uncertainty or reducible uncertainty, arises from incompleteness of knowledge. Sources of incertitude include measurement uncertainty, small sample sizes, and data censoring, ignorance about the details of physical mechanisms and processes. +Modern risk analysts distinguish between variability and incertitude. ***Variability*** (also called randomness, aleatory uncertainty, or irreducible uncertainty) arises from natural stochasticity, environmental or structural variation across space or time, manufacturing heterogeneity among components or individuals. ***Incertitude***, also called ignorance, epistemic uncertainty, subjective uncertainty or reducible uncertainty, arises from incompleteness of knowledge. Sources of incertitude include measurement uncertainty, small sample sizes, and data censoring, ignorance about the details of physical mechanisms and processes. -For an engineering analysis, the **challenge** lies in formulating suitable uncertainty models given available information, **without introducing unwarranted assumptions**. However, the available information is often vague, ambiguous, or qualitive. Available data are frequently limited and of poor quality, giving rise to challenges in eliciting precise probabilistic specifications. Solutions to this problem are discussed in the literature, under the framework of imprecise probability, from various perspectives using different mathematical concepts, including for example random sets, evidence theory, fuzzy stochastic concepts, info-gap theory, and probability bounds analysis. +For an engineering analysis, the **challenge** lies in formulating suitable uncertainty models given available information, **without introducing unwarranted assumptions**. However, the available information is often vague, ambiguous, or qualitative. Available data are frequently limited and of poor quality, giving rise to challenges in eliciting precise probabilistic specifications. Solutions to this problem are discussed in the literature, under the framework of imprecise probability, from various perspectives using different mathematical concepts, including for example random sets, evidence theory, fuzzy stochastic concepts, info-gap theory, and probability bounds analysis. ```{tip} It is suggested to use interval analysis for propagating ignorance and the methods of probability theory for propagating variability. ``` -```{seealso} -See also in the [propagation](./up.md) -``` -### bounding distributional parameters -The mean of a normal distribution may be elicited from an expert but this expert cannot be precise to a certain value but rather give a range based on past experience. +## Bounding distributional parameters + +The mean of a normal distribution may be elicited from an expert, but this expert cannot be precise to a certain value but rather give a range based on past experience. ````{tab} verbose To comprehensively characterise a pbox, specify the bounds for the parameters along with many other ancillary fields. @@ -42,21 +40,39 @@ un = pun.norm([0,12],[1,4]) ``` ```` -```{tip} -shortcut may not work for some distribution families at the moment as an internal restructure is underway. Use the canonical verbose constructor for best compatibility. -``` -### aggregation of multiple sources of information +````{tab} pba API +For low-level controls and customisation -Expert elicitation has been a challenging topic, especially when knowledge is limited and measurements are sparse. Multiple experts may not necessarily agree on the choice of elicited prbability distributions, which leads to the need for aggregation. Below shows two situations for illustration. +```python +from pyuncertainnumber import pba +pbox = pba.normal([0,12],[1,4]) +``` +```` -Assume the expert opinions are expressed in closed intervals. There may well be multiple such intervals from different experts and these collections of interval can be overlapping, partially contradictory or even completely contradictory. Their relative credibility may be expressed in probabilities. Essentially such information creates a **Dempster-Shafer structure**. On the basis of a mixture operation, such information can be aggregated into a **pbox**. ```{tip} The different sub-types of uncertain number can normally convert to one another (though may not be one by one), ergo the uncertain number been said to be a unified representation. ``` -Pbox arithmetic also extends the convolution of probability distributions which has typically been done with the independence assumption. However, often in engineering modelling practices independence is assumed for mathematical easiness rather than warranted. Fortunately, the uncertainty about the dependency between random variables can be characterised by the probability bounds, as seen below. It should be noted that such dependency bound does not imply independence. +```{seealso} +See also the tutorial the [What is an uncertain number](https://pyuncertainnumber.readthedocs.io/en/latest/tutorials/what_is_un.html) to get started. +``` + + +## Aggregation of multiple sources of information + +Expert elicitation has been a challenging topic, especially when knowledge is limited and measurements are sparse. Multiple experts may not necessarily agree on the choice of elicited probability distributions, which leads to the need for aggregation. Below shows two situations for illustration. + +Assume the expert opinions are expressed in closed intervals. There may well be multiple such intervals from different experts and these collections of intervals can be overlapping, partially contradictory or even completely contradictory. Their relative credibility may be expressed in probabilities. Essentially such information creates a **Dempster-Shafer structure**. On the basis of a mixture operation, such information can be aggregated into a **p-box**. + +```{seealso} +See also the tutorial [uncertainty aggregation](https://pyuncertainnumber.readthedocs.io/en/latest/tutorials/uncertainty_aggregation.html) to get started. +``` + +## Inter-variable dependence + +P-box arithmetic also extends the convolution of probability distributions which has typically been done with the independence assumption. However, often in engineering modelling practices independence is assumed for mathematical easiness rather than warranted. Fortunately, the uncertainty about the dependency between random variables can be characterised by the probability bounds, as seen below. It should be noted that such dependency bound does not imply independence. ```{image} ../../../assets/addition_bound.png :alt: sum of two random variables without dependency specification @@ -66,8 +82,13 @@ Pbox arithmetic also extends the convolution of probability distributions which The sum of two random variables of lognormal distribution without dependency specification ``` +```{seealso} +See also the tutorial [depenency structure](https://pyuncertainnumber.readthedocs.io/en/latest/examples/characterisation/example_dependency_dev_purpose.html) to get started . +``` + -### known statistical properties + +## Known statistical properties When the knowledge of a quantity is limited to the point where only some statistical information is available, such as the *min*, *max*, *median* etc. but not about the distribution and parameters, such partial information can serve as **constraints** to bound the underlying distribution: @@ -78,9 +99,14 @@ When the knowledge of a quantity is limited to the point where only some statist :align: center ``` -### hedged numerical expression +```{seealso} +See also the tutorial [characterise as you go](https://pyuncertainnumber.readthedocs.io/en/latest/examples/characterisation/characterise_what_you_know.html) to get started. +``` + -Sometimes only purely qualitive information is available. An important part of processing elicited numerical inputs is an ability to quantitatively decode natural-language words, the linguistic information, that are commonly used to express or modify numerical values. Some example include ‘about’, ‘around’, ‘almost’, ‘exactly’, ‘nearly’, ‘below’, ‘at least’, ‘order of’, etc. A numerical expression with these approximators are called *hedges*. Extending upon the significant-digit convention, a series of interval interpretations of common hedged numerical expressions are proposed. +## Hedged numerical expression + +Sometimes only purely qualitative information is available. An important part of processing elicited numerical inputs is an ability to quantitatively decode natural-language words, the linguistic information, that are commonly used to express or modify numerical values. Some examples include ‘about’, ‘around’, ‘almost’, ‘exactly’, ‘nearly’, ‘below’, ‘at least’, ‘order of’, etc. A numerical expression with these approximators are called *hedges*. Extending upon the significant-digit convention, a series of interval interpretations of common hedged numerical expressions are proposed. ```{image} ../../../assets/interval_hedge.png :alt: interval hedges @@ -107,7 +133,12 @@ pun.hedge_interpret('about 200', return_type='pbox').display() hedged numerical expression "about 200" ``` -### data uncertainty +```{seealso} +See also the tutorial [Interpret linguistic hedges](https://pyuncertainnumber.readthedocs.io/en/latest/examples/characterisation/linguistic_approximation.html) to get started. +``` + + +## Data uncertainty Measurement uncertainty is another main source uncertainty of data uncertainty besides sampling uncertainty. Point estimates from samples vary from one to another. We will typically use confidence intervals (as interval estimators) to account for the sampling uncertainty. As an example, `PyUncertainNumber` provides support for Kolmogorov–Smirnov (KS) confidence limits to infer the confidence limits for empirical cumulative distribution function. @@ -115,7 +146,7 @@ Measurement uncertainty is another main source uncertainty of data uncertainty b See also the [confidence box](../cbox.md) for a distributional estimator. ``` -As to measurement uncertainty, `Intervals` turn out to be a natural means of mathematical construct for imprecise data due to the common understanding of margin of error, which leads to the midpoint notation of an interval object. `PyUncertainNumber` provides an extension of the Kolmogorov–Smirnov confidence limits for interval-valued data as well. [](#KS-bounds-imprecise) shows such confidence limits for the skinny data. +As to measurement uncertainty, `Intervals` turn out to be a natural means of mathematical construct for imprecise data due to the common understanding of margin of error, which leads to the midpoint notation of an interval object. `PyUncertainNumber` provides an extension of the Kolmogorov–Smirnov confidence limits for interval-valued data as well. The lower figure shows such confidence limits for the skinny data. ```{figure} ../../../assets/ks_precise.png :alt: Kolmogorov–Smirnov bounds for precise data @@ -130,3 +161,4 @@ As to measurement uncertainty, `Intervals` turn out to be a natural means of mat :align: center :width: 400px ``` + diff --git a/docs/source/guides/up.md b/docs/source/guides/up.md index 05971b43..7f6c9e4a 100644 --- a/docs/source/guides/up.md +++ b/docs/source/guides/up.md @@ -6,13 +6,13 @@ Methods to efficiently propagate different types of uncertainty through computat It is suggested to use [interval analysis](../interval_analysis.md) for propagating ignorance and the methods of probability theory for propagating variability. But realistic engineering problems or risk analyses will most likely involve a mixture of both types and as such probability bounds analysis provides means to rigourously propagate the uncertainty. -For aleatoric uncertainty, probability theory already provides some established approaches, such as Taylor expansion or sampling methods, etc. This guide will mostly focuses on the propagation of intervals due to the close relations with propagation of p-boxes. A detailed review can be found in this [report](https://sites.google.com/view/dawsreports/up/report). Importantly, see {ref}`up` for a hands-on tutorial. +For aleatory uncertainty, probability theory already provides some established approaches, such as Taylor expansion or sampling methods, etc. This guide will mostly focuses on the propagation of intervals due to the close relations with propagation of p-boxes. A detailed review can be found in this [report](https://sites.google.com/view/dawsreports/up/report). Importantly, see {ref}`up` for a hands-on tutorial. -### Vertex method +## Vertex method The vertex propagation method {cite:p}`DONG198765` is a straightforward way to project intervals through the code, by projecting a number of input combinations given by the Cartesian product of the interval bounds. This results in a total of $n=2d$ evaluations, where $d$ is the number of interval-valued parameters. In the case of two intervals, $[x]$ and $[y]$, the code, $f(·)$ must be evaluated four times at all endpoints. The main advantage of the method is its simplicity. But it should be used under the assumption of monotonicity. -### Subinterval reconstitution +## Subinterval reconstitution To accommodate the presence of non-monotonic trends, the input intervals can be partitioned into smaller intervals, which can then be propagated through the model using vertex propagation and an output interval can be reassembled. The logic behind this method is that even though the code may not be monotonic over the full width of the interval, it will likely behave monotonically on a smaller interval, provided the underlying function is pathologically rough. Thus, output intervals for even highly non-linear functions can be computed to arbitrary reliability. @@ -23,11 +23,11 @@ $$ where $\cup_{j=1}^{n} X_{j} = X$ and $F$ denotes an interval extension of $f$. -### Cauchy-deviate method +## Cauchy-deviate method Similar to the Monte Carlo methods, the Cauchy-deviate method {cite:p}`KREINOVICH2004267` is also built upon the direct sampling of uncertain input numbers expressed as intervals. This makes it suitable for propagating epistemic uncertainty through black-box models. For each uncertain number, the method generates random samples from a Cauchy distribution and computes the width of the output interval through appropriate scaling of these samples. If the model has more than one input, the errors in each are considered independent at the sampling step. By generating samples outside of the input interval bounds, the Cauchy-deviate method explicitly includes those bounds via normalisation, thus solving one of the problems classical sampling methods face when used to propagate epistemic uncertainty. -### Gradient-based optimisation methods +## Gradient-based optimisation methods In general cases, interval propagation problem can be casted as an optimisation problem. These methods, gradients-based or gradients-free, would often start with a set of initial input values and by searching for new candidates which yield better solutions than the previous iterations find an optimum solution. Key characteristic of these methods is that, for each iteration, the search for better solution is local, in other words it takes place in the immediate neighbourhood of the input values used in the previous iteration, leading to a local optimum solution. diff --git a/docs/source/index.md b/docs/source/index.md index 682780a3..019fd239 100755 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -45,7 +45,7 @@ autoapi/index
-This package is underpinned by a framework of **uncertain numbers** which allows for a closed computation ecosystem whereby trustworthy computations can be conducted in a rigorous manner. It provides capabilities across the typical uncertainty analysis pipeline, encompassing uncertainty characterisation, aggregation, propagation, and applications including reliability analysis and optimisation under uncertainty, especially with a focus on imprecise probabilities. +This package is underpinned by a framework of **uncertain numbers** which allows for a closed computation ecosystem whereby trustworthy computations can be conducted in a rigorous manner. It provides capabilities across the typical uncertainty analysis pipeline, encompassing uncertainty characterisation, aggregation, propagation, model updating, and applications including reliability analysis and optimisation under uncertainty, especially with a focus on imprecise probabilities. ```{note} **Uncertain Number** refers to a class of mathematical objects useful for risk analysis that generalize real numbers, intervals, probability distributions, interval bounds on probability distributions (i.e. [probability boxes](https://en.wikipedia.org/wiki/Probability_box)), and [finite DempsterShafer structures](https://en.wikipedia.org/wiki/Dempster–Shafer_theory). Refer to the [source code repository](https://github.com/leslieDLcy/PyUncertainNumber) of this package for additional introduction. @@ -59,7 +59,7 @@ This package is underpinned by a framework of **uncertain numbers** which allows - `PyUncertainNumber` is a Python package for generic computational tasks focussing on **rigorous uncertainty analysis**, which provides a research-grade computing environment for uncertainty characterisation, propagation, validation and uncertainty extrapolation. - `PyUncertainNumber` supports [probability bounds analysis](https://en.wikipedia.org/wiki/Probability_bounds_analysis) to rigorously bound the prediction for the quantity of interest with mixed uncertainty propagation. -- `PyUncertainNumber` also features great **natural language support** as such characterisatin of input uncertainty can be intuitively done by using natural language like `about 7` or simple expression like `[15 +- 10%]`, without worrying about the elicitation. +- `PyUncertainNumber` also features great **natural language support** as such characterisation of input uncertainty can be intuitively done by using natural language like `about 7` or simple expression like `[15 +- 10%]`, without worrying about the elicitation. - Interoperability via serialization: features the save and loading of Uncertain Number objects to work with downstream applications. - Yields informative results during the computation process such as the combination that leads to the maximum in vertex method. @@ -111,9 +111,15 @@ response = p.run(n_slices=50) The libary is under active develpment, so APIs will change across different versions. ``` +```{tip} +If looking for deeper controls and customisation, refer to the [Low-level `pba` APIs](https://pyuncertainnumber.readthedocs.io/en/latest/tutorials/getting_started.html#low-level-pba-apis) + for advanced usage. +``` + + ## Installation -```{tip} +```{note} - See [installation](./guides/installation.md) for additional details. - **Requirement:** Python >=3.11 ``` @@ -127,8 +133,7 @@ pip install pyuncertainnumber ## UQ multiverse -UQ is a big world (like Marvel multiverse) consisting of abundant theories and software implementations on multiple platforms. We focus mainly on the imprecise probability frameworks. Some notable examples include [OpenCossan](https://github.com/cossan-working-group/OpenCossan) [UQlab](https://www.uqlab.com/) in Matlab and [ProbabilityBoundsAnalysis.jl](https://github.com/AnderGray/ProbabilityBoundsAnalysis.jl) in Julia, and many others of course. -`PyUncertainNumber` is rooted in Python and has close ties with the Python scientific computing ecosystem, it builds upon and greatly extends a few pioneering projects, such as [intervals](https://github.com/marcodeangelis/intervals), [scipy-stats](https://docs.scipy.org/doc/scipy/tutorial/stats.html) and [pba-for-python](https://github.com/Institute-for-Risk-and-Uncertainty/pba-for-python) to generalise probability and interval arithmetic. Beyond arithmetic, `PyUncertainNumber` has offered a wide spectrum of algorithms and methods for uncertainty characterisation, propagation, surrogate modelling, and optimisation under uncertainty, allowing imprecise uncertainty analysis in both intrusive and non-intrusive manner. `PyUncertainNumber` is under active development and will continue to be dedicated to support imprecise analysis in engineering using Python. +UQ is a big world (like Marvel multiverse) consisting of abundant theories and software implementations on multiple platforms. Some notable examples include [OpenCossan](https://github.com/cossan-working-group/OpenCossan) [UQlab](https://www.uqlab.com/) in Matlab and [ProbabilityBoundsAnalysis.jl](https://github.com/AnderGray/ProbabilityBoundsAnalysis.jl) in Julia, and many others of course. We focus mainly on the imprecise probability frameworks. `PyUncertainNumber` is rooted in Python and has close ties with the Python scientific computing ecosystem, it builds upon and greatly extends a few pioneering projects, such as [intervals](https://github.com/marcodeangelis/intervals), [scipy-stats](https://docs.scipy.org/doc/scipy/tutorial/stats.html) and [pba-for-python](https://github.com/Institute-for-Risk-and-Uncertainty/pba-for-python) to generalise probability and interval arithmetic. Beyond arithmetic calculations, `PyUncertainNumber` has offered a wide spectrum of algorithms and methods for uncertainty characterisation, propagation, surrogate modelling, and optimisation under uncertainty, allowing imprecise uncertainty analysis in both intrusive and non-intrusive manner. `PyUncertainNumber` is under active development and will continue to be dedicated to support imprecise analysis in engineering using Python. ## Acknowledgements diff --git a/docs/source/tutorials/index.md b/docs/source/tutorials/index.md index 06c74d66..7afd81bf 100644 --- a/docs/source/tutorials/index.md +++ b/docs/source/tutorials/index.md @@ -19,31 +19,35 @@ uncertainty_propagation :::{card} Getting started :link: getting_started :link-type: doc +:img-top: ../_static/propagation_flowchart.png Getting started with PyUncertainNumber and basic workflows. ::: :::{card} What is UN? :link: what_is_un :link-type: doc -:img-top: ../_static/what_is_un.png +:img-top: ../_static/uc_diagram_smaller.png An introduction to uncertain numbers and their representations. ::: :::{card} Uncertainty characterisation :link: uncertainty_characterisation :link-type: doc +:img-top: ../_static/pbox_imprecise_measurements.png Methods for characterising and representing uncertainty in data. ::: :::{card} Uncertainty aggregation :link: uncertainty_aggregation :link-type: doc +:img-top: ../_static/distribution_expert.png Techniques for combining multiple sources of uncertainty. ::: :::{card} Uncertainty propagation :link: uncertainty_propagation :link-type: doc +:img-top: ../_static/pbox_array.png Propagate uncertainty through computational models and functions. ::: diff --git a/pyproject.toml b/pyproject.toml index 68154f1f..c3deee3e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,7 +38,7 @@ maintainers = [ name = "pyuncertainnumber" readme = "README.md" requires-python = ">= 3.11" -version = "0.1.3" +version = "0.1.4" [project.optional-dependencies] test = [ diff --git a/src/pyuncertainnumber/calibration/epistemic_filter.py b/src/pyuncertainnumber/calibration/epistemic_filter.py index 18f2f3ed..8f34cd85 100644 --- a/src/pyuncertainnumber/calibration/epistemic_filter.py +++ b/src/pyuncertainnumber/calibration/epistemic_filter.py @@ -9,6 +9,29 @@ class EpistemicFilter: + """The EpistemicFilter method to reduce the epistemic uncertainty space based on discrepancy scores. + + args: + xe_samples (NDArray): Proposed Samples of epistemic parameters, shape (ne, n_dimensions). + Typically samples from a bounded set of some epistemic parameters. + + discrepancy_scores (NDArray, optional): Discrepancy scores between the model simulations and the observation. + Associated with each xe sample, shape (ne,). Defaults to None. + + sets_of_discrepancy (list, optional): List of sets of discrepancy scores for multiple datasets. + Each element should be an NDArray of shape (ne,). Defaults to None. + + tip: + For performance functions that output multiple responses, some aggregation of discrepancy scores may be used. + Depending on the number of observation, either a single set of discrepancy scores or multiple sets can be provided. + + .. figure:: /_static/convex_hull.png + :alt: convex hull with bounds + :align: center + :width: 50% + + Convex hull with bounds illustration. + """ def __init__( self, @@ -16,29 +39,7 @@ def __init__( discrepancy_scores: NDArray = None, sets_of_discrepancy: list = None, ): - """The EpistemicFilter method to reduce the epistemic uncertainty space based on discrepancy scores. - args: - xe_samples (NDArray): Proposed Samples of epistemic parameters, shape (ne, n_dimensions). - Typically samples from a bounded set of some epistemic parameters. - - discrepancy_scores (NDArray, optional): Discrepancy scores between the model simulations and the observation. - Associated with each xe sample, shape (ne,). Defaults to None. - - sets_of_discrepancy (list, optional): List of sets of discrepancy scores for multiple datasets. - Each element should be an NDArray of shape (ne,). Defaults to None. - - tip: - For performance functions that output multiple responses, some aggregation of discrepancy scores may be used. - Depending on the number of observation, either a single set of discrepancy scores or multiple sets can be provided. - - .. figure:: /_static/convex_hull.png - :alt: convex hull with bounds - :align: center - :width: 50% - - Convex hull with bounds illustration. - """ self.xe_samples = xe_samples self.discrepancy_scores = discrepancy_scores self.sets_of_discrepancy = ( diff --git a/src/pyuncertainnumber/calibration/tmcmc.py b/src/pyuncertainnumber/calibration/tmcmc.py index 5df29c3e..ed0f9ae6 100644 --- a/src/pyuncertainnumber/calibration/tmcmc.py +++ b/src/pyuncertainnumber/calibration/tmcmc.py @@ -53,6 +53,7 @@ class TMCMC: >>> from pyuncertainnumber import pba >>> # create an instance of TMCMC class and run tmcmc >>> parameters = [pba.D("uniform", (0.8, 2.2)), pba.D("uniform", (0.4, 1.2))] # dummy prior distributions + >>> t = TMCMC( >>> N=1000, # number of particles >>> parameters=parameters, # prior distributions @@ -68,6 +69,7 @@ class TMCMC: >>> with open('tmcmc_trace.pkl', 'rb') as f: >>> mytrace = pickle.load(f) >>> re = TMCMC(trace=mytrace, names=names) # create TMCMC instance with loaded trace and names + >>> re.plot_updated_distribution(save=False) # plot prior and posterior distribution >>> prior_samples = re.load_prior_samples() # load prior samples as DataFrame >>> posterior_samples = re.load_posterior_samples() # load posterior samples as DataFrame