numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/joining/join_keys.py

@@ -0,0 +1,367 @@
+"""
+Checks and alignment of the key columns of a join.
+
+.. versionadded:: 0.1.0
+"""
+
+import numpy
+import pandas
+
+from numdaplot.data_types.numpy_mapping import from_numpy_dtype, to_numpy_dtype
+from numdaplot.data_types.pandas_mapping import to_pandas_dtype
+from numdaplot.data_types.type import Type
+from numdaplot.data_types.value_family import ValueFamily, find_family
+from numdaplot.errors.column_not_found_error import ColumnNotFoundError
+from numdaplot.errors.incompatible_types_error import IncompatibleTypesError
+from numdaplot.errors.time_zone_mismatch_error import TimeZoneMismatchError
+from numdaplot.tables.columns.column_names import require_known_columns
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.frames.column_values import find_column_type
+from numdaplot.tables.frames.named_column_errors import NamedColumnErrors
+from numdaplot.tables.frames.time_zones import find_column_time_zone
+from numdaplot.tables.joining.key_types import KeyTypes
+
+OTHER_TABLE_NAME = "the other Table"
+JOIN_OPERATION = "Join"
+KEY_OPERATION = "Joining on {key_name!r}"
+FLOAT_DTYPE = numpy.dtype(numpy.float64)
+
+
+def align_key_frames(
+	frame: pandas.DataFrame, other_frame: pandas.DataFrame, keys: list[str], key_types: KeyTypes
+) -> tuple[pandas.DataFrame, pandas.DataFrame]:
+	"""
+	Return the key columns of both Tables of a join, each key converted to one type on both sides.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of the joined Table.
+	other_frame
+		The columns of the other Table.
+	keys
+		The names of the key columns.
+	key_types
+		How close the types of each key must be.
+
+	Returns
+	-------
+	tuple[pandas.DataFrame, pandas.DataFrame]
+		The key columns of the joined Table and of the other Table, of the same types.
+
+	Raises
+	------
+	ColumnNotFoundError
+		When a key is missing from one of the Tables.
+	IncompatibleTypesError
+		When the two columns of a key are of different families, of different types with ``KeyTypes.SAME_TYPE``, or
+		a date and a datetime.
+	TimeZoneMismatchError
+		When the two columns of a key hold datetimes of different time zones, or with and without one.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.joining.join_keys import align_key_frames
+	>>> frame = pandas.DataFrame({"id": pandas.array([1, 2], dtype="Int64")})
+	>>> other_frame = pandas.DataFrame({"id": [1.0, 2.5]})
+	>>> key_frame, other_key_frame = align_key_frames(frame, other_frame, ["id"], ndp.KeyTypes.SAME_FAMILY)
+	>>> key_frame["id"].tolist()
+	[1.0, 2.0]
+	"""
+	column_names = frame.columns.tolist()
+	other_names = other_frame.columns.tolist()
+	require_known_columns(keys, column_names)
+	require_other_keys(keys, other_names)
+	key_columns = dict[str, Column]()
+	other_key_columns = dict[str, Column]()
+
+	for key_name in keys:
+		column = frame[key_name]
+		other_column = other_frame[key_name]
+		key_type = find_key_type(column, other_column, key_types)
+		key_column = convert_key_column(column, key_type)
+		other_key_column = convert_key_column(other_column, key_type)
+		key_columns[key_name] = key_column
+		other_key_columns[key_name] = other_key_column
+
+	key_frame = pandas.DataFrame(key_columns)
+	other_key_frame = pandas.DataFrame(other_key_columns)
+
+	return key_frame, other_key_frame
+
+
+def require_other_keys(keys: list[str], other_names: list[str]) -> None:
+	"""
+	Check that the other Table of a join has every key column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	keys
+		The names of the key columns.
+	other_names
+		The column names of the other Table.
+
+	Raises
+	------
+	ColumnNotFoundError
+		At the first key the other Table does not have, naming it.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.joining.join_keys import require_other_keys
+	>>> try:
+	... 	require_other_keys(["Num_Acc"], ["num_acc"])
+	... except ndp.ColumnNotFoundError as error:
+	... 	print(error)
+	No column of the other Table is named 'Num_Acc'.
+	"""
+	known_names = set(other_names)
+
+	for key_name in keys:
+		if key_name not in known_names:
+			raise ColumnNotFoundError(key_name, OTHER_TABLE_NAME)
+
+
+def find_key_type(column: Column, other_column: Column, key_types: KeyTypes) -> Type:
+	"""
+	Return the type both columns of a key take for the join.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		The key column of the joined Table.
+	other_column
+		The key column of the other Table.
+	key_types
+		How close their types must be.
+
+	Returns
+	-------
+	Type
+		Their type when they share it, except categories of different categories, which give ``TEXT``. Otherwise
+		the number type holding both, or ``TEXT`` for a text and a category.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the columns are of different families, of different types with ``KeyTypes.SAME_TYPE``, or a date and
+		a datetime.
+	TimeZoneMismatchError
+		When the columns hold datetimes of different time zones, or with and without one.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.joining.join_keys import find_key_type
+	>>> integers = pandas.Series([1], dtype="Int32")
+	>>> find_key_type(integers, pandas.Series([1], dtype="Int64"), ndp.KeyTypes.SAME_FAMILY)
+	<Type.INT64: 4>
+	"""
+	column_type = find_column_type(column)
+	other_type = find_column_type(other_column)
+	require_key_types(column, column_type, other_type, key_types)
+	require_same_time_zone(column, other_column)
+	if column_type == other_type:
+		shared_type = find_shared_key_type(column, other_column, column_type)
+		return shared_type
+
+	family = find_family(column_type)
+	if family == ValueFamily.TEXT:
+		return Type.TEXT
+
+	numpy_dtype = to_numpy_dtype(column_type)
+	other_numpy_dtype = to_numpy_dtype(other_type)
+	common_numpy_dtype = numpy.result_type(numpy_dtype, other_numpy_dtype)
+	common_type = from_numpy_dtype(common_numpy_dtype)
+
+	return common_type
+
+
+def require_key_types(column: Column, column_type: Type, other_type: Type, key_types: KeyTypes) -> None:
+	"""
+	Check that the two columns of a key can match.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		The key column of the joined Table, named in the error message.
+	column_type
+		Its type.
+	other_type
+		The type of the key column of the other Table.
+	key_types
+		How close the types must be.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the types are of different families, different with ``KeyTypes.SAME_TYPE``, or a date and a datetime,
+		whose family is the same.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.joining.join_keys import require_key_types
+	>>> days = pandas.Series(pandas.to_datetime(["2026-01-01"]), name="day").astype("datetime64[s]")
+	>>> try:
+	... 	require_key_types(days, ndp.Type.DATE, ndp.Type.DATETIME, ndp.KeyTypes.SAME_FAMILY)
+	... except ndp.IncompatibleTypesError as error:
+	... 	print(error)
+	Cannot apply Join to the DATE column 'day' and DATETIME.
+	"""
+	if column_type == other_type:
+		return
+
+	family = find_family(column_type)
+	other_family = find_family(other_type)
+	is_same_family = family == other_family
+	is_moment = family == ValueFamily.MOMENT
+	needs_same_type = key_types == KeyTypes.SAME_TYPE
+	can_match = is_same_family and not is_moment and not needs_same_type
+	if can_match:
+		return
+
+	with NamedColumnErrors(column):
+		raise IncompatibleTypesError(JOIN_OPERATION, [column_type.name, other_type.name])
+
+
+def require_same_time_zone(column: Column, other_column: Column) -> None:
+	"""
+	Check that the two columns of a key hold datetimes of the same time zone, or both without one.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		The key column of the joined Table, named in the error message.
+	other_column
+		The key column of the other Table.
+
+	Raises
+	------
+	TimeZoneMismatchError
+		When only one has a time zone, naming the state the other column needs, or their time zones differ: change
+		them first with ``TimeZoneChange``.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.joining.join_keys import require_same_time_zone
+	>>> utc_times = pandas.Series(pandas.to_datetime(["2026-07-01 10:30"]), name="time").dt.tz_localize("UTC")
+	>>> try:
+	... 	require_same_time_zone(utc_times, utc_times.dt.tz_convert("Europe/Paris"))
+	... except ndp.TimeZoneMismatchError as error:
+	... 	print(error)
+	Joining on 'time' needs datetimes in one time zone, got UTC and Europe/Paris.
+	"""
+	time_zone = find_column_time_zone(column)
+	other_time_zone = find_column_time_zone(other_column)
+	if time_zone == other_time_zone:
+		return
+
+	operation = KEY_OPERATION.format(key_name=column.name)
+	if time_zone is None:
+		raise TimeZoneMismatchError(operation, False)
+
+	if other_time_zone is None:
+		raise TimeZoneMismatchError(operation, True)
+
+	zone_names = [time_zone.name, other_time_zone.name]
+	raise TimeZoneMismatchError(operation, True, zone_names)
+
+
+def find_shared_key_type(column: Column, other_column: Column, key_type: Type) -> Type:
+	"""
+	Return the type of a key whose two columns have the same type.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		The key column of the joined Table.
+	other_column
+		The key column of the other Table.
+	key_type
+		Their type.
+
+	Returns
+	-------
+	Type
+		The type itself, or ``TEXT`` for two categories that do not have the same categories.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.joining.join_keys import find_shared_key_type
+	>>> paris = pandas.Series(["Paris"], dtype="category")
+	>>> find_shared_key_type(paris, pandas.Series(["Lyon"], dtype="category"), ndp.Type.CATEGORY)
+	<Type.TEXT: 12>
+	"""
+	if key_type != Type.CATEGORY:
+		return key_type
+
+	categories = column.cat.categories
+	other_categories = other_column.cat.categories
+	has_same_categories = categories.equals(other_categories)
+	if has_same_categories:
+		return key_type
+
+	return Type.TEXT
+
+
+def convert_key_column(column: Column, key_type: Type) -> Column:
+	"""
+	Return a key column converted to the type both sides of the key take.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A key column.
+	key_type
+		The type of the key for the join.
+
+	Returns
+	-------
+	Column
+		The column itself when it has that type, otherwise a converted copy, missing values staying missing.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.joining.join_keys import convert_key_column
+	>>> convert_key_column(pandas.Series([1, None], dtype="Int64"), ndp.Type.FLOAT64).tolist()
+	[1.0, nan]
+	"""
+	column_type = find_column_type(column)
+	if column_type == key_type:
+		return column
+
+	if key_type == Type.FLOAT64:
+		numbers = column.to_numpy(dtype=FLOAT_DTYPE, na_value=numpy.nan)
+		number_column = pandas.Series(numbers, name=column.name)
+		return number_column
+
+	key_dtype = to_pandas_dtype(key_type)
+	converted_column = column.astype(key_dtype)
+
+	return converted_column

