numdaplot 0.1.0__py3-none-any.whl

numdaplot/plots/data/heatmap_values.py

@@ -0,0 +1,63 @@
+"""
+Values of a HeatmapChart.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.arrays.array import Array
+from numdaplot.plots.charts.heatmap_chart import HeatmapChart
+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 ChartValues
+from numdaplot.plots.data.table_values import read_table_values
+from numdaplot.tables.table import Table
+
+CHART_NAME = "HeatmapChart"
+COLUMNS_SETTING = "columns"
+LABELS_SETTING = "labels"
+
+
+def read_heatmap_values(data: Table | Array, chart: HeatmapChart) -> ChartValues:
+	"""
+	Return the row labels and the columns a HeatmapChart draws.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	data
+		The Table or the Array drawn.
+	chart
+		The ``columns`` and the ``labels`` of a Table.
+
+	Returns
+	-------
+	ChartValues
+		The row labels as positions, and one series per column.
+
+	Raises
+	------
+	InvalidChartDataError
+		When a Table has no ``columns``, or an Array has ``columns`` or ``labels``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.heatmap_values import read_heatmap_values
+	>>> grid = ndp.Array.from_list([[1.0, 2.0], [3.0, 4.0]])
+	>>> try:
+	... 	read_heatmap_values(grid, ndp.HeatmapChart(labels="city"))
+	... except ndp.InvalidChartDataError as error:
+	... 	print(error)
+	HeatmapChart takes no labels for an Array.
+	"""
+	if isinstance(data, Array):
+		column_settings = dict[str, object]({COLUMNS_SETTING: chart.columns, LABELS_SETTING: chart.labels})
+		require_no_column_settings(CHART_NAME, column_settings)
+		array_values = read_array_values(data, CHART_NAME)
+		return array_values
+
+	column_names = require_column_setting(CHART_NAME, COLUMNS_SETTING, chart.columns)
+	table_values = read_table_values(data, chart.labels, column_names, CHART_NAME)
+
+	return table_values

numdaplot/plots/data/missing_cells.py

@@ -0,0 +1,165 @@
+"""
+Missing values of a Table, read to be drawn.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.data_types.type import Type
+from numdaplot.plots.data.chart_values import ChartValues, Positions, Series
+from numdaplot.plots.data.position_kind import PositionKind
+from numdaplot.positions.axis import Axis
+from numdaplot.ratios.measure import Measure
+from numdaplot.tables.missing.missing_count import MissingCount
+from numdaplot.tables.missing.missing_counts import (
+	COLUMN_NAMES_COLUMN,
+	MEASURE_COLUMN_NAMES,
+	count_frame_missing,
+	find_frame_missing,
+)
+from numdaplot.tables.table import Table
+from numdaplot.tables.table_data import read_stored_frame
+
+MEASURE_LABELS = {
+	Measure.COUNT: "Missing count",
+	Measure.RATIO: "Missing ratio",
+}
+FLOAT_DTYPE = numpy.dtype(numpy.float64)
+COLUMN_SUM_AXIS = 0
+COLUMN_AXIS_NAME = "Column"
+TEXT_DTYPE = numpy.dtype(object)
+
+
+@dataclass(frozen=True, eq=False)
+class MissingCounts(ChartValues):
+	"""
+	The bars of the missing values of each column, with what their labels show.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	positions
+		The column names.
+	series
+		The single series of bars, in the chosen measure.
+	rows
+		The number of each column.
+	value_name
+		The label of the axis of the values.
+	value_type
+		``FLOAT64``, the type of the counts and the shares.
+	counts
+		The number of missing values of each column.
+	row_count
+		The number of rows of the Table.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.missing_cells import read_missing_counts
+	>>> prices = ndp.Array.from_list([12.0, None])
+	>>> flats = ndp.Table.from_arrays({"price": prices})
+	>>> read_missing_counts(flats, ndp.Measure.RATIO).counts
+	array([1.])
+	"""
+
+	counts: NDArray[numpy.float64]
+	row_count: int
+
+
+def read_missing_counts(table: Table, measure: Measure) -> MissingCounts:
+	"""
+	Return the number or the share of missing values of each column of a Table, as one series of bars.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	table
+		The Table counted.
+	measure
+		``Measure.COUNT`` for the number of missing values, ``Measure.RATIO`` for their share.
+
+	Returns
+	-------
+	MissingCounts
+		The column names as text positions, the chosen measure as a single series, ``"Missing count"`` or
+		``"Missing ratio"`` as label of the axis of the values, and the counts for the labels of the bars.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.missing_cells import read_missing_counts
+	>>> prices = ndp.Array.from_list([12.0, None])
+	>>> rooms = ndp.Array.from_list([2, 3])
+	>>> flats = ndp.Table.from_arrays({"price": prices, "rooms": rooms})
+	>>> read_missing_counts(flats, ndp.Measure.RATIO).series[0].values
+	array([0.5, 0. ])
+	"""
+	frame = read_stored_frame(table)
+	missing_count = MissingCount(measure=measure)
+	counts_frame = count_frame_missing(frame, missing_count, Axis.EACH_COLUMN)
+	count_name = MEASURE_COLUMN_NAMES[measure]
+	column_names = counts_frame[COLUMN_NAMES_COLUMN].to_numpy(dtype=TEXT_DTYPE)
+	shown_values = counts_frame[count_name].to_numpy(dtype=FLOAT_DTYPE, na_value=numpy.nan)
+	missing_grid = find_frame_missing(frame)
+	counts = missing_grid.sum(axis=COLUMN_SUM_AXIS, dtype=FLOAT_DTYPE)
+	row_count = len(frame)
+	column_count = len(column_names)
+	rows = numpy.arange(column_count)
+	positions = Positions(PositionKind.TEXTS, column_names, COLUMN_AXIS_NAME)
+	count_series = Series(count_name, shown_values)
+	measure_label = MEASURE_LABELS[measure]
+	count_values = MissingCounts(positions, [count_series], rows, measure_label, Type.FLOAT64, counts, row_count)
+
+	return count_values
+
+
+def read_missing_cells(table: Table) -> ChartValues:
+	"""
+	Return where the values of a Table are missing, 1 for a missing value and 0 for a present one.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	table
+		The Table read.
+
+	Returns
+	-------
+	ChartValues
+		The row numbers as positions, and one series per column.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.missing_cells import read_missing_cells
+	>>> prices = ndp.Array.from_list([12.0, None])
+	>>> flats = ndp.Table.from_arrays({"price": prices})
+	>>> read_missing_cells(flats).series[0].values
+	array([0., 1.])
+	"""
+	frame = read_stored_frame(table)
+	missing_grid = find_frame_missing(frame)
+	cells = missing_grid.astype(FLOAT_DTYPE)
+	column_names = frame.columns.tolist()
+	row_count = len(frame)
+	rows = numpy.arange(row_count)
+	row_numbers = rows.astype(FLOAT_DTYPE)
+	positions = Positions(PositionKind.NUMBERS, row_numbers, None)
+	series = list[Series]()
+
+	for i, column_name in enumerate(column_names):
+		column_cells = cells[:, i]
+		column_series = Series(column_name, column_cells)
+		series.append(column_series)
+
+	cell_values = ChartValues(positions, series, rows, None, Type.FLOAT64)
+
+	return cell_values

