numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/table_columns.py

@@ -0,0 +1,214 @@
+"""
+Column operations of a Table: choice, renaming, conversion and addition.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Self
+
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.tables.columns.added_column import add_frame_column
+from numdaplot.tables.columns.chosen_columns import choose_frame_columns
+from numdaplot.tables.columns.column_choice import ColumnChoice
+from numdaplot.tables.columns.conversion import Conversion
+from numdaplot.tables.columns.converted_column import convert_column
+from numdaplot.tables.columns.new_column import NewColumn
+from numdaplot.tables.columns.renamed_columns import rename_frame_columns
+from numdaplot.tables.columns.renaming import Renaming
+from numdaplot.tables.frames.named_column_errors import NamedColumnErrors
+from numdaplot.tables.table_data import TableData
+
+
+class TableColumns(TableData):
+	"""
+	Column operations of a Table: ``choose_columns``, ``rename``, ``convert`` and ``add_column``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def choose_columns(self, choice: ColumnChoice) -> Self:
+		"""
+		Return the Table with only some columns, or without some columns.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		choice
+			The columns, and whether to keep them, in the order of the list, or to drop them.
+
+		Returns
+		-------
+		Self
+			A new Table.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ColumnNotFoundError
+			When a named column does not exist.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> cities = ndp.Array.from_list(["Paris"])
+		>>> prices = ndp.Array.from_list([1.5])
+		>>> table = ndp.Table.from_arrays({"city": cities, "price": prices})
+		>>> table.choose_columns(ndp.ColumnChoice(columns=["city"], mode=ndp.ColumnMode.DROP)).column_names
+		['price']
+		"""
+		chosen_frame = choose_frame_columns(self._frame, choice)
+		chosen_table = self._wrap(chosen_frame)
+
+		return chosen_table
+
+	@checked_arguments
+	def rename(self, renaming: Renaming) -> Self:
+		"""
+		Return the Table with renamed columns, every renaming applied at once.
+
+		Two columns can swap their names in a single call.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		renaming
+			The ``NameChange`` of each renamed column.
+
+		Returns
+		-------
+		Self
+			A new Table, columns in the same order.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		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 numdaplot as ndp
+		>>> table = ndp.Table.from_arrays({"prix": ndp.Array.from_list([1.5])})
+		>>> table.rename(ndp.Renaming(changes=[ndp.NameChange(old_name="prix", new_name="price")])).column_names
+		['price']
+		"""
+		renamed_frame = rename_frame_columns(self._frame, renaming)
+		renamed_table = self._wrap(renamed_frame)
+
+		return renamed_table
+
+	@checked_arguments
+	def convert(self, conversion: Conversion) -> Self:
+		"""
+		Return the Table with a column converted to another type, missing values staying missing.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		conversion
+			The column, its new type, and the date format or the time zone change. Accepted: between number
+			types, from numbers, booleans, categories, dates, datetimes and durations to texts, from texts and
+			categories to numbers, booleans (``"true"`` or ``"false"`` in any case), dates or datetimes, from any
+			other type to categories, between dates and datetimes, and a time zone change of datetimes.
+
+		Returns
+		-------
+		Self
+			A new Table, the column at its place.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ColumnNotFoundError
+			When the column does not exist.
+		IncompatibleTypesError
+			When the conversion is not accepted.
+		InvalidConversionError
+			When the format, the time zone change or the boolean rule does not apply to the conversion.
+		InvalidLimitsError
+			When ``Brackets`` cut integers and a bracket between two limits holds no integer.
+		UnmatchedValueError
+			When a number is in no bracket of ``Brackets`` whose ``others`` is ``Unmatched.ERROR``.
+		ValueConversionError
+			At the first value that cannot be stored in the new type, such as ``"abc"`` read as a number,
+			2.5 stored as an integer, 3 read as a boolean with ``ZERO_ONE``, ``"31/02/2026"`` read as a date, or
+			``"25:00"`` read as a time of day.
+		TimeOverflowError
+			When a value converted to ``DATETIME`` is outside 1677 to 2262.
+		TimeZoneMismatchError
+			When the time zone change does not apply to whether the datetimes have a zone.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> table = ndp.Table.from_arrays({"zip_code": ndp.Array.from_list(["06000", "75001"])})
+		>>> table.convert(ndp.Conversion(column="zip_code", dtype=ndp.Type.INT32))
+		  zip_code
+		     INT32
+		0     6000
+		1    75001
+		"""
+		column = self._read_column(conversion.column)
+		with NamedColumnErrors(column):
+			converted_column = convert_column(column, conversion)
+
+		converted_frame = self._frame.copy(deep=False)
+		converted_frame[conversion.column] = converted_column
+		converted_table = self._wrap(converted_frame)
+
+		return converted_table
+
+	@checked_arguments
+	def add_column(self, new_column: NewColumn) -> Self:
+		"""
+		Return the Table with one more column, or with a column replaced.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		new_column
+			The name, a one-dimensional Array with one value per row, and what to do when the name exists.
+
+		Returns
+		-------
+		Self
+			A new Table. A new column is placed last; a replaced column keeps its place.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		DimensionError
+			When the Array does not have one dimension.
+		ShapeMismatchError
+			When the Array does not have one value per row.
+		DuplicateColumnError
+			When the name exists and ``on_conflict`` is ``Conflict.ERROR``.
+		TimeOverflowError
+			When a column holds a datetime outside 1677 to 2262, or a duration beyond about 292 years.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> table = ndp.Table.from_arrays({"price": ndp.Array.from_list([10.0, 20.0])})
+		>>> taxed_prices = table.column("price") * 1.2
+		>>> table.add_column(ndp.NewColumn(name="taxed_price", values=taxed_prices))
+		    price taxed_price
+		  FLOAT64     FLOAT64
+		0    10.0        12.0
+		1    20.0        24.0
+		"""
+		extended_frame = add_frame_column(self._frame, new_column)
+		extended_table = self._wrap(extended_frame)
+
+		return extended_table

