Reporting

This module provides functions to facilitate reporting information about uncertainty calculations.

The abbreviation rp is defined as an alias for reporting, to resolve the names of objects defined in this module.

Reporting functions

  • The function budget() produces an uncertainty budget.

  • The function k_factor() returns the coverage factor used for real-valued problems (based on the Student-t distribution).

  • The function k_to_dof() returns the degrees of freedom corresponding to a given coverage factor and coverage probability.

  • The function k2_factor_sq() returns coverage factor squared for the complex-valued problem.

  • The function k2_to_dof() returns the degrees of freedom corresponding to a given coverage factor and coverage probability in complex-valued problems.

  • Functions u_bar() and v_bar() return summary values for matrix results associated with 2-D uncertainty.

Uncertainty functions

  • The function u_component() returns the signed component of uncertainty in one uncertain number due to uncertainty in another.

  • The function sensitivity() returns the partial derivative of one uncertain number with respect to another. This is often called a sensitivity coefficient.

Type functions

  • The function is_ureal() can be used to identify uncertain real numbers.

  • The function is_ucomplex() can be used to identify uncertain complex numbers.

Module contents

budget(y, **kwargs)

Return a sequence of Influence objects

Parameters:

  • y – UncertainReal or UncertainComplex: an uncertain number

  • **kwargs –

    Keyword arguments:

    • influences: a sequence of uncertain numbers

    • key (str): a sorting key ('u' or 'label')

    • reverse (bool): the sorting order (forward or reverse)

    • trim (float): to control the smallest reported magnitudes

    • max_number (int): to return no more than max_number components

    • intermediate (bool): to report all intermediate components

Returns:

A sequence of Influence namedtuples.

Each Influence has three attributes: label, u, uid.

  • label is the label assigned to the uncertain number.

  • u is the value of the component of uncertainty (see component());

  • uid is the unique identifier for the uncertain number.

The keyword argument influences can be used to report specific influences.

The keyword argument key sets the sequence ordering to use the component of uncertainty or the label, respectively, u or label.

The keyword argument reverse controls the sense of ordering.

The keyword argument trim can be used to set the minimum relative magnitude of components returned. Components of uncertainty greater than trim times the largest component returned will be reported. Set trim=0 for a complete list.

The keyword argument max_number can be used to restrict the number of components returned.

The keyword argument intermediate will cause all components of uncertainty with respect to all intermediate results to be reported. When intermediate is True, influences cannot be specified.

Examples:

>>> x1 = ureal(1,1,label='x1')
>>> x2 = ureal(2,0.5,label='x2')
>>> x3 = ureal(3,0.1,label='x3')
>>> y = (x1 - x2) / x3
>>> for i in reporting.budget(y):
...     print("{0}: {1:G}".format(i.label,i.u))
...
x1: 0.333333
x2: 0.166667
x3: 0.0111111

>>> for i in reporting.budget(y,reverse=False):
...     print("{0}: {1:G}".format(i.label,i.u))
...
x3: 0.0111111
x2: 0.166667
x1: 0.333333

>>> y1 = result(x1 + x2,label='y1')
>>> y2 = result(x2 + x3,label='y2')
>>> for i in reporting.budget(y1 + y2,intermediate=True):
...     print("{0}: {1:G}".format(i.label,i.u))
...
y1: 1.11803
y2: 0.509902

Changed in version 1.3.7: The Influence namedtuple has a third attribute uid

Changed in version 1.3.4: Added the intermediate keyword argument.

components(y, **kwargs)

Return a sequence of uid-component of uncertainty pairs

Parameters:

  • y – UncertainReal or UncertainComplex: an uncertain number

  • **kwargs –

    Keyword arguments:

    • influences: a sequence of uncertain numbers

    • trim (float): control of the smallest included magnitude for u

    • max_number (int): return no more than max_number components

    • intermediate (bool): report all intermediate components

Returns:

A sequence of Component namedtuples is returned, each with the attributes uid and u for a component of uncertainty (see u_component()). The sequence is sorted in descending order of magnitude for u.

The keyword argument influences can be used to report on specific influences.

The keyword argument trim can be used to set a minimum relative magnitude of u for the components returned. Components of uncertainty with a magnitude greater than trim times the largest value of u will be reported. Set trim=0 for a complete list.

The keyword argument max_number can be used to set an upper limit on the number of components returned.

Setting keyword argument intermediate=True causes all the components of uncertainty with respect to intermediate results to be reported. When intermediate is True, influences cannot be specified.

is_ucomplex(z)

Return True if z is an uncertain complex number

Example:

>>> z = ucomplex(1+2j,(0.1,0.2))
>>> reporting.is_ucomplex(z)
True
is_ureal(x)

Return True if x is an uncertain real number

Example:

>>> x = ureal(1,1)
>>> reporting.is_ureal(x)
True
k2_factor_sq(df=inf, p=95)

Return a squared coverage factor for an elliptical uncertainty region

Parameters:

  • df (float) – the degrees-of-freedom (>=2)

  • p (int or float) – the coverage probability (%)

Evaluates the square of the coverage factor for an elliptical uncertainty region with coverage probability p and df degrees of freedom based on the F-distribution.

Example:

>>> reporting.k2_factor_sq(3)
    56.99999999999994
k2_to_dof(k2, p=95)

Return the dof corresponding to a bivariate coverage factor k2

Parameters:

  • k2 (float) – coverage factor (>0)

  • p (int or float) – coverage probability (%)

Evaluates a number of degrees-of-freedom given a coverage factor for an elliptical uncertainty region with coverage probability p based on the F-distribution.

Example:

>>> reporting.k2_to_dof(2.6,95)
34.3578842438992...
k_factor(df=inf, p=95)

Return the a coverage factor for an uncertainty interval

