numdaplot 0.1.0__py3-none-any.whl

numdaplot/statistics/counted_missing.py

@@ -0,0 +1,46 @@
+"""
+Whether Count counts the missing values.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class CountedMissing(Enum):
+	"""
+	Whether ``Count`` counts the missing values.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> answers = ndp.Array.from_list([4.0, None, 2.0])
+	>>> answers.compute(ndp.Count(missing=ndp.CountedMissing.INCLUDED)).to_value()
+	3
+	"""
+
+	EXCLUDED = auto()
+	"""
+	Only the present values are counted. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> answers = ndp.Array.from_list([4.0, None, 2.0])
+	>>> answers.compute(ndp.Count(missing=ndp.CountedMissing.EXCLUDED)).to_value()
+	2
+	"""
+
+	INCLUDED = auto()
+	"""
+	Every value is counted, missing or not, which gives the number of rows of a column.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> answers = ndp.Array.from_list([4.0, None, 2.0])
+	>>> answers.compute(ndp.Count(missing=ndp.CountedMissing.INCLUDED)).to_value()
+	3
+	"""

numdaplot/statistics/maximum.py

@@ -0,0 +1,27 @@
+"""
+Largest value statistic.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.statistics.statistic import Statistic
+
+
+@dataclass(frozen=True)
+class Max(Statistic):
+	"""
+	Largest value.
+
+	Missing values are ignored.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, None, 30.0])
+	>>> prices.compute(ndp.Max()).to_value()
+	30.0
+	"""

numdaplot/statistics/mean.py

@@ -0,0 +1,27 @@
+"""
+Arithmetic mean of the values statistic.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.statistics.statistic import Statistic
+
+
+@dataclass(frozen=True)
+class Mean(Statistic):
+	"""
+	Arithmetic mean of the values.
+
+	Missing values are ignored.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([10.0, None, 30.0])
+	>>> prices.compute(ndp.Mean()).to_value()
+	20.0
+	"""

numdaplot/statistics/median.py

@@ -0,0 +1,27 @@
+"""
+Median of the values, the middle value once sorted statistic.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.statistics.statistic import Statistic
+
+
+@dataclass(frozen=True)
+class Median(Statistic):
+	"""
+	Median of the values, the middle value once sorted.
+
+	It equals ``Quantile(0.5)``. Missing values are ignored.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> salaries = ndp.Array.from_list([1800, 2000, 9000])
+	>>> salaries.compute(ndp.Median()).to_value()
+	2000.0
+	"""

numdaplot/statistics/minimum.py

@@ -0,0 +1,27 @@
+"""
+Smallest value statistic.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.statistics.statistic import Statistic
+
+
+@dataclass(frozen=True)
+class Min(Statistic):
+	"""
+	Smallest value.
+
+	Missing values are ignored.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Pau", "Lyon", "Paris"])
+	>>> cities.compute(ndp.Min()).to_value()
+	'Lyon'
+	"""

numdaplot/statistics/most_frequent.py

@@ -0,0 +1,27 @@
+"""
+Value that appears the most often statistic.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.statistics.statistic import Statistic
+
+
+@dataclass(frozen=True)
+class MostFrequent(Statistic):
+	"""
+	Value that appears the most often.
+
+	Works on any type, text included. Missing values are ignored.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> sizes = ndp.Array.from_list(["M", "L", "M"])
+	>>> sizes.compute(ndp.MostFrequent()).to_value()
+	'M'
+	"""

numdaplot/statistics/most_frequent_count.py

