Evaluating type-A uncertainty

A type-A evaluation of uncertainty involves statistical analysis of data (in contrast to a type-B evaluation, which by some means other than statistical analysis).

The shorter name ta has been defined as an alias for type_a, to resolve the names of objects defined in this module.

Sample estimates

  • estimate() returns an uncertain number defined from the statistics of a sample of data.
  • multi_estimate_real() returns a sequence of related uncertain real numbers defined from the multivariate statistics calculated from a sample of data.
  • multi_estimate_complex() returns a sequence of related uncertain complex numbers defined from the multivariate statistics of a sample of data.
  • estimate_digitized() returns an uncertain number for the mean of a sample of digitized data.
  • mean() returns the mean of a sample of data.
  • standard_uncertainty() evaluates the standard uncertainty associated with the sample mean.
  • standard_deviation() evaluates the standard deviation of a sample of data.
  • variance_covariance_complex() evaluates the variance and covariance associated with the mean real component and mean imaginary component of the data.

Note

Many functions in type_a treat data as pure numbers. Sequences of uncertain numbers can be passed to these functions, but only the uncertain-number values will be used.

Module contents

estimate(seq, label=None, context=<GTC.context.Context object>)

Return an uncertain number for the mean of the data

Parameters:
  • seq – a sequence of data
  • label (str) – a label for the returned uncertain number
Return type:

UncertainReal or UncertainComplex

The elements of seq may be real numbers, complex numbers, or uncertain real or complex numbers. Note that only the value of uncertain numbers will be used.

In a type-A evaluation, the sample mean provides an estimate of the quantity of interest. The uncertainty in this estimate is the standard deviation of the sample mean (or the sample covariance of the mean, in the complex case).

The function returns an UncertainReal when the mean of the data is real, and an UncertainComplex when the mean of the data is complex.

Examples:

>>> data = range(15)
>>> type_a.estimate(data)
ureal(7.0,1.1547005383792515,14)

>>> data = [(0.91518731126816899+1.5213442955575518j),
... (0.96572684493613492-0.18547192979059401j),
... (0.23216598132006649+1.6951311687588568j),
... (2.1642786101267397+2.2024333895672563j),
... (1.1812532664590505+0.59062101107787357j),
... (1.2259264339405165+1.1499373179910186j),
... (-0.99422341300318684+1.7359338393131392j),
... (1.2122867690240853+0.32535154897909946j),
... (2.0122536479379196-0.23283009302603963j),
... (1.6770229536619197+0.77195994890476838j)]

>>> type_a.estimate(data)
ucomplex((1.059187840567141+0.9574410497332932j), u=[0.28881665310241805,0.2655555630050262], r=-4.090655272692547, df=9)
estimate_digitized(seq, delta, label=None, truncate=False, context=<GTC.context.Context object>)

Return an uncertain number for the mean of digitized data

Parameters:
  • seq (float, UncertainReal or UncertainComplex) – data
  • delta (float) – digitization step size
  • label (str) – label for uncertain number returned
  • truncate (bool) – if True, truncation, rather than rounding, is assumed
Return type:

UncertainReal or UncertainComplex

A sequence of data that has been formatted with fixed precision can completely conceal a small amount of variability in the original values, or merely obscure that variability.

This function recognises the possible interaction between truncation, or rounding, errors and random errors in the underlying data. The function obtains the mean of the data sequence and evaluates the uncertainty in this mean as an estimate of the mean of the process generating the data.

Set the argument truncate to True if data have been truncated, instead of rounded.

See reference: R Willink, Metrologia, 44 (2007) 73-81

Examples:

# LSD = 0.0001, data varies between -0.0055 and -0.0057
>>> seq = (-0.0056,-0.0055,-0.0056,-0.0056,-0.0056,
...      -0.0057,-0.0057,-0.0056,-0.0056,-0.0057,-0.0057)
>>> type_a.estimate_digitized(seq,0.0001)
ureal(-0.005627272727272727,1.9497827808661157e-05,10)

# LSD = 0.0001, data varies between -0.0056 and -0.0057
>>> seq = (-0.0056,-0.0056,-0.0056,-0.0056,-0.0056,
... -0.0057,-0.0057,-0.0056,-0.0056,-0.0057,-0.0057)
>>> type_a.estimate_digitized(seq,0.0001)
ureal(-0.005636363636363636,1.5212000482437775e-05,10)

