NDUncertainty

class astropy.nddata.NDUncertainty(array=None, unit=None, copy=True)

Bases: object

This is the base class for uncertainty classes used with NDData.

Parameters:

array: any type, optional

The array or value (the parameter name is due to historical reasons) of the uncertainty. ndarray, Quantity or NDUncertainty subclasses are recommended. If the array is list-like or ndarray-like it will be cast to a base ndarray. Default is None.

unit: `~astropy.units.Unit` or str, optional

The unit of the uncertainty array. If input is a string this will be converted to an Unit. Default is None.

copy : bool, optional

Save the array as copy or as reference. True copies the uncertainty array before saving it while False tries to save it as reference. Note however that it is not always possible to save is as reference. Default is True.

Raises:

IncompatibleUncertaintiesException

If given another NDUncertainty-like class as array if their uncertainty_type is not the same.

Notes

1. NDUncertainty is an abstract class and should never be instantiated directly.
2. NDUncertainty takes a unit parameter and if the array is something with a unit (like a Quantity or another NDUncertainty) the unit parameter is considered the true unit of the NDUncertainty instance and a warning is issued that the unit is overwritten. No conversion is done while overwriting the unit so the uncertainty array is not altered.
3. NDUncertainty provides a :meth:__getitem__ method so slicing is in theory supported but that relies on the array being something that actually can be sliced.
4. Subclasses need to define:
   • property uncertainty_type which should be a small string defining the kind of uncertainty. Recommened is std for standard deviation var for variance (following the numpy conventions).
   • _propagate_add() and similar ones which takes the uncertainty of the other element and the resulting data (or quantity) and calculates the array (or quantity) which represents the resulting uncertainty.
   • Most of the time a subclasses will need to extend or override the NDUncertainty._convert_uncertainty(). This method is responsible for checking that the other uncertainty has a class that can be used for uncertainty propagation. (NDUncertainty only checks that it is another instance or subclass of NDUncertainty). For subclasses that cannot propagate with arbitary other uncertainties they should check that the other uncertainty has the same class as they are or convert it to such a class. (Handling units should be part of the _propagate_* methods and NOT done in there).
   • The NDUncertainty.propagate() method should only be overriden if one wants to allow other operations than addition, subtraction, multiplication or division. This function is the common entry point of any arithmetic computation that tries to propagate uncertainties and is responsible for calling the appropriate _propagate_* method and then returns another instance of the same class with the results uncertainty.
5. NDUncertainty and it’s subclasses can only be used for uncertainty propagation if their parent_nddata attribute is a reference to the NDData object. This is needed since many kinds of propagation need the actual data besides the uncertainty.
6. If a unit is implicit (data had a unit) or explicitly passed to the __init__ one should be sure that this unit is identical or convertable to the unit of the parent. Otherwise uncertainty propagation should fail.

Attributes Summary

array	numpy.ndarray: the uncertainty’s value.
parent_nddata	NDData reference: The NDData whose uncertainty this is.
supports_correlated	bool: Supports uncertainty propagation with correlated uncertainties?
uncertainty_type	str: Short description which kind of uncertainty is saved.
unit	Unit: The unit of the uncertainty.

Methods Summary

propagate(operation, other_nddata, ...)

Calculate the resulting uncertainty given an operation on the data.

Attributes Documentation

array

numpy.ndarray: the uncertainty’s value.

parent_nddata

NDData reference: The NDData whose uncertainty this is.

In case the reference is not set uncertainty propagation will not be possible since almost all kinds of propagation need the uncertain data besides the uncertainty.

supports_correlated

bool: Supports uncertainty propagation with correlated uncertainties?

uncertainty_type

str: Short description which kind of uncertainty is saved.

Defined as abstract property so subclasses have to override this and return a string.

unit

Unit: The unit of the uncertainty.

Even though it is not enforced the unit should be convertable to the parent_nddata unit. Otherwise uncertainty propagation might give wrong results.

If the unit is not set the unit of the parent will be returned.

Methods Documentation

propagate(operation, other_nddata, result_data, correlation)

Calculate the resulting uncertainty given an operation on the data.

Parameters:

operation: callable

The operation that is performed on the NDData. Supported are numpy.add, numpy.subtract, numpy.multiply and numpy.true_divide.

other_nddata: `NDData` instance

The second NDData in the arithmetic operation.

result_data: `~numpy.ndarray` or `~astropy.units.Quantity`

The result of the arithmetic operations. This saves some duplicate calculations.

correlation: number or `~numpy.ndarray`

The correlation (rho) is defined between the uncertainties in sigma_AB = sigma_A * sigma_B * rho. A value of 0 means uncorrelated operands.

Returns:

resulting_uncertainty: NDUncertainty instance

Another instance of the same NDUncertainty subclass containing the uncertainty of the result.

Raises:

ValueError:

If the operation is not supported or if correlation is not zero but the subclass does not support correlated uncertainties.

Notes

This method at first tries to convert the uncertainty of the other operand to a NDUncertainty subclass that is useable for uncertainty propagation (this check and optional conversion is done in NDUncertainty._convert_uncertainty()) and then the appropriate _propagate_* method for calculating the resulting uncertainty is invoked. Afterwards this function wraps it into another instance of NDUncertainty and returns it.