numdaplot 0.1.0__py3-none-any.whl

numdaplot/arrays/creation/random_integers.py

@@ -0,0 +1,104 @@
+"""
+Uniform distribution of whole numbers.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.arrays.creation.distribution import Distribution
+from numdaplot.errors.invalid_bounds_error import InvalidBoundsError
+from numdaplot.rules.bounds import HIGH_INCLUDED_BOUNDS, LOW_INCLUDED_BOUNDS, Bounds
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class RandomIntegers(Distribution):
+	"""
+	Whole numbers drawn with the same chance from ``low`` to ``high``.
+
+	Both bounds can be drawn by default: ``RandomIntegers(low=1, high=6)`` rolls a die.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	low
+		Low bound.
+	high
+		High bound.
+	bounds
+		Which bounds can be drawn. Both are included by default.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidBoundsError
+		When no whole number lies between the bounds, such as ``low`` greater than ``high``,
+		or ``low=3, high=4`` with both bounds excluded.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> dice = ndp.RandomIntegers(low=1, high=6)
+	>>> ndp.Array.random(dice, shape=ndp.Shape([5]), seed=0)
+	Array([6, 4, 4, 2, 2], dtype=INT64)
+	"""
+
+	low: int
+	high: int
+	bounds: Bounds = Bounds.INCLUDED
+
+	def __post_init__(self) -> None:
+		"""
+		Check that at least one whole number can be drawn.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidBoundsError
+			When no whole number lies between the bounds.
+		"""
+		require_field_types(self)
+
+		lowest_value, value_limit = find_drawn_interval(self)
+		if lowest_value >= value_limit:
+			raise InvalidBoundsError(self.low, self.high)
+
+
+def find_drawn_interval(distribution: RandomIntegers) -> tuple[int, int]:
+	"""
+	Return the lowest value that can be drawn and the value that every drawn value stays below.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	distribution
+		The distribution whose bounds are read.
+
+	Returns
+	-------
+	tuple[int, int]
+		The lowest drawable value, and the high limit excluded from the draw, as numpy expects them.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.creation.random_integers import find_drawn_interval
+	>>> find_drawn_interval(ndp.RandomIntegers(low=1, high=6))
+	(1, 7)
+	"""
+	lowest_value = distribution.low
+	if distribution.bounds not in LOW_INCLUDED_BOUNDS:
+		lowest_value += 1
+
+	value_limit = distribution.high
+	if distribution.bounds in HIGH_INCLUDED_BOUNDS:
+		value_limit += 1
+
+	return lowest_value, value_limit

numdaplot/arrays/creation/random_values.py

@@ -0,0 +1,97 @@
+"""
+Values drawn from a random distribution.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.creation.normal import Normal
+from numdaplot.arrays.creation.random_integers import RandomIntegers, find_drawn_interval
+from numdaplot.arrays.creation.uniform import Uniform
+from numdaplot.arrays.shape import Shape
+from numdaplot.errors.invalid_seed_error import InvalidSeedError
+
+LOWEST_SEED = 0
+
+
+def draw_random_values(distribution: Uniform | Normal | RandomIntegers, shape: Shape, seed: int | None) -> NDArray[Any]:
+	"""
+	Return values drawn from a random distribution.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	distribution
+		The law followed by the values.
+	shape
+		The shape of the result.
+	seed
+		A number giving the same values at each call, at least 0. Different values at each call when ``None``.
+
+	Returns
+	-------
+	NDArray
+		Decimals for ``Uniform`` and ``Normal``, integers for ``RandomIntegers``.
+
+	Raises
+	------
+	InvalidSeedError
+		When ``seed`` is lower than 0.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.creation.random_values import draw_random_values
+	>>> dice = ndp.RandomIntegers(low=1, high=6)
+	>>> draw_random_values(dice, ndp.Shape([4]), 0)
+	array([6, 4, 4, 2])
+	"""
+	if seed is not None:
+		require_valid_seed(seed)
+
+	generator = numpy.random.default_rng(seed)
+	match distribution:
+		case Uniform():
+			values = generator.uniform(distribution.low, distribution.high, shape.dimensions)
+		case Normal():
+			values = generator.normal(distribution.mean, distribution.deviation, shape.dimensions)
+		case RandomIntegers():
+			lowest_value, value_limit = find_drawn_interval(distribution)
+			values = generator.integers(lowest_value, value_limit, shape.dimensions)
+
+	return values
+
+
+def require_valid_seed(seed: int) -> None:
+	"""
+	Check that a random seed is not negative.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	seed
+		The seed to check.
+
+	Raises
+	------
+	InvalidSeedError
+		When ``seed`` is lower than 0.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.creation.random_values import require_valid_seed
+	>>> try:
+	... 	require_valid_seed(-1)
+	... except ndp.InvalidSeedError as error:
+	... 	print(error)
+	Expected a seed of at least 0, got -1.
+	"""
+	if seed < LOWEST_SEED:
+		raise InvalidSeedError(seed)

