numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/frames/region_positions.py

@@ -0,0 +1,113 @@
+"""
+Rows and columns of a Table chosen by a Region.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+import pandas
+from numpy.typing import NDArray
+
+from numdaplot.arrays.selection.region_index import find_positions
+from numdaplot.positions.index import Index
+from numdaplot.positions.range import Range
+from numdaplot.positions.region import Region
+from numdaplot.tables.columns.column_names import require_known_columns, require_unique_names
+
+POSITION_DTYPE = numpy.int64
+
+
+def take_region(frame: pandas.DataFrame, region: Region) -> pandas.DataFrame:
+	"""
+	Return the rows and the columns of a Table chosen by a Region.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	region
+		The rows and the columns to take, every one of a dimension when omitted.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The chosen part, rows numbered from 0, columns in the order of the region.
+
+	Raises
+	------
+	InvalidPositionError
+		When a position is not a whole number inside its dimension.
+	ColumnNotFoundError
+		When a column name matches no column.
+	DuplicateColumnError
+		When a column name appears twice in the region.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.frames.region_positions import take_region
+	>>> frame = pandas.DataFrame({"city": ["Paris", "Lyon"], "price": [1.5, 8.0]})
+	>>> take_region(frame, ndp.Region(rows=ndp.Index(-1), columns=["price"]))
+	   price
+	0    8.0
+	"""
+	row_count = len(frame)
+	row_positions = find_positions(region.rows, row_count)
+	column_names = [str(column_name) for column_name in frame.columns]
+	column_positions = find_column_positions(region.columns, column_names)
+	region_frame = frame.iloc[row_positions, column_positions]
+	numbered_frame = region_frame.reset_index(drop=True)
+
+	return numbered_frame
+
+
+def find_column_positions(columns: Index | Range | list[str] | None, column_names: list[str]) -> NDArray[Any]:
+	"""
+	Return the positions of the columns chosen by a Region.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	columns
+		One position, a sequence of positions, a list of names, or ``None`` for every column.
+	column_names
+		The names of the columns of the Table.
+
+	Returns
+	-------
+	NDArray
+		The chosen positions, in the order of the region.
+
+	Raises
+	------
+	InvalidPositionError
+		When a position is not a whole number inside the columns.
+	ColumnNotFoundError
+		When a name matches no column.
+	DuplicateColumnError
+		When a name appears twice.
+
+	Examples
+	--------
+	>>> from numdaplot.tables.frames.region_positions import find_column_positions
+	>>> find_column_positions(["price", "city"], ["city", "price"])
+	array([1, 0])
+	"""
+	if not isinstance(columns, list):
+		column_count = len(column_names)
+		positions = find_positions(columns, column_count)
+		return positions
+
+	require_unique_names(columns)
+	require_known_columns(columns, column_names)
+	positions_by_name = {column_name: position for position, column_name in enumerate(column_names)}
+	named_positions = [positions_by_name[column_name] for column_name in columns]
+	positions = numpy.array(named_positions, dtype=POSITION_DTYPE)
+
+	return positions

numdaplot/tables/frames/table_text.py

@@ -0,0 +1,222 @@
+"""
+Text of a Table, with the type of each column under its name.
+
+.. versionadded:: 0.1.0
+"""
+
+from shutil import get_terminal_size
+
+import pandas
+
+from numdaplot.tables.frames.column_values import find_column_type
+from numdaplot.tables.frames.time_columns import is_time_column, write_time_texts_column
+from numdaplot.tables.frames.time_zones import name_column_type
+from numdaplot.tables.preview.shown_columns import ShownColumns
+
+MAX_COLUMNS_OPTION = "display.max_columns"
+WIDTH_OPTION = "display.width"
+# In pandas, no limit shows every column, and a limit of 0 only shows those fitting in the width.
+NO_ROWS_NOTE = "(0 rows)"
+NO_COLUMNS_NOTE = "(no columns, {rows_text})"
+ONE_ROW_TEXT = "1 row"
+ROWS_TEXT = "{row_count} rows"
+BLANK_CELL = ""
+BLANK_ROW_START = "0"
+LINE_BREAK = "\n"
+SHOW_DIMENSIONS_OPTION = "display.show_dimensions"
+COLUMN_LIMITS = {
+	ShownColumns.ALL: None,
+	ShownColumns.COMPACT: 0,
+}
+
+
+def build_typed_frame(frame: pandas.DataFrame) -> pandas.DataFrame:
+	"""
+	Return a copy of the columns of a Table whose header shows the name, then the type, of each column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+
+	Returns
+	-------
+	pandas.DataFrame
+		A copy with a two-level header: the column names, then the names of their ``ndp.Type``, followed by
+		the time zone of a datetime column that has one.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.table_text import build_typed_frame
+	>>> build_typed_frame(pandas.DataFrame({"price": [1.5]})).columns.tolist()
+	[('price', 'FLOAT64')]
+	"""
+	column_names = list(frame.columns)
+	type_names = list[str]()
+
+	for column_name in column_names:
+		column = frame[column_name]
+		column_type = find_column_type(column)
+		type_name = name_column_type(column, column_type)
+		type_names.append(type_name)
+
+	header = pandas.MultiIndex.from_arrays([column_names, type_names])
+	typed_frame = frame.copy()
+	for column_name in column_names:
+		column = frame[column_name]
+		if is_time_column(column):
+			typed_frame[column_name] = write_time_texts_column(column)
+
+	typed_frame.columns = header
+
+	return typed_frame
+
+
+def format_table(frame: pandas.DataFrame, shown_columns: ShownColumns = ShownColumns.ALL) -> str:
+	"""
+	Return the text pandas shows for 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. The columns follow the
+	width of the terminal, whatever the pandas display settings.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	shown_columns
+		``ShownColumns.ALL`` by default for every column, going on after a line break when they do not fit, or
+		``ShownColumns.COMPACT`` to replace those that do not fit by ``...``.
+
+	Returns
+	-------
+	str
+		The text of the Table, with row numbers on the left.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.table_text import format_table
+	>>> print(format_table(pandas.DataFrame({"price": [1.5, 8.0]})))
+	    price
+	  FLOAT64
+	0     1.5
+	1     8.0
+	"""
+	empty_table_text = format_empty_table(frame, shown_columns)
+	if empty_table_text is not None:
+		return empty_table_text
+
+	typed_frame = build_typed_frame(frame)
+	column_limit = COLUMN_LIMITS[shown_columns]
+	terminal_size = get_terminal_size()
+	with pandas.option_context(MAX_COLUMNS_OPTION, column_limit, WIDTH_OPTION, terminal_size.columns):
+		table_text = repr(typed_frame)
+
+	return table_text
+
+
+def write_empty_table_note(frame: pandas.DataFrame) -> str | None:
+	"""
+	Return the note replacing the rows of a Table without rows or without columns.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+
+	Returns
+	-------
+	str or None
+		``(0 rows)``, ``(no columns, 2 rows)``, or None for a Table with values.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.table_text import write_empty_table_note
+	>>> write_empty_table_note(pandas.DataFrame({"price": [1.5]})) is None
+	True
+	>>> write_empty_table_note(pandas.DataFrame(index=[0, 1]))
+	'(no columns, 2 rows)'
+	>>> write_empty_table_note(pandas.DataFrame(index=[0]))
+	'(no columns, 1 row)'
+	"""
+	row_count = len(frame.index)
+	column_count = len(frame.columns)
+	if column_count == 0:
+		rows_text = ONE_ROW_TEXT if row_count == 1 else ROWS_TEXT.format(row_count=row_count)
+		no_columns_note = NO_COLUMNS_NOTE.format(rows_text=rows_text)
+		return no_columns_note
+
+	if row_count == 0:
+		return NO_ROWS_NOTE
+
+	return None
+
+
+def format_empty_table(frame: pandas.DataFrame, shown_columns: ShownColumns) -> str | None:
+	"""
+	Return the text of a Table without rows or without columns: its header if any, then a note.
+
+	pandas writes such a Table with its own words, so the header comes from a Table of one blank row.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	shown_columns
+		``ShownColumns.ALL`` for every column, or ``ShownColumns.COMPACT`` to replace those that do not fit by ``...``.
+
+	Returns
+	-------
+	str or None
+		The text, or None for a Table with values.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.table_text import format_empty_table
+	>>> from numdaplot.tables.preview.shown_columns import ShownColumns
+	>>> prices = pandas.DataFrame({"price": pandas.Series(dtype="float64")})
+	>>> print(format_empty_table(prices, ShownColumns.ALL))
+	    price
+	  FLOAT64
+	(0 rows)
+	"""
+	note = write_empty_table_note(frame)
+	if note is None:
+		return None
+
+	column_count = len(frame.columns)
+	if column_count == 0:
+		return note
+
+	typed_frame = build_typed_frame(frame)
+	blank_row = [[BLANK_CELL] * column_count]
+	blank_frame = pandas.DataFrame(blank_row, columns=typed_frame.columns)
+	column_limit = COLUMN_LIMITS[shown_columns]
+	terminal_size = get_terminal_size()
+	with pandas.option_context(
+		MAX_COLUMNS_OPTION,
+		column_limit,
+		WIDTH_OPTION,
+		terminal_size.columns,
+		SHOW_DIMENSIONS_OPTION,
+		False,
+	):
+		blank_text = repr(blank_frame)
+
+	lines = blank_text.splitlines()
+	header_lines = [line for line in lines if not line.startswith(BLANK_ROW_START)]
+	empty_table_lines = [*header_lines, note]
+	empty_table_text = LINE_BREAK.join(empty_table_lines)
+
+	return empty_table_text

numdaplot/tables/frames/time_columns.py

@@ -0,0 +1,345 @@
+"""
+Table columns of times of day, and the durations a Table reads from outside numdaplot.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any, cast
+
+import numpy
+import pandas
+from numpy.typing import NDArray
+
+from numdaplot.arrays.conversion.time_text import format_times
+from numdaplot.data_types.time_of_day import TIME_DTYPE, read_time_objects, store_time_objects
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.frames.time_range_errors import TimeRangeErrors
+
+DURATION_KIND = "m"
+NANOSECOND_DURATION_DTYPE = numpy.dtype("timedelta64[ns]")
+PYTHON_OBJECT_DTYPE = numpy.dtype(object)
+TEXT_PANDAS_DTYPE = "string"
+TABLE_CREATION_OPERATION = "Table creation"
+
+
+def is_time_column(column: Column) -> bool:
+	"""
+	Return whether a Table column stores times of day.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column.
+
+	Returns
+	-------
+	bool
+		True for a column in ``timedelta64[us]``.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.time_columns import is_time_column
+	>>> import numpy
+	>>> is_time_column(pandas.Series(numpy.array([1], dtype="timedelta64[us]"))), is_time_column(pandas.Series([1]))
+	(True, False)
+	"""
+	holds_times = column.dtype == TIME_DTYPE
+
+	return holds_times
+
+
+def read_time_objects_column(column: Column) -> Column:
+	"""
+	Return a column of times of day as Python ``datetime.time`` objects, None where missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column of times of day.
+
+	Returns
+	-------
+	Column
+		An object column with the same index.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.time_columns import read_time_objects_column
+	>>> import numpy
+	>>> minutes = pandas.Series(numpy.array([60000000], dtype="timedelta64[us]"))
+	>>> read_time_objects_column(minutes).tolist()
+	[datetime.time(0, 1)]
+	"""
+	stored_times = column.to_numpy(dtype=TIME_DTYPE)
+	time_objects = read_time_objects(stored_times)
+	object_column = pandas.Series(time_objects, index=column.index, name=column.name, dtype=PYTHON_OBJECT_DTYPE)
+
+	return object_column
+
+
+def store_time_column(column: Column) -> Column:
+	"""
+	Return a column of Python times of day stored as the time since midnight.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		An object column of ``datetime.time`` and missing values.
+
+	Returns
+	-------
+	Column
+		A column in ``timedelta64[us]`` with the same index, NaT where missing.
+
+	Examples
+	--------
+	>>> from datetime import time
+	>>> import pandas
+	>>> from numdaplot.tables.frames.time_columns import store_time_column
+	>>> store_time_column(pandas.Series([time(0, 1), None], dtype=object)).tolist()
+	[Timedelta('0 days 00:01:00'), NaT]
+	"""
+	object_values = read_object_values(column)
+	stored_times = store_time_objects(object_values)
+	time_column = pandas.Series(stored_times, index=column.index, name=column.name)
+
+	return time_column
+
+
+def read_object_values(column: Column) -> NDArray[Any]:
+	"""
+	Return the values of a column as Python objects, None where missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A column of any dtype.
+
+	Returns
+	-------
+	NDArray
+		An object array, None for every missing marker such as NaN or ``pd.NA``.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.time_columns import read_object_values
+	>>> read_object_values(pandas.Series(["a", float("nan")], dtype=object))
+	array(['a', None], dtype=object)
+	"""
+	missing = column.isna()
+	missing_flags = missing.to_numpy(dtype=bool)
+	# Some versions of the numpy stubs refuse None as a value of an object array.
+	object_values = cast(Any, column.to_numpy(dtype=PYTHON_OBJECT_DTYPE, copy=True))
+	object_values[missing_flags] = None
+
+	return object_values
+
+
+def convert_outside_durations(frame: pandas.DataFrame) -> pandas.DataFrame:
+	"""
+	Return a DataFrame read from outside numdaplot whose durations, of any unit, are stored in nanoseconds.
+
+	Microseconds store the times of day, so an outside duration in microseconds must not keep them.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		A DataFrame read from a file or given by the user. It is not changed.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The DataFrame, a copy with its duration columns in ``timedelta64[ns]`` when it has some.
+
+	Raises
+	------
+	TimeOverflowError
+		When a duration is beyond about 292 years, which nanoseconds cannot hold.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.time_columns import convert_outside_durations
+	>>> import numpy
+	>>> frame = pandas.DataFrame({"wait": numpy.array([5], dtype="timedelta64[us]")})
+	>>> convert_outside_durations(frame).dtypes.tolist()
+	[dtype('<m8[ns]')]
+	"""
+	duration_names = [name for name in frame.columns if frame[name].dtype.kind == DURATION_KIND]
+	if duration_names == []:
+		return frame
+
+	converted_frame = frame.copy(deep=False)
+	for column_name in duration_names:
+		column = frame[column_name]
+		duration_values = column.to_numpy()
+		nanosecond_values = convert_to_nanoseconds(duration_values, str(column_name))
+		nanosecond_column = pandas.Series(nanosecond_values, index=column.index, name=column.name)
+		converted_frame[column_name] = nanosecond_column
+
+	return converted_frame
+
+
+def convert_to_nanoseconds(durations: NDArray[Any], column_name: str) -> NDArray[Any]:
+	"""
+	Return durations of any unit in nanoseconds, refusing those that nanoseconds cannot hold.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	durations
+		Durations in ``timedelta64`` of any unit.
+	column_name
+		The name of the column holding them, named by the error.
+
+	Returns
+	-------
+	NDArray
+		The durations in ``timedelta64[ns]``.
+
+	Raises
+	------
+	TimeOverflowError
+		When a duration is beyond about 292 years.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.tables.frames.time_columns import convert_to_nanoseconds
+	>>> convert_to_nanoseconds(numpy.array([2], dtype="timedelta64[s]"), "wait")
+	array([2000000000], dtype='timedelta64[ns]')
+	"""
+	with TimeRangeErrors(TABLE_CREATION_OPERATION, column_name):
+		try:
+			nanosecond_values = durations.astype(NANOSECOND_DURATION_DTYPE)
+		except OverflowError as error:
+			raise pandas.errors.OutOfBoundsTimedelta from error
+
+		# Some versions of numpy wrap a duration beyond the range of nanoseconds instead of raising.
+		original_values = nanosecond_values.astype(durations.dtype)
+		is_kept = (original_values == durations) | numpy.isnat(durations)
+		is_exact = bool(is_kept.all())
+		if not is_exact:
+			raise pandas.errors.OutOfBoundsTimedelta
+
+	return nanosecond_values
+
+
+def read_time_objects_frame(frame: pandas.DataFrame) -> pandas.DataFrame:
+	"""
+	Return a DataFrame whose columns of times of day hold Python ``datetime.time`` objects.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table. It is not changed.
+
+	Returns
+	-------
+	pandas.DataFrame
+		A deep copy, each column of times of day as an object column.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.time_columns import read_time_objects_frame
+	>>> import numpy
+	>>> frame = pandas.DataFrame({"hour": numpy.array([60000000], dtype="timedelta64[us]")})
+	>>> read_time_objects_frame(frame)["hour"].tolist()
+	[datetime.time(0, 1)]
+	"""
+	frame_copy = frame.copy(deep=True)
+	for column_name in frame.columns:
+		column = frame[column_name]
+		if is_time_column(column):
+			object_column = read_time_objects_column(column)
+			frame_copy[column_name] = object_column
+
+	return frame_copy
+
+
+def write_time_texts_column(column: Column) -> Column:
+	"""
+	Return a column of times of day as texts, such as ``15:35:00``, ``NaT`` where missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column of times of day.
+
+	Returns
+	-------
+	Column
+		An object column of texts with the same index.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.time_columns import write_time_texts_column
+	>>> import numpy
+	>>> hours = pandas.Series(numpy.array([56100000000, "NaT"], dtype="timedelta64[us]"))
+	>>> write_time_texts_column(hours).tolist()
+	['15:35:00', 'NaT']
+	"""
+	stored_times = column.to_numpy(dtype=TIME_DTYPE)
+	time_texts = format_times(stored_times)
+	text_column = pandas.Series(time_texts, index=column.index, name=column.name, dtype=PYTHON_OBJECT_DTYPE)
+
+	return text_column
+
+
+def write_time_texts_frame(frame: pandas.DataFrame) -> pandas.DataFrame:
+	"""
+	Return a DataFrame whose columns of times of day are written as texts, missing where a time is missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table. It is not changed.
+
+	Returns
+	-------
+	pandas.DataFrame
+		A copy, each column of times of day as texts such as ``15:35:00``.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import pandas
+	>>> from numdaplot.tables.frames.time_columns import write_time_texts_frame
+	>>> frame = pandas.DataFrame({"hour": numpy.array([56100000000, "NaT"], dtype="timedelta64[us]")})
+	>>> write_time_texts_frame(frame)["hour"].tolist()
+	['15:35:00', <NA>]
+	"""
+	text_frame = frame.copy()
+	for column_name in frame.columns:
+		column = frame[column_name]
+		if is_time_column(column):
+			time_texts = write_time_texts_column(column)
+			missing = column.isna()
+			# Some versions of the pandas stubs leave the types of mask partly unknown.
+			text_column = cast(Any, time_texts)
+			present_texts = cast(Column, text_column.mask(missing))
+			text_frame[column_name] = present_texts.astype(TEXT_PANDAS_DTYPE)
+
+	return text_frame