numdaplot 0.1.0__py3-none-any.whl

numdaplot/plots/drawing/cell_merging.py

@@ -0,0 +1,237 @@
+"""
+Merging of the cells of a map too small to give each of them a pixel.
+
+.. versionadded:: 0.1.0
+"""
+
+from collections.abc import Callable
+
+import numpy
+from matplotlib.axes import Axes
+from numpy.typing import NDArray
+
+type CellMerger = Callable[[NDArray[numpy.float64], int, int], NDArray[numpy.float64]]
+"""A function merging cells along an axis into at most a number of bands.
+
+.. versionadded:: 0.1.0
+"""
+
+MINIMUM_BAND_PIXELS = 2
+# Below this share of the pixels before the layout, each cell keeps at least one pixel afterwards.
+FITTING_SHARE = 0.75
+ROW_AXIS = 0
+COLUMN_AXIS = 1
+HALF_CELL = 0.5
+
+
+def find_band_count(length_pixels: float) -> int:
+	"""
+	Return how many bands of cells an axis can show, each one staying visible once the layout narrows the axes.
+
+	The layout keeps more than half of the length of the axes, so a band of 2 pixels keeps at least 1 pixel.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	length_pixels
+		The length of the axis before the layout, in pixels.
+
+	Returns
+	-------
+	int
+		The number of bands, at least 1.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.drawing.cell_merging import find_band_count
+	>>> find_band_count(369.6)
+	184
+	"""
+	band_count = int(length_pixels // MINIMUM_BAND_PIXELS)
+	shown_band_count = max(band_count, 1)
+
+	return shown_band_count
+
+
+def merge_cells(cells: NDArray[numpy.float64], band_count: int, axis: int) -> NDArray[numpy.float64]:
+	"""
+	Return the cells merged along an axis into bands, each one keeping the highest value of its cells.
+
+	Matplotlib only keeps one cell per pixel when it shrinks an image, which would lose most of the marked cells.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	cells
+		The cells, in two dimensions.
+	band_count
+		The most bands kept.
+	axis
+		The axis merged, 0 for the rows and 1 for the columns.
+
+	Returns
+	-------
+	NDArray[numpy.float64]
+		The merged cells, or the same cells when they fit in the bands.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.drawing.cell_merging import merge_cells
+	>>> merge_cells(numpy.array([[0.0], [1.0], [0.0], [0.0]]), 2, 0).tolist()
+	[[1.0], [0.0]]
+	"""
+	cell_count = cells.shape[axis]
+	if cell_count <= band_count:
+		return cells
+
+	first_cells = find_first_cells(cell_count, band_count)
+	merged_cells = numpy.maximum.reduceat(cells, first_cells, axis=axis)
+
+	return merged_cells
+
+
+def average_cells(cells: NDArray[numpy.float64], band_count: int, axis: int) -> NDArray[numpy.float64]:
+	"""
+	Return the cells merged along an axis into bands, each one showing the mean of the present values of its cells.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	cells
+		The cells, in two dimensions, NaN for a missing value.
+	band_count
+		The most bands kept.
+	axis
+		The axis merged, 0 for the rows and 1 for the columns.
+
+	Returns
+	-------
+	NDArray[numpy.float64]
+		The merged cells, NaN for a band without value, or the same cells when they fit in the bands.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.drawing.cell_merging import average_cells
+	>>> average_cells(numpy.array([[1.0], [3.0], [numpy.nan], [numpy.nan]]), 2, 0).tolist()[0]
+	[2.0]
+	"""
+	cell_count = cells.shape[axis]
+	if cell_count <= band_count:
+		return cells
+
+	first_cells = find_first_cells(cell_count, band_count)
+	is_present = ~numpy.isnan(cells)
+	present_numbers = numpy.nan_to_num(cells)
+	totals = numpy.add.reduceat(present_numbers, first_cells, axis=axis)
+	present_counts = numpy.add.reduceat(is_present.astype(numpy.float64), first_cells, axis=axis)
+	empty_bands = present_counts == 0
+	divisors = numpy.where(empty_bands, numpy.nan, present_counts)
+	averaged_cells = totals / divisors
+
+	return averaged_cells
+
+
+def find_first_cells(cell_count: int, band_count: int) -> NDArray[numpy.intp]:
+	"""
+	Return the position of the first cell of each band, the bands sharing the cells evenly.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	cell_count
+		The number of cells, above the number of bands.
+	band_count
+		The number of bands.
+
+	Returns
+	-------
+	NDArray[numpy.intp]
+		One position per band.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.drawing.cell_merging import find_first_cells
+	>>> find_first_cells(10, 4).tolist()
+	[0, 2, 5, 7]
+	"""
+	band_numbers = numpy.arange(band_count, dtype=numpy.intp)
+	first_cells = band_numbers * cell_count // band_count
+
+	return first_cells
+
+
+def fit_cells_to_axes(grid: NDArray[numpy.float64], axes: Axes, merge: CellMerger) -> NDArray[numpy.float64]:
+	"""
+	Return the cells of a map merged along each direction where the axes have too few pixels for them.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	grid
+		The cells of the map.
+	axes
+		The matplotlib axes drawn on.
+	merge
+		What a band keeps of its cells: ``merge_cells`` or ``average_cells``.
+
+	Returns
+	-------
+	NDArray[numpy.float64]
+		The cells to draw, the same ones when they fit.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.drawing.cell_merging import fit_cells_to_axes, merge_cells
+	>>> axes = Figure().add_subplot()
+	>>> fit_cells_to_axes(numpy.zeros((1000, 2)), axes, merge_cells).shape
+	(184, 2)
+	"""
+	row_count, column_count = grid.shape
+	shown_cells = grid
+	if row_count > axes.bbox.height * FITTING_SHARE:
+		row_band_count = find_band_count(axes.bbox.height)
+		shown_cells = merge(shown_cells, row_band_count, ROW_AXIS)
+
+	if column_count > axes.bbox.width * FITTING_SHARE:
+		column_band_count = find_band_count(axes.bbox.width)
+		shown_cells = merge(shown_cells, column_band_count, COLUMN_AXIS)
+
+	return shown_cells
+
+
+def find_cell_limits(grid: NDArray[numpy.float64]) -> tuple[float, float, float, float]:
+	"""
+	Return where an image of a map goes, so that each row and column keeps its own number once merged.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	grid
+		The cells of the map before they are merged.
+
+	Returns
+	-------
+	tuple[float, float, float, float]
+		The left, right, bottom and top limits, the first row being on top.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.drawing.cell_merging import find_cell_limits
+	>>> find_cell_limits(numpy.zeros((3, 2)))
+	(-0.5, 1.5, 2.5, -0.5)
+	"""
+	row_count, column_count = grid.shape
+	cell_limits = (-HALF_CELL, column_count - HALF_CELL, row_count - HALF_CELL, -HALF_CELL)
+
+	return cell_limits

numdaplot/plots/drawing/chart_texts.py

@@ -0,0 +1,124 @@
+"""
+Title and axis labels of a Plot, chosen between its style and the defaults of its chart.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.plots.drawing.drawn_chart import DrawnChart
+from numdaplot.plots.style.plot_style import PlotStyle
+
+DEFAULT_TITLE = "{y_label} by {x_label}"
+
+
+def choose_title(drawn_chart: DrawnChart, style: PlotStyle) -> str:
+	"""
+	Return the title of a Plot: the style one, else the one of the chart, else the ``y`` label by the ``x`` label.
+
+	A label removed with an empty text keeps its default name in the title.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	drawn_chart
+		The default title and labels of the chart.
+	style
+		The title and the labels chosen, None for the default ones.
+
+	Returns
+	-------
+	str
+		The title, empty when the style removes it or when the chart has no label to build it from.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.drawing.drawn_chart import DrawnChart
+	>>> from numdaplot.plots.drawing.grid_axes import GridAxes
+	>>> from numdaplot.plots.drawing.chart_texts import choose_title
+	>>> drawn_chart = DrawnChart("day", "price", False, GridAxes.BOTH, None)
+	>>> choose_title(drawn_chart, ndp.PlotStyle())
+	'price by day'
+	>>> choose_title(drawn_chart, ndp.PlotStyle(x_label="Day"))
+	'price by Day'
+	"""
+	if style.title is not None:
+		return style.title
+
+	if drawn_chart.title is not None:
+		return drawn_chart.title
+
+	x_label = choose_title_label(style.x_label, drawn_chart.x_label)
+	y_label = choose_title_label(style.y_label, drawn_chart.y_label)
+	if x_label == "" or y_label == "":
+		return ""
+
+	title = DEFAULT_TITLE.format(y_label=y_label, x_label=x_label)
+
+	return title
+
+
+def choose_title_label(style_label: str | None, default_label: str | None) -> str:
+	"""
+	Return the name of an axis in a title: the style label, else the default label, even for a removed style label.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	style_label
+		The label chosen in the style, None for the default and an empty text for no label.
+	default_label
+		The default label of the chart, None for no label.
+
+	Returns
+	-------
+	str
+		The name, empty when there is none.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.drawing.chart_texts import choose_title_label
+	>>> choose_title_label("", "price")
+	'price'
+	"""
+	chosen_label = choose_label(style_label, default_label)
+	if chosen_label != "":
+		return chosen_label
+
+	default_name = choose_label(None, default_label)
+
+	return default_name
+
+
+def choose_label(style_label: str | None, default_label: str | None) -> str:
+	"""
+	Return the label of an axis.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	style_label
+		The label chosen in the style, None for the default.
+	default_label
+		The default label of the chart, None for no label.
+
+	Returns
+	-------
+	str
+		The chosen label, else the default one, else an empty text.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.drawing.chart_texts import choose_label
+	>>> choose_label(None, "price")
+	'price'
+	"""
+	if style_label is not None:
+		return style_label
+
+	if default_label is not None:
+		return default_label
+
+	return ""

numdaplot/plots/drawing/color_bar.py

@@ -0,0 +1,57 @@
+"""
+Color bar showing the color scale of a chart.
+
+.. versionadded:: 0.1.0
+"""
+
+# The matplotlib stubs leave the keyword arguments of most drawing methods untyped.
+# pyright: reportUnknownMemberType=false
+
+from typing import cast
+
+import numpy
+from matplotlib.axes import Axes
+from matplotlib.cm import ScalarMappable
+from matplotlib.figure import Figure
+from numpy.typing import NDArray
+
+from numdaplot.plots.drawing.whole_numbers import place_whole_ticks
+
+
+def add_color_bar(
+	axes: Axes, scaled_artist: ScalarMappable, scale_label: str, scaled_numbers: NDArray[numpy.float64]
+) -> None:
+	"""
+	Draw the color scale of a chart next to its axes, with a label.
+
+	Its ticks are on whole numbers only when every number colored is whole.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	axes
+		The matplotlib axes drawn on.
+	scaled_artist
+		The points or the cells colored along the scale.
+	scale_label
+		The label of the color bar, such as the ``color_by`` column of a ScatterChart, empty for none.
+	scaled_numbers
+		The numbers colored, NaN where a value is missing.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.drawing.color_bar import add_color_bar
+	>>> figure = Figure()
+	>>> axes = figure.add_subplot()
+	>>> add_color_bar(axes, axes.scatter([0.0], [1.0], c=[5.0]), "rooms", numpy.array([5.0]))
+	>>> figure.axes[1].get_ylabel()
+	'rooms'
+	"""
+	figure = cast(Figure, axes.figure)
+	# A color bar takes the opacity of what it describes, so it gets its own scale to stay opaque.
+	opaque_scale = ScalarMappable(norm=scaled_artist.norm, cmap=scaled_artist.cmap)
+	color_bar = figure.colorbar(opaque_scale, ax=axes, label=scale_label)
+	place_whole_ticks(color_bar.ax.yaxis, scaled_numbers)

numdaplot/plots/drawing/color_scale_values.py

@@ -0,0 +1,120 @@
+"""
+Values of the color scales of a chart: their matplotlib names and their limits.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any, cast
+
+import matplotlib
+import numpy
+from matplotlib.colors import Colormap, ListedColormap
+from numpy.typing import NDArray
+
+from numdaplot.plots.charts.color_scale import ColorScale
+
+SCALE_NAMES = {
+	ColorScale.VIRIDIS: "viridis",
+	ColorScale.BLUES: "Blues",
+	ColorScale.REDS: "Reds",
+	ColorScale.RED_BLUE: "RdBu_r",
+	ColorScale.GREENS: "Greens",
+	ColorScale.GRAYS: "Greys",
+	ColorScale.CIVIDIS: "cividis",
+}
+NO_LIMITS = (None, None)
+SCALES_STARTING_WHITE = frozenset({ColorScale.BLUES, ColorScale.REDS, ColorScale.GREENS, ColorScale.GRAYS})
+# The start of the scale keeps a point of the smallest values visible on a white background.
+VISIBLE_SCALE_START = 0.25
+SCALE_END = 1.0
+SCALE_COLOR_COUNT = 256
+
+
+def find_scale_limits(grid: NDArray[numpy.float64], color_scale: ColorScale) -> tuple[float | None, float | None]:
+	"""
+	Return the values of the two ends of a color scale, centered on 0 for ``RED_BLUE`` around 0.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	grid
+		The numbers colored, NaN where a value is missing.
+	color_scale
+		The color scale.
+
+	Returns
+	-------
+	tuple[float | None, float | None]
+		Opposite limits for ``RED_BLUE`` when the numbers are on both sides of 0, so white means 0, and None
+		otherwise, for limits on the smallest and the largest number.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> import numpy
+	>>> from numdaplot.plots.drawing.color_scale_values import find_scale_limits
+	>>> find_scale_limits(numpy.array([[-1.0, 4.0]]), ndp.ColorScale.RED_BLUE)
+	(-4.0, 4.0)
+	"""
+	if color_scale != ColorScale.RED_BLUE:
+		return NO_LIMITS
+
+	present = ~numpy.isnan(grid)
+	present_numbers = grid[present]
+	present_count = len(present_numbers)
+	if present_count == 0:
+		return NO_LIMITS
+
+	smallest_number = float(present_numbers.min())
+	largest_number = float(present_numbers.max())
+	is_below_zero = smallest_number < 0
+	is_above_zero = largest_number > 0
+	spans_zero = is_below_zero and is_above_zero
+	if not spans_zero:
+		return NO_LIMITS
+
+	smallest_distance = abs(smallest_number)
+	limit = max(smallest_distance, largest_number)
+
+	return -limit, limit
+
+
+def find_point_colors(color_scale: ColorScale) -> Colormap:
+	"""
+	Return the matplotlib colors of points colored along a color scale.
+
+	A scale starting from white loses its lightest colors, so that no point disappears on a white background.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	color_scale
+		The color scale.
+
+	Returns
+	-------
+	matplotlib.colors.Colormap
+		The colors, under the matplotlib name of the scale.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.drawing.color_scale_values import find_point_colors
+	>>> find_point_colors(ndp.ColorScale.VIRIDIS).name
+	'viridis'
+	>>> [float(color) < 0.9 for color in find_point_colors(ndp.ColorScale.BLUES)(0.0)[:3]]
+	[True, True, False]
+	"""
+	scale_name = SCALE_NAMES[color_scale]
+	full_colors = matplotlib.colormaps[scale_name]
+	if color_scale not in SCALES_STARTING_WHITE:
+		return full_colors
+
+	kept_positions = numpy.linspace(VISIBLE_SCALE_START, SCALE_END, SCALE_COLOR_COUNT)
+	# Some versions of the matplotlib stubs leave the result of a Colormap unknown.
+	kept_colors = cast(Any, full_colors(kept_positions))
+	visible_colors = ListedColormap(kept_colors, name=scale_name)
+
+	return visible_colors

numdaplot/plots/drawing/default_labels.py

@@ -0,0 +1,41 @@
+"""
+Default labels of a chart when its data names no column for an axis.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.plots.data.chart_values import Positions
+
+ROW_LABEL = "Row"
+COLUMN_LABEL = "Column"
+
+
+def find_position_label(positions: Positions) -> str:
+	"""
+	Return the default label of the axis of the positions: the name of their column, else ``Row``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	positions
+		The positions of a chart.
+
+	Returns
+	-------
+	str
+		The label of the axis.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.plots.data.chart_values import Positions
+	>>> from numdaplot.plots.data.position_kind import PositionKind
+	>>> from numdaplot.plots.drawing.default_labels import find_position_label
+	>>> find_position_label(Positions(PositionKind.NUMBERS, numpy.array([0.0]), None))
+	'Row'
+	"""
+	if positions.name is None:
+		return ROW_LABEL
+
+	return positions.name

numdaplot/plots/drawing/drawn_chart.py

@@ -0,0 +1,50 @@
+"""
+What a drawn chart tells the style of its Plot.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.plots.drawing.grid_axes import GridAxes
+
+
+@dataclass(frozen=True)
+class DrawnChart:
+	"""
+	What a drawn chart tells the style of its Plot: default labels, axis directions and grid lines.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	x_label
+		The default label of the axis of the ``x`` values, or None.
+	y_label
+		The default label of the axis of the series, or None.
+	x_on_vertical_axis
+		True when the ``x`` values are on the vertical axis, as with horizontal bars.
+	grid_axes
+		The axes crossed by the grid lines, when the PlotStyle shows them.
+	legend_title
+		The title of the legend, such as the ``color_by`` column of a ScatterChart, or None.
+	title
+		The default title when it is not the ``y`` label by the ``x`` label, or None.
+	legend_outside
+		True when ``LegendPosition.BEST`` places the legend past the axes, the chart filling them.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.drawing.drawn_chart import DrawnChart
+	>>> from numdaplot.plots.drawing.grid_axes import GridAxes
+	>>> DrawnChart("day", "price", False, GridAxes.BOTH, None).grid_axes
+	<GridAxes.BOTH: 1>
+	"""
+
+	x_label: str | None
+	y_label: str | None
+	x_on_vertical_axis: bool
+	grid_axes: GridAxes
+	legend_title: str | None
+	title: str | None = None
+	legend_outside: bool = False

numdaplot/plots/drawing/grid_axes.py

@@ -0,0 +1,75 @@
+"""
+Axes crossed by the grid lines of a chart.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class GridAxes(Enum):
+	"""
+	Axes crossed by the grid lines of a chart, when its PlotStyle shows grid lines.
+
+	.. versionadded:: 0.1.0
+
+	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.line_drawing import draw_line_chart
+	>>> prices = ndp.Array.from_list([12.0, 15.5])
+	>>> layer = ChartLayer(ndp.LineChart(), read_array_values(prices, "LineChart"))
+	>>> draw_line_chart(Figure().add_subplot(), layer).grid_axes
+	<GridAxes.BOTH: 1>
+	"""
+
+	BOTH = auto()
+	"""
+	Grid lines across both axes, as for lines and points.
+
+	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.style_drawing import draw_grid_lines
+	>>> axes = Figure().add_subplot()
+	>>> draw_grid_lines(axes, DrawnChart(None, None, False, GridAxes.BOTH, None))
+	>>> axes.xaxis.get_gridlines()[0].get_visible()
+	True
+	"""
+
+	VALUES = auto()
+	"""
+	Grid lines across the axis of the values only, as for bars, histograms and boxes.
+
+	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.style_drawing import draw_grid_lines
+	>>> axes = Figure().add_subplot()
+	>>> draw_grid_lines(axes, DrawnChart(None, None, False, GridAxes.VALUES, None))
+	>>> axes.xaxis.get_gridlines()[0].get_visible()
+	False
+	"""
+
+	NONE = auto()
+	"""
+	No grid lines, as for pies and heatmaps, whose grid lines would cross the drawing.
+
+	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.style_drawing import draw_grid_lines
+	>>> axes = Figure().add_subplot()
+	>>> draw_grid_lines(axes, DrawnChart(None, None, False, GridAxes.NONE, None))
+	>>> axes.yaxis.get_gridlines()[0].get_visible()
+	False
+	"""