numdaplot/arrays/creation/range_values.py

@@ -0,0 +1,73 @@
+"""
+Numbers of a regular sequence.
+
+.. versionadded:: 0.1.0
+"""
+
+import math
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.positions.range import Range
+from numdaplot.rules.bounds import HIGH_INCLUDED_BOUNDS, LOW_INCLUDED_BOUNDS
+
+# Decimal steps accumulate rounding errors: 0.1 * 10 gives 0.9999999999999999, not 1.
+STEP_TOLERANCE = 1e-9
+
+
+def compute_range_values(sequence: Range) -> NDArray[Any]:
+	"""
+	Return the numbers of a regular sequence.
+
+	A stop reached within a tiny fraction of a step counts as reached, so ``Range(0, 1, 0.1)``
+	ends with exactly 1.0 when the stop is included.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	sequence
+		The sequence. ``LOW_ONLY`` keeps its start and drops its stop, ``HIGH_ONLY`` the opposite.
+
+	Returns
+	-------
+	NDArray
+		Integers when the start and the step are integers, decimals otherwise.
+		Empty when the excluded bounds leave no number, such as from 1 to 1 with ``Bounds.EXCLUDED``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.creation.range_values import compute_range_values
+	>>> compute_range_values(ndp.Range(start=0, stop=10, step=5))
+	array([ 0,  5, 10])
+	"""
+	distance = sequence.stop - sequence.start
+	step_count = distance / sequence.step
+	nearest_step_count = round(step_count)
+	step_count_error = abs(step_count - nearest_step_count)
+	reaches_stop = step_count_error <= STEP_TOLERANCE
+	tolerated_step_count = step_count + STEP_TOLERANCE
+
+	first_index = 0
+	if sequence.bounds not in LOW_INCLUDED_BOUNDS:
+		first_index = 1
+
+	last_index = math.floor(tolerated_step_count)
+	includes_stop = sequence.bounds in HIGH_INCLUDED_BOUNDS
+	drops_reached_stop = reaches_stop and not includes_stop
+	if drops_reached_stop:
+		last_index -= 1
+
+	index_limit = last_index + 1
+	indexes = numpy.arange(first_index, index_limit)
+	offsets = indexes * sequence.step
+	values = sequence.start + offsets
+	has_values = indexes.size > 0
+	ends_on_stop = reaches_stop and includes_stop and has_values
+	if ends_on_stop:
+		values[-1] = sequence.stop
+
+	return values

numdaplot/arrays/creation/spacing.py

