# 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.

## 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 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 (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 (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 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 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 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 (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 = 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 (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 (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
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 (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) 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)