numdaplot 0.1.0__py3-none-any.whl

numdaplot/plots/data/chart_data.py

@@ -0,0 +1,143 @@
+"""
+Checks of the column settings of a chart against the data it draws.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.arrays.array import Array
+from numdaplot.errors.invalid_chart_data_error import InvalidChartDataError
+from numdaplot.plots.data.array_values import read_array_values
+from numdaplot.plots.data.chart_values import ChartValues
+from numdaplot.plots.data.table_values import read_table_values
+from numdaplot.tables.table import Table
+
+TABLE_NAME = "a Table"
+ARRAY_NAME = "an Array"
+X_SETTING = "x"
+Y_SETTING = "y"
+
+
+def require_no_column_settings(chart_name: str, column_settings: dict[str, object]) -> None:
+	"""
+	Check that a chart drawing an Array names no column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	chart_name
+		Name of the chart class, shown in the error message.
+	column_settings
+		Each column setting of the chart by name, such as ``{"x": None, "y": None}``.
+
+	Raises
+	------
+	InvalidChartDataError
+		At the first setting that is not None.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.chart_data import require_no_column_settings
+	>>> try:
+	... 	require_no_column_settings("LineChart", {"x": "day", "y": None})
+	... except ndp.InvalidChartDataError as error:
+	... 	print(error)
+	LineChart takes no x for an Array.
+	"""
+	for setting_name, setting_value in column_settings.items():
+		if setting_value is not None:
+			raise InvalidChartDataError(chart_name, setting_name, ARRAY_NAME, False)
+
+
+def require_column_setting[SettingValue](
+	chart_name: str, setting_name: str, setting_value: SettingValue | None
+) -> SettingValue:
+	"""
+	Check that a chart drawing a Table has a column setting it needs, and return it.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	chart_name
+		Name of the chart class, shown in the error message.
+	setting_name
+		Name of the setting, such as ``y``.
+	setting_value
+		The value of the setting.
+
+	Returns
+	-------
+	SettingValue
+		The value, known not to be None.
+
+	Raises
+	------
+	InvalidChartDataError
+		When the value is None.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.chart_data import require_column_setting
+	>>> try:
+	... 	require_column_setting("LineChart", "y", None)
+	... except ndp.InvalidChartDataError as error:
+	... 	print(error)
+	LineChart needs y for a Table.
+	"""
+	if setting_value is None:
+		raise InvalidChartDataError(chart_name, setting_name, TABLE_NAME, True)
+
+	return setting_value
+
+
+def read_chart_values(
+	data: Table | Array, x_name: str | None, y_names: list[str] | None, chart_name: str
+) -> ChartValues:
+	"""
+	Return the positions and the series a line or bar chart draws from a Table or an Array.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	data
+		The Table or the Array drawn.
+	x_name
+		The ``x`` column of a Table, None for its row numbers and for an Array.
+	y_names
+		The ``y`` columns of a Table, None for an Array.
+	chart_name
+		Name of the chart class, shown in error messages.
+
+	Returns
+	-------
+	ChartValues
+		The values read by ``read_table_values`` or ``read_array_values``.
+
+	Raises
+	------
+	InvalidChartDataError
+		When a Table has no ``y`` columns, or an Array has ``x`` or ``y`` columns.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.chart_data import read_chart_values
+	>>> prices = ndp.Array.from_list([12.0, 15.5])
+	>>> sales = ndp.Table.from_arrays({"price": prices})
+	>>> read_chart_values(sales, None, ["price"], "LineChart").value_name
+	'price'
+	"""
+	if isinstance(data, Array):
+		column_settings = dict[str, object]({X_SETTING: x_name, Y_SETTING: y_names})
+		require_no_column_settings(chart_name, column_settings)
+		array_values = read_array_values(data, chart_name)
+		return array_values
+
+	required_y_names = require_column_setting(chart_name, Y_SETTING, y_names)
+	table_values = read_table_values(data, x_name, required_y_names, chart_name)
+
+	return table_values

numdaplot/plots/data/chart_values.py

@@ -0,0 +1,109 @@
+"""
+Values a chart draws, read from a Table or an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.data_types.type import Type
+from numdaplot.plots.data.position_kind import PositionKind
+
+
+@dataclass(frozen=True, eq=False)
+class Positions:
+	"""
+	The ``x`` values of a chart.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	kind
+		Numbers, moments, texts or times of day.
+	values
+		One value per row: float64 numbers with NaN, datetime64[ns] clock times with NaT, texts, or float64 hours
+		since midnight with NaN.
+	name
+		The name of the ``x`` column, or None for row numbers.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.data.chart_values import Positions
+	>>> from numdaplot.plots.data.position_kind import PositionKind
+	>>> Positions(PositionKind.NUMBERS, numpy.array([0.0, 1.0]), None).values
+	array([0., 1.])
+	"""
+
+	kind: PositionKind
+	values: NDArray[Any]
+	name: str | None
+
+
+@dataclass(frozen=True, eq=False)
+class Series:
+	"""
+	One series of values drawn by a chart, as numbers.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	name
+		The name shown in the legend: the column name, or the column number of an Array.
+	values
+		One float64 number per row, NaN where the value is missing or not drawn. A time of day is its hours since
+		midnight, such as 15.5 for 15:30.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.data.chart_values import Series
+	>>> Series("price", numpy.array([12.0, numpy.nan])).name
+	'price'
+	"""
+
+	name: str
+	values: NDArray[numpy.float64]
+
+
+@dataclass(frozen=True, eq=False)
+class ChartValues:
+	"""
+	The positions and the series a chart draws.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	positions
+		The ``x`` values.
+	series
+		The series of numbers, each with one value per position.
+	rows
+		The row numbers of the source kept for drawing, to read other columns of the same rows.
+	value_name
+		The default label of the axis of the series: the name of the single ``y`` column of a Table, None
+		otherwise.
+	value_type
+		The type of the first series, of the family of every series: numbers or times of day.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.array_values import read_array_values
+	>>> grid = ndp.Array.from_list([[1.0, 2.0], [3.0, 4.0]])
+	>>> [series.name for series in read_array_values(grid, "LineChart").series]
+	['0', '1']
+	"""
+
+	positions: Positions
+	series: list[Series]
+	rows: NDArray[numpy.intp]
+	value_name: str | None
+	value_type: Type

