Reporting functions

This module provides functions that facilitate the reporting of information about GTC results.

The prefix reporting (or the alias rp) is needed to resolve objects defined in this module.

Reporting functions

  • The function budget generates an uncertainty budget.
  • The function round rounds values according to the level of uncertainty. It facilitates string formatting for uncertain numbers.
  • The function uncertainty_interval calculates the upper and lower bounds of an uncertainty interval.
  • The function uncertainty_region calculates a set of points located on the perimeter of an elliptical uncertainty region.
  • The function eigenv evaluates the eigenvalues and eigenvectors of a 2-by-2 variance-covariance matrix.
  • The function k_factor returns the coverage factor used for real-valued problems.
  • 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.
  • Functions u_bar and v_bar return summary values for matrices associated with two-dimensional uncertainty.
  • The function mahalanobis_sq evaluates the squared Mahalanobis distance.

Coordinate changes

  • Functions u_polar_to_rect and u_rect_to_polar transform statements of uncertainty from one system of coordinates to the other (polar and rectangular).
  • Functions u_rect_to_tangent and u_tangent_to_rect transform statements of uncertainty between rectangular coordinates and tangential coordinates (in-phase / quadrature).
  • The function rotate_cv_coordinates applies a rotation to the coordinate axes associated with a particular variance-covariance matrix.

Uncertainty functions

  • The function u_component returns the component of uncertainty in one uncertain number due to uncertainty in another.
  • The function variance_and_dof evaluates the variance and the degrees-of-freedom for both real and complex uncertain numbers.

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(x, influences=None, key='u', reverse=True, trim=0.01, max_number=None)

Return a sequence of label-component of uncertainty pairs

Parameters:
  • x (UncertainReal or UncertainComplex) – the measurand estimate
  • influences – a sequence of uncertain numbers
  • key – the list sorting key
  • reverse (Boolean) – determines sorting order (forward or reverse)
  • trim – remove components of uncertainty that are less than trim times the largest component
  • max_number – return no more than max_number components

A sequence of namedtuple pairs is returned, with the attributes label and u.

Each element is a pair: a label and the magnitude of the component of uncertainty (see component).

The sequence influences can be used to select the influences are that reported.

The argument key can be used to order the sequence by the component of uncertainty or the label (u or label).

The argument reverse controls the sense of ordering.

The argument trim can be used to set a minimum relative magnitude of components returned. Set trim=0 for a complete list.

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

Example:

>>> 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 "%s: %G" % (l,u)
...     
x1: 0.333333
x2: 0.166667
x3: 0.0111111

>>> for l,u in reporting.budget(y,reverse=False):
...     print "%s: %G" % (l,u)
...     
x3: 0.0111111
x2: 0.166667
x1: 0.333333
u_component(y, x)

Return the component of uncertainty in y due to x.

Note

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

  • If one of y or x is an uncertain complex number, return

    a 4-element sequence of float, containing the components of the uncertainty matrix.

  • Otherwise, return 0.

Example:

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

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

>>> q = ucomplex(2,1)
>>> z = magnitude(q)    # uncertain real numbers
>>> reporting.u_component(z,q)
u_components(rr=1.0, ri=0.0, ir=0.0, ii=0.0)
round(un, digits=2, df_decimals=0)

Round the value of attributes of un ready for printing

If un is uncertain real, an RoundedUncertainReal object is returned with attributes x, u, df, label and precision.

The first four attributes correspond to the attributes of un. The values of x and u have been rounded to give digits significant figures in the uncertainty.

The degrees-of-freedom is rounded down to df_decimals decimal places.

precision is the number of decimal places needed to represent x and u in fixed-point format. It is intended for use when formatting a Python string.

Example

>>> un = ureal(10.2523,1.51,3.2,label='x')
>>> un_ = reporting.round(un)
>>> "{0.label!s}: {0.x:.{0.precision}f},        ... u={0.u:.{0.precision}f}, df={0.df:.0f}".format( un_ )
x: 10.3, u=1.5, df=3
sensitivity(y, x)

Return the partial derivative of y with respect to x.

Warning

This function is deprecated and there is no equivalent function available. Future releases of GTC may not support this calculation.

