numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/table_data.py

@@ -0,0 +1,321 @@
+"""
+Columns stored by a Table, shared by every group of Table methods.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Never, Self
+
+import pandas
+
+from numdaplot.data_types.type import Type
+from numdaplot.dates.time_zone import TimeZone
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+from numdaplot.tables.columns.column_names import require_known_columns
+from numdaplot.tables.files.column_names import ColumnNames
+from numdaplot.tables.frames.cleaned_names import clean_frame_names
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.frames.column_values import find_column_type
+from numdaplot.tables.frames.frame_normalization import normalize_frame
+from numdaplot.tables.frames.time_columns import convert_outside_durations
+from numdaplot.tables.frames.time_zones import find_column_time_zone
+
+CONSTRUCTOR_OPERATION = "Creating a Table with ndp.Table(...)"
+CONSTRUCTOR_ALTERNATIVE = "ndp.Table.from_arrays, from_pandas or a file method such as from_csv"
+
+
+class TableData:
+	"""
+	Columns stored by a Table, shared by every group of Table methods.
+
+	Use ``ndp.Table`` and its ``from_*`` methods; this base class only holds the columns.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	_frame: pandas.DataFrame
+
+	def __init__(self, *arguments: Never, **keyword_arguments: Never) -> None:
+		"""
+		Refuse the creation of a Table by its constructor: the ``from_*`` methods create Tables.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		arguments
+			Any value, refused.
+		keyword_arguments
+			Any named value, refused.
+
+		Raises
+		------
+		RefusedOperationError
+			Always, naming the ``from_*`` methods.
+		"""
+		raise RefusedOperationError(CONSTRUCTOR_OPERATION, CONSTRUCTOR_ALTERNATIVE)
+
+	@classmethod
+	def _create(cls, frame: pandas.DataFrame) -> Self:
+		"""
+		Return a new Table storing normalized columns without copy.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		frame
+			The columns, already stored with the dtypes given by ``to_pandas_dtype`` and numbered from 0,
+			never changed afterwards.
+
+		Returns
+		-------
+		Self
+			The new Table.
+		"""
+		created_table = cls.__new__(cls)
+		created_table._frame = frame
+
+		return created_table
+
+	@property
+	def row_count(self) -> int:
+		"""
+		Number of rows.
+
+		.. versionadded:: 0.1.0
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5, 8.0])}).row_count
+		2
+		"""
+		row_count = len(self._frame)
+
+		return row_count
+
+	@property
+	def column_count(self) -> int:
+		"""
+		Number of columns.
+
+		.. versionadded:: 0.1.0
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5, 8.0])}).column_count
+		1
+		"""
+		column_count = len(self._frame.columns)
+
+		return column_count
+
+	@property
+	def column_names(self) -> list[str]:
+		"""
+		Names of the columns, in order. Changing the returned list never changes the Table.
+
+		.. versionadded:: 0.1.0
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> cities = ndp.Array.from_list(["Paris"])
+		>>> prices = ndp.Array.from_list([1.5])
+		>>> ndp.Table.from_arrays({"city": cities, "price": prices}).column_names
+		['city', 'price']
+		"""
+		column_names = [str(column_name) for column_name in self._frame.columns]
+
+		return column_names
+
+	@property
+	def column_types(self) -> dict[str, Type]:
+		"""
+		Type of each column, by column name, in the order of the columns.
+
+		.. versionadded:: 0.1.0
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5])}).column_types
+		{'price': <Type.FLOAT64: 10>}
+		"""
+		column_types = dict[str, Type]()
+
+		for column_name in self.column_names:
+			column = self._frame[column_name]
+			column_type = find_column_type(column)
+			column_types[column_name] = column_type
+
+		return column_types
+
+	@property
+	def column_time_zones(self) -> dict[str, TimeZone | None]:
+		"""
+		Time zone of each datetime column, by column name, ``None`` for a datetime column without zone.
+
+		Columns of other types are not listed.
+
+		.. versionadded:: 0.1.0
+
+		Examples
+		--------
+		>>> from datetime import datetime
+		>>> import numdaplot as ndp
+		>>> times = ndp.Table.from_arrays({"time": ndp.Array.from_list([datetime(2026, 7, 1, 10, 30)])})
+		>>> times.column_time_zones
+		{'time': None}
+		"""
+		column_time_zones = dict[str, TimeZone | None]()
+
+		for column_name in self.column_names:
+			column = self._frame[column_name]
+			column_type = find_column_type(column)
+			if column_type == Type.DATETIME:
+				column_time_zones[column_name] = find_column_time_zone(column)
+
+		return column_time_zones
+
+	@classmethod
+	def _from_frame(cls, frame: pandas.DataFrame) -> Self:
+		"""
+		Return a new Table holding the normalized copy of any pandas DataFrame.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		frame
+			Any pandas DataFrame, which is not changed.
+
+		Returns
+		-------
+		Self
+			The new Table.
+
+		Raises
+		------
+		InvalidColumnNameError, DuplicateColumnError, UnsupportedIndexError, UnsupportedTypeError
+			When the pandas DataFrame cannot become a Table, as in ``normalize_frame``.
+		"""
+		normalized_frame = normalize_frame(frame)
+		table = cls._create(normalized_frame)
+
+		return table
+
+	@classmethod
+	def _from_read_frame(cls, frame: pandas.DataFrame, column_names: ColumnNames) -> Self:
+		"""
+		Return a new Table holding a DataFrame read from a file or given by the user, its names cleaned when asked.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		frame
+			A pandas DataFrame read from outside numdaplot, which is not changed.
+		column_names
+			Whether the spaces, tabs and line breaks at the start and the end of each name are removed.
+
+		Returns
+		-------
+		Self
+			The new Table.
+
+		Raises
+		------
+		DuplicateColumnError
+			When two names become the same once cleaned, or a name appears twice.
+		InvalidColumnNameError, UnsupportedIndexError, UnsupportedTypeError
+			When the pandas DataFrame cannot become a Table, as in ``normalize_frame``.
+		"""
+		cleaned_frame = clean_frame_names(frame, column_names)
+		duration_frame = convert_outside_durations(cleaned_frame)
+		table = cls._from_frame(duration_frame)
+
+		return table
+
+	def _wrap(self, frame: pandas.DataFrame) -> Self:
+		"""
+		Return a new Table of the same class holding other normalized columns.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		frame
+			The columns of the new Table, stored without copy.
+
+		Returns
+		-------
+		Self
+			The new Table.
+		"""
+		table_class = type(self)
+		wrapped_table = table_class._create(frame)
+
+		return wrapped_table
+
+	def _read_column(self, column_name: str) -> Column:
+		"""
+		Return a column of the Table.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		column_name
+			The name of the column.
+
+		Returns
+		-------
+		Column
+			The stored column, which must not be changed.
+
+		Raises
+		------
+		ColumnNotFoundError
+			When no column has this name.
+		"""
+		requested_names = [column_name]
+		require_known_columns(requested_names, self.column_names)
+		column = self._frame[column_name]
+
+		return column
+
+
+def read_stored_frame(table: TableData) -> pandas.DataFrame:
+	"""
+	Return the columns a Table stores, without copy, for the code of numdaplot that reads them.
+
+	Unlike ``Table.to_pandas``, times of day stay stored as the time since midnight.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	table
+		A Table.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The stored columns, which must not be changed.
+
+	Examples
+	--------
+	>>> from datetime import time
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.table_data import read_stored_frame
+	>>> hours = ndp.Table.from_arrays({"hour": ndp.Array.from_list([time(0, 1)])})
+	>>> read_stored_frame(hours).dtypes.tolist()
+	[dtype('<m8[us]')]
+	"""
+	# The function lives next to the class to read its stored columns on behalf of the rest of numdaplot.
+	stored_frame = table._frame  # pyright: ignore[reportPrivateUsage]
+
+	return stored_frame

