numdaplot 0.1.0__py3-none-any.whl

numdaplot/arrays/layout/unique_values.py

@@ -0,0 +1,49 @@
+"""
+Distinct values of an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.selection.missing_mask import find_missing
+
+SINGLE_MISSING_VALUE = slice(0, 1)
+
+
+def find_unique_values(values: NDArray[Any]) -> NDArray[Any]:
+	"""
+	Return each distinct value once, sorted, with a single missing value at the end when there is one.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array, of any number of dimensions.
+
+	Returns
+	-------
+	NDArray
+		The distinct values, in one dimension.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.layout.unique_values import find_unique_values
+	>>> find_unique_values(numpy.array([[3.0, numpy.nan], [1.0, 3.0]]))
+	array([ 1.,  3., nan])
+	"""
+	missing = find_missing(values)
+	present = ~missing
+	present_values = values[present]
+	missing_values = values[missing]
+	distinct_values = numpy.unique(present_values)
+	single_missing_values = missing_values[SINGLE_MISSING_VALUE]
+	parts = [distinct_values, single_missing_values]
+	unique_values = numpy.concatenate(parts)
+
+	return unique_values

numdaplot/arrays/mapping/__init__.py

@@ -0,0 +1,5 @@
+"""
+Replacement of the values of an Array by other values.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/arrays/mapping/mapped_values.py

