auto_uncertainties.uncertainty.uncertainty_containers ===================================================== .. py:module:: auto_uncertainties.uncertainty.uncertainty_containers Attributes ---------- .. autoapisummary:: auto_uncertainties.uncertainty.uncertainty_containers.UType auto_uncertainties.uncertainty.uncertainty_containers.VectorUncertainty auto_uncertainties.uncertainty.uncertainty_containers.ScalarUncertainty Classes ------- .. autoapisummary:: auto_uncertainties.uncertainty.uncertainty_containers.Uncertainty Functions --------- .. autoapisummary:: auto_uncertainties.uncertainty.uncertainty_containers.nominal_values auto_uncertainties.uncertainty.uncertainty_containers.std_devs Module Contents --------------- .. py:class:: UType Type alias for the underlying data types supporting `Uncertainty` objects. :TYPE ALIAS: | `float` | | `~numpy.floating` | | `~numpy.typing.NDArray`\[`~numpy.floating`] .. py:class:: Uncertainty(value: int, error: ErrT | None = ...) Uncertainty(value, error = ...) Uncertainty(value, error = ...) Uncertainty(value) Uncertainty(value) Uncertainty(value) Uncertainty(value, error = ...) Uncertainty(value, error = ..., skip = ...) Bases: :py:obj:`Generic`\ [\ :py:obj:`T`\ ], :py:obj:`auto_uncertainties.UncertaintyDisplay` .. autoapi-inheritance-diagram:: auto_uncertainties.uncertainty.uncertainty_containers.Uncertainty :parts: 1 :private-bases: Representation of a central value and its associated uncertainty. Parameters can be numbers, sequences, `numpy` arrays, `pint.Quantity` objects, other `Uncertainty` objects, or lists / tuples of `Uncertainty` objects. The `Uncertainty` class automatically determines which methods should be implemented based on whether it represents a vector uncertainty, or a scalar uncertainty. When instantiated with sequences or `numpy` arrays, vector-based operations are enabled; when instantiated with scalars, only scalar operations are permitted. `Uncertainty` objects only support float-based data types. If integers or integer arrays are passed as parameters to the `Uncertainty` constructor, they will be cast to `float` (or `numpy.float64` if a `numpy.integer` subclass is detected). :param value: The central value(s) :param error: The uncertainty value(s). Zero if not provided. :raise NegativeStdDevError: If ``err`` is negative, or contains negative values :raise TypeError: If the parameters are of incompatible types :raise ValueError: If the parameters have incomaptible values (e.g., misaligned array sizes) :return: An initialized `Uncertainty` object .. code-block:: python :caption: Example >>> u1 = Uncertainty(1.25, 0.25) >>> u2 = Uncertainty([1.4, 2.8, 0.09], [0.1, 0.14, 0.12]) >>> u3 = Uncertainty([1.4, 2.8, 0.09], 0.1) >>> u4 = Uncertainty(u1) >>> u5 = Uncertainty(np.array([1.4, 2.8]), np.array([0.1, 0.14])) >>> u6 = Uncertainty(np.array([1.4, 2.8]), 0.1) >>> u3.value array([1.4 , 2.8 , 0.09]) >>> u3.error array([0.1, 0.1, 0.1]) >>> np.cos(u1) 0.315322 +/- 0.237246 >>> u4 == u1 True .. code-block:: python :caption: Pint Quantity Example >>> from pint import Quantity >>> val = Quantity(2.24, 'kg') >>> err = Quantity(0.208, 'kg') >>> new_quantity = Uncertainty(val, err) >>> new_quantity .. note:: * If sequences (not NumPy arrays) are supplied for ``value`` and ``error``, their numeric values will always be converted to `numpy.float64`. * If `pint.Quantity` objects are supplied for either parameter, the behavior is exactly as described in the `from_quantities` method. * If an `Uncertainty` is supplied for ``value``, its ``error`` attribute will always override any ``error`` argument (if it is supplied). * If the ``error`` parameter is not finite, the resulting `Uncertainty` object will have its ``error`` attribute set to zero. .. seealso:: * `from_quantities` .. py:attribute:: _nom :type: T .. py:attribute:: _err :type: T .. py:method:: _init_seq(value, error) .. py:method:: _init_vec(value, error) .. py:property:: is_vector :type: bool Whether the current object is a vector uncertainty. .. py:property:: value :type: T The central value of the `Uncertainty` object. .. py:property:: error :type: T The uncertainty (error) of the `Uncertainty` object. .. py:property:: relative :type: T The relative uncertainty of the `Uncertainty` object. .. py:property:: rel :type: T Alias for `relative`. .. py:property:: rel2 :type: T The square of the relative uncertainty of the `Uncertainty` object. .. py:method:: plus_minus(error) Add an error to the `Uncertainty` object. Returns a new instance. :param error: Error value to add .. py:method:: from_string(string) :classmethod: Create an `Uncertainty` object from a string representation of the value and error. :param string: A string representation of the value and error. The error can be represented as "+/-" or "±". For instance, 5.0 +- 1.0 or 5.0 ± 1.0. .. py:method:: from_quantities(value, error=None) :classmethod: Create a `pint.Quantity` object with uncertainty from one or more `~pint.Quantity` objects. .. warning:: Static type inference is hindered when using this method. Call ``Uncertainty(value, error)`` instead for full typing support. :param value: The central value(s) of the `Uncertainty` object :param error: The uncertainty value(s) of the `Uncertainty` object (Default = `None`) .. note:: It is not necessary (and not advised) to call this method explicitly. Instantiating an `Uncertainty` object with ``Uncertainty(value, error)`` will automatically use `from_quantities` if `~pint.Quantity` objects are supplied as parameters. .. note:: * If **neither** argument is a `~pint.Quantity`, returns a regular `Uncertainty` object. * If **both** arguments are `~pint.Quantity` objects, returns a `~pint.Quantity` (wrapped `Uncertainty`) with the same units as ``value`` (attempts to convert ``error`` to ``value.units``). * If **only the** ``value`` argument is a `~pint.Quantity`, returns a `~pint.Quantity` (wrapped `Uncertainty`) object with the same units as ``value``. * If **only the** ``error`` argument is a `~pint.Quantity`, returns a `~pint.Quantity` (wrapped `Uncertainty`) object with the same units as ``error``. .. py:method:: from_sequence(value, error=None) :classmethod: Creates either an `Uncertainty` object or a `pint.Quantity` object from a supported sequence. The primary purpose of this method is to intercept sequences containing `~pint.Quantity` objects, reformat them, and then continue the instantiation process. .. warning:: Static type inference is hindered when using this method. Call ``Uncertainty(value, error)`` instead for full typing support. :param value: The central value(s) :param error: The uncertainty value(s). Zero if not provided. (Default = `None`) .. note:: It is not necessary (and not advised) to call this method explicitly. Instantiating an `Uncertainty` object with ``Uncertainty(value, error)`` will automatically use `from_sequence` if sequences are supplied as parameters. .. py:method:: from_list(value, error = None) :classmethod: Alias for `from_sequence`. .. warning:: This method is deprecated. .. py:method:: __getstate__() .. py:method:: __setstate__(state) .. py:method:: __getnewargs__() .. py:method:: __copy__() .. py:method:: __deepcopy__(memo) .. py:attribute:: _HANDLED_TYPES .. py:method:: __add__(other) .. py:attribute:: __radd__ .. py:method:: __sub__(other) .. py:method:: __rsub__(other) .. py:method:: __mul__(other) .. py:attribute:: __rmul__ .. py:method:: __truediv__(other) .. py:method:: __rtruediv__(other) .. py:attribute:: __div__ .. py:attribute:: __rdiv__ .. py:method:: __floordiv__(other) .. py:method:: __rfloordiv__(other) .. py:method:: __mod__(other) .. py:method:: __rmod__(other) .. py:method:: __divmod__(other) .. py:method:: __rdivmod__(other) .. py:method:: __pow__(other) .. py:method:: __rpow__(other) .. py:method:: __abs__() .. py:method:: __pos__() .. py:method:: __neg__() .. py:method:: _compare(other, op) .. py:attribute:: __lt__ .. py:attribute:: __le__ .. py:attribute:: __ge__ .. py:attribute:: __gt__ .. py:method:: __bool__() .. py:attribute:: __nonzero__ .. py:method:: __ne__(other) .. py:method:: __eq__(other) .. py:method:: __round__(ndigits) .. py:method:: __hash__() .. py:method:: __array_function__(func, types, args, kwargs) .. py:method:: __array_ufunc__(ufunc, method, *args, **kwargs) .. py:method:: __array__(dtype=None, *, copy=None) .. py:method:: __getattr__(item) .. py:method:: __bytes__() .. py:attribute:: __apply_to_both_ndarray__ :value: ('flatten', 'real', 'imag', 'astype', 'T', 'reshape') .. py:attribute:: __ndarray_attributes__ :value: ('dtype', 'ndim', 'size') .. py:attribute:: __array_priority__ :value: 18 .. py:method:: clip(*args, **kwargs) NumPy `~numpy.ndarray.clip` implementation. :param min: :param max: :param out: .. note:: Implemented only for vector uncertainty objects. .. py:method:: fill(value) NumPy `~numpy.ndarray.fill` implementation. :param value: .. note:: Implemented only for vector uncertainty objects. .. py:method:: put(indices, values, mode = 'raise') NumPy `~numpy.ndarray.put` implementation. :param indices: :param values: :param mode: (Default = `'raise'`) .. note:: Implemented only for vector uncertainty objects. .. py:method:: copy() Return a copy of the `Uncertainty` object. .. note:: Implemented only for vector uncertainty objects. .. py:property:: flat NumPy `~numpy.ndarray.flat` implementation. .. note:: Implemented only for vector uncertainty objects. .. py:property:: shape NumPy `~numpy.ndarray.shape` implemenetation. .. note:: Implemented only for vector uncertainty objects. .. py:property:: nbytes NumPy `~numpy.ndarray.nbytes` implementation. .. note:: Implemented only for vector uncertainty objects. .. py:method:: searchsorted(v, side = 'left', sorter=None) NumPy `~numpy.ndarray.searchsorted` implementation. .. note:: Implemented only for vector uncertainty objects. .. py:method:: tolist() NumPy `~numpy.ndarray.tolist` implementation. .. note:: Implemented only for vector uncertainty objects. .. py:method:: view() NumPy `~numpy.ndarray.view` implementation. .. note:: Implemented only for vector uncertainty objects. .. py:method:: __iter__() .. py:method:: __len__() .. py:method:: __getitem__(key) .. py:method:: __setitem__(key, value) .. py:method:: __float__() .. py:method:: __int__() .. py:method:: __complex__() .. py:data:: VectorUncertainty Alias for `Uncertainty` to maintain backward compatibility. .. py:data:: ScalarUncertainty Alias for `Uncertainty` to maintain backward compatibility. .. py:function:: nominal_values(x: Uncertainty[UType]) -> UType nominal_values(x: G) -> G Return the central value of an `Uncertainty` object if it is one, otherwise returns the object. .. py:function:: std_devs(x: Uncertainty[UType]) -> UType std_devs(x: G) -> G Return the uncertainty of an `Uncertainty` object if it is one, otherwise returns zero.