@@ -0,0 +1,84 @@
+"""
+A given count of evenly spaced numbers between two bounds.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.invalid_count_error import InvalidCountError
+from numdaplot.rules.bounds import Bounds
+from numdaplot.settings.field_types import require_field_types
+
+LOWEST_COUNT_WITH_BOTH_BOUNDS = 2
+LOWEST_COUNT = 1
+
+
+@dataclass(frozen=True)
+class Spacing:
+	"""
+	A given count of evenly spaced numbers from ``start`` to ``stop``, used by ``Array.from_spacing``.
+
+	``bounds`` tells whether ``start`` and ``stop`` are among the values. With ``start=0``,
+	``stop=1`` and ``count=4``:
+
+	- ``INCLUDED`` gives 0, 0.333, 0.667, 1;
+	- ``LOW_ONLY`` gives 0, 0.25, 0.5, 0.75;
+	- ``HIGH_ONLY`` gives 0.25, 0.5, 0.75, 1;
+	- ``EXCLUDED`` gives 0.2, 0.4, 0.6, 0.8.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	start
+		First bound.
+	stop
+		Second bound, lower than ``start`` for decreasing values.
+	count
+		Number of values, at least 2 when both bounds are included, at least 1 otherwise.
+	bounds
+		Which bounds are among the values. Both are included by default.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidCountError
+		When ``count`` is too low for the bounds.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_spacing(ndp.Spacing(start=0, stop=1, count=5))
+	Array([0.  , 0.25, 0.5 , 0.75, 1.  ], dtype=FLOAT64)
+	>>> ndp.Array.from_spacing(ndp.Spacing(start=0, stop=1, count=4, bounds=ndp.Bounds.EXCLUDED))
+	Array([0.2, 0.4, 0.6, 0.8], dtype=FLOAT64)
+	"""
+
+	start: float
+	stop: float
+	count: int
+	bounds: Bounds = Bounds.INCLUDED
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the count is high enough for the bounds.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidCountError
+			When ``count`` is too low for the bounds.
+		"""
+		require_field_types(self)
+
+		lowest_count = LOWEST_COUNT
+		if self.bounds == Bounds.INCLUDED:
+			lowest_count = LOWEST_COUNT_WITH_BOTH_BOUNDS
+
+		if self.count < lowest_count:
+			raise InvalidCountError(self.count, lowest_count)

numdaplot/arrays/creation/spacing_values.py

@@ -0,0 +1,63 @@
+"""
+Evenly spaced numbers.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.creation.spacing import Spacing
+from numdaplot.rules.bounds import HIGH_INCLUDED_BOUNDS, LOW_INCLUDED_BOUNDS
+
+
+def compute_spacing_values(spacing: Spacing) -> NDArray[Any]:
+	"""
+	Return the evenly spaced numbers of a spacing.
+
+	The interval is cut into equal gaps: one fewer than the count when both bounds are kept,
+	one more when both are dropped.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	spacing
+		The spacing.
+
+	Returns
+	-------
+	NDArray
+		``count`` decimals. An included stop is exactly ``stop``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.creation.spacing_values import compute_spacing_values
+	>>> compute_spacing_values(ndp.Spacing(start=0, stop=1, count=4, bounds=ndp.Bounds.LOW_ONLY))
+	array([0.  , 0.25, 0.5 , 0.75])
+	"""
+	includes_start = spacing.bounds in LOW_INCLUDED_BOUNDS
+	includes_stop = spacing.bounds in HIGH_INCLUDED_BOUNDS
+
+	gap_count = spacing.count + 1
+	first_offset = 1
+	if includes_start:
+		gap_count -= 1
+		first_offset = 0
+
+	if includes_stop:
+		gap_count -= 1
+
+	distance = spacing.stop - spacing.start
+	gap = distance / gap_count
+	offset_limit = first_offset + spacing.count
+	offsets = numpy.arange(first_offset, offset_limit)
+	distances = offsets * gap
+	values = spacing.start + distances
+	if includes_stop:
+		values[-1] = spacing.stop
+
+	return values

numdaplot/arrays/creation/uniform.py

@@ -0,0 +1,63 @@
+"""
+Uniform distribution of decimals.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.arrays.creation.distribution import Distribution
+from numdaplot.errors.invalid_bounds_error import InvalidBoundsError
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class Uniform(Distribution):
+	"""
+	Decimals drawn with the same chance anywhere from ``low`` to ``high``.
+
+	``high`` itself is never drawn, as in numpy. Use ``RandomIntegers`` for whole numbers.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	low
+		Lowest value that can be drawn.
+	high
+		Value that every drawn value stays below, greater than or equal to ``low``.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidBoundsError
+		When ``low`` is greater than ``high``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.random(ndp.Uniform(low=0, high=1), shape=ndp.Shape([3]), seed=0)
+	Array([0.63696169, 0.26978671, 0.04097352], dtype=FLOAT64)
+	"""
+
+	low: float
+	high: float
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the low bound is not greater than the high bound.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidBoundsError
+			When ``low`` is greater than ``high``.
+		"""
+		require_field_types(self)
+
+		if self.low > self.high:
+			raise InvalidBoundsError(self.low, self.high)

numdaplot/arrays/equality.py

@@ -0,0 +1,68 @@
+"""
+Settings of the comparison of two Arrays or two Tables.
+
+.. versionadded:: 0.1.0
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from numdaplot.arrays.type_match import TypeMatch
+from numdaplot.settings.field_types import require_field_types
+
+if TYPE_CHECKING:
+	from numdaplot.arrays.array import Array
+	from numdaplot.tables.table import Table
+
+
+# eq=False because comparing two settings would compare their Arrays or Tables with ==, which they refuse.
+@dataclass(frozen=True, eq=False)
+class Equality:
+	"""
+	Settings of the comparison of two Arrays or two Tables, used by ``Array.is_equal`` and ``Table.is_equal``.
+
+	Two Arrays are equal when they have the same shape and the same values at each position.
+	Two Tables are equal when they have the same columns, in the same order, with the same values.
+	Two missing values at the same position are equal.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	other
+		The Array or the Table to compare with, of the same kind as the compared one.
+	types
+		Whether the types must also be the same. Only the values are compared by default.
+
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting 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, types=ndp.TypeMatch.STRICT))
+	False
+	"""
+
+	other: Array | Table
+	types: TypeMatch = TypeMatch.IGNORED
+
+	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/layout/__init__.py

