numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/filtering/filter.py

@@ -0,0 +1,74 @@
+"""
+Settings of the filter of the rows 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.filtering.condition import Condition
+from numdaplot.tables.filtering.filter_mode import FilterMode
+
+CONDITION_ITEM_NAME = "condition"
+
+
+@dataclass(frozen=True)
+class Filter:
+	"""
+	Conditions a row must satisfy to be kept, used by ``Table.filter``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	conditions
+		The conditions, at least one. The filter keeps its own copy of the list.
+	mode
+		Whether a row must satisfy every condition, ``FilterMode.ALL`` by default, or at least one, ``FilterMode.ANY``.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	EmptyListError
+		When ``conditions`` is empty.
+
+	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})
+	>>> expensive = ndp.Condition(rule=ndp.Greater(100), columns=["price"])
+	>>> in_lyon = ndp.Condition(rule=ndp.Equal("Lyon"), columns=["city"])
+	>>> sales.filter(ndp.Filter(conditions=[expensive, in_lyon]))
+	   city   price
+	   TEXT FLOAT64
+	(0 rows)
+	"""
+
+	conditions: list[Condition]
+	mode: FilterMode = FilterMode.ALL
+
+	def __post_init__(self) -> None:
+		"""
+		Check that there is a condition and replace the list with a copy that only the filter holds.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		EmptyListError
+			When ``conditions`` is empty.
+		"""
+		require_field_types(self)
+
+		if self.conditions == []:
+			raise EmptyListError(CONDITION_ITEM_NAME)
+
+		conditions_copy = list(self.conditions)
+		object.__setattr__(self, "conditions", conditions_copy)

numdaplot/tables/filtering/filter_mode.py

@@ -0,0 +1,67 @@
+"""
+How the conditions of a Filter combine.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class FilterMode(Enum):
+	"""
+	How the conditions of a ``Filter`` combine to keep a row.
+
+	.. 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})
+	>>> expensive = ndp.Condition(rule=ndp.Greater(130), columns=["price"])
+	>>> in_lyon = ndp.Condition(rule=ndp.Equal("Lyon"), columns=["city"])
+	>>> sales.filter(ndp.Filter(conditions=[expensive, in_lyon], mode=ndp.FilterMode.ANY))
+	    city   price
+	    TEXT FLOAT64
+	0   Lyon    80.0
+	1  Paris   150.0
+	"""
+
+	ALL = auto()
+	"""
+	A row is kept when it satisfies every condition. 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})
+	>>> expensive = ndp.Condition(rule=ndp.Greater(100), columns=["price"])
+	>>> in_lyon = ndp.Condition(rule=ndp.Equal("Lyon"), columns=["city"])
+	>>> sales.filter(ndp.Filter(conditions=[expensive, in_lyon], mode=ndp.FilterMode.ALL))
+	   city   price
+	   TEXT FLOAT64
+	(0 rows)
+	"""
+
+	ANY = auto()
+	"""
+	A row is kept when it satisfies at least one condition.
+
+	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})
+	>>> expensive = ndp.Condition(rule=ndp.Greater(100), columns=["price"])
+	>>> in_lyon = ndp.Condition(rule=ndp.Equal("Lyon"), columns=["city"])
+	>>> sales.filter(ndp.Filter(conditions=[expensive, in_lyon], mode=ndp.FilterMode.ANY))
+	    city   price
+	    TEXT FLOAT64
+	0  Paris   120.0
+	1   Lyon    80.0
+	2  Paris   150.0
+	"""

numdaplot/tables/filtering/row_mask.py

