numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/missing/missing_count.py

@@ -0,0 +1,59 @@
+"""
+Settings of the count of the missing values of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.ratios.measure import Measure
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class MissingCount:
+	"""
+	How the missing values of a Table are counted, used by ``Table.count_missing``.
+
+	The axis, for each row or each column, is given to ``Table.count_missing`` itself.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	measure
+		A number of missing values by default, or with ``Measure.RATIO`` their fraction of the values counted.
+
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau"])
+	>>> prices = ndp.Array.from_list([120.0, None, None])
+	>>> table = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> table.count_missing(ndp.MissingCount(measure=ndp.Measure.RATIO), axis=ndp.Axis.EACH_COLUMN)
+	  column missing_ratio
+	    TEXT       FLOAT64
+	0   city      0.000000
+	1  price      0.666667
+	"""
+
+	measure: Measure = Measure.COUNT
+
+	def __post_init__(self) -> None:
+		"""
+		Check the type of every setting.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		"""
+		require_field_types(self)

numdaplot/tables/missing/missing_counts.py

@@ -0,0 +1,214 @@
+"""
+Count of the missing values of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+import numpy
+import pandas
+from numpy.typing import NDArray
+
+from numdaplot.data_types.numpy_mapping import to_numpy_dtype
+from numdaplot.data_types.type import Type
+from numdaplot.positions.axis import Axis
+from numdaplot.ratios.measure import Measure
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.frames.column_values import build_column
+from numdaplot.tables.missing.missing_count import MissingCount
+
+COLUMN_NAMES_COLUMN = "column"
+MEASURE_COLUMN_NAMES = {
+	Measure.COUNT: "missing_count",
+	Measure.RATIO: "missing_ratio",
+}
+# A numpy sum along axis 0 gives one result per column, along axis 1 one result per row.
+COLUMN_SUM_AXIS = 0
+ROW_SUM_AXIS = 1
+
+
+def count_frame_missing(frame: pandas.DataFrame, missing_count: MissingCount, axis: Axis | None) -> pandas.DataFrame:
+	"""
+	Return the count of the missing values of a Table, for the whole Table, each row or each column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	missing_count
+		The measure of the count.
+	axis
+		``EACH_ROW`` for one count per row, ``EACH_COLUMN`` for one per column, or None for the whole Table.
+
+	Returns
+	-------
+	pandas.DataFrame
+		A ``missing_count`` or ``missing_ratio`` column: one row for the whole Table, one row per row,
+		or one row per column after a ``column`` column naming it. A ratio without any value is missing.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.missing.missing_counts import count_frame_missing
+	>>> frame = pandas.DataFrame({"price": [1.5, None], "stock": [None, None]})
+	>>> count_frame_missing(frame, ndp.MissingCount(measure=ndp.Measure.RATIO), ndp.Axis.EACH_ROW)
+	   missing_ratio
+	0            0.5
+	1            1.0
+	"""
+	missing_grid = find_frame_missing(frame)
+	counts, value_count = count_axis_missing(missing_grid, axis)
+	measures = counts
+	if missing_count.measure == Measure.RATIO:
+		measures = divide_counts(counts, value_count)
+
+	measure_name = MEASURE_COLUMN_NAMES[missing_count.measure]
+	measure_column = build_column(measures)
+	count_columns = dict[str, Column]()
+	if axis == Axis.EACH_COLUMN:
+		count_columns[COLUMN_NAMES_COLUMN] = build_name_column(frame)
+
+	count_columns[measure_name] = measure_column
+	count_frame = pandas.DataFrame(count_columns)
+
+	return count_frame
+
+
+def find_frame_missing(frame: pandas.DataFrame) -> NDArray[numpy.bool_]:
+	"""
+	Return which values of a Table are missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		One row per row and one column per column, True at each missing value.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.missing.missing_counts import find_frame_missing
+	>>> find_frame_missing(pandas.DataFrame({"price": [1.5, None]}))
+	array([[False],
+	       [ True]])
+	"""
+	missing_frame = frame.isna()
+	missing_grid = missing_frame.to_numpy(dtype=numpy.bool_)
+
+	return missing_grid
+
+
+def count_axis_missing(missing_grid: NDArray[numpy.bool_], axis: Axis | None) -> tuple[NDArray[numpy.int64], int]:
+	"""
+	Return the number of missing values along an axis, and how many values each number is counted on.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	missing_grid
+		True at each missing value of a Table, one row per row.
+	axis
+		One count per row, per column, or a single count for the whole Table when ``None``.
+
+	Returns
+	-------
+	tuple[NDArray[numpy.int64], int]
+		The counts, then the number of values behind each count.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.missing.missing_counts import count_axis_missing
+	>>> count_axis_missing(numpy.array([[True, False], [True, True]]), ndp.Axis.EACH_COLUMN)
+	(array([2, 1]), 2)
+	"""
+	row_count, column_count = missing_grid.shape
+	if axis == Axis.EACH_ROW:
+		row_counts = missing_grid.sum(axis=ROW_SUM_AXIS, dtype=numpy.int64)
+		return row_counts, column_count
+
+	if axis == Axis.EACH_COLUMN:
+		column_counts = missing_grid.sum(axis=COLUMN_SUM_AXIS, dtype=numpy.int64)
+		return column_counts, row_count
+
+	missing_total = missing_grid.sum(dtype=numpy.int64)
+	total_counts = numpy.array([missing_total], dtype=numpy.int64)
+
+	return total_counts, missing_grid.size
+
+
+def divide_counts(counts: NDArray[numpy.int64], value_count: int) -> NDArray[numpy.float64]:
+	"""
+	Return the fraction of the values each count represents.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	counts
+		Numbers of missing values.
+	value_count
+		The number of values behind each count.
+
+	Returns
+	-------
+	NDArray[numpy.float64]
+		Each count divided by the number of values, NaN everywhere when there is no value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.tables.missing.missing_counts import divide_counts
+	>>> divide_counts(numpy.array([1, 2]), 4)
+	array([0.25, 0.5 ])
+	>>> divide_counts(numpy.array([0]), 0)
+	array([nan])
+	"""
+	if value_count == 0:
+		no_ratios = numpy.full(counts.shape, numpy.nan, dtype=numpy.float64)
+		return no_ratios
+
+	ratios = numpy.divide(counts, value_count, dtype=numpy.float64)
+
+	return ratios
+
+
+def build_name_column(frame: pandas.DataFrame) -> Column:
+	"""
+	Return a text column holding the names of the columns of a Table.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+
+	Returns
+	-------
+	Column
+		One name per row, in the order of the Table.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.missing.missing_counts import build_name_column
+	>>> build_name_column(pandas.DataFrame({"city": ["Pau"], "price": [1.5]})).tolist()
+	['city', 'price']
+	"""
+	column_names = [str(column_name) for column_name in frame.columns]
+	text_dtype = to_numpy_dtype(Type.TEXT)
+	name_values = numpy.array(column_names, dtype=text_dtype)
+	name_column = build_column(name_values)
+
+	return name_column

