numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/columns/brackets.py

@@ -0,0 +1,234 @@
+"""
+Brackets cutting a number column into categories.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.arrays.mapping.unmatched import Unmatched
+from numdaplot.errors.duplicate_label_error import DuplicateLabelError
+from numdaplot.errors.empty_list_error import EmptyListError
+from numdaplot.errors.invalid_label_count_error import InvalidLabelCountError
+from numdaplot.errors.invalid_limits_error import InvalidLimitsError
+from numdaplot.errors.refused_setting_error import RefusedSettingError
+from numdaplot.rules.bounds import Bounds
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.columns.bracket_end import BracketEnd
+
+LIMIT_ITEM_NAME = "limit"
+BRACKETS_NAME = "Brackets"
+ACCEPTED_BOUNDS = frozenset({Bounds.LOW_ONLY, Bounds.HIGH_ONLY})
+REFUSED_BOUNDS_NAME = "Bounds.{bounds_name}"
+
+
+@dataclass(frozen=True)
+class Brackets:
+	"""
+	Brackets cutting a number column into categories, used as the ``format`` of a ``Conversion`` to ``CATEGORY``.
+
+	The categories keep the order of the brackets, so that sorting and plots follow it. A missing value stays missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	limits
+		The limits between the brackets, at least one, in strictly increasing order. Two limits make one bracket.
+	bounds
+		Which limit of each bracket it holds: ``Bounds.LOW_ONLY`` by default, ``0 <= x < 10``, or
+		``Bounds.HIGH_ONLY``, ``0 < x <= 10``. The other members are refused, as they would put a value in two
+		brackets or in none.
+	labels
+		The name of each bracket, in order. When omitted, each name gives the values the bracket holds: ``0 to 9`` for
+		integers, ``0 to under 10`` for decimals, ``80 or more`` or ``under 0`` for an open bracket. Whole limits are
+		written without decimals.
+	first
+		Whether the first bracket stops at the first limit, ``BracketEnd.CLOSED`` by default, or holds every value
+		below it with ``BracketEnd.OPEN``.
+	last
+		Whether the last bracket stops at the last limit, ``BracketEnd.CLOSED`` by default, or holds every value
+		above it with ``BracketEnd.OPEN``.
+	others
+		What happens to a value in no bracket, ``Unmatched.ERROR`` by default.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	EmptyListError
+		When ``limits`` is an empty list.
+	RefusedSettingError
+		When ``bounds`` is ``Bounds.INCLUDED`` or ``Bounds.EXCLUDED``.
+	InvalidLimitsError
+		When the limits do not strictly increase, or a single limit has no open end.
+	InvalidLabelCountError
+		When ``labels`` does not give one name per bracket.
+	DuplicateLabelError
+		When a label appears twice.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ages = ndp.Array.from_list([4, 17, 30, 92])
+	>>> victims = ndp.Table.from_arrays({"age": ages})
+	>>> brackets = ndp.Brackets(limits=[0, 10, 20], last=ndp.BracketEnd.OPEN)
+	>>> victims.convert(ndp.Conversion(column="age", dtype=ndp.Type.CATEGORY, format=brackets))
+	          age
+	     CATEGORY
+	0      0 to 9
+	1    10 to 19
+	2  20 or more
+	3  20 or more
+	"""
+
+	limits: list[int | float]
+	bounds: Bounds = Bounds.LOW_ONLY
+	labels: list[str] | None = None
+	first: BracketEnd = BracketEnd.CLOSED
+	last: BracketEnd = BracketEnd.CLOSED
+	others: Unmatched = Unmatched.ERROR
+
+	def __post_init__(self) -> None:
+		"""
+		Check the limits, the bounds and the labels.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		EmptyListError
+			When ``limits`` is an empty list.
+		RefusedSettingError
+			When ``bounds`` is ``Bounds.INCLUDED`` or ``Bounds.EXCLUDED``.
+		InvalidLimitsError
+			When the limits do not strictly increase, or a single limit has no open end.
+		InvalidLabelCountError
+			When ``labels`` does not give one name per bracket.
+		DuplicateLabelError
+			When a label appears twice.
+		"""
+		require_field_types(self)
+
+		if self.limits == []:
+			raise EmptyListError(LIMIT_ITEM_NAME)
+
+		if self.bounds not in ACCEPTED_BOUNDS:
+			bounds_name = REFUSED_BOUNDS_NAME.format(bounds_name=self.bounds.name)
+			raise RefusedSettingError(bounds_name, BRACKETS_NAME)
+
+		require_increasing_limits(self.limits)
+		bracket_count = self.count_brackets()
+		if bracket_count == 0:
+			raise InvalidLimitsError(self.limits)
+
+		if self.labels is not None:
+			require_bracket_labels(self.labels, bracket_count)
+			labels_copy = list(self.labels)
+			object.__setattr__(self, "labels", labels_copy)
+
+		limits_copy = list(self.limits)
+		object.__setattr__(self, "limits", limits_copy)
+
+	def count_brackets(self) -> int:
+		"""
+		Return the number of brackets: one between two limits, plus one per open end.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		int
+			The number of brackets.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.Brackets(limits=[0, 18, 65], last=ndp.BracketEnd.OPEN).count_brackets()
+		3
+		"""
+		limit_count = len(self.limits)
+		bracket_count = limit_count - 1
+		if self.first == BracketEnd.OPEN:
+			bracket_count += 1
+
+		if self.last == BracketEnd.OPEN:
+			bracket_count += 1
+
+		return bracket_count
+
+
+def require_increasing_limits(limits: list[int | float]) -> None:
+	"""
+	Check that each limit is greater than the one before.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	limits
+		The limits of brackets.
+
+	Raises
+	------
+	InvalidLimitsError
+		When a limit is not greater than the one before, or is NaN.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.brackets import require_increasing_limits
+	>>> try:
+	... 	require_increasing_limits([20, 10])
+	... except ndp.InvalidLimitsError as error:
+	... 	print(error)
+	Expected limits in strictly increasing order, got 10 after 20.
+	"""
+	for earlier_limit, later_limit in zip(limits, limits[1:], strict=False):
+		is_greater = later_limit > earlier_limit
+		if not is_greater:
+			raise InvalidLimitsError(limits)
+
+
+def require_bracket_labels(labels: list[str], bracket_count: int) -> None:
+	"""
+	Check that the labels give one distinct name per bracket.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	labels
+		The names of the brackets.
+	bracket_count
+		The number of brackets.
+
+	Raises
+	------
+	InvalidLabelCountError
+		When there is not one label per bracket.
+	DuplicateLabelError
+		At the first label given twice.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.brackets import require_bracket_labels
+	>>> try:
+	... 	require_bracket_labels(["child", "child"], 2)
+	... except ndp.DuplicateLabelError as error:
+	... 	print(error)
+	The label 'child' appears more than once.
+	"""
+	label_count = len(labels)
+	if label_count != bracket_count:
+		raise InvalidLabelCountError(bracket_count, label_count)
+
+	seen_labels = set[str]()
+	for label in labels:
+		if label in seen_labels:
+			raise DuplicateLabelError(label)
+
+		seen_labels.add(label)

numdaplot/tables/columns/chosen_columns.py

@@ -0,0 +1,55 @@
+"""
+Choice of the columns of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+import pandas
+
+from numdaplot.tables.columns.column_choice import ColumnChoice
+from numdaplot.tables.columns.column_mode import ColumnMode
+from numdaplot.tables.columns.column_names import require_known_columns
+
+
+def choose_frame_columns(frame: pandas.DataFrame, choice: ColumnChoice) -> pandas.DataFrame:
+	"""
+	Return the columns of a Table that a choice keeps.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	choice
+		The columns, and whether to keep or drop them.
+
+	Returns
+	-------
+	pandas.DataFrame
+		With ``KEEP``, the named columns in the order of the list; with ``DROP``, the other columns in their order.
+
+	Raises
+	------
+	ColumnNotFoundError
+		When a named column does not exist.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.chosen_columns import choose_frame_columns
+	>>> frame = pandas.DataFrame({"city": ["Pau"], "price": [1.5]})
+	>>> choose_frame_columns(frame, ndp.ColumnChoice(columns=["price", "city"]))
+	   price city
+	0    1.5  Pau
+	"""
+	column_names = [str(column_name) for column_name in frame.columns]
+	require_known_columns(choice.columns, column_names)
+	if choice.mode == ColumnMode.DROP:
+		remaining_frame = frame.drop(columns=choice.columns)
+		return remaining_frame
+
+	kept_frame = frame.loc[:, choice.columns]
+
+	return kept_frame