@@ -0,0 +1,152 @@
+"""
+Rows of a Table satisfying a Filter.
+
+.. versionadded:: 0.1.0
+"""
+
+import numpy
+import pandas
+from numpy.typing import NDArray
+
+from numdaplot.tables.columns.column_names import require_known_columns
+from numdaplot.tables.filtering.column_mask import build_column_mask
+from numdaplot.tables.filtering.column_match import ColumnMatch
+from numdaplot.tables.filtering.condition import Condition
+from numdaplot.tables.filtering.filter import Filter
+from numdaplot.tables.filtering.filter_mode import FilterMode
+
+MASK_AXIS = 0
+
+
+def build_filter_mask(frame: pandas.DataFrame, row_filter: Filter) -> NDArray[numpy.bool_]:
+	"""
+	Return which rows of a Table satisfy a Filter.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	row_filter
+		The conditions and how they combine.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		True at each row to keep.
+
+	Raises
+	------
+	ColumnNotFoundError
+		When a condition names a column the Table does not have.
+	IncompatibleTypesError
+		When a rule does not apply to the type of one of its columns.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.filtering.row_mask import build_filter_mask
+	>>> frame = pandas.DataFrame({"price": [5.0, 12.0]})
+	>>> build_filter_mask(frame, ndp.Filter(conditions=[ndp.Condition(rule=ndp.Greater(10))]))
+	array([False,  True])
+	"""
+	condition_masks = [build_condition_mask(frame, condition) for condition in row_filter.conditions]
+	requires_all = row_filter.mode == FilterMode.ALL
+	row_count = len(frame)
+	filter_mask = combine_masks(condition_masks, requires_all, row_count)
+
+	return filter_mask
+
+
+def build_condition_mask(frame: pandas.DataFrame, condition: Condition) -> NDArray[numpy.bool_]:
+	"""
+	Return which rows of a Table satisfy a Condition.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	condition
+		The rule, its columns, and how the columns combine.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		True at each row satisfying the condition.
+
+	Raises
+	------
+	ColumnNotFoundError
+		When the condition names a column the Table does not have.
+	IncompatibleTypesError
+		When the rule does not apply to the type of one of the columns.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.filtering.row_mask import build_condition_mask
+	>>> frame = pandas.DataFrame({"low": [1.0, 5.0], "high": [2.0, 9.0]})
+	>>> build_condition_mask(frame, ndp.Condition(rule=ndp.Greater(1.5), mode=ndp.ColumnMatch.ALL))
+	array([False,  True])
+	"""
+	column_names = [str(column_name) for column_name in frame.columns]
+	if condition.columns is not None:
+		require_known_columns(condition.columns, column_names)
+		column_names = condition.columns
+
+	column_masks = list[NDArray[numpy.bool_]]()
+
+	for column_name in column_names:
+		column = frame[column_name]
+		column_mask = build_column_mask(column, condition.rule)
+		column_masks.append(column_mask)
+
+	requires_all = condition.mode == ColumnMatch.ALL
+	row_count = len(frame)
+	condition_mask = combine_masks(column_masks, requires_all, row_count)
+
+	return condition_mask
+
+
+def combine_masks(masks: list[NDArray[numpy.bool_]], requires_all: bool, row_count: int) -> NDArray[numpy.bool_]:
+	"""
+	Return the rows satisfying every mask, or at least one mask.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	masks
+		One mask per condition or per column, each as long as the Table.
+	requires_all
+		True to keep the rows satisfying every mask, False for at least one.
+	row_count
+		The number of rows of the Table, used when there is no mask.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		The combined mask. Without any mask, every row satisfies "every mask" and none satisfies "at least one".
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.tables.filtering.row_mask import combine_masks
+	>>> combine_masks([numpy.array([True, False]), numpy.array([True, True])], True, 2)
+	array([ True, False])
+	"""
+	mask_count = len(masks)
+	stacked_masks = numpy.array(masks, dtype=numpy.bool_)
+	mask_grid = stacked_masks.reshape(mask_count, row_count)
+	if requires_all:
+		every_mask = numpy.logical_and.reduce(mask_grid, axis=MASK_AXIS)
+		return every_mask
+
+	any_mask = numpy.logical_or.reduce(mask_grid, axis=MASK_AXIS)
+
+	return any_mask

numdaplot/tables/filtering/rule_moments.py