numdaplot/plots/data/column_reading.py

@@ -0,0 +1,468 @@
+"""
+Reading of the Table columns a chart draws.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.data_types.time_of_day import read_times
+from numdaplot.data_types.type import Type
+from numdaplot.data_types.value_family import ValueFamily, find_family
+from numdaplot.errors.incompatible_types_error import IncompatibleTypesError
+from numdaplot.plots.charts.box_chart import BoxChart
+from numdaplot.plots.charts.histogram_chart import HistogramChart
+from numdaplot.plots.charts.line_chart import LineChart
+from numdaplot.plots.charts.scatter_chart import ScatterChart
+from numdaplot.plots.data.position_kind import PositionKind
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.frames.column_values import find_column_missing, find_column_type
+from numdaplot.tables.frames.named_column_errors import NamedColumnErrors
+from numdaplot.tables.frames.time_zones import find_column_time_zone
+
+POSITION_KINDS = {
+	ValueFamily.NUMBER: PositionKind.NUMBERS,
+	ValueFamily.MOMENT: PositionKind.MOMENTS,
+	ValueFamily.TEXT: PositionKind.TEXTS,
+	ValueFamily.BOOL: PositionKind.TEXTS,
+	ValueFamily.TIME: PositionKind.TIMES,
+}
+NUMBER_FAMILIES = frozenset({ValueFamily.NUMBER})
+VALUE_FAMILIES = frozenset({ValueFamily.NUMBER, ValueFamily.TIME})
+TIME_VALUE_CHARTS = frozenset({LineChart.__name__, ScatterChart.__name__, HistogramChart.__name__, BoxChart.__name__})
+LABEL_FAMILIES = frozenset({ValueFamily.TEXT, ValueFamily.BOOL, ValueFamily.TIME})
+HOUR_LABEL_PATTERN = "%H:%M"
+MICROSECONDS_PER_HOUR = 3_600_000_000
+TIME_DTYPE = numpy.dtype("timedelta64[us]")
+MOMENT_DTYPE = numpy.dtype("datetime64[ns]")
+TEXT_DTYPE = "string"
+PYTHON_OBJECT_DTYPE = numpy.dtype(object)
+
+
+def require_column_family(column: Column, accepted_families: frozenset[ValueFamily], chart_name: str) -> ValueFamily:
+	"""
+	Check that a column holds values a chart draws, and return their family.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column.
+	accepted_families
+		The families the chart draws in this column.
+	chart_name
+		Name of the chart class, shown in the error message.
+
+	Returns
+	-------
+	ValueFamily
+		The family of the column.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the column holds values of another family, such as durations.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.column_reading import NUMBER_FAMILIES, require_column_family
+	>>> try:
+	... 	require_column_family(pandas.Series([True], dtype="boolean"), NUMBER_FAMILIES, "LineChart")
+	... except ndp.IncompatibleTypesError as error:
+	... 	print(error)
+	Cannot apply LineChart to BOOL.
+	"""
+	column_type = find_column_type(column)
+	family = find_family(column_type)
+	if family not in accepted_families:
+		with NamedColumnErrors(column):
+			raise IncompatibleTypesError(chart_name, [column_type.name])
+
+	return family
+
+
+def read_numbers(column: Column, chart_name: str) -> NDArray[numpy.float64]:
+	"""
+	Return a column of numbers as float64 values, NaN where a value is missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column.
+	chart_name
+		Name of the chart class, shown in the error message.
+
+	Returns
+	-------
+	NDArray[numpy.float64]
+		One number per row.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the column does not hold numbers.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.plots.data.column_reading import read_numbers
+	>>> read_numbers(pandas.Series([3, None], dtype="Int64"), "LineChart")
+	array([ 3., nan])
+	"""
+	require_column_family(column, NUMBER_FAMILIES, chart_name)
+	numbers = column.to_numpy(dtype=numpy.float64, na_value=numpy.nan)
+
+	return numbers
+
+
+def find_value_families(chart_name: str) -> frozenset[ValueFamily]:
+	"""
+	Return the families of the values a chart draws: numbers, and times of day for the charts measuring them.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	chart_name
+		Name of the chart class.
+
+	Returns
+	-------
+	frozenset[ValueFamily]
+		Numbers and times of day for a LineChart, a ScatterChart, a HistogramChart or a BoxChart, numbers only
+		otherwise.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.data.column_reading import find_value_families
+	>>> sorted(family.name for family in find_value_families("BoxChart"))
+	['NUMBER', 'TIME']
+	>>> sorted(family.name for family in find_value_families("BarChart"))
+	['NUMBER']
+	"""
+	if chart_name in TIME_VALUE_CHARTS:
+		return VALUE_FAMILIES
+
+	return NUMBER_FAMILIES
+
+
+def read_values(column: Column, chart_name: str) -> NDArray[numpy.float64]:
+	"""
+	Return a column of values a chart draws as float64 numbers, a time of day being its hours since midnight.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column.
+	chart_name
+		Name of the chart class, shown in the error message.
+
+	Returns
+	-------
+	NDArray[numpy.float64]
+		One number per row, NaN where a value is missing.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the column does not hold numbers, or times of day for a chart measuring them.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import pandas
+	>>> from numdaplot.plots.data.column_reading import read_values
+	>>> read_values(pandas.Series(numpy.array([55800000000], dtype="timedelta64[us]")), "BoxChart")
+	array([15.5])
+	"""
+	value_families = find_value_families(chart_name)
+	family = require_column_family(column, value_families, chart_name)
+	if family == ValueFamily.TIME:
+		hours = read_hours(column)
+		return hours
+
+	numbers = read_numbers(column, chart_name)
+
+	return numbers
+
+
+def require_same_family(column: Column, value_type: Type, chart_name: str) -> None:
+	"""
+	Check that a column holds values of the family of the first column a chart draws on the same axis.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column.
+	value_type
+		The type of the first column.
+	chart_name
+		Name of the chart class, shown in the error message.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When one holds numbers and the other times of day.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.column_reading import require_same_family
+	>>> counts = pandas.Series([3.0], name="count")
+	>>> try:
+	... 	require_same_family(counts, ndp.Type.TIME, "BoxChart")
+	... except ndp.IncompatibleTypesError as error:
+	... 	print(error)
+	Cannot apply BoxChart to the FLOAT64 column 'count' and TIME.
+	"""
+	column_type = find_column_type(column)
+	column_family = find_family(column_type)
+	value_family = find_family(value_type)
+	if column_family != value_family:
+		with NamedColumnErrors(column):
+			raise IncompatibleTypesError(chart_name, [column_type.name, value_type.name])
+
+
+def read_texts(column: Column, chart_name: str) -> NDArray[Any]:
+	"""
+	Return a column of texts, categories, booleans or times of day as Python texts, None where a value is missing.
+
+	A time of day is written ``HH:MM``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column.
+	chart_name
+		Name of the chart class, shown in the error message.
+
+	Returns
+	-------
+	NDArray
+		One text per row, in a numpy array of Python objects.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the column does not hold texts.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.plots.data.column_reading import read_texts
+	>>> read_texts(pandas.Series(["Paris", None], dtype="string"), "BarChart")
+	array(['Paris', None], dtype=object)
+	"""
+	family = require_column_family(column, LABEL_FAMILIES, chart_name)
+	if family == ValueFamily.TIME:
+		hour_texts = write_hour_labels(column)
+		return hour_texts
+
+	text_column = column.astype(TEXT_DTYPE)
+	text_values = text_column.tolist()
+	missing = find_column_missing(column)
+	value_pairs = zip(text_values, missing, strict=True)
+	present_texts = [None if is_missing else text for text, is_missing in value_pairs]
+	texts = numpy.array(present_texts, dtype=PYTHON_OBJECT_DTYPE)
+
+	return texts
+
+
+def read_moments(column: Column) -> NDArray[numpy.datetime64]:
+	"""
+	Return a column of dates or datetimes as the clock times shown in its time zone, NaT where a value is missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A date or datetime column.
+
+	Returns
+	-------
+	NDArray[numpy.datetime64]
+		One datetime64[ns] value per row, without time zone.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.plots.data.column_reading import read_moments
+	>>> utc_times = pandas.Series(pandas.to_datetime(["2026-07-01 10:30"])).dt.tz_localize("UTC")
+	>>> read_moments(utc_times.dt.tz_convert("Europe/Paris"))
+	array(['2026-07-01T12:30:00.000000000'], dtype='datetime64[ns]')
+	"""
+	clock_times = column
+	time_zone = find_column_time_zone(column)
+	if time_zone is not None:
+		clock_times = column.dt.tz_localize(None)
+
+	moments = clock_times.to_numpy(dtype=MOMENT_DTYPE)
+
+	return moments
+
+
+def read_positions(column: Column, chart_name: str) -> tuple[PositionKind, NDArray[Any]]:
+	"""
+	Return the ``x`` values of a chart read from a column, with their kind.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column of numbers, dates, datetimes or texts.
+	chart_name
+		Name of the chart class, shown in the error message.
+
+	Returns
+	-------
+	tuple[PositionKind, NDArray]
+		The kind and the values, read by ``read_numbers``, ``read_moments`` or ``read_texts``.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the column holds durations.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.plots.data.column_reading import read_positions
+	>>> read_positions(pandas.Series(["Paris"], dtype="string"), "BarChart")
+	(<PositionKind.TEXTS: 3>, array(['Paris'], dtype=object))
+	"""
+	accepted_families = frozenset(POSITION_KINDS)
+	family = require_column_family(column, accepted_families, chart_name)
+	kind = POSITION_KINDS[family]
+	if kind == PositionKind.NUMBERS:
+		numbers = read_numbers(column, chart_name)
+		return kind, numbers
+
+	if kind == PositionKind.MOMENTS:
+		moments = read_moments(column)
+		return kind, moments
+
+	if kind == PositionKind.TIMES:
+		hours = read_hours(column)
+		return kind, hours
+
+	texts = read_texts(column, chart_name)
+
+	return kind, texts
+
+
+def read_hours(column: Column) -> NDArray[numpy.float64]:
+	"""
+	Return a column of times of day as the hours since midnight, NaN where a time is missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column of times of day.
+
+	Returns
+	-------
+	NDArray[numpy.float64]
+		The hours, such as 15.5 for 15:30.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import pandas
+	>>> from numdaplot.plots.data.column_reading import read_hours
+	>>> read_hours(pandas.Series(numpy.array([55800000000, "NaT"], dtype="timedelta64[us]")))
+	array([15.5,  nan])
+	"""
+	stored_times = column.to_numpy(dtype=TIME_DTYPE)
+	hours = count_hours(stored_times)
+
+	return hours
+
+
+def count_hours(stored_times: NDArray[numpy.timedelta64]) -> NDArray[numpy.float64]:
+	"""
+	Return stored times of day as the hours since midnight, NaN where a time is missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	stored_times
+		Times of day as ``timedelta64[us]`` values since midnight, of any shape.
+
+	Returns
+	-------
+	NDArray[numpy.float64]
+		The hours, of the same shape, such as 15.5 for 15:30.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.data.column_reading import count_hours
+	>>> count_hours(numpy.array([[55800000000, "NaT"]], dtype="timedelta64[us]"))
+	array([[15.5,  nan]])
+	"""
+	missing = numpy.isnat(stored_times)
+	microseconds = stored_times.astype(numpy.float64)
+	hours = microseconds / MICROSECONDS_PER_HOUR
+	present_hours = numpy.where(missing, numpy.nan, hours)
+
+	return present_hours
+
+
+def write_hour_labels(column: Column) -> NDArray[Any]:
+	"""
+	Return a column of times of day as ``HH:MM`` texts, None where a time is missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column of times of day.
+
+	Returns
+	-------
+	NDArray
+		One text per row, in a numpy array of Python objects.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import pandas
+	>>> from numdaplot.plots.data.column_reading import write_hour_labels
+	>>> write_hour_labels(pandas.Series(numpy.array([55800000000, "NaT"], dtype="timedelta64[us]")))
+	array(['15:30', None], dtype=object)
+	"""
+	stored_times = column.to_numpy(dtype=TIME_DTYPE)
+	times = read_times(stored_times)
+	hour_labels = list[str | None]()
+	for time_of_day in times:
+		hour_label = None
+		if time_of_day is not None:
+			hour_label = time_of_day.strftime(HOUR_LABEL_PATTERN)
+
+		hour_labels.append(hour_label)
+
+	label_values = numpy.array(hour_labels, dtype=PYTHON_OBJECT_DTYPE)
+
+	return label_values