numdaplot/tables/table_display.py

@@ -0,0 +1,56 @@
+"""
+Display of a few rows of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.tables.preview.notebook_display import show_frame
+from numdaplot.tables.preview.preview import Preview
+from numdaplot.tables.preview.preview_rows import choose_preview_rows
+from numdaplot.tables.table_data import TableData
+
+
+class TableDisplay(TableData):
+	"""
+	Display of a few rows of a Table with ``preview``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def preview(self, preview: Preview | None = None) -> None:
+		"""
+		Show a few rows, with their row numbers and the type of each column under its name.
+
+		In a Jupyter notebook the rows are shown as an HTML table, elsewhere as text. Every column is shown unless
+		the settings ask for a compact display. Nothing is returned.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		preview
+			How many rows, which ones, and how the columns are shown: the first 5, with every column, when omitted.
+
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> table = ndp.Table.from_arrays({"price": ndp.Array.from_list([10.0, 20.0, 30.0])})
+		>>> table.preview(ndp.Preview(count=2, side=ndp.Side.END))
+		    price
+		  FLOAT64
+		1    20.0
+		2    30.0
+		"""
+		if preview is None:
+			preview = Preview()
+
+		preview_frame = choose_preview_rows(self._frame, preview)
+		show_frame(preview_frame, preview.columns)

