numdaplot 0.1.0__py3-none-any.whl

numdaplot/arrays/selection/replaced_values.py

@@ -0,0 +1,120 @@
+"""
+Replacement of the values of a region of an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any, cast
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.operations.operand import Operand, find_operand_type
+from numdaplot.arrays.operations.time_bounds import NANOSECOND_TYPES, require_nanoseconds_fit
+from numdaplot.arrays.selection.region_index import build_region_index
+from numdaplot.data_types.numpy_mapping import from_numpy_dtype, to_numpy_dtype
+from numdaplot.errors.shape_mismatch_error import ShapeMismatchError
+from numdaplot.errors.value_conversion_error import ValueConversionError
+from numdaplot.positions.region import Region
+
+SAFE_CASTING = "same_kind"
+REPLACE_OPERATION = "replace"
+
+
+def replace_region(values: NDArray[Any], region: Region, new_values: Operand) -> NDArray[Any]:
+	"""
+	Return a copy of the values whose region is replaced.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	region
+		The positions to replace.
+	new_values
+		A single value written at every position, or Array values of exactly the shape of the region.
+
+	Returns
+	-------
+	NDArray
+		The new values, of the same shape and type.
+
+	Raises
+	------
+	ShapeMismatchError
+		When Array values do not have the shape of the region.
+	ValueConversionError
+		When the new values cannot be stored in the type of the values without losing information.
+	DimensionError, RefusedOperationError, InvalidPositionError
+		When the region does not fit the values, as in ``build_region_index``.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.selection.replaced_values import replace_region
+	>>> replace_region(numpy.array([1, 2, 3]), ndp.Region(rows=ndp.Index(0)), 9)
+	array([9, 2, 3])
+	"""
+	region_index = build_region_index(region, values.shape)
+	region_values = values[region_index]
+	if isinstance(new_values, numpy.ndarray):
+		if new_values.shape != region_values.shape:
+			raise ShapeMismatchError(new_values.shape, region_values.shape)
+
+	require_storable(new_values, values)
+	replaced_values = values.copy()
+	# numpy reads dates and durations from Python objects, which its type hints do not list.
+	storable_values = cast(Any, new_values)
+	try:
+		replaced_values[region_index] = storable_values
+	except OverflowError as error:
+		new_type = find_operand_type(new_values)
+		values_type = from_numpy_dtype(values.dtype)
+		raise ValueConversionError(new_type.name, values_type.name) from error
+
+	return replaced_values
+
+
+def require_storable(new_values: Operand, values: NDArray[Any]) -> None:
+	"""
+	Check that new values can be stored in the type of existing values without losing information.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	new_values
+		A single value, or Array values.
+	values
+		The values receiving them.
+
+	Raises
+	------
+	ValueConversionError
+		When a decimal would become an integer, or a text a number, for example.
+	TimeOverflowError
+		When a value stored as ``DATETIME`` or ``DURATION`` is outside the range of nanoseconds.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.selection.replaced_values import require_storable
+	>>> try:
+	... 	require_storable(0.5, numpy.array([1, 2]))
+	... except ndp.ValueConversionError as error:
+	... 	print(error)
+	Cannot store FLOAT64 values as INT64 without losing information.
+	"""
+	new_type = find_operand_type(new_values)
+	values_type = from_numpy_dtype(values.dtype)
+	new_dtype = to_numpy_dtype(new_type)
+	is_safe = numpy.can_cast(new_dtype, values.dtype, casting=SAFE_CASTING)
+	if not is_safe:
+		raise ValueConversionError(new_type.name, values_type.name)
+
+	if values_type in NANOSECOND_TYPES:
+		require_nanoseconds_fit(new_values, values_type, REPLACE_OPERATION)

numdaplot/arrays/selection/rule_mask.py

@@ -0,0 +1,83 @@
+"""
+Mask of any rule applied to the values of an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any, cast
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.selection.comparison_masks import build_between_mask, build_comparison_mask
+from numdaplot.arrays.selection.membership_masks import build_contains_mask, build_membership_mask
+from numdaplot.arrays.selection.missing_mask import find_missing
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+from numdaplot.rules.between import Between
+from numdaplot.rules.contains import Contains
+from numdaplot.rules.is_in import IsIn
+from numdaplot.rules.is_missing import IsMissing
+from numdaplot.rules.is_present import IsPresent
+from numdaplot.rules.rule import Rule
+from numdaplot.rules.value_rule import ValueRule
+
+UNKNOWN_RULE_OPERATION = "The rule {rule_name}"
+UNKNOWN_RULE_ALTERNATIVE = "a rule of numdaplot"
+
+
+def build_rule_mask(values: NDArray[Any], rule: Rule) -> NDArray[numpy.bool_]:
+	"""
+	Return which values satisfy a rule.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	rule
+		Any rule of numdaplot.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		True at each value satisfying the rule. A missing value only satisfies ``IsMissing``.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the rule does not apply to the type of the values.
+	RefusedOperationError
+		When the rule is not a rule of numdaplot.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.selection.rule_mask import build_rule_mask
+	>>> build_rule_mask(numpy.array([1.0, numpy.nan]), ndp.IsPresent())
+	array([ True, False])
+	"""
+	match rule:
+		case IsMissing():
+			mask = find_missing(values)
+		case IsPresent():
+			missing = find_missing(values)
+			mask = ~missing
+		case Contains():
+			mask = build_contains_mask(values, rule)
+		case IsIn():
+			membership_rule = cast(IsIn[Any], rule)
+			mask = build_membership_mask(values, membership_rule)
+		case Between():
+			interval_rule = cast(Between[Any], rule)
+			mask = build_between_mask(values, interval_rule)
+		case ValueRule():
+			comparison_rule = cast(ValueRule[Any], rule)
+			mask = build_comparison_mask(values, comparison_rule)
+		case _:
+			rule_class = type(rule)
+			operation = UNKNOWN_RULE_OPERATION.format(rule_name=rule_class.__name__)
+			raise RefusedOperationError(operation, UNKNOWN_RULE_ALTERNATIVE)
+
+	return mask

