numdaplot 0.1.0__py3-none-any.whl

numdaplot/arrays/array_selection.py

@@ -0,0 +1,195 @@
+"""
+Selection of the values of an Array, by rule and by position.
+
+.. versionadded:: 0.1.0
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Self
+
+from numdaplot.arrays.array_data import ArrayData
+from numdaplot.arrays.selection.region_index import build_region_index
+from numdaplot.arrays.selection.replaced_values import replace_region
+from numdaplot.arrays.selection.rule_mask import build_rule_mask
+from numdaplot.positions.region import Region
+from numdaplot.rules.rule import Rule
+from numdaplot.settings.argument_types import checked_arguments
+
+if TYPE_CHECKING:
+	from numdaplot.arrays.replacement import Replacement
+
+
+class ArraySelection(ArrayData):
+	"""
+	Selection of the values of an Array.
+
+	By rule with ``select`` and ``check``, by position with ``take`` and ``replace``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def select(self, rule: Rule) -> Self:
+		"""
+		Return the values satisfying a rule, in one dimension.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		rule
+			A ``Rule``, such as ``ndp.Greater(10)`` or ``ndp.IsIn(["Paris"])``: see ``Rule`` for every rule.
+			A missing value only satisfies ``IsMissing``.
+
+		Returns
+		-------
+		Self
+			A new one-dimensional Array, in reading order.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When the rule does not apply to the type of the values.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([[5, 12], [30, 8]])
+		>>> prices.select(ndp.Greater(10))
+		Array([12, 30], dtype=INT64)
+		"""
+		mask = build_rule_mask(self._values, rule)
+		selected_values = self._values[mask]
+		selected_array = self._wrap(selected_values)
+
+		return selected_array
+
+	@checked_arguments
+	def check(self, rule: Rule) -> Self:
+		"""
+		Return whether each value satisfies a rule, keeping the shape.
+
+		Combine several checks with ``&``, ``|`` and ``~``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		rule
+			A ``Rule``, such as ``ndp.Greater(10)`` or ``ndp.IsIn(["Paris"])``: see ``Rule`` for every rule.
+			A missing value only satisfies ``IsMissing``.
+
+		Returns
+		-------
+		Self
+			A new ``BOOL`` Array of the same shape.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When the rule does not apply to the type of the values.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau"])
+		>>> cities.check(ndp.Contains("Pa"))
+		Array([ True, False,  True], dtype=BOOL)
+		"""
+		mask = build_rule_mask(self._values, rule)
+		mask_array = self._wrap(mask)
+
+		return mask_array
+
+	@checked_arguments
+	def take(self, region: Region) -> Self:
+		"""
+		Return the values of a region of a one- or two-dimensional Array.
+
+		A row or a column chosen with ``Index`` keeps its dimension: one row of a two-dimensional
+		Array is still two-dimensional. Use ``to_value`` to read a single value.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		region
+			The rows and the columns to take, every one of a dimension when omitted.
+			Negative positions count from the end.
+
+		Returns
+		-------
+		Self
+			A new Array with as many dimensions as this one.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		DimensionError
+			When the Array has more than two dimensions, or columns are given for a one-dimensional Array.
+		RefusedOperationError
+			When columns are given as names, which only a Table has.
+		InvalidPositionError
+			When a position is not a whole number inside its dimension.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> grid = ndp.Array.from_list([[1, 2, 3], [4, 5, 6]])
+		>>> grid.take(ndp.Region(rows=ndp.Index(-1), columns=ndp.Range(start=0, stop=1)))
+		Array([[4, 5]], dtype=INT64)
+		"""
+		region_index = build_region_index(region, self._values.shape)
+		region_values = self._values[region_index]
+		region_array = self._wrap(region_values)
+
+		return region_array
+
+	@checked_arguments
+	def replace(self, replacement: Replacement) -> Self:
+		"""
+		Return a new Array whose region is replaced; this Array does not change.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		replacement
+			The region, and a single value or an Array of exactly the shape of the region.
+
+		Returns
+		-------
+		Self
+			A new Array of the same shape and type.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ShapeMismatchError
+			When an Array of new values does not have the shape of the region.
+		ValueConversionError
+			When the new values cannot be stored in the type of the Array without losing information.
+		TimeOverflowError
+			When a datetime is outside 1677 to 2262, or a duration beyond about 292 years.
+		DimensionError, RefusedOperationError, InvalidPositionError
+			When the region does not fit the Array, as in ``take``.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> scores = ndp.Array.from_list([10, 20, 30])
+		>>> scores.replace(ndp.Replacement(region=ndp.Region(rows=ndp.Index(1)), value=0))
+		Array([10,  0, 30], dtype=INT64)
+		"""
+		new_values = self._read_operand(replacement.value)
+		replaced_values = replace_region(self._values, replacement.region, new_values)
+		replaced_array = self._wrap(replaced_values)
+
+		return replaced_array

numdaplot/arrays/array_sorting.py