Note

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

  • If one of y or x is an uncertain complex number, return

    a 4-element sequence of float, containing the elements of the Jacobian matrix.

  • Otherwise, return 0.

Example:

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

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

>>> q = ucomplex(2,1)
>>> z = magnitude(q)    # uncertain real numbers
>>> reporting.sensitivity(z,q)
jacobian_matrix(rr=1.0, ri=0.0, ir=0.0, ii=0.0)
k_factor(df=inf, p=95, quick=True)

Return the univariate coverage factor

Parameters:
  • df (float) – the degrees-of-freedom (>1)
  • p (integer) – the coverage probability (%)
  • quick (bool) – use faster algorithm

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

Accuracy is reduced when using the quick option, for example:

>>> reporting.k_factor(3)
3.181632923406346
>>> reporting.k_factor(3,quick=False)
3.1824463052837175
k_to_dof(k, p=95)

Return the dof for k a univariate coverage factor

Parameters:
  • k – coverage factor (>0)
  • p – coverage probability (%)

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

Returns infinity for degrees-of-freedom values above 1E8.

Example:

>>> reporting.k_to_dof(2.0,95)
60.437564504892904
uncertainty_interval(x, p=95, quick=True)

Return the upper and lower bounds of a p% uncertainty interval.

Parameters:
  • x (UncertainReal) – the value (estimate)
  • p (integer) – coverage probability in percent
  • quick (bool) – use the faster coverage factor algorithm
Returns:

a 2-element sequence

Example:

>>> x = ureal(1.5,1,50)
>>> reporting.uncertainty_interval(x)
expanded_uncertainty(lower=-0.5085590722581137, upper=3.5085590722581137)
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
variance_and_dof(x)

Return the variance and degrees-of-freedom.

If x is an uncertain real number, a pair of real numbers is returned (v,df), where v is the standard variance and df is the degrees-of-freedom calculated using the Welch-Satterthwaite formula.

If x is an uncertain complex number, a sequence and a float is returned (cv,df), where cv is a 4-element sequence representing the variance-covariance matrix and df is the degrees-of-freedom, calculated using the Willink-Hall total-variance method.

Otherwise, returns (0.0,inf).

Example:

>>> x1 = ureal(1.1,1,5)
>>> x2 = ureal(2.3,1,15)
>>> x3 = ureal(-3.5,1,50)
>>> y = (x1 + x2) / x3
>>> v,df = reporting.variance_and_dof(y)
>>> v
0.24029987505206163
>>> df
30.460148613530492
u_to_cv(u_re_im, r=0)

Convert standard uncertainties to a covariance matrix

Parameters:
  • u_re_im (a 2-element sequence of float, or a float) – standard uncertainties for the real and imaginary components
  • r (float) – correlation coefficient between the real and imaginary components
Returns:

(v_rr,v_ri,v_ir,v_ii) : the four elements of the covariance matrix

Example:

>>> reporting.u_to_cv( (0.1,0.1) ,0.5)
variance_covariance(rr=0.010000000000000002, ri=0.005000000000000001,
ir=0.005000000000000001, ii=0.010000000000000002)

>>> reporting.u_to_cv(3)
variance_covariance(rr=9, ri=0, ir=0, ii=9)
cv_to_u(cv)

Return standard uncertainties and a correlation coefficient

Parameters:cv (4-element sequence of float) – covariance matrix
Returns:(u_re,u_im), r : the standard uncertainties and a correlation coefficient

A pair of standard uncertainties in the real and imaginary components and a correlation coefficient are obtained from the variance-covariance matrix cv.

Example:

>>> reporting.cv_to_u( (0.01,0.005,0.005,0.01) )
(standard_uncertainty(real=0.1, imag=0.1), 0.4999999999999999)
v_bar(cv)

Return the trace of cv divided by 2

