numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/aggregation/calculation.py

@@ -0,0 +1,123 @@
+"""
+A statistic computed on a column of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.statistics.statistic import Statistic
+from numdaplot.tables.aggregation.statistic_name import name_statistic
+from numdaplot.tables.columns.column_names import require_column_name
+
+RESULT_NAME = "{column}_{function}"
+
+
+@dataclass(frozen=True)
+class Calculation:
+	"""
+	A statistic computed on a column of a Table, used by ``Aggregation``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		The name of the column.
+	function
+		A ``Statistic``, such as ``ndp.Mean()`` or ``ndp.Quantile(0.9)``: see ``Statistic`` for every statistic.
+		Missing values are ignored, unless ``Count`` is set to include them.
+	result_name
+		The name of the result column. When omitted, it is ``<column>_<function>``, such as ``"price_mean"``
+		``"price_quantile_90"`` or ``"price_count_excluded"``.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidColumnNameError
+		When ``column`` is an empty text.
+	InvalidColumnNameError
+		When ``result_name`` is an empty text.
+	RefusedOperationError
+		When ``function`` is not a statistic of numdaplot.
+
+	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})
+	>>> total = ndp.Calculation(column="price", function=ndp.Sum())
+	>>> highest = ndp.Calculation(column="price", function=ndp.Max(), result_name="highest_price")
+	>>> sales.aggregate(ndp.Aggregation(calculations=[total, highest]))
+	  price_sum highest_price
+	    FLOAT64       FLOAT64
+	0     350.0         150.0
+	"""
+
+	column: str
+	function: Statistic
+	result_name: str | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the result name, given or automatic, is valid.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidColumnNameError
+			When ``column`` is an empty text.
+		InvalidColumnNameError
+			When ``result_name`` is an empty text.
+		RefusedOperationError
+			When ``function`` is not a statistic of numdaplot.
+		"""
+		require_field_types(self)
+
+		require_column_name(self.column)
+
+		result_name = find_result_name(self)
+		require_column_name(result_name)
+
+
+def find_result_name(calculation: Calculation) -> str:
+	"""
+	Return the name of the column holding the result of a calculation.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	calculation
+		The calculation.
+
+	Returns
+	-------
+	str
+		The given result name, or ``<column>_<function>``.
+
+	Raises
+	------
+	RefusedOperationError
+		When the statistic is not a statistic of numdaplot and no result name is given.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.aggregation.calculation import find_result_name
+	>>> find_result_name(ndp.Calculation(column="price", function=ndp.Quantile(0.9)))
+	'price_quantile_90'
+	"""
+	if calculation.result_name is not None:
+		return calculation.result_name
+
+	function_name = name_statistic(calculation.function)
+	result_name = RESULT_NAME.format(column=calculation.column, function=function_name)
+
+	return result_name

numdaplot/tables/aggregation/result_column.py

