numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/columns/name_change.py

@@ -0,0 +1,67 @@
+"""
+A new name for one column of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.columns.column_names import require_column_name
+
+
+@dataclass(frozen=True)
+class NameChange:
+	"""
+	A new name for one column of a Table, used by ``Renaming``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	old_name
+		The current name of the column.
+	new_name
+		Its new name, a non-empty text.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidColumnNameError
+		When ``old_name`` or ``new_name`` is an empty text.
+
+	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.rename(ndp.Renaming(changes=[ndp.NameChange(old_name="city", new_name="town")]))
+	    town   price
+	    TEXT FLOAT64
+	0  Paris   120.0
+	1   Lyon    80.0
+	2  Paris   150.0
+	"""
+
+	old_name: str
+	new_name: str
+
+	def __post_init__(self) -> None:
+		"""
+		Check that both names are non-empty texts.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidColumnNameError
+			When ``old_name`` or ``new_name`` is an empty text.
+		"""
+		require_field_types(self)
+
+		require_column_name(self.old_name)
+		require_column_name(self.new_name)

numdaplot/tables/columns/new_column.py

@@ -0,0 +1,79 @@
+"""
+A column to add to a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.columns.column_names import require_column_name
+from numdaplot.tables.conflict import Conflict
+
+if TYPE_CHECKING:
+	from numdaplot.arrays.array import Array
+
+
+# eq=False because comparing two new columns would compare their Arrays with ==, which Array refuses.
+@dataclass(frozen=True, eq=False)
+class NewColumn:
+	"""
+	A column to add to a Table, used by ``Table.add_column``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	name
+		The name of the column, a non-empty text.
+	values
+		A one-dimensional Array with one value per row of the Table.
+	on_conflict
+		``ERROR`` by default, refusing a name that already exists, or ``REPLACE`` to replace the existing column, at its
+		place.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidColumnNameError
+		When ``name`` is empty.
+
+	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})
+	>>> taxed_prices = sales.column("price") * 1.2
+	>>> sales.add_column(ndp.NewColumn(name="taxed_price", values=taxed_prices))
+	    city   price taxed_price
+	    TEXT FLOAT64     FLOAT64
+	0  Paris   120.0       144.0
+	1   Lyon    80.0        96.0
+	2  Paris   150.0       180.0
+	"""
+
+	name: str
+	values: Array
+	on_conflict: Conflict = Conflict.ERROR
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the name is a non-empty text.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidColumnNameError
+			When ``name`` is empty.
+		"""
+		require_field_types(self)
+
+		require_column_name(self.name)

numdaplot/tables/columns/number_conversion.py

@@ -0,0 +1,281 @@
+"""
+Conversion of Table columns to number types.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any, cast
+
+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.errors.value_conversion_error import ValueConversionError
+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.pandas_decimals import restore_exact_decimals
+
+DECIMAL_KIND = "f"
+FAILED_PARSE = "coerce"
+PYTHON_OBJECT_DTYPE = numpy.dtype(object)
+IGNORED_FLOAT_ERROR = "ignore"
+
+
+def convert_numbers(column: Column, target_type: Type) -> Column:
+	"""
+	Return a number column converted to another number type.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A number column.
+	target_type
+		The new number type.
+
+	Returns
+	-------
+	Column
+		The converted column. Decimals may be rounded to the precision of a smaller decimal type.
+
+	Raises
+	------
+	ValueConversionError
+		When a value does not fit: a decimal with a fractional part converted to an integer,
+		or a number out of the range of the new type.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.number_conversion import convert_numbers
+	>>> convert_numbers(pandas.Series([2.0, None]), ndp.Type.INT64).tolist()
+	[2, <NA>]
+	"""
+	source_type = find_column_type(column)
+	missing = find_column_missing(column)
+	present_values = read_present_values(column)
+	converted_values = store_numbers(present_values, target_type)
+	require_no_lost_value(present_values, converted_values, source_type, target_type)
+	converted_column = build_column_with_missing(converted_values, missing)
+
+	return converted_column
+
+
+def parse_numbers(column: Column, target_type: Type) -> Column:
+	"""
+	Return a text or category column read as numbers.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A text or category column.
+	target_type
+		The number type to read the texts as.
+
+	Returns
+	-------
+	Column
+		The numbers, missing values staying missing.
+
+	Raises
+	------
+	ValueConversionError
+		At the first text that is not a number, or whose number does not fit the type.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.number_conversion import parse_numbers
+	>>> parse_numbers(pandas.Series(["2.5", "1e3"], dtype="string"), ndp.Type.FLOAT64).tolist()
+	[2.5, 1000.0]
+	"""
+	source_type = find_column_type(column)
+	missing = find_column_missing(column)
+	texts = read_present_values(column)
+	object_texts = texts.astype(PYTHON_OBJECT_DTYPE)
+	parsed_values = pandas.to_numeric(object_texts, errors=FAILED_PARSE)
+	read_numbers = numpy.asarray(parsed_values)
+	failed = numpy.zeros(texts.shape, dtype=numpy.bool_)
+	if read_numbers.dtype.kind == DECIMAL_KIND:
+		failed = numpy.isnan(read_numbers)
+
+	require_no_failed_value(texts, failed, source_type, target_type)
+	numbers = restore_exact_decimals(object_texts, read_numbers)
+	converted_values = store_numbers(numbers, target_type)
+	lost = find_lost_values(numbers, converted_values)
+	require_no_failed_value(texts, lost, source_type, target_type)
+	parsed_column = build_column_with_missing(converted_values, missing)
+
+	return parsed_column
+
+
+def store_numbers(values: NDArray[Any], target_type: Type) -> NDArray[Any]:
+	"""
+	Return numbers stored in a number type, even when some do not fit.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		Numbers in a numpy dtype.
+	target_type
+		The number type to store them as.
+
+	Returns
+	-------
+	NDArray
+		The stored numbers; check them with ``find_lost_values``.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.number_conversion import store_numbers
+	>>> store_numbers(numpy.array([2.0]), ndp.Type.INT8)
+	array([2], dtype=int8)
+	"""
+	target_dtype = to_numpy_dtype(target_type)
+	with numpy.errstate(invalid=IGNORED_FLOAT_ERROR, over=IGNORED_FLOAT_ERROR):
+		stored_values = values.astype(target_dtype)
+
+	return stored_values
+
+
+def find_lost_values(values: NDArray[Any], stored_values: NDArray[Any]) -> NDArray[numpy.bool_]:
+	"""
+	Return which numbers changed when stored in another number type, beyond the rounding of decimals.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The original numbers.
+	stored_values
+		The same numbers stored in another type.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		For a decimal type, True where a finite number became infinite. For an integer type,
+		True where the stored number differs from the original one.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.tables.columns.number_conversion import find_lost_values
+	>>> find_lost_values(numpy.array([2.0, 2.5]), numpy.array([2, 2]))
+	array([False,  True])
+	"""
+	if stored_values.dtype.kind == DECIMAL_KIND:
+		finite = numpy.isfinite(values)
+		infinite = numpy.isinf(stored_values)
+		overflowed = finite & infinite
+		return overflowed
+
+	with numpy.errstate(invalid=IGNORED_FLOAT_ERROR, over=IGNORED_FLOAT_ERROR):
+		restored_values = stored_values.astype(values.dtype)
+
+	changed = restored_values != values
+
+	return changed
+
+
+def require_no_lost_value(
+	values: NDArray[Any], stored_values: NDArray[Any], source_type: Type, target_type: Type
+) -> None:
+	"""
+	Check that numbers kept their value when stored in another number type.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The original numbers.
+	stored_values
+		The same numbers stored in the new type.
+	source_type
+		The type of the original numbers.
+	target_type
+		The new type.
+
+	Raises
+	------
+	ValueConversionError
+		At the first number that changed.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.number_conversion import require_no_lost_value
+	>>> try:
+	... 	require_no_lost_value(numpy.array([2.0, 2.5]), numpy.array([2, 2]), ndp.Type.FLOAT64, ndp.Type.INT64)
+	... except ndp.ValueConversionError as error:
+	... 	print(error)
+	Cannot store the FLOAT64 value 2.5 as INT64 without losing information.
+	"""
+	lost = find_lost_values(values, stored_values)
+	require_no_failed_value(values, lost, source_type, target_type)
+
+
+def require_no_failed_value(
+	values: NDArray[Any], failed: NDArray[numpy.bool_], source_type: Type, target_type: Type
+) -> None:
+	"""
+	Check that no value failed its conversion.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The original values, texts or numbers.
+	failed
+		True at each value that failed.
+	source_type
+		The type of the original values.
+	target_type
+		The new type.
+
+	Raises
+	------
+	ValueConversionError
+		At the first failed value, which the message shows.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.number_conversion import require_no_failed_value
+	>>> texts = numpy.array(["12", "abc"])
+	>>> failed = numpy.array([False, True])
+	>>> try:
+	... 	require_no_failed_value(texts, failed, ndp.Type.TEXT, ndp.Type.INT64)
+	... except ndp.ValueConversionError as error:
+	... 	print(error)
+	Cannot store the TEXT value 'abc' as INT64 without losing information.
+	"""
+	has_failure = bool(failed.any())
+	if not has_failure:
+		return
+
+	failed_values = values[failed]
+	raw_values = failed_values.tolist()
+	python_values = cast(list[Any], raw_values)
+	rejected_value = python_values[0]
+	raise ValueConversionError(source_type.name, target_type.name, rejected_value)

