# Overview¶

The GUM Tree calculator (GTC) is a tool for data processing with automatic uncertainty calculation. It uses uncertain numbers to represent quantities that have been measured, or estimated in some way.

## Measurement errors and uncertainty¶

Measurement can never provide an exact value for a quantity of interest (the measurand). The difference, between the true, but unknown, value $$Y$$ and the measurement result $$y$$, is called the measurement error

$E = y - Y \; .$

When considering the uncertainty of $$y$$ as an estimate of $$Y$$, the likely magnitude of $$E$$ must be taken into account. Although $$E$$ is never known, a statistical distribution can be used to describe it. The standard deviation of this distribution is called the standard uncertainty.

### Measurement functions¶

A measurand is often defined in terms of other quantities in an equation

$Y = f(X_1, X_2, \cdots) \;,$

where the $$X_i$$ are called influence quantities.

However, $$X_1, X_2, \cdots$$ are unknown; only estimates $$x_1, x_2, \cdots$$ are available. These estimates can be used to calculated an estimate of the measurand

$y = f(x_1, x_2, \cdots) \;.$

The error in $$y$$ depends on the individual measurement errors $$E_1 = x_1-X_1$$, $$E_2 = x_2-X_2$$, etc, which are unknown. So, the uncertainty of the result as an estimate of the measurand must be calculated from information about the uncertainties of $$x_1, x_2,$$ etc.

## Uncertain Numbers¶

An uncertain number is used to represent a quantity that is unknown. It holds an estimate of that quantity and the uncertainty of that estimate.

Suppose a flag is flying from a pole that is estimated to be 15 metres away from an observer (with an uncertainty of 3 cm). The angle between horizontal and line-of-sight to the top of the pole is 38 degrees (with an uncertainty of 2 degrees). The measurement equation is

$H = B \tan\Phi \;,$

where $$H$$ is the actual height, $$B$$ is the length from the base of the pole and $$\Phi$$ is the actual line-of-sight angle. The question is: how high is the flag?

The following calculation obtains 11.7 metres, with a standard uncertainty of 0.8 metres

>>> B = ureal(15,3E-2)
>>> H = B * tan(Phi)
>>> H
ureal(11.719284397600761, 0.843532951107579, inf)


It is important to note that GTC calculations are open ended. It is possible to continue the calculation above and evaluate the observer angle at 20 metres from the pole (the base distance still has an uncertainty of 3 cm)

>>> B_20 = ureal(20,3E-2)
>>> Phi_20 = atan( H/B_20 )
>>> Phi_20
ureal(0.5300351420781763, 0.031403340387013895, inf)
>>> math.degrees( Phi_20.x )
30.36877663469645
>>> math.degrees( Phi_20.u )
1.7992788667886215


### Elementary uncertain numbers¶

We use the term elementary uncertain number to describe uncertain numbers associated with problem inputs (e.g., B and Phi above). Elementary uncertain numbers are defined by functions like ureal and ucomplex.

### Uncertain Number Attributes¶

Uncertain numbers use attributes to provide access to the value (the estimate), the uncertainty (of the estimate) and the degrees of freedom (associated with the uncertainty), as well as some other properties (see UncertainReal).

Continuing with the flagpole example, the attributes x, u, df can be used to see the estimate, the uncertainty and the degrees-of-freedom (which is infinity), respectively

>>> H.x
11.719284397600761
>>> H.u
0.84353295110757898
>>> H.df
inf


Alternatively, there are GTC functions that return the same numbers

>>> value(H)
11.719284397600761
>>> uncertainty(H)
0.84353295110757898
>>> dof(H)
inf


### Uncertain numbers and measurement errors¶

To make the best use of GTC it is helpful to think in terms of the actual quantities that appear in measurement equations. These quantities are not known exactly and many will be residual errors with estimates of zero or unity.

In the context of the example above, $$B$$ and $$\Phi$$ are quantities in the measurement equation. When measured, there will be errors, which can be written as $$E_b$$ and $$E_\phi$$. So the measured values $$b=15\,\mathrm{m}$$ and $$\phi=38 \, \mathrm{deg}$$ are related to the quantities of interest as

\begin{align}\begin{aligned}b = B + E_b\\\phi = \Phi + E_\phi\end{aligned}\end{align}

Our best estimates of the errors are $$E_b \approx 0$$ and $$E_\phi \approx 0$$, with uncertainties in these estimates of $$u(E_b)=3\times 10^{2}\, \mathrm{m}$$ and $$u(E_\phi)=2\, \mathrm{deg}$$.

The GTC calculation now looks like this

>>> b = 15
>>> E_b = ureal(0,3E-2)
>>> B = b - E_b

This way of expressing the calculation reflects our understanding of the problem: $$b=15$$ and $$\phi=38$$ are precisely known numbers, there is nothing ‘uncertain’ about their values. However, when we use those number as estimates of $$B$$ and $$\Phi$$ the unknown errors $$E_b$$ and $$E_\phi$$ give rise to uncertainty.