numdaplot 0.1.0__py3-none-any.whl

numdaplot/positions/region.py

@@ -0,0 +1,92 @@
+"""
+A rectangular part of an Array or a Table, chosen by position.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.empty_list_error import EmptyListError
+from numdaplot.errors.empty_region_error import EmptyRegionError
+from numdaplot.positions.index import Index
+from numdaplot.positions.range import Range
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.columns.column_names import require_column_names
+
+COLUMN_ITEM_NAME = "column"
+
+
+@dataclass(frozen=True)
+class Region:
+	"""
+	A rectangular part of an Array or a Table, chosen by position, used by ``take`` and ``replace``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	rows
+		The rows to take: one ``Index`` or a ``Range``. Every row when omitted, but a Region needs rows,
+		columns or both.
+	columns
+		The columns to take: one ``Index``, a ``Range``, or a list of column names for a Table.
+		Every column when omitted. The region keeps its own copy of a list of names.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	EmptyRegionError
+		When ``rows`` and ``columns`` are both omitted.
+	EmptyListError
+		When ``columns`` is an empty list.
+	InvalidColumnNameError
+		When a column name is an empty text.
+	DuplicateColumnError
+		When a column name appears twice.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> grid = ndp.Array.from_list([[1, 2, 3], [4, 5, 6]])
+	>>> grid.take(ndp.Region(rows=ndp.Index(0), columns=ndp.Range(start=1, stop=2)))
+	Array([[2, 3]], dtype=INT64)
+	"""
+
+	rows: Index | Range | None = None
+	columns: Index | Range | list[str] | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check the rows and the columns, and replace a list of column names with a copy only the region holds.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		EmptyRegionError
+			When ``rows`` and ``columns`` are both omitted.
+		EmptyListError
+			When ``columns`` is an empty list.
+		InvalidColumnNameError
+			When a column name is an empty text.
+		DuplicateColumnError
+			When a column name appears twice.
+		"""
+		require_field_types(self)
+
+		has_no_position = self.rows is None and self.columns is None
+		if has_no_position:
+			raise EmptyRegionError()
+
+		if not isinstance(self.columns, list):
+			return
+
+		if self.columns == []:
+			raise EmptyListError(COLUMN_ITEM_NAME)
+
+		require_column_names(self.columns)
+		columns_copy = list(self.columns)
+		object.__setattr__(self, "columns", columns_copy)

numdaplot/ratios/__init__.py

@@ -0,0 +1,5 @@
+"""
+Validation of fractions, shared by every numdaplot setting expressed between 0 and 1.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/ratios/fraction.py

@@ -0,0 +1,40 @@
+"""
+Check that a value is a fraction between 0 and 1.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.invalid_fraction_error import InvalidFractionError
+
+MIN_FRACTION = 0.0
+MAX_FRACTION = 1.0
+
+
+def require_fraction(value: float) -> None:
+	"""
+	Check that a value is a fraction between 0 and 1, both included.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		The value to check. NaN is never a fraction.
+
+	Raises
+	------
+	InvalidFractionError
+		When the value is lower than 0, greater than 1 or NaN.
+
+	Examples
+	--------
+	>>> from numdaplot.ratios.fraction import require_fraction
+	>>> require_fraction(0.25)
+	>>> require_fraction(-0.1)
+	Traceback (most recent call last):
+	...
+	numdaplot.errors.invalid_fraction_error.InvalidFractionError: Expected a fraction between 0 and 1, got -0.1.
+	"""
+	is_fraction = MIN_FRACTION <= value <= MAX_FRACTION
+	if not is_fraction:
+		raise InvalidFractionError(value)

numdaplot/ratios/measure.py

