numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/pivot/pivoted_frame.py

@@ -0,0 +1,244 @@
+"""
+Pivot table of the rows of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any, cast
+
+import numpy
+import pandas
+from numpy.typing import NDArray
+
+from numdaplot.data_types.type import Type
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+from numdaplot.tables.aggregation.aggregated_frame import compute_group_results, take_group_keys
+from numdaplot.tables.aggregation.row_groups import find_row_groups, split_positions
+from numdaplot.tables.columns.column_names import require_known_columns, require_unique_names
+from numdaplot.tables.columns.conversion import Conversion
+from numdaplot.tables.columns.converted_column import convert_column
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.frames.column_values import find_column_missing, find_column_type
+from numdaplot.tables.pivot.pivot_table import PivotTable
+
+MISSING_PIVOT_OPERATION = "Pivoting the column {column_name!r} while it holds missing values"
+MISSING_PIVOT_ALTERNATIVE = "drop_missing with ndp.MissingDrop(columns=[{column_name!r}])"
+DECIMAL_TYPES = frozenset({Type.FLOAT32, Type.FLOAT64})
+FIRST_ROW = 0
+ROW_POSITION_DTYPE = numpy.int64
+
+
+def pivot_frame(frame: pandas.DataFrame, pivot: PivotTable) -> pandas.DataFrame:
+	"""
+	Return one row per group of rows and one column per value of a column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	pivot
+		The columns forming the rows and the columns of the result, and the statistic of each cell.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The columns of ``rows``, then one column per value of ``columns``, both sorted.
+
+	Raises
+	------
+	ColumnNotFoundError
+		When a setting names a column the Table does not have.
+	RefusedOperationError
+		When the column of ``columns`` holds missing values.
+	DuplicateColumnError
+		When a value written as a text is also the name of a column of ``rows``.
+	IncompatibleTypesError
+		When the statistic does not apply to the type of its column.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.pivot.pivoted_frame import pivot_frame
+	>>> days = pandas.Series(["Mon", "Tue", "Mon"], dtype="string")
+	>>> frame = pandas.DataFrame({"hour": [8, 8, 9], "day": days, "fare": [7.0, 9.0, 5.0]})
+	>>> total = ndp.Calculation(column="fare", function=ndp.Sum())
+	>>> pivot_frame(frame, ndp.PivotTable(rows=["hour"], columns="day", calculation=total))
+	   hour  Mon  Tue
+	0     8  7.0  9.0
+	1     9  5.0  0.0
+	"""
+	column_names = [str(column_name) for column_name in frame.columns]
+	calculation = pivot.calculation
+	requested_names = [*pivot.rows, pivot.columns, calculation.column]
+	require_known_columns(requested_names, column_names)
+	pivot_column = frame[pivot.columns]
+	require_present_pivot_values(pivot_column, pivot.columns)
+	row_groups = find_row_groups(frame, pivot.rows)
+	column_groups = find_row_groups(frame, [pivot.columns])
+	value_names = name_value_columns(pivot_column, column_groups, pivot.columns)
+	output_names = [*pivot.rows, *value_names]
+	require_unique_names(output_names)
+	row_count = len(frame)
+	group_numbers = number_row_groups(row_groups, row_count)
+	group_count = len(row_groups)
+	result_columns = take_group_keys(frame, pivot.rows, row_groups)
+	value_column = frame[calculation.column]
+
+	for value_name, column_rows in zip(value_names, column_groups, strict=True):
+		column_group_numbers = group_numbers[column_rows]
+		cell_rows = split_positions(column_rows, column_group_numbers, group_count)
+		result_columns[value_name] = compute_group_results(value_column, calculation.function, cell_rows)
+
+	result_numbers = pandas.RangeIndex(group_count)
+	pivoted_frame = pandas.DataFrame(result_columns, index=result_numbers)
+
+	return pivoted_frame
+
+
+def require_present_pivot_values(pivot_column: Column, column_name: str) -> None:
+	"""
+	Check that the column giving its values to the result columns holds no missing value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	pivot_column
+		The column.
+	column_name
+		Its name.
+
+	Raises
+	------
+	RefusedOperationError
+		When the column holds a missing value, which could not name a result column.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.pivot.pivoted_frame import require_present_pivot_values
+	>>> try:
+	... 	require_present_pivot_values(pandas.Series(["Mon", None], dtype="string"), "day")
+	... except ndp.RefusedOperationError as error:
+	... 	print(error)
+	Pivoting the column 'day' while it holds missing values is not available,
+	use drop_missing with ndp.MissingDrop(columns=['day']) instead.
+	"""
+	missing = find_column_missing(pivot_column)
+	has_missing = bool(missing.any())
+	if has_missing:
+		operation = MISSING_PIVOT_OPERATION.format(column_name=column_name)
+		alternative = MISSING_PIVOT_ALTERNATIVE.format(column_name=column_name)
+		raise RefusedOperationError(operation, alternative)
+
+
+def name_value_columns(pivot_column: Column, column_groups: list[NDArray[Any]], column_name: str) -> list[str]:
+	"""
+	Return the name of the result column of each value, the value written as a text.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	pivot_column
+		The column giving its values to the result columns.
+	column_groups
+		The rows of each value.
+	column_name
+		The name of the column.
+
+	Returns
+	-------
+	list[str]
+		One name per group. A whole decimal is written without decimal part.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import pandas
+	>>> from numdaplot.tables.pivot.pivoted_frame import name_value_columns
+	>>> name_value_columns(pandas.Series([1.0, 2.5]), [numpy.array([0]), numpy.array([1])], "hour")
+	['1', '2.5']
+	"""
+	first_row_list = [column_group[FIRST_ROW] for column_group in column_groups]
+	first_rows = numpy.array(first_row_list, dtype=ROW_POSITION_DTYPE)
+	first_values = pivot_column.iloc[first_rows]
+	source_type = find_column_type(pivot_column)
+	if source_type in DECIMAL_TYPES:
+		decimals = cast(list[float], first_values.tolist())
+		decimal_names = [write_decimal(decimal) for decimal in decimals]
+		return decimal_names
+
+	text_conversion = Conversion(column=column_name, dtype=Type.TEXT)
+	value_texts = convert_column(first_values, text_conversion)
+	value_names = cast(list[str], value_texts.tolist())
+
+	return value_names
+
+
+def write_decimal(decimal: float) -> str:
+	"""
+	Return a decimal written as a text, without decimal part when it is whole.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	decimal
+		The decimal.
+
+	Returns
+	-------
+	str
+		The text.
+
+	Examples
+	--------
+	>>> from numdaplot.tables.pivot.pivoted_frame import write_decimal
+	>>> write_decimal(8.0)
+	'8'
+	>>> write_decimal(2.5)
+	'2.5'
+	"""
+	if decimal.is_integer():
+		whole_number = int(decimal)
+		return str(whole_number)
+
+	return str(decimal)
+
+
+def number_row_groups(row_groups: list[NDArray[Any]], row_count: int) -> NDArray[Any]:
+	"""
+	Return the number of the group of each row.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	row_groups
+		The rows of each group, every row being in one group.
+	row_count
+		The number of rows.
+
+	Returns
+	-------
+	NDArray
+		One group number per row.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.tables.pivot.pivoted_frame import number_row_groups
+	>>> number_row_groups([numpy.array([1]), numpy.array([0, 2])], 3)
+	array([1, 0, 1])
+	"""
+	group_numbers = numpy.zeros(row_count, dtype=ROW_POSITION_DTYPE)
+
+	for group_number, row_group in enumerate(row_groups):
+		group_numbers[row_group] = group_number
+
+	return group_numbers

numdaplot/tables/preview/__init__.py

@@ -0,0 +1,5 @@
+"""
+Display of a few rows of a Table.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/tables/preview/notebook_display.py