@@ -0,0 +1,59 @@
+"""
+Settings of the sort of an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.ordering.missing_position import MissingPosition
+from numdaplot.ordering.order import Order
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class ArraySorting:
+	"""
+	Settings of the sort of an Array, used by ``Array.sort``.
+
+	The axis, inside each row or each column, is given to ``Array.sort`` itself.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	order
+		Ascending by default.
+	missing
+		Place of the missing values, last by default whatever the order.
+
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> grid = ndp.Array.from_list([[3, 1], [2, 4]])
+	>>> grid.sort(ndp.ArraySorting(order=ndp.Order.DESCENDING), axis=ndp.Axis.EACH_COLUMN)
+	Array([[3, 4],
+	       [2, 1]], dtype=INT64)
+	"""
+
+	order: Order = Order.ASCENDING
+	missing: MissingPosition = MissingPosition.LAST
+
+	def __post_init__(self) -> None:
+		"""
+		Check the type of every setting.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		"""
+		require_field_types(self)

numdaplot/arrays/axis_number.py

@@ -0,0 +1,58 @@
+"""
+Conversion of an ``ndp.Axis`` to a numpy axis number.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.dimension_error import DimensionError
+from numdaplot.positions.axis import Axis
+
+AXIS_DIMENSION_COUNT = 2
+AXIS_OPERATION = "An axis"
+NUMPY_AXES = {
+	Axis.EACH_ROW: 1,
+	Axis.EACH_COLUMN: 0,
+}
+
+
+def find_numpy_axis(axis: Axis | None, dimension_count: int) -> int | None:
+	"""
+	Return the numpy axis number an operation runs along.
+
+	``EACH_ROW`` handles every row on its own, so the numpy operation runs along the columns, axis 1.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axis
+		The numdaplot axis, or ``None`` when omitted.
+	dimension_count
+		The number of dimensions of the Array.
+
+	Returns
+	-------
+	int or None
+		1 for ``EACH_ROW``, 0 for ``EACH_COLUMN``, ``None`` when the axis is omitted.
+
+	Raises
+	------
+	DimensionError
+		When an axis is given for an Array that is not two-dimensional.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.axis_number import find_numpy_axis
+	>>> find_numpy_axis(ndp.Axis.EACH_COLUMN, 2)
+	0
+	"""
+	if axis is None:
+		return None
+
+	if dimension_count != AXIS_DIMENSION_COUNT:
+		raise DimensionError(AXIS_OPERATION, dimension_count)
+
+	numpy_axis = NUMPY_AXES[axis]
+
+	return numpy_axis

numdaplot/arrays/calculation/__init__.py