@@ -0,0 +1,48 @@
+"""
+How a quantity is measured: as a count or as a fraction of a whole.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class Measure(Enum):
+	"""
+	How a quantity is measured: as a count, or as a fraction of a whole between 0 and 1.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Table.from_arrays({"price": ndp.Array.from_list([12.5, None, 30.0, None])})
+	>>> prices.count_missing(ndp.MissingCount(measure=ndp.Measure.COUNT)).to_value()
+	2
+	>>> prices.count_missing(ndp.MissingCount(measure=ndp.Measure.RATIO)).to_value()
+	0.5
+	"""
+
+	COUNT = auto()
+	"""
+	A number of values. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Table.from_arrays({"price": ndp.Array.from_list([12.5, None, 30.0, None])})
+	>>> prices.count_missing(ndp.MissingCount(measure=ndp.Measure.COUNT)).to_value()
+	2
+	"""
+
+	RATIO = auto()
+	"""
+	A fraction of the values, between 0 and 1.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Table.from_arrays({"price": ndp.Array.from_list([12.5, None, 30.0, None])})
+	>>> prices.count_missing(ndp.MissingCount(measure=ndp.Measure.RATIO)).to_value()
+	0.5
+	"""

numdaplot/rules/__init__.py

@@ -0,0 +1,5 @@
+"""
+Rules that test each value: shared by ``Table.filter``, ``Array.select`` and ``check``.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/rules/between.py

@@ -0,0 +1,78 @@
+"""
+Rule keeping the values inside an interval.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+from datetime import date, datetime, time, timedelta
+
+from numdaplot.errors.invalid_bounds_error import InvalidBoundsError
+from numdaplot.rules.bounds import Bounds
+from numdaplot.rules.rule import Rule
+from numdaplot.settings.field_types import require_field_types
+
+
+# The type parameter has the name of the alias holding the same types: the documentation shows the alias,
+# and both bounds must be of one type.
+@dataclass(frozen=True)
+class Between[OrderedValue: (int, float, str, date, datetime, timedelta, time)](Rule):
+	"""
+	Keep the values inside an interval.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	low
+		Low bound of the interval, an ``OrderedValue`` such as ``10``, ``"A"`` or ``date(2026, 1, 1)``.
+	high
+		High bound of the interval, an ``OrderedValue`` such as ``20``, ``"M"`` or ``date(2026, 12, 31)``, greater than
+		or equal to ``low`` and of a comparable kind.
+	bounds
+		Which bounds are part of the interval. Both are included by default.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidBoundsError
+		When ``low`` is greater than ``high``, or when they cannot be compared,
+		such as a number and a text, or a date and a datetime.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ages = ndp.Array.from_list([8, 10, 15, 20, 31])
+	>>> ages.select(ndp.Between(low=10, high=20))
+	Array([10, 15, 20], dtype=INT64)
+	>>> ages.select(ndp.Between(low=10, high=20, bounds=ndp.Bounds.EXCLUDED))
+	Array([15], dtype=INT64)
+	"""
+
+	low: OrderedValue
+	high: OrderedValue
+	bounds: Bounds = Bounds.INCLUDED
+
+	def __post_init__(self) -> None:
+		"""
+		Check the bounds: 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``, or when they cannot be compared.
+		"""
+		require_field_types(self)
+
+		try:
+			is_reversed = self.low > self.high
+		except TypeError as error:
+			raise InvalidBoundsError(self.low, self.high) from error
+
+		if is_reversed:
+			raise InvalidBoundsError(self.low, self.high)

numdaplot/rules/bounds.py

@@ -0,0 +1,83 @@
+"""
+Which bounds of an interval are part of it.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class Bounds(Enum):
+	"""
+	Which bounds of an interval are part of it, used by ``Between`` and ``Range``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> scores = ndp.Array.from_list([0, 5, 10])
+	>>> scores.select(ndp.Between(low=0, high=10, bounds=ndp.Bounds.LOW_ONLY))
+	Array([0, 5], dtype=INT64)
+	"""
+
+	INCLUDED = auto()
+	"""
+	Both bounds are included: low <= x <= high. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ages = ndp.Array.from_list([10, 15, 20])
+	>>> ages.select(ndp.Between(low=10, high=20, bounds=ndp.Bounds.INCLUDED))
+	Array([10, 15, 20], dtype=INT64)
+	"""
+
+	EXCLUDED = auto()
+	"""
+	Both bounds are excluded: low < x < high.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ages = ndp.Array.from_list([10, 15, 20])
+	>>> ages.select(ndp.Between(low=10, high=20, bounds=ndp.Bounds.EXCLUDED))
+	Array([15], dtype=INT64)
+	"""
+
+	LOW_ONLY = auto()
+	"""
+	Only the low bound is included: low <= x < high.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ages = ndp.Array.from_list([10, 15, 20])
+	>>> ages.select(ndp.Between(low=10, high=20, bounds=ndp.Bounds.LOW_ONLY))
+	Array([10, 15], dtype=INT64)
+	"""
+
+	HIGH_ONLY = auto()
+	"""
+	Only the high bound is included: low < x <= high.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ages = ndp.Array.from_list([10, 15, 20])
+	>>> ages.select(ndp.Between(low=10, high=20, bounds=ndp.Bounds.HIGH_ONLY))
+	Array([15, 20], dtype=INT64)
+	"""
+
+
+LOW_INCLUDED_BOUNDS = frozenset({Bounds.INCLUDED, Bounds.LOW_ONLY})
+"""The bounds settings that include the low bound, or the start of a sequence.
+
+.. versionadded:: 0.1.0
+"""
+
+HIGH_INCLUDED_BOUNDS = frozenset({Bounds.INCLUDED, Bounds.HIGH_ONLY})
+"""The bounds settings that include the high bound, or the end of a sequence.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/rules/case.py

@@ -0,0 +1,48 @@
+"""
+Whether text comparisons distinguish upper and lower case.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class Case(Enum):
+	"""
+	Whether text comparisons distinguish upper and lower case, used by ``Contains``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "PARIS", "Lyon"])
+	>>> cities.select(ndp.Contains("paris", case=ndp.Case.SENSITIVE))
+	Array([], dtype=TEXT)
+	>>> cities.select(ndp.Contains("paris", case=ndp.Case.IGNORED))
+	Array(['Paris', 'PARIS'], dtype=TEXT)
+	"""
+
+	SENSITIVE = auto()
+	"""
+	``"paris"`` does not match ``"Paris"``, as in Python and pandas. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "PARIS", "Lyon"])
+	>>> cities.select(ndp.Contains("Paris", case=ndp.Case.SENSITIVE))
+	Array(['Paris'], dtype=TEXT)
+	"""
+
+	IGNORED = auto()
+	"""
+	``"paris"`` matches ``"Paris"``, ``"PARIS"`` and ``"paris"``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "PARIS", "Lyon"])
+	>>> cities.select(ndp.Contains("Paris", case=ndp.Case.IGNORED))
+	Array(['Paris', 'PARIS'], dtype=TEXT)
+	"""

