lezargus.library.math module#

Different mathematical operations which we also propagate uncertainty.

Many mathematical operations are needed, and the uncertainties of these operations need to be propagated. We gather these functions so that they can easily be reused or better default methods used in place.

lezargus.library.math.add(augend: hint.NDArray | float, addend: hint.NDArray | float, augend_uncertainty: hint.NDArray | float | None = 0, addend_uncertainty: hint.NDArray | float | None = 0) tuple[hint.NDArray | float, hint.NDArray | float][source]#

Add two values and propagate uncertainties.

Parameters:
  • augend (ndarray or float) – The “left”-side of the addition.

  • addend (ndarray or float) – The “right”-side of the addition.

  • augend_uncertainty (ndarray, default = 0) – The uncertainty on the augend term. If None, we assume that the uncertainty is 0.

  • addend_uncertainty (ndarray, default = 0) – The uncertainty on the addend term. If None, we assume that the uncertainty is 0.

Returns:

  • result (ndarray) – The result of the addition operation.

  • uncertainty (ndarray) – The propagated uncertainty.

lezargus.library.math.covariance(param_1: hint.NDArray | float, param_2: hint.NDArray | float) float[source]#

Compute the covariance for two parameters.

If the covariance cannot be computed, we default to 0.

Parameters:
  • param_1 (ndarray or float) – The first parameter.

  • param_2 (ndarray or float) – The second parameter.

Returns:

covar – The covariance.

Return type:

float

lezargus.library.math.divide(numerator: float | hint.NDArray, denominator: float | hint.NDArray, numerator_uncertainty: hint.NDArray | float | None = None, denominator_uncertainty: hint.NDArray | float | None = None) tuple[float | hint.NDArray, float | hint.NDArray][source]#

Divide two values and propagate uncertainties.

Note, the typical formula for the propagation of uncertainties for division can lead to issues because of division by zero. We rewrite the equations. This reformulation is based on Astropy’s reformulation. See Multiplication and Division for more information.

Parameters:
  • numerator (ndarray) – The numerator of the division; the top value.

  • denominator (ndarray) – The denominator of the division; the bottom value.

  • numerator_uncertainty (ndarray, default = None) – The uncertainty on the numerator term. If None, we assume that the uncertainty is 0.

  • denominator_uncertainty (ndarray, default = None) – The uncertainty on the denominator term. If None, we assume that the uncertainty is 0.

Returns:

  • result (ndarray) – The result of the division operation.

  • uncertainty (ndarray) – The propagated uncertainty.

lezargus.library.math.exponentiate(base: float | hint.NDArray, exponent: float | hint.NDArray, base_uncertainty: hint.NDArray | float | None = None, exponent_uncertainty: hint.NDArray | float | None = None) tuple[hint.NDArray, hint.NDArray][source]#

Compute the exponent of two values and propagate uncertainties.

Parameters:
  • base (ndarray) – The base of the exponentiation; the lower value.

  • exponent (ndarray) – The exponent of the exponentiation; the upper value.

  • base_uncertainty (ndarray, default = None) – The uncertainty on the base term. If None, we assume that the uncertainty is 0.

  • exponent_uncertainty (ndarray, default = None) – The uncertainty on the exponent term. If None, we assume that the uncertainty is 0.

Returns:

  • result (ndarray) – The result of the exponentiation operation.

  • uncertainty (ndarray) – The propagated uncertainty.

lezargus.library.math.integrate_discrete(variable: hint.NDArray, integrand: hint.NDArray, integrand_uncertainty: hint.NDArray | float | None = None) tuple[float, float][source]#

Integrate discrete values and propagate the errors.

Parameters:
  • variable (ndarray) – The variable being integrated over.

  • integrand (ndarray) – The integrand function being integrated.

  • integrand_uncertainty (ndarray, default = None) – The uncertainty in the integrand. If None, we assume that the uncertainty is 0.

Returns:

  • result (float) – The result the integration.

  • uncertainty (float) – The uncertainty on the integration.