numdaplot/tables/table_conversion.py

@@ -0,0 +1,351 @@
+"""
+Conversion of a Table to and from pandas, Arrays and Python values.
+
+.. versionadded:: 0.1.0
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Self, cast
+
+import pandas
+
+from numdaplot.arrays.array import Array, create_array
+from numdaplot.arrays.conversion.python_values import to_python_list
+from numdaplot.errors.invalid_type_error import InvalidTypeError
+from numdaplot.errors.not_single_value_error import NotSingleValueError
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.tables.files.column_names import ColumnNames
+from numdaplot.tables.frames.array_frame import build_array_frame
+from numdaplot.tables.frames.column_values import convert_column_values, find_column_missing, read_array_values
+from numdaplot.tables.frames.frame_equality import are_frames_equal
+from numdaplot.tables.frames.table_text import format_table
+from numdaplot.tables.frames.time_columns import read_time_objects_frame
+from numdaplot.tables.frames.time_zones import find_column_time_zone
+from numdaplot.tables.preview.notebook_display import format_table_html
+from numdaplot.tables.preview.shown_columns import ShownColumns
+from numdaplot.tables.table_data import TableData
+
+if TYPE_CHECKING:
+	from numdaplot.arrays.equality import Equality
+
+SINGLE_VALUE_COUNT = 1
+FIRST_POSITION = 0
+EQUALITY_TARGET = "Table.is_equal other"
+EQUALITY_EXPECTED = "a Table"
+
+
+class TableConversion(TableData):
+	"""
+	Conversion of a Table to and from pandas, Arrays and Python values.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@classmethod
+	@checked_arguments
+	def from_pandas(cls, frame: pandas.DataFrame, column_names: ColumnNames = ColumnNames.CLEANED) -> Self:
+		"""
+		Return a Table holding a copy of a pandas DataFrame; changing the DataFrame never changes the Table.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		frame
+			A pandas DataFrame whose index is the row numbers 0, 1, 2... Python objects become dates, datetimes,
+			durations, times of day, integers, decimals or booleans when they all are, and texts otherwise. Durations
+			of any unit become ``DURATION``, and ``datetime.time`` objects ``TIME``.
+		column_names
+			Whether the column names are cleaned, ``ColumnNames.CLEANED`` by default: the spaces, tabs and line breaks
+			at the start and the end of each name are removed. ``ColumnNames.KEPT`` keeps the names as written.
+
+		Returns
+		-------
+		Self
+			A new Table.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		UnsupportedIndexError
+			When the index holds other values: call ``reset_index()`` first to keep them as a column.
+		InvalidColumnNameError, DuplicateColumnError
+			When a column name is not a non-empty text, even once cleaned, or appears twice, or two names become the
+			same once cleaned.
+		UnsupportedTypeError
+			When a column has a type numdaplot does not support, such as complex numbers
+			or datetimes with a time zone.
+		TimeOverflowError
+			When a column holds a datetime outside 1677 to 2262, or a duration beyond about 292 years.
+
+		Examples
+		--------
+		>>> import pandas
+		>>> import numdaplot as ndp
+		>>> ndp.Table.from_pandas(pandas.DataFrame({"city": ["Pau", None], "count": [2, 3]}))
+		   city count
+		   TEXT INT64
+		0   Pau     2
+		1  <NA>     3
+		"""
+		table = cls._from_read_frame(frame, column_names)
+
+		return table
+
+	@classmethod
+	@checked_arguments
+	def from_arrays(cls, columns: dict[str, Array]) -> Self:
+		"""
+		Return a Table whose columns hold the values of one-dimensional Arrays.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		columns
+			One Array per column, by column name, all of the same length.
+
+		Returns
+		-------
+		Self
+			A new Table, columns in the order of the dictionary.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		EmptyListError
+			When there is no column.
+		InvalidColumnNameError
+			When a column name is not a non-empty text.
+		DimensionError
+			When an Array does not have one dimension.
+		ShapeMismatchError
+			When the Arrays do not have the same length.
+		TimeOverflowError
+			When a column holds a datetime outside 1677 to 2262, or a duration beyond about 292 years.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> cities = ndp.Array.from_list(["Paris", "Lyon"])
+		>>> prices = ndp.Array.from_list([1.5, 8.0])
+		>>> ndp.Table.from_arrays({"city": cities, "price": prices})
+		    city   price
+		    TEXT FLOAT64
+		0  Paris     1.5
+		1   Lyon     8.0
+		"""
+		frame = build_array_frame(columns)
+		table = cls._create(frame)
+
+		return table
+
+	def to_pandas(self) -> pandas.DataFrame:
+		"""
+		Return a pandas copy of the Table; changing it never changes the Table.
+
+		Integers, booleans and texts use the pandas dtypes that accept missing values (``pd.NA``).
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		pandas.DataFrame
+			A copy, rows numbered from 0. Times of day are ``datetime.time`` objects, as pandas has no type for them.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.Table.from_arrays({"count": ndp.Array.from_list([2, 3])}).to_pandas().dtypes.tolist()
+		[Int64Dtype()]
+		"""
+		pandas_frame = read_time_objects_frame(self._frame)
+
+		return pandas_frame
+
+	@checked_arguments
+	def column(self, column_name: str) -> Array:
+		"""
+		Return the values of a column as an Array.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		column_name
+			The name of the column.
+
+		Returns
+		-------
+		Array
+			A one-dimensional Array of the type of the column, with the same number of values as the Table has rows;
+			a ``CATEGORY`` column gives a ``TEXT`` Array.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ColumnNotFoundError
+			When no column has this name.
+		UnsupportedMissingError
+			When an integer or boolean column has missing values, which an Array cannot hold: remove them with
+			``drop_missing``, or convert an integer column to ``FLOAT64`` first.
+		TimeZoneMismatchError
+			When the column holds datetimes with a time zone, which an Array cannot hold: remove the zone first
+			with ``TimeZoneMode.REMOVE``.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> table = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5, 8.0])})
+		>>> table.column("price").compute(ndp.Sum()).to_value()
+		9.5
+		"""
+		column = self._read_column(column_name)
+		array_values = read_array_values(column)
+		column_array = create_array(array_values)
+
+		return column_array
+
+	def to_value(self) -> Any:
+		"""
+		Return the single value of a Table of one row and one column, as a Python value.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		Any
+			The value, ``None`` when it is missing. A datetime with a time zone keeps its zone.
+
+		Raises
+		------
+		NotSingleValueError
+			When the Table does not hold exactly one value.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> table = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5, 8.0])})
+		>>> highest_price = ndp.Calculation(column="price", function=ndp.Max())
+		>>> table.aggregate(ndp.Aggregation(calculations=[highest_price])).to_value()
+		8.0
+		"""
+		value_count = self.row_count * self.column_count
+		if value_count != SINGLE_VALUE_COUNT:
+			raise NotSingleValueError(value_count)
+
+		column = self._frame.iloc[:, FIRST_POSITION]
+		missing = find_column_missing(column)
+		is_missing = bool(missing[FIRST_POSITION])
+		if is_missing:
+			return None
+
+		time_zone = find_column_time_zone(column)
+		if time_zone is not None:
+			moment = column.iloc[FIRST_POSITION]
+			zone_datetime = moment.to_pydatetime()
+			return zone_datetime
+
+		values = convert_column_values(column)
+		python_values = to_python_list(values)
+		single_value = python_values[FIRST_POSITION]
+
+		return single_value
+
+	@checked_arguments
+	def is_equal(self, equality: Equality) -> bool:
+		"""
+		Return whether this Table and another one have the same columns, in the same order, with the same values.
+
+		Two missing values at the same row are equal. Datetime columns in different time zones are different,
+		even for the same instants.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		equality
+			The other Table, and whether the type of each column must also be the same.
+
+		Returns
+		-------
+		bool
+			True when both Tables are equal.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> integers = ndp.Table.from_arrays({"count": ndp.Array.from_list([1, 2])})
+		>>> decimals = ndp.Table.from_arrays({"count": ndp.Array.from_list([1.0, 2.0])})
+		>>> integers.is_equal(ndp.Equality(other=decimals))
+		True
+		"""
+		other = cast(object, equality.other)
+		if not isinstance(other, TableData):
+			raise InvalidTypeError(EQUALITY_TARGET, EQUALITY_EXPECTED, other)
+
+		other_frame = other._frame
+		is_equal = are_frames_equal(self._frame, other_frame, equality.types)
+
+		return is_equal
+
+	def __repr__(self) -> str:
+		"""
+		Return the text of the Table, with the type of each column under its name.
+
+		A long Table only shows its first and last rows, as in pandas. Every column is shown, going on after a line
+		break, ended by a backslash, when they do not fit in the width of the terminal.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		str
+			The text shown by ``print(table)``.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> print(ndp.Table.from_arrays({"paid": ndp.Array.from_list([True, False])}))
+		    paid
+		    BOOL
+		0   True
+		1  False
+		"""
+		table_text = format_table(self._frame)
+
+		return table_text
+
+	def _repr_html_(self) -> str:
+		"""
+		Return the HTML table a Jupyter notebook shows for a Table written at the end of a cell.
+
+		The table is the one of ``preview``: every column, with the type of each column under its name. A long Table
+		only shows its first and last rows, as its text does.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		str
+			The HTML table, or a note for a Table without rows or without columns.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> table = ndp.Table.from_arrays({"paid": ndp.Array.from_list([True, False])})
+		>>> "BOOL" in table._repr_html_()
+		True
+		"""
+		table_html = format_table_html(self._frame, ShownColumns.ALL)
+
+		return table_html