@@ -0,0 +1,286 @@
+"""
+Application of a ValueMapping to the values of an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from collections.abc import Sequence
+from datetime import date, datetime, time
+from typing import Any, cast
+
+from numpy.typing import NDArray
+
+from numdaplot.arrays.conversion.python_values import to_python_list
+from numdaplot.arrays.creation.list_conversion import convert_list
+from numdaplot.arrays.mapping.unmatched import Unmatched
+from numdaplot.arrays.mapping.value_mapping import MAPPING_OPERATION, ValueMapping, find_new_type
+from numdaplot.arrays.operations.type_requirements import require_comparable
+from numdaplot.arrays.selection.missing_mask import find_missing
+from numdaplot.data_types.numpy_mapping import from_numpy_dtype
+from numdaplot.data_types.type import Type
+from numdaplot.errors.unmatched_value_error import UnmatchedValueError
+from numdaplot.errors.unsupported_missing_error import UnsupportedMissingError
+from numdaplot.rules.rule_values import ScalarValue
+
+DECIMAL_ADVICE = "Give decimal new values, such as 10.0, which can be missing."
+BOOLEAN_ADVICE = "Give texts as new values, which can be missing."
+MIDNIGHT = time()
+INTEGER_TYPES = frozenset(
+	{Type.INT8, Type.INT16, Type.INT32, Type.INT64, Type.UINT8, Type.UINT16, Type.UINT32, Type.UINT64}
+)
+
+
+def map_values(values: NDArray[Any], mapping: ValueMapping) -> NDArray[Any]:
+	"""
+	Return the values of an Array replaced by the new values of a mapping, in the same shape.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	mapping
+		The new value of each listed value, and what happens to the others.
+
+	Returns
+	-------
+	NDArray
+		The new values, stored with the type the new values share. Missing values stay missing.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the old values are not of the type family of the Array.
+	UnmatchedValueError
+		When a value has no new value and ``others`` is ``Unmatched.ERROR``.
+	UnsupportedMissingError
+		When the result holds integers or booleans and a missing value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.mapping.mapped_values import map_values
+	>>> mapping = ndp.ValueMapping(changes=[ndp.ValueChange(1, "Homme"), ndp.ValueChange(2, "Femme")])
+	>>> map_values(numpy.array([[1, 2], [2, 1]]), mapping).tolist()
+	[['Homme', 'Femme'], ['Femme', 'Homme']]
+	"""
+	for change in mapping.changes:
+		require_comparable(values, change.old_value, MAPPING_OPERATION)
+
+	flat_values = values.ravel()
+	new_values = find_flat_new_values(flat_values, mapping)
+	new_type = find_new_type(mapping.changes)
+	require_missing_supported(new_values, new_type)
+	stored_values = convert_list(new_values, new_type)
+	shaped_values = stored_values.reshape(values.shape)
+
+	return shaped_values
+
+
+def find_flat_new_values(flat_values: NDArray[Any], mapping: ValueMapping) -> list[object]:
+	"""
+	Return the new value of each value of a flat Array, None for a missing one.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	flat_values
+		The values of an Array in one dimension.
+	mapping
+		The new value of each listed value, and what happens to the others.
+
+	Returns
+	-------
+	list[object]
+		The new Python values, in order.
+
+	Raises
+	------
+	UnmatchedValueError
+		At the first value without new value, when ``others`` is ``Unmatched.ERROR``.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.mapping.mapped_values import find_flat_new_values
+	>>> mapping = ndp.ValueMapping(changes=[ndp.ValueChange(1.0, "one")], others=ndp.Unmatched.MISSING)
+	>>> find_flat_new_values(numpy.array([1.0, numpy.nan, 2.0]), mapping)
+	['one', None, None]
+	"""
+	array_type = from_numpy_dtype(flat_values.dtype)
+	new_value_by_old = dict[ScalarValue, ScalarValue | None]()
+	for change in mapping.changes:
+		lookup_value = find_lookup_value(change.old_value, array_type)
+		new_value_by_old[lookup_value] = change.new_value
+
+	missing = find_missing(flat_values)
+	raw_missing = missing.tolist()
+	is_missing_list = cast(list[bool], raw_missing)
+	python_values = to_python_list(flat_values)
+	new_values = list[object]()
+	for value, is_missing in zip(python_values, is_missing_list, strict=True):
+		if is_missing:
+			new_values.append(None)
+			continue
+
+		if value in new_value_by_old:
+			new_value = new_value_by_old[value]
+			new_values.append(new_value)
+			continue
+
+		if mapping.others == Unmatched.ERROR:
+			raise UnmatchedValueError(value)
+
+		new_values.append(None)
+
+	return new_values
+
+
+def require_missing_supported(new_values: Sequence[object], new_type: Type | None) -> None:
+	"""
+	Check that a result of integers or booleans holds no missing value, with advice fitting a mapping.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	new_values
+		The new Python values, None for a missing one.
+	new_type
+		The type the new values share, or None.
+
+	Raises
+	------
+	UnsupportedMissingError
+		When the type is an integer or boolean type and a new value is None.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.mapping.mapped_values import require_missing_supported
+	>>> try:
+	... 	require_missing_supported([10, None], ndp.Type.INT64)
+	... except ndp.UnsupportedMissingError as error:
+	... 	print(error)
+	INT64 values cannot be missing in an Array. Give decimal new values, such as 10.0, which can be missing.
+	"""
+	has_missing = None in new_values
+	if not has_missing:
+		return
+
+	if new_type in INTEGER_TYPES:
+		raise UnsupportedMissingError(new_type.name, advice=DECIMAL_ADVICE)
+
+	if new_type == Type.BOOL:
+		raise UnsupportedMissingError(new_type.name, advice=BOOLEAN_ADVICE)
+
+
+def find_lookup_value(old_value: ScalarValue, array_type: Type) -> ScalarValue:
+	"""
+	Return an old value written as the values of the Array are, so that a date finds a datetime at midnight.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	old_value
+		An old value of a ``ValueChange``.
+	array_type
+		The type of the values of the Array.
+
+	Returns
+	-------
+	ScalarValue
+		A date as a datetime at midnight for ``DATETIME`` values, a datetime at midnight as a date for ``DATE``
+		values, any other value unchanged.
+
+	Examples
+	--------
+	>>> from datetime import date
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.mapping.mapped_values import find_lookup_value
+	>>> find_lookup_value(date(2026, 12, 25), ndp.Type.DATETIME)
+	datetime.datetime(2026, 12, 25, 0, 0)
+	"""
+	if array_type == Type.DATETIME:
+		datetime_value = write_date_as_datetime(old_value)
+		return datetime_value
+
+	if array_type == Type.DATE:
+		date_value = write_midnight_as_date(old_value)
+		return date_value
+
+	return old_value
+
+
+def write_date_as_datetime(old_value: ScalarValue) -> ScalarValue:
+	"""
+	Return a date as the datetime at midnight of that day, any other value unchanged.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	old_value
+		An old value of a ``ValueChange``.
+
+	Returns
+	-------
+	ScalarValue
+		The datetime at midnight, or the value itself.
+
+	Examples
+	--------
+	>>> from datetime import date
+	>>> from numdaplot.arrays.mapping.mapped_values import write_date_as_datetime
+	>>> write_date_as_datetime(date(2026, 12, 25)), write_date_as_datetime(3)
+	(datetime.datetime(2026, 12, 25, 0, 0), 3)
+	"""
+	if isinstance(old_value, datetime):
+		return old_value
+
+	if not isinstance(old_value, date):
+		return old_value
+
+	midnight = datetime.combine(old_value, MIDNIGHT)
+
+	return midnight
+
+
+def write_midnight_as_date(old_value: ScalarValue) -> ScalarValue:
+	"""
+	Return a datetime at midnight as its date, any other value unchanged.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	old_value
+		An old value of a ``ValueChange``.
+
+	Returns
+	-------
+	ScalarValue
+		The date of a datetime at midnight, or the value itself, so that a datetime with a time finds no date.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> from numdaplot.arrays.mapping.mapped_values import write_midnight_as_date
+	>>> write_midnight_as_date(datetime(2026, 12, 25)), write_midnight_as_date(datetime(2026, 12, 25, 10))
+	(datetime.date(2026, 12, 25), datetime.datetime(2026, 12, 25, 10, 0))
+	"""
+	if not isinstance(old_value, datetime):
+		return old_value
+
+	old_time = old_value.time()
+	if old_time != MIDNIGHT:
+		return old_value
+
+	old_date = old_value.date()
+
+	return old_date

numdaplot/arrays/mapping/unmatched.py

@@ -0,0 +1,50 @@
+"""
+What happens to a value that no setting gives a new value.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class Unmatched(Enum):
+	"""
+	What happens to a value of an Array that a ``ValueMapping`` gives no new value.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> sexes = ndp.Array.from_list([1, 2, 9])
+	>>> changes = [ndp.ValueChange(1, "Homme"), ndp.ValueChange(2, "Femme")]
+	>>> sexes.apply(ndp.ValueMapping(changes=changes, others=ndp.Unmatched.MISSING))
+	Array(['Homme', 'Femme', nan], dtype=TEXT)
+	"""
+
+	ERROR = auto()
+	"""
+	The value raises ``UnmatchedValueError``. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> sexes = ndp.Array.from_list([1, 9])
+	>>> try:
+	... 	sexes.apply(ndp.ValueMapping(changes=[ndp.ValueChange(1, "Homme")], others=ndp.Unmatched.ERROR))
+	... except ndp.UnmatchedValueError as error:
+	... 	print(error)
+	The value 9 has no ValueChange. Add one, or give others=Unmatched.MISSING to make it missing.
+	"""
+
+	MISSING = auto()
+	"""
+	The value becomes missing.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> sexes = ndp.Array.from_list([1, 9])
+	>>> sexes.apply(ndp.ValueMapping(changes=[ndp.ValueChange(1, "Homme")], others=ndp.Unmatched.MISSING))
+	Array(['Homme', nan], dtype=TEXT)
+	"""