numdaplot/tables/columns/renamed_columns.py

@@ -0,0 +1,60 @@
+"""
+Renaming of the columns of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+import pandas
+
+from numdaplot.tables.columns.column_names import require_known_columns, require_unique_names
+from numdaplot.tables.columns.renaming import Renaming
+
+
+def rename_frame_columns(frame: pandas.DataFrame, renaming: Renaming) -> pandas.DataFrame:
+	"""
+	Return the columns of a Table with new names, every change applied at once.
+
+	Two columns can swap their names in a single renaming.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	renaming
+		The new names.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The same columns, in the same order, renamed.
+
+	Raises
+	------
+	ColumnNotFoundError
+		When a renamed column does not exist.
+	DuplicateColumnError
+		When a new name is the name of a column kept as it is.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.columns.renamed_columns import rename_frame_columns
+	>>> frame = pandas.DataFrame({"low": [1.0], "high": [9.0]})
+	>>> swap = [ndp.NameChange(old_name="low", new_name="high"), ndp.NameChange(old_name="high", new_name="low")]
+	>>> rename_frame_columns(frame, ndp.Renaming(changes=swap))
+	   high  low
+	0   1.0  9.0
+	"""
+	column_names = [str(column_name) for column_name in frame.columns]
+	old_names = [change.old_name for change in renaming.changes]
+	require_known_columns(old_names, column_names)
+	new_names_by_old_name = {change.old_name: change.new_name for change in renaming.changes}
+	final_names = [new_names_by_old_name.get(column_name, column_name) for column_name in column_names]
+	require_unique_names(final_names)
+	renamed_frame = frame.copy(deep=False)
+	renamed_frame.columns = pandas.Index(final_names)
+
+	return renamed_frame

numdaplot/tables/columns/renaming.py

@@ -0,0 +1,81 @@
+"""
+The new names of columns of a Table, applied at once.
+
+.. 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_unique_names
+from numdaplot.tables.columns.name_change import NameChange
+
+CHANGE_ITEM_NAME = "name change"
+
+
+@dataclass(frozen=True)
+class Renaming:
+	"""
+	The new names of columns of a Table, applied at once, used by ``Table.rename``.
+
+	Two columns can swap their names in a single renaming.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	changes
+		The ``NameChange`` of each renamed column, at least one. The renaming keeps its own copy of the list.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	EmptyListError
+		When ``changes`` is an empty list.
+	DuplicateColumnError
+		When a column is renamed twice, or two columns receive the same new name.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> low = ndp.Array.from_list([1.0, 2.0])
+	>>> high = ndp.Array.from_list([9.0, 8.0])
+	>>> bounds = ndp.Table.from_arrays({"low": low, "high": high})
+	>>> swap = [ndp.NameChange(old_name="low", new_name="high"), ndp.NameChange(old_name="high", new_name="low")]
+	>>> bounds.rename(ndp.Renaming(changes=swap))
+	     high     low
+	  FLOAT64 FLOAT64
+	0     1.0     9.0
+	1     2.0     8.0
+	"""
+
+	changes: list[NameChange]
+
+	def __post_init__(self) -> None:
+		"""
+		Check the list of changes and replace it with a copy that only the renaming holds.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		EmptyListError
+			When ``changes`` is an empty list.
+		DuplicateColumnError
+			When a column is renamed twice, or two columns receive the same new name.
+		"""
+		require_field_types(self)
+
+		if self.changes == []:
+			raise EmptyListError(CHANGE_ITEM_NAME)
+
+		old_names = [change.old_name for change in self.changes]
+		require_unique_names(old_names)
+		new_names = [change.new_name for change in self.changes]
+		require_unique_names(new_names)
+		changes_copy = list(self.changes)
+		object.__setattr__(self, "changes", changes_copy)