@@ -0,0 +1,27 @@
+"""
+Number of times the most frequent value appears statistic.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.statistics.statistic import Statistic
+
+
+@dataclass(frozen=True)
+class MostFrequentCount(Statistic):
+	"""
+	Number of times the most frequent value appears.
+
+	Works on any type, text included.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> sizes = ndp.Array.from_list(["M", "L", "M"])
+	>>> sizes.compute(ndp.MostFrequentCount()).to_value()
+	2
+	"""

numdaplot/statistics/quantile.py

@@ -0,0 +1,61 @@
+"""
+Quantile statistic.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.ratios.fraction import require_fraction
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.statistics.statistic import Statistic
+
+
+@dataclass(frozen=True)
+class Quantile(Statistic):
+	"""
+	Value below which a given fraction of the values lies.
+
+	``Quantile(0.9)`` on salaries gives the salary below which 90 % of people are,
+	and ``Quantile(0.5)`` is the median. Missing values are ignored.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	fraction
+		Fraction of the values that lie below the result, between 0 and 1 included.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidFractionError
+		When ``fraction`` is lower than 0, greater than 1 or NaN.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> salaries = ndp.Array.from_list([1000, 2000, 3000, 4000, 5000])
+	>>> salaries.compute(ndp.Quantile(0.9)).to_value()
+	4600.0
+	"""
+
+	fraction: float
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the fraction is between 0 and 1.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidFractionError
+			When ``fraction`` is lower than 0, greater than 1 or NaN.
+		"""
+		require_field_types(self)
+
+		require_fraction(self.fraction)

numdaplot/statistics/standard_deviation.py

@@ -0,0 +1,29 @@
+"""
+Standard deviation statistic.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.statistics.statistic import Statistic
+
+
+@dataclass(frozen=True)
+class StandardDeviation(Statistic):
+	"""
+	Standard deviation of the values, how far they spread around the mean.
+
+	``[10, 10, 10]`` gives 0, while ``[0, 10, 20]`` gives about 8.2. It is the population standard
+	deviation, divided by the number of values as in numpy, not by that number minus one as in pandas.
+	Missing values are ignored.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> grades = ndp.Array.from_list([8, 12])
+	>>> grades.compute(ndp.StandardDeviation()).to_value()
+	2.0
+	"""

numdaplot/statistics/statistic.py

@@ -0,0 +1,63 @@
+"""
+Base class of every statistic.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+
+CONSTRUCTOR_OPERATION = "Creating a Statistic with ndp.Statistic()"
+CONSTRUCTOR_ALTERNATIVE = "a statistic such as ndp.Mean"
+
+
+class Statistic:
+	"""
+	Base class of every statistic, a single result computed from a set of values.
+
+	A statistic is immutable and checks its settings when it is created.
+
+	Only its subclasses are created: calling ``ndp.Statistic()`` raises ``RefusedOperationError``.
+
+	Every statistic, passed to ``Array.compute``, ``Calculation`` and ``Description``:
+
+	|Statistic|What it computes|Example|
+	|---|---|---|
+	|``Count``|Number of values, without the missing ones by default|``ndp.Count()``|
+	|``CountDistinct``|Number of distinct values that are not missing|``ndp.CountDistinct()``|
+	|``Sum``|Sum of the values|``ndp.Sum()``|
+	|``Mean``|Arithmetic mean of the values|``ndp.Mean()``|
+	|``Median``|Median of the values, the middle value once sorted|``ndp.Median()``|
+	|``Min``|Smallest value|``ndp.Min()``|
+	|``Max``|Largest value|``ndp.Max()``|
+	|``StandardDeviation``|How far the values spread around the mean|``ndp.StandardDeviation()``|
+	|``Quantile``|Value below which a given fraction of the values lies|``ndp.Quantile(0.9)``|
+	|``MostFrequent``|Value that appears the most often|``ndp.MostFrequent()``|
+	|``MostFrequentCount``|Number of times the most frequent value appears|``ndp.MostFrequentCount()``|
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([10.0, 30.0])
+	>>> for statistic in [ndp.Min(), ndp.Mean(), ndp.Max()]:
+	... 	print(prices.compute(statistic).to_value())
+	10.0
+	20.0
+	30.0
+	"""
+
+	def __init__(self) -> None:
+		"""
+		Refuse the creation of the base class itself, and let a subclass be created.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		RefusedOperationError
+			When the created object is a Statistic and not one of its subclasses.
+		"""
+		created_class = type(self)
+		if created_class is Statistic:
+			raise RefusedOperationError(CONSTRUCTOR_OPERATION, CONSTRUCTOR_ALTERNATIVE)

numdaplot/statistics/sum.py

@@ -0,0 +1,27 @@
+"""
+Sum of the values statistic.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.statistics.statistic import Statistic
+
+
+@dataclass(frozen=True)
+class Sum(Statistic):
+	"""
+	Sum of the values.
+
+	Missing values are ignored.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> amounts = ndp.Array.from_list([10.5, None, 4.5])
+	>>> amounts.compute(ndp.Sum()).to_value()
+	15.0
+	"""