numdaplot/tables/columns/column_choice.py

@@ -0,0 +1,84 @@
+"""
+Settings of the choice of the columns of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.empty_list_error import EmptyListError
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.columns.column_mode import ColumnMode
+from numdaplot.tables.columns.column_names import require_column_names
+
+COLUMN_ITEM_NAME = "column"
+
+
+@dataclass(frozen=True)
+class ColumnChoice:
+	"""
+	Columns to keep or to drop, used by ``Table.choose_columns``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	columns
+		The names of the columns. The choice keeps its own copy of the list.
+	mode
+		``KEEP`` by default, keeping only these columns, in the order of the list, or ``DROP`` to remove them.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	EmptyListError
+		When ``columns`` is empty with ``KEEP``, which would keep nothing.
+	InvalidColumnNameError
+		When a column name is an empty text.
+	DuplicateColumnError
+		When a column name appears twice.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Paris"])
+	>>> prices = ndp.Array.from_list([120.0, 80.0, 150.0])
+	>>> sales = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> sales.choose_columns(ndp.ColumnChoice(columns=["price"]))
+	    price
+	  FLOAT64
+	0   120.0
+	1    80.0
+	2   150.0
+	"""
+
+	columns: list[str]
+	mode: ColumnMode = ColumnMode.KEEP
+
+	def __post_init__(self) -> None:
+		"""
+		Check the columns and replace them with a copy that only the choice holds.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		EmptyListError
+			When ``columns`` is empty with ``KEEP``.
+		InvalidColumnNameError
+			When a column name is an empty text.
+		DuplicateColumnError
+			When a column name appears twice.
+		"""
+		require_field_types(self)
+
+		keeps_nothing = self.columns == [] and self.mode == ColumnMode.KEEP
+		if keeps_nothing:
+			raise EmptyListError(COLUMN_ITEM_NAME)
+
+		require_column_names(self.columns)
+		columns_copy = list(self.columns)
+		object.__setattr__(self, "columns", columns_copy)

numdaplot/tables/columns/column_mode.py

@@ -0,0 +1,64 @@
+"""
+Whether a ColumnChoice keeps or drops its columns.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class ColumnMode(Enum):
+	"""
+	Whether a ``ColumnChoice`` keeps or drops the columns it names.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Paris"])
+	>>> prices = ndp.Array.from_list([120.0, 80.0, 150.0])
+	>>> sales = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> sales.choose_columns(ndp.ColumnChoice(columns=["price"], mode=ndp.ColumnMode.DROP))
+	    city
+	    TEXT
+	0  Paris
+	1   Lyon
+	2  Paris
+	"""
+
+	KEEP = auto()
+	"""
+	Only the named columns remain, in the order of the list. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Paris"])
+	>>> prices = ndp.Array.from_list([120.0, 80.0, 150.0])
+	>>> sales = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> sales.choose_columns(ndp.ColumnChoice(columns=["price"], mode=ndp.ColumnMode.KEEP))
+	    price
+	  FLOAT64
+	0   120.0
+	1    80.0
+	2   150.0
+	"""
+
+	DROP = auto()
+	"""
+	The named columns are removed, the others keep their order.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Paris"])
+	>>> prices = ndp.Array.from_list([120.0, 80.0, 150.0])
+	>>> sales = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> sales.choose_columns(ndp.ColumnChoice(columns=["price"], mode=ndp.ColumnMode.DROP))
+	    city
+	    TEXT
+	0  Paris
+	1   Lyon
+	2  Paris
+	"""