numdaplot/tables/columns/text_conversion.py

@@ -0,0 +1,70 @@
+"""
+Conversion of text columns to booleans.
+
+.. versionadded:: 0.1.0
+"""
+
+import numpy
+
+from numdaplot.data_types.type import Type
+from numdaplot.errors.value_conversion_error import ValueConversionError
+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,
+)
+
+TRUE_TEXT = "true"
+FALSE_TEXT = "false"
+
+
+def parse_booleans(column: Column) -> Column:
+	"""
+	Return a text or category column read as booleans.
+
+	``"true"`` and ``"false"`` are accepted whatever their case and the spaces around them.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A text or category column.
+
+	Returns
+	-------
+	Column
+		A ``BOOL`` column, missing values staying missing.
+
+	Raises
+	------
+	ValueConversionError
+		At the first text that is neither ``"true"`` nor ``"false"``.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.columns.text_conversion import parse_booleans
+	>>> parse_booleans(pandas.Series(["True", " false ", None], dtype="string")).tolist()
+	[True, False, <NA>]
+	"""
+	source_type = find_column_type(column)
+	missing = find_column_missing(column)
+	texts = read_present_values(column)
+	stripped_texts = numpy.strings.strip(texts)
+	lowered_texts = numpy.strings.lower(stripped_texts)
+	is_true = lowered_texts == TRUE_TEXT
+	is_false = lowered_texts == FALSE_TEXT
+	is_known = is_true | is_false
+	is_unknown = ~is_known
+	has_unknown = bool(is_unknown.any())
+	if has_unknown:
+		unknown_texts = texts[is_unknown]
+		first_unknown_text = unknown_texts[0]
+		raise ValueConversionError(source_type.name, Type.BOOL.name, first_unknown_text)
+
+	boolean_column = build_column_with_missing(is_true, missing)
+
+	return boolean_column