numdaplot/arrays/selection/time_reference.py

@@ -0,0 +1,172 @@
+"""
+Comparison of nanosecond values with a date, a datetime or a duration that nanoseconds cannot hold.
+
+Such a reference lies beyond every stored value, so the answer is known without converting it, which numpy
+either refuses or does wrongly.
+
+.. versionadded:: 0.1.0
+"""
+
+from datetime import timedelta
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.operations.operand import LONGEST_MICROSECOND_DURATION, convert_time_value
+from numdaplot.arrays.operations.time_bounds import NANOSECOND_DTYPES, is_python_time_in_range
+
+MICROSECOND_DURATION_DTYPE = numpy.dtype("timedelta64[us]")
+AFTER_EVERY_VALUE = 1
+BEFORE_EVERY_VALUE = -1
+ANY_STORED_VALUE = 0
+NO_DURATION = timedelta(0)
+FIRST_YEAR_AFTER_ZERO = 1970
+
+
+def is_far_reference(values: NDArray[Any], reference: object) -> bool:
+	"""
+	Return whether a reference value lies beyond everything nanosecond values can hold.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	reference
+		A single Python value.
+
+	Returns
+	-------
+	bool
+		True for a date, a datetime or a duration out of range, beside values stored in nanoseconds, and for a duration
+		that microseconds cannot count, beside durations stored in microseconds.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numpy
+	>>> from numdaplot.arrays.selection.time_reference import is_far_reference
+	>>> moments = numpy.array(["2026-01-31"], dtype="datetime64[ns]")
+	>>> is_far_reference(moments, datetime(3000, 1, 1)), is_far_reference(moments, datetime(2026, 1, 1))
+	(True, False)
+	"""
+	if values.dtype == MICROSECOND_DURATION_DTYPE and isinstance(reference, timedelta):
+		is_too_long = abs(reference) > LONGEST_MICROSECOND_DURATION
+		return is_too_long
+
+	if values.dtype not in NANOSECOND_DTYPES:
+		return False
+
+	in_range = is_python_time_in_range(reference)
+
+	return not in_range
+
+
+def find_far_side(reference: Any) -> int:
+	"""
+	Return on which side of every stored value a reference out of range lies.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	reference
+		A date, a datetime or a duration out of range.
+
+	Returns
+	-------
+	int
+		1 after every value, -1 before every value.
+
+	Examples
+	--------
+	>>> from datetime import date, timedelta
+	>>> from numdaplot.arrays.selection.time_reference import find_far_side
+	>>> find_far_side(date(3000, 1, 1)), find_far_side(date(1000, 1, 1)), find_far_side(timedelta(days=-200000))
+	(1, -1, -1)
+	"""
+	if isinstance(reference, timedelta):
+		is_after = reference > NO_DURATION
+	else:
+		is_after = reference.year >= FIRST_YEAR_AFTER_ZERO
+
+	if is_after:
+		return AFTER_EVERY_VALUE
+
+	return BEFORE_EVERY_VALUE
+
+
+def compare_with_reference(values: NDArray[Any], reference: Any, compare: numpy.ufunc) -> NDArray[numpy.bool_]:
+	"""
+	Return the comparison of each value with a reference value, which may be out of range.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	reference
+		A single Python value.
+	compare
+		The numpy comparison, such as ``numpy.less``, with the values on its left.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		The result for each value, a missing value not being set apart.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numpy
+	>>> from numdaplot.arrays.selection.time_reference import compare_with_reference
+	>>> moments = numpy.array(["2026-01-31"], dtype="datetime64[ns]")
+	>>> compare_with_reference(moments, datetime(3000, 1, 1), numpy.less)
+	array([ True])
+	"""
+	is_far = is_far_reference(values, reference)
+	if is_far:
+		far_side = find_far_side(reference)
+		same_answer = compare(ANY_STORED_VALUE, far_side)
+		far_matches = numpy.full(values.shape, same_answer, dtype=numpy.bool_)
+		return far_matches
+
+	numpy_reference = convert_time_value(reference)
+	matches = compare(values, numpy_reference)
+
+	return matches
+
+
+def remove_far_references(values: NDArray[Any], references: list[Any]) -> list[Any]:
+	"""
+	Return the reference values that may equal a stored value, those out of range never doing so.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	references
+		Single Python values.
+
+	Returns
+	-------
+	list[Any]
+		The values kept, in their order.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numpy
+	>>> from numdaplot.arrays.selection.time_reference import remove_far_references
+	>>> moments = numpy.array(["2026-01-31"], dtype="datetime64[ns]")
+	>>> remove_far_references(moments, [datetime(2026, 1, 31), datetime(3000, 1, 1)])
+	[datetime.datetime(2026, 1, 31, 0, 0)]
+	"""
+	near_references = [reference for reference in references if not is_far_reference(values, reference)]
+
+	return near_references