Parameters:

  • df (float) – the degrees-of-freedom (>1)

  • p (int or float) – the coverage probability (%)

Evaluates the coverage factor for an uncertainty interval with coverage probability p and degrees-of-freedom df based on the Student t-distribution.

Example:

>>> reporting.k_factor(3)
3.182446305284263
k_to_dof(k, p=95)

Return the dof corresponding to a univariate coverage factor k

Parameters:

  • k (float) – coverage factor (>0)

  • p (int or float) – coverage probability (%)

Evaluates the degrees-of-freedom given a coverage factor for an uncertainty interval with coverage probability p based on the Student t-distribution.

Example:

>>> reporting.k_to_dof(2.0,95)
60.43756442698591
sensitivity(y, x)

Return the first partial derivative of y with respect to x

Parameters:

If x and y are uncertain real numbers, return a float.

If y or x is an uncertain complex number, return a 4-element sequence of float, representing the Jacobian matrix.

When x and y are arrays, an UncertainArray is returned containing the results of applying this function to the array elements.

Otherwise, return 0.

New in version 1.1.

Example:

>>> x = ureal(3,1)
>>> y = 3 * x
>>> reporting.sensitivity(y,x)
3.0

>>> q = ucomplex(2,1)
>>> z = magnitude(q)    # uncertain real numbers
>>> reporting.sensitivity(z,q)
JacobianMatrix(rr=1.0, ri=0.0, ir=0.0, ii=0.0)

>>> r = ucomplex(3,1)
>>> z = q * r
>>> reporting.sensitivity(z,q)
JacobianMatrix(rr=3.0, ri=-0.0, ir=0.0, ii=3.0)

Note

This function evaluates the sensitivity (partial derivative) of one uncertain number with respect to another term x.

However, if the standard uncertainty of x is zero, the term is treated as being absent from the analytical model, so a sensitivity of 0 is reported.

For example

>>> z1 = ucomplex(1+2j,[0,1])
>>> z2 = ucomplex(-1.2-0.9j,[1,0])
>>> z = z1*z2
>>> rp.sensitivity(z,z1.real)
JacobianMatrix(rr=0.0, ri=0.0, ir=0.0, ii=0.0)
>>> rp.sensitivity(z,z1.imag)
JacobianMatrix(rr=0.9, ri=0.0, ir=-1.2, ii=0.0)
>>> rp.sensitivity(z,z2.real)
JacobianMatrix(rr=1.0, ri=0.0, ir=2.0, ii=0.0)
>>> rp.sensitivity(z,z2.imag)
JacobianMatrix(rr=0.0, ri=0.0, ir=0.0, ii=0.0)

If all the partial derivatives of a measurement model are required, regardless of the associated standard uncertainties, the preferred method is to assign all standard uncertainty values to unity.

Using the same example as above

>>> z1 = ucomplex(1+2j,1)
>>> z2 = ucomplex(-1.2-0.9j,1)
>>> z = z1*z2
>>> rp.sensitivity(z,z1.real)
JacobianMatrix(rr=-1.2, ri=0.0, ir=-0.9, ii=0.0)
>>> rp.sensitivity(z,z1.imag)
JacobianMatrix(rr=0.9, ri=0.0, ir=-1.2, ii=0.0)
>>> rp.sensitivity(z,z2.real)
JacobianMatrix(rr=1.0, ri=0.0, ir=2.0, ii=0.0)
>>> rp.sensitivity(z,z2.imag)
JacobianMatrix(rr=-2.0, ri=0.0, ir=1.0, ii=0.0)
u_bar(ucpt)

Return the magnitude of a component of uncertainty

Parameters:

ucpt (float or 4-element sequence of float) – a component of uncertainty

If ucpt is a sequence, return the root-sum-square of the elements divided by \(\sqrt{2}\)

If ucpt is a number, return the absolute value.

Example:

>>> x1 = 1-.5j
>>> x2 = .2+7.1j
>>> z1 = ucomplex(x1,1)
>>> z2 = ucomplex(x2,1)
>>> y = z1 * z2
>>> dy_dz1 = reporting.u_component(y,z1)
>>> dy_dz1
ComponentOfUncertainty(rr=0.2, ri=-7.1, ir=7.1, ii=0.2)
>>> reporting.u_bar(dy_dz1)
7.102816342831905
u_component(y, x)

Return the component of uncertainty in y due to x

Parameters:

If x and y are uncertain real numbers, return a float.

If y or x is an uncertain complex number, return a 4-element sequence of float, containing the components of uncertainty.

When x and y are arrays, an uncertain_array.UncertainArray is returned containing the results of applying this function to the array elements.

Otherwise, return 0.

Example:

>>> x = ureal(3,1)
>>> y = 3 * x
>>> reporting.u_component(y,x)
3.0

>>> q = ucomplex(2,1)
>>> z = magnitude(q)    # uncertain real numbers
>>> reporting.u_component(z,q)
ComponentOfUncertainty(rr=1.0, ri=0.0, ir=0.0, ii=0.0)

>>> r = ucomplex(3,1)
>>> z = q * r
>>> reporting.u_component(z,q)
ComponentOfUncertainty(rr=3.0, ri=-0.0, ir=0.0, ii=3.0)
v_bar(cv)

Return the trace of cv divided by 2

Parameters:

cv (4-element sequence of float) – a variance-covariance matrix

Returns:

float

Example:

>>> x1 = 1-.5j
>>> x2 = .2+7.1j
>>> z1 = ucomplex(x1,(1,.2))
>>> z2 = ucomplex(x2,(.2,1))
>>> y = z1 * z2
>>> y.v
VarianceCovariance(rr=2.3464, ri=1.8432, ir=1.8432, ii=51.4216)
>>> reporting.v_bar(y.v)
26.884