numdaplot/plots/data/pie_values.py

@@ -0,0 +1,215 @@
+"""
+Values a PieChart shares out, read from a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+import warnings
+from typing import Any
+
+import numpy
+import pandas
+from numpy.typing import NDArray
+
+from numdaplot.errors.empty_total_error import EmptyTotalError
+from numdaplot.errors.missing_value_error import MissingValueError
+from numdaplot.errors.out_of_domain_error import OutOfDomainError
+from numdaplot.errors.readability_warning import ReadabilityWarning
+from numdaplot.plots.charts.pie_chart import PieChart
+from numdaplot.plots.data.chart_values import ChartValues, Positions, Series
+from numdaplot.plots.data.column_reading import read_numbers, read_texts
+from numdaplot.plots.data.position_kind import PositionKind
+from numdaplot.plots.data.unique_labels import require_unique_labels
+from numdaplot.tables.columns.column_names import require_known_columns
+from numdaplot.tables.frames.column_values import find_column_type
+from numdaplot.tables.table import Table
+from numdaplot.tables.table_data import read_stored_frame
+
+CHART_NAME = "PieChart"
+MAXIMUM_READABLE_SLICES = 5
+READABILITY_START = "A PieChart with {slice_count} slices is hard to read."
+READABILITY_ADVICE = "Try ndp.Plot.bar with a BarChart, it may compare them better."
+READABILITY_MESSAGE = f"{READABILITY_START} {READABILITY_ADVICE}"
+# The warning points at the line calling Plot.pie, above warn_slice_count, read_pie_values, Plot.pie and its check.
+READABILITY_STACK_LEVEL = 5
+
+
+def read_pie_values(table: Table, chart: PieChart) -> ChartValues:
+	"""
+	Return the labels and the values of the slices of a PieChart, after checking that they can be shared out.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	table
+		The Table drawn.
+	chart
+		The ``labels`` and ``values`` columns.
+
+	Returns
+	-------
+	ChartValues
+		The labels as text positions, and the values as a single series.
+
+	Raises
+	------
+	ColumnNotFoundError
+		When a column does not exist.
+	IncompatibleTypesError
+		When ``labels`` does not hold texts, or ``values`` does not hold numbers.
+	MissingValueError
+		When a label or a value is missing.
+	OutOfDomainError
+		When a value is negative.
+	EmptyTotalError
+		When the values add up to 0.
+	DuplicateLabelError
+		When two slices have the same label.
+
+	Warns
+	-----
+	ReadabilityWarning
+		When there are more than 5 slices.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.pie_values import read_pie_values
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon"])
+	>>> sales = ndp.Array.from_list([120.0, 80.0])
+	>>> shares = ndp.Table.from_arrays({"city": cities, "sales": sales})
+	>>> read_pie_values(shares, ndp.PieChart(labels="city", values="sales")).series[0].values
+	array([120.,  80.])
+	"""
+	labels_name = chart.labels
+	values_name = chart.values
+	frame = read_stored_frame(table)
+	known_names = frame.columns.tolist()
+	require_known_columns([labels_name, values_name], known_names)
+	labels = read_texts(frame[labels_name], CHART_NAME)
+	numbers = read_numbers(frame[values_name], CHART_NAME)
+	require_present_values(labels, labels_name)
+	require_present_values(numbers, values_name)
+	require_unique_labels(labels)
+	require_shares(numbers, values_name)
+	slice_count = len(labels)
+	warn_slice_count(slice_count)
+	rows = numpy.arange(slice_count)
+	positions = Positions(PositionKind.TEXTS, labels, labels_name)
+	values_series = Series(values_name, numbers)
+	values_column = frame[values_name]
+	values_type = find_column_type(values_column)
+	pie_values = ChartValues(positions, [values_series], rows, values_name, values_type)
+
+	return pie_values
+
+
+def require_present_values(values: NDArray[Any], column_name: str) -> None:
+	"""
+	Check that a column drawn by a PieChart has no missing value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The labels, None where missing, or the numbers, NaN where missing.
+	column_name
+		The column read, shown in the error message.
+
+	Raises
+	------
+	MissingValueError
+		When a value is missing.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.pie_values import require_present_values
+	>>> try:
+	... 	require_present_values(numpy.array([120.0, numpy.nan]), "sales")
+	... except ndp.MissingValueError as error:
+	... 	print(error)
+	PieChart cannot draw a missing value, found one in 'sales'.
+	"""
+	missing = pandas.isna(values)
+	has_missing = bool(missing.any())
+	if has_missing:
+		raise MissingValueError(CHART_NAME, column_name)
+
+
+def require_shares(numbers: NDArray[numpy.float64], column_name: str) -> None:
+	"""
+	Check that the values of a PieChart can be shared out: none is negative and their total is above 0.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	numbers
+		The value of each slice, none missing.
+	column_name
+		The column of the values, shown in the error message.
+
+	Raises
+	------
+	OutOfDomainError
+		At the first negative value.
+	EmptyTotalError
+		When the values add up to 0.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.pie_values import require_shares
+	>>> try:
+	... 	require_shares(numpy.array([120.0, -3.0]), "sales")
+	... except ndp.OutOfDomainError as error:
+	... 	print(error)
+	PieChart is not defined for -3.0.
+	"""
+	negative_numbers = numbers[numbers < 0]
+	negative_count = len(negative_numbers)
+	if negative_count > 0:
+		first_negative = float(negative_numbers[0])
+		raise OutOfDomainError(CHART_NAME, first_negative)
+
+	total = numbers.sum()
+	if total == 0:
+		raise EmptyTotalError(CHART_NAME, column_name)
+
+
+def warn_slice_count(slice_count: int) -> None:
+	"""
+	Emit a ReadabilityWarning when a PieChart has more than 5 slices.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	slice_count
+		The number of slices.
+
+	Warns
+	-----
+	ReadabilityWarning
+		When there are more than 5 slices.
+
+	Examples
+	--------
+	>>> import warnings
+	>>> from numdaplot.plots.data.pie_values import warn_slice_count
+	>>> with warnings.catch_warnings(record=True) as caught_warnings:
+	... 	warnings.simplefilter("always")
+	... 	warn_slice_count(6)
+	>>> print(caught_warnings[0].message)
+	A PieChart with 6 slices is hard to read. Try ndp.Plot.bar with a BarChart, it may compare them better.
+	"""
+	if slice_count <= MAXIMUM_READABLE_SLICES:
+		return
+
+	message = READABILITY_MESSAGE.format(slice_count=slice_count)
+	warnings.warn(message, ReadabilityWarning, stacklevel=READABILITY_STACK_LEVEL)

numdaplot/plots/data/point_values.py

@@ -0,0 +1,249 @@
+"""
+Values coloring and sizing the points of a ScatterChart.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass, replace
+from typing import Any
+
+import numpy
+import pandas
+from numpy.typing import NDArray
+
+from numdaplot.data_types.value_family import ValueFamily
+from numdaplot.errors.refused_setting_error import RefusedSettingError
+from numdaplot.plots.charts.color_scale import ColorScale
+from numdaplot.plots.data.chart_values import ChartValues, Series
+from numdaplot.plots.data.column_reading import read_numbers, read_texts, require_column_family
+from numdaplot.tables.columns.column_names import require_known_columns
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.table import Table
+from numdaplot.tables.table_data import read_stored_frame
+
+CHART_NAME = "ScatterChart"
+NUMBER_COLORS_DTYPE = numpy.dtype(numpy.float64)
+SCALE_ON_TEXTS = "scale without a color_by column of numbers"
+COLOR_FAMILIES = frozenset({ValueFamily.NUMBER, ValueFamily.TEXT, ValueFamily.BOOL, ValueFamily.TIME})
+
+
+@dataclass(frozen=True, eq=False)
+class PointValues:
+	"""
+	The values coloring and sizing each point of a ScatterChart, one per drawn row.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	color_name
+		The ``color_by`` column, or None.
+	colors
+		Its values: float64 numbers or texts, or None.
+	size_name
+		The ``size_by`` column, or None.
+	sizes
+		Its float64 numbers, or None.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.data.point_values import PointValues
+	>>> PointValues("city", numpy.array(["Paris"], dtype=object), None, None).color_name
+	'city'
+	"""
+
+	color_name: str | None
+	colors: NDArray[Any] | None
+	size_name: str | None
+	sizes: NDArray[numpy.float64] | None
+
+
+def read_point_values(
+	table: Table, color_name: str | None, size_name: str | None, rows: NDArray[numpy.intp]
+) -> PointValues:
+	"""
+	Return the values of the ``color_by`` and ``size_by`` columns of a ScatterChart for the drawn rows.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	table
+		The Table drawn.
+	color_name
+		The ``color_by`` column, or None.
+	size_name
+		The ``size_by`` column, or None.
+	rows
+		The row numbers drawn.
+
+	Returns
+	-------
+	PointValues
+		The values of each column given, in the order of the drawn rows.
+
+	Raises
+	------
+	ColumnNotFoundError
+		When a column does not exist.
+	IncompatibleTypesError
+		When ``color_by`` holds neither numbers nor texts, or ``size_by`` does not hold numbers.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.point_values import read_point_values
+	>>> surfaces = ndp.Array.from_list([30.0, 45.0])
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon"])
+	>>> flats = ndp.Table.from_arrays({"surface": surfaces, "city": cities})
+	>>> read_point_values(flats, "city", "surface", numpy.arange(2)).sizes
+	array([30., 45.])
+	"""
+	frame = read_stored_frame(table)
+	column_names = frame.columns.tolist()
+	colors = None
+	sizes = None
+	if color_name is not None:
+		require_known_columns([color_name], column_names)
+		all_colors = read_colors(frame[color_name])
+		colors = all_colors[rows]
+
+	if size_name is not None:
+		require_known_columns([size_name], column_names)
+		all_sizes = read_numbers(frame[size_name], CHART_NAME)
+		sizes = all_sizes[rows]
+
+	point_values = PointValues(color_name, colors, size_name, sizes)
+
+	return point_values
+
+
+def require_scale_on_numbers(scale: ColorScale | None, colors: NDArray[Any] | None) -> None:
+	"""
+	Check that a color scale colors numbers.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	scale
+		The ``scale`` of a ScatterChart, or None.
+	colors
+		The values of its ``color_by`` column, float64 numbers or texts.
+
+	Raises
+	------
+	RefusedSettingError
+		When a scale is given for texts or booleans, which take one color per value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.point_values import require_scale_on_numbers
+	>>> require_scale_on_numbers(ndp.ColorScale.BLUES, numpy.array([1.5]))
+	>>> try:
+	... 	require_scale_on_numbers(ndp.ColorScale.BLUES, numpy.array(["Paris"], dtype=object))
+	... except ndp.RefusedSettingError as error:
+	... 	print(error)
+	ScatterChart does not accept scale without a color_by column of numbers.
+	"""
+	if scale is None or colors is None:
+		return
+
+	if colors.dtype != NUMBER_COLORS_DTYPE:
+		raise RefusedSettingError(SCALE_ON_TEXTS, CHART_NAME)
+
+
+def read_colors(column: Column) -> NDArray[Any]:
+	"""
+	Return the values of a ``color_by`` column: float64 numbers or texts.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column.
+
+	Returns
+	-------
+	NDArray
+		Numbers with NaN, or texts with None, where a value is missing.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the column holds neither numbers, texts, booleans nor times of day.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.plots.data.point_values import read_colors
+	>>> read_colors(pandas.Series([2.5, None], dtype="float64"))
+	array([2.5, nan])
+	"""
+	family = require_column_family(column, COLOR_FAMILIES, CHART_NAME)
+	if family == ValueFamily.NUMBER:
+		numbers = read_numbers(column, CHART_NAME)
+		return numbers
+
+	texts = read_texts(column, CHART_NAME)
+
+	return texts
+
+
+def hide_missing_points(chart_values: ChartValues, point_values: PointValues) -> ChartValues:
+	"""
+	Return the values of a ScatterChart without the points whose color or size value is missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	chart_values
+		The positions and the series.
+	point_values
+		The values coloring and sizing the points.
+
+	Returns
+	-------
+	ChartValues
+		The same values, NaN in the series where a color or size value is missing.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.data.chart_values import ChartValues, Positions, Series
+	>>> from numdaplot.plots.data.point_values import PointValues, hide_missing_points
+	>>> from numdaplot.plots.data.position_kind import PositionKind
+	>>> positions = Positions(PositionKind.NUMBERS, numpy.array([0.0, 1.0]), None)
+	>>> price_series = Series("price", numpy.array([1.0, 2.0]))
+	>>> chart_values = ChartValues(positions, [price_series], numpy.arange(2), "price", ndp.Type.FLOAT64)
+	>>> point_values = PointValues(None, None, "surface", numpy.array([30.0, numpy.nan]))
+	>>> hide_missing_points(chart_values, point_values).series[0].values
+	array([ 1., nan])
+	"""
+	row_count = len(chart_values.rows)
+	missing = numpy.zeros(row_count, dtype=numpy.bool_)
+
+	for point_column in (point_values.colors, point_values.sizes):
+		if point_column is None:
+			continue
+
+		missing_values = pandas.isna(point_column)
+		missing = missing | missing_values
+
+	shown_series = list[Series]()
+
+	for series in chart_values.series:
+		shown_numbers = numpy.where(missing, numpy.nan, series.values)
+		series_copy = Series(series.name, shown_numbers)
+		shown_series.append(series_copy)
+
+	shown_values = replace(chart_values, series=shown_series)
+
+	return shown_values