numdaplot/tables/table_joining.py

@@ -0,0 +1,80 @@
+"""
+Join of a Table with another Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Self
+
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.tables.joining.join import Join
+from numdaplot.tables.joining.joined_frame import join_frames
+from numdaplot.tables.table_data import TableData
+
+
+class TableJoining(TableData):
+	"""
+	Join of a Table with another Table on the values of key columns, with ``join``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def join(self, join: Join) -> Self:
+		"""
+		Return the rows of this Table and of another Table put side by side where their keys match.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		join
+			The other Table, the key columns, the rows kept, how the columns both Tables have are told apart, and
+			how many times each key may appear.
+
+		Returns
+		-------
+		Self
+			A new Table: the keys, then the other columns of this Table, then those of the other Table. The rows of
+			this Table come first, in their order, each once per match, then the unmatched rows of the other Table
+			kept by the mode. Missing values fill the columns of a Table that has no matching row, each column
+			keeping its type.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		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: convert one of them first.
+		TimeZoneMismatchError
+			When the two columns of a key hold datetimes of different time zones, or with and without one: change
+			them first with ``TimeZoneChange``.
+		JoinRelationError
+			When a key is repeated in a Table where the ``relation`` of the join expects it once.
+		DuplicateColumnError
+			When both Tables have a column besides the keys and the join has no ``suffixes``, or a suffixed name is
+			already the name of another column.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> accidents = ndp.Table.from_arrays(
+		... 	{"Num_Acc": ndp.Array.from_list([101, 102]), "dep": ndp.Array.from_list(["75", "69"])}
+		... )
+		>>> users = ndp.Table.from_arrays(
+		... 	{"Num_Acc": ndp.Array.from_list([101, 101, 103]), "grav": ndp.Array.from_list([1, 3, 2])}
+		... )
+		>>> accidents.join(ndp.Join(other=users, keys=["Num_Acc"], mode=ndp.JoinMode.LEFT))
+		  Num_Acc  dep  grav
+		    INT64 TEXT INT64
+		0     101   75     1
+		1     101   75     3
+		2     102   69  <NA>
+		"""
+		joined_frame = join_frames(self._frame, join)
+		joined_table = self._wrap(joined_frame)
+
+		return joined_table

numdaplot/tables/table_layout.py

@@ -0,0 +1,105 @@
+"""
+Order and uniqueness of the rows of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Self
+
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.tables.duplicates.deduplicated_frame import drop_duplicate_rows
+from numdaplot.tables.duplicates.deduplication import Deduplication
+from numdaplot.tables.sorting.sorted_frame import sort_frame
+from numdaplot.tables.sorting.sorting import Sorting
+from numdaplot.tables.table_data import TableData
+
+
+class TableLayout(TableData):
+	"""
+	Order and uniqueness of the rows of a Table with ``sort`` and ``drop_duplicates``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def sort(self, sorting: Sorting) -> Self:
+		"""
+		Return the rows sorted by one or several columns.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		sorting
+			The sort keys, each with its order and the place of its missing values.
+
+		Returns
+		-------
+		Self
+			A new Table, rows numbered from 0. Rows equal on every key keep their order.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ColumnNotFoundError
+			When a key names a column the Table does not have.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> table = ndp.Table.from_arrays({"price": ndp.Array.from_list([20.0, 10.0, 30.0])})
+		>>> table.sort(ndp.Sorting(keys=[ndp.SortKey(column="price", order=ndp.Order.DESCENDING)]))
+		    price
+		  FLOAT64
+		0    30.0
+		1    20.0
+		2    10.0
+		"""
+		sorted_frame = sort_frame(self._frame, sorting)
+		sorted_table = self._wrap(sorted_frame)
+
+		return sorted_table
+
+	@checked_arguments
+	def drop_duplicates(self, deduplication: Deduplication | None = None) -> Self:
+		"""
+		Return the Table without its duplicated rows.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		deduplication
+			The compared columns, every column when omitted, and the row kept in each group.
+			Two missing values are equal.
+
+		Returns
+		-------
+		Self
+			A new Table, remaining rows in their order, numbered from 0.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ColumnNotFoundError
+			When a compared column does not exist.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> table = ndp.Table.from_arrays({"city": ndp.Array.from_list(["Pau", "Lyon", "Pau"])})
+		>>> table.drop_duplicates()
+		   city
+		   TEXT
+		0   Pau
+		1  Lyon
+		"""
+		if deduplication is None:
+			deduplication = Deduplication()
+
+		remaining_frame = drop_duplicate_rows(self._frame, deduplication)
+		remaining_table = self._wrap(remaining_frame)
+
+		return remaining_table

