## Obtaining numerical results from uncertain numbers

Every uncertain real number has the attributes:
• value
• uncertainty
• degrees of freedom
Value is the estimate of a quantity of interest. Uncertainty is the standard uncertainty of this estimate and the degrees of freedom is, well, the degrees of freedom associated with the uncertainty.

The numerical values of these attributes are used to calculate an expanded uncertainty for a quantity of interest.

GTC functions can obtain attribute values from an uncertain number, or there is a set of Python object-attributes that do the same thing. For example, if
y = ureal(1.1,2.5,6)

then
print value(y)
print uncertainty(y)
print dof(y)

yields
1.1
2.5
6

as does the more succinct form using object attributes
print y.x
print y.u
print y.df


### Expanded uncertainty

To calculate an expanded uncertainty, the standard uncertainty of a result is multiplied by a coverage factor $$k_p$$ that depends on the number of degrees of freedom ($$p$$ is the level of confidence, or coverage probability).

For the uncertain number above (and for a 95% level of confidence)
k_95 = reporting.k_factor(y.df,p=95)
U_95 = k_95 * y.u

Alternatively, the lower and upper bounds of an uncertainty interval can be calculated directly
Y_lb, Y_ub = reporting.uncertainty_interval(y,p=95)

The numbers obtained here are -5.017 and 7.217

### Uncertainty budgets

An uncertainty budget breaks down the various contributions to the combined uncertainty of a result.

For example, the following three uncertain numbers are associated with measurements of voltage, current and phase in an electrical circuit
V = ureal(4.999,3.2E-3,label='V')        # volt
I = ureal(19.661E-3,9.5E-6,label='I')    # amp

Based on these measurements, an uncertain number for the resistance $$R$$ is
R = V * cos(phi) / I

We obtain a budget for this by writing
for cpt in reporting.budget(R):
print "%s: %G" % cpt

which generates a list of names and components of uncertainty in the same units as the measurement result and in order of decreasing magnitude
phi: 0.164885
V: 0.0817649
I: 0.0617189

This shows that phase is the most important source of measurement error. The contribution to uncertainty from a phase error is likely to be about twice as big as voltage and current errors.

### Correlation coefficients

Measurement results may become correlated if they share influence quantities, or are calculated from common data sets.

Continuing with the example above, an estimate of reactance is
X = V * sin(phi) / I

Now, the estimates associated with R and X will not be independent, because they were calculated using the same set of data. Their correlation coefficient can be calculated by
get_correlation(R,X)

(the value obtained is 0.058)

## Representing estimates

Measurements estimate quantities of interest, but there is always some uncertainty. So GTC has built-in types, called uncertain numbers, that represent estimates and keep track of their uncertainty at the same time.

The first task then, when using GTC, is to define uncertain numbers.

### Absolute uncertainty

When an estimate and standard uncertainty are given in the same units, the definition of an uncertain number is straight forward.

Suppose, a length is reported
$\widehat{l} = 10.1\,\mathrm{cm},\; u(\widehat{l}) = 0.3\,\mathrm{cm}\;,$
an uncertain number for $$\widehat{l}$$ may be defined by writing
l = ureal(10.1,0.3)
although it would be better to write
l = 10.1 - ureal(0,0.3)

The slightly longer form is preferred because the uncertainty is associated with the unknown measurement error (estimated as zero), rather than the number 10.1 (which is known). This corresponds to the mathematical relation between a result $$\widehat{l}$$ and the quantity that was intended to be measured
$l = \widehat{l} - e \;,$
with $$e$$ being the (unknown) measurement error.

### Relative uncertainty

Sometimes an uncertainty is expressed relative to the magnitude of an estimate (i.e., as a standard relative uncertainty).

For instance, a length may be reported as
$\widehat{l} = 10.1\,\mathrm{cm},\; \frac{u(\widehat{l})}{\widehat{l}} = 3\% \;.$
An uncertain number for $$\widehat{l}$$ in this case can be defined by writing
l = 10.1 * ureal(1.0,0.03)

which corresponds to the relation
$l = \widehat{l} \cdot e_\mathrm{rel} \;,$
with $$e_\mathrm{rel}$$ an unknown relative error (estimated as unity).

### Expanded uncertainty

Whether relative or absolute, uncertainties are more often reported "expanded", than as standard uncertainties.

An expanded uncertainty is just a standard uncertainty, or a relative standard uncertainty, multiplied by a coverage factor. Formally, the expanded uncertainty is represented by a capital $$U$$ and the coverage factor by $$k_p$$, so for length we might write
$U(\widehat{l}) = k_p \cdot u(\widehat{l}) \; ,$
$$p$$ is a coverage probability, or level of confidence, associated with the expanded uncertainty.

Expanded uncertainties should never be used to define uncertain numbers. They should be converted to a standard uncertainty, by dividing by the coverage factor. The coverage factor should be used to find a number of degrees of freedom. The standard uncertainty and the degrees of freedom can then be used to define an uncertain number.

For example, suppose a length has been reported as $$\widehat{l} = 10.1$$ with an expanded uncertainty of $$k_p = 2.1$$ at a level of confidence of $$p = 95\%$$. Let's say we already have the following lines of GTC code
U_l = 0.63
k_95 = 2.1

The standard uncertainty and degrees of freedom can be easily found (note, 'k_to_dof' is a function in the GTC 'reporting' module)
u_l = U_l / k_95
df_l = reporting.k_to_dof( k_95, 95 )

and an uncertain number for $$\widehat{l}$$ can be defined with these values
l = 10.1 - ureal(0,u_l,df_l)