# LSD = 0.0001, no spread in data values
>>> seq = (-0.0056,-0.0056,-0.0056,-0.0056,-0.0056,
... -0.0056,-0.0056,-0.0056,-0.0056,-0.0056,-0.0056)
>>> type_a.estimate_digitized(seq,0.0001)
ureal(-0.0056,2.886751345948129e-05,10)

# LSD = 0.0001, no spread in data values, fewer points
>>> seq = (-0.0056,-0.0056,-0.0056)
>>> type_a.estimate_digitized(seq,0.0001)
ureal(-0.0056,3.291402943021917e-05,2)
multi_estimate_real(seq_of_seq, labels=None)

Return a sequence of uncertain real numbers

Parameters:
  • seq_of_seq – a sequence of sequences of data
  • labels – a sequence of str labels
Return type:

seq of UncertainReal

The sequences in seq_of_seq must all be the same length. Each sequence is associated with a particular quantity and contains a sample of data. An uncertain number for the quantity will be created using the sample of data, using sample statistics. The covariance between different quantities will also be evaluated from the data.

A sequence of elementary uncertain numbers are returned. The uncertain numbers are considered related, allowing a degrees-of-freedom calculations to be performed on derived quantities.

Example:

# From Appendix H2 in the GUM

>>> V = [5.007,4.994,5.005,4.990,4.999]
>>> I = [19.663E-3,19.639E-3,19.640E-3,19.685E-3,19.678E-3]
>>> phi = [1.0456,1.0438,1.0468,1.0428,1.0433]
>>> v,i,p = type_a.multi_estimate_real((V,I,phi),labels=('V','I','phi'))
>>> v
ureal(4.999,0.0032093613071761794,4, label='V')
>>> i
ureal(0.019661,9.471008394041335e-06,4, label='I')
>>> p
ureal(1.04446,0.0007520638270785368,4, label='phi')

>>> r = v/i*cos(p)
>>> r
ureal(127.732169928102...,0.071071407396995...,4.0)
multi_estimate_complex(seq_of_seq, labels=None, context=<GTC.context.Context object>)

Return a sequence of uncertain complex numbers

Parameters:
  • seq_of_seq – a sequence of sequences of data
  • labels – a sequence of str labels
Return type:

a sequence of UncertainComplex

The sequences in seq_of_seq must all be the same length. Each sequence contains a sample of data that is associated with a particular quantity. An uncertain number for the quantity will be created using this data from sample statistics. The covariance between different quantities will also be evaluated from the data.

A sequence of elementary uncertain complex numbers are returned. These uncertain numbers are considered related, allowing a degrees-of-freedom calculations to be performed on derived quantities.

Defines uncertain numbers using the sample statistics, including the sample covariance.

Example:

# From Appendix H2 in the GUM

>>> I = [ complex(x) for x in (19.663E-3,19.639E-3,19.640E-3,19.685E-3,19.678E-3) ]
>>> V = [ complex(x) for x in (5.007,4.994,5.005,4.990,4.999)]
>>> P = [ complex(0,p) for p in (1.0456,1.0438,1.0468,1.0428,1.0433) ]

>>> v,i,p = type_a.multi_estimate_complex( (V,I,P) )

>>> get_correlation(v.real,i.real)
-0.355311219817512

>>> z = v/i*exp(p)
>>> z.real
ureal(127.732169928102...,0.071071407396995...,4.0)
>>> get_correlation(z.real,z.imag)
-0.588429784423515...
mean(seq, *args, **kwargs)

Return the arithmetic mean of data in seq

Parameters:
  • seq – a sequence, ndarray, or iterable, of numbers or uncertain numbers
  • args – optional arguments when seq is an ndarray
  • kwargs – optional keyword arguments when seq is an ndarray

If seq contains real or uncertain real numbers, a real number is returned.

If seq contains complex or uncertain complex numbers, a complex number is returned.

Example:

>>> data = range(15)
>>> type_a.mean(data)
7.0
standard_deviation(seq, mu=None)

Return the sample standard deviation

