numdaplot 0.1.0__py3-none-any.whl

numdaplot/plots/drawing/position_axis.py

@@ -0,0 +1,278 @@
+"""
+Placement of the ``x`` values of a chart along its axis.
+
+.. versionadded:: 0.1.0
+"""
+
+# The matplotlib stubs leave the keyword arguments of most drawing methods untyped.
+# pyright: reportUnknownMemberType=false
+
+from typing import Any, cast
+
+import numpy
+from matplotlib.axes import Axes
+from matplotlib.axis import Axis
+from matplotlib.dates import AutoDateLocator
+from matplotlib.ticker import FixedFormatter, FixedLocator
+from numpy.typing import NDArray
+
+from numdaplot.arrays.conversion.time_text import format_datetimes
+from numdaplot.plots.data.chart_values import Positions
+from numdaplot.plots.data.position_kind import PositionKind
+from numdaplot.plots.drawing.moment_period_formatter import MomentPeriodFormatter
+from numdaplot.plots.drawing.time_axis import format_hour, place_hour_ticks
+from numdaplot.plots.drawing.whole_numbers import place_whole_ticks
+
+DAY_UNIT = "D"
+DAY_DTYPE = numpy.dtype("datetime64[D]")
+TRIMMED_ZEROS = "-"
+
+
+def place_positions(axes: Axes, positions: Positions, on_vertical_axis: bool) -> NDArray[Any]:
+	"""
+	Return the coordinates of the ``x`` values of a line or scatter chart, and set the ticks of their axis.
+
+	Numbers keep their value, with ticks on whole numbers only when every number is whole, moments are
+	placed on a time axis whose corner label gives their period, and texts are placed at 0, 1, 2 and so on,
+	each labeled with its text.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axes
+		The matplotlib axes drawn on.
+	positions
+		The ``x`` values.
+	on_vertical_axis
+		True to place them on the vertical axis.
+
+	Returns
+	-------
+	NDArray
+		The coordinates given to matplotlib.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.data.chart_values import Positions
+	>>> from numdaplot.plots.data.position_kind import PositionKind
+	>>> from numdaplot.plots.drawing.position_axis import place_positions
+	>>> axes = Figure().add_subplot()
+	>>> place_positions(axes, Positions(PositionKind.TEXTS, numpy.array(["Paris", "Lyon"]), "city"), False)
+	array([0., 1.])
+	>>> [label.get_text() for label in axes.get_xticklabels()]
+	['Paris', 'Lyon']
+	"""
+	if positions.kind == PositionKind.TEXTS:
+		categories = place_categories(axes, positions, on_vertical_axis)
+		return categories
+
+	position_axis = find_axis(axes, on_vertical_axis)
+	if positions.kind == PositionKind.NUMBERS:
+		place_whole_ticks(position_axis, positions.values)
+		return positions.values
+
+	if positions.kind == PositionKind.TIMES:
+		place_hour_ticks(position_axis, positions.values)
+		return positions.values
+
+	if positions.kind == PositionKind.MOMENTS:
+		date_locator = AutoDateLocator()
+		date_formatter = MomentPeriodFormatter(date_locator, axes, on_vertical_axis)
+		position_axis.set_major_locator(date_locator)
+		position_axis.set_major_formatter(date_formatter)
+
+	return positions.values
+
+
+def place_categories(axes: Axes, positions: Positions, on_vertical_axis: bool) -> NDArray[numpy.float64]:
+	"""
+	Return the coordinates 0, 1, 2 and so on of the ``x`` values, each tick labeled with its value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axes
+		The matplotlib axes drawn on.
+	positions
+		The ``x`` values.
+	on_vertical_axis
+		True to place them on the vertical axis.
+
+	Returns
+	-------
+	NDArray[numpy.float64]
+		One coordinate per value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.data.chart_values import Positions
+	>>> from numdaplot.plots.data.position_kind import PositionKind
+	>>> from numdaplot.plots.drawing.position_axis import place_categories
+	>>> axes = Figure().add_subplot()
+	>>> place_categories(axes, Positions(PositionKind.NUMBERS, numpy.array([2025.0, 2026.0]), "year"), False)
+	array([0., 1.])
+	>>> [label.get_text() for label in axes.get_xticklabels()]
+	['2025', '2026']
+	"""
+	position_count = len(positions.values)
+	coordinates = numpy.arange(position_count, dtype=numpy.float64)
+	labels = write_position_labels(positions)
+	position_axis = find_axis(axes, on_vertical_axis)
+	set_fixed_labels(position_axis, coordinates, labels)
+
+	return coordinates
+
+
+def set_fixed_labels(axis: Axis, coordinates: NDArray[numpy.float64], labels: list[str]) -> None:
+	"""
+	Place a label at each coordinate of an axis, without creating the matplotlib ticks yet.
+
+	``Axis.set_ticks`` creates one tick per label, about 3 milliseconds each, when only the labels that fit stay.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axis
+		The axis.
+	coordinates
+		The coordinate of each label.
+	labels
+		The text of each label.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.drawing.position_axis import set_fixed_labels
+	>>> axes = Figure().add_subplot()
+	>>> set_fixed_labels(axes.xaxis, numpy.array([0.0, 1.0]), ["Paris", "Lyon"])
+	>>> [label.get_text() for label in axes.get_xticklabels()]
+	['Paris', 'Lyon']
+	"""
+	label_places = cast(list[float], coordinates.tolist())
+	label_locator = FixedLocator(label_places)
+	label_formatter = FixedFormatter(labels)
+	axis.set_major_locator(label_locator)
+	axis.set_major_formatter(label_formatter)
+
+
+def find_axis(axes: Axes, on_vertical_axis: bool) -> Axis:
+	"""
+	Return the horizontal or the vertical axis of matplotlib axes.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axes
+		The matplotlib axes.
+	on_vertical_axis
+		True for the vertical axis.
+
+	Returns
+	-------
+	matplotlib.axis.Axis
+		The ``yaxis`` or the ``xaxis``.
+
+	Examples
+	--------
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.drawing.position_axis import find_axis
+	>>> find_axis(Figure().add_subplot(), True).axis_name
+	'y'
+	"""
+	if on_vertical_axis:
+		return axes.yaxis
+
+	return axes.xaxis
+
+
+def write_position_labels(positions: Positions) -> list[str]:
+	"""
+	Return the text labeling each ``x`` value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	positions
+		The ``x`` values.
+
+	Returns
+	-------
+	list[str]
+		Numbers without trailing zeros, dates without time when every value is at midnight, texts as they are.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.data.chart_values import Positions
+	>>> from numdaplot.plots.data.position_kind import PositionKind
+	>>> from numdaplot.plots.drawing.position_axis import write_position_labels
+	>>> days = numpy.array(["2026-01-01", "2026-01-02"], dtype="datetime64[ns]")
+	>>> write_position_labels(Positions(PositionKind.MOMENTS, days, "day"))
+	['2026-01-01', '2026-01-02']
+	"""
+	if positions.kind == PositionKind.NUMBERS:
+		number_labels = [numpy.format_float_positional(value, trim=TRIMMED_ZEROS) for value in positions.values]
+		return number_labels
+
+	if positions.kind == PositionKind.MOMENTS:
+		moment_labels = write_moment_labels(positions.values)
+		return moment_labels
+
+	if positions.kind == PositionKind.TIMES:
+		hour_labels = [format_hour(value) for value in positions.values]
+		return hour_labels
+
+	text_labels = [str(value) for value in positions.values]
+
+	return text_labels
+
+
+def write_moment_labels(moments: NDArray[numpy.datetime64]) -> list[str]:
+	"""
+	Return the text of each date or datetime, without time when every value is at midnight.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	moments
+		datetime64 values.
+
+	Returns
+	-------
+	list[str]
+		One text per value, ``NaT`` for a missing value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.drawing.position_axis import write_moment_labels
+	>>> write_moment_labels(numpy.array(["2026-01-01T10:30"], dtype="datetime64[ns]"))
+	['2026-01-01 10:30:00']
+	"""
+	days = moments.astype(DAY_DTYPE)
+	day_starts = days.astype(moments.dtype)
+	at_midnight = day_starts == moments
+	missing = numpy.isnat(moments)
+	is_whole_day = at_midnight | missing
+	all_whole_days = bool(numpy.all(is_whole_day))
+	if all_whole_days:
+		day_texts = numpy.datetime_as_string(days, unit=DAY_UNIT)
+		# Some versions of the numpy stubs type the list of a text array as nested lists.
+		day_labels = cast(list[str], day_texts.tolist())
+		return day_labels
+
+	moment_texts = format_datetimes(moments)
+	moment_labels = cast(list[str], moment_texts.tolist())
+
+	return moment_labels