lezargus.library.math.logarithm(antilogarithm: hint.NDArray, base: hint.NDArray, antilogarithm_uncertainty: hint.NDArray | float | None = None) tuple[hint.NDArray, hint.NDArray][source]#

Compute the logarithm of two values and propagate uncertainties.

Parameters:
  • antilogarithm (ndarray) – The inside value of the logarithm; what we are taking a logarithm of.

  • base (ndarray) – The logarithm base.

  • antilogarithm_uncertainty (ndarray, default = None) – The uncertainty in the anti-logarithm.

Returns:

  • result (ndarray) – The result of the exponentiation operation.

  • uncertainty (ndarray) – The propagated uncertainty.

lezargus.library.math.median(values: hint.NDArray, uncertainties: hint.NDArray | None = None, weights: hint.NDArray | None = None) tuple[float, float][source]#

Calculate the median and uncertainty.

See Median for more information on the general median.

Parameters:
  • values (ndarray) – The values which we will compute the median of.

  • uncertainties (ndarray, default = None) – The uncertainties in the values. If None, we default to no uncertainty.

  • weights (ndarray, default = None) – The weights for the given values for the median of. If None, we assume equal weights. This is only used for uncertainty propagation.

Returns:

  • median_value (float) – The calculated median.

  • median_uncertainty (float) – The calculated uncertainty in the median.

lezargus.library.math.modulo(numerator: hint.NDArray | float, denominator: hint.NDArray | float, numerator_uncertainty: hint.NDArray | float | None = None, denominator_uncertainty: hint.NDArray | float | None = None) tuple[hint.NDArray, hint.NDArray][source]#

Compute the modulo of two values and propagate uncertainties.

This function properly handles floating point modulo operations and thus is preferred if floats are involved.

Parameters:
  • numerator (ndarray) – The numerator of the modulo division; the top value.

  • denominator (ndarray) – The denominator of the modulo division; the bottom value.

  • numerator_uncertainty (ndarray, default = None) – The uncertainty on the numerator term. If None, we assume that the uncertainty is 0.

  • denominator_uncertainty (ndarray, default = None) – The uncertainty on the denominator term. If None, we assume that the uncertainty is 0.

Returns:

  • result (ndarray) – The result of the modulo division operation.

  • uncertainty (ndarray) – The propagated uncertainty.

lezargus.library.math.multiply(multiplier: hint.NDArray | float, multiplicand: hint.NDArray | float, multiplier_uncertainty: hint.NDArray | float | None = None, multiplicand_uncertainty: hint.NDArray | float | None = None) tuple[float | hint.NDArray, float | hint.NDArray][source]#

Multiply two values and propagate uncertainties.

Note, the typical formula for the propagation of uncertainties for multiplication can lead to issues because of division by zero. We rewrite the equations. This reformulation is based on Astropy’s reformulation. See Multiplication and Division for more information.

Parameters:
  • multiplier (ndarray) – The “left”-side of the multiplication.

  • multiplicand (ndarray) – The “right”-side of the multiplication.

  • multiplier_uncertainty (ndarray, default = None) – The uncertainty on the multiplier term. If None, we assume that the uncertainty is 0.

  • multiplicand_uncertainty (ndarray, default = None) – The uncertainty on the multiplicand term. If None, we assume that the uncertainty is 0.

Returns:

  • result (ndarray) – The result of the multiplication operation.

  • uncertainty (ndarray) – The propagated uncertainty.

lezargus.library.math.nan_median(values: hint.NDArray, uncertainties: hint.NDArray | None = None, weights: hint.NDArray | None = None) tuple[float, float][source]#

Calculate the no-NaN median and uncertainty.

This function is similar to median(), but we do not include any non-finite values.

See Median for more information.

Parameters:
  • values (ndarray) – The values which we will compute the median of.

  • uncertainties (ndarray, default = None) – The uncertainties in the values. If None, we default to no uncertainty.

  • weights (ndarray, default = None) – The weights for the given values for the median of. If None, we assume equal weights. This is only used for uncertainty propagation.

Returns:

  • median_value (float) – The calculated median.

  • median_uncertainty (float) – The calculated uncertainty in the median.