numdaplot/rules/contains.py

@@ -0,0 +1,63 @@
+"""
+Rule keeping the texts that contain a given text.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.empty_text_error import EmptyTextError
+from numdaplot.rules.case import Case
+from numdaplot.rules.rule import Rule
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class Contains(Rule):
+	"""
+	Keep the texts that contain a given text. Applies to text values only.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	text
+		The text to look for, anywhere in each value. It cannot be empty.
+	case
+		Whether upper and lower case are distinguished. Sensitive by default.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	EmptyTextError
+		When ``text`` is empty.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> emails = ndp.Array.from_list(["ana@shop.fr", "bob@mail.com"])
+	>>> emails.select(ndp.Contains(".fr"))
+	Array(['ana@shop.fr'], dtype=TEXT)
+	"""
+
+	text: str
+	case: Case = Case.SENSITIVE
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the searched text is not empty.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		EmptyTextError
+			When ``text`` is empty.
+		"""
+		require_field_types(self)
+
+		if self.text == "":
+			raise EmptyTextError()

numdaplot/rules/equal.py

@@ -0,0 +1,43 @@
+"""
+Rule keeping the values equal to a reference value.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from numdaplot.rules.rule_values import ScalarValue
+from numdaplot.rules.value_rule import ValueRule
+
+
+@dataclass(frozen=True)
+class Equal(ValueRule[ScalarValue]):
+	"""
+	Keep the values equal to a reference value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		The reference value, a ``ScalarValue`` such as ``"Paris"``, ``10`` or ``True``.
+
+	Raises
+	------
+	RefusedOperationError
+		When ``value`` is None: ``IsMissing`` tests the missing values.
+	InvalidTypeError
+		When ``value`` is not a single value, such as an Array or a list.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> countries = ndp.Array.from_list(["FR", "DE", "FR"])
+	>>> countries.check(ndp.Equal("FR"))
+	Array([ True, False,  True], dtype=BOOL)
+	"""
+
+	MISSING_VALUE_RULE: ClassVar[str | None] = "IsMissing"
+
+	value: ScalarValue

numdaplot/rules/greater.py

@@ -0,0 +1,39 @@
+"""
+Rule keeping the values strictly greater than a reference value.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.rules.rule_values import OrderedValue
+from numdaplot.rules.value_rule import ValueRule
+
+
+@dataclass(frozen=True)
+class Greater(ValueRule[OrderedValue]):
+	"""
+	Keep the values strictly greater than a reference value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		The reference value, an ``OrderedValue`` such as ``10``, ``"M"`` or ``date(2026, 1, 31)``, which is not
+		kept itself.
+
+	Raises
+	------
+	InvalidTypeError
+		When ``value`` is not a single value, such as an Array or a list.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([80, 100, 120])
+	>>> prices.select(ndp.Greater(100))
+	Array([120], dtype=INT64)
+	"""
+
+	value: OrderedValue

