Reporting functions

This module provides functions to facilitate the reporting of information about calculations.

The shorter name rp has been 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 label-component of uncertainty pairs

arg:
y (UncertainReal or UncertainComplex): an uncertain number
keyword args:
influences: a sequence of uncertain numbers
key (str): sorting key (‘u’ or ‘label’)
reverse (bool): sorting order (forward or reverse)
trim (float): control smallest reported magnitudes
max_number (int): return no more than max_number components
intermediate (bool): report intermediate components

A sequence of Influence namedtuples is returned, each with the attributes label and u for a component of uncertainty (see component()).

The keyword argument influences can select specific influences to be reported.

The keyword argument key sets the order of the sequence by the component of uncertainty or the label (u or label).

The keyword argument reverse controls the sense of ordering.

The keyword argument trim can be used to set a minimum relative magnitude of components returned. The components of uncertainty greater than trim times the largest component 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 allows all the components of uncertainty with respect to all intermediate results to be reported.

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 l,u in reporting.budget(y):
...     print("{0}: {1:G}".format(l,u))
...
x1: 0.333333
x2: 0.166667
x3: 0.0111111

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

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

Changed in version Added: the intermediate keyword argument.

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
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.35788424389927
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)
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)
is_ureal(x)

Return True if x is an uncertain real number

Example:

>>> x = ureal(1,1)
>>> reporting.is_ureal(x)
True
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
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
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