numdaplot 0.1.0__py3-none-any.whl

numdaplot/arrays/math_functions/logarithm.py

@@ -0,0 +1,72 @@
+"""
+Logarithm math function.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.arrays.math_functions.math_function import MathFunction
+from numdaplot.errors.invalid_base_error import InvalidBaseError
+from numdaplot.settings.field_types import require_field_types
+
+LOWEST_EXCLUDED_BASE = 0
+FORBIDDEN_BASE = 1
+
+
+@dataclass(frozen=True)
+class Logarithm(MathFunction):
+	"""
+	Logarithm of each value: with ``base=10``, 1000 gives 3.
+
+	Applying it to a value lower than or equal to 0 raises ``OutOfDomainError``.
+	Missing values stay missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	base
+		Base of the logarithm, greater than 0 and different from 1.
+		The natural logarithm, of base ``e``, when omitted.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidBaseError
+		When ``base`` is lower than or equal to 0, or equal to 1.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> populations = ndp.Array.from_list([1, 100, 1000])
+	>>> populations.apply(ndp.Logarithm(base=10))
+	Array([0., 2., 3.], dtype=FLOAT64)
+	"""
+
+	base: float | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the base can be used.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidBaseError
+			When ``base`` is lower than or equal to 0, or equal to 1.
+		"""
+		require_field_types(self)
+
+		if self.base is None:
+			return
+
+		if self.base <= LOWEST_EXCLUDED_BASE:
+			raise InvalidBaseError(self.base)
+
+		if self.base == FORBIDDEN_BASE:
+			raise InvalidBaseError(self.base)

numdaplot/arrays/math_functions/math_function.py

@@ -0,0 +1,58 @@
+"""
+Base class of every math function.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+
+CONSTRUCTOR_OPERATION = "Creating a MathFunction with ndp.MathFunction()"
+CONSTRUCTOR_ALTERNATIVE = "a math function such as ndp.SquareRoot"
+
+
+class MathFunction:
+	"""
+	Base class of every math function, applied to each value of a number Array by ``Array.apply``.
+
+	A math function is immutable and checks its settings when it is created.
+
+	Only its subclasses are created: calling ``ndp.MathFunction()`` raises ``RefusedOperationError``.
+
+	Every math function, passed to ``Array.apply``:
+
+	|Math function|What it gives for each value|Example|
+	|---|---|---|
+	|``Absolute``|Its distance to 0: -3 and 3 both give 3|``ndp.Absolute()``|
+	|``SquareRoot``|Its square root: 9 gives 3|``ndp.SquareRoot()``|
+	|``Exponential``|``e`` raised to the value: 0 gives 1|``ndp.Exponential()``|
+	|``Logarithm``|Its logarithm: with ``base=10``, 1000 gives 3|``ndp.Logarithm(base=10)``|
+	|``Round``|The value rounded to a number of decimals|``ndp.Round(decimals=2)``|
+	|``Sine``|Its sine, read as an angle in radians|``ndp.Sine()``|
+	|``Cosine``|Its cosine, read as an angle in radians|``ndp.Cosine()``|
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> values = ndp.Array.from_list([1.0, 4.0])
+	>>> for function in [ndp.SquareRoot(), ndp.Logarithm(base=2)]:
+	... 	print(values.apply(function))
+	Array([1., 2.], dtype=FLOAT64)
+	Array([0., 2.], dtype=FLOAT64)
+	"""
+
+	def __init__(self) -> None:
+		"""
+		Refuse the creation of the base class itself, and let a subclass be created.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		RefusedOperationError
+			When the created object is a MathFunction and not one of its subclasses.
+		"""
+		created_class = type(self)
+		if created_class is MathFunction:
+			raise RefusedOperationError(CONSTRUCTOR_OPERATION, CONSTRUCTOR_ALTERNATIVE)

numdaplot/arrays/math_functions/round.py

@@ -0,0 +1,58 @@
+"""
+Rounding math function.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.arrays.math_functions.math_function import MathFunction
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class Round(MathFunction):
+	"""
+	Each value rounded to a number of decimals.
+
+	A value exactly halfway is rounded to the nearest even digit, as in numpy:
+	2.5 gives 2 and 3.5 gives 4. Missing values stay missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	decimals
+		Number of decimals kept, 0 by default to round to whole numbers. A negative number rounds to
+		tens, hundreds...: -2 turns 1234 into 1200.
+
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.346, 2.5, 3.5])
+	>>> prices.apply(ndp.Round(decimals=2))
+	Array([12.35,  2.5 ,  3.5 ], dtype=FLOAT64)
+	>>> prices.apply(ndp.Round())
+	Array([12.,  2.,  4.], dtype=FLOAT64)
+	"""
+
+	decimals: int = 0
+
+	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/math_functions/sine.py