numdaplot/rules/greater_or_equal.py

@@ -0,0 +1,38 @@
+"""
+Rule keeping the values greater than or equal to a reference value.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.rules.rule_values import OrderedValue
+from numdaplot.rules.value_rule import ValueRule
+
+
+@dataclass(frozen=True)
+class GreaterOrEqual(ValueRule[OrderedValue]):
+	"""
+	Keep the values greater than or equal to a reference value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		The reference value, an ``OrderedValue`` such as ``10``, ``"M"`` or ``date(2026, 1, 31)``, which is kept itself.
+
+	Raises
+	------
+	InvalidTypeError
+		When ``value`` is not a single value, such as an Array or a list.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([80, 100, 120])
+	>>> prices.select(ndp.GreaterOrEqual(100))
+	Array([100, 120], dtype=INT64)
+	"""
+
+	value: OrderedValue

numdaplot/rules/is_in.py

@@ -0,0 +1,67 @@
+"""
+Rule keeping the values that belong to a list.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+from datetime import date, datetime, time, timedelta
+
+from numdaplot.errors.empty_values_error import EmptyValuesError
+from numdaplot.rules.rule import Rule
+from numdaplot.settings.field_types import require_field_types
+
+
+# The type parameter has the name of the alias holding the same types: the documentation shows the alias,
+# and every accepted value must be of one type.
+@dataclass(frozen=True)
+class IsIn[ScalarValue: (bool, int, float, str, date, datetime, timedelta, time)](Rule):
+	"""
+	Keep the values that belong to a list of accepted values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The accepted values, a list of ``ScalarValue`` such as ``["Paris", "Lyon"]`` or ``[1, 2]``, at least one and
+		all of the same kind. The rule keeps its own copy, so changing the list afterwards does not change the rule.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	EmptyValuesError
+		When ``values`` is empty.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> countries = ndp.Array.from_list(["FR", "US", "DE"])
+	>>> countries.select(ndp.IsIn(["FR", "DE"]))
+	Array(['FR', 'DE'], dtype=TEXT)
+	"""
+
+	values: list[ScalarValue]
+
+	def __post_init__(self) -> None:
+		"""
+		Check the list and its values, then replace it with a copy that only the rule holds.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		EmptyValuesError
+			When ``values`` is empty.
+		"""
+		require_field_types(self)
+
+		value_count = len(self.values)
+		if value_count == 0:
+			raise EmptyValuesError()
+
+		values_copy = list(self.values)
+		object.__setattr__(self, "values", values_copy)

numdaplot/rules/is_missing.py

@@ -0,0 +1,25 @@
+"""
+Rule keeping the missing values.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.rules.rule import Rule
+
+
+@dataclass(frozen=True)
+class IsMissing(Rule):
+	"""
+	Keep the missing values, whatever their type: NaN, ``pd.NA`` or ``NaT``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> temperatures = ndp.Array.from_list([12.5, None, 18.0])
+	>>> temperatures.check(ndp.IsMissing())
+	Array([False,  True, False], dtype=BOOL)
+	"""