@@ -0,0 +1,5 @@
+"""
+Statistics and math functions computed on Array values.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/arrays/calculation/counting_statistics.py

@@ -0,0 +1,325 @@
+"""
+Statistics counting the values of an Array: count, distinct count, most frequent value and its count.
+
+Each function ignores missing values, unless ``Count`` is set to include them, and reduces the whole Array when
+``axis`` is ``None``.
+
+.. versionadded:: 0.1.0
+"""
+
+from collections.abc import Callable
+from typing import Any, cast
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.selection.missing_mask import find_missing
+from numdaplot.statistics.count import Count
+from numdaplot.statistics.counted_missing import CountedMissing
+from numdaplot.statistics.statistic import Statistic
+
+LAST_AXIS = -1
+NO_VALUE_COUNT = 0
+
+
+def compute_count(values: NDArray[Any], axis: int | None, statistic: Statistic) -> Any:
+	"""
+	Return the number of present values, or of every value when the statistic includes the missing ones.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	axis
+		The numpy axis to reduce, or ``None`` for the whole Array.
+	statistic
+		The ``Count`` statistic, holding whether missing values are counted.
+
+	Returns
+	-------
+	Any
+		A single count, or one count per reduced slice.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.counting_statistics import compute_count
+	>>> compute_count(numpy.array([1.0, numpy.nan]), None, ndp.Count())
+	np.int64(1)
+	>>> compute_count(numpy.array([1.0, numpy.nan]), None, ndp.Count(missing=ndp.CountedMissing.INCLUDED))
+	np.int64(2)
+	"""
+	count = cast(Count, statistic)
+	counted = numpy.ones(values.shape, dtype=numpy.bool_)
+	if count.missing == CountedMissing.EXCLUDED:
+		missing = find_missing(values)
+		counted = ~missing
+
+	counted_values = numpy.sum(counted, axis=axis)
+
+	return counted_values
+
+
+def compute_count_distinct(values: NDArray[Any], axis: int | None, statistic: Statistic) -> Any:
+	"""
+	Return the number of distinct present values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	axis
+		The numpy axis to reduce, or ``None`` for the whole Array.
+	statistic
+		The ``CountDistinct`` statistic.
+
+	Returns
+	-------
+	Any
+		A single count, or one count per reduced slice.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.counting_statistics import compute_count_distinct
+	>>> compute_count_distinct(numpy.array([1, 1, 2]), None, ndp.CountDistinct())
+	2
+	"""
+	distinct_counts = apply_to_each_slice(values, axis, count_distinct_values)
+
+	return distinct_counts
+
+
+def compute_most_frequent(values: NDArray[Any], axis: int | None, statistic: Statistic) -> Any:
+	"""
+	Return the present value appearing the most often, the lowest one in case of a tie.
+
+	.. 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 ``MostFrequent`` statistic.
+
+	Returns
+	-------
+	Any
+		A single value, or one value per reduced slice.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.counting_statistics import compute_most_frequent
+	>>> compute_most_frequent(numpy.array([3, 1, 3]), None, ndp.MostFrequent())
+	np.int64(3)
+	"""
+	most_frequent_values = apply_to_each_slice(values, axis, find_most_frequent_value)
+
+	return most_frequent_values
+
+
+def compute_most_frequent_count(values: NDArray[Any], axis: int | None, statistic: Statistic) -> Any:
+	"""
+	Return the number of times the most frequent present value appears.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	axis
+		The numpy axis to reduce, or ``None`` for the whole Array.
+	statistic
+		The ``MostFrequentCount`` statistic.
+
+	Returns
+	-------
+	Any
+		A single count, or one count per reduced slice. 0 when there is no present value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.calculation.counting_statistics import compute_most_frequent_count
+	>>> compute_most_frequent_count(numpy.array([3, 1, 3]), None, ndp.MostFrequentCount())
+	np.int64(2)
+	"""
+	most_frequent_counts = apply_to_each_slice(values, axis, count_most_frequent_value)
+
+	return most_frequent_counts
+
+
+def apply_to_each_slice(values: NDArray[Any], axis: int | None, slice_function: Callable[[NDArray[Any]], Any]) -> Any:
+	"""
+	Return the result of a function applied to the whole Array, or to each slice along an axis.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	axis
+		The numpy axis to reduce, or ``None`` for the whole Array.
+	slice_function
+		The function reducing one-dimensional values to a single result.
+
+	Returns
+	-------
+	Any
+		A single result, or an array of one result per slice.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.calculation.counting_statistics import apply_to_each_slice
+	>>> apply_to_each_slice(numpy.array([[1, 2], [3, 4]]), 0, numpy.max)
+	array([3, 4])
+	"""
+	if axis is None:
+		flat_values = values.reshape(LAST_AXIS)
+		single_result = slice_function(flat_values)
+		return single_result
+
+	slices = numpy.moveaxis(values, axis, LAST_AXIS)
+	slice_results = [slice_function(values_slice) for values_slice in slices]
+	results = numpy.array(slice_results)
+
+	return results
+
+
+def find_present_values(values: NDArray[Any]) -> NDArray[Any]:
+	"""
+	Return the present values, in a single dimension.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+
+	Returns
+	-------
+	NDArray
+		Every value that is not missing.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.calculation.counting_statistics import find_present_values
+	>>> find_present_values(numpy.array([1.0, numpy.nan]))
+	array([1.])
+	"""
+	missing = find_missing(values)
+	present = ~missing
+	present_values = values[present]
+
+	return present_values
+
+
+def count_distinct_values(values: NDArray[Any]) -> int:
+	"""
+	Return the number of distinct present values of one-dimensional values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		One-dimensional values.
+
+	Returns
+	-------
+	int
+		The number of distinct present values.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.calculation.counting_statistics import count_distinct_values
+	>>> count_distinct_values(numpy.array(["a", "b", "a"]))
+	2
+	"""
+	present_values = find_present_values(values)
+	distinct_values = numpy.unique(present_values)
+	distinct_count = distinct_values.size
+
+	return distinct_count
+
+
+def find_most_frequent_value(values: NDArray[Any]) -> Any:
+	"""
+	Return the present value appearing the most often, the lowest one in case of a tie.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		One-dimensional values, at least one of them present.
+
+	Returns
+	-------
+	Any
+		The most frequent value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.calculation.counting_statistics import find_most_frequent_value
+	>>> find_most_frequent_value(numpy.array([2, 1, 2, 1]))
+	np.int64(1)
+	"""
+	present_values = find_present_values(values)
+	distinct_values, counts = numpy.unique(present_values, return_counts=True)
+	most_frequent_position = numpy.argmax(counts)
+	most_frequent_value = distinct_values[most_frequent_position]
+
+	return most_frequent_value
+
+
+def count_most_frequent_value(values: NDArray[Any]) -> Any:
+	"""
+	Return the number of times the most frequent present value appears.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		One-dimensional values.
+
+	Returns
+	-------
+	Any
+		The highest count, 0 when there is no present value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.calculation.counting_statistics import count_most_frequent_value
+	>>> count_most_frequent_value(numpy.array([2, 1, 2]))
+	np.int64(2)
+	"""
+	present_values = find_present_values(values)
+	if present_values.size == 0:
+		return NO_VALUE_COUNT
+
+	_, counts = numpy.unique(present_values, return_counts=True)
+	highest_count = numpy.max(counts)
+
+	return highest_count