numdaplot/plots/drawing/scatter_drawing.py

@@ -0,0 +1,364 @@
+"""
+Drawing of a ScatterChart.
+
+.. versionadded:: 0.1.0
+"""
+
+# The matplotlib stubs leave the keyword arguments of most drawing methods untyped.
+# pyright: reportUnknownMemberType=false
+
+from dataclasses import dataclass
+from typing import Any, cast
+
+import numpy
+import pandas
+from matplotlib.axes import Axes
+from matplotlib.collections import PathCollection
+from numpy.typing import NDArray
+
+from numdaplot.plots.chart_layer import ChartLayer
+from numdaplot.plots.charts.color_scale import ColorScale
+from numdaplot.plots.charts.scatter_chart import ScatterChart
+from numdaplot.plots.data.chart_values import ChartValues, Series
+from numdaplot.plots.data.point_values import PointValues
+from numdaplot.plots.drawing.color_bar import add_color_bar
+from numdaplot.plots.drawing.color_scale_values import find_point_colors, find_scale_limits
+from numdaplot.plots.drawing.default_labels import find_position_label
+from numdaplot.plots.drawing.drawn_chart import DrawnChart
+from numdaplot.plots.drawing.grid_axes import GridAxes
+from numdaplot.plots.drawing.marker_codes import MARKER_CODES
+from numdaplot.plots.drawing.position_axis import place_positions
+from numdaplot.plots.drawing.series_colors import choose_series_colors
+from numdaplot.plots.style.color import Color
+from numdaplot.plots.style.custom_color import CustomColor
+
+DEFAULT_POINT_SIZE = 6.0
+SMALLEST_POINT_AREA = 16.0
+LARGEST_POINT_AREA = 256.0
+DEFAULT_COLOR_SCALE = ColorScale.VIRIDIS
+NO_POINT_VALUES = PointValues(None, None, None, None)
+
+
+@dataclass(frozen=True, eq=False)
+class PointLook:
+	"""
+	The look shared by the points of a ScatterChart.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	coordinates
+		The coordinates of the ``x`` values.
+	areas
+		The area of each point in square points.
+	marker_code
+		The matplotlib code of the marker shape.
+	opacity
+		How opaque the points are, from 0 to 1.
+	scale
+		The colors of the points colored by numbers.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> import numpy
+	>>> from numdaplot.plots.drawing.scatter_drawing import PointLook
+	>>> PointLook(numpy.array([0.0]), numpy.array([36.0]), "o", 1.0, ndp.ColorScale.VIRIDIS).marker_code
+	'o'
+	"""
+
+	coordinates: NDArray[Any]
+	areas: NDArray[numpy.float64]
+	marker_code: str
+	opacity: float
+	scale: ColorScale
+
+
+def draw_scatter_chart(axes: Axes, layer: ChartLayer) -> DrawnChart:
+	"""
+	Draw each row of a ScatterChart as a point, colored and sized by the ``color_by`` and ``size_by`` columns.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axes
+		The matplotlib axes drawn on.
+	layer
+		A ScatterChart, its values and the values of its points.
+
+	Returns
+	-------
+	DrawnChart
+		The default labels, grid lines across both axes, and the ``color_by`` column as legend title when it
+		holds texts.
+
+	Raises
+	------
+	InvalidColorCountError
+		When ``color`` is given for an Array of several columns.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.chart_layer import ChartLayer
+	>>> from numdaplot.plots.data.array_values import read_array_values
+	>>> from numdaplot.plots.drawing.scatter_drawing import draw_scatter_chart
+	>>> prices = ndp.Array.from_list([12.0, 15.5])
+	>>> axes = Figure().add_subplot()
+	>>> layer = ChartLayer(ndp.ScatterChart(), read_array_values(prices, "ScatterChart"))
+	>>> drawn_chart = draw_scatter_chart(axes, layer)
+	>>> axes.collections[0].get_offsets().tolist()
+	[[0.0, 12.0], [1.0, 15.5]]
+	"""
+	chart = cast(ScatterChart, layer.chart)
+	values = cast(ChartValues, layer.values)
+	points = NO_POINT_VALUES
+	if layer.points is not None:
+		points = layer.points
+
+	coordinates = place_positions(axes, values.positions, False)
+	row_count = len(coordinates)
+	areas = choose_areas(points.sizes, row_count, chart.point_size)
+	marker_code = MARKER_CODES[chart.marker]
+	scale = DEFAULT_COLOR_SCALE if chart.scale is None else chart.scale
+	point_look = PointLook(coordinates, areas, marker_code, chart.opacity, scale)
+	x_label = find_position_label(values.positions)
+	no_legend_chart = DrawnChart(x_label, values.value_name, False, GridAxes.BOTH, None)
+	if points.colors is None:
+		draw_colored_series(axes, chart.color, values.series, point_look)
+		return no_legend_chart
+
+	color_name = cast(str, points.color_name)
+	first_series = values.series[0]
+	if points.colors.dtype == numpy.float64:
+		scaled_points = draw_color_scale(axes, first_series, points.colors, point_look)
+		add_color_bar(axes, scaled_points, color_name, points.colors)
+		return no_legend_chart
+
+	draw_color_groups(axes, first_series, points.colors, point_look)
+	group_chart = DrawnChart(x_label, values.value_name, False, GridAxes.BOTH, color_name)
+
+	return group_chart
+
+
+def choose_areas(
+	sizes: NDArray[numpy.float64] | None, row_count: int, point_size: float | None
+) -> NDArray[numpy.float64]:
+	"""
+	Return the area of each point, scaled from the smallest to the largest ``size_by`` value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	sizes
+		The ``size_by`` values, NaN where a value is missing, or None for points of the same size.
+	row_count
+		The number of points.
+	point_size
+		The diameter of every point without ``size_by``, or None for the default diameter.
+
+	Returns
+	-------
+	NDArray[numpy.float64]
+		Areas from 16 to 256 square points, the square of the diameter for every point without ``size_by``, 36 by
+		default, and the middle area when every value is the same. A point with a missing size is not drawn, its area
+		is 0.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.drawing.scatter_drawing import choose_areas
+	>>> choose_areas(numpy.array([10.0, 20.0, 30.0]), 3, None)
+	array([ 16., 136., 256.])
+	"""
+	if sizes is None:
+		diameter = DEFAULT_POINT_SIZE if point_size is None else point_size
+		same_areas = numpy.full(row_count, diameter**2)
+		return same_areas
+
+	area_range = LARGEST_POINT_AREA - SMALLEST_POINT_AREA
+	middle_area = SMALLEST_POINT_AREA + area_range / 2
+	present = ~numpy.isnan(sizes)
+	present_sizes = sizes[present]
+	areas = numpy.full(row_count, middle_area)
+	present_count = len(present_sizes)
+	if present_count == 0:
+		return areas
+
+	smallest_size = present_sizes.min()
+	largest_size = present_sizes.max()
+	size_range = largest_size - smallest_size
+	if size_range > 0:
+		size_shares = (sizes - smallest_size) / size_range
+		areas = SMALLEST_POINT_AREA + size_shares * area_range
+
+	drawn_areas = numpy.where(present, areas, 0.0)
+
+	return drawn_areas
+
+
+def draw_colored_series(
+	axes: Axes, color: Color | CustomColor | None, series_list: list[Series], point_look: PointLook
+) -> None:
+	"""
+	Draw the points of each series in one color.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axes
+		The matplotlib axes drawn on.
+	color
+		The color of the points of a single series, or None for the colors of the default cycle.
+	series_list
+		The series drawn.
+	point_look
+		The coordinates, the areas and the marker of the points.
+
+	Raises
+	------
+	InvalidColorCountError
+		When a color is given for several series.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.data.chart_values import Series
+	>>> from numdaplot.plots.drawing.scatter_drawing import PointLook, draw_colored_series
+	>>> axes = Figure().add_subplot()
+	>>> point_look = PointLook(numpy.array([0.0]), numpy.array([36.0]), "o", 1.0, ndp.ColorScale.VIRIDIS)
+	>>> draw_colored_series(axes, ndp.Color.RED, [Series("price", numpy.array([12.0]))], point_look)
+	>>> axes.collections[0].get_facecolor().round(2).tolist()
+	[[0.84, 0.15, 0.16, 1.0]]
+	"""
+	chosen_colors = None
+	if color is not None:
+		chosen_colors = [color]
+
+	series_count = len(series_list)
+	color_codes = choose_series_colors(chosen_colors, series_count)
+
+	for series, color_code in zip(series_list, color_codes, strict=True):
+		axes.scatter(
+			point_look.coordinates,
+			series.values,
+			s=point_look.areas,
+			color=color_code,
+			marker=point_look.marker_code,
+			alpha=point_look.opacity,
+			label=series.name,
+		)
+
+
+def draw_color_scale(
+	axes: Axes, series: Series, color_numbers: NDArray[numpy.float64], point_look: PointLook
+) -> PathCollection:
+	"""
+	Draw points colored along a color scale, from the smallest to the largest ``color_by`` number.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axes
+		The matplotlib axes drawn on.
+	series
+		The series drawn.
+	color_numbers
+		The ``color_by`` numbers.
+	point_look
+		The coordinates, the areas and the marker of the points.
+
+	Returns
+	-------
+	matplotlib.collections.PathCollection
+		The drawn points, which the color bar describes.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> import numpy
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.data.chart_values import Series
+	>>> from numdaplot.plots.drawing.scatter_drawing import PointLook, draw_color_scale
+	>>> axes = Figure().add_subplot()
+	>>> point_look = PointLook(numpy.array([0.0, 1.0]), numpy.array([36.0, 36.0]), "o", 1.0, ndp.ColorScale.VIRIDIS)
+	>>> series = Series("price", numpy.array([1.0, 2.0]))
+	>>> scaled_points = draw_color_scale(axes, series, numpy.array([5.0, 9.0]), point_look)
+	>>> [float(limit) for limit in scaled_points.get_clim()]
+	[5.0, 9.0]
+	"""
+	point_colors = find_point_colors(point_look.scale)
+	lowest_color, highest_color = find_scale_limits(color_numbers, point_look.scale)
+	scaled_points = axes.scatter(
+		point_look.coordinates,
+		series.values,
+		s=point_look.areas,
+		c=color_numbers,
+		cmap=point_colors,
+		vmin=lowest_color,
+		vmax=highest_color,
+		marker=point_look.marker_code,
+		alpha=point_look.opacity,
+	)
+
+	return scaled_points
+
+
+def draw_color_groups(axes: Axes, series: Series, color_texts: NDArray[Any], point_look: PointLook) -> None:
+	"""
+	Draw the points of each ``color_by`` text in its own color, named in the legend.
+
+	The texts take the colors of the default cycle in the order they first appear.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axes
+		The matplotlib axes drawn on.
+	series
+		The series drawn.
+	color_texts
+		The ``color_by`` texts, None where a text is missing.
+	point_look
+		The coordinates, the areas and the marker of the points.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> import numpy
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.data.chart_values import Series
+	>>> from numdaplot.plots.drawing.scatter_drawing import PointLook, draw_color_groups
+	>>> axes = Figure().add_subplot()
+	>>> point_look = PointLook(numpy.array([0.0, 1.0]), numpy.array([36.0, 36.0]), "o", 1.0, ndp.ColorScale.VIRIDIS)
+	>>> texts = numpy.array(["Pau", "Lyon"], dtype=object)
+	>>> draw_color_groups(axes, Series("price", numpy.array([1.0, 2.0])), texts, point_look)
+	>>> [points.get_label() for points in axes.collections]
+	['Pau', 'Lyon']
+	"""
+	present = pandas.notna(color_texts)
+	present_texts = color_texts[present]
+	groups = pandas.unique(present_texts)
+	group_count = len(groups)
+	color_codes = choose_series_colors(None, group_count)
+
+	for group, color_code in zip(groups, color_codes, strict=True):
+		in_group = color_texts == group
+		axes.scatter(
+			point_look.coordinates[in_group],
+			series.values[in_group],
+			s=point_look.areas[in_group],
+			color=color_code,
+			marker=point_look.marker_code,
+			alpha=point_look.opacity,
+			label=group,
+		)