numdaplot/tables/joining/join_mode.py

@@ -0,0 +1,93 @@
+"""
+Which rows a join of two Tables keeps.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class JoinMode(Enum):
+	"""
+	Which rows a join keeps, used by ``Join``: the rows of both Tables whose keys match, and the rows left alone.
+
+	A row whose keys match several rows of the other Table appears once per match. A missing key never matches.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> accidents = ndp.Table.from_arrays({"id": ndp.Array.from_list([1, 2]), "dep": ndp.Array.from_list(["75", "69"])})
+	>>> users = ndp.Table.from_arrays({"id": ndp.Array.from_list([1, 3]), "age": ndp.Array.from_list([34, 51])})
+	>>> accidents.join(ndp.Join(other=users, keys=["id"], mode=ndp.JoinMode.OUTER))
+	     id  dep   age
+	  INT64 TEXT INT64
+	0     1   75    34
+	1     2   69  <NA>
+	2     3 <NA>    51
+	"""
+
+	INNER = auto()
+	"""
+	Only the rows whose keys match a row of the other Table. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> accidents = ndp.Table.from_arrays({"id": ndp.Array.from_list([1, 2]), "dep": ndp.Array.from_list(["75", "69"])})
+	>>> users = ndp.Table.from_arrays({"id": ndp.Array.from_list([1, 3]), "age": ndp.Array.from_list([34, 51])})
+	>>> accidents.join(ndp.Join(other=users, keys=["id"], mode=ndp.JoinMode.INNER))
+	     id dep   age
+	  INT64 TEXT INT64
+	0     1  75    34
+	"""
+
+	LEFT = auto()
+	"""
+	Every row of the joined Table, with missing values where the other Table has no match.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> accidents = ndp.Table.from_arrays({"id": ndp.Array.from_list([1, 2]), "dep": ndp.Array.from_list(["75", "69"])})
+	>>> users = ndp.Table.from_arrays({"id": ndp.Array.from_list([1, 3]), "age": ndp.Array.from_list([34, 51])})
+	>>> accidents.join(ndp.Join(other=users, keys=["id"], mode=ndp.JoinMode.LEFT))
+	     id  dep   age
+	  INT64 TEXT INT64
+	0     1   75    34
+	1     2   69  <NA>
+	"""
+
+	RIGHT = auto()
+	"""
+	Every row of the other Table, with missing values where the joined Table has no match.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> accidents = ndp.Table.from_arrays({"id": ndp.Array.from_list([1, 2]), "dep": ndp.Array.from_list(["75", "69"])})
+	>>> users = ndp.Table.from_arrays({"id": ndp.Array.from_list([1, 3]), "age": ndp.Array.from_list([34, 51])})
+	>>> accidents.join(ndp.Join(other=users, keys=["id"], mode=ndp.JoinMode.RIGHT))
+	     id  dep   age
+	  INT64 TEXT INT64
+	0     1   75    34
+	1     3 <NA>    51
+	"""
+
+	OUTER = auto()
+	"""
+	Every row of both Tables, with missing values where one has no match.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> accidents = ndp.Table.from_arrays({"id": ndp.Array.from_list([1, 2]), "dep": ndp.Array.from_list(["75", "69"])})
+	>>> users = ndp.Table.from_arrays({"id": ndp.Array.from_list([1, 3]), "age": ndp.Array.from_list([34, 51])})
+	>>> accidents.join(ndp.Join(other=users, keys=["id"], mode=ndp.JoinMode.OUTER))
+	     id  dep   age
+	  INT64 TEXT INT64
+	0     1   75    34
+	1     2   69  <NA>
+	2     3 <NA>    51
+	"""

numdaplot/tables/joining/join_relation.py

@@ -0,0 +1,149 @@
+"""
+Check of the number of times each key appears in the Tables of a join.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import pandas
+
+from numdaplot.arrays.conversion.python_values import to_python_list
+from numdaplot.errors.join_relation_error import JoinRelationError
+from numdaplot.errors.repeated_key import RepeatedKey
+from numdaplot.tables.frames.column_values import convert_column_values
+from numdaplot.tables.joining.relation import Relation
+
+UNIQUE_LEFT_RELATIONS = frozenset({Relation.ONE_TO_ONE, Relation.ONE_TO_MANY})
+UNIQUE_RIGHT_RELATIONS = frozenset({Relation.ONE_TO_ONE, Relation.MANY_TO_ONE})
+LEFT_TABLE_NAME = "the left Table"
+RIGHT_TABLE_NAME = "the right Table"
+RELATION_NAME = "Relation.{member_name}"
+ROWS_AXIS = 1
+EVERY_REPEAT = False
+FIRST_ROW_COUNT = 1
+
+
+def require_relation(key_frame: pandas.DataFrame, other_key_frame: pandas.DataFrame, relation: Relation) -> None:
+	"""
+	Check that each key appears at most once in the Tables where the relation of a join expects it once.
+
+	The left Table is checked first, then the right Table.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	key_frame
+		The key columns of the left Table, the one joined.
+	other_key_frame
+		The key columns of the right Table, the other one.
+	relation
+		How many times each key may appear on each side.
+
+	Raises
+	------
+	JoinRelationError
+		At the first key repeated in a Table where the relation expects it once.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.joining.join_relation import require_relation
+	>>> key_frame = pandas.DataFrame({"id": pandas.Series([1], dtype="Int64")})
+	>>> other_key_frame = pandas.DataFrame({"id": pandas.Series([1, 1], dtype="Int64")})
+	>>> try:
+	... 	require_relation(key_frame, other_key_frame, ndp.Relation.ONE_TO_ONE)
+	... except ndp.JoinRelationError as error:
+	... 	print(error)
+	Expected each key of the right Table to appear once for Relation.ONE_TO_ONE, but 'id' 1 appears 2 times.
+	"""
+	if relation in UNIQUE_LEFT_RELATIONS:
+		require_unique_keys(key_frame, relation, LEFT_TABLE_NAME)
+
+	if relation in UNIQUE_RIGHT_RELATIONS:
+		require_unique_keys(other_key_frame, relation, RIGHT_TABLE_NAME)
+
+
+def require_unique_keys(key_frame: pandas.DataFrame, relation: Relation, table_name: str) -> None:
+	"""
+	Check that each key, or combination of keys, appears at most once in a Table, missing keys aside.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	key_frame
+		The key columns of a Table.
+	relation
+		The relation checked, named in the error message.
+	table_name
+		The Table checked, named in the error message.
+
+	Raises
+	------
+	JoinRelationError
+		At the first repeated key, in the order of the rows, with its number of rows.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.joining.join_relation import require_unique_keys
+	>>> key_frame = pandas.DataFrame({"id": pandas.Series([1, None, None], dtype="Int64")})
+	>>> require_unique_keys(key_frame, ndp.Relation.ONE_TO_ONE, "the left Table")
+	"""
+	missing_keys = key_frame.isna()
+	has_missing_key = missing_keys.any(axis=ROWS_AXIS)
+	present_frame = key_frame[~has_missing_key]
+	repeated_rows = present_frame.duplicated(keep=EVERY_REPEAT)
+	has_repeat = bool(repeated_rows.any())
+	if not has_repeat:
+		return
+
+	repeated_frame = present_frame[repeated_rows]
+	first_repeat_frame = repeated_frame.iloc[:FIRST_ROW_COUNT]
+	first_repeat = first_repeat_frame.iloc[0]
+	matching_cells = present_frame == first_repeat
+	matching_rows = matching_cells.all(axis=ROWS_AXIS)
+	repeat_count = int(matching_rows.sum())
+	key_names = key_frame.columns.tolist()
+	key_values = read_key_values(first_repeat_frame)
+	repeated_key = RepeatedKey(key_names, key_values, repeat_count)
+	relation_name = RELATION_NAME.format(member_name=relation.name)
+	raise JoinRelationError(relation_name, table_name, repeated_key)
+
+
+def read_key_values(key_row_frame: pandas.DataFrame) -> list[Any]:
+	"""
+	Return the values of the single row of key columns as Python values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	key_row_frame
+		One row of the key columns of a Table.
+
+	Returns
+	-------
+	list[Any]
+		The value of each key column, such as ``202500000001`` or ``datetime.date(2026, 1, 1)``.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.joining.join_relation import read_key_values
+	>>> seat = pandas.Series(["A"], dtype="string")
+	>>> read_key_values(pandas.DataFrame({"id": pandas.Series([7], dtype="Int64"), "seat": seat}))
+	[7, 'A']
+	"""
+	key_values = list[Any]()
+
+	for _, column in key_row_frame.items():
+		column_values = convert_column_values(column)
+		python_values = to_python_list(column_values)
+		key_values.append(python_values[0])
+
+	return key_values

