How to use the Uncertain type

The uncertain type is implemented as a CPython extension type, as such it may be used like any other native python type. The following import is required to follow the examples presented in this section:

from numcertain import uncertain

Creating an uncertain value

An uncertain value may be created with use of the uncertain object imported via numcertain. Several examples of uncertain value instantiation are shown below.

Ideally, an uncertain value is created by passing a expectation and standard deviation as floating point values. Thus an uncertain value with an expectation of 42 and standard deviation of 12.7 should be created as follows:

x = uncertain(42.0, 12.7)
print(x)

>> 42.0±12.7

If given two integer values, the library will cast these to floating point numbers. As such, an uncertain value with an expectation of 36 and standard deviation of 8 could be created as follows:

x = uncertain(36, 8)
print(x)

>> 36.0±8.0

Uncertain values may also be created with a single value, in which case it is treated as the expectation and a standard deviation of zero is applied. E.g.:

x = uncertain(87)
print(x)

>> 87.0±0.0

Converting to an uncertain value

It is also possible to convert pre-existing floating point or integer values to the uncertain data type via casting, in such cases the value is treated as the expectation and a standard deviation of zero is applied. This is performed with the usual python syntax, as:

x = 3.14
y = (uncertain)(x)
print(y)

>> 3.14±0.0

Displaying an uncertain value

Printing an uncertain value will use the built in string representation (__str__) which stringifies the value in the format expectance ± standard deviation, as:

x = uncertain(42.0, 12.7)
print(x)

Which will produce the following output:

>> 42.0±12.7

You may also wish to display the full object representation (__repr__) of an uncertain value, this can be done by calling the repr method on the value, as:

x = uncertain(42.0, 12.7)
print(repr(x))

Which will produce the following output:

>> uncertain(42.0, 12.7)

Retrieving expectance or standard deviation

It is likely you will wish at some point to reteieve either the expectance or standard deviation of the uncertain value in isolation; In order to do this we simply query the nominal and uncertainity attributes respectively, as:

x = uncertain(42.0, 12.7)
print(x.nominal)
print(x.uncertainty)

>> 42.0
>> 12.7

Arithmetic with uncertain values

It is likely you will wish to perform arethemtic operations on uncertain values, these may be performed as normal for numeric python types (i.e. with use of the +, -, * & / operators). An example of such is shown below:

a = uncertain(42.0, 5.0)
b = uncertain(36, 12)

print(a + b)
print(a - b)
print(a * b)
print(a / b)

>> 78.0±13.0
>> 6.0±13.0
>> 1512.0±535.1784749034662
>> 1.1666666666666667±0.41294635409218067

Note

See: Uncertainty Propagation Explained for details of how the uncertainty propagation math is performed.