numdaplot 0.1.0__py3-none-any.whl

numdaplot/plots/drawing/tick_rotation.py

@@ -0,0 +1,354 @@
+"""
+Rotation of the labels of the ``x`` and ``y`` values of a Plot.
+
+.. versionadded:: 0.1.0
+"""
+
+# The matplotlib stubs leave the keyword arguments of most drawing methods untyped.
+# pyright: reportUnknownMemberType=false
+
+from typing import Literal
+
+from matplotlib.axes import Axes
+from matplotlib.axis import Axis
+from matplotlib.dates import ConciseDateFormatter
+from matplotlib.ticker import ScalarFormatter
+
+from numdaplot.plots.drawing.drawn_chart import DrawnChart
+from numdaplot.plots.drawing.label_room import (
+	LABEL_GAP_RATIO,
+	find_current_length,
+	find_font_pixels,
+	find_tick_locations,
+	find_tick_room,
+	find_widest_label,
+	read_label_texts,
+)
+from numdaplot.plots.drawing.label_thinning import MINIMUM_TICKS, thin_labels
+from numdaplot.plots.drawing.position_axis import find_axis
+
+TEXT_ROTATION = 45.0
+NO_ROTATION = 0.0
+ANCHOR_ROTATION_MODE = "anchor"
+MINUS_SIGN = "\N{MINUS SIGN}"
+HYPHEN_MINUS = "-"
+
+
+def rotate_x_labels(axes: Axes, drawn_chart: DrawnChart, rotation: float | None) -> None:
+	"""
+	Rotate the labels of the ``x`` values, wherever the chart places them, keeping those that stay readable.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axes
+		The matplotlib axes of the Plot.
+	drawn_chart
+		Which axis holds the ``x`` values.
+	rotation
+		The angle in degrees. When None, 45 degrees for texts, moments and numbers without enough room, and no
+		rotation for other numbers and for labels on the vertical axis.
+
+	Warns
+	-----
+	ReadabilityWarning
+		When labels left out may be texts.
+
+	Examples
+	--------
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.drawing.drawn_chart import DrawnChart
+	>>> from numdaplot.plots.drawing.grid_axes import GridAxes
+	>>> from numdaplot.plots.drawing.tick_rotation import rotate_x_labels
+	>>> axes = Figure().add_subplot()
+	>>> axes.xaxis.set_ticks([0.0, 1.0], ["Paris", "Lyon"])  # doctest: +ELLIPSIS
+	[...]
+	>>> rotate_x_labels(axes, DrawnChart(None, None, False, GridAxes.NONE, None), None)
+	>>> axes.get_xticklabels()[0].get_rotation()
+	45.0
+	"""
+	if drawn_chart.x_on_vertical_axis:
+		vertical_rotation = NO_ROTATION if rotation is None else rotation
+		thin_labels(axes.yaxis, True, vertical_rotation)
+		apply_rotation(axes, True, vertical_rotation)
+		return
+
+	horizontal_rotation = choose_rotation(axes.xaxis, rotation)
+	thin_labels(axes.xaxis, False, horizontal_rotation)
+	apply_rotation(axes, False, horizontal_rotation)
+
+
+def rotate_y_labels(axes: Axes, drawn_chart: DrawnChart, rotation: float | None) -> None:
+	"""
+	Rotate the labels of the ``y`` values, wherever the chart places them, keeping those that stay readable.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axes
+		The matplotlib axes of the Plot.
+	drawn_chart
+		Which axis holds the ``x`` values: the ``y`` values are on the other one.
+	rotation
+		The angle in degrees. When None, the labels stay horizontal.
+
+	Warns
+	-----
+	ReadabilityWarning
+		When labels left out may be texts.
+
+	Examples
+	--------
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.drawing.drawn_chart import DrawnChart
+	>>> from numdaplot.plots.drawing.grid_axes import GridAxes
+	>>> from numdaplot.plots.drawing.tick_rotation import rotate_y_labels
+	>>> axes = Figure().add_subplot()
+	>>> rotate_y_labels(axes, DrawnChart(None, None, False, GridAxes.NONE, None), 30.0)
+	>>> axes.get_yticklabels()[0].get_rotation()
+	30.0
+	"""
+	y_on_vertical_axis = not drawn_chart.x_on_vertical_axis
+	y_axis = find_axis(axes, y_on_vertical_axis)
+	thinning_rotation = NO_ROTATION if rotation is None else rotation
+	thin_labels(y_axis, y_on_vertical_axis, thinning_rotation)
+	if rotation is None:
+		return
+
+	apply_rotation(axes, y_on_vertical_axis, rotation)
+
+
+def apply_rotation(axes: Axes, on_vertical_axis: bool, rotation: float) -> None:
+	"""
+	Rotate the labels of an axis around their end closest to the axis.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axes
+		The matplotlib axes of the Plot.
+	on_vertical_axis
+		True for the vertical axis, whose labels already end at their tick.
+	rotation
+		The angle in degrees.
+
+	Examples
+	--------
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.drawing.tick_rotation import apply_rotation
+	>>> axes = Figure().add_subplot()
+	>>> apply_rotation(axes, False, 45.0)
+	>>> axes.get_xticklabels()[0].get_horizontalalignment()
+	'right'
+	"""
+	axis = find_axis(axes, on_vertical_axis)
+	axis.set_tick_params(labelrotation=rotation)
+	alignment = choose_alignment(rotation)
+
+	for label in axis.get_ticklabels():
+		label.set_rotation_mode(ANCHOR_ROTATION_MODE)
+		if not on_vertical_axis:
+			label.set_horizontalalignment(alignment)
+
+
+def choose_rotation(axis: Axis, rotation: float | None) -> float:
+	"""
+	Return the angle of the labels of a horizontal axis.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axis
+		The horizontal axis, with its ticks.
+	rotation
+		The angle chosen in degrees, or None.
+
+	Returns
+	-------
+	float
+		The angle chosen, else 45 degrees for texts, moments and numbers without enough room, and no rotation for
+		other numbers.
+
+	Examples
+	--------
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.drawing.tick_rotation import choose_rotation
+	>>> axes = Figure().add_subplot()
+	>>> choose_rotation(axes.xaxis, None), choose_rotation(axes.xaxis, 30.0)
+	(0.0, 30.0)
+	"""
+	if rotation is not None:
+		return rotation
+
+	has_text = has_text_labels(axis)
+	if has_text:
+		return TEXT_ROTATION
+
+	labels_touch = do_labels_touch(axis)
+	if labels_touch:
+		return TEXT_ROTATION
+
+	return NO_ROTATION
+
+
+def do_labels_touch(axis: Axis) -> bool:
+	"""
+	Return whether horizontal labels fixed on each tick of a horizontal axis leave too little room between them.
+
+	The axes do not have their final width yet. Their current width is a little lower, which makes the answer prudent.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axis
+		The horizontal axis, with its ticks.
+
+	Returns
+	-------
+	bool
+		True when the widest label and a gap of half its font size exceed the room between the closest ticks. Labels
+		chosen by matplotlib according to the room, such as those of a line chart, never touch.
+
+	Examples
+	--------
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.drawing.tick_rotation import do_labels_touch
+	>>> axes = Figure().add_subplot()
+	>>> years = [float(year) for year in range(24)]
+	>>> axes.xaxis.set_ticks(years, [str(2000 + year) for year in range(24)])  # doctest: +ELLIPSIS
+	[...]
+	>>> do_labels_touch(axes.xaxis)
+	True
+	"""
+	formatter = axis.get_major_formatter()
+	if isinstance(formatter, ScalarFormatter):
+		return False
+
+	tick_locations = find_tick_locations(axis)
+	tick_count = len(tick_locations)
+	if tick_count < MINIMUM_TICKS:
+		return False
+
+	current_length = find_current_length(axis, False)
+	room = find_tick_room(axis, False, current_length)
+	widest_label = find_widest_label(axis)
+	font_pixels = find_font_pixels(axis)
+	needed_room = widest_label + font_pixels * LABEL_GAP_RATIO
+	labels_touch = bool(needed_room > room)
+
+	return labels_touch
+
+
+def has_text_labels(axis: Axis) -> bool:
+	"""
+	Return whether the labels of an axis are moments, or texts that are not all numbers.
+
+	Numbers can be written as texts, such as the years or the row numbers below bars: they stay numbers.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axis
+		An axis, with its ticks.
+
+	Returns
+	-------
+	bool
+		True when at least one label is not a number. An axis without label holds no text.
+
+	Examples
+	--------
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.drawing.tick_rotation import has_text_labels
+	>>> axes = Figure().add_subplot()
+	>>> axes.xaxis.set_ticks([0.0, 1.0], ["2025", "2026"])  # doctest: +ELLIPSIS
+	[...]
+	>>> has_text_labels(axes.xaxis)
+	False
+	"""
+	formatter = axis.get_major_formatter()
+	if isinstance(formatter, ScalarFormatter):
+		return False
+
+	if isinstance(formatter, ConciseDateFormatter):
+		return True
+
+	label_texts = read_label_texts(axis)
+
+	for label_text in label_texts:
+		is_number = is_number_text(label_text)
+		if not is_number:
+			return True
+
+	return False
+
+
+def is_number_text(text: str) -> bool:
+	"""
+	Return whether a label is a number, as matplotlib or numdaplot writes it.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	text
+		The text of a label.
+
+	Returns
+	-------
+	bool
+		True for a number, with the minus sign matplotlib writes, or for an empty label.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.drawing.tick_rotation import is_number_text
+	>>> is_number_text("2025"), is_number_text("-1.5"), is_number_text("Paris")
+	(True, True, False)
+	"""
+	if text == "":
+		return True
+
+	python_text = text.replace(MINUS_SIGN, HYPHEN_MINUS)
+	try:
+		float(python_text)
+	except ValueError:
+		return False
+
+	return True
+
+
+def choose_alignment(rotation: float) -> Literal["left", "center", "right"]:
+	"""
+	Return the side of a rotated label that stays under its tick.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	rotation
+		The angle of the label in degrees.
+
+	Returns
+	-------
+	Literal["left", "center", "right"]
+		The end of the text for a positive angle, its start for a negative one, its middle without rotation.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.drawing.tick_rotation import choose_alignment
+	>>> choose_alignment(45.0), choose_alignment(-45.0), choose_alignment(0.0)
+	('right', 'left', 'center')
+	"""
+	if rotation > NO_ROTATION:
+		return "right"
+
+	if rotation < NO_ROTATION:
+		return "left"
+
+	return "center"