@@ -0,0 +1,28 @@
+"""
+Sine math function.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.arrays.math_functions.math_function import MathFunction
+
+
+@dataclass(frozen=True)
+class Sine(MathFunction):
+	"""
+	Sine 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 / 2])
+	>>> angles.apply(ndp.Sine())
+	Array([0., 1.], dtype=FLOAT64)
+	"""

numdaplot/arrays/math_functions/square_root.py

@@ -0,0 +1,27 @@
+"""
+Square root math function.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.arrays.math_functions.math_function import MathFunction
+
+
+@dataclass(frozen=True)
+class SquareRoot(MathFunction):
+	"""
+	Square root of each value: 9 gives 3.
+
+	Applying it to a negative value raises ``OutOfDomainError``. Missing values stay missing.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> areas = ndp.Array.from_list([4, 9, 16])
+	>>> areas.apply(ndp.SquareRoot())
+	Array([2., 3., 4.], dtype=FLOAT64)
+	"""

numdaplot/arrays/operations/__init__.py

@@ -0,0 +1,5 @@
+"""
+Arithmetic and boolean operations between Arrays and single values.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/arrays/operations/boolean_operands.py

@@ -0,0 +1,48 @@
+"""
+Check that the operands of a boolean operator are booleans.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.arrays.operations.operand import Operand, find_operand_type, find_operand_type_names
+from numdaplot.data_types.type import Type
+from numdaplot.errors.incompatible_types_error import IncompatibleTypesError
+
+
+def require_booleans(operands: list[Operand], symbol: str) -> None:
+	"""
+	Check that every operand of a boolean operator holds booleans.
+
+	``&``, ``|`` and ``~`` combine the masks returned by ``check``. On integers, numpy would
+	combine their bits instead, which is refused.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operands
+		The values of Arrays, or single values.
+	symbol
+		The operator shown in error messages, such as ``"&"``.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When an operand is not a boolean.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.operations.boolean_operands import require_booleans
+	>>> try:
+	... 	require_booleans([numpy.array([True]), 2], "|")
+	... except ndp.IncompatibleTypesError as error:
+	... 	print(error)
+	Cannot apply | to BOOL and INT64.
+	"""
+	for operand in operands:
+		operand_type = find_operand_type(operand)
+		if operand_type != Type.BOOL:
+			type_names = find_operand_type_names(operands)
+			raise IncompatibleTypesError(symbol, type_names)

numdaplot/arrays/operations/combination.py