@@ -0,0 +1,238 @@
+"""
+Display of a Table in a terminal or in a Jupyter notebook.
+
+.. versionadded:: 0.1.0
+"""
+
+from importlib import import_module
+from importlib.util import find_spec
+
+import pandas
+
+from numdaplot.tables.frames.table_text import build_typed_frame, format_table, write_empty_table_note
+from numdaplot.tables.preview.shown_columns import ShownColumns
+
+IPYTHON_PACKAGE = "IPython"
+IPYTHON_DISPLAY_MODULE = "IPython.display"
+NOTEBOOK_KERNEL = "IPKernelApp"
+COMPACT_NOTEBOOK_COLUMN_COUNT = 10
+NOTE_HTML = "<p>{note}</p>"
+MAX_ROWS_OPTION = "display.max_rows"
+MIN_ROWS_OPTION = "display.min_rows"
+
+
+def show_frame(frame: pandas.DataFrame, shown_columns: ShownColumns) -> None:
+	"""
+	Show the columns of a Table: as an HTML table in a Jupyter notebook, as text anywhere else.
+
+	The type of each column is shown under its name.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The rows to show.
+	shown_columns
+		Whether every column is shown. A compact HTML table shows 10 columns.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.preview.notebook_display import show_frame
+	>>> show_frame(pandas.DataFrame({"price": [1.5]}), ndp.ShownColumns.ALL)
+	    price
+	  FLOAT64
+	0     1.5
+	"""
+	runs_in_notebook = is_notebook()
+	if not runs_in_notebook:
+		table_text = format_table(frame, shown_columns)
+		print(table_text)
+		return
+
+	table_html = format_table_html(frame, shown_columns)
+	display_html(table_html)
+
+
+def format_table_html(frame: pandas.DataFrame, shown_columns: ShownColumns) -> str:
+	"""
+	Return the HTML table of the columns of a Table, with the type of each column under its name.
+
+	A long Table only shows its first and last rows, following the pandas display settings, as its text does.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	shown_columns
+		Whether every column is shown. A compact HTML table shows 10 columns.
+
+	Returns
+	-------
+	str
+		The HTML table, followed by a note for a Table without rows, or only the note for a Table without columns.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.preview.notebook_display import format_table_html
+	>>> table_html = format_table_html(pandas.DataFrame({"price": [1.5]}), ndp.ShownColumns.ALL)
+	>>> "FLOAT64" in table_html
+	True
+	"""
+	note = write_empty_table_note(frame)
+	column_count = len(frame.columns)
+	if column_count == 0:
+		note_html = NOTE_HTML.format(note=note)
+		return note_html
+
+	typed_frame = build_typed_frame(frame)
+	column_limit = None
+	are_columns_left_out = False
+	if shown_columns == ShownColumns.COMPACT:
+		column_limit = COMPACT_NOTEBOOK_COLUMN_COUNT
+		are_columns_left_out = column_count > column_limit
+
+	row_count = len(frame.index)
+	row_limit = find_shown_row_count(row_count)
+	are_rows_left_out = row_limit is not None
+	# pandas writes the size of the Table under it, as in its text, only when rows or columns are left out.
+	shows_size = are_rows_left_out or are_columns_left_out
+	table_html = typed_frame.to_html(max_rows=row_limit, max_cols=column_limit, show_dimensions=shows_size)
+	if note is not None:
+		note_html = NOTE_HTML.format(note=note)
+		table_html += note_html
+
+	return table_html
+
+
+def find_shown_row_count(row_count: int) -> int | None:
+	"""
+	Return how many rows pandas shows for a Table of this length.
+
+	pandas shows every row up to ``display.max_rows``, and only ``display.min_rows`` of them, the first and last
+	ones, beyond it. A missing ``display.min_rows`` or one above ``display.max_rows`` shows ``display.max_rows`` rows.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	row_count
+		The number of rows of the Table.
+
+	Returns
+	-------
+	int or None
+		The number of rows shown, or None to show every row.
+
+	Examples
+	--------
+	>>> from numdaplot.tables.preview.notebook_display import find_shown_row_count
+	>>> find_shown_row_count(5) is None
+	True
+	>>> find_shown_row_count(1000)
+	10
+	"""
+	max_rows = pandas.get_option(MAX_ROWS_OPTION)
+	if max_rows is None:
+		return None
+
+	if row_count <= max_rows:
+		return None
+
+	min_rows = pandas.get_option(MIN_ROWS_OPTION)
+	if min_rows is None:
+		return max_rows
+
+	shown_row_count = min(min_rows, max_rows)
+
+	return shown_row_count
+
+
+def show_pandas_frame(frame: pandas.DataFrame) -> None:
+	"""
+	Show a pandas DataFrame as it is: as an HTML table in a Jupyter notebook, as text anywhere else.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The rows to show, with their header.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.preview.notebook_display import show_pandas_frame
+	>>> show_pandas_frame(pandas.DataFrame({"price": [1.5]}))
+	   price
+	0    1.5
+	"""
+	runs_in_notebook = is_notebook()
+	if not runs_in_notebook:
+		frame_text = repr(frame)
+		print(frame_text)
+		return
+
+	frame_html = frame.to_html()
+	display_html(frame_html)
+
+
+def display_html(frame_html: str) -> None:
+	"""
+	Show an HTML table in a Jupyter notebook.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame_html
+		The HTML table.
+
+	Examples
+	--------
+	>>> from numdaplot.tables.preview.notebook_display import display_html, is_notebook
+	>>> if is_notebook():
+	... 	display_html("<table></table>")
+	"""
+	display_module = import_module(IPYTHON_DISPLAY_MODULE)
+	html_object = display_module.HTML(frame_html)
+	display_module.display(html_object)
+
+
+def is_notebook() -> bool:
+	"""
+	Return whether the code runs in a Jupyter notebook.
+
+	IPython is optional: without it, the code never runs in a notebook.
+
+	.. versionadded:: 0.1.0
+
+	Returns
+	-------
+	bool
+		True inside a Jupyter kernel, False in a terminal or a script.
+
+	Examples
+	--------
+	>>> from numdaplot.tables.preview.notebook_display import is_notebook
+	>>> is_notebook()
+	False
+	"""
+	ipython_spec = find_spec(IPYTHON_PACKAGE)
+	if ipython_spec is None:
+		return False
+
+	ipython_module = import_module(IPYTHON_PACKAGE)
+	shell = ipython_module.get_ipython()
+	if shell is None:
+		return False
+
+	runs_in_kernel = NOTEBOOK_KERNEL in shell.config
+
+	return runs_in_kernel

