numdaplot 0.1.0__py3-none-any.whl

numdaplot/plots/plot_output.py

@@ -0,0 +1,124 @@
+"""
+Output of a Plot: display, image files and matplotlib figures.
+
+.. versionadded:: 0.1.0
+"""
+
+from matplotlib.figure import Figure
+
+from numdaplot.plots.drawing.plot_drawing import build_figure
+from numdaplot.plots.output.image_saving import write_image
+from numdaplot.plots.output.plot_display import show_drawing
+from numdaplot.plots.output.shown_object import ShownObject
+from numdaplot.plots.plot_data import PlotData
+from numdaplot.plots.style.image_options import ImageOptions
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.tables.conflict import Conflict
+from numdaplot.tables.files.file_paths import FilePath
+
+
+class PlotOutput(PlotData):
+	"""
+	Output of a Plot: display, image files and matplotlib figures.
+
+	Use ``ndp.Plot``; this group only adds the output methods.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	def to_matplotlib(self) -> Figure:
+		"""
+		Return a new matplotlib figure of the Plot, to change it with matplotlib.
+
+		Changing the figure never changes the Plot. The figure is not managed by ``matplotlib.pyplot``, so
+		a notebook does not display it on its own.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		matplotlib.figure.Figure
+			The figure, drawn on a single matplotlib ``Axes``.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0])
+		>>> style = ndp.PlotStyle(title="Prices")
+		>>> figure = ndp.Plot.line(prices, style=style).to_matplotlib()
+		>>> figure.axes[0].get_title()
+		'Prices'
+		>>> figure.axes[0].lines[0].get_ydata()
+		array([12. , 15.5, 14. ])
+		"""
+		drawing = self._describe_drawing()
+		figure = build_figure(drawing)
+
+		return figure
+
+	@checked_arguments
+	def save(self, path: FilePath, options: ImageOptions | None = None, on_conflict: Conflict = Conflict.ERROR) -> None:
+		"""
+		Save the Plot as an image, in the format named by the extension of the path.
+
+		``.png`` gives an image made of pixels, ``.svg`` and ``.pdf`` images made of lines and texts that stay
+		sharp at any zoom. The image has the size of the style, 640 by 480 pixels for a PNG image by default.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		path
+			The path of the image, a ``FilePath`` such as ``"chart.png"`` or ``Path("images/chart.svg")``, ending with
+			``.png``, ``.svg`` or ``.pdf``.
+		options
+			The resolution of a PNG image, 100 dots per inch when omitted. SVG and PDF images take none.
+		on_conflict
+			``ERROR`` by default, refusing to overwrite an existing file, or ``REPLACE`` to overwrite it.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		UnsupportedImageFormatError
+			When the path does not end with ``.png``, ``.svg`` or ``.pdf``.
+		RefusedSettingError
+			When options are given for an SVG or PDF image.
+		FileExistsError
+			When a file exists at the path and ``on_conflict`` is ``ERROR``.
+		FileAccessError
+			When the file system refuses the file: missing folder, missing permission and so on.
+
+		Examples
+		--------
+		>>> import tempfile
+		>>> from pathlib import Path
+		>>> import numdaplot as ndp
+		>>> path = Path(tempfile.mkdtemp()) / "prices.svg"
+		>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0])
+		>>> plot = ndp.Plot.line(prices)
+		>>> plot.save(path)
+		>>> path.read_text().startswith("<?xml")
+		True
+		"""
+		drawing = self._describe_drawing()
+		write_image(drawing, path, options, on_conflict)
+
+	def show(self) -> None:
+		"""
+		Show the Plot: as an image in a Jupyter notebook, in a matplotlib window anywhere else.
+
+		In a script, the window stays open until it is closed. When no window can be opened, because Python has no
+		``tkinter`` or runs on a server, nothing is shown and a ``DisplayWarning`` suggests saving the Plot instead.
+
+		.. versionadded:: 0.1.0
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+		>>> plot = ndp.Plot.bar(prices)
+		>>> plot.show()
+		"""
+		drawing = self._describe_drawing()
+		show_drawing(drawing, ShownObject.PLOT)

numdaplot/plots/plot_overlays.py

@@ -0,0 +1,273 @@
+"""
+Charts drawn over the charts of a Plot.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import replace
+from typing import Self
+
+from numdaplot.arrays.array import Array
+from numdaplot.plots.chart_layer import ChartLayer
+from numdaplot.plots.charts.bar_chart import BarChart
+from numdaplot.plots.charts.line_chart import LineChart
+from numdaplot.plots.charts.scatter_chart import ScatterChart
+from numdaplot.plots.charts.value_axis import ValueAxis
+from numdaplot.plots.drawing.layer_alignment import align_layers
+from numdaplot.plots.layer_reading import read_bar_layer, read_line_layer, read_scatter_layer
+from numdaplot.plots.overlay_checks import (
+	require_overlay_base,
+	require_same_positions,
+	require_same_values,
+	require_vertical_bars,
+)
+from numdaplot.plots.plot_data import PlotData
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.tables.table import Table
+
+ADD_LINE_NAME = "add_line"
+ADD_BAR_NAME = "add_bar"
+ADD_SCATTER_NAME = "add_scatter"
+
+
+class PlotOverlays(PlotData):
+	"""
+	Charts drawn over the charts of a Plot.
+
+	Use ``ndp.Plot``; this group only adds the ``add_*`` methods.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def add_line(self, data: Table | Array, chart: LineChart | None = None, axis: ValueAxis = ValueAxis.LEFT) -> Self:
+		"""
+		Return a new Plot with lines added over the charts of this one.
+
+		The lines take the colors of the default cycle after the ones already used. Over bars or texts, their
+		``x`` values are placed on the labels of the Plot, new labels following the others.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		data
+			The Table or the Array of the lines, which may differ from the one of the Plot.
+		chart
+			The columns drawn and the look of the lines.
+			The default ``LineChart`` when omitted, which draws an Array: a Table needs the columns named.
+		axis
+			``ValueAxis.LEFT`` by default to share the scale of the Plot, ``ValueAxis.RIGHT`` for a scale of
+			their own on the right.
+
+		Returns
+		-------
+		Self
+			A new Plot; this one is left unchanged.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		RefusedSettingError
+			When the Plot does not draw lines, vertical bars or points.
+		IncompatibleChartsError
+			When the ``x`` values are not of the kind of the ones of the Plot: numbers, dates, texts or times of day;
+			or when one measures numbers and the other times of day on the same axis.
+		DuplicateLabelError
+			When a label appears twice in the ``x`` values of one chart placed on labels.
+		InvalidChartDataError
+			When a Table has no ``y`` columns, or an Array has ``x`` or ``y`` columns.
+		InvalidColorCountError
+			When the colors of the chart are not one per line.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> months = ndp.Array.from_list(["Jan", "Feb", "Mar", "Apr"])
+		>>> sales = ndp.Array.from_list([120.0, 150.0, 90.0, 170.0])
+		>>> targets = ndp.Array.from_list([130.0, 130.0, 140.0, 140.0])
+		>>> shop = ndp.Table.from_arrays({"month": months, "sales": sales, "target": targets})
+		>>> plot = ndp.Plot.bar(shop, ndp.BarChart(x="month", y=["sales"]))
+		>>> line = ndp.LineChart(x="month", y=["target"], marker=ndp.MarkerShape.CIRCLE)
+		>>> both = plot.add_line(shop, line)
+		>>> both.show()
+		"""
+		if chart is None:
+			chart = LineChart()
+
+		layer = read_line_layer(data, chart)
+		added_plot = self._add_layer(layer, axis, ADD_LINE_NAME)
+
+		return added_plot
+
+	@checked_arguments
+	def add_bar(self, data: Table | Array, chart: BarChart | None = None, axis: ValueAxis = ValueAxis.LEFT) -> Self:
+		"""
+		Return a new Plot with vertical bars added over the charts of this one.
+
+		The bars are drawn over the ones already there, at the same positions: to draw bars side by side, give
+		several columns to a single ``BarChart``. Their ``x`` values are placed on the labels of the Plot, new
+		labels following the others.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		data
+			The Table or the Array of the bars, which may differ from the one of the Plot.
+		chart
+			The columns drawn and the look of the bars, which must be vertical.
+			The default ``BarChart`` when omitted, which draws an Array: a Table needs the columns named.
+		axis
+			``ValueAxis.LEFT`` by default to share the scale of the Plot, ``ValueAxis.RIGHT`` for a scale of
+			their own on the right.
+
+		Returns
+		-------
+		Self
+			A new Plot; this one is left unchanged.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		RefusedSettingError
+			When the bars are horizontal, or the Plot does not draw lines, vertical bars or points.
+		IncompatibleChartsError
+			When the ``x`` values are not of the kind of the ones of the Plot: numbers, dates, texts or times of day;
+			or when one measures numbers and the other times of day on the same axis.
+		DuplicateLabelError
+			When a label appears twice in the ``x`` values of one chart.
+		InvalidChartDataError
+			When a Table has no ``y`` columns, or an Array has ``x`` or ``y`` columns.
+		InvalidColorCountError
+			When the colors of the chart are not one per series.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> months = ndp.Array.from_list(["Jan", "Feb", "Mar", "Apr"])
+		>>> sales = ndp.Array.from_list([120.0, 150.0, 90.0, 170.0])
+		>>> targets = ndp.Array.from_list([130.0, 130.0, 140.0, 160.0])
+		>>> shop = ndp.Table.from_arrays({"month": months, "sales": sales, "target": targets})
+		>>> plot = ndp.Plot.bar(shop, ndp.BarChart(x="month", y=["target"], colors=[ndp.CustomColor("#d9d9d9")]))
+		>>> bars = ndp.BarChart(x="month", y=["sales"], colors=[ndp.Color.BLUE])
+		>>> both = plot.add_bar(shop, bars)
+		>>> both.show()
+		"""
+		if chart is None:
+			chart = BarChart()
+
+		require_vertical_bars(chart, ADD_BAR_NAME)
+		layer = read_bar_layer(data, chart)
+		added_plot = self._add_layer(layer, axis, ADD_BAR_NAME)
+
+		return added_plot
+
+	@checked_arguments
+	def add_scatter(
+		self, data: Table | Array, chart: ScatterChart | None = None, axis: ValueAxis = ValueAxis.LEFT
+	) -> Self:
+		"""
+		Return a new Plot with points added over the charts of this one.
+
+		The points take the color of the default cycle after the ones already used, unless ``color`` or
+		``color_by`` is given. Over bars or texts, their ``x`` values are placed on the labels of the Plot.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		data
+			The Table or the Array of the points, which may differ from the one of the Plot.
+		chart
+			The columns drawn and the look of the points.
+			The default ``ScatterChart`` when omitted, which draws an Array: a Table needs the columns named.
+		axis
+			``ValueAxis.LEFT`` by default to share the scale of the Plot, ``ValueAxis.RIGHT`` for a scale of
+			their own on the right.
+
+		Returns
+		-------
+		Self
+			A new Plot; this one is left unchanged.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		RefusedSettingError
+			When the Plot does not draw lines, vertical bars or points.
+		IncompatibleChartsError
+			When the ``x`` values are not of the kind of the ones of the Plot: numbers, dates, texts or times of day;
+			or when one measures numbers and the other times of day on the same axis.
+		DuplicateLabelError
+			When a label appears twice in the ``x`` values of one chart placed on labels.
+		InvalidChartDataError
+			When a Table has no ``y`` column, or an Array has a column setting.
+		InvalidColorCountError
+			When ``color`` is given for an Array of several columns.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> days = ndp.Array.from_list([1, 2, 3, 4, 5, 6])
+		>>> trend = ndp.Array.from_list([10.0, 12.0, 14.0, 16.0, 18.0, 20.0])
+		>>> measures = ndp.Array.from_list([10.5, 11.2, 14.8, 15.1, 18.9, 19.4])
+		>>> readings = ndp.Table.from_arrays({"day": days, "trend": trend, "measure": measures})
+		>>> plot = ndp.Plot.line(readings, ndp.LineChart(x="day", y=["trend"]))
+		>>> points = ndp.ScatterChart(x="day", y="measure")
+		>>> both = plot.add_scatter(readings, points)
+		>>> both.show()
+		"""
+		if chart is None:
+			chart = ScatterChart()
+
+		layer = read_scatter_layer(data, chart)
+		added_plot = self._add_layer(layer, axis, ADD_SCATTER_NAME)
+
+		return added_plot
+
+	def _add_layer(self, layer: ChartLayer, axis: ValueAxis, method_name: str) -> Self:
+		"""
+		Return a new Plot with a chart added after the ones of this one, once checked against them.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		layer
+			The chart added and its values.
+		axis
+			The vertical axis the chart is measured on.
+		method_name
+			The method adding the chart, shown in error messages.
+
+		Returns
+		-------
+		Self
+			The new Plot, with the style of this one.
+
+		Raises
+		------
+		RefusedSettingError
+			When the Plot does not draw lines, vertical bars or points.
+		IncompatibleChartsError
+			When the ``x`` values are not of the kind of the ones of the Plot, or when one measures numbers and the
+			other times of day on the same axis.
+		DuplicateLabelError
+			When a label appears twice in the ``x`` values of one chart placed on labels.
+		"""
+		first_layer = self._layers[0]
+		require_overlay_base(first_layer, method_name)
+		require_same_positions(first_layer, layer)
+		require_same_values(self._layers, layer, axis)
+		axis_layer = replace(layer, value_axis=axis)
+		layers = [*self._layers, axis_layer]
+		# Aligning the charts on their labels checks them, so a wrong chart is refused when it is added.
+		align_layers(layers)
+		plot_class = type(self)
+		added_plot = plot_class._create(layers, self._style)
+
+		return added_plot

numdaplot/plots/plot_overview_creation.py

@@ -0,0 +1,195 @@
+"""
+Creation of a Plot giving an overview of the values of a Table or an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Self
+
+from numdaplot.arrays.array import Array
+from numdaplot.plots.chart_layer import ChartLayer
+from numdaplot.plots.charts.heatmap_chart import HeatmapChart
+from numdaplot.plots.charts.missing_chart import MissingChart
+from numdaplot.plots.charts.missing_map_chart import MissingMapChart
+from numdaplot.plots.data.heatmap_values import read_heatmap_values
+from numdaplot.plots.data.missing_cells import read_missing_cells, read_missing_counts
+from numdaplot.plots.plot_data import PlotData
+from numdaplot.plots.style.plot_style import PlotStyle
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.tables.table import Table
+
+
+class PlotOverviewCreation(PlotData):
+	"""
+	Creation of a Plot giving an overview of the values of a Table or an Array.
+
+	Use ``ndp.Plot.heatmap``, ``ndp.Plot.missing_by_column`` and ``ndp.Plot.missing_map``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@classmethod
+	@checked_arguments
+	def heatmap(cls, data: Table | Array, chart: HeatmapChart | None = None, style: PlotStyle | None = None) -> Self:
+		"""
+		Return a Plot coloring each value of columns of numbers along a color scale.
+
+		For a Table, ``HeatmapChart.columns`` names the columns drawn and ``HeatmapChart.labels`` the column labeling
+		the rows.
+		For an Array of one or two dimensions, each column is drawn and each row is labeled with its number.
+		When there are more rows or columns than the image can show, each band shows the mean of its cells, without
+		their values written, with a ``ReadabilityWarning``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		data
+			The Table or the Array drawn.
+		chart
+			The columns drawn, the row labels, the color scale and the cell values.
+			The default ``HeatmapChart`` when omitted, which draws an Array: a Table needs the columns named.
+		style
+			The look of the Plot, the default ``PlotStyle`` when omitted.
+
+		Returns
+		-------
+		Self
+			The Plot, which ``show`` displays and ``save`` writes as an image.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		InvalidChartDataError
+			When a Table has no ``columns``, or an Array has ``columns`` or ``labels``.
+		ColumnNotFoundError
+			When a column does not exist.
+		IncompatibleTypesError
+			When ``labels`` holds booleans or durations, or a drawn column does not hold numbers.
+		DimensionError
+			When an Array has more than two dimensions.
+
+		Warns
+		-----
+		ReadabilityWarning
+			When the cells are merged into bands.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> days = ndp.Array.from_list(["Mon", "Tue", "Wed", "Thu", "Fri"])
+		>>> morning = ndp.Array.from_list([12.0, 15.0, 9.0, 14.0, 20.0])
+		>>> noon = ndp.Array.from_list([30.0, 28.0, 25.0, 33.0, 41.0])
+		>>> evening = ndp.Array.from_list([18.0, 22.0, None, 19.0, 35.0])
+		>>> orders = ndp.Table.from_arrays({"day": days, "morning": morning, "noon": noon, "evening": evening})
+		>>> chart = ndp.HeatmapChart(columns=["morning", "noon", "evening"], labels="day", values=ndp.CellValues.SHOWN)
+		>>> style = ndp.PlotStyle(title="Orders")
+		>>> plot = ndp.Plot.heatmap(orders, chart, style)
+		>>> plot.show()
+		"""
+		if chart is None:
+			chart = HeatmapChart()
+
+		values = read_heatmap_values(data, chart)
+		layer = ChartLayer(chart, values)
+		plot = cls._create_from_layer(layer, style)
+
+		return plot
+
+	@classmethod
+	@checked_arguments
+	def missing_by_column(cls, table: Table, chart: MissingChart | None = None, style: PlotStyle | None = None) -> Self:
+		"""
+		Return a Plot drawing one bar per column of a Table, as high as its missing values.
+
+		Above each bar are its number of missing values and their share of the rows, written on one line going upwards
+		when the bars are too narrow, and left out when they are too narrow for that.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		table
+			The Table whose missing values are counted.
+		chart
+			The measure, the number of missing values of each column when omitted.
+		style
+			The look of the Plot, the default ``PlotStyle`` when omitted.
+
+		Returns
+		-------
+		Self
+			The Plot, which ``show`` displays and ``save`` writes as an image.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Nice", "Pau", "Lyon"])
+		>>> prices = ndp.Array.from_list([12.0, None, None, 15.5, None])
+		>>> surfaces = ndp.Array.from_list([30.0, 45.0, None, 60.0, 52.0])
+		>>> flats = ndp.Table.from_arrays({"city": cities, "price": prices, "surface": surfaces})
+		>>> style = ndp.PlotStyle(title="Missing values")
+		>>> plot = ndp.Plot.missing_by_column(flats, style=style)
+		>>> plot.show()
+		"""
+		if chart is None:
+			chart = MissingChart()
+
+		values = read_missing_counts(table, chart.measure)
+		layer = ChartLayer(chart, values)
+		plot = cls._create_from_layer(layer, style)
+
+		return plot
+
+	@classmethod
+	@checked_arguments
+	def missing_map(cls, table: Table, style: PlotStyle | None = None) -> Self:
+		"""
+		Return a Plot drawing each value of a Table as a cell, light gray when present and dark when missing.
+
+		The columns are side by side and the rows go down from the first one, which shows whether the missing
+		values gather in some rows or columns. When there are more rows or columns than the image can show, each mark
+		stands for at least one missing value among the cells it covers, so no missing value is lost. The legend gives
+		the total of missing values.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		table
+			The Table whose missing values are drawn.
+		style
+			The look of the Plot, the default ``PlotStyle`` when omitted.
+
+		Returns
+		-------
+		Self
+			The Plot, which ``show`` displays and ``save`` writes as an image.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Nice", "Pau", "Lyon", "Nice", "Paris", "Pau"])
+		>>> prices = ndp.Array.from_list([12.0, None, None, 15.5, None, 18.0, 11.0, 14.0])
+		>>> surfaces = ndp.Array.from_list([30.0, 45.0, None, 60.0, 52.0, 41.0, None, 38.0])
+		>>> flats = ndp.Table.from_arrays({"city": cities, "price": prices, "surface": surfaces})
+		>>> style = ndp.PlotStyle(legend=ndp.LegendPosition.OUTSIDE_RIGHT)
+		>>> plot = ndp.Plot.missing_map(flats, style)
+		>>> plot.show()
+		"""
+		values = read_missing_cells(table)
+		layer = ChartLayer(MissingMapChart(), values)
+		plot = cls._create_from_layer(layer, style)
+
+		return plot