numdaplot/tables/joining/join_suffixes.py

@@ -0,0 +1,71 @@
+"""
+Suffixes telling apart the columns that two joined Tables both have.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.invalid_suffixes_error import InvalidSuffixesError
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class JoinSuffixes:
+	"""
+	Suffixes added to the names of the columns both Tables of a join have, besides the keys, used by ``Join``.
+
+	Only those columns get a suffix, as in pandas. A suffixed name that another column already has raises
+	``DuplicateColumnError`` at the join.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	left
+		The suffix of the columns of the joined Table, such as ``"_2024"``.
+	right
+		The suffix of the columns of the other Table, such as ``"_2025"``.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidSuffixesError
+		When a suffix is empty, or both suffixes are the same.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> before = ndp.Table.from_arrays({"dep": ndp.Array.from_list(["75"]), "deaths": ndp.Array.from_list([40])})
+	>>> after = ndp.Table.from_arrays({"dep": ndp.Array.from_list(["75"]), "deaths": ndp.Array.from_list([35])})
+	>>> years = ndp.JoinSuffixes(left="_2024", right="_2025")
+	>>> before.join(ndp.Join(other=after, keys=["dep"], suffixes=years))
+	   dep deaths_2024 deaths_2025
+	  TEXT       INT64       INT64
+	0   75          40          35
+	"""
+
+	left: str
+	right: str
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the suffixes are not empty and differ.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidSuffixesError
+			When a suffix is empty, or both suffixes are the same.
+		"""
+		require_field_types(self)
+
+		has_empty_suffix = self.left == "" or self.right == ""
+		are_same = self.left == self.right
+		is_invalid = has_empty_suffix or are_same
+		if is_invalid:
+			raise InvalidSuffixesError(self.left, self.right)