numdaplot 0.1.0__py3-none-any.whl

numdaplot/plots/data/position_kind.py

@@ -0,0 +1,83 @@
+"""
+Kinds of values a chart places along its ``x`` axis.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class PositionKind(Enum):
+	"""
+	Kinds of values a chart places along its ``x`` axis, each drawn with its own kind of axis.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.array_values import read_array_values
+	>>> prices = ndp.Array.from_list([12.0, 15.5])
+	>>> read_array_values(prices, "LineChart").positions.kind
+	<PositionKind.NUMBERS: 1>
+	"""
+
+	NUMBERS = auto()
+	"""
+	Numbers, placed on a numbered axis.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.array_values import read_array_values
+	>>> prices = ndp.Array.from_list([12.0, 15.5])
+	>>> read_array_values(prices, "LineChart").positions.kind
+	<PositionKind.NUMBERS: 1>
+	"""
+
+	MOMENTS = auto()
+	"""
+	Dates or datetimes, placed on a time axis.
+
+	Examples
+	--------
+	>>> from datetime import date
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.table_values import read_table_values
+	>>> days = ndp.Array.from_list([date(2026, 1, 1), date(2026, 1, 2)])
+	>>> prices = ndp.Array.from_list([12.0, 15.5])
+	>>> sales = ndp.Table.from_arrays({"day": days, "price": prices})
+	>>> read_table_values(sales, "day", ["price"], "LineChart").positions.kind
+	<PositionKind.MOMENTS: 2>
+	"""
+
+	TEXTS = auto()
+	"""
+	Texts, each placed at its own position labeled with it.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.table_values import read_table_values
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon"])
+	>>> prices = ndp.Array.from_list([12.0, 15.5])
+	>>> sales = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> read_table_values(sales, "city", ["price"], "LineChart").positions.kind
+	<PositionKind.TEXTS: 3>
+	"""
+
+	TIMES = auto()
+	"""
+	Times of day, placed on an axis of one day labeled ``HH:MM``.
+
+	Examples
+	--------
+	>>> from datetime import time
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.table_values import read_table_values
+	>>> hours = ndp.Array.from_list([time(8), time(17, 30)])
+	>>> counts = ndp.Array.from_list([12.0, 15.5])
+	>>> traffic = ndp.Table.from_arrays({"hour": hours, "count": counts})
+	>>> read_table_values(traffic, "hour", ["count"], "LineChart").positions.kind
+	<PositionKind.TIMES: 4>
+	"""

numdaplot/plots/data/renamed_layers.py

@@ -0,0 +1,340 @@
+"""
+Charts of a Plot with their columns shown under new names.
+
+.. versionadded:: 0.1.0
+"""
+
+import dataclasses
+from typing import cast
+
+import numpy
+
+from numdaplot.plots.chart_layer import ChartLayer
+from numdaplot.plots.data.chart_values import ChartValues, Series
+from numdaplot.plots.data.missing_cells import MissingCounts
+from numdaplot.plots.data.point_values import PointValues
+from numdaplot.plots.data.sample_values import SampleValues
+from numdaplot.plots.data.table_values import name_columns
+from numdaplot.tables.columns.renaming import Renaming
+
+
+def rename_layers(layers: list[ChartLayer], renaming: Renaming | None) -> list[ChartLayer]:
+	"""
+	Return the charts of a Plot with their columns shown under their new names.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	layers
+		Every chart of the Plot.
+	renaming
+		The names under which some columns are shown, or None to keep every name.
+
+	Returns
+	-------
+	list[ChartLayer]
+		New charts whose names, and the default labels built from them, are the shown names.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.chart_layer import ChartLayer
+	>>> from numdaplot.plots.data.array_values import read_array_values
+	>>> from numdaplot.plots.data.renamed_layers import rename_layers
+	>>> grid = ndp.Array.from_list([[12.0, 8.0]])
+	>>> layer = ChartLayer(ndp.LineChart(), read_array_values(grid, "LineChart"))
+	>>> renaming = ndp.Renaming(changes=[ndp.NameChange(old_name="0", new_name="Paris")])
+	>>> [series.name for series in rename_layers([layer], renaming)[0].values.series]
+	['Paris', '1']
+	"""
+	if renaming is None:
+		return layers
+
+	new_names = {change.old_name: change.new_name for change in renaming.changes}
+	renamed_layers = list[ChartLayer]()
+	for layer in layers:
+		renamed_layer = rename_layer(layer, new_names)
+		renamed_layers.append(renamed_layer)
+
+	return renamed_layers
+
+
+def rename_layer(layer: ChartLayer, new_names: dict[str, str]) -> ChartLayer:
+	"""
+	Return one chart with its columns shown under their new names.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	layer
+		A chart and its values.
+	new_names
+		The new name of each renamed column.
+
+	Returns
+	-------
+	ChartLayer
+		A new chart, with renamed values and points.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.chart_layer import ChartLayer
+	>>> from numdaplot.plots.data.array_values import read_array_values
+	>>> from numdaplot.plots.data.renamed_layers import rename_layer
+	>>> layer = ChartLayer(ndp.LineChart(), read_array_values(ndp.Array.from_list([12.0]), "LineChart"))
+	>>> rename_layer(layer, {"0": "Paris"}).values.series[0].name
+	'Paris'
+	"""
+	renamed_values = rename_values(layer.values, new_names)
+	renamed_points = layer.points
+	if layer.points is not None:
+		renamed_points = rename_points(layer.points, new_names)
+
+	renamed_layer = dataclasses.replace(layer, values=renamed_values, points=renamed_points)
+
+	return renamed_layer
+
+
+def rename_values(values: ChartValues | SampleValues, new_names: dict[str, str]) -> ChartValues | SampleValues:
+	"""
+	Return the values of one chart with their columns shown under their new names.
+
+	The label of the axis of the values follows when it names the drawn columns.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of a chart.
+	new_names
+		The new name of each renamed column.
+
+	Returns
+	-------
+	ChartValues or SampleValues
+		New values of the same kind.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.table_values import read_table_values
+	>>> from numdaplot.plots.data.renamed_layers import rename_values
+	>>> prices = ndp.Array.from_list([12.0, 15.5])
+	>>> sales = ndp.Table.from_arrays({"price": prices})
+	>>> rename_values(read_table_values(sales, None, ["price"], "LineChart"), {"price": "Price"}).value_name
+	'Price'
+	"""
+	if isinstance(values, MissingCounts):
+		renamed_counts = rename_missing_counts(values, new_names)
+		return renamed_counts
+
+	renamed_series = rename_series(values.series, new_names)
+	renamed_value_name = rename_value_name(values, renamed_series)
+	if isinstance(values, SampleValues):
+		renamed_group_name = rename_optional(values.group_name, new_names)
+		renamed_samples = dataclasses.replace(
+			values, series=renamed_series, group_name=renamed_group_name, value_name=renamed_value_name
+		)
+		return renamed_samples
+
+	renamed_position_name = rename_optional(values.positions.name, new_names)
+	renamed_positions = dataclasses.replace(values.positions, name=renamed_position_name)
+	renamed_chart_values = dataclasses.replace(
+		values, positions=renamed_positions, series=renamed_series, value_name=renamed_value_name
+	)
+
+	return renamed_chart_values
+
+
+def rename_missing_counts(counts: MissingCounts, new_names: dict[str, str]) -> MissingCounts:
+	"""
+	Return the counts of a missing value chart with its columns shown under their new names.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	counts
+		The counts, one position per column of the Table.
+	new_names
+		The new name of each renamed column.
+
+	Returns
+	-------
+	MissingCounts
+		New counts whose positions are the shown names.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.missing_cells import read_missing_counts
+	>>> from numdaplot.plots.data.renamed_layers import rename_missing_counts
+	>>> flats = ndp.Table.from_arrays({"price": ndp.Array.from_list([12.0, None])})
+	>>> counts = read_missing_counts(flats, ndp.Measure.COUNT)
+	>>> rename_missing_counts(counts, {"price": "Price"}).positions.values.tolist()
+	['Price']
+	"""
+	raw_columns = counts.positions.values.tolist()
+	column_names = cast(list[str], raw_columns)
+	shown_names = list[str]()
+	for column_name in column_names:
+		shown_name = new_names.get(column_name, column_name)
+		shown_names.append(shown_name)
+
+	position_dtype = counts.positions.values.dtype
+	shown_values = numpy.array(shown_names, dtype=position_dtype)
+	renamed_positions = dataclasses.replace(counts.positions, values=shown_values)
+	renamed_counts = dataclasses.replace(counts, positions=renamed_positions)
+
+	return renamed_counts
+
+
+def rename_series(series: list[Series], new_names: dict[str, str]) -> list[Series]:
+	"""
+	Return series named after the shown names of their columns.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	series
+		The series of a chart.
+	new_names
+		The new name of each renamed column.
+
+	Returns
+	-------
+	list[Series]
+		New series with the same numbers.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.data.chart_values import Series
+	>>> from numdaplot.plots.data.renamed_layers import rename_series
+	>>> rename_series([Series("price", numpy.array([12.0]))], {"price": "Price"})[0].name
+	'Price'
+	"""
+	renamed_series = list[Series]()
+	for one_series in series:
+		shown_name = new_names.get(one_series.name, one_series.name)
+		shown_series = dataclasses.replace(one_series, name=shown_name)
+		renamed_series.append(shown_series)
+
+	return renamed_series
+
+
+def rename_value_name(values: ChartValues | SampleValues, renamed_series: list[Series]) -> str | None:
+	"""
+	Return the label of the axis of the values, following the series when it names them.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of a chart, with their series under their column names.
+	renamed_series
+		The same series under their shown names.
+
+	Returns
+	-------
+	str or None
+		The names of the renamed series when the label names the series, the label unchanged otherwise, such as
+		``"value"`` for an Array.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.table_values import read_table_values
+	>>> from numdaplot.plots.data.renamed_layers import rename_series, rename_value_name
+	>>> prices = ndp.Array.from_list([12.0])
+	>>> costs = ndp.Array.from_list([8.0])
+	>>> sales = ndp.Table.from_arrays({"price": prices, "cost": costs})
+	>>> values = read_table_values(sales, None, ["price", "cost"], "LineChart")
+	>>> rename_value_name(values, rename_series(values.series, {"cost": "Cost"}))
+	'price, Cost'
+	"""
+	if values.value_name is None:
+		return None
+
+	column_names = [one_series.name for one_series in values.series]
+	shown_names = [one_series.name for one_series in renamed_series]
+	if column_names == []:
+		return values.value_name
+
+	column_label = name_columns(column_names)
+	if values.value_name != column_label:
+		return values.value_name
+
+	shown_label = name_columns(shown_names)
+
+	return shown_label
+
+
+def rename_points(points: PointValues, new_names: dict[str, str]) -> PointValues:
+	"""
+	Return the colors and the sizes of points with their columns shown under their new names.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	points
+		The colors and the sizes of a scatter chart.
+	new_names
+		The new name of each renamed column.
+
+	Returns
+	-------
+	PointValues
+		New points with the same colors and sizes.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.data.point_values import PointValues
+	>>> from numdaplot.plots.data.renamed_layers import rename_points
+	>>> rename_points(PointValues("zone", None, None, None), {"zone": "Zone"}).color_name
+	'Zone'
+	"""
+	color_name = rename_optional(points.color_name, new_names)
+	size_name = rename_optional(points.size_name, new_names)
+	renamed_points = dataclasses.replace(points, color_name=color_name, size_name=size_name)
+
+	return renamed_points
+
+
+def rename_optional(name: str | None, new_names: dict[str, str]) -> str | None:
+	"""
+	Return the shown name of a column, when there is a column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	name
+		A column name, or None.
+	new_names
+		The new name of each renamed column.
+
+	Returns
+	-------
+	str or None
+		The new name, the name itself when it is not renamed, or None.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.data.renamed_layers import rename_optional
+	>>> rename_optional("day", {"day": "Day"}), rename_optional("hour", {"day": "Day"}), rename_optional(None, {})
+	('Day', 'hour', None)
+	"""
+	if name is None:
+		return None
+
+	shown_name = new_names.get(name, name)
+
+	return shown_name

numdaplot/plots/data/sample_values.py

@@ -0,0 +1,160 @@
+"""
+Values a histogram or a box chart sums up, 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.arrays.array import Array
+from numdaplot.data_types.type import Type
+from numdaplot.plots.data.array_values import read_array_values
+from numdaplot.plots.data.chart_data import require_column_setting, require_no_column_settings
+from numdaplot.plots.data.chart_values import Series
+from numdaplot.plots.data.column_reading import read_texts
+from numdaplot.plots.data.table_values import name_columns, read_series
+from numdaplot.tables.columns.column_names import require_known_columns
+from numdaplot.tables.table import Table
+from numdaplot.tables.table_data import read_stored_frame
+
+COLUMNS_SETTING = "columns"
+GROUP_SETTING = "group_by"
+
+
+@dataclass(frozen=True, eq=False)
+class SampleValues:
+	"""
+	The columns of numbers or times of day a histogram or a box chart sums up, and the groups splitting their rows.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	series
+		One series per column, NaN where a value is missing, a time of day being its hours since midnight.
+	groups
+		The group of each row, None where it is missing, or None without ``group_by``.
+	group_name
+		The ``group_by`` column, or None.
+	value_name
+		The default label of the axis of the values: the name of the single 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 numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.chart_values import Series
+	>>> from numdaplot.plots.data.sample_values import SampleValues
+	>>> SampleValues([Series("price", numpy.array([12.0]))], None, None, "price", ndp.Type.FLOAT64).value_name
+	'price'
+	"""
+
+	series: list[Series]
+	groups: NDArray[Any] | None
+	group_name: str | None
+	value_name: str | None
+	value_type: Type
+
+
+def read_sample_values(
+	data: Table | Array, column_names: list[str] | None, group_name: str | None, chart_name: str
+) -> SampleValues:
+	"""
+	Return the columns a histogram or a box chart sums up, and their groups.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	data
+		The Table or the Array drawn.
+	column_names
+		The columns of a Table, None for an Array, whose columns are all read.
+	group_name
+		The ``group_by`` column of a Table, holding texts, booleans or times of day, or None.
+	chart_name
+		Name of the chart class, shown in error messages.
+
+	Returns
+	-------
+	SampleValues
+		One series per column, and the group of each row.
+
+	Raises
+	------
+	InvalidChartDataError
+		When a Table has no columns, or an Array has columns or ``group_by``.
+	ColumnNotFoundError
+		When a column does not exist.
+	IncompatibleTypesError
+		When a column holds neither numbers nor times of day, the columns mix them, or ``group_by`` holds
+		neither texts, booleans nor times of day.
+	DimensionError
+		When an Array has more than two dimensions.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.sample_values import read_sample_values
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon"])
+	>>> prices = ndp.Array.from_list([12.0, 9.5])
+	>>> flats = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> read_sample_values(flats, ["price"], "city", "BoxChart").groups
+	array(['Paris', 'Lyon'], dtype=object)
+	"""
+	if isinstance(data, Array):
+		column_settings = dict[str, object]({COLUMNS_SETTING: column_names, GROUP_SETTING: group_name})
+		require_no_column_settings(chart_name, column_settings)
+		array_values = read_array_values(data, chart_name)
+		array_samples = SampleValues(array_values.series, None, None, array_values.value_name, array_values.value_type)
+		return array_samples
+
+	required_names = require_column_setting(chart_name, COLUMNS_SETTING, column_names)
+	frame = read_stored_frame(data)
+	known_names = frame.columns.tolist()
+	require_known_columns(required_names, known_names)
+	series, value_type = read_series(frame, required_names, chart_name)
+	value_name = name_columns(required_names)
+	groups = None
+	if group_name is not None:
+		require_known_columns([group_name], known_names)
+		groups = read_texts(frame[group_name], chart_name)
+
+	table_samples = SampleValues(series, groups, group_name, value_name, value_type)
+
+	return table_samples
+
+
+def drop_missing_numbers(numbers: NDArray[numpy.float64]) -> NDArray[numpy.float64]:
+	"""
+	Return the numbers that are present, in their order.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	numbers
+		Numbers, NaN where a value is missing.
+
+	Returns
+	-------
+	NDArray[numpy.float64]
+		The numbers without NaN.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.data.sample_values import drop_missing_numbers
+	>>> drop_missing_numbers(numpy.array([3.0, numpy.nan, 1.0]))
+	array([3., 1.])
+	"""
+	present = ~numpy.isnan(numbers)
+	present_numbers = numbers[present]
+
+	return present_numbers