Parameters:cv (a 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
variance_covariance(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 magnitude.

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
u_components(rr=0.2, ri=-7.1, ir=7.1, ii=0.2)
>>> reporting.u_bar(dy_dz1)
7.102816342831905
fn_bar(ucpt)

Deprecated function name: use u_bar instead

tv_bar(cv)

Deprecated function name: use v_bar instead

k2_factor_sq(df=inf, p=95, quick=True)

Return the bivariate coverage factor squared

Parameters:
  • df (float) – the degrees-of-freedom (>=2)
  • quick (bool) – use faster algorithm
Arg:

p: 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.

The quick option is not available for df less than 3

Accuracy is reduced when using the quick option, for example:

>>> reporting.k2_factor_sq(3)
57.35717041567613
>>> reporting.k2_factor_sq(3,quick=False)
56.99999999936168
k2_to_dof(k2, p=95)

Return the dof for k2 a bivariate coverage factor

Parameters:
  • k2 – coverage factor (>0)
  • p – 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.

Returns infinity for degrees-of-freedom values above 1E8.

Example:

>>> reporting.k2_to_dof(2.6,95)
34.357884313812384
mahalanobis_sq(x, y, cv, inverted=False)

Return the squared Mahalanobis distance between x and y

Parameters:
  • x – complex number
  • y – complex number
  • cv (4-element sequence of float) – variance-covariance matrix
  • inverted (Boolean) – True if cv is inverted

If inverted is True, the matrix inverse of cv is not calculated.

Example:

>>> cv = reporting.u_to_cv( (2,4) )
>>> x1 = complex(1,3)
>>> x2 = complex(3,1)
>>> y = complex(1,1)
>>> reporting.mahalanobis_sq(x1,y,cv)
0.25
>>> reporting.mahalanobis_sq(x2,y,cv)
1.0
uncertainty_region(N, z, p=95, quick=True)

Return a sequence of N (x,y) points on a p% uncertainty ellipse

Parameters:
  • N (int or long) – number of coordinates required
  • z (UncertainComplex) – the value (estimate)
  • p (integer) – coverage probability in percent
  • quick (bool) – use the faster coverage factor algorithm

This function generates N points on the perimeter of an elliptical uncertainty region.

Example:

>>> z = ucomplex(0,1,50)
>>> reporting.uncertainty_region(10,z)
[(2.53924593344018+0j), 
(1.9451752370243123+1.6321958239622785j), 
(0.44093542899005095+2.50066908205661j), 
(-1.2696229667200893+2.199051484815526j), 
(-2.3861106660143627+0.8684732580943322j), 
(-2.386110666014363-0.8684732580943316j), 
(-1.2696229667200911-2.199051484815525j), 
(0.44093542899004984-2.5006690820566106j), 
(1.9451752370243116-1.6321958239622794j), 
(2.53924593344018-6.219358809270899e-16j)]
eigenv(cv)

Return the eigenvalues and eigenvectors of cv

Parameters:cv (a 4-element sequence of float) – variance-covariance matrix
Returns:a pair of eigenvalues and a pair of eigenvectors

The function raises a RuntimeError exception if the off-diagonal elements differ by more than 1E-10, or if either diagonal element is negative.

Calculates the eigenvalues and eigenvectors of a variance-covariance matrix cv.

Returns a pair of eigenvalues (ordered) and a pair of eigenvectors (2-element sequences). The eigenvectors have unit magnitude.

Examples:

>>> z = ucomplex(1+1j,(.2,.4))
>>> L,V = reporting.eigenv(z.v)
>>> L
(0.16000000000000003, 0.04000000000000001)
>>> V
((0, 1), (1, 0))

>>> m = linear_algebra.matrix( [[.8,.3],[.3,.7]])
>>> L,V = reporting.eigenv(m.flat)
>>> L
(1.054138126514911, 0.445861873485089)
>>> V[0]
(0.7630199824727258, 0.6463748961301957)
>>> V[1]
(-0.6463748961301957, 0.7630199824727257)
u_polar_to_rect(z, u_r_phi, r=0)

Return standard uncertainties, and correlation, in rectangular coordinates

Parameters:
  • z (complex) – the value (estimate)
  • u_r_phi (2-element sequence of float) – a pair of standard uncertainties in polar coordinates (angle uncertainty in radians)
  • r (float) – correlation between the radial and azimuthal components
Returns:

(u_re,u_im), r : a pair of standard uncertainties and a correlation coefficient in rectangular coordinates

Transform a pair of standard uncertainties in polar coordinates into a pair of standard uncertainties in rectangular coordinates.

Note

If u/abs(z)< 5 the polar to rectangular conversion is not recommended.

Example:

>>> z = complex(0.93,-0.03)
>>> u_r_phi = (0.01,math.radians(.5))
>>> u,r = reporting.u_polar_to_rect(z,u_r_phi)
>>> u
standard_uncertainty(real=0.009998229284003339, imag=0.008122182692929972)
>>> r
-0.013517808883928624
u_rect_to_polar(z, u_re_im, r=0)

Return standard uncertainties, and correlation, in polar coordinates

Parameters:
  • z (complex) – the value (estimate)
  • u_re_im (2-element sequence of float) – a pair of standard uncertainties in rectangular coordinates
  • r (float) – correlation between the real and imaginary components
Returns:

(u_r,u_phi), r : a pair of standard uncertainties and a correlation coefficient in polar coordinates (angle uncertainty in radians)

Transform a pair of standard uncertainties in rectangular coordinates into a pair of standard uncertainties in polar coordinates.

Note

If u/abs(z)< 5 the rectangular to polar conversion is not recommended.

Example:

>>> z = complex(0.93,-0.03)
>>> u_re_im = (0.05,0.05)
>>> u_p,r = reporting.u_rect_to_polar(z,u_re_im)
>>> u_p
(0.05000000000000001, 0.05373549001826343)
>>> r
0
u_rect_to_tangent(z, u_re_im, r=0)

Return standard uncertainties and correlation in tangential coordinates

Parameters:
  • z (complex) – the value (estimate)
  • u_re_im (2-element sequence of float) – a pair of standard uncertainties for the real and imaginary components of z
  • r (float) – correlation between components
Returns:

(u_r,u_t), r_t : a pair of uncertainties expressed in coordinates aligned with the polar axes and a correlation coefficient

Transform a pair of standard uncertainties in rectangular coordinates into a pair of uncertainties expressed in rotated rectangular coordinates (tangential coordinates) aligned with the polar axes at the point z.

Example:

>>> z = complex(1,1)
>>> u = (1,2)
>>> u_rt, r = reporting.u_rect_to_tangent(z, u )
>>> u_rt
rt_uncertainty(radial=1.5811388300841895, tangent=1.5811388300841898)
>>> u_rt.radial
1.5811388300841895
>>> u_rt.tangent
1.5811388300841898
>>> r
0.6

Note

Raises a RuntimeError if abs(z) == 0

u_tangent_to_rect(z, u_rt, r=0)

Return standard uncertainties and the correlation coefficient

Parameters:
  • z (complex) – the value (estimate)
  • u_rt (2-element sequence of float) – a pair of standard uncertainties given in tangential coordinates
  • r (float) – correlation between the radial and tangential components
Returns:

(u_re,u_im), r : a pair of standard uncertainties and a correlation coefficient in rectangular coordinates

Transform a pair of standard uncertainties and a correlation coefficient in tangential coordinates (aligned to the polar axes at the point z) to a pair of standard uncertainties and a correlation coefficient expressed in rectangular coordinates.

Example:

>>> z = complex(.3,.4)
>>> u_rt = (.5,1)
>>> u,r = reporting.u_tangent_to_rect(z, u_rt)
>>> u
standard_uncertainty(real=0.8544003745317532, imag=0.7211102550927979)
>>> u.real
0.8544003745317532
>>> u.imag
0.7211102550927979
>>> r
-0.5843047258450758
rotate_cv_coordinates(cv, phi)

Return the covariance matrix in a rotated coordinate system.

Parameters:
  • cv (4-element sequence of float) – initial covariance matrix
  • phi (float) – angle of rotation (radians)
Returns:

covariance matrix in rotated coordinate system

The coordinate axes associated with the covariance matrix cv are rotated counter-clockwise through an angle phi.

Example:

>>> z = ucomplex(1,(2,1))
>>> reporting.rotate_cv_coordinates(z.v,math.pi/4)
variance_covariance(rr=2.5000000000000004, ri=1.5, ir=1.5, ii=2.4999999999999996)