numdaplot/tables/preview/preview.py

@@ -0,0 +1,100 @@
+"""
+Settings of the preview of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.arrays.creation.random_values import require_valid_seed
+from numdaplot.errors.invalid_count_error import InvalidCountError
+from numdaplot.errors.refused_setting_error import RefusedSettingError
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.preview.shown_columns import ShownColumns
+from numdaplot.tables.preview.side import Side
+
+DEFAULT_PREVIEW_COUNT = 5
+MINIMUM_PREVIEW_COUNT = 1
+SEED_SETTING = "seed"
+SIDE_OWNER = "Side.{side_name}"
+
+
+@dataclass(frozen=True)
+class Preview:
+	"""
+	How many rows of a Table to show, which ones, and how its columns are shown, used by ``Table.preview``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	count
+		The number of rows, 5 by default. A shorter Table shows all its rows.
+	side
+		The first rows, ``Side.START`` by default, the last rows, ``Side.END``, or rows drawn at random,
+		``Side.RANDOM``.
+	seed
+		The seed of the random draw, to show the same rows each time, other rows at each call when omitted. Only
+		``Side.RANDOM`` accepts it.
+	columns
+		``ShownColumns.ALL`` by default to show every column, going on after a line break when they do not fit, or
+		``ShownColumns.COMPACT`` to replace those that do not fit by ``...``.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidCountError
+		When ``count`` is lower than 1.
+	InvalidSeedError
+		When ``seed`` is negative.
+	RefusedSettingError
+		When ``seed`` is given with ``Side.START`` or ``Side.END``, which draw nothing.
+
+	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))
+	    city   price
+	    TEXT FLOAT64
+	0  Paris   120.0
+	1   Lyon    80.0
+	"""
+
+	count: int = DEFAULT_PREVIEW_COUNT
+	side: Side = Side.START
+	seed: int | None = None
+	columns: ShownColumns = ShownColumns.ALL
+
+	def __post_init__(self) -> None:
+		"""
+		Check the side, the count and the seed, which only a random draw uses.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidCountError
+			When ``count`` is lower than 1.
+		InvalidSeedError
+			When ``seed`` is negative.
+		RefusedSettingError
+			When ``seed`` is given with ``Side.START`` or ``Side.END``.
+		"""
+		require_field_types(self)
+
+		if self.count < MINIMUM_PREVIEW_COUNT:
+			raise InvalidCountError(self.count, MINIMUM_PREVIEW_COUNT)
+
+		if self.seed is None:
+			return
+
+		require_valid_seed(self.seed)
+		if self.side != Side.RANDOM:
+			side_owner = SIDE_OWNER.format(side_name=self.side.name)
+			raise RefusedSettingError(SEED_SETTING, side_owner)

numdaplot/tables/preview/preview_rows.py

@@ -0,0 +1,55 @@
+"""
+Rows of a Table shown by a preview.
+
+.. versionadded:: 0.1.0
+"""
+
+import numpy
+import pandas
+
+from numdaplot.tables.preview.preview import Preview
+from numdaplot.tables.preview.side import Side
+
+
+def choose_preview_rows(frame: pandas.DataFrame, preview: Preview) -> pandas.DataFrame:
+	"""
+	Return the rows of a Table that a preview shows, with their row numbers.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	preview
+		How many rows, and which ones.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The chosen rows, in the order of the Table, keeping their numbers in the Table.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.preview.preview_rows import choose_preview_rows
+	>>> frame = pandas.DataFrame({"price": [1.0, 2.0, 3.0]})
+	>>> choose_preview_rows(frame, ndp.Preview(count=2, side=ndp.Side.END))
+	   price
+	1    2.0
+	2    3.0
+	"""
+	match preview.side:
+		case Side.START:
+			chosen_rows = frame.head(preview.count)
+		case Side.END:
+			chosen_rows = frame.tail(preview.count)
+		case Side.RANDOM:
+			row_count = len(frame)
+			drawn_count = min(preview.count, row_count)
+			generator = numpy.random.default_rng(preview.seed)
+			drawn_rows = frame.sample(n=drawn_count, random_state=generator)
+			chosen_rows = drawn_rows.sort_index()
+
+	return chosen_rows

numdaplot/tables/preview/shown_columns.py

@@ -0,0 +1,62 @@
+"""
+Which columns of a Table a preview shows.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class ShownColumns(Enum):
+	"""
+	Which columns of a Table ``Preview`` shows when they do not fit in the width of the terminal.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon"])
+	>>> prices = ndp.Array.from_list([120.0, 80.0])
+	>>> sales = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> sales.preview(ndp.Preview(columns=ndp.ShownColumns.ALL))
+	    city   price
+	    TEXT FLOAT64
+	0  Paris   120.0
+	1   Lyon    80.0
+	"""
+
+	ALL = auto()
+	"""
+	Every column, the columns going on after a line break, ended by a backslash, when they do not fit. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon"])
+	>>> prices = ndp.Array.from_list([120.0, 80.0])
+	>>> sales = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> sales.preview(ndp.Preview(columns=ndp.ShownColumns.ALL))
+	    city   price
+	    TEXT FLOAT64
+	0  Paris   120.0
+	1   Lyon    80.0
+	"""
+
+	COMPACT = auto()
+	"""
+	Only the first and last columns that fit, the others replaced by ``...``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> long_name = "a_very_long_column_name_{number}"
+	>>> columns = {long_name.format(number=number): ndp.Array.from_list([number]) for number in range(6)}
+	>>> wide_table = ndp.Table.from_arrays(columns)
+	>>> wide_table.preview(ndp.Preview(columns=ndp.ShownColumns.COMPACT))
+	  a_very_long_column_name_0  ... a_very_long_column_name_5
+	                      INT64  ...                     INT64
+	0                         0  ...                         5
+	<BLANKLINE>
+	[1 rows x 6 columns]
+	"""