numdaplot 0.1.0__py3-none-any.whl

numdaplot/arrays/operations/transformation.py

@@ -0,0 +1,54 @@
+"""
+Transformation of each value of an Array with a numpy function of one operand.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.operations.operand import find_operand_type_names
+from numdaplot.errors.incompatible_types_error import IncompatibleTypesError
+
+
+def transform_values(values: NDArray[Any], function: numpy.ufunc, name: str) -> NDArray[Any]:
+	"""
+	Return the result of a numpy function applied to each value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	function
+		The numpy function, such as ``numpy.negative``.
+	name
+		The operator or function name shown in error messages, such as ``"-"``.
+
+	Returns
+	-------
+	NDArray
+		The transformed values.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the function does not apply to the type of the values.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.operations.transformation import transform_values
+	>>> transform_values(numpy.array([1, -2]), numpy.negative, "-")
+	array([-1,  2])
+	"""
+	try:
+		transformed_values = function(values)
+	except TypeError as error:
+		type_names = find_operand_type_names([values])
+		raise IncompatibleTypesError(name, type_names) from error
+
+	return transformed_values

numdaplot/arrays/operations/type_requirements.py

@@ -0,0 +1,94 @@
+"""
+Checks that the values of an Array have a type an operation applies to.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+from numpy.typing import NDArray
+
+from numdaplot.data_types.numpy_mapping import from_numpy_dtype
+from numdaplot.data_types.value_family import ValueFamily, find_family
+from numdaplot.data_types.value_type import find_value_type
+from numdaplot.errors.incompatible_types_error import IncompatibleTypesError
+from numdaplot.rules.rule_values import ScalarValue
+
+
+def require_family(values: NDArray[Any], accepted_families: frozenset[ValueFamily], operation: str) -> None:
+	"""
+	Check that the values of an Array belong to one of the families an operation applies to.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	accepted_families
+		The families the operation applies to.
+	operation
+		Name of the operation, shown in the error message.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the type of the values belongs to another family.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.operations.type_requirements import require_family
+	>>> from numdaplot.data_types.value_family import ValueFamily
+	>>> try:
+	... 	require_family(numpy.array(["a"]), frozenset({ValueFamily.NUMBER}), "Mean")
+	... except ndp.IncompatibleTypesError as error:
+	... 	print(error)
+	Cannot apply Mean to TEXT.
+	"""
+	array_type = from_numpy_dtype(values.dtype)
+	array_family = find_family(array_type)
+	if array_family not in accepted_families:
+		raise IncompatibleTypesError(operation, [array_type.name])
+
+
+def require_comparable(values: NDArray[Any], reference: ScalarValue, operation: str) -> None:
+	"""
+	Check that the values of an Array can be compared with a reference value.
+
+	Numbers compare with numbers, texts with texts, dates and datetimes with each other.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	reference
+		The value they are compared with.
+	operation
+		Name of the operation, shown in the error message.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the reference value belongs to another family than the values.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.operations.type_requirements import require_comparable
+	>>> try:
+	... 	require_comparable(numpy.array([1, 2]), "10", "Greater")
+	... except ndp.IncompatibleTypesError as error:
+	... 	print(error)
+	Cannot apply Greater to INT64 and TEXT.
+	"""
+	array_type = from_numpy_dtype(values.dtype)
+	reference_type = find_value_type(reference)
+	array_family = find_family(array_type)
+	reference_family = find_family(reference_type)
+	if array_family != reference_family:
+		raise IncompatibleTypesError(operation, [array_type.name, reference_type.name])

numdaplot/arrays/replacement.py

@@ -0,0 +1,66 @@
+"""
+Settings of the replacement of a region of an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from numdaplot.positions.region import Region
+from numdaplot.rules.rule_values import ScalarValue
+from numdaplot.settings.field_types import require_field_types
+
+if TYPE_CHECKING:
+	from numdaplot.arrays.array import Array
+
+
+# eq=False because comparing two settings would compare their Arrays with ==, which Array refuses.
+@dataclass(frozen=True, eq=False)
+class Replacement:
+	"""
+	Settings of the replacement of a region of an Array, used by ``Array.replace``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	region
+		The positions to replace.
+	value
+		A ``ScalarValue``, such as ``0`` or ``"Paris"``, written at every position of the region, or an Array of
+		exactly the shape of the region. Its type must fit in the type of the Array: a decimal cannot replace
+		an integer.
+
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> scores = ndp.Array.from_list([10, 20, 30])
+	>>> first_score = ndp.Region(rows=ndp.Index(0))
+	>>> scores.replace(ndp.Replacement(region=first_score, value=0))
+	Array([ 0, 20, 30], dtype=INT64)
+	"""
+
+	region: Region
+	value: ScalarValue | Array
+
+	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/selection/__init__.py

@@ -0,0 +1,5 @@
+"""
+Selection of Array values by rule and by position.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/arrays/selection/comparison_masks.py