numdaplot/arrays/mapping/value_change.py

@@ -0,0 +1,55 @@
+"""
+One old value and the new value replacing it.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.rules.rule_values import ScalarValue
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class ValueChange:
+	"""
+	One old value of an Array and the new value replacing it, used by ``ValueMapping``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	old_value
+		The value replaced, of the type family of the Array: ``2.0`` finds the integer ``2``.
+	new_value
+		The value replacing it, or None to make it missing.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names, such as None as old value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> severities = ndp.Array.from_list([1, 2, -1])
+	>>> changes = [ndp.ValueChange(1, "Indemne"), ndp.ValueChange(2, "Tue"), ndp.ValueChange(-1, None)]
+	>>> severities.apply(ndp.ValueMapping(changes=changes))
+	Array(['Indemne', 'Tue', nan], dtype=TEXT)
+	"""
+
+	old_value: ScalarValue
+	new_value: ScalarValue | None
+
+	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/mapping/value_mapping.py

@@ -0,0 +1,161 @@
+"""
+Replacement of each value of an Array by a new value.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.arrays.mapping.unmatched import Unmatched
+from numdaplot.arrays.mapping.value_change import ValueChange
+from numdaplot.data_types.type import Type
+from numdaplot.data_types.value_type import find_common_type, find_value_type
+from numdaplot.errors.duplicate_value_error import DuplicateValueError
+from numdaplot.errors.empty_list_error import EmptyListError
+from numdaplot.rules.rule_values import ScalarValue
+from numdaplot.settings.field_types import require_field_types
+
+CHANGE_ITEM_NAME = "value change"
+MAPPING_OPERATION = "ValueMapping"
+
+
+@dataclass(frozen=True)
+class ValueMapping:
+	"""
+	The new value of each listed value of an Array, used by ``Array.apply``, such as codes replaced by labels.
+
+	A missing value stays missing. The new values share one type, which the result takes: integers and decimals
+	give decimals.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	changes
+		The ``ValueChange`` of each replaced value, at least one, each old value once. The mapping keeps its own copy
+		of the list.
+	others
+		What happens to a value without ``ValueChange``, ``Unmatched.ERROR`` by default.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	EmptyListError
+		When ``changes`` is an empty list.
+	IncompatibleTypesError
+		When the old values, or the new values, mix several families of types, such as numbers and texts.
+	DuplicateValueError
+		When an old value appears twice.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> sexes = ndp.Array.from_list([2, 1, 2])
+	>>> sexes.apply(ndp.ValueMapping(changes=[ndp.ValueChange(1, "Homme"), ndp.ValueChange(2, "Femme")]))
+	Array(['Femme', 'Homme', 'Femme'], dtype=TEXT)
+	"""
+
+	changes: list[ValueChange]
+	others: Unmatched = Unmatched.ERROR
+
+	def __post_init__(self) -> None:
+		"""
+		Check the changes: at least one, old and new values each of one type family, no old value twice.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		EmptyListError
+			When ``changes`` is an empty list.
+		IncompatibleTypesError
+			When the old values, or the new values, mix several families of types.
+		DuplicateValueError
+			When an old value appears twice.
+		"""
+		require_field_types(self)
+
+		if self.changes == []:
+			raise EmptyListError(CHANGE_ITEM_NAME)
+
+		old_values = [change.old_value for change in self.changes]
+		old_types = [find_value_type(old_value) for old_value in old_values]
+		find_common_type(old_types, MAPPING_OPERATION)
+		require_unique_values(old_values)
+		find_new_type(self.changes)
+		changes_copy = list(self.changes)
+		object.__setattr__(self, "changes", changes_copy)
+
+
+def require_unique_values(values: list[ScalarValue]) -> None:
+	"""
+	Check that no value appears twice, ``2`` and ``2.0`` being the same value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		Values of one family of types.
+
+	Raises
+	------
+	DuplicateValueError
+		At the first value seen before.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.mapping.value_mapping import require_unique_values
+	>>> try:
+	... 	require_unique_values([1, 2, 2.0])
+	... except ndp.DuplicateValueError as error:
+	... 	print(error)
+	The value 2.0 appears more than once.
+	"""
+	seen_values = set[ScalarValue]()
+	for value in values:
+		if value in seen_values:
+			raise DuplicateValueError(value)
+
+		seen_values.add(value)
+
+
+def find_new_type(changes: list[ValueChange]) -> Type | None:
+	"""
+	Return the type shared by the new values of a mapping.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	changes
+		The changes of a mapping.
+
+	Returns
+	-------
+	Type or None
+		The common type of the new values that are not None, or None when every new value is None.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the new values mix several families of types.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.mapping.value_mapping import find_new_type
+	>>> find_new_type([ndp.ValueChange(1, 10), ndp.ValueChange(2, 2.5), ndp.ValueChange(-1, None)])
+	<Type.FLOAT64: 10>
+	"""
+	new_types = [find_value_type(change.new_value) for change in changes if change.new_value is not None]
+	if new_types == []:
+		return None
+
+	new_type = find_common_type(new_types, MAPPING_OPERATION)
+
+	return new_type

