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

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, usage is very simple:

>>> 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 Jupyter notebook.

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.

The majority of the documentation that has been written for this package thus far is contained in the 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 document.

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. Citation information can also be exported from ADS (2022ascl.soft08005G) or the sidebar of this repository.