numdaplot 0.1.0__py3-none-any.whl

numdaplot/arrays/array_layout.py

@@ -0,0 +1,179 @@
+"""
+Changes of the layout of an Array: shape, order and distinct values.
+
+.. versionadded:: 0.1.0
+"""
+
+import math
+from typing import Self
+
+from numdaplot.arrays.array_data import ArrayData
+from numdaplot.arrays.array_sorting import ArraySorting
+from numdaplot.arrays.layout.sorting_values import sort_values
+from numdaplot.arrays.layout.unique_values import find_unique_values
+from numdaplot.arrays.shape import Shape
+from numdaplot.errors.shape_mismatch_error import ShapeMismatchError
+from numdaplot.positions.axis import Axis
+from numdaplot.settings.argument_types import checked_arguments
+
+FLAT_DIMENSIONS = (-1,)
+
+
+class ArrayLayout(ArrayData):
+	"""
+	Changes of the layout of an Array: ``reshape``, ``transpose``, ``flatten``, ``sort`` and ``unique``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def reshape(self, shape: Shape) -> Self:
+		"""
+		Return the same values arranged in another shape, in reading order.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		shape
+			The new shape, holding exactly as many values as the Array.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ShapeMismatchError
+			When the new shape holds another number of values.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.Array.from_list([1, 2, 3, 4, 5, 6]).reshape(ndp.Shape([2, 3]))
+		Array([[1, 2, 3],
+		       [4, 5, 6]], dtype=INT64)
+		"""
+		new_size = math.prod(shape.dimensions)
+		if new_size != self._values.size:
+			raise ShapeMismatchError(self._values.shape, shape.dimensions)
+
+		reshaped_values = self._values.reshape(shape.dimensions)
+		reshaped_array = self._wrap(reshaped_values)
+
+		return reshaped_array
+
+	def transpose(self) -> Self:
+		"""
+		Return the Array with its rows turned into columns.
+
+		A one-dimensional Array stays the same. With more dimensions, their order is reversed.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.Array.from_list([[1, 2, 3], [4, 5, 6]]).transpose()
+		Array([[1, 4],
+		       [2, 5],
+		       [3, 6]], dtype=INT64)
+		"""
+		transposed_values = self._values.transpose()
+		transposed_array = self._wrap(transposed_values)
+
+		return transposed_array
+
+	def flatten(self) -> Self:
+		"""
+		Return the values in a single dimension, in reading order.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		Self
+			A new one-dimensional Array.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.Array.from_list([[1, 2], [3, 4]]).flatten()
+		Array([1, 2, 3, 4], dtype=INT64)
+		"""
+		flat_values = self._values.reshape(FLAT_DIMENSIONS)
+		flat_array = self._wrap(flat_values)
+
+		return flat_array
+
+	@checked_arguments
+	def sort(self, sorting: ArraySorting | None = None, axis: Axis | None = None) -> Self:
+		"""
+		Return the values sorted inside each row, or inside each column.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		sorting
+			The order and the place of missing values, the default ``ArraySorting`` when omitted.
+		axis
+			``Axis.EACH_ROW`` sorts the values inside each row, ``Axis.EACH_COLUMN`` inside each column. An axis
+			only applies to a two-dimensional Array. When omitted, each row is sorted, which sorts a
+			one-dimensional Array as a whole.
+
+		Returns
+		-------
+		Self
+			A new Array of the same shape.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		DimensionError
+			When an axis is given for an Array that is not two-dimensional.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.Array.from_list([3.0, None, 1.0]).sort(ndp.ArraySorting(order=ndp.Order.DESCENDING))
+		Array([ 3.,  1., nan], dtype=FLOAT64)
+		"""
+		if sorting is None:
+			sorting = ArraySorting()
+
+		sorted_values = sort_values(self._values, sorting, axis)
+		sorted_array = self._wrap(sorted_values)
+
+		return sorted_array
+
+	def unique(self) -> Self:
+		"""
+		Return each distinct value once, sorted, with a single missing value at the end when there is one.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		Self
+			A new one-dimensional Array.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.Array.from_list(["b", "a", "b"]).unique()
+		Array(['a', 'b'], dtype=TEXT)
+		"""
+		unique_values = find_unique_values(self._values)
+		unique_array = self._wrap(unique_values)
+
+		return unique_array

numdaplot/arrays/array_logic.py

@@ -0,0 +1,227 @@
+"""
+Boolean operators of an Array, combining the masks returned by ``check``.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Self
+
+import numpy
+
+from numdaplot.arrays.array_data import ArrayData
+from numdaplot.arrays.operations.boolean_operands import require_booleans
+from numdaplot.arrays.operations.transformation import transform_values
+from numdaplot.settings.argument_types import checked_arguments
+
+AND_SYMBOL = "&"
+OR_SYMBOL = "|"
+NOT_SYMBOL = "~"
+
+
+class ArrayLogic(ArrayData):
+	"""
+	Boolean operators of an Array: ``&`` (and), ``|`` (or) and ``~`` (not).
+
+	They only apply to ``BOOL`` values, such as the masks returned by ``check``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def __and__(self, other: Self | bool) -> Self:
+		"""
+		Return True where both operands are True, written ``array & other``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			A ``BOOL`` Array or a boolean.
+
+		Returns
+		-------
+		Self
+			A new ``BOOL`` Array.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When an operand is not a boolean.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ages = ndp.Array.from_list([15, 30, 70])
+		>>> ages.check(ndp.Greater(18)) & ages.check(ndp.Less(65))
+		Array([False,  True, False], dtype=BOOL)
+		"""
+		combined_array = self._combine_booleans(other, numpy.logical_and, AND_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __rand__(self, other: bool) -> Self:
+		"""
+		Return True where both operands are True, written ``value & array``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			A boolean.
+
+		Returns
+		-------
+		Self
+			A new ``BOOL`` Array.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When an operand is not a boolean.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> True & ndp.Array.from_list([True, False])
+		Array([ True, False], dtype=BOOL)
+		"""
+		combined_array = self._combine_booleans(other, numpy.logical_and, AND_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __or__(self, other: Self | bool) -> Self:
+		"""
+		Return True where at least one operand is True, written ``array | other``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			A ``BOOL`` Array or a boolean.
+
+		Returns
+		-------
+		Self
+			A new ``BOOL`` Array.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When an operand is not a boolean.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ages = ndp.Array.from_list([15, 30, 70])
+		>>> ages.check(ndp.Less(18)) | ages.check(ndp.Greater(65))
+		Array([ True, False,  True], dtype=BOOL)
+		"""
+		combined_array = self._combine_booleans(other, numpy.logical_or, OR_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __ror__(self, other: bool) -> Self:
+		"""
+		Return True where at least one operand is True, written ``value | array``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			A boolean.
+
+		Returns
+		-------
+		Self
+			A new ``BOOL`` Array.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When an operand is not a boolean.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> False | ndp.Array.from_list([True, False])
+		Array([ True, False], dtype=BOOL)
+		"""
+		combined_array = self._combine_booleans(other, numpy.logical_or, OR_SYMBOL)
+
+		return combined_array
+
+	def __invert__(self) -> Self:
+		"""
+		Return True where the value is False, and False where it is True, written ``~array``.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		Self
+			A new ``BOOL`` Array.
+
+		Raises
+		------
+		IncompatibleTypesError
+			When the values are not booleans.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ~ndp.Array.from_list([True, False])
+		Array([False,  True], dtype=BOOL)
+		"""
+		require_booleans([self._values], NOT_SYMBOL)
+		inverted_values = transform_values(self._values, numpy.logical_not, NOT_SYMBOL)
+		inverted_array = self._wrap(inverted_values)
+
+		return inverted_array
+
+	def _combine_booleans(self, other: object, function: numpy.ufunc, symbol: str) -> Self:
+		"""
+		Return a new Array combining the booleans of this Array with another boolean operand.
+
+		Both boolean operators are symmetric, so the side of each operand does not matter.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			A ``BOOL`` Array or a boolean.
+		function
+			``numpy.logical_and`` or ``numpy.logical_or``.
+		symbol
+			The operator shown in error messages.
+
+		Returns
+		-------
+		Self
+			The combined Array.
+
+		Raises
+		------
+		IncompatibleTypesError
+			When an operand is not a boolean.
+		"""
+		other_values = self._read_operand(other)
+		require_booleans([self._values, other_values], symbol)
+		combined_array = self._combine(other, function, symbol)
+
+		return combined_array