numdaplot/tables/columns/column_names.py

@@ -0,0 +1,186 @@
+"""
+Checks of the column names of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from collections.abc import Sequence
+
+from numdaplot.errors.column_not_found_error import ColumnNotFoundError
+from numdaplot.errors.duplicate_column_error import DuplicateColumnError
+from numdaplot.errors.invalid_column_name_error import InvalidColumnNameError
+
+
+def require_column_name(column_name: object) -> None:
+	"""
+	Check that a column name is a non-empty text.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column_name
+		The name to check.
+
+	Raises
+	------
+	InvalidColumnNameError
+		When the name is not a text, or is empty.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.column_names import require_column_name
+	>>> try:
+	... 	require_column_name(2024)
+	... except ndp.InvalidColumnNameError as error:
+	... 	print(error)
+	Expected a column name as a non-empty text, got 2024.
+	"""
+	is_text = isinstance(column_name, str)
+	if not is_text:
+		raise InvalidColumnNameError(column_name)
+
+	if column_name == "":
+		raise InvalidColumnNameError(column_name)
+
+
+def require_optional_column_name(column_name: object) -> None:
+	"""
+	Check that a column name, when given, is a non-empty text.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column_name
+		The name to check, or None when the setting is omitted.
+
+	Raises
+	------
+	InvalidColumnNameError
+		When the name is given and is not a non-empty text.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.column_names import require_optional_column_name
+	>>> require_optional_column_name(None)
+	>>> try:
+	... 	require_optional_column_name("")
+	... except ndp.InvalidColumnNameError as error:
+	... 	print(error)
+	Expected a column name as a non-empty text, got ''.
+	"""
+	if column_name is None:
+		return
+
+	require_column_name(column_name)
+
+
+def require_unique_names(column_names: Sequence[str]) -> None:
+	"""
+	Check that no column name appears twice.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column_names
+		The names to check.
+
+	Raises
+	------
+	DuplicateColumnError
+		At the first name that appears a second time.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.column_names import require_unique_names
+	>>> try:
+	... 	require_unique_names(["city", "price", "city"])
+	... except ndp.DuplicateColumnError as error:
+	... 	print(error)
+	The column name 'city' appears more than once.
+	"""
+	seen_names = set[str]()
+
+	for column_name in column_names:
+		if column_name in seen_names:
+			raise DuplicateColumnError(column_name)
+
+		seen_names.add(column_name)
+
+
+def require_column_names(column_names: Sequence[object]) -> None:
+	"""
+	Check that every column name is a non-empty text and appears once.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column_names
+		The names to check, such as the header of a file.
+
+	Raises
+	------
+	InvalidColumnNameError
+		At the first name that is not a non-empty text.
+	DuplicateColumnError
+		At the first name that appears a second time.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.column_names import require_column_names
+	>>> try:
+	... 	require_column_names(["city", ""])
+	... except ndp.InvalidColumnNameError as error:
+	... 	print(error)
+	Expected a column name as a non-empty text, got ''.
+	"""
+	text_names = list[str]()
+
+	for column_name in column_names:
+		require_column_name(column_name)
+		text_name = str(column_name)
+		text_names.append(text_name)
+
+	require_unique_names(text_names)
+
+
+def require_known_columns(requested_names: Sequence[str], column_names: Sequence[str]) -> None:
+	"""
+	Check that every requested column exists.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	requested_names
+		The names given by the user.
+	column_names
+		The names of the columns of the Table.
+
+	Raises
+	------
+	ColumnNotFoundError
+		At the first requested name that matches no column.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.column_names import require_known_columns
+	>>> try:
+	... 	require_known_columns(["prise"], ["city", "price"])
+	... except ndp.ColumnNotFoundError as error:
+	... 	print(error)
+	No column is named 'prise'.
+	"""
+	known_names = set(column_names)
+
+	for requested_name in requested_names:
+		if requested_name not in known_names:
+			raise ColumnNotFoundError(requested_name)