@@ -0,0 +1,131 @@
+"""
+Masks of the rules comparing each value with reference values.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.operations.type_requirements import require_comparable
+from numdaplot.arrays.selection.missing_mask import find_missing
+from numdaplot.arrays.selection.time_reference import compare_with_reference
+from numdaplot.rules.between import Between
+from numdaplot.rules.bounds import HIGH_INCLUDED_BOUNDS, LOW_INCLUDED_BOUNDS
+from numdaplot.rules.equal import Equal
+from numdaplot.rules.greater import Greater
+from numdaplot.rules.greater_or_equal import GreaterOrEqual
+from numdaplot.rules.less import Less
+from numdaplot.rules.less_or_equal import LessOrEqual
+from numdaplot.rules.not_equal import NotEqual
+from numdaplot.rules.value_rule import ValueRule
+
+COMPARISON_FUNCTIONS = dict[type[ValueRule[Any]], numpy.ufunc](
+	{
+		Equal: numpy.equal,
+		NotEqual: numpy.not_equal,
+		Greater: numpy.greater,
+		GreaterOrEqual: numpy.greater_equal,
+		Less: numpy.less,
+		LessOrEqual: numpy.less_equal,
+	}
+)
+BETWEEN_NAME = "Between"
+
+
+def build_comparison_mask(values: NDArray[Any], rule: ValueRule[Any]) -> NDArray[numpy.bool_]:
+	"""
+	Return which values satisfy a rule comparing them with a single reference value.
+
+	A missing value never satisfies the rule, not even ``NotEqual``. A date, a datetime or a duration that nanoseconds
+	cannot hold lies beyond every datetime or duration: ``Less`` accepts them all for a reference in the year 3000.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	rule
+		``Equal``, ``NotEqual``, ``Greater``, ``GreaterOrEqual``, ``Less`` or ``LessOrEqual``.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		True at each value satisfying the rule.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the reference value cannot be compared with the values.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.selection.comparison_masks import build_comparison_mask
+	>>> build_comparison_mask(numpy.array([1, 5, 9]), ndp.Greater(4))
+	array([False,  True,  True])
+	"""
+	rule_class = type(rule)
+	require_comparable(values, rule.value, rule_class.__name__)
+
+	compare = COMPARISON_FUNCTIONS[rule_class]
+	matches = compare_with_reference(values, rule.value, compare)
+	missing = find_missing(values)
+	present = ~missing
+	mask = matches & present
+
+	return mask
+
+
+def build_between_mask(values: NDArray[Any], rule: Between[Any]) -> NDArray[numpy.bool_]:
+	"""
+	Return which values lie inside the interval of a ``Between`` rule.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	rule
+		The interval and the bounds it includes.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		True at each value inside the interval. A missing value is never inside.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the bounds cannot be compared with the values.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.selection.comparison_masks import build_between_mask
+	>>> build_between_mask(numpy.array([1, 5, 9]), ndp.Between(low=1, high=5, bounds=ndp.Bounds.HIGH_ONLY))
+	array([False,  True, False])
+	"""
+	require_comparable(values, rule.low, BETWEEN_NAME)
+
+	compare_with_low = numpy.greater
+	if rule.bounds in LOW_INCLUDED_BOUNDS:
+		compare_with_low = numpy.greater_equal
+
+	compare_with_high = numpy.less
+	if rule.bounds in HIGH_INCLUDED_BOUNDS:
+		compare_with_high = numpy.less_equal
+
+	above_low = compare_with_reference(values, rule.low, compare_with_low)
+	below_high = compare_with_reference(values, rule.high, compare_with_high)
+	missing = find_missing(values)
+	present = ~missing
+	mask = above_low & below_high & present
+
+	return mask

numdaplot/arrays/selection/membership_masks.py

@@ -0,0 +1,118 @@
+"""
+Masks of the rules looking for values in a list or for a text inside each value.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.operations.operand import convert_time_value
+from numdaplot.arrays.operations.type_requirements import require_comparable, require_family
+from numdaplot.arrays.selection.missing_mask import find_missing
+from numdaplot.arrays.selection.time_reference import remove_far_references
+from numdaplot.data_types.value_family import ValueFamily
+from numdaplot.rules.case import Case
+from numdaplot.rules.contains import Contains
+from numdaplot.rules.is_in import IsIn
+
+IS_IN_NAME = "IsIn"
+CONTAINS_NAME = "Contains"
+TEXT_FAMILIES = frozenset({ValueFamily.TEXT})
+EMPTY_TEXT = ""
+NOT_FOUND_POSITION = -1
+
+
+def build_membership_mask(values: NDArray[Any], rule: IsIn[Any]) -> NDArray[numpy.bool_]:
+	"""
+	Return which values belong to the accepted values of an ``IsIn`` rule.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	rule
+		The accepted values.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		True at each accepted value. A missing value is never accepted.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the accepted values cannot be compared with the values.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.selection.membership_masks import build_membership_mask
+	>>> build_membership_mask(numpy.array([1, 2, 3]), ndp.IsIn([1, 3]))
+	array([ True, False,  True])
+	"""
+	first_accepted_value = rule.values[0]
+	require_comparable(values, first_accepted_value, IS_IN_NAME)
+
+	near_values = remove_far_references(values, rule.values)
+	accepted_values = [convert_time_value(accepted_value) for accepted_value in near_values]
+	matches = numpy.isin(values, accepted_values)
+	missing = find_missing(values)
+	present = ~missing
+	mask = matches & present
+
+	return mask
+
+
+def build_contains_mask(values: NDArray[Any], rule: Contains) -> NDArray[numpy.bool_]:
+	"""
+	Return which texts contain the text of a ``Contains`` rule.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of a ``TEXT`` Array.
+	rule
+		The searched text and whether case is ignored.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		True at each text containing the searched text.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the values are not texts.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.selection.membership_masks import build_contains_mask
+	>>> build_contains_mask(numpy.array(["Paris", "Lyon"]), ndp.Contains("paris", case=ndp.Case.IGNORED))
+	array([ True, False])
+	"""
+	require_family(values, TEXT_FAMILIES, CONTAINS_NAME)
+
+	missing = find_missing(values)
+	present = ~missing
+	# numpy cannot search a missing text. The mask of the present texts removes the empty text standing for it.
+	searched_values = numpy.where(missing, EMPTY_TEXT, values)
+	searched_text = rule.text
+	if rule.case == Case.IGNORED:
+		searched_values = numpy.strings.lower(searched_values)
+		searched_text = rule.text.lower()
+
+	positions = numpy.strings.find(searched_values, searched_text)
+	found = positions != NOT_FOUND_POSITION
+	mask = found & present
+
+	return mask