@@ -0,0 +1,108 @@
+"""
+Columns holding the results of statistics.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.calculation.statistic_values import compute_statistic
+from numdaplot.errors.empty_array_error import EmptyArrayError
+from numdaplot.statistics.count import Count
+from numdaplot.statistics.counted_missing import CountedMissing
+from numdaplot.statistics.statistic import Statistic
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.frames.column_values import build_column, build_column_with_missing
+
+MISSING_RESULT = numpy.nan
+
+
+def compute_cell(present_values: NDArray[Any], statistic: Statistic, value_count: int) -> NDArray[Any] | None:
+	"""
+	Return a statistic of present values, or nothing when it needs a value and there is none.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	present_values
+		One-dimensional values without missing value.
+	statistic
+		Any statistic of numdaplot.
+	value_count
+		The number of values before the missing ones were left out, the result of a ``Count`` including them.
+
+	Returns
+	-------
+	NDArray or None
+		The result as a one-value array, ``None`` when the statistic needs a value and there is none.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the statistic does not apply to the type of the values.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.aggregation.result_column import compute_cell
+	>>> compute_cell(numpy.array([10.0, 30.0]), ndp.Mean(), 3)
+	array([20.])
+	>>> print(compute_cell(numpy.array([], dtype=float), ndp.Mean(), 1))
+	None
+	>>> compute_cell(numpy.array([10.0, 30.0]), ndp.Count(missing=ndp.CountedMissing.INCLUDED), 3)
+	array([3])
+	"""
+	counts_every_value = isinstance(statistic, Count) and statistic.missing == CountedMissing.INCLUDED
+	if counts_every_value:
+		every_value_count = numpy.array([value_count])
+		return every_value_count
+
+	try:
+		result = compute_statistic(present_values, statistic, None)
+	except EmptyArrayError:
+		return None
+
+	return result
+
+
+def build_result_column(results: list[NDArray[Any] | None]) -> Column:
+	"""
+	Return a Table column holding one result per row, missing where there is no result.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	results
+		One one-value array per row, or ``None`` for a missing result.
+
+	Returns
+	-------
+	Column
+		The column, ``FLOAT64`` when no row has a result.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.tables.aggregation.result_column import build_result_column
+	>>> build_result_column([numpy.array([2]), None]).tolist()
+	[2, <NA>]
+	"""
+	missing_results = [result is None for result in results]
+	missing = numpy.array(missing_results, dtype=numpy.bool_)
+	present_results = [result for result in results if result is not None]
+	if present_results == []:
+		result_count = len(results)
+		missing_values = numpy.full(result_count, MISSING_RESULT)
+		missing_column = build_column(missing_values)
+		return missing_column
+
+	present_values = numpy.concatenate(present_results)
+	result_column = build_column_with_missing(present_values, missing)
+
+	return result_column

numdaplot/tables/aggregation/row_groups.py

@@ -0,0 +1,96 @@
+"""
+Groups of rows of a Table sharing the same values in some columns.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any, cast
+
+import numpy
+import pandas
+from numpy.typing import NDArray
+
+STABLE_SORT = "stable"
+
+
+def find_row_groups(frame: pandas.DataFrame, group_by: list[str] | None) -> list[NDArray[Any]]:
+	"""
+	Return the rows of each group, groups sorted by their values, the group of missing values last.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	group_by
+		The names of the columns forming the groups, or ``None`` for a single group of every row.
+
+	Returns
+	-------
+	list[NDArray]
+		The positions of the rows of each group, in the order of the Table.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.aggregation.row_groups import find_row_groups
+	>>> find_row_groups(pandas.DataFrame({"city": ["Pau", "Lyon", "Pau"]}), ["city"])
+	[array([1]), array([0, 2])]
+	"""
+	row_count = len(frame)
+	if group_by is None:
+		every_row = numpy.arange(row_count)
+		return [every_row]
+
+	# Some versions of the pandas stubs leave the parameter types of groupby unknown.
+	grouped_frame = cast(Any, frame)
+	grouped_rows = grouped_frame.groupby(group_by, sort=True, dropna=False, observed=True)
+	group_count = cast(int, grouped_rows.ngroups)
+	if group_count == 0:
+		return []
+
+	raw_group_numbers = grouped_rows.ngroup()
+	group_number_column = cast("pandas.Series[int]", raw_group_numbers)
+	group_numbers = group_number_column.to_numpy()
+	every_row = numpy.arange(row_count)
+	row_groups = split_positions(every_row, group_numbers, group_count)
+
+	return row_groups
+
+
+def split_positions(positions: NDArray[Any], group_numbers: NDArray[Any], group_count: int) -> list[NDArray[Any]]:
+	"""
+	Return the positions of each group, in their order, a group without position being empty.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	positions
+		The positions of rows.
+	group_numbers
+		The number of the group of each position, from 0.
+	group_count
+		The number of groups.
+
+	Returns
+	-------
+	list[NDArray]
+		One array per group, ``group_count`` in all.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.tables.aggregation.row_groups import split_positions
+	>>> split_positions(numpy.array([4, 7, 9]), numpy.array([2, 0, 2]), 3)
+	[array([7]), array([], dtype=int64), array([4, 9])]
+	"""
+	order = numpy.argsort(group_numbers, kind=STABLE_SORT)
+	sorted_positions = positions[order]
+	group_sizes = numpy.bincount(group_numbers, minlength=group_count)
+	group_ends = numpy.cumsum(group_sizes)
+	group_starts = group_ends[:-1]
+	position_groups = numpy.split(sorted_positions, group_starts)
+
+	return position_groups