Parameters:
  • seq – sequence of data
  • mu – the arithmetic mean of seq

If seq contains real or uncertain real numbers, the sample standard deviation is returned.

If seq contains complex or uncertain complex numbers, the standard deviation in the real and imaginary components is evaluated, as well as the correlation coefficient between the components. The results are returned in a pair of objects: a StandardDeviation namedtuple and a correlation coefficient.

Only the values of uncertain numbers are used in calculations.

Examples:

>>> data = range(15)
>>> type_a.standard_deviation(data)
4.47213595499958

>>> data = [(0.91518731126816899+1.5213442955575518j),
... (0.96572684493613492-0.18547192979059401j),
... (0.23216598132006649+1.6951311687588568j),
... (2.1642786101267397+2.2024333895672563j),
... (1.1812532664590505+0.59062101107787357j),
... (1.2259264339405165+1.1499373179910186j),
... (-0.99422341300318684+1.7359338393131392j),
... (1.2122867690240853+0.32535154897909946j),
... (2.0122536479379196-0.23283009302603963j),
... (1.6770229536619197+0.77195994890476838j)]
>>> sd,r = type_a.standard_deviation(data)
>>> sd
StandardDeviation(real=0.913318449990377, imag=0.8397604244242309)
>>> r
-0.31374045124595246
standard_uncertainty(seq, mu=None)

Return the standard uncertainty of the sample mean

Parameters:
  • seq – sequence of data
  • mu – the arithmetic mean of seq
Return type:

float or StandardUncertainty

If seq contains real or uncertain real numbers, the standard uncertainty of the sample mean is returned.

If seq contains complex or uncertain complex numbers, the standard uncertainties of the real and imaginary components are evaluated, as well as the sample correlation coefficient are returned in a StandardUncertainty namedtuple

Only the values of uncertain numbers are used in calculations.

Example:

>>> data = range(15)
>>> type_a.standard_uncertainty(data)
1.1547005383792515

>>> data = [(0.91518731126816899+1.5213442955575518j),
... (0.96572684493613492-0.18547192979059401j),
... (0.23216598132006649+1.6951311687588568j),
... (2.1642786101267397+2.2024333895672563j),
... (1.1812532664590505+0.59062101107787357j),
... (1.2259264339405165+1.1499373179910186j),
... (-0.99422341300318684+1.7359338393131392j),
... (1.2122867690240853+0.32535154897909946j),
... (2.0122536479379196-0.23283009302603963j),
... (1.6770229536619197+0.77195994890476838j)]
>>> u,r = type_a.standard_uncertainty(data)
>>> u
StandardUncertainty(real=0.28881665310241805, imag=0.2655555630050262)
>>> u.real
0.28881665310241805
>>> r
-0.31374045124595246
variance_covariance_complex(seq, mu=None)

Return the sample variance-covariance matrix

Parameters:
  • seq – sequence of data
  • mu – the arithmetic mean of seq
Returns:

a 4-element sequence

If mu is None the mean will be evaluated by mean().

seq may contain numbers or uncertain numbers. Only the values of uncertain numbers are used in calculations.

Variance-covariance matrix elements are returned in a VarianceCovariance namedtuple; they can be accessed using the attributes .rr, .ri, ,ir and .ii.

Example:

>>> data = [(0.91518731126816899+1.5213442955575518j),
... (0.96572684493613492-0.18547192979059401j),
... (0.23216598132006649+1.6951311687588568j),
... (2.1642786101267397+2.2024333895672563j),
... (1.1812532664590505+0.59062101107787357j),
... (1.2259264339405165+1.1499373179910186j),
... (-0.99422341300318684+1.7359338393131392j),
... (1.2122867690240853+0.32535154897909946j),
... (2.0122536479379196-0.23283009302603963j),
... (1.6770229536619197+0.77195994890476838j)]
>>> type_a.variance_covariance_complex(data)
VarianceCovariance(rr=0.8341505910928249, ri=-0.24062910264062262, ir=-0.24062910264062262, ii=0.7051975704291644)

>>> v = type_a.variance_covariance_complex(data)
>>> v[0]
0.8341505910928249
>>> v.rr
0.8341505910928249
>>> v.ii
0.7051975704291644