@@ -0,0 +1,164 @@
+"""
+Datetimes of a rule matched with the time zone of the column it is applied to.
+
+.. versionadded:: 0.1.0
+"""
+
+import dataclasses
+from datetime import UTC, date, datetime
+from typing import Any, cast
+
+from numdaplot.dates.time_zone import TimeZone
+from numdaplot.errors.time_zone_mismatch_error import TimeZoneMismatchError
+from numdaplot.rules.rule import Rule
+
+NAIVE_COLUMN_OPERATION = "A rule on a column without time zone"
+ZONE_COLUMN_OPERATION = "A rule on a datetime column with a time zone"
+
+
+def match_rule_time_zone(rule: Rule, time_zone: TimeZone | None) -> Rule:
+	"""
+	Return a rule whose dates and datetimes can be compared with the values of a column.
+
+	A column with a time zone is compared through its UTC clock times, so the datetimes of the rule are
+	moved to UTC too.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	rule
+		Any rule of numdaplot.
+	time_zone
+		The time zone of the column, ``None`` when it has none.
+
+	Returns
+	-------
+	Rule
+		The rule itself for a column without time zone, or a copy with its datetimes as UTC clock times
+		without zone.
+
+	Raises
+	------
+	TimeZoneMismatchError
+		When the rule has a datetime with a time zone and the column has none, or the column has a zone and
+		the rule has a date or a datetime without zone.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> from zoneinfo import ZoneInfo
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.filtering.rule_moments import match_rule_time_zone
+	>>> paris_noon = datetime(2026, 7, 1, 12, tzinfo=ZoneInfo("Europe/Paris"))
+	>>> match_rule_time_zone(ndp.Greater(paris_noon), ndp.TimeZone("Europe/Paris"))
+	Greater(value=datetime.datetime(2026, 7, 1, 10, 0))
+	"""
+	if not dataclasses.is_dataclass(rule):
+		return rule
+
+	rule_fields = dataclasses.fields(rule)
+	matched_values = dict[str, Any]()
+
+	for rule_field in rule_fields:
+		field_value = getattr(rule, rule_field.name)
+		matched_values[rule_field.name] = match_field_time_zone(field_value, time_zone)
+
+	if time_zone is None:
+		return rule
+
+	matched_rule = dataclasses.replace(rule, **matched_values)
+
+	return matched_rule
+
+
+def match_field_time_zone(field_value: Any, time_zone: TimeZone | None) -> Any:
+	"""
+	Return the value of a rule setting with its dates and datetimes matched with the zone of a column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	field_value
+		The value of a setting of a rule, a single value or a list of values.
+	time_zone
+		The time zone of the column, ``None`` when it has none.
+
+	Returns
+	-------
+	Any
+		The value, a datetime moved to a UTC clock time without zone, or a list of such values.
+
+	Raises
+	------
+	TimeZoneMismatchError
+		When a date or a datetime does not match the zone state of the column.
+
+	Examples
+	--------
+	>>> from numdaplot.tables.filtering.rule_moments import match_field_time_zone
+	>>> match_field_time_zone([1, 2], None)
+	[1, 2]
+	"""
+	if isinstance(field_value, list):
+		list_values = cast(list[Any], field_value)
+		matched_list = [match_moment_time_zone(list_value, time_zone) for list_value in list_values]
+		return matched_list
+
+	matched_value = match_moment_time_zone(field_value, time_zone)
+
+	return matched_value
+
+
+def match_moment_time_zone(value: Any, time_zone: TimeZone | None) -> Any:
+	"""
+	Return a single value of a rule with its date or datetime matched with the zone of a column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		A single value of a rule.
+	time_zone
+		The time zone of the column, ``None`` when it has none.
+
+	Returns
+	-------
+	Any
+		The value itself, or a datetime with a zone moved to a UTC clock time without zone.
+
+	Raises
+	------
+	TimeZoneMismatchError
+		When the value is a datetime with a zone and the column has none, or the column has a zone and the value
+		is a date or a datetime without zone.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> from zoneinfo import ZoneInfo
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.filtering.rule_moments import match_moment_time_zone
+	>>> match_moment_time_zone(datetime(2026, 1, 1, 9, tzinfo=ZoneInfo("Europe/Paris")), ndp.TimeZone("UTC"))
+	datetime.datetime(2026, 1, 1, 8, 0)
+	"""
+	if not isinstance(value, date):
+		return value
+
+	has_zone = isinstance(value, datetime) and value.tzinfo is not None
+	if time_zone is None and has_zone:
+		raise TimeZoneMismatchError(NAIVE_COLUMN_OPERATION, False)
+
+	if time_zone is None:
+		return value
+
+	if not has_zone:
+		raise TimeZoneMismatchError(ZONE_COLUMN_OPERATION, True)
+
+	zone_datetime = cast(datetime, value)
+	utc_datetime = zone_datetime.astimezone(UTC)
+	naive_datetime = utc_datetime.replace(tzinfo=None)
+
+	return naive_datetime

