The upy uncertain ndarray: class undarray

class upy.undarray(object=None, uncertainty=None, derivatives=None, characteristic=None, dtype=None, shape=None, sigmas=None)

Implements uncertain ndarrays. The name is derived from numpy.ndarray. Read-ony attributes:

.value - The plain nominal value of the undarray.

Initialisation methods

undarray.__init__(object=None, uncertainty=None, derivatives=None, characteristic=None, dtype=None, shape=None, sigmas=None)

If OBJECT is an undarray, its content will not be copied. (This initialisation scheme is intendend to make shure that some object is an undarray.)

If DERIVATIVES and OBJECT are not None, DERIVATIVES must be a list [(undarray instance: derivative), ...], giving the derivatives with that the new undarray depends on the key undarrays. OBJECT will be converted to an numpy.ndarray.

If UNCERTAINTY and OBJECT aren’t None, OBJECT and UNCERTAINTY will be converted to numpy.ndarrays. SIGMAS tells how many sigmas the UNCERTAINTY covers. The default for SIGMAS is 2.0. SIGMAS will be converted by float().

If CHARACTERISTIC and OBJECT are not None, OBJECT is converted to an numpy.ndarray, and the CHARACTERISTIC is used directly without copying.

If OBJECT isn’t None, but all other branches mentioned so far are not fulfilled, Mixed-Mode applies. In this mode, OBJECT will not be converted to an numpy.ndarray, but will be recursed into. Nevertheless the objects comprising OBJECT must match the effective shape of the OBJECT. OBJECT may be contain upy.undarrays. The shape of the new undarray is obtained from the first scalar element in the upy.ravel()ed version of the OBJECT and from the lengthes of the sequences containing that first element. Scalars are objects for which numpy.isscalar() returns True. When there are shape inconsistencies, an exception will occur. If the first element is an undarray, its shape will be taken into account. In Mixed-Mode, the DTYPE of the initially zero .value ndarray is either determined automatically from all values contained in OBJECT and undarrays therein, or can be given explicitly via DTYPE. It is strongly recommended to use DTYPE, because raveling large datasets can be very expensive in memory and time both.

If also OBJECT is None, SHAPE is taken into account, to create a new, zero-valued undarray of dtype DTYPE (None means numyp.float).

If none of these branches match, ValueError will be raised.

Methods to obtain net quantities


Returns the variance array, i.e., sigma ** 2.


Returns the sigma array, i.e., the square root of the variance.


Returns the dispersion, i.e., the sigma.


Returns the standard deviation.


Returns the error, i.e., 2 * sigma.


Returns SIGMAS * (standard deviation).


Returns a numpy.ndarray suitable for weighting this undarray. The weights are 1.0 / .variance(). When a variance element is zero, the used variance is 1.0.

ndarray methods, alphabetically sorted

Note: Not all of these method are released yet.

undarray.argmax(*args, **kwargs)

Refer to numpy.argmax() for documentation of the functionality.

undarray.argmin(*args, **kwargs)

Refer to numpy.argmin() for documentation of the functionality.

undarray.argsort(*args, **kwargs)

Refer to numpy.argsort() for documentation of the functionality.

undarray.clip(a, a_min, a_max)

Refer to numpy.clip() for documentation of the functionality.

The errors of the clipped values will be set to zero and any dependency stored before in them will be removed. Thus the clipped values are then exact.

Returned is a copy.

undarray.compress(*compress_args, **compress_kwargs)

Refer to numpy.compress() for documentation of the functionality.


Returns a copy of the undarray. Note that only the data is copied, and no new names for the dependencies are created. This means, that the undarray will bahave in all arithmetics the same as the original, except for that it has its own memory.

This behaviour is choosen, because there may happen too many complications with lost intercorrelations when the data would be dropped and replaced by new names completely. Also, it cannot be decided at this program level which correlation to keep and which to “copy”, i.e., to replicate with new names.


Calculate the cumulative product along axis AXIS. If AXIS is not given, perform the operation on the flattened array.

undarray.flatten(*flatten_args, **flatten_kwargs)

Returns a copy with flatten()’ed arrays.

undarray.repeat(*repeat_args, **repeat_kwargs)

Returns a copy with repeat()’ed arrays.

undarray.reshape(*reshape_args, **reshape_kwargs)

Returns a copy with reshape()’ed arrays.

undarray.transpose(*transpose_args, **transpose_kwargs)

Returns a copy with transpos()’ed arrays.

Printing methods

undarray.printable(sigmas=None, enforce_sign_value=None, enforce_sign_exponent=None, format=None, precision=None, infinite_precision=None)

Return a printable object created from this undarray instance.

SIGMA sigmas will be displayed as uncertainty (default 2).

To enforce the printing of optional ‘+’ signs in the value and the exponent, use ENFORCE_SIGN_VALUE and ENFORCE_SIGN_EXPONENT.

The three FORMATS supported are ‘float’, e.g. 0.120 +- 0.034, ‘exp’, e.g. (1.20 +- 0.34) 10^-1, and ‘int’, e.g. 12300 +- 4500. By default, the format will be determined from the values and the uncertainties. The ‘int’ mode is choosen upon integer type of values and uncertainties. If the uncertainty is all-zero, the printing mode will be determined from the value alone, else both must be integer to enable int printing mode.

PRECISION influences the precision of the output. Generally, the precision is determined from the uncertainty. With PRECISION = 1, the output will look like (1.0 +- 0.3), with PRECISION = 2, like (1.00 +- 0.23). If the uncertainty is zero, INFINITE_PRECISION will be used instead, giving the number of digits behind the point, either in float or exp mode. In int mode all post-point digits are suppressed. If both the value and the uncertainty are zero, only (0 +- 0) is printed. The default PRECISION is 2.

Note that you can affect the way the array is printed also by calling numpy.set_printoptions().


For scalar undarrays, return a useful print value of the value and the error. For everything else, return some symbolic string.


Binary arithmetics


Reverse binary arithmetics


Augmented arithmetics

... are emulated.

Unary operators


This works for real-valued undarrays.

Comparison operators


Keying methods


Returns the given subset of the undarray array, by applying the KEY both the the value and the Characteristic. VALUE is assumed to be an undarray.

undarray.__setitem__(key, value)

Updates the given subset of the undarray array, by replacing the value’s subset and the Characteristic’s subset. VALUE is supposed to be an undarray.