Reporting
This module provides functions to facilitate reporting information about uncertainty calculations.
The abbreviation rp
is 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 Influence objects
- Parameters:
y –
UncertainReal
orUncertainComplex
: an uncertain number**kwargs –
Keyword arguments:
influences: a sequence of uncertain numbers
key (
str
): a sorting key ('u'
or'label'
)reverse (
bool
): the sorting order (forward or reverse)trim (
float
): to control the smallest reported magnitudesmax_number (
int
): to return no more than max_number componentsintermediate (
bool
): to report all intermediate components
- Returns:
A sequence of
Influence
namedtuples.
Each
Influence
has three attributes:label
,u
,uid
.label
is the label assigned to the uncertain number.u
is the value of the component of uncertainty (seecomponent()
);uid
is the unique identifier for the uncertain number.
The keyword argument
influences
can be used to report specific influences.The keyword argument
key
sets the sequence ordering to use the component of uncertainty or the label, respectively,u
orlabel
.The keyword argument
reverse
controls the sense of ordering.The keyword argument
trim
can be used to set the minimum relative magnitude of components returned. Components of uncertainty greater thantrim
times the largest component returned 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
will cause all components of uncertainty with respect to all intermediate results to be reported. Whenintermediate
isTrue
,influences
cannot be specified.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 i in reporting.budget(y): ... print("{0}: {1:G}".format(i.label,i.u)) ... x1: 0.333333 x2: 0.166667 x3: 0.0111111 >>> for i in reporting.budget(y,reverse=False): ... print("{0}: {1:G}".format(i.label,i.u)) ... x3: 0.0111111 x2: 0.166667 x1: 0.333333 >>> y1 = result(x1 + x2,label='y1') >>> y2 = result(x2 + x3,label='y2') >>> for i in reporting.budget(y1 + y2,intermediate=True): ... print("{0}: {1:G}".format(i.label,i.u)) ... y1: 1.11803 y2: 0.509902
Changed in version 1.3.7: The Influence namedtuple has a third attribute uid
Changed in version 1.3.4: Added the intermediate keyword argument.
- components(y, **kwargs)
Return a sequence of uid-component of uncertainty pairs
- Parameters:
y –
UncertainReal
orUncertainComplex
: an uncertain number**kwargs –
Keyword arguments:
- Returns:
A sequence of
Component
namedtuples is returned, each with the attributesuid
andu
for a component of uncertainty (seeu_component()
). The sequence is sorted in descending order of magnitude foru
.
The keyword argument
influences
can be used to report on specific influences.The keyword argument
trim
can be used to set a minimum relative magnitude ofu
for the components returned. Components of uncertainty with a magnitude greater thantrim
times the largest value ofu
will be reported. Settrim=0
for a complete list.The keyword argument
max_number
can be used to set an upper limit on the number of components returned.Setting keyword argument
intermediate=True
causes all the components of uncertainty with respect to intermediate results to be reported. Whenintermediate
isTrue
,influences
cannot be specified.
- is_ucomplex(z)
Return
True
ifz
is an uncertain complex numberExample:
>>> z = ucomplex(1+2j,(0.1,0.2)) >>> reporting.is_ucomplex(z) True
- is_ureal(x)
Return
True
ifx
is an uncertain real numberExample:
>>> x = ureal(1,1) >>> reporting.is_ureal(x) True
- 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
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.3578842438992...
- 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
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
- 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)
Note
This function evaluates the sensitivity (partial derivative) of one uncertain number with respect to another term
x
.However, if the standard uncertainty of
x
is zero, the term is treated as being absent from the analytical model, so a sensitivity of 0 is reported.For example
>>> z1 = ucomplex(1+2j,[0,1]) >>> z2 = ucomplex(-1.2-0.9j,[1,0]) >>> z = z1*z2 >>> rp.sensitivity(z,z1.real) JacobianMatrix(rr=0.0, ri=0.0, ir=0.0, ii=0.0) >>> rp.sensitivity(z,z1.imag) JacobianMatrix(rr=0.9, ri=0.0, ir=-1.2, ii=0.0) >>> rp.sensitivity(z,z2.real) JacobianMatrix(rr=1.0, ri=0.0, ir=2.0, ii=0.0) >>> rp.sensitivity(z,z2.imag) JacobianMatrix(rr=0.0, ri=0.0, ir=0.0, ii=0.0)
If all the partial derivatives of a measurement model are required, regardless of the associated standard uncertainties, the preferred method is to assign all standard uncertainty values to unity.
Using the same example as above
>>> z1 = ucomplex(1+2j,1) >>> z2 = ucomplex(-1.2-0.9j,1) >>> z = z1*z2 >>> rp.sensitivity(z,z1.real) JacobianMatrix(rr=-1.2, ri=0.0, ir=-0.9, ii=0.0) >>> rp.sensitivity(z,z1.imag) JacobianMatrix(rr=0.9, ri=0.0, ir=-1.2, ii=0.0) >>> rp.sensitivity(z,z2.real) JacobianMatrix(rr=1.0, ri=0.0, ir=2.0, ii=0.0) >>> rp.sensitivity(z,z2.imag) JacobianMatrix(rr=-2.0, ri=0.0, ir=1.0, ii=0.0)
- u_bar(ucpt)
Return the magnitude of 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
- 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)
- 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