lezargus.library.math.nan_weighted_mean(values: hint.NDArray, uncertainties: hint.NDArray | None = None, weights: hint.NDArray | None = None) tuple[float, float][source]#

Calculate the no-NaN weighted mean and uncertainty.

This function is similar to weighted_mean(), but we do not include any non-finite values.

See Weighted Mean for more information.

Parameters:
  • values (ndarray) – The values which we will compute the weighted mean of.

  • uncertainties (ndarray, default = None) – The uncertainties in the values. If None, we default to no uncertainty.

  • weights (ndarray, default = None) – The weights for the given values for the weighted mean. If None, we assume equal weights.

Returns:

  • mean_value (float) – The calculated mean.

  • mean_uncertainty (float) – The calculated uncertainty in the mean.

lezargus.library.math.normalize_weights(weights: hint.NDArray) hint.NDArray[source]#

Normalize weights, handling NaNs so they don’t screw things up.

We do not include NaNs in the normalization of the weights, however we still keep them as weights to allow for its proper propagation when needed.

Parameters:

weights (ndarray) – The weights to normalize.

Returns:

normalized – The weights normalized.

Return type:

ndarray

lezargus.library.math.subtract(minuend: hint.NDArray | float, subtrahend: hint.NDArray | float, minuend_uncertainty: hint.NDArray | float | None = None, subtrahend_uncertainty: hint.NDArray | float | None = None) tuple[float | hint.NDArray, float | hint.NDArray][source]#

Subtract two values and propagate uncertainties.

Parameters:
  • minuend (ndarray) – The “left”-side of the subtraction.

  • subtrahend (ndarray) – The “right”-side of the subtraction.

  • minuend_uncertainty (ndarray, default = None) – The uncertainty on the minuend term. If None, we assume that the uncertainty is 0.

  • subtrahend_uncertainty (ndarray, default = None) – The uncertainty on the subtrahend term. If None, we assume that the uncertainty is 0.

Returns:

  • result (ndarray) – The result of the subtraction operation.

  • uncertainty (ndarray) – The propagated uncertainty.

lezargus.library.math.weighted_mean(values: hint.NDArray, uncertainties: hint.NDArray | None = None, weights: hint.NDArray | None = None) tuple[float, float][source]#

Calculate a weighted mean, propagating uncertainties where needed.

This function calculates the weighted arithmetic mean of a group of samples and weights. If the weights are not provided, we default to equal weights and thus the ordinary arithmetic mean. If any value, uncertainty, or weight is NaN, the result is a NaN.

See Weighted Mean for more information.

Parameters:
  • values (ndarray) – The values which we will compute the weighted mean of.

  • uncertainties (ndarray, default = None) – The uncertainties in the values. If None, we default to no uncertainty.

  • weights (ndarray, default = None) – The weights for the given values for the weighted mean. If None, we assume equal weights.

Returns:

  • mean_value (float) – The calculated mean.

  • mean_uncertainty (float) – The calculated uncertainty in the mean.

lezargus.library.math.weighted_quantile_mean(values: hint.NDArray, uncertainties: hint.NDArray | None = None, weights: hint.NDArray | None = None, quantile: float | tuple[float, float] = (0, 1)) tuple[float, float][source]#

Calculate the no-NaN weighted quantile mean and uncertainty.

See Weighted Mean for more information on the general weighted mean; the quantile functionality only reduces the input space.

Parameters:
  • values (ndarray) – The values which we will compute the weighted quantile mean of.

  • uncertainties (ndarray, default = None) – The uncertainties in the values. If None, we default to no uncertainty.

  • weights (ndarray, default = None) – The weights for the given values for the weighted quantile mean. If None, we assume equal weights.

  • quantile (float or tuple, default = (0, 1)) – A single quantile value to cut off each end; or the minimum and maximum quantile to cut from the entire array before taking the average. Must be between 0 and 1.

Returns:

  • mean_value (float) – The calculated mean.

  • mean_uncertainty (float) – The calculated uncertainty in the mean.