samirelanduk / fuzz

A lightweight Python utility providing values with associated uncertainty

fuzz

fuzz is a lightweight Python utility providing values with associated uncertainty.

Example

>>> import fuzz
>>> value1 = fuzz.Value(23, error=0.3)
>>> value2 = fuzz.Value(28, error=1.3)
>>> value1
23 ± 0.3
>>> value2
28 ± 1.3
>>> value1 + value2
51 ± 1.3341664064126335

Installing

pip

fuzz can be installed using pip:

$ pip3 install fuzz

fuzz is written for Python 3, and does not support Python 2.

If you get permission errors, try using sudo:

$ sudo pip3 install fuzz

Development

The repository for fuzz, containing the most recent iteration, can be found here. To clone the fuzz repository directly from there, use:

$ git clone git://github.com/samirelanduk/fuzz.git

Requirements

fuzz currently has no external dependencies.

Overview

fuzz allows you to manipulate numbers which are the result of a measurement, and which therefore have uncertainty bounds associated with them.

All methods of measuring a physical quantity - reading a thermometer, weighing yourself, measuring the speed of a car - produce values which are actually 'plus or minus' some amount, because all methods of measurement have limits to their precision. It is this 'plus or minus' which fuzz handles.

Creating

The key (and currently only) object type in fuzz is the Value. A Value is just a number, or measurement. The most basic Value would be created as follows:

>>> from fuzz import Value
>>> val = Value(108.5)
>>> val
108.5
>>> type(val)
<class 'fuzz.values.Value'>

Here a Value is created to represent the number of 108.5. There is no error associated (error and uncertainty are used interchangeably here), and it is generally indistinguishable from the float 108.5, unless you actually query its type.

You would add error like this:

>>> val = Value(108.5, 1.4)
>>> val
108.5 ± 1.4
>>> val.value()
108.5
>>> val.error()
1.4

This represents a value of 108.5, but for which there is uncertainty in either direction of 1.4 - '108.5 plus or minus 1.4'. This error can be represented in other ways:

>>> val.relative_error() # The error relative to the value
0.012903225806451613
>>> val.error_range() # The range of possible values implied by the error
(107.1, 109.9)

Mathematical Operations

Values can be added, subtracted, multiplied, and divided - with other Values and with ordinary numbers. The result will be a new Value, whose value is the result of that operation.

>>> val1 = (96, 1.5)
>>> val2 = (23, 0.8)
>>> sum_val = val1 + val2
>>> sum_val.value()
119
>>> product_val = val1 * val2
>>> product_val.value()
2208

The new Value will also have an error associated, that comes from the error values of the operands. The values are assumed to be independent, and so error values are combined in quadrature.

You can also raise a Value to a power.

Comparing

Values support the ==, !=, <, <=, > and >= comparison operators. These will just compare the values themselves, and ignore error.

However, the error is important when comparing uncertain values. The expression Value(10, 5) > Value(9, 4) will return True, because 10 is greater than 9. But mathematically, the values are so uncertain and so close, that you might wish to check that this difference is significant.

For this purpose, the Value.consistent_with method can be used. Two values are consistent if the sum of their errors is larger than the difference between their values. Value(10, 5).consistent_with(Value(9, 4)) would return True, and so whatever the operands might say, you should be careful about treating one as being unambiguously larger than the other.

Changelog

Release 0.1.1

21 July 2017

• Fixed bugs related to negative numbers.

Release 0.1.0

28 June 2017

• Added basic Value class.
• Added basic mathematical operations.