Skip to main content
`Ctrl`+`K`

# NDArithmeticMixin

class astropy.nddata.NDArithmeticMixin

  Bases: `object`

  Mixin class to add arithmetic to an NDData object.

  When subclassing, be sure to list the superclasses in the correct order so that the subclass sees NDData as the main superclass. See `NDDataArray` for an example.

  Notes

  This class only aims at covering the most common cases so there are certain restrictions on the saved attributes:

      - ``uncertainty`` : has to be something that has a `NDUncertainty`-like
        interface for uncertainty propagation
      - ``mask`` : has to be something that can be used by a bitwise ``or``
        operation.
      - ``wcs`` : has to implement a way of comparing with ``=`` to allow
        the operation.

  But there is a workaround that allows to disable handling a specific attribute and to simply set the results attribute to `None` or to copy the existing attribute (and neglecting the other). For example for uncertainties not representing an `NDUncertainty`-like interface you can alter the `propagate_uncertainties` parameter in `NDArithmeticMixin.add()`. `None` means that the result will have no uncertainty, `False` means it takes the uncertainty of the first operand (if this does not exist from the second operand) as the result’s uncertainty. This behavior is also explained in the docstring for the different arithmetic operations.

  Decomposing the units is not attempted, mainly due to the internal mechanics of `Quantity`, so the resulting data might have units like `km/m` if you divided for example 100km by 5m. So this Mixin has adopted this behavior.

  Examples

  Using this Mixin with `NDData`:

      >>> from astropy.nddata import NDData, NDArithmeticMixin
      >>> class NDDataWithMath(NDArithmeticMixin, NDData):
      ...     pass

  Using it with one operand on an instance:

      >>> ndd = NDDataWithMath(100)
      >>> ndd.add(20)
      NDDataWithMath(120)

  Using it with two operand on an instance:

      >>> ndd = NDDataWithMath(-4)
      >>> ndd.divide(1, ndd)
      NDDataWithMath(-0.25)

  Using it as classmethod requires two operands:

      >>> NDDataWithMath.subtract(5, 4)
      NDDataWithMath(1)

  Methods Summary

  `add`(operand[, operand2]) | Performs addition by evaluating `self` + `operand`.
  `divide`(operand[, operand2]) | Performs division by evaluating `self` / `operand`.
  `max`(**kwargs) |
  `mean`(**kwargs) |
  `min`(**kwargs) |
  `multiply`(operand[, operand2]) | Performs multiplication by evaluating `self` * `operand`.
  `subtract`(operand[, operand2]) | Performs subtraction by evaluating `self` - `operand`.
  `sum`(**kwargs) |

  Methods Documentation

  classmethod add(operand, operand2=None, **kwargs)

    Performs addition by evaluating `self` + `operand`.

    Parameters:
      operand, operand2 `NDData` astropy:-like instance

        If `operand2` is `None` or not given it will perform the operation `self` + `operand`. If `operand2` is given it will perform `operand` + `operand2`. If the method was called on a class rather than on the instance `operand2` must be given.

      propagate_uncertainties `bool` or `None`, optional

        If `None` the result will have no uncertainty. If `False` the result will have a copied version of the first operand that has an uncertainty. If `True` the result will have a correctly propagated uncertainty from the uncertainties of the operands but this assumes that the uncertainties are `NDUncertainty`-like. Default is `True`.

        Changed in version 1.2: This parameter must be given as keyword-parameter. Using it as positional parameter is deprecated. `None` was added as valid parameter value.

      handle_mask `python:callable()`, `'first_found'` or `None`, optional

        If `None` the result will have no mask. If `'first_found'` the result will have a copied version of the first operand that has a mask). If it is a callable then the specified callable must create the results `mask` and if necessary provide a copy. Default is `numpy.logical_or`.

        Added in version 1.2.

      handle_meta `python:callable()`, `'first_found'` or `None`, optional

        If `None` the result will have no meta. If `'first_found'` the result will have a copied version of the first operand that has a (not empty) meta. If it is a callable then the specified callable must create the results `meta` and if necessary provide a copy. Default is `None`.

        Added in version 1.2.

      compare_wcs `python:callable()`, `'first_found'` or `None`, optional

        If `None` the result will have no wcs and no comparison between the wcs of the operands is made. If `'first_found'` the result will have a copied version of the first operand that has a wcs. If it is a callable then the specified callable must compare the `wcs`. The resulting `wcs` will be like if `False` was given otherwise it raises a `ValueError` if the comparison was not successful. Default is `'first_found'`.

        Added in version 1.2.

      uncertainty_correlation number or `ndarray`, optional

        The correlation between the two operands is used for correct error propagation for correlated data as given in: https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulas Default is 0.

        Added in version 1.2.

      kwargs

        Any other parameter that should be passed to the callables used.

    Returns:
      result `NDData` astropy:-like

        The resulting dataset

    Notes

    If a `callable` is used for `mask`, `wcs` or `meta` the callable must accept the corresponding attributes as first two parameters. If the callable also needs additional parameters these can be defined as `kwargs` and must start with `"wcs_"` (for wcs callable) or `"meta_"` (for meta callable). This startstring is removed before the callable is called.

    `"first_found"` can also be abbreviated with `"ff"`.

  classmethod divide(operand, operand2=None, **kwargs)

    Performs division by evaluating `self` / `operand`.

    Parameters:
      operand, operand2 `NDData` astropy:-like instance

        If `operand2` is `None` or not given it will perform the operation `self` / `operand`. If `operand2` is given it will perform `operand` / `operand2`. If the method was called on a class rather than on the instance `operand2` must be given.

      propagate_uncertainties `bool` or `None`, optional

        If `None` the result will have no uncertainty. If `False` the result will have a copied version of the first operand that has an uncertainty. If `True` the result will have a correctly propagated uncertainty from the uncertainties of the operands but this assumes that the uncertainties are `NDUncertainty`-like. Default is `True`.

        Changed in version 1.2: This parameter must be given as keyword-parameter. Using it as positional parameter is deprecated. `None` was added as valid parameter value.

      handle_mask `python:callable()`, `'first_found'` or `None`, optional

        If `None` the result will have no mask. If `'first_found'` the result will have a copied version of the first operand that has a mask). If it is a callable then the specified callable must create the results `mask` and if necessary provide a copy. Default is `numpy.logical_or`.

        Added in version 1.2.

      handle_meta `python:callable()`, `'first_found'` or `None`, optional

        If `None` the result will have no meta. If `'first_found'` the result will have a copied version of the first operand that has a (not empty) meta. If it is a callable then the specified callable must create the results `meta` and if necessary provide a copy. Default is `None`.

        Added in version 1.2.

      compare_wcs `python:callable()`, `'first_found'` or `None`, optional

        If `None` the result will have no wcs and no comparison between the wcs of the operands is made. If `'first_found'` the result will have a copied version of the first operand that has a wcs. If it is a callable then the specified callable must compare the `wcs`. The resulting `wcs` will be like if `False` was given otherwise it raises a `ValueError` if the comparison was not successful. Default is `'first_found'`.

        Added in version 1.2.

      uncertainty_correlation number or `ndarray`, optional

        The correlation between the two operands is used for correct error propagation for correlated data as given in: https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulas Default is 0.

        Added in version 1.2.

      kwargs

        Any other parameter that should be passed to the callables used.

    Returns:
      result `NDData` astropy:-like

        The resulting dataset

    Notes

    If a `callable` is used for `mask`, `wcs` or `meta` the callable must accept the corresponding attributes as first two parameters. If the callable also needs additional parameters these can be defined as `kwargs` and must start with `"wcs_"` (for wcs callable) or `"meta_"` (for meta callable). This startstring is removed before the callable is called.

    `"first_found"` can also be abbreviated with `"ff"`.

  classmethod max(**kwargs)
  classmethod mean(**kwargs)
  classmethod min(**kwargs)
  classmethod multiply(operand, operand2=None, **kwargs)

    Performs multiplication by evaluating `self` * `operand`.

    Parameters:
      operand, operand2 `NDData` astropy:-like instance

        If `operand2` is `None` or not given it will perform the operation `self` * `operand`. If `operand2` is given it will perform `operand` * `operand2`. If the method was called on a class rather than on the instance `operand2` must be given.

      propagate_uncertainties `bool` or `None`, optional

        If `None` the result will have no uncertainty. If `False` the result will have a copied version of the first operand that has an uncertainty. If `True` the result will have a correctly propagated uncertainty from the uncertainties of the operands but this assumes that the uncertainties are `NDUncertainty`-like. Default is `True`.

        Changed in version 1.2: This parameter must be given as keyword-parameter. Using it as positional parameter is deprecated. `None` was added as valid parameter value.

      handle_mask `python:callable()`, `'first_found'` or `None`, optional

        If `None` the result will have no mask. If `'first_found'` the result will have a copied version of the first operand that has a mask). If it is a callable then the specified callable must create the results `mask` and if necessary provide a copy. Default is `numpy.logical_or`.

        Added in version 1.2.

      handle_meta `python:callable()`, `'first_found'` or `None`, optional

        If `None` the result will have no meta. If `'first_found'` the result will have a copied version of the first operand that has a (not empty) meta. If it is a callable then the specified callable must create the results `meta` and if necessary provide a copy. Default is `None`.

        Added in version 1.2.

      compare_wcs `python:callable()`, `'first_found'` or `None`, optional

        If `None` the result will have no wcs and no comparison between the wcs of the operands is made. If `'first_found'` the result will have a copied version of the first operand that has a wcs. If it is a callable then the specified callable must compare the `wcs`. The resulting `wcs` will be like if `False` was given otherwise it raises a `ValueError` if the comparison was not successful. Default is `'first_found'`.

        Added in version 1.2.

      uncertainty_correlation number or `ndarray`, optional

        The correlation between the two operands is used for correct error propagation for correlated data as given in: https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulas Default is 0.

        Added in version 1.2.

      kwargs

        Any other parameter that should be passed to the callables used.

    Returns:
      result `NDData` astropy:-like

        The resulting dataset

    Notes

    If a `callable` is used for `mask`, `wcs` or `meta` the callable must accept the corresponding attributes as first two parameters. If the callable also needs additional parameters these can be defined as `kwargs` and must start with `"wcs_"` (for wcs callable) or `"meta_"` (for meta callable). This startstring is removed before the callable is called.

    `"first_found"` can also be abbreviated with `"ff"`.

  classmethod subtract(operand, operand2=None, **kwargs)

    Performs subtraction by evaluating `self` - `operand`.

    Parameters:
      operand, operand2 `NDData` astropy:-like instance

        If `operand2` is `None` or not given it will perform the operation `self` - `operand`. If `operand2` is given it will perform `operand` - `operand2`. If the method was called on a class rather than on the instance `operand2` must be given.

      propagate_uncertainties `bool` or `None`, optional

        If `None` the result will have no uncertainty. If `False` the result will have a copied version of the first operand that has an uncertainty. If `True` the result will have a correctly propagated uncertainty from the uncertainties of the operands but this assumes that the uncertainties are `NDUncertainty`-like. Default is `True`.

        Changed in version 1.2: This parameter must be given as keyword-parameter. Using it as positional parameter is deprecated. `None` was added as valid parameter value.

      handle_mask `python:callable()`, `'first_found'` or `None`, optional

        If `None` the result will have no mask. If `'first_found'` the result will have a copied version of the first operand that has a mask). If it is a callable then the specified callable must create the results `mask` and if necessary provide a copy. Default is `numpy.logical_or`.

        Added in version 1.2.

      handle_meta `python:callable()`, `'first_found'` or `None`, optional

        If `None` the result will have no meta. If `'first_found'` the result will have a copied version of the first operand that has a (not empty) meta. If it is a callable then the specified callable must create the results `meta` and if necessary provide a copy. Default is `None`.

        Added in version 1.2.

      compare_wcs `python:callable()`, `'first_found'` or `None`, optional

        If `None` the result will have no wcs and no comparison between the wcs of the operands is made. If `'first_found'` the result will have a copied version of the first operand that has a wcs. If it is a callable then the specified callable must compare the `wcs`. The resulting `wcs` will be like if `False` was given otherwise it raises a `ValueError` if the comparison was not successful. Default is `'first_found'`.

        Added in version 1.2.

      uncertainty_correlation number or `ndarray`, optional

        The correlation between the two operands is used for correct error propagation for correlated data as given in: https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulas Default is 0.

        Added in version 1.2.

      kwargs

        Any other parameter that should be passed to the callables used.

    Returns:
      result `NDData` astropy:-like

        The resulting dataset

    Notes

    If a `callable` is used for `mask`, `wcs` or `meta` the callable must accept the corresponding attributes as first two parameters. If the callable also needs additional parameters these can be defined as `kwargs` and must start with `"wcs_"` (for wcs callable) or `"meta_"` (for meta callable). This startstring is removed before the callable is called.

    `"first_found"` can also be abbreviated with `"ff"`.

  classmethod sum(**kwargs)