numdaplot/tables/frames/__init__.py

@@ -0,0 +1,5 @@
+"""
+Storage of Table columns in pandas: normalization, conversion to numpy, equality, text and positions.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/tables/frames/array_frame.py

@@ -0,0 +1,95 @@
+"""
+Columns of a Table built from Arrays.
+
+.. versionadded:: 0.1.0
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pandas
+
+from numdaplot.arrays.array_data import read_stored_values
+from numdaplot.errors.dimension_error import DimensionError
+from numdaplot.errors.empty_list_error import EmptyListError
+from numdaplot.errors.shape_mismatch_error import ShapeMismatchError
+from numdaplot.tables.columns.column_names import require_column_names
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.frames.column_values import build_column
+from numdaplot.tables.frames.time_range_errors import TimeRangeErrors
+
+if TYPE_CHECKING:
+	from numdaplot.arrays.array import Array
+
+FROM_ARRAYS_OPERATION = "from_arrays"
+COLUMN_ITEM_NAME = "column"
+ONE_DIMENSION = 1
+
+
+def build_array_frame(columns: dict[str, Array]) -> pandas.DataFrame:
+	"""
+	Return the columns of a Table holding the values of one-dimensional Arrays.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	columns
+		One Array per column, by column name, all of the same length.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The columns in the order of the dictionary, rows numbered from 0.
+
+	Raises
+	------
+	EmptyListError
+		When there is no column.
+	InvalidColumnNameError
+		When a column name is not a non-empty text.
+	DimensionError
+		When an Array does not have one dimension.
+	ShapeMismatchError
+		When the Arrays do not have the same length.
+	TimeOverflowError
+		When an Array holds a datetime or a duration that nanoseconds cannot hold.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.frames.array_frame import build_array_frame
+	>>> build_array_frame({"city": ndp.Array.from_list(["Pau"]), "price": ndp.Array.from_list([1.5])})
+	  city  price
+	0  Pau    1.5
+	"""
+	if columns == {}:
+		raise EmptyListError(COLUMN_ITEM_NAME)
+
+	column_names = list(columns)
+	require_column_names(column_names)
+	built_columns = dict[str, Column]()
+	value_counts = list[int]()
+
+	for column_name, array in columns.items():
+		values = read_stored_values(array)
+		if values.ndim != ONE_DIMENSION:
+			raise DimensionError(FROM_ARRAYS_OPERATION, values.ndim)
+
+		with TimeRangeErrors(FROM_ARRAYS_OPERATION, column_name):
+			column = build_column(values)
+
+		built_columns[column_name] = column
+		value_counts.append(values.size)
+
+	row_count = value_counts[0]
+
+	for value_count in value_counts:
+		if value_count != row_count:
+			raise ShapeMismatchError((row_count,), (value_count,))
+
+	row_numbers = pandas.RangeIndex(row_count)
+	frame = pandas.DataFrame(built_columns, index=row_numbers)
+
+	return frame

numdaplot/tables/frames/cleaned_names.py