numdaplot/arrays/math_functions/__init__.py

@@ -0,0 +1,5 @@
+"""
+Math functions applied to each value of an Array.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/arrays/math_functions/absolute.py

@@ -0,0 +1,27 @@
+"""
+Absolute value math function.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.arrays.math_functions.math_function import MathFunction
+
+
+@dataclass(frozen=True)
+class Absolute(MathFunction):
+	"""
+	Absolute value of each value, its distance to 0: -3 and 3 both give 3.
+
+	Missing values stay missing.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> gaps = ndp.Array.from_list([-3, 0, 2])
+	>>> gaps.apply(ndp.Absolute())
+	Array([3, 0, 2], dtype=INT64)
+	"""

numdaplot/arrays/math_functions/cosine.py

@@ -0,0 +1,28 @@
+"""
+Cosine math function.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.arrays.math_functions.math_function import MathFunction
+
+
+@dataclass(frozen=True)
+class Cosine(MathFunction):
+	"""
+	Cosine of each value, read as an angle in radians.
+
+	Missing values stay missing.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> import math
+	>>> angles = ndp.Array.from_list([0.0, math.pi])
+	>>> angles.apply(ndp.Cosine())
+	Array([ 1., -1.], dtype=FLOAT64)
+	"""

numdaplot/arrays/math_functions/exponential.py

@@ -0,0 +1,27 @@
+"""
+Exponential math function.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.arrays.math_functions.math_function import MathFunction
+
+
+@dataclass(frozen=True)
+class Exponential(MathFunction):
+	"""
+	Exponential of each value, ``e`` raised to the value: 0 gives 1, 1 gives about 2.718.
+
+	Missing values stay missing.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> rates = ndp.Array.from_list([0.0, 1.0])
+	>>> rates.apply(ndp.Exponential())
+	Array([1.        , 2.71828183], dtype=FLOAT64)
+	"""