numdaplot/arrays/shape.py

@@ -0,0 +1,74 @@
+"""
+Number of values along each dimension of an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.invalid_shape_error import InvalidShapeError
+from numdaplot.settings.field_types import require_field_types
+
+LOWEST_DIMENSION = 0
+
+
+@dataclass(frozen=True)
+class Shape:
+	"""
+	Number of values along each dimension of an Array.
+
+	``Shape([3, 4])`` describes 3 rows of 4 values, and ``Shape([5])`` a single row of 5 values.
+	It is used by ``Array.filled``, ``Array.random`` and ``reshape``, and returned by ``Array.shape``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	dimensions
+		Number of values along each dimension, a list of at least one dimension and none lower than 0.
+		The shape keeps its own copy of the list.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidShapeError
+		When ``dimensions`` is empty or holds a negative number.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.filled(shape=ndp.Shape([2, 3]), value=0)
+	Array([[0, 0, 0],
+	       [0, 0, 0]], dtype=INT64)
+	>>> ndp.Array.from_list([[1, 2, 3], [4, 5, 6]]).shape
+	Shape(dimensions=[2, 3])
+	"""
+
+	dimensions: list[int]
+
+	def __post_init__(self) -> None:
+		"""
+		Check the dimensions and replace them with a copy that only the shape holds.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidShapeError
+			When ``dimensions`` is empty or holds a negative number.
+		"""
+		require_field_types(self)
+
+		dimension_count = len(self.dimensions)
+		if dimension_count == 0:
+			raise InvalidShapeError(self.dimensions)
+
+		for dimension in self.dimensions:
+			if dimension < LOWEST_DIMENSION:
+				raise InvalidShapeError(self.dimensions)
+
+		dimensions_copy = list(self.dimensions)
+		object.__setattr__(self, "dimensions", dimensions_copy)

numdaplot/arrays/type_match.py

@@ -0,0 +1,51 @@
+"""
+Whether a comparison of two Arrays also compares their types.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class TypeMatch(Enum):
+	"""
+	Whether a comparison of two Arrays also compares their types, used by ``Equality``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> integers = ndp.Array.from_list([1, 2])
+	>>> decimals = ndp.Array.from_list([1.0, 2.0])
+	>>> integers.is_equal(ndp.Equality(other=decimals, types=ndp.TypeMatch.IGNORED))
+	True
+	>>> integers.is_equal(ndp.Equality(other=decimals, types=ndp.TypeMatch.STRICT))
+	False
+	"""
+
+	STRICT = auto()
+	"""
+	The types must be the same: ``[1, 2]`` as ``INT64`` differs from ``[1.0, 2.0]`` as ``FLOAT64``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> integers = ndp.Array.from_list([1, 2])
+	>>> decimals = ndp.Array.from_list([1.0, 2.0])
+	>>> integers.is_equal(ndp.Equality(other=decimals, types=ndp.TypeMatch.STRICT))
+	False
+	"""
+
+	IGNORED = auto()
+	"""
+	Only the values are compared: ``[1, 2]`` equals ``[1.0, 2.0]``. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> integers = ndp.Array.from_list([1, 2])
+	>>> decimals = ndp.Array.from_list([1.0, 2.0])
+	>>> integers.is_equal(ndp.Equality(other=decimals, types=ndp.TypeMatch.IGNORED))
+	True
+	"""