@@ -0,0 +1,132 @@
+r"""
+Cleaning of the column names a Table reads.
+
+.. versionadded:: 0.1.0
+"""
+
+from collections.abc import Hashable
+
+import pandas
+
+from numdaplot.errors.duplicate_column_error import DuplicateColumnError
+from numdaplot.tables.files.column_names import ColumnNames
+
+
+def clean_frame_names(frame: pandas.DataFrame, column_names: ColumnNames) -> pandas.DataFrame:
+	r"""
+	Return a DataFrame read from outside numdaplot, with its column names cleaned when asked.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		A DataFrame read from a file or given by the user. It is not changed.
+	column_names
+		``CLEANED`` to remove the spaces, tabs and line breaks at the start and the end of each name, ``KEPT`` to
+		keep the names as written.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The DataFrame with the cleaned names, or the same DataFrame when the names are kept.
+
+	Raises
+	------
+	DuplicateColumnError
+		When two different names become the same once cleaned.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.frames.cleaned_names import clean_frame_names
+	>>> frame = pandas.DataFrame({"id_vehicule\n": [1], " speed ": [50]})
+	>>> clean_frame_names(frame, ndp.ColumnNames.CLEANED).columns.tolist()
+	['id_vehicule', 'speed']
+	"""
+	if column_names == ColumnNames.KEPT:
+		return frame
+
+	raw_names = list[Hashable](frame.columns)
+	cleaned_names = clean_names(raw_names)
+	require_distinct_cleaned_names(raw_names, cleaned_names)
+	cleaned_frame = frame.copy(deep=False)
+	cleaned_frame.columns = pandas.Index(cleaned_names)
+
+	return cleaned_frame
+
+
+def clean_names(names: list[Hashable]) -> list[Hashable]:
+	r"""
+	Return column names without the spaces, tabs and line breaks at their start and end.
+
+	A name that is not a text is kept, so that the check of the column names refuses it.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	names
+		The column names.
+
+	Returns
+	-------
+	list[Hashable]
+		The cleaned names, in the same order.
+
+	Examples
+	--------
+	>>> from numdaplot.tables.frames.cleaned_names import clean_names
+	>>> clean_names(["id_vehicule\n", " speed", 2024])
+	['id_vehicule', 'speed', 2024]
+	"""
+	cleaned_names = list[Hashable]()
+	for name in names:
+		cleaned_name = name
+		if isinstance(name, str):
+			cleaned_name = name.strip()
+
+		cleaned_names.append(cleaned_name)
+
+	return cleaned_names
+
+
+def require_distinct_cleaned_names(raw_names: list[Hashable], cleaned_names: list[Hashable]) -> None:
+	r"""
+	Check that two different names do not become the same once cleaned.
+
+	A name written twice the same way is left to the check of the column names, which names it alone.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	raw_names
+		The column names as written.
+	cleaned_names
+		The same names once cleaned, in the same order.
+
+	Raises
+	------
+	DuplicateColumnError
+		At the first cleaned name coming from two different names, with both of them.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.frames.cleaned_names import require_distinct_cleaned_names
+	>>> try:
+	... 	require_distinct_cleaned_names(["id", "id\n"], ["id", "id"])
+	... except ndp.DuplicateColumnError as error:
+	... 	print(error)
+	The column names 'id' and 'id\n' both become 'id' once cleaned. Use ColumnNames.KEPT to keep them as written.
+	"""
+	first_raw_names = dict[Hashable, Hashable]()
+	for raw_name, cleaned_name in zip(raw_names, cleaned_names, strict=True):
+		first_raw_name = first_raw_names.setdefault(cleaned_name, raw_name)
+		if first_raw_name == raw_name:
+			continue
+
+		original_names = [str(first_raw_name), str(raw_name)]
+		raise DuplicateColumnError(str(cleaned_name), original_names)

numdaplot/tables/frames/column.py

@@ -0,0 +1,15 @@
+"""
+Type of the pandas columns a Table stores.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import pandas
+
+type Column = pandas.Series[Any]
+"""A pandas column of a Table, stored with one of the dtypes given by ``to_pandas_dtype``.
+
+.. versionadded:: 0.1.0
+"""