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 ofetn called the 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, influences=None, key='u', reverse=True, trim=0.01, max_number=None)¶ Return a sequence of label-component of uncertainty pairs
Parameters: - y (
UncertainReal
orUncertainComplex
) – an uncertain number - influences – a sequence of uncertain numbers
- key – the list sorting key
- reverse (bool) – 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
Influence
namedtuples is returned, each with the attributeslabel
andu
for a component of uncertainty (seecomponent()
).The argument
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
orlabel
).The argument
reverse
controls the sense of ordering.The argument
trim
can be used to set a minimum relative magnitude of components returned. Settrim=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("{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
- y (
-
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