numdaplot/tables/__init__.py

@@ -0,0 +1,5 @@
+"""
+The ``ndp.Table`` class and its settings: files, filters, aggregations, columns, sorting and preview.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/tables/aggregation/__init__.py

@@ -0,0 +1,5 @@
+"""
+Aggregation of the rows of a Table, as a whole or by group.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/tables/aggregation/aggregated_frame.py

@@ -0,0 +1,189 @@
+"""
+Aggregation of the rows of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+import pandas
+from numpy.typing import NDArray
+
+from numdaplot.statistics.statistic import Statistic
+from numdaplot.tables.aggregation.aggregation import Aggregation
+from numdaplot.tables.aggregation.calculation import find_result_name
+from numdaplot.tables.aggregation.result_column import build_result_column, compute_cell
+from numdaplot.tables.aggregation.row_groups import find_row_groups
+from numdaplot.tables.columns.column_names import require_known_columns
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.frames.column_values import find_column_missing, read_present_values
+from numdaplot.tables.frames.named_column_errors import NamedColumnErrors
+from numdaplot.tables.frames.time_zones import attribute_source_time_zone
+
+FIRST_ROW = 0
+ROW_POSITION_DTYPE = numpy.int64
+
+
+def aggregate_frame(frame: pandas.DataFrame, aggregation: Aggregation) -> pandas.DataFrame:
+	"""
+	Return the statistics of the whole Table, or of each group of rows.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	aggregation
+		The statistics and the group columns.
+
+	Returns
+	-------
+	pandas.DataFrame
+		One row per group, sorted by group values with missing values last, or a single row.
+		The group columns come first, then one column per calculation.
+
+	Raises
+	------
+	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 pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.aggregation.aggregated_frame import aggregate_frame
+	>>> frame = pandas.DataFrame({"city": ["Pau", "Lyon", "Pau"], "price": [1.0, 2.0, 3.0]})
+	>>> total = ndp.Calculation(column="price", function=ndp.Sum())
+	>>> aggregate_frame(frame, ndp.Aggregation(calculations=[total], group_by=["city"]))
+	   city  price_sum
+	0  Lyon        2.0
+	1   Pau        4.0
+	"""
+	column_names = [str(column_name) for column_name in frame.columns]
+	calculation_columns = [calculation.column for calculation in aggregation.calculations]
+	require_known_columns(calculation_columns, column_names)
+	group_by = aggregation.group_by
+	if group_by is not None:
+		require_known_columns(group_by, column_names)
+
+	row_groups = find_row_groups(frame, group_by)
+	result_columns = dict[str, Column]()
+	if group_by is not None:
+		key_columns = take_group_keys(frame, group_by, row_groups)
+		result_columns.update(key_columns)
+
+	for calculation in aggregation.calculations:
+		result_name = find_result_name(calculation)
+		column = frame[calculation.column]
+		result_column = compute_group_results(column, calculation.function, row_groups)
+		result_columns[result_name] = result_column
+
+	group_count = len(row_groups)
+	group_numbers = pandas.RangeIndex(group_count)
+	aggregated_frame = pandas.DataFrame(result_columns, index=group_numbers)
+
+	return aggregated_frame
+
+
+def take_group_keys(frame: pandas.DataFrame, group_by: list[str], row_groups: list[NDArray[Any]]) -> dict[str, Column]:
+	"""
+	Return the values of the group columns for each group, taken from its first row.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	group_by
+		The names of the group columns.
+	row_groups
+		The rows of each group.
+
+	Returns
+	-------
+	dict[str, Column]
+		One column per group column, one row per group, numbered from 0.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import pandas
+	>>> from numdaplot.tables.aggregation.aggregated_frame import take_group_keys
+	>>> frame = pandas.DataFrame({"city": ["Pau", "Lyon", "Pau"]})
+	>>> take_group_keys(frame, ["city"], [numpy.array([1]), numpy.array([0, 2])])["city"].tolist()
+	['Lyon', 'Pau']
+	"""
+	first_row_list = [row_group[FIRST_ROW] for row_group in row_groups]
+	first_rows = numpy.array(first_row_list, dtype=ROW_POSITION_DTYPE)
+	key_columns = dict[str, Column]()
+
+	for column_name in group_by:
+		column = frame[column_name]
+		first_values = column.iloc[first_rows]
+		key_column = first_values.reset_index(drop=True)
+		key_columns[column_name] = key_column
+
+	return key_columns
+
+
+def compute_group_results(column: Column, statistic: Statistic, row_groups: list[NDArray[Any]]) -> Column:
+	"""
+	Return a statistic of the values of a column, for each group of rows, missing values left out unless counted.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column.
+	statistic
+		Any statistic of numdaplot.
+	row_groups
+		The rows of each group.
+
+	Returns
+	-------
+	Column
+		One result per group, missing for a group without present value when the statistic needs one.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the statistic does not apply to the type of the column.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.aggregation.aggregated_frame import compute_group_results
+	>>> column = pandas.Series([1.0, None, 3.0])
+	>>> compute_group_results(column, ndp.Mean(), [numpy.array([1]), numpy.array([0, 2])]).tolist()
+	[nan, 2.0]
+	"""
+	missing = find_column_missing(column)
+	present = ~missing
+	present_values = read_present_values(column)
+	present_counts = numpy.cumsum(present)
+	value_positions = present_counts - 1
+	results = list[NDArray[Any] | None]()
+
+	with NamedColumnErrors(column):
+		for row_group in row_groups:
+			group_present = present[row_group]
+			present_rows = row_group[group_present]
+			group_value_positions = value_positions[present_rows]
+			group_values = present_values[group_value_positions]
+			group_size = len(row_group)
+			result = compute_cell(group_values, statistic, group_size)
+			results.append(result)
+
+	utc_results = build_result_column(results)
+	result_column = attribute_source_time_zone(utc_results, column)
+
+	return result_column

numdaplot/tables/aggregation/aggregation.py

@@ -0,0 +1,97 @@
+"""
+Settings of the aggregation 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.aggregation.calculation import Calculation, find_result_name
+from numdaplot.tables.columns.column_names import require_column_names, require_unique_names
+
+CALCULATION_ITEM_NAME = "calculation"
+GROUP_COLUMN_ITEM_NAME = "group column"
+
+
+@dataclass(frozen=True)
+class Aggregation:
+	"""
+	Statistics computed on the whole Table or on each group of rows, used by ``Table.aggregate``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	calculations
+		The statistics to compute, at least one. The aggregation keeps its own copy of the list.
+	group_by
+		The names of the columns whose values form the groups: one result row per combination
+		of values. The whole Table gives a single row when omitted.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	EmptyListError
+		When ``calculations`` or ``group_by`` is an empty list.
+	InvalidColumnNameError
+		When a group column name is an empty text.
+	DuplicateColumnError
+		When a name appears twice among the group columns and the result names.
+
+	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})
+	>>> average_price = ndp.Calculation(column="price", function=ndp.Mean())
+	>>> sales.aggregate(ndp.Aggregation(calculations=[average_price], group_by=["city"]))
+	    city price_mean
+	    TEXT    FLOAT64
+	0   Lyon       80.0
+	1  Paris      135.0
+	"""
+
+	calculations: list[Calculation]
+	group_by: list[str] | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check the lists and replace them with copies that only the aggregation holds.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		EmptyListError
+			When ``calculations`` or ``group_by`` is an empty list.
+		InvalidColumnNameError
+			When a group column name is an empty text.
+		DuplicateColumnError
+			When a name appears twice among the group columns and the result names.
+		"""
+		require_field_types(self)
+
+		if self.calculations == []:
+			raise EmptyListError(CALCULATION_ITEM_NAME)
+
+		if self.group_by == []:
+			raise EmptyListError(GROUP_COLUMN_ITEM_NAME)
+
+		calculations_copy = list(self.calculations)
+		object.__setattr__(self, "calculations", calculations_copy)
+		output_names = list[str]()
+		if self.group_by is not None:
+			require_column_names(self.group_by)
+			group_by_copy = list(self.group_by)
+			object.__setattr__(self, "group_by", group_by_copy)
+			output_names.extend(group_by_copy)
+
+		result_names = [find_result_name(calculation) for calculation in calculations_copy]
+		output_names.extend(result_names)
+		require_unique_names(output_names)