numdaplot/tables/missing/missing_drop.py

@@ -0,0 +1,98 @@
+"""
+Settings of the removal of the rows or the columns of a Table holding missing values.
+
+.. 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_column_names
+from numdaplot.tables.missing.missing_mode import MissingMode
+from numdaplot.tables.missing.missing_ratio import MissingRatio
+
+COLUMN_ITEM_NAME = "column"
+
+
+@dataclass(frozen=True)
+class MissingDrop:
+	"""
+	Which rows or columns holding missing values are removed, used by ``Table.drop_missing``.
+
+	The axis, rows or columns, is given to ``Table.drop_missing`` itself.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	columns
+		The names of the columns looked at, every column when omitted. Rows are removed according to
+		their values in these columns; columns are only removed among them, the others are always kept.
+		The settings keep their own copy of the list.
+	rule
+		How many missing values make a row or a column removed: a single one by default, all of them with
+		``MissingMode.ALL``, or a share of them with ``MissingRatio``. In a Table without rows, no column
+		is removed.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	EmptyListError
+		When ``columns`` is an empty list.
+	InvalidColumnNameError
+		When a column name is an empty text.
+	DuplicateColumnError
+		When a column name appears twice.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau"])
+	>>> prices = ndp.Array.from_list([120.0, None, 150.0])
+	>>> table = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> table.drop_missing()
+	    city   price
+	    TEXT FLOAT64
+	0  Paris   120.0
+	1    Pau   150.0
+	>>> table.drop_missing(ndp.MissingDrop(columns=["price"]), axis=ndp.Axis.EACH_COLUMN)
+	    city
+	    TEXT
+	0  Paris
+	1   Lyon
+	2    Pau
+	"""
+
+	columns: list[str] | None = None
+	rule: MissingMode | MissingRatio = MissingMode.ANY
+
+	def __post_init__(self) -> None:
+		"""
+		Check the columns and replace them with a copy that only the settings hold.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		EmptyListError
+			When ``columns`` is an empty list.
+		InvalidColumnNameError
+			When a column name is an empty text.
+		DuplicateColumnError
+			When a column name appears twice.
+		"""
+		require_field_types(self)
+
+		if self.columns is None:
+			return
+
+		if self.columns == []:
+			raise EmptyListError(COLUMN_ITEM_NAME)
+
+		require_column_names(self.columns)
+		columns_copy = list(self.columns)
+		object.__setattr__(self, "columns", columns_copy)

numdaplot/tables/missing/missing_mode.py

@@ -0,0 +1,63 @@
+"""
+How many missing values make a row or a column removed.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class MissingMode(Enum):
+	"""
+	How many missing values make a row or a column removed, used by ``MissingDrop``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau"])
+	>>> prices = ndp.Array.from_list([120.0, None, None])
+	>>> stocks = ndp.Array.from_list([3.0, 5.0, None])
+	>>> table = ndp.Table.from_arrays({"city": cities, "price": prices, "stock": stocks})
+	>>> table.drop_missing(ndp.MissingDrop(columns=["price", "stock"], rule=ndp.MissingMode.ALL))
+	    city   price   stock
+	    TEXT FLOAT64 FLOAT64
+	0  Paris   120.0     3.0
+	1   Lyon     NaN     5.0
+	"""
+
+	ANY = auto()
+	"""
+	A single missing value is enough. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau"])
+	>>> prices = ndp.Array.from_list([120.0, None, None])
+	>>> stocks = ndp.Array.from_list([3.0, 5.0, None])
+	>>> table = ndp.Table.from_arrays({"city": cities, "price": prices, "stock": stocks})
+	>>> table.drop_missing(ndp.MissingDrop(columns=["price", "stock"], rule=ndp.MissingMode.ANY))
+	    city   price   stock
+	    TEXT FLOAT64 FLOAT64
+	0  Paris   120.0     3.0
+	"""
+
+	ALL = auto()
+	"""
+	Every value must be missing.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau"])
+	>>> prices = ndp.Array.from_list([120.0, None, None])
+	>>> stocks = ndp.Array.from_list([3.0, 5.0, None])
+	>>> table = ndp.Table.from_arrays({"city": cities, "price": prices, "stock": stocks})
+	>>> table.drop_missing(ndp.MissingDrop(columns=["price", "stock"], rule=ndp.MissingMode.ALL))
+	    city   price   stock
+	    TEXT FLOAT64 FLOAT64
+	0  Paris   120.0     3.0
+	1   Lyon     NaN     5.0
+	"""