numdaplot/tables/aggregation/statistic_name.py

@@ -0,0 +1,122 @@
+"""
+Names of the statistics in the column names of an aggregation and in a description.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.arrays.calculation.statistic_values import UNKNOWN_STATISTIC_ALTERNATIVE, UNKNOWN_STATISTIC_OPERATION
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+from numdaplot.statistics.count import Count
+from numdaplot.statistics.count_distinct import CountDistinct
+from numdaplot.statistics.counted_missing import CountedMissing
+from numdaplot.statistics.maximum import Max
+from numdaplot.statistics.mean import Mean
+from numdaplot.statistics.median import Median
+from numdaplot.statistics.minimum import Min
+from numdaplot.statistics.most_frequent import MostFrequent
+from numdaplot.statistics.most_frequent_count import MostFrequentCount
+from numdaplot.statistics.quantile import Quantile
+from numdaplot.statistics.standard_deviation import StandardDeviation
+from numdaplot.statistics.statistic import Statistic
+from numdaplot.statistics.sum import Sum
+
+STATISTIC_NAMES = {
+	Sum: "sum",
+	Mean: "mean",
+	Median: "median",
+	Min: "min",
+	Max: "max",
+	CountDistinct: "count_distinct",
+	StandardDeviation: "standard_deviation",
+	MostFrequent: "most_frequent",
+	MostFrequentCount: "most_frequent_count",
+}
+COUNT_NAMES = {
+	CountedMissing.EXCLUDED: "count_excluded",
+	CountedMissing.INCLUDED: "count_included",
+}
+QUANTILE_NAME = "quantile_{percent}"
+PERCENT_FACTOR = 100
+PERCENT_DIGITS = 10
+GENERAL_NUMBER_FORMAT = "g"
+DECIMAL_POINT = "."
+NAME_SEPARATOR = "_"
+
+
+def name_statistic(statistic: Statistic) -> str:
+	"""
+	Return the name of a statistic, in lowercase words joined by underscores.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	statistic
+		Any statistic of numdaplot.
+
+	Returns
+	-------
+	str
+		The name, such as ``standard_deviation``, ``quantile_90`` for ``Quantile(0.9)``, or ``count_excluded`` for
+		``Count()``.
+
+	Raises
+	------
+	RefusedOperationError
+		When the statistic is not a statistic of numdaplot.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.aggregation.statistic_name import name_statistic
+	>>> name_statistic(ndp.CountDistinct())
+	'count_distinct'
+	"""
+	if isinstance(statistic, Quantile):
+		quantile_name = name_quantile(statistic)
+		return quantile_name
+
+	if isinstance(statistic, Count):
+		count_name = COUNT_NAMES[statistic.missing]
+		return count_name
+
+	statistic_class = type(statistic)
+	if statistic_class not in STATISTIC_NAMES:
+		operation = UNKNOWN_STATISTIC_OPERATION.format(statistic_name=statistic_class.__name__)
+		raise RefusedOperationError(operation, UNKNOWN_STATISTIC_ALTERNATIVE)
+
+	statistic_name = STATISTIC_NAMES[statistic_class]
+
+	return statistic_name
+
+
+def name_quantile(quantile: Quantile) -> str:
+	"""
+	Return the name of a quantile, holding its fraction as a percentage.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	quantile
+		The quantile.
+
+	Returns
+	-------
+	str
+		``quantile_90`` for 0.9, and ``quantile_97_5`` for 0.975: an underscore replaces the decimal point.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.aggregation.statistic_name import name_quantile
+	>>> name_quantile(ndp.Quantile(0.975))
+	'quantile_97_5'
+	"""
+	percent = quantile.fraction * PERCENT_FACTOR
+	rounded_percent = round(percent, PERCENT_DIGITS)
+	percent_text = format(rounded_percent, GENERAL_NUMBER_FORMAT)
+	percent_name = percent_text.replace(DECIMAL_POINT, NAME_SEPARATOR)
+	quantile_name = QUANTILE_NAME.format(percent=percent_name)
+
+	return quantile_name

numdaplot/tables/columns/__init__.py

@@ -0,0 +1,5 @@
+"""
+Column operations of a Table: names, choice, renaming, conversion and new columns.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/tables/columns/added_column.py

