https://github.com/cgobat/asymmetric_uncertainty
A package for handling numeric quantities with asymmetric uncertainties.
https://github.com/cgobat/asymmetric_uncertainty
error-analysis error-propagation python uncertainty-propagation
Last synced: 6 months ago
JSON representation
A package for handling numeric quantities with asymmetric uncertainties.
- Host: GitHub
- URL: https://github.com/cgobat/asymmetric_uncertainty
- Owner: cgobat
- License: gpl-3.0
- Created: 2022-07-09T05:28:45.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-01-11T01:16:57.000Z (almost 2 years ago)
- Last Synced: 2024-08-03T15:06:36.555Z (about 1 year ago)
- Topics: error-analysis, error-propagation, python, uncertainty-propagation
- Language: Jupyter Notebook
- Homepage: https://github.com/cgobat/asymmetric_uncertainty/wiki
- Size: 201 KB
- Stars: 17
- Watchers: 3
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Citation: CITATION.bib
- Support: supporting_matl.md
Awesome Lists containing this project
README
# Asymmetric Uncertainty
[](https://opensource.org/licenses/GPL-3.0) [](https://github.com/cgobat/asymmetric_uncertainty/actions)  [](https://ascl.net/2208.005)
Many values and quantities in science and engineering have associated uncertainties—for example, $3.0\pm0.3$ expresses a quantity whose measured or expected value is 3.0, but might reasonably be expected[^1] to have a true value anywhere between 2.7 and 3.3. This is a *symmetric* uncertainty, because the error is the same to either side of the central value. However, not all numbers behave this way: for example, we could write $3.0_{-0.4}^{+0.2}$ to signify that although the expected value is 3.0 as well, the magnitude of the uncertainty to the left and right of this value are not equivalent.
## Usage
This repository contains the `asymmetric_uncertainty` Python package, which provides the `a_u` class for dealing with these kinds of numbers in practice. After [installation](#installation), usage is very simple:
```python
>>> from asymmetric_uncertainty import a_u
>>> x = a_u(3.0, 0.2, 0.4)
>>> print(x + 1)
```
```
4.0 (+0.2, -0.4)
```
Here we see how to create an instance of the class representing the example number given before: $3.0_{-0.4}^{+0.2}$. The initialization arguments are the nominal value, positive error, and negative error—in that order. `x` will play nicely with other numeric objects under most mathematical operations, and its errors will propagate appropriately. More complete examples can be found in the [`example.ipynb`](./example.ipynb) Jupyter notebook.
## Installation
If you have a local installation of Git, you can install this package with a single command: run `pip install git+https://github.com/cgobat/asymmetric_uncertainty.git` to install the latest version.
Otherwise, clone/download this repository, then (from a command line running within the associated directory) run `pip install .` or `python setup.py install`.
`asymmetric_uncertainty` should then be available as a module that you can import like any other.
## Documentation
The majority of the documentation that has been written for this package thus far is contained in the [wiki](../../wiki) associated with this repository. Supplemental information, such as related works, the mathematical basis of this implementation, and further background reading, can be found in the [supporting materials](./supporting_matl.md) document.
## [Citing this project](./CITATION.bib)
If you make use of this package in your own work, please cite it by referencing its entry in ASCL, the Astrophysics Source Code Library: [ascl:2208.005](http://ascl.net/2208.005). Citation information can also be exported from ADS ([2022ascl.soft08005G](https://ui.adsabs.harvard.edu/abs/2022ascl.soft08005G/exportcitation)) or the sidebar of this repository.
[^1]: Definitions and conventions for what this means vary. Common uses/interpretations include standard deviation, standard deviation divided by the square root of the number of samples (often called standard error), 90% confidence interval, etc. As long as usage is consistent and intentions are clear, any of these are valid.