numdaplot/tables/missing/missing_ratio.py

@@ -0,0 +1,71 @@
+"""
+A ratio of missing values from which a row or a column is removed.
+
+.. 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.tables.missing.ratio_comparison import RatioComparison
+
+
+@dataclass(frozen=True)
+class MissingRatio:
+	"""
+	A ratio of missing values from which a row or a column is removed, used by ``MissingDrop``.
+
+	The ratio of a row is its missing values divided by its number of values, and the same for a column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	ratio
+		The threshold, a fraction between 0 and 1: ``0.3`` for 30 %.
+	comparison
+		Whether a ratio equal to the threshold is enough, ``RatioComparison.AT_LEAST`` by default, or the ratio must be
+		above it, ``RatioComparison.ABOVE``.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidFractionError
+		When ``ratio`` is lower than 0, greater than 1 or NaN.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([120.0, None, 80.0, None])
+	>>> stocks = ndp.Array.from_list([3.0, 5.0, None, 2.0])
+	>>> table = ndp.Table.from_arrays({"price": prices, "stock": stocks})
+	>>> table.drop_missing(ndp.MissingDrop(rule=ndp.MissingRatio(0.4)), axis=ndp.Axis.EACH_COLUMN)
+	    stock
+	  FLOAT64
+	0     3.0
+	1     5.0
+	2     NaN
+	3     2.0
+	"""
+
+	ratio: float
+	comparison: RatioComparison = RatioComparison.AT_LEAST
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the ratio is a fraction.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidFractionError
+			When ``ratio`` is lower than 0, greater than 1 or NaN.
+		"""
+		require_field_types(self)
+
+		require_fraction(self.ratio)