numdaplot 0.1.0__py3-none-any.whl

numdaplot/arrays/calculation/location_statistics.py

@@ -0,0 +1,268 @@
+"""
+Statistics locating or summing the values of an Array: sum, mean, median, deviation, quantile, min, max.
+
+Each function ignores missing values and reduces the whole Array when ``axis`` is ``None``.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any, cast
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.selection.missing_mask import find_missing
+from numdaplot.statistics.quantile import Quantile
+from numdaplot.statistics.statistic import Statistic
+
+MISSING_AWARE_KINDS = frozenset({"f", "M", "m"})
+TEXT_KIND = "T"
+LOWEST_TEXT = ""
+POPULATION_DEGREES_OF_FREEDOM = 0
+
+
+def compute_sum(values: NDArray[Any], axis: int | None, statistic: Statistic) -> Any:
+	"""
+	Return the sum of the present values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of a number or boolean Array.
+	axis
+		The numpy axis to reduce, or ``None`` for the whole Array.
+	statistic
+		The ``Sum`` statistic.
+
+	Returns
+	-------
+	Any
+		A single value, or one value per reduced slice.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.location_statistics import compute_sum
+	>>> compute_sum(numpy.array([1.0, numpy.nan, 2.0]), None, ndp.Sum())
+	np.float64(3.0)
+	"""
+	total = numpy.nansum(values, axis=axis)
+
+	return total
+
+
+def compute_mean(values: NDArray[Any], axis: int | None, statistic: Statistic) -> Any:
+	"""
+	Return the mean of the present values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of a number or boolean Array, at least one present value per slice.
+	axis
+		The numpy axis to reduce, or ``None`` for the whole Array.
+	statistic
+		The ``Mean`` statistic.
+
+	Returns
+	-------
+	Any
+		A single value, or one value per reduced slice.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.location_statistics import compute_mean
+	>>> compute_mean(numpy.array([1.0, numpy.nan, 3.0]), None, ndp.Mean())
+	np.float64(2.0)
+	"""
+	mean = numpy.nanmean(values, axis=axis)
+
+	return mean
+
+
+def compute_median(values: NDArray[Any], axis: int | None, statistic: Statistic) -> Any:
+	"""
+	Return the median of the present values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of a number Array, at least one present value per slice.
+	axis
+		The numpy axis to reduce, or ``None`` for the whole Array.
+	statistic
+		The ``Median`` statistic.
+
+	Returns
+	-------
+	Any
+		A single value, or one value per reduced slice.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.location_statistics import compute_median
+	>>> compute_median(numpy.array([1, 9, 2]), None, ndp.Median())
+	np.float64(2.0)
+	"""
+	median = numpy.nanmedian(values, axis=axis)
+
+	return median
+
+
+def compute_standard_deviation(values: NDArray[Any], axis: int | None, statistic: Statistic) -> Any:
+	"""
+	Return the population standard deviation of the present values, divided by their number.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of a number Array, at least one present value per slice.
+	axis
+		The numpy axis to reduce, or ``None`` for the whole Array.
+	statistic
+		The ``StandardDeviation`` statistic.
+
+	Returns
+	-------
+	Any
+		A single value, or one value per reduced slice.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.location_statistics import compute_standard_deviation
+	>>> compute_standard_deviation(numpy.array([2, 4]), None, ndp.StandardDeviation())
+	np.float64(1.0)
+	"""
+	deviation = numpy.nanstd(values, axis=axis, ddof=POPULATION_DEGREES_OF_FREEDOM)
+
+	return deviation
+
+
+def compute_quantile(values: NDArray[Any], axis: int | None, statistic: Statistic) -> Any:
+	"""
+	Return the value below which a fraction of the present values lies.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of a number Array, at least one present value per slice.
+	axis
+		The numpy axis to reduce, or ``None`` for the whole Array.
+	statistic
+		The ``Quantile`` statistic, holding the fraction.
+
+	Returns
+	-------
+	Any
+		A single value, or one value per reduced slice.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.location_statistics import compute_quantile
+	>>> compute_quantile(numpy.array([0, 10]), None, ndp.Quantile(0.9))
+	np.float64(9.0)
+	"""
+	quantile = cast(Quantile, statistic)
+	quantile_values = numpy.nanquantile(values, quantile.fraction, axis=axis)
+
+	return quantile_values
+
+
+def compute_minimum(values: NDArray[Any], axis: int | None, statistic: Statistic) -> Any:
+	"""
+	Return the lowest present value: the smallest number, the first text in alphabetical order, the earliest date.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array, at least one present value per slice.
+	axis
+		The numpy axis to reduce, or ``None`` for the whole Array.
+	statistic
+		The ``Min`` statistic.
+
+	Returns
+	-------
+	Any
+		A single value, or one value per reduced slice.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.location_statistics import compute_minimum
+	>>> compute_minimum(numpy.array([3.0, numpy.nan, 1.0]), None, ndp.Min())
+	np.float64(1.0)
+	"""
+	if values.dtype.kind in MISSING_AWARE_KINDS:
+		present_minimum = numpy.nanmin(values, axis=axis)
+		return present_minimum
+
+	minimum = numpy.min(values, axis=axis)
+
+	return minimum
+
+
+def compute_maximum(values: NDArray[Any], axis: int | None, statistic: Statistic) -> Any:
+	"""
+	Return the highest present value: the largest number, the last text in alphabetical order, the latest date.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array, at least one present value per slice.
+	axis
+		The numpy axis to reduce, or ``None`` for the whole Array.
+	statistic
+		The ``Max`` statistic.
+
+	Returns
+	-------
+	Any
+		A single value, or one value per reduced slice.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.location_statistics import compute_maximum
+	>>> compute_maximum(numpy.array(["b", "c", "a"], dtype="T"), None, ndp.Max())
+	'c'
+	"""
+	if values.dtype.kind in MISSING_AWARE_KINDS:
+		present_maximum = numpy.nanmax(values, axis=axis)
+		return present_maximum
+
+	if values.dtype.kind == TEXT_KIND:
+		# numpy orders a missing text last. The empty text orders first, so it never wins over a present text.
+		missing = find_missing(values)
+		ordered_texts = numpy.where(missing, LOWEST_TEXT, values)
+		highest_text = numpy.max(ordered_texts, axis=axis)
+		return highest_text
+
+	maximum = numpy.max(values, axis=axis)
+
+	return maximum

numdaplot/arrays/calculation/math_function_values.py

@@ -0,0 +1,183 @@
+"""
+Application of a math function to each value of an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.math_functions.absolute import Absolute
+from numdaplot.arrays.math_functions.cosine import Cosine
+from numdaplot.arrays.math_functions.exponential import Exponential
+from numdaplot.arrays.math_functions.logarithm import Logarithm
+from numdaplot.arrays.math_functions.math_function import MathFunction
+from numdaplot.arrays.math_functions.round import Round
+from numdaplot.arrays.math_functions.sine import Sine
+from numdaplot.arrays.math_functions.square_root import SquareRoot
+from numdaplot.arrays.operations.float_errors import FloatErrorWarnings
+from numdaplot.arrays.operations.integer_rules import require_absolute_fits
+from numdaplot.arrays.operations.type_requirements import require_family
+from numdaplot.data_types.value_family import ValueFamily
+from numdaplot.errors.out_of_domain_error import OutOfDomainError
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+
+NUMBER_FAMILIES = frozenset({ValueFamily.NUMBER})
+DOMAIN_LIMIT = 0
+LOGARITHM_FUNCTIONS = {
+	2.0: numpy.log2,
+	10.0: numpy.log10,
+}
+UNKNOWN_FUNCTION_OPERATION = "The math function {function_name}"
+UNKNOWN_FUNCTION_ALTERNATIVE = "a math function of numdaplot"
+
+
+def apply_math_function(values: NDArray[Any], function: MathFunction) -> NDArray[Any]:
+	"""
+	Return the result of a math function applied to each value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of a number Array.
+	function
+		Any math function of numdaplot.
+
+	Returns
+	-------
+	NDArray
+		The transformed values. Missing values stay missing.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the values are not numbers.
+	OutOfDomainError
+		When a value is outside the domain of the function.
+	RefusedOperationError
+		When the function is not a math function of numdaplot.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.math_function_values import apply_math_function
+	>>> apply_math_function(numpy.array([1, 100]), ndp.Logarithm(base=10))
+	array([0., 2.])
+	"""
+	function_class = type(function)
+	function_name = function_class.__name__
+	require_family(values, NUMBER_FAMILIES, function_name)
+
+	with FloatErrorWarnings(function_name):
+		match function:
+			case SquareRoot():
+				require_domain(values, numpy.less, function_name)
+				transformed_values = numpy.sqrt(values)
+			case Logarithm():
+				require_domain(values, numpy.less_equal, function_name)
+				transformed_values = compute_logarithm(values, function)
+			case Exponential():
+				transformed_values = numpy.exp(values)
+			case Absolute():
+				require_absolute_fits(values, function_name)
+				transformed_values = numpy.absolute(values)
+			case Round():
+				transformed_values = numpy.round(values, function.decimals)
+			case Sine():
+				transformed_values = numpy.sin(values)
+			case Cosine():
+				transformed_values = numpy.cos(values)
+			case _:
+				operation = UNKNOWN_FUNCTION_OPERATION.format(function_name=function_name)
+				raise RefusedOperationError(operation, UNKNOWN_FUNCTION_ALTERNATIVE)
+
+		return transformed_values
+
+
+def require_domain(values: NDArray[Any], is_outside: numpy.ufunc, function_name: str) -> None:
+	"""
+	Check that no value is outside the domain of a math function, by comparison with 0.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of a number Array. Missing values are never outside.
+	is_outside
+		The comparison with 0 telling a value is outside, such as ``numpy.less`` for a square root.
+	function_name
+		Name of the math function, shown in the error message.
+
+	Raises
+	------
+	OutOfDomainError
+		At the first value outside the domain.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.math_function_values import require_domain
+	>>> try:
+	... 	require_domain(numpy.array([4, -9]), numpy.less, "SquareRoot")
+	... except ndp.OutOfDomainError as error:
+	... 	print(error)
+	SquareRoot is not defined for -9.
+	"""
+	outside = is_outside(values, DOMAIN_LIMIT)
+	has_outside_value = outside.any()
+	if has_outside_value:
+		outside_values = values[outside]
+		first_outside_value = outside_values[0]
+		rejected_value = first_outside_value.item()
+		raise OutOfDomainError(function_name, rejected_value)
+
+
+def compute_logarithm(values: NDArray[Any], logarithm: Logarithm) -> NDArray[Any]:
+	"""
+	Return the logarithm of each value, in the base of a ``Logarithm``.
+
+	Bases 2 and 10 use their dedicated numpy functions, which give exact results on exact powers.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values, all greater than 0 or missing.
+	logarithm
+		The base, natural when ``None``.
+
+	Returns
+	-------
+	NDArray
+		The logarithm of each value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.math_function_values import compute_logarithm
+	>>> compute_logarithm(numpy.array([8]), ndp.Logarithm(base=2))
+	array([3.])
+	"""
+	natural_logarithms = numpy.log(values)
+	base = logarithm.base
+	if base is None:
+		return natural_logarithms
+
+	if base in LOGARITHM_FUNCTIONS:
+		dedicated_function = LOGARITHM_FUNCTIONS[base]
+		dedicated_logarithms = dedicated_function(values)
+		return dedicated_logarithms
+
+	base_logarithm = numpy.log(base)
+	logarithms = natural_logarithms / base_logarithm
+
+	return logarithms