numdaplot/plots/drawing/time_axis.py

@@ -0,0 +1,212 @@
+"""
+Axes of times of day, counted in hours since midnight and labeled ``HH:MM``.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from matplotlib.axes import Axes
+from matplotlib.axis import Axis
+from matplotlib.ticker import FuncFormatter, MultipleLocator
+from numpy.typing import NDArray
+
+from numdaplot.data_types.type import Type
+from numdaplot.data_types.value_family import ValueFamily, find_family
+from numdaplot.plots.chart_layer import ChartLayer
+from numdaplot.plots.data.chart_values import ChartValues
+
+MINUTES_PER_HOUR = 60
+MINUTES_PER_DAY = 1440
+OUTSIDE_DAY_LABEL = ""
+HOUR_LABEL = "{hour:02d}:{minute:02d}"
+# The step between two labels, in hours, for the widest span of times it fits, in hours.
+HOUR_STEPS = ((1.0, 0.25), (3.0, 0.5), (6.0, 1.0), (12.0, 2.0))
+LONGEST_HOUR_STEP = 3.0
+
+
+def format_hour(hours: float, _position: object = None) -> str:
+	"""
+	Return a number of hours since midnight as ``HH:MM``, rounded to the minute.
+
+	The ticks that the margins of an axis place before 00:00 or after 24:00 are left without label.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	hours
+		The hours since midnight, such as 15.5.
+	_position
+		The position of the label, given by matplotlib and not used.
+
+	Returns
+	-------
+	str
+		The time, such as ``15:30``, or an empty text outside 00:00 to 24:00.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.drawing.time_axis import format_hour
+	>>> format_hour(15.5), format_hour(0.0), format_hour(24.0), format_hour(-3.0)
+	('15:30', '00:00', '24:00', '')
+	"""
+	minutes = hours * MINUTES_PER_HOUR
+	whole_minutes = round(minutes)
+	is_outside_day = whole_minutes < 0 or whole_minutes > MINUTES_PER_DAY
+	if is_outside_day:
+		return OUTSIDE_DAY_LABEL
+
+	hour, minute = divmod(whole_minutes, MINUTES_PER_HOUR)
+	hour_label = HOUR_LABEL.format(hour=hour, minute=minute)
+
+	return hour_label
+
+
+def choose_hour_step(hours: NDArray[numpy.float64]) -> float:
+	"""
+	Return the step between two labels of an axis of times, from the span of the times.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	hours
+		The hours since midnight shown on the axis, NaN where missing.
+
+	Returns
+	-------
+	float
+		A quarter of an hour for an hour or less, then half an hour, one, two or three hours.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.drawing.time_axis import choose_hour_step
+	>>> choose_hour_step(numpy.array([8.0, 23.0])), choose_hour_step(numpy.array([8.0, 8.5]))
+	(3.0, 0.25)
+	"""
+	present_hours = hours[~numpy.isnan(hours)]
+	if present_hours.size == 0:
+		return LONGEST_HOUR_STEP
+
+	earliest_hour = present_hours.min()
+	latest_hour = present_hours.max()
+	span = float(latest_hour - earliest_hour)
+	for widest_span, step in HOUR_STEPS:
+		if span <= widest_span:
+			return step
+
+	return LONGEST_HOUR_STEP
+
+
+def place_hour_ticks(axis: Axis, hours: NDArray[Any]) -> None:
+	"""
+	Place labels ``HH:MM`` on an axis counted in hours since midnight, at a regular step.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axis
+		A matplotlib axis.
+	hours
+		The hours since midnight shown on the axis.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.drawing.time_axis import place_hour_ticks
+	>>> axes = Figure().add_subplot()
+	>>> _ = axes.plot([8.0, 14.0], [1.0, 2.0])
+	>>> place_hour_ticks(axes.xaxis, numpy.array([8.0, 14.0]))
+	>>> axes.figure.canvas.draw()
+	>>> [label.get_text() for label in axes.get_xticklabels()][1:4]
+	['08:00', '09:00', '10:00']
+	"""
+	step = choose_hour_step(hours)
+	locator = MultipleLocator(step)
+	formatter = FuncFormatter(format_hour)
+	axis.set_major_locator(locator)
+	axis.set_major_formatter(formatter)
+
+
+def measures_times(value_type: Type) -> bool:
+	"""
+	Return whether the values of a chart are times of day, drawn on an axis labeled ``HH:MM``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value_type
+		The type of the values of the chart.
+
+	Returns
+	-------
+	bool
+		True for ``TIME``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.drawing.time_axis import measures_times
+	>>> measures_times(ndp.Type.TIME), measures_times(ndp.Type.FLOAT64)
+	(True, False)
+	"""
+	value_family = find_family(value_type)
+	is_time = value_family == ValueFamily.TIME
+
+	return is_time
+
+
+def place_value_hours(axes: Axes, layers: list[ChartLayer]) -> None:
+	"""
+	Label ``HH:MM`` the vertical axis of the lines and points measuring times of day, from all their values.
+
+	Histograms and boxes, which are drawn alone, label their own axis of values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axes
+		The matplotlib axes the charts are drawn on.
+	layers
+		The charts drawn on these axes and their values.
+
+	Examples
+	--------
+	>>> from datetime import time
+	>>> from matplotlib.figure import Figure
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.chart_layer import ChartLayer
+	>>> from numdaplot.plots.data.array_values import read_array_values
+	>>> from numdaplot.plots.drawing.time_axis import place_value_hours
+	>>> hours = ndp.Array.from_list([time(8), time(14)])
+	>>> axes = Figure().add_subplot()
+	>>> place_value_hours(axes, [ChartLayer(ndp.LineChart(), read_array_values(hours, "LineChart"))])
+	>>> axes.yaxis.get_major_formatter()(8.5)
+	'08:30'
+	"""
+	hour_series = list[NDArray[numpy.float64]]()
+
+	for layer in layers:
+		values = layer.values
+		if not isinstance(values, ChartValues):
+			continue
+
+		is_time = measures_times(values.value_type)
+		if not is_time:
+			continue
+
+		for series in values.series:
+			hour_series.append(series.values)
+
+	if hour_series == []:
+		return
+
+	hours = numpy.concatenate(hour_series)
+	place_hour_ticks(axes.yaxis, hours)

numdaplot/plots/drawing/whole_numbers.py

@@ -0,0 +1,72 @@
+"""
+Ticks of an axis holding whole numbers only.
+
+.. versionadded:: 0.1.0
+"""
+
+import numpy
+from matplotlib.axis import Axis
+from matplotlib.ticker import MaxNLocator
+from numpy.typing import NDArray
+
+
+def has_only_whole_numbers(numbers: NDArray[numpy.float64]) -> bool:
+	"""
+	Return whether every present number is a whole number.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	numbers
+		float64 numbers, NaN where a value is missing.
+
+	Returns
+	-------
+	bool
+		True when no present number has a fraction, such as days or counts.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.drawing.whole_numbers import has_only_whole_numbers
+	>>> has_only_whole_numbers(numpy.array([1.0, numpy.nan, 3.0]))
+	True
+	"""
+	present = ~numpy.isnan(numbers)
+	present_numbers = numbers[present]
+	rounded_numbers = numpy.round(present_numbers)
+	is_whole = rounded_numbers == present_numbers
+	all_whole = bool(numpy.all(is_whole))
+
+	return all_whole
+
+
+def place_whole_ticks(axis: Axis, numbers: NDArray[numpy.float64]) -> None:
+	"""
+	Place the ticks of an axis on whole numbers only, when every number it shows is whole.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axis
+		A matplotlib axis.
+	numbers
+		The numbers shown along the axis.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.drawing.whole_numbers import place_whole_ticks
+	>>> axes = Figure().add_subplot()
+	>>> lines = axes.plot([1.0, 2.0], [5.0, 6.0])
+	>>> place_whole_ticks(axes.xaxis, numpy.array([1.0, 2.0]))
+	>>> all(float(tick).is_integer() for tick in axes.get_xticks())
+	True
+	"""
+	all_whole = has_only_whole_numbers(numbers)
+	if all_whole:
+		whole_locator = MaxNLocator(integer=True)
+		axis.set_major_locator(whole_locator)

numdaplot/plots/figure/__init__.py

@@ -0,0 +1,5 @@
+"""
+Figures placing several Plots on a grid of cells.
+
+.. versionadded:: 0.1.0
+"""