numdaplot 0.1.0__py3-none-any.whl

numdaplot/arrays/array_arithmetic.py

@@ -0,0 +1,404 @@
+"""
+Arithmetic operators of an Array, with the Array on the left.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Self
+
+import numpy
+
+from numdaplot.arrays.array_data import ArrayData
+from numdaplot.arrays.operations.integer_rules import require_opposite_fits
+from numdaplot.arrays.operations.transformation import transform_values
+from numdaplot.rules.rule_values import ScalarValue
+from numdaplot.settings.argument_types import checked_arguments
+
+ADDITION_SYMBOL = "+"
+SUBTRACTION_SYMBOL = "-"
+MULTIPLICATION_SYMBOL = "*"
+DIVISION_SYMBOL = "/"
+FLOOR_DIVISION_SYMBOL = "//"
+REMAINDER_SYMBOL = "%"
+POWER_SYMBOL = "**"
+
+
+class ArrayArithmetic(ArrayData):
+	"""
+	Arithmetic operators of an Array, with the Array on the left.
+
+	``+``, ``-``, ``*``, ``/``, ``//``, ``%``, ``**`` and the opposite ``-array``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def __add__(self, other: Self | ScalarValue) -> Self:
+		"""
+		Return the sum of each value and another operand, written ``array + other``.
+
+		Two Arrays are combined value by value. Two Arrays of different shapes are stretched to match,
+		as in numpy, with a ``BroadcastWarning``. The result follows the numpy type rules.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			An Array or a ``ScalarValue``, such as ``10`` or ``2.5``.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ShapeMismatchError
+			When the shapes of two Arrays cannot be combined.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+		IntegerOverflowError
+			When a result does not fit its integer type, which refuses to wrap around to a wrong number.
+		TimeOverflowError
+			When a date or a datetime leaves 1677 to 2262, a duration exceeds about 292 years, or a time of day moves
+			past midnight.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> prices + 5
+		Array([15, 25], dtype=INT64)
+		"""
+		combined_array = self._combine(other, numpy.add, ADDITION_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __sub__(self, other: Self | ScalarValue) -> Self:
+		"""
+		Return the difference of each value and another operand, written ``array - other``.
+
+		Two Arrays are combined value by value. Two Arrays of different shapes are stretched to match,
+		as in numpy, with a ``BroadcastWarning``. The result follows the numpy type rules.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			An Array or a ``ScalarValue``, such as ``10`` or ``2.5``.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ShapeMismatchError
+			When the shapes of two Arrays cannot be combined.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+		IntegerOverflowError
+			When a result does not fit its integer type, which refuses to wrap around to a wrong number.
+		TimeOverflowError
+			When a date or a datetime leaves 1677 to 2262, a duration exceeds about 292 years, or a time of day moves
+			past midnight.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> prices - 5
+		Array([ 5, 15], dtype=INT64)
+		"""
+		combined_array = self._combine(other, numpy.subtract, SUBTRACTION_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __mul__(self, other: Self | ScalarValue) -> Self:
+		"""
+		Return the product of each value and another operand, written ``array * other``.
+
+		Two Arrays are combined value by value. Two Arrays of different shapes are stretched to match,
+		as in numpy, with a ``BroadcastWarning``. The result follows the numpy type rules.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			An Array or a ``ScalarValue``, such as ``10`` or ``2.5``.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ShapeMismatchError
+			When the shapes of two Arrays cannot be combined.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+		IntegerOverflowError
+			When a result does not fit its integer type, which refuses to wrap around to a wrong number.
+		TimeOverflowError
+			When a date or a datetime leaves 1677 to 2262, or a duration exceeds about 292 years.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> prices * 2
+		Array([20, 40], dtype=INT64)
+		"""
+		combined_array = self._combine(other, numpy.multiply, MULTIPLICATION_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __truediv__(self, other: Self | ScalarValue) -> Self:
+		"""
+		Return the quotient of each value and another operand, written ``array / other``.
+
+		Two Arrays are combined value by value. Two Arrays of different shapes are stretched to match,
+		as in numpy, with a ``BroadcastWarning``. The result follows the numpy type rules.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			An Array or a ``ScalarValue``, such as ``10`` or ``2.5``.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ShapeMismatchError
+			When the shapes of two Arrays cannot be combined.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+		TimeOverflowError
+			When a date or a datetime leaves 1677 to 2262, or a duration exceeds about 292 years.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> prices / 4
+		Array([2.5, 5. ], dtype=FLOAT64)
+		"""
+		combined_array = self._combine(other, numpy.true_divide, DIVISION_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __floordiv__(self, other: Self | ScalarValue) -> Self:
+		"""
+		Return the whole quotient of each value and another operand, written ``array // other``.
+
+		Two Arrays are combined value by value. Two Arrays of different shapes are stretched to match,
+		as in numpy, with a ``BroadcastWarning``. The result follows the numpy type rules.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			An Array or a ``ScalarValue``, such as ``10`` or ``2.5``.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ShapeMismatchError
+			When the shapes of two Arrays cannot be combined.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+		OutOfDomainError
+			When integers are divided by 0: convert them to ``FLOAT64`` first.
+		IntegerOverflowError
+			When a result does not fit its integer type, which refuses to wrap around to a wrong number.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> prices // 3
+		Array([3, 6], dtype=INT64)
+		"""
+		combined_array = self._combine(other, numpy.floor_divide, FLOOR_DIVISION_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __mod__(self, other: Self | ScalarValue) -> Self:
+		"""
+		Return the remainder of each value and another operand, written ``array % other``.
+
+		Two Arrays are combined value by value. Two Arrays of different shapes are stretched to match,
+		as in numpy, with a ``BroadcastWarning``. The result follows the numpy type rules.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			An Array or a ``ScalarValue``, such as ``10`` or ``2.5``.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ShapeMismatchError
+			When the shapes of two Arrays cannot be combined.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+		OutOfDomainError
+			When integers are divided by 0: convert them to ``FLOAT64`` first.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> prices % 3
+		Array([1, 2], dtype=INT64)
+		"""
+		combined_array = self._combine(other, numpy.remainder, REMAINDER_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __pow__(self, other: Self | ScalarValue) -> Self:
+		"""
+		Return the power of each value and another operand, written ``array ** other``.
+
+		Two Arrays are combined value by value. Two Arrays of different shapes are stretched to match,
+		as in numpy, with a ``BroadcastWarning``. The result follows the numpy type rules.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			An Array or a ``ScalarValue``, such as ``10`` or ``2.5``.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ShapeMismatchError
+			When the shapes of two Arrays cannot be combined.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+		OutOfDomainError
+			When integers are raised to a negative power: convert them to ``FLOAT64`` first.
+		IntegerOverflowError
+			When a result does not fit its integer type, which refuses to wrap around to a wrong number.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> prices ** 2
+		Array([100, 400], dtype=INT64)
+		"""
+		combined_array = self._combine(other, numpy.power, POWER_SYMBOL)
+
+		return combined_array
+
+	def __neg__(self) -> Self:
+		"""
+		Return the opposite of each value, written ``-array``.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Raises
+		------
+		IncompatibleTypesError
+			When the values have no opposite, such as texts or booleans.
+		IntegerOverflowError
+			When an integer has no opposite in its type, such as any positive ``UINT8``.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> -ndp.Array.from_list([1, -2])
+		Array([-1,  2], dtype=INT64)
+		"""
+		require_opposite_fits(self._values, SUBTRACTION_SYMBOL)
+		negated_values = transform_values(self._values, numpy.negative, SUBTRACTION_SYMBOL)
+		negated_array = self._wrap(negated_values)
+
+		return negated_array

numdaplot/arrays/array_calculation.py

@@ -0,0 +1,143 @@
+"""
+Statistics, math functions and time functions computed on an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Self
+
+from numdaplot.arrays.array_data import ArrayData
+from numdaplot.arrays.calculation.math_function_values import apply_math_function
+from numdaplot.arrays.calculation.statistic_values import compute_statistic
+from numdaplot.arrays.calculation.time_function_values import apply_time_function
+from numdaplot.arrays.mapping.mapped_values import map_values
+from numdaplot.arrays.mapping.value_mapping import ValueMapping
+from numdaplot.arrays.math_functions.math_function import MathFunction
+from numdaplot.dates.time_function import TimeFunction
+from numdaplot.positions.axis import Axis
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.statistics.statistic import Statistic
+
+
+class ArrayCalculation(ArrayData):
+	"""
+	Statistics with ``compute``, math and time functions with ``apply``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def compute(self, statistic: Statistic, axis: Axis | None = None) -> Self:
+		"""
+		Return a statistic of the values, ignoring missing values unless ``Count`` is set to include them.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		statistic
+			A ``Statistic``, such as ``ndp.Mean()`` or ``ndp.Quantile(0.9)``: see ``Statistic`` for every statistic.
+		axis
+			``EACH_ROW`` for one result per row, ``EACH_COLUMN`` for one per column, only for a
+			two-dimensional Array. A single result for the whole Array when omitted.
+
+		Returns
+		-------
+		Self
+			A new Array: one value when ``axis`` is omitted, read it with ``to_value``.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When the statistic does not apply to the type of the values, such as the mean of texts.
+		DimensionError
+			When an axis is given for an Array that is not two-dimensional.
+		EmptyArrayError
+			When the statistic needs a value, such as ``Mean``, and the whole Array, or a row or column,
+			has no present value.
+		IntegerOverflowError
+			When the ``Sum`` of integers does not fit their type.
+
+		Warns
+		-----
+		CalculationWarning
+			When a result on decimals becomes an infinite value or NaN.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> temperatures = ndp.Array.from_list([12.0, None, 18.0])
+		>>> temperatures.compute(ndp.Mean()).to_value()
+		15.0
+		"""
+		statistic_values = compute_statistic(self._values, statistic, axis)
+		statistic_array = self._wrap(statistic_values)
+
+		return statistic_array
+
+	@checked_arguments
+	def apply(self, function: MathFunction | TimeFunction | ValueMapping) -> Self:
+		"""
+		Return a math function, a time function or a value mapping applied to each value.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		function
+			A ``MathFunction``, such as ``ndp.SquareRoot()``, applied to numbers, or a ``TimeFunction``,
+			such as ``ndp.DatePart(unit=ndp.DatePartUnit.MONTH)``, applied to dates, datetimes, durations or
+			numbers as each one states: see ``MathFunction`` and ``TimeFunction`` for every function. Or a
+			``ValueMapping`` giving a new value to listed values, such as codes replaced by labels.
+
+		Returns
+		-------
+		Self
+			A new Array of the same shape. Missing values stay missing.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When the function does not apply to the type of the values.
+		OutOfDomainError
+			When a value is outside the domain of a math function, such as the square root of -1.
+		UnmatchedValueError
+			When a value has no ``ValueChange`` in a ``ValueMapping`` whose ``others`` is ``Unmatched.ERROR``.
+		UnsupportedMissingError
+			When a ``ValueMapping`` gives integers or booleans and a missing value.
+
+		Warns
+		-----
+		CalculationWarning
+			When a result of a math function becomes an infinite value or NaN.
+
+		Examples
+		--------
+		>>> from datetime import date
+		>>> import numdaplot as ndp
+		>>> ndp.Array.from_list([1, 4, 9]).apply(ndp.SquareRoot())
+		Array([1., 2., 3.], dtype=FLOAT64)
+		>>> ndp.Array.from_list([date(2026, 3, 14)]).apply(ndp.DatePart(unit=ndp.DatePartUnit.MONTH))
+		Array([3.], dtype=FLOAT64)
+		>>> sexes = ndp.ValueMapping(changes=[ndp.ValueChange(1, "M"), ndp.ValueChange(2, "F")])
+		>>> ndp.Array.from_list([2, 1]).apply(sexes)
+		Array(['F', 'M'], dtype=TEXT)
+		"""
+		if isinstance(function, ValueMapping):
+			mapped_values = map_values(self._values, function)
+			mapped_array = self._wrap(mapped_values)
+			return mapped_array
+
+		if isinstance(function, TimeFunction):
+			time_values = apply_time_function(self._values, function)
+			time_array = self._wrap(time_values)
+			return time_array
+
+		transformed_values = apply_math_function(self._values, function)
+		transformed_array = self._wrap(transformed_values)
+
+		return transformed_array

numdaplot/arrays/array_conversion.py

@@ -0,0 +1,150 @@
+"""
+Conversion of an Array to Python values and text, and comparison of two Arrays.
+
+.. versionadded:: 0.1.0
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+from numdaplot.arrays.array_data import ArrayData
+from numdaplot.arrays.conversion.array_text import format_array
+from numdaplot.arrays.conversion.equality_check import are_equal
+from numdaplot.arrays.conversion.python_values import to_python_list
+from numdaplot.errors.invalid_type_error import InvalidTypeError
+from numdaplot.errors.not_single_value_error import NotSingleValueError
+from numdaplot.settings.argument_types import checked_arguments
+
+if TYPE_CHECKING:
+	from numdaplot.arrays.equality import Equality
+
+SINGLE_VALUE_COUNT = 1
+FLAT_DIMENSIONS = (-1,)
+EQUALITY_TARGET = "Array.is_equal other"
+EQUALITY_EXPECTED = "an Array"
+
+
+class ArrayConversion(ArrayData):
+	"""
+	Conversion of an Array with ``to_list`` and ``to_value``, comparison with ``is_equal``, and its text.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	def to_list(self) -> list[Any]:
+		"""
+		Return the values as a Python list, with one nested list per row for several dimensions.
+
+		This is the way to loop over the values: ``for value in array.to_list()``.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		list[Any]
+			Python values, ``datetime.time`` for times of day. A missing date, datetime, duration or time of day
+			becomes ``None``, a missing decimal ``nan``.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.Array.from_list([[1, 2], [3, 4]]).to_list()
+		[[1, 2], [3, 4]]
+		"""
+		python_values = to_python_list(self._values)
+
+		return python_values
+
+	def to_value(self) -> Any:
+		"""
+		Return the single value of an Array holding exactly one value, as a Python value.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		Any
+			The value, ``None`` for a missing date, datetime or duration.
+
+		Raises
+		------
+		NotSingleValueError
+			When the Array does not hold exactly one value.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.Array.from_list([3, 1, 2]).compute(ndp.Max()).to_value()
+		3
+		"""
+		if self._values.size != SINGLE_VALUE_COUNT:
+			raise NotSingleValueError(self._values.size)
+
+		flat_values = self._values.reshape(FLAT_DIMENSIONS)
+		python_values = to_python_list(flat_values)
+		single_value = python_values[0]
+
+		return single_value
+
+	@checked_arguments
+	def is_equal(self, equality: Equality) -> bool:
+		"""
+		Return whether this Array and another one have the same shape and the same values.
+
+		Two missing values at the same position are equal.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		equality
+			The other Array, and whether the types must also be the same.
+
+		Returns
+		-------
+		bool
+			True when both Arrays are equal.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+
+		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))
+		True
+		"""
+		other = cast(object, equality.other)
+		if not isinstance(other, ArrayData):
+			raise InvalidTypeError(EQUALITY_TARGET, EQUALITY_EXPECTED, other)
+
+		other_values = other._values
+		is_equal = are_equal(self._values, other_values, equality.types)
+
+		return is_equal
+
+	def __repr__(self) -> str:
+		"""
+		Return the text of the Array: its values, then its type.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		str
+			The text, such as ``Array([1, 2, 3], dtype=INT64)``.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.Array.from_list(["a", "b"])
+		Array(['a', 'b'], dtype=TEXT)
+		"""
+		array_text = format_array(self._values)
+
+		return array_text