numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/preview/side.py

@@ -0,0 +1,82 @@
+"""
+Which rows of a Table a preview shows.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class Side(Enum):
+	"""
+	Which rows of a Table a ``Preview`` shows.
+
+	.. 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.preview(ndp.Preview(count=1, side=ndp.Side.END))
+	    city   price
+	    TEXT FLOAT64
+	2  Paris   150.0
+	>>> sales.preview(ndp.Preview(count=2, side=ndp.Side.RANDOM, seed=42))
+	    city   price
+	    TEXT FLOAT64
+	0  Paris   120.0
+	2  Paris   150.0
+	"""
+
+	START = auto()
+	"""
+	The first rows. 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.preview(ndp.Preview(count=2, side=ndp.Side.START))
+	    city   price
+	    TEXT FLOAT64
+	0  Paris   120.0
+	1   Lyon    80.0
+	"""
+
+	END = auto()
+	"""
+	The last rows.
+
+	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.preview(ndp.Preview(count=2, side=ndp.Side.END))
+	    city   price
+	    TEXT FLOAT64
+	1   Lyon    80.0
+	2  Paris   150.0
+	"""
+
+	RANDOM = auto()
+	"""
+	Rows drawn at random, shown in the order of the Table.
+
+	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.preview(ndp.Preview(count=2, side=ndp.Side.RANDOM, seed=42))
+	    city   price
+	    TEXT FLOAT64
+	0  Paris   120.0
+	2  Paris   150.0
+	"""

numdaplot/tables/sorting/__init__.py

@@ -0,0 +1,5 @@
+"""
+Sort of the rows of a Table by one or several columns.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/tables/sorting/sort_key.py

@@ -0,0 +1,71 @@
+"""
+A column the rows of a Table are sorted by.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.ordering.missing_position import MissingPosition
+from numdaplot.ordering.order import Order
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.columns.column_names import require_column_name
+
+
+@dataclass(frozen=True)
+class SortKey:
+	"""
+	A column the rows of a Table are sorted by, used by ``Sorting``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		The name of the column.
+	order
+		Ascending by default.
+	missing
+		Place of the missing values, last by default whatever the order.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidColumnNameError
+		When ``column`` is an empty text.
+
+	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.sort(ndp.Sorting(keys=[ndp.SortKey(column="price", order=ndp.Order.DESCENDING)]))
+	    city   price
+	    TEXT FLOAT64
+	0  Paris   150.0
+	1  Paris   120.0
+	2   Lyon    80.0
+	"""
+
+	column: str
+	order: Order = Order.ASCENDING
+	missing: MissingPosition = MissingPosition.LAST
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the column name is a non-empty text.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidColumnNameError
+			When ``column`` is an empty text.
+		"""
+		require_field_types(self)
+
+		require_column_name(self.column)

numdaplot/tables/sorting/sorted_frame.py

@@ -0,0 +1,81 @@
+"""
+Sort of the rows of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Literal
+
+import pandas
+
+from numdaplot.ordering.missing_position import MissingPosition
+from numdaplot.ordering.order import Order
+from numdaplot.tables.columns.column_names import require_known_columns
+from numdaplot.tables.sorting.sorting import Sorting
+
+STABLE_SORT = "stable"
+MISSING_PLACES = dict[MissingPosition, Literal["first", "last"]](
+	{
+		MissingPosition.FIRST: "first",
+		MissingPosition.LAST: "last",
+	}
+)
+
+
+def sort_frame(frame: pandas.DataFrame, sorting: Sorting) -> pandas.DataFrame:
+	"""
+	Return the rows of a Table sorted by several columns, each with its own order and place of missing values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	sorting
+		The sort keys.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The sorted rows, numbered from 0. Rows equal on every key keep their order.
+
+	Raises
+	------
+	ColumnNotFoundError
+		When a key names a column the Table does not have.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.sorting.sorted_frame import sort_frame
+	>>> frame = pandas.DataFrame({"city": ["Pau", "Lyon", "Pau"], "price": [1.0, 2.0, 3.0]})
+	>>> by_city = ndp.SortKey(column="city")
+	>>> by_price = ndp.SortKey(column="price", order=ndp.Order.DESCENDING)
+	>>> sort_frame(frame, ndp.Sorting(keys=[by_city, by_price]))
+	   city  price
+	0  Lyon    2.0
+	1   Pau    3.0
+	2   Pau    1.0
+	"""
+	column_names = [str(column_name) for column_name in frame.columns]
+	key_columns = [key.column for key in sorting.keys]
+	require_known_columns(key_columns, column_names)
+	sorted_frame = frame
+	reversed_keys = reversed(sorting.keys)
+
+	# A stable sort by the last key first leaves the rows sorted by every key in order.
+	for key in reversed_keys:
+		is_ascending = key.order == Order.ASCENDING
+		missing_place = MISSING_PLACES[key.missing]
+		sorted_frame = sorted_frame.sort_values(
+			by=key.column,
+			ascending=is_ascending,
+			na_position=missing_place,
+			kind=STABLE_SORT,
+		)
+
+	numbered_frame = sorted_frame.reset_index(drop=True)
+
+	return numbered_frame

numdaplot/tables/sorting/sorting.py

@@ -0,0 +1,82 @@
+"""
+Settings of the sort 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.columns.column_names import require_unique_names
+from numdaplot.tables.sorting.sort_key import SortKey
+
+SORT_KEY_ITEM_NAME = "sort key"
+
+
+@dataclass(frozen=True)
+class Sorting:
+	"""
+	Columns the rows of a Table are sorted by, used by ``Table.sort``.
+
+	Rows are sorted by the first key, then rows with the same value by the second key, and so on.
+	Rows equal on every key keep their order.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	keys
+		The sort keys, at least one, each on a different column. The sorting keeps its own copy of the list.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	EmptyListError
+		When ``keys`` is empty.
+	DuplicateColumnError
+		When two keys sort the same column.
+
+	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})
+	>>> by_city = ndp.SortKey(column="city")
+	>>> by_price = ndp.SortKey(column="price", order=ndp.Order.DESCENDING)
+	>>> sales.sort(ndp.Sorting(keys=[by_city, by_price]))
+	    city   price
+	    TEXT FLOAT64
+	0   Lyon    80.0
+	1  Paris   150.0
+	2  Paris   120.0
+	"""
+
+	keys: list[SortKey]
+
+	def __post_init__(self) -> None:
+		"""
+		Check the keys and replace them with a copy that only the sorting holds.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		EmptyListError
+			When ``keys`` is empty.
+		DuplicateColumnError
+			When two keys sort the same column.
+		"""
+		require_field_types(self)
+
+		if self.keys == []:
+			raise EmptyListError(SORT_KEY_ITEM_NAME)
+
+		key_columns = [key.column for key in self.keys]
+		require_unique_names(key_columns)
+		keys_copy = list(self.keys)
+		object.__setattr__(self, "keys", keys_copy)

