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()
andv_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
orUncertainComplex
): an uncertain number - keyword args:
- influences: a sequence of uncertain numberskey (str): sorting key (‘u’ or ‘label’)reverse (bool): sorting order (forward or reverse)trim (float): control smallest reported magnitudesmax_number (int): return no more than
max_number
componentsintermediate (bool): report intermediate components
A sequence of
Influence
namedtuples is returned, each with the attributeslabel
andu
for a component of uncertainty (seecomponent()
).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
orlabel
).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 thantrim
times the largest component will be reported. Settrim=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: Evaluates the coverage factor for an uncertainty interval with coverage probability
p
and degrees-of-freedomdf
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: 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: Evaluates the square of the coverage factor for an elliptical uncertainty region with coverage probability
p
anddf
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: 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 tox
Parameters: - y –
UncertainReal
orUncertainComplex
orUncertainArray
- x –
UncertainReal
orUncertainComplex
orUncertainArray
If
x
andy
are uncertain real numbers, return a float.If
y
orx
is an uncertain complex number, return a 4-element sequence of float, containing the components of uncertainty.When
x
andy
are arrays, anuncertain_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)
- y –
-
sensitivity
(y, x)¶ Return the first partial derivative of
y
with respect tox
Parameters: - y –
UncertainReal
orUncertainComplex
orUncertainArray
- x –
UncertainReal
orUncertainComplex
orUncertainArray
If
x
andy
are uncertain real numbers, return a float.If
y
orx
is an uncertain complex number, return a 4-element sequence of float, representing the Jacobian matrix.When
x
andy
are arrays, anUncertainArray
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)
- y –
-
is_ureal
(x)¶ Return
True
ifx
is an uncertain real numberExample:
>>> x = ureal(1,1) >>> reporting.is_ureal(x) True
-
is_ucomplex
(z)¶ Return
True
ifz
is an uncertain complex numberExample:
>>> z = ucomplex(1+2j,(0.1,0.2)) >>> reporting.is_ucomplex(z) True
-
v_bar
(cv)¶ Return the trace of
cv
divided by 2Parameters: 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