numdaplot/data_types/__init__.py

@@ -0,0 +1,5 @@
+"""
+The ``ndp.Type`` enum and its conversion to and from numpy and pandas types.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/data_types/library.py

@@ -0,0 +1,57 @@
+"""
+Libraries that numdaplot types are converted to and from.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum
+
+
+class Library(Enum):
+	"""
+	Underlying library on the other side of a type conversion, read on ``UnsupportedTypeError.library``.
+
+	The value of each member is the name of the library, as shown in error messages.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> import numpy
+	>>> try:
+	... 	ndp.Array.from_numpy(numpy.array([1 + 2j]))
+	... except ndp.UnsupportedTypeError as error:
+	... 	print(error.library.value)
+	numpy
+	"""
+
+	NUMPY = "numpy"
+	"""
+	numpy, used by Array.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> import numpy
+	>>> try:
+	... 	ndp.Array.from_numpy(numpy.array([1 + 2j]))
+	... except ndp.UnsupportedTypeError as error:
+	... 	print(error.library == ndp.Library.NUMPY)
+	True
+	"""
+
+	PANDAS = "pandas"
+	"""
+	pandas, used by Table.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> import pandas
+	>>> try:
+	... 	ndp.Table.from_pandas(pandas.DataFrame({"impedance": [1 + 2j]}))
+	... except ndp.UnsupportedTypeError as error:
+	... 	print(error.library == ndp.Library.PANDAS)
+	True
+	"""