numdaplot/tables/table.py

@@ -0,0 +1,71 @@
+"""
+The ``ndp.Table`` class: named columns, each holding values of one type.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.tables.table_calculation import TableCalculation
+from numdaplot.tables.table_columns import TableColumns
+from numdaplot.tables.table_conversion import TableConversion
+from numdaplot.tables.table_display import TableDisplay
+from numdaplot.tables.table_joining import TableJoining
+from numdaplot.tables.table_layout import TableLayout
+from numdaplot.tables.table_missing import TableMissing
+from numdaplot.tables.table_reading import TableReading
+from numdaplot.tables.table_refusals import TableRefusals
+from numdaplot.tables.table_selection import TableSelection
+from numdaplot.tables.table_writing import TableWriting
+
+
+class Table(
+	TableReading,
+	TableWriting,
+	TableConversion,
+	TableSelection,
+	TableColumns,
+	TableCalculation,
+	TableLayout,
+	TableJoining,
+	TableMissing,
+	TableDisplay,
+	TableRefusals,
+):
+	"""
+	Named columns, each holding values of one type, wrapping a pandas DataFrame.
+
+	A Table never changes: every operation returns a new Table. Its rows are numbered from 0, and renumbered
+	after a filter or a sort. Integer, boolean and text columns accept missing values.
+
+	- Create it with ``from_csv``, ``from_json``, ``from_excel``, ``from_parquet``, ``from_stata``, ``from_sas``,
+	``from_xpt``, ``from_pandas`` or ``from_arrays``.
+	- Write it with ``to_csv``, ``to_json``, ``to_excel``, ``to_parquet`` or ``to_stata``.
+	- Select rows with ``filter`` and ``take``, check values with ``check``, read a column with ``column``.
+	- Change columns with ``choose_columns``, ``rename``, ``convert`` and ``add_column``.
+	- Compute with ``aggregate``, ``pivot_table`` and ``describe``.
+	- Rearrange rows with ``sort`` and ``drop_duplicates``, and combine two Tables with ``join``.
+	- Handle missing values with ``count_missing``, ``preview_missing`` and ``drop_missing``.
+	- Read it with ``row_count``, ``column_names``, ``column_types``, ``to_value``, ``to_pandas`` and ``is_equal``,
+	and show it with ``preview`` or ``print``.
+
+	Calling ``ndp.Table(...)``, comparisons, brackets, ``for``, ``in``, ``len`` and ``bool`` are refused
+	with ``RefusedOperationError``, which names the method to use instead.
+
+	.. 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
+	    city   price
+	    TEXT FLOAT64
+	0  Paris   120.0
+	1   Lyon    80.0
+	2  Paris   150.0
+	>>> sales.row_count
+	3
+	>>> sales.column_names
+	['city', 'price']
+	"""

numdaplot/tables/table_calculation.py

@@ -0,0 +1,172 @@
+"""
+Statistics of a Table: aggregation, pivot table and description.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Self
+
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.tables.aggregation.aggregated_frame import aggregate_frame
+from numdaplot.tables.aggregation.aggregation import Aggregation
+from numdaplot.tables.description.described_frame import describe_frame
+from numdaplot.tables.description.description import Description
+from numdaplot.tables.pivot.pivot_table import PivotTable
+from numdaplot.tables.pivot.pivoted_frame import pivot_frame
+from numdaplot.tables.table_data import TableData
+
+
+class TableCalculation(TableData):
+	"""
+	Statistics of a Table with ``aggregate``, ``pivot_table`` and ``describe``. Missing values are ignored.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def aggregate(self, aggregation: Aggregation) -> Self:
+		"""
+		Return statistics of the whole Table, or of each group of rows.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		aggregation
+			The calculations, and the columns forming the groups.
+
+		Returns
+		-------
+		Self
+			A new Table: the group columns, then one column per calculation; one row per group, sorted by
+			group values with missing values as a group of their own, last. Without groups, a single row.
+			A statistic needing a value gives a missing value for a group without present value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ColumnNotFoundError
+			When a calculation or a group names a column the Table does not have.
+		IncompatibleTypesError
+			When a statistic does not apply to the type of its column.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> cities = ndp.Array.from_list(["Pau", "Lyon", "Pau"])
+		>>> prices = ndp.Array.from_list([10.0, 30.0, 20.0])
+		>>> table = ndp.Table.from_arrays({"city": cities, "price": prices})
+		>>> average_price = ndp.Calculation(column="price", function=ndp.Mean())
+		>>> table.aggregate(ndp.Aggregation(calculations=[average_price], group_by=["city"]))
+		   city price_mean
+		   TEXT    FLOAT64
+		0  Lyon       30.0
+		1   Pau       15.0
+		"""
+		aggregated_frame = aggregate_frame(self._frame, aggregation)
+		aggregated_table = self._wrap(aggregated_frame)
+
+		return aggregated_table
+
+	@checked_arguments
+	def pivot_table(self, pivot: PivotTable) -> Self:
+		"""
+		Return one statistic for each combination of groups of rows and values of a column, as a wide Table.
+
+		``aggregate`` gives one row per combination: ``pivot_table`` gives one column per value of a column, as
+		``Plot.heatmap`` draws them.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		pivot
+			The columns forming the rows and the columns of the result, and the statistic of each cell.
+
+		Returns
+		-------
+		Self
+			A new Table: the columns of ``rows``, then one column per value of ``columns``, named after the value;
+			one row per group, sorted, with missing values as a group of their own, last.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ColumnNotFoundError
+			When a setting names a column the Table does not have.
+		RefusedOperationError
+			When the column of ``columns`` holds missing values: remove them with ``drop_missing``.
+		DuplicateColumnError
+			When a value written as a text is also the name of a column of ``rows``.
+		InvalidColumnNameError
+			When a value written as a text is empty.
+		IncompatibleTypesError
+			When the statistic does not apply to the type of its column.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> hours = ndp.Array.from_list([8, 8, 9])
+		>>> weekdays = ndp.Array.from_list(["Mon", "Tue", "Mon"])
+		>>> fares = ndp.Array.from_list([7.0, 9.0, 5.0])
+		>>> trips = ndp.Table.from_arrays({"hour": hours, "weekday": weekdays, "fare": fares})
+		>>> trip_count = ndp.Calculation(column="fare", function=ndp.Count(missing=ndp.CountedMissing.INCLUDED))
+		>>> trips.pivot_table(ndp.PivotTable(rows=["hour"], columns="weekday", calculation=trip_count))
+		   hour   Mon   Tue
+		  INT64 INT64 INT64
+		0     8     1     1
+		1     9     1     0
+		"""
+		pivoted_frame = pivot_frame(self._frame, pivot)
+		pivoted_table = self._wrap(pivoted_frame)
+
+		return pivoted_table
+
+	@checked_arguments
+	def describe(self, description: Description | None = None) -> Self:
+		"""
+		Return statistics describing columns, one row per statistic and one column per described column.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		description
+			The statistics and the columns. When omitted, every number column is described with the
+			statistics of pandas.
+
+		Returns
+		-------
+		Self
+			A new Table whose first column, ``statistic``, names each statistic, such as ``quantile_25``.
+			A cell is missing when the statistic does not apply to the column or finds no value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ColumnNotFoundError
+			When a described column does not exist.
+		DuplicateColumnError
+			When a described column is named ``statistic``.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> table = ndp.Table.from_arrays({"price": ndp.Array.from_list([10.0, 30.0])})
+		>>> table.describe(ndp.Description(functions=[ndp.Count(), ndp.Mean(), ndp.Max()]))
+		        statistic   price
+		             TEXT FLOAT64
+		0  count_excluded     2.0
+		1            mean    20.0
+		2             max    30.0
+		"""
+		if description is None:
+			description = Description()
+
+		described_frame = describe_frame(self._frame, description)
+		described_table = self._wrap(described_frame)
+
+		return described_table