@@ -0,0 +1,89 @@
+"""
+Addition of a column to a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+import pandas
+
+from numdaplot.errors.dimension_error import DimensionError
+from numdaplot.errors.duplicate_column_error import DuplicateColumnError
+from numdaplot.errors.shape_mismatch_error import ShapeMismatchError
+from numdaplot.tables.columns.new_column import NewColumn
+from numdaplot.tables.conflict import Conflict
+from numdaplot.tables.frames.column_values import build_column
+from numdaplot.tables.frames.time_range_errors import TimeRangeErrors
+
+ADD_COLUMN_OPERATION = "add_column"
+ONE_DIMENSION = 1
+
+
+def add_frame_column(frame: pandas.DataFrame, new_column: NewColumn) -> pandas.DataFrame:
+	"""
+	Return the columns of a Table with one more column, or with a column replaced.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table, which are not changed.
+	new_column
+		The name, the values and what to do when the name exists.
+
+	Returns
+	-------
+	pandas.DataFrame
+		A new column is placed last; a replaced column keeps its place. A Table without column
+		takes as many rows as the new column has values.
+
+	Raises
+	------
+	DimensionError
+		When the Array of values does not have one dimension.
+	ShapeMismatchError
+		When the Array does not have one value per row of the Table.
+	DuplicateColumnError
+		When the name exists and ``on_conflict`` is ``ERROR``.
+	TimeOverflowError
+		When the Array holds a datetime or a duration that nanoseconds cannot hold.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.added_column import add_frame_column
+	>>> frame = pandas.DataFrame({"price": [1.5, 8.0]})
+	>>> add_frame_column(frame, ndp.NewColumn(name="count", values=ndp.Array.from_list([2, 1])))
+	   price  count
+	0    1.5      2
+	1    8.0      1
+	"""
+	values = new_column.values.to_numpy()
+	if values.ndim != ONE_DIMENSION:
+		raise DimensionError(ADD_COLUMN_OPERATION, values.ndim)
+
+	column_names = [str(column_name) for column_name in frame.columns]
+	value_count = values.size
+	row_count = len(frame)
+	has_columns = column_names != []
+	has_wrong_length = has_columns and value_count != row_count
+	if has_wrong_length:
+		raise ShapeMismatchError((value_count,), (row_count,))
+
+	name_exists = new_column.name in column_names
+	refuses_existing_name = name_exists and new_column.on_conflict == Conflict.ERROR
+	if refuses_existing_name:
+		raise DuplicateColumnError(new_column.name)
+
+	with TimeRangeErrors(ADD_COLUMN_OPERATION, new_column.name):
+		column = build_column(values)
+
+	extended_frame = frame.copy(deep=False)
+	if not has_columns:
+		row_numbers = pandas.RangeIndex(value_count)
+		extended_frame = pandas.DataFrame(index=row_numbers)
+
+	extended_frame[new_column.name] = column
+
+	return extended_frame

numdaplot/tables/columns/boolean_conversion.py

@@ -0,0 +1,144 @@
+"""
+Conversion of Table columns between booleans and numbers.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any, cast
+
+import numpy
+
+from numdaplot.data_types.type import Type
+from numdaplot.errors.value_conversion_error import ValueConversionError
+from numdaplot.tables.columns.boolean_rule import BooleanRule
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.frames.column_values import (
+	build_column_with_missing,
+	find_column_missing,
+	find_column_type,
+	read_present_values,
+)
+from numdaplot.tables.frames.frame_normalization import convert_to_type
+
+FALSE_NUMBER = 0
+TRUE_NUMBER = 1
+
+
+def convert_booleans_to_numbers(column: Column, target_type: Type) -> Column:
+	"""
+	Return a boolean column as numbers: 1 for ``True`` and 0 for ``False``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A ``BOOL`` column.
+	target_type
+		A number type.
+
+	Returns
+	-------
+	Column
+		The column of numbers, missing values staying missing.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.boolean_conversion import convert_booleans_to_numbers
+	>>> flags = pandas.Series([True, None, False], dtype="boolean")
+	>>> convert_booleans_to_numbers(flags, ndp.Type.FLOAT64).tolist()
+	[1.0, nan, 0.0]
+	"""
+	number_column = convert_to_type(column, target_type)
+
+	return number_column
+
+
+def convert_numbers_to_booleans(column: Column, rule: BooleanRule) -> Column:
+	"""
+	Return a number column as booleans, each number read by a rule.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A number column.
+	rule
+		``ZERO_ONE`` to accept only 0 and 1, ``NONZERO_TRUE`` to read every number but 0 as ``True``.
+
+	Returns
+	-------
+	Column
+		A ``BOOL`` column, missing values staying missing.
+
+	Raises
+	------
+	ValueConversionError
+		With ``ZERO_ONE``, at the first number that is neither 0 nor 1.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.boolean_conversion import convert_numbers_to_booleans
+	>>> numbers = pandas.Series([1, None, 0], dtype="Int64")
+	>>> convert_numbers_to_booleans(numbers, ndp.BooleanRule.ZERO_ONE).tolist()
+	[True, <NA>, False]
+	"""
+	missing = find_column_missing(column)
+	numbers = read_present_values(column)
+	if rule == BooleanRule.ZERO_ONE:
+		source_type = find_column_type(column)
+		require_zero_or_one(numbers, source_type)
+
+	is_true = numbers != FALSE_NUMBER
+	boolean_column = build_column_with_missing(is_true, missing)
+
+	return boolean_column
+
+
+def require_zero_or_one(numbers: numpy.typing.NDArray[numpy.number], source_type: Type) -> None:
+	"""
+	Check that every number is 0 or 1.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	numbers
+		The present numbers of a column.
+	source_type
+		The type of the column, named in the error.
+
+	Raises
+	------
+	ValueConversionError
+		At the first number that is neither 0 nor 1.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.boolean_conversion import require_zero_or_one
+	>>> try:
+	... 	require_zero_or_one(numpy.array([1, 2, 0]), ndp.Type.INT64)
+	... except ndp.ValueConversionError as error:
+	... 	print(error)
+	Cannot store the INT64 value 2 as BOOL without losing information.
+	"""
+	is_false = numbers == FALSE_NUMBER
+	is_true = numbers == TRUE_NUMBER
+	is_boolean = is_false | is_true
+	is_other = ~is_boolean
+	has_other = bool(is_other.any())
+	if not has_other:
+		return
+
+	other_numbers = numbers[is_other]
+	raw_numbers = other_numbers.tolist()
+	python_numbers = cast(list[Any], raw_numbers)
+	first_other_number = python_numbers[0]
+	raise ValueConversionError(source_type.name, Type.BOOL.name, first_other_number)