numdaplot/tables/table_missing.py

@@ -0,0 +1,146 @@
+"""
+Missing values of a Table: count, summary and removal.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Self
+
+from numdaplot.positions.axis import Axis
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.tables.missing.missing_count import MissingCount
+from numdaplot.tables.missing.missing_counts import count_frame_missing
+from numdaplot.tables.missing.missing_drop import MissingDrop
+from numdaplot.tables.missing.missing_removal import drop_frame_missing
+from numdaplot.tables.missing.missing_summary import summarize_missing
+from numdaplot.tables.preview.notebook_display import show_pandas_frame
+from numdaplot.tables.table_data import TableData
+
+
+class TableMissing(TableData):
+	"""
+	Missing values of a Table with ``count_missing``, ``preview_missing`` and ``drop_missing``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def count_missing(self, missing_count: MissingCount | None = None, axis: Axis | None = None) -> Self:
+		"""
+		Return the number or the ratio of missing values, for the whole Table, each row or each column.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		missing_count
+			The measure, the number of missing values when omitted.
+		axis
+			One count per row with ``Axis.EACH_ROW``, one per column with ``Axis.EACH_COLUMN``, a single count for
+			the whole Table when omitted.
+
+		Returns
+		-------
+		Self
+			A new Table with a ``missing_count`` column, or ``missing_ratio`` for ``Measure.RATIO``:
+			one row for the whole Table, read with ``to_value``, one row per row, or one row per column after
+			a ``column`` column naming it. A ratio is missing when there is no value to count.
+
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau", "Nice"])
+		>>> prices = ndp.Array.from_list([120.0, None, None, 90.0])
+		>>> table = ndp.Table.from_arrays({"city": cities, "price": prices})
+		>>> table.count_missing().to_value()
+		2
+		>>> table.count_missing(ndp.MissingCount(measure=ndp.Measure.RATIO), axis=ndp.Axis.EACH_COLUMN)
+		  column missing_ratio
+		    TEXT       FLOAT64
+		0   city           0.0
+		1  price           0.5
+		"""
+		if missing_count is None:
+			missing_count = MissingCount()
+
+		count_frame = count_frame_missing(self._frame, missing_count, axis)
+		count_table = self._wrap(count_frame)
+
+		return count_table
+
+	def preview_missing(self) -> None:
+		"""
+		Show the number and the percentage of missing values of each column, then of the whole Table.
+
+		In a Jupyter notebook the summary is shown as an HTML table, elsewhere as text. Nothing is returned:
+		use ``count_missing`` to compute with these numbers.
+
+		.. versionadded:: 0.1.0
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau"])
+		>>> prices = ndp.Array.from_list([120.0, None, 150.0])
+		>>> table = ndp.Table.from_arrays({"city": cities, "price": prices})
+		>>> table.preview_missing()
+		          column     type  missing_count missing_ratio
+		0           city     TEXT              0         0.0 %
+		1          price  FLOAT64              1        33.3 %
+		2  (all columns)                       1        16.7 %
+		"""
+		summary = summarize_missing(self._frame)
+		show_pandas_frame(summary)
+
+	@checked_arguments
+	def drop_missing(self, missing_drop: MissingDrop | None = None, axis: Axis = Axis.EACH_ROW) -> Self:
+		"""
+		Return the Table without its rows, or its columns, holding missing values.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		missing_drop
+			The columns looked at and how many missing values are needed: a single one in any column when
+			omitted.
+		axis
+			``Axis.EACH_ROW`` by default to remove rows, ``Axis.EACH_COLUMN`` to remove columns.
+
+		Returns
+		-------
+		Self
+			A new Table, remaining rows in their order and numbered from 0, or remaining columns in their order.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ColumnNotFoundError
+			When a looked at column does not exist.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau"])
+		>>> prices = ndp.Array.from_list([120.0, None, 150.0])
+		>>> table = ndp.Table.from_arrays({"city": cities, "price": prices})
+		>>> table.drop_missing()
+		    city   price
+		    TEXT FLOAT64
+		0  Paris   120.0
+		1    Pau   150.0
+		"""
+		if missing_drop is None:
+			missing_drop = MissingDrop()
+
+		remaining_frame = drop_frame_missing(self._frame, missing_drop, axis)
+		remaining_table = self._wrap(remaining_frame)
+
+		return remaining_table