numdaplot/arrays/calculation/statistic_values.py

@@ -0,0 +1,209 @@
+"""
+Computation of any statistic on the values of an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.axis_number import find_numpy_axis
+from numdaplot.arrays.calculation.counting_statistics import (
+	compute_count,
+	compute_count_distinct,
+	compute_most_frequent,
+	compute_most_frequent_count,
+)
+from numdaplot.arrays.calculation.location_statistics import (
+	compute_maximum,
+	compute_mean,
+	compute_median,
+	compute_minimum,
+	compute_quantile,
+	compute_standard_deviation,
+	compute_sum,
+)
+from numdaplot.arrays.creation.numpy_conversion import normalize_text
+from numdaplot.arrays.operations.float_errors import FloatErrorWarnings
+from numdaplot.arrays.operations.integer_rules import require_sum_fits
+from numdaplot.arrays.operations.type_requirements import require_family
+from numdaplot.arrays.selection.missing_mask import find_missing
+from numdaplot.data_types.value_family import ValueFamily
+from numdaplot.errors.empty_array_error import EmptyArrayError
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+from numdaplot.positions.axis import Axis
+from numdaplot.statistics.count import Count
+from numdaplot.statistics.count_distinct import CountDistinct
+from numdaplot.statistics.maximum import Max
+from numdaplot.statistics.mean import Mean
+from numdaplot.statistics.median import Median
+from numdaplot.statistics.minimum import Min
+from numdaplot.statistics.most_frequent import MostFrequent
+from numdaplot.statistics.most_frequent_count import MostFrequentCount
+from numdaplot.statistics.quantile import Quantile
+from numdaplot.statistics.standard_deviation import StandardDeviation
+from numdaplot.statistics.statistic import Statistic
+from numdaplot.statistics.sum import Sum
+
+type StatisticFunction = Callable[[NDArray[Any], int | None, Statistic], Any]
+
+
+@dataclass(frozen=True)
+class StatisticCalculation:
+	"""
+	How a statistic is computed on the values of an Array.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	function
+		The function computing the statistic, given the values, the numpy axis and the statistic.
+	accepted_families
+		The families of types the statistic applies to.
+	needs_present_value
+		Whether the statistic needs at least one present value per slice.
+	"""
+
+	function: StatisticFunction
+	accepted_families: frozenset[ValueFamily]
+	needs_present_value: bool
+
+
+ALL_FAMILIES = frozenset(ValueFamily)
+NUMBER_FAMILIES = frozenset({ValueFamily.NUMBER})
+NUMBER_AND_BOOL_FAMILIES = frozenset({ValueFamily.NUMBER, ValueFamily.BOOL})
+STATISTIC_CALCULATIONS = {
+	Sum: StatisticCalculation(compute_sum, NUMBER_AND_BOOL_FAMILIES, needs_present_value=False),
+	Mean: StatisticCalculation(compute_mean, NUMBER_AND_BOOL_FAMILIES, needs_present_value=True),
+	Median: StatisticCalculation(compute_median, NUMBER_FAMILIES, needs_present_value=True),
+	Min: StatisticCalculation(compute_minimum, ALL_FAMILIES, needs_present_value=True),
+	Max: StatisticCalculation(compute_maximum, ALL_FAMILIES, needs_present_value=True),
+	Count: StatisticCalculation(compute_count, ALL_FAMILIES, needs_present_value=False),
+	CountDistinct: StatisticCalculation(compute_count_distinct, ALL_FAMILIES, needs_present_value=False),
+	StandardDeviation: StatisticCalculation(compute_standard_deviation, NUMBER_FAMILIES, needs_present_value=True),
+	Quantile: StatisticCalculation(compute_quantile, NUMBER_FAMILIES, needs_present_value=True),
+	MostFrequent: StatisticCalculation(compute_most_frequent, ALL_FAMILIES, needs_present_value=True),
+	MostFrequentCount: StatisticCalculation(compute_most_frequent_count, ALL_FAMILIES, needs_present_value=False),
+}
+SINGLE_VALUE_DIMENSIONS = (1,)
+UNKNOWN_STATISTIC_OPERATION = "The statistic {statistic_name}"
+UNKNOWN_STATISTIC_ALTERNATIVE = "a statistic of numdaplot"
+
+
+def compute_statistic(values: NDArray[Any], statistic: Statistic, axis: Axis | None) -> NDArray[Any]:
+	"""
+	Return a statistic of the present values, for the whole Array or for each row or column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	statistic
+		Any statistic of numdaplot.
+	axis
+		``EACH_ROW`` for one result per row, ``EACH_COLUMN`` for one per column,
+		``None`` for a single result.
+
+	Returns
+	-------
+	NDArray
+		A single value in one dimension when ``axis`` is ``None``, otherwise one value per row or column.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the statistic does not apply to the type of the values.
+	DimensionError
+		When an axis is given for an Array that is not two-dimensional.
+	EmptyArrayError
+		When the statistic needs a present value and a slice has none.
+	RefusedOperationError
+		When the statistic is not a statistic of numdaplot.
+	IntegerOverflowError
+		When the sum of integers does not fit their type.
+
+	Warns
+	-----
+	CalculationWarning
+		When a result on decimals becomes NaN or an infinite value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.statistic_values import compute_statistic
+	>>> compute_statistic(numpy.array([[1, 2], [3, 4]]), ndp.Sum(), ndp.Axis.EACH_ROW)
+	array([3, 7])
+	"""
+	statistic_class = type(statistic)
+	statistic_name = statistic_class.__name__
+	if statistic_class not in STATISTIC_CALCULATIONS:
+		operation = UNKNOWN_STATISTIC_OPERATION.format(statistic_name=statistic_name)
+		raise RefusedOperationError(operation, UNKNOWN_STATISTIC_ALTERNATIVE)
+
+	calculation = STATISTIC_CALCULATIONS[statistic_class]
+	require_family(values, calculation.accepted_families, statistic_name)
+	numpy_axis = find_numpy_axis(axis, values.ndim)
+	if calculation.needs_present_value:
+		require_present_values(values, numpy_axis, statistic_name)
+
+	with FloatErrorWarnings(statistic_name):
+		result = calculation.function(values, numpy_axis, statistic)
+
+	result_values = numpy.asarray(result)
+	if statistic_class == Sum:
+		require_sum_fits(values, numpy_axis, result_values, statistic_name)
+
+	if numpy_axis is None:
+		result_values = result_values.reshape(SINGLE_VALUE_DIMENSIONS)
+
+	normalized_values = normalize_text(result_values)
+
+	return normalized_values
+
+
+def require_present_values(values: NDArray[Any], axis: int | None, statistic_name: str) -> None:
+	"""
+	Check that the whole Array, or each slice along an axis, holds at least one present value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	axis
+		The numpy axis to reduce, or ``None`` for the whole Array.
+	statistic_name
+		Name of the statistic, shown in the error message.
+
+	Raises
+	------
+	EmptyArrayError
+		When the Array, or one of its slices, has no present value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.statistic_values import require_present_values
+	>>> try:
+	... 	require_present_values(numpy.array([numpy.nan]), None, "Mean")
+	... except ndp.EmptyArrayError as error:
+	... 	print(error)
+	Cannot compute Mean without any present value.
+	"""
+	missing = find_missing(values)
+	present = ~missing
+	present_counts = numpy.sum(present, axis=axis)
+	empty_slices = present_counts == 0
+	has_empty_slice = numpy.any(empty_slices)
+	if has_empty_slice:
+		raise EmptyArrayError(statistic_name)