numdaplot/arrays/selection/missing_mask.py

@@ -0,0 +1,50 @@
+"""
+Positions of the missing values of an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+NAN_KINDS = frozenset({"f", "T"})
+TIME_KINDS = frozenset({"M", "m"})
+
+
+def find_missing(values: NDArray[Any]) -> NDArray[numpy.bool_]:
+	"""
+	Return which values are missing: NaN for decimals and texts, NaT for dates, datetimes and durations.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		True at each missing value. Always false for types that cannot be missing.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.selection.missing_mask import find_missing
+	>>> find_missing(numpy.array([1.0, numpy.nan]))
+	array([False,  True])
+	"""
+	value_kind = values.dtype.kind
+	if value_kind in NAN_KINDS:
+		missing_values = numpy.isnan(values)
+		return missing_values
+
+	if value_kind in TIME_KINDS:
+		missing_times = numpy.isnat(values)
+		return missing_times
+
+	no_missing_value = numpy.zeros(values.shape, dtype=numpy.bool_)
+
+	return no_missing_value

numdaplot/arrays/selection/region_index.py

@@ -0,0 +1,178 @@
+"""
+Numpy index of the positions of a Region inside an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.creation.range_values import compute_range_values
+from numdaplot.errors.dimension_error import DimensionError
+from numdaplot.errors.invalid_position_error import InvalidPositionError
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+from numdaplot.positions.index import Index
+from numdaplot.positions.range import Range
+from numdaplot.positions.region import Region
+
+ONE_DIMENSION = 1
+TWO_DIMENSIONS = 2
+WHOLE_NUMBER_KINDS = frozenset({"i", "u"})
+REGION_OPERATION = "A Region"
+COLUMNS_OPERATION = "A Region with columns"
+COLUMN_NAMES_OPERATION = "Column names in a Region for an Array"
+COLUMN_NAMES_ALTERNATIVE = "Index or Range positions"
+
+
+def build_region_index(region: Region, dimensions: tuple[int, ...]) -> tuple[NDArray[Any], ...]:
+	"""
+	Return the numpy index selecting the positions of a Region.
+
+	Rows and columns given as an ``Index`` keep their dimension, so the selection of one row
+	of a two-dimensional Array is still two-dimensional.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	region
+		The rows and the columns to select.
+	dimensions
+		The dimensions of the Array.
+
+	Returns
+	-------
+	tuple[NDArray, ...]
+		One array of positions per dimension, usable inside numpy brackets.
+
+	Raises
+	------
+	DimensionError
+		When the Array has more than two dimensions, or when 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
+	>>> from numdaplot.arrays.selection.region_index import build_region_index
+	>>> build_region_index(ndp.Region(rows=ndp.Index(-1)), (3,))
+	(array([-1]),)
+	"""
+	dimension_count = len(dimensions)
+	if dimension_count > TWO_DIMENSIONS:
+		raise DimensionError(REGION_OPERATION, dimension_count)
+
+	if isinstance(region.columns, list):
+		raise RefusedOperationError(COLUMN_NAMES_OPERATION, COLUMN_NAMES_ALTERNATIVE)
+
+	row_count = dimensions[0]
+	row_positions = find_positions(region.rows, row_count)
+	if dimension_count == ONE_DIMENSION:
+		if region.columns is not None:
+			raise DimensionError(COLUMNS_OPERATION, dimension_count)
+
+		return (row_positions,)
+
+	column_count = dimensions[1]
+	column_positions = find_positions(region.columns, column_count)
+	region_index = numpy.ix_(row_positions, column_positions)
+
+	return region_index
+
+
+def find_positions(selector: Index | Range | None, size: int) -> NDArray[Any]:
+	"""
+	Return the positions chosen in one dimension.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	selector
+		One position, a sequence of positions, or ``None`` for every position.
+	size
+		The size of the dimension.
+
+	Returns
+	-------
+	NDArray
+		The chosen positions, negative ones counting from the end.
+
+	Raises
+	------
+	InvalidPositionError
+		When a position is not a whole number inside the dimension.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.selection.region_index import find_positions
+	>>> find_positions(ndp.Range(start=0, stop=4, step=2), 5)
+	array([0, 2, 4])
+	"""
+	match selector:
+		case None:
+			positions = numpy.arange(size)
+		case Index():
+			positions = numpy.array([selector.position])
+		case Range():
+			positions = compute_range_values(selector)
+
+	require_valid_positions(positions, size)
+
+	return positions
+
+
+def require_valid_positions(positions: NDArray[Any], size: int) -> None:
+	"""
+	Check that positions are whole numbers inside a dimension.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	positions
+		The positions to check.
+	size
+		The size of the dimension, which accepts the positions from ``-size`` to ``size - 1``.
+
+	Raises
+	------
+	InvalidPositionError
+		At the first position that is not a whole number or falls outside the dimension.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.selection.region_index import require_valid_positions
+	>>> try:
+	... 	require_valid_positions(numpy.array([0, 3]), 3)
+	... except ndp.InvalidPositionError as error:
+	... 	print(error)
+	Expected a whole position between -3 and 2, got 3.
+	"""
+	if positions.size == 0:
+		return
+
+	if positions.dtype.kind not in WHOLE_NUMBER_KINDS:
+		first_position = positions[0]
+		rejected_position = first_position.item()
+		raise InvalidPositionError(rejected_position, size)
+
+	lowest_position = -size
+	below_lowest = positions < lowest_position
+	above_highest = positions >= size
+	outside = below_lowest | above_highest
+	has_outside_position = outside.any()
+	if has_outside_position:
+		outside_positions = positions[outside]
+		first_outside_position = outside_positions[0]
+		rejected_position = first_outside_position.item()
+		raise InvalidPositionError(rejected_position, size)