@@ -0,0 +1,5 @@
+"""
+Sorting and deduplication of Array values.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/arrays/layout/sorting_values.py

@@ -0,0 +1,113 @@
+"""
+Sorting of the values of an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.array_sorting import ArraySorting
+from numdaplot.arrays.axis_number import find_numpy_axis
+from numdaplot.arrays.selection.missing_mask import find_missing
+from numdaplot.ordering.missing_position import MissingPosition
+from numdaplot.ordering.order import Order
+from numdaplot.positions.axis import Axis
+
+LAST_AXIS = -1
+
+
+def sort_values(values: NDArray[Any], sorting: ArraySorting, axis: Axis | None) -> NDArray[Any]:
+	"""
+	Return the values sorted inside each row, or inside each column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of an Array.
+	sorting
+		The order and the place of missing values.
+	axis
+		``EACH_ROW`` or ``EACH_COLUMN`` for a two-dimensional Array, or None to sort each row.
+
+	Returns
+	-------
+	NDArray
+		The sorted values, of the same shape.
+
+	Raises
+	------
+	DimensionError
+		When an axis is given for an Array that is not two-dimensional.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.layout.sorting_values import sort_values
+	>>> sort_values(numpy.array([[3, 1], [2, 4]]), ndp.ArraySorting(), ndp.Axis.EACH_COLUMN)
+	array([[2, 1],
+	       [3, 4]])
+	"""
+	numpy_axis = find_numpy_axis(axis, values.ndim)
+	if numpy_axis is None:
+		numpy_axis = LAST_AXIS
+
+	moved_values = numpy.moveaxis(values, numpy_axis, LAST_AXIS)
+	slice_size = moved_values.shape[LAST_AXIS]
+	slices = moved_values.reshape(LAST_AXIS, slice_size)
+	sorted_slices = numpy.empty_like(slices)
+	for i, values_slice in enumerate(slices):
+		sorted_slices[i] = sort_slice(values_slice, sorting)
+
+	sorted_moved_values = sorted_slices.reshape(moved_values.shape)
+	sorted_values = numpy.moveaxis(sorted_moved_values, LAST_AXIS, numpy_axis)
+
+	return sorted_values
+
+
+def sort_slice(values: NDArray[Any], sorting: ArraySorting) -> NDArray[Any]:
+	"""
+	Return one-dimensional values sorted, with their missing values first or last.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		One-dimensional values.
+	sorting
+		The order and the place of missing values.
+
+	Returns
+	-------
+	NDArray
+		The sorted values.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.layout.sorting_values import sort_slice
+	>>> sort_slice(numpy.array([1.0, numpy.nan, 3.0]), ndp.ArraySorting(order=ndp.Order.DESCENDING))
+	array([ 3.,  1., nan])
+	"""
+	missing = find_missing(values)
+	present = ~missing
+	present_values = values[present]
+	missing_values = values[missing]
+	ordered_values = numpy.sort(present_values)
+	if sorting.order == Order.DESCENDING:
+		ordered_values = ordered_values[::-1]
+
+	parts = [ordered_values, missing_values]
+	if sorting.missing == MissingPosition.FIRST:
+		parts = [missing_values, ordered_values]
+
+	sorted_values = numpy.concatenate(parts)
+
+	return sorted_values