@@ -0,0 +1,157 @@
+"""
+Combination of two operands with an arithmetic or boolean function.
+
+.. versionadded:: 0.1.0
+"""
+
+import warnings
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.operations.float_errors import FloatErrorWarnings, TimeErrorWarnings
+from numdaplot.arrays.operations.integer_rules import require_combination_fits, require_defined_integers
+from numdaplot.arrays.operations.operand import Operand, find_operand_type_names
+from numdaplot.arrays.operations.time_arithmetic import combine_time_values, involves_time
+from numdaplot.errors.broadcast_warning import BroadcastWarning
+from numdaplot.errors.incompatible_types_error import IncompatibleTypesError
+from numdaplot.errors.integer_overflow_error import IntegerOverflowError
+from numdaplot.errors.shape_mismatch_error import ShapeMismatchError
+
+PYTHON_OBJECT_KIND = "O"
+BROADCAST_MESSAGE = "Shapes {left_dimensions} and {right_dimensions} differ, values are repeated to match."
+# The warning points at the user line: check_shapes, combine_values, the Array helper, the operator, its check.
+BROADCAST_STACK_LEVEL = 6
+
+
+def combine_values(left: Operand, right: Operand, function: numpy.ufunc, symbol: str) -> NDArray[Any]:
+	"""
+	Return the result of a numpy function applied to two operands, value by value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	left
+		The values of an Array, or a single value.
+	right
+		The values of an Array, or a single value. At least one side is the values of an Array.
+	function
+		The numpy function, such as ``numpy.add``.
+	symbol
+		The operator shown in error messages, such as ``"+"``.
+
+	Returns
+	-------
+	NDArray
+		The combined values, following the numpy type rules, and the rules of ``combine_time_values`` for
+		dates, datetimes and durations.
+
+	Warns
+	-----
+	BroadcastWarning
+		When both sides are Array values of different but compatible shapes.
+	CalculationWarning
+		When values of decimals become NaN or an infinite value, or durations become missing values.
+
+	Raises
+	------
+	ShapeMismatchError
+		When both sides are Array values whose shapes cannot be combined.
+	IncompatibleTypesError
+		When the function does not apply to the types of the operands.
+	OutOfDomainError
+		When integers are divided by 0 with ``//`` or ``%``, or raised to a negative power.
+	IntegerOverflowError
+		When a result does not fit its integer type.
+	TimeOverflowError
+		When a date, a datetime or a duration is outside the range of nanoseconds.
+	RefusedOperationError, ValueConversionError
+		When a time operation is refused, as in ``combine_time_values``.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.operations.combination import combine_values
+	>>> combine_values(numpy.array([1, 2]), 10, numpy.multiply, "*")
+	array([10, 20])
+	"""
+	check_shapes(left, right)
+	has_time = involves_time(left, right)
+	if has_time:
+		with TimeErrorWarnings(symbol):
+			time_values = combine_time_values(left, right, function, symbol)
+
+		return time_values
+
+	require_defined_integers(left, right, function)
+	operands = list[Operand]([left, right])
+	try:
+		with FloatErrorWarnings(symbol):
+			combined_values = function(left, right)
+			require_combination_fits(operands, function, combined_values, symbol)
+	except TypeError as error:
+		type_names = find_operand_type_names(operands)
+		raise IncompatibleTypesError(symbol, type_names) from error
+	except OverflowError as error:
+		type_names = find_operand_type_names(operands)
+		raise IntegerOverflowError(symbol, type_names[0]) from error
+
+	if combined_values.dtype.kind == PYTHON_OBJECT_KIND:
+		type_names = find_operand_type_names(operands)
+		raise IncompatibleTypesError(symbol, type_names)
+
+	return combined_values
+
+
+def check_shapes(left: Operand, right: Operand) -> None:
+	"""
+	Check that two operands can be combined, and warn when an Array is stretched to match the other.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	left
+		The values of an Array, or a single value.
+	right
+		The values of an Array, or a single value.
+
+	Warns
+	-----
+	BroadcastWarning
+		When both sides are Array values of different but compatible shapes.
+
+	Raises
+	------
+	ShapeMismatchError
+		When both sides are Array values whose shapes cannot be combined.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.operations.combination import check_shapes
+	>>> try:
+	... 	check_shapes(numpy.array([1, 2]), numpy.array([1, 2, 3]))
+	... except ndp.ShapeMismatchError as error:
+	... 	print(error)
+	Expected matching shapes, got [2] and [3].
+	"""
+	if not isinstance(left, numpy.ndarray):
+		return
+
+	if not isinstance(right, numpy.ndarray):
+		return
+
+	if left.shape == right.shape:
+		return
+
+	try:
+		numpy.broadcast_shapes(left.shape, right.shape)
+	except ValueError as error:
+		raise ShapeMismatchError(left.shape, right.shape) from error
+
+	message = BROADCAST_MESSAGE.format(left_dimensions=left.shape, right_dimensions=right.shape)
+	warnings.warn(message, BroadcastWarning, stacklevel=BROADCAST_STACK_LEVEL)

numdaplot/arrays/operations/float_errors.py

@@ -0,0 +1,170 @@
+"""
+Warnings about the values of a calculation that become NaN or an infinite value.
+
+.. versionadded:: 0.1.0
+"""
+
+import os
+import warnings
+from pathlib import Path
+from types import TracebackType
+
+import numpy
+
+from numdaplot.errors.calculation_warning import CalculationWarning
+
+CALL_MODE = "call"
+IGNORE_MODE = "ignore"
+PACKAGE_LEVEL = 2
+PACKAGE_DIRECTORY = str(Path(__file__).parents[PACKAGE_LEVEL]) + os.sep
+INTERNAL_FILES = (PACKAGE_DIRECTORY,)
+# The keys are the names numpy gives to its floating point errors.
+FLOAT_ERROR_MESSAGES = {
+	"invalid value": "The operation {operation_name} has values without a defined result, such as 0 / 0: "
+	"they became NaN.",
+	"divide by zero": "The operation {operation_name} divides by zero: these values became inf.",
+	"overflow": "The operation {operation_name} has values too large for their type: they became inf.",
+}
+# A duration too large is refused before it is computed, so a calculation on times only meets these two errors.
+TIME_ERROR_MESSAGES = {
+	"invalid value": "The operation {operation_name} has values without a defined result, such as 0 / 0: "
+	"they became missing.",
+	"divide by zero": "The operation {operation_name} divides by zero: these values became missing.",
+}
+
+
+class FloatErrorWarnings:
+	"""
+	Context giving the numpy floating point errors of a block as ``CalculationWarning``, at the calling code.
+
+	Each kind of error gives one warning when the block ends, and none when the block raises an error.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operation_name
+		The operator or the function shown in the message, such as ``/`` or ``Sum``.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import warnings
+	>>> from numdaplot.arrays.operations.float_errors import FloatErrorWarnings
+	>>> with warnings.catch_warnings(record=True) as caught_warnings:
+	... 	warnings.simplefilter("always")
+	... 	with FloatErrorWarnings("/"):
+	... 		numpy.array([1.0]) / numpy.array([0.0])
+	array([inf])
+	>>> print(caught_warnings[0].message)
+	The operation / divides by zero: these values became inf.
+	"""
+
+	messages = FLOAT_ERROR_MESSAGES
+
+	def __init__(self, operation_name: str) -> None:
+		"""
+		Prepare the numpy settings recording the errors of the block.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		operation_name
+			The operator or the function shown in the message, such as ``/`` or ``Sum``.
+		"""
+		self.operation_name = operation_name
+		self.met_errors = set[str]()
+		self.numpy_settings = numpy.errstate(
+			divide=CALL_MODE,
+			invalid=CALL_MODE,
+			over=CALL_MODE,
+			under=IGNORE_MODE,
+			call=self.record_float_error,
+		)
+
+	def record_float_error(self, error_name: str, _error_flag: int) -> None:
+		"""
+		Remember a floating point error, as numpy reports it during the block.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		error_name
+			The name numpy gives to the error.
+		_error_flag
+			The numpy code of the error, not used.
+		"""
+		self.met_errors.add(error_name)
+
+	def __enter__(self) -> None:
+		"""
+		Start recording the errors.
+
+		.. versionadded:: 0.1.0
+		"""
+		self.numpy_settings.__enter__()
+
+	def __exit__(
+		self,
+		error_type: type[BaseException] | None,
+		error: BaseException | None,
+		traceback: TracebackType | None,
+	) -> None:
+		"""
+		Stop recording the errors, and warn once per kind of error unless the block raised one.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		error_type
+			The type of the error raised by the block, or None.
+		error
+			The error raised by the block, or None.
+		traceback
+			Its traceback, or None.
+
+		Warns
+		-----
+		CalculationWarning
+			Once per kind of error met in the block.
+		"""
+		self.numpy_settings.__exit__(error_type, error, traceback)
+		if error_type is not None:
+			return
+
+		for error_name, message_format in self.messages.items():
+			if error_name in self.met_errors:
+				message = message_format.format(operation_name=self.operation_name)
+				warnings.warn(message, CalculationWarning, skip_file_prefixes=INTERNAL_FILES)
+
+
+class TimeErrorWarnings(FloatErrorWarnings):
+	"""
+	Context giving the numpy floating point errors of a calculation on times, whose values become missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operation_name
+		The operator shown in the message, such as ``/``.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import warnings
+	>>> from numdaplot.arrays.operations.float_errors import TimeErrorWarnings
+	>>> durations = numpy.array([1], dtype="timedelta64[ns]")
+	>>> with warnings.catch_warnings(record=True) as caught_warnings:
+	... 	warnings.simplefilter("always")
+	... 	with TimeErrorWarnings("/"):
+	... 		durations / numpy.array([0.0])
+	array(['NaT'], dtype='timedelta64[ns]')
+	>>> print(caught_warnings[0].message)
+	The operation / divides by zero: these values became missing.
+	"""
+
+	messages = TIME_ERROR_MESSAGES