numdaplot 0.1.0__py3-none-any.whl

numdaplot/plots/figure/cell.py

@@ -0,0 +1,95 @@
+"""
+Place of a Plot in the grid of a Figure.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.invalid_count_error import InvalidCountError
+from numdaplot.errors.invalid_position_error import InvalidPositionError
+from numdaplot.settings.field_types import require_field_types
+
+MINIMUM_SPAN = 1
+FIRST_POSITION = 0
+
+
+@dataclass(frozen=True)
+class Cell:
+	"""
+	Place of a Plot in the grid of a ``Figure``: its first cell, and how many cells it spans.
+
+	Rows and columns are numbered from 0, row 0 at the top and column 0 on the left.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	row
+		The row of the top cell, from 0.
+	column
+		The column of the left cell, from 0.
+	row_span
+		The number of rows covered, 1 by default.
+	column_span
+		The number of columns covered, 1 by default.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidPositionError
+		When ``row`` or ``column`` is lower than 0.
+	InvalidCountError
+		When ``row_span`` or ``column_span`` is lower than 1.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> months = ndp.Array.from_list([1, 2, 3, 4, 5, 6])
+	>>> sales = ndp.Array.from_list([120.0, 150.0, 90.0, 170.0, 160.0, 185.0])
+	>>> costs = ndp.Array.from_list([80.0, 95.0, 70.0, 110.0, 100.0, 120.0])
+	>>> shop = ndp.Table.from_arrays({"month": months, "sales": sales, "cost": costs})
+	>>> trend = ndp.Plot.line(shop, ndp.LineChart(x="month", y=["sales", "cost"]))
+	>>> sales_spread = ndp.Plot.box(shop, ndp.BoxChart(columns=["sales"]))
+	>>> cost_spread = ndp.Plot.box(shop, ndp.BoxChart(columns=["cost"]))
+	>>> figure = ndp.Figure(ndp.Layout(rows=2, columns=2))
+	>>> figure = figure.place(trend, ndp.Cell(row=0, column=0, column_span=2))
+	>>> figure = figure.place(sales_spread, ndp.Cell(row=1, column=0))
+	>>> figure = figure.place(cost_spread, ndp.Cell(row=1, column=1))
+	>>> figure.show()
+	"""
+
+	row: int
+	column: int
+	row_span: int = MINIMUM_SPAN
+	column_span: int = MINIMUM_SPAN
+
+	def __post_init__(self) -> None:
+		"""
+		Check the first cell and the number of rows and of columns covered.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidPositionError
+			When ``row`` or ``column`` is lower than 0.
+		InvalidCountError
+			When ``row_span`` or ``column_span`` is lower than 1.
+		"""
+		require_field_types(self)
+
+		if self.row < FIRST_POSITION:
+			raise InvalidPositionError(self.row)
+
+		if self.column < FIRST_POSITION:
+			raise InvalidPositionError(self.column)
+
+		if self.row_span < MINIMUM_SPAN:
+			raise InvalidCountError(self.row_span, MINIMUM_SPAN)
+
+		if self.column_span < MINIMUM_SPAN:
+			raise InvalidCountError(self.column_span, MINIMUM_SPAN)

numdaplot/plots/figure/figure.py

@@ -0,0 +1,256 @@
+"""
+Several Plots placed on a grid of cells.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Self
+
+from matplotlib.figure import Figure as MatplotlibFigure
+from matplotlib.figure import FigureBase
+
+from numdaplot.plots.drawing.plot_drawing import FigureDrawing, build_figure
+from numdaplot.plots.figure.cell import Cell
+from numdaplot.plots.figure.figure_drawing import choose_figure_size, draw_figure
+from numdaplot.plots.figure.figure_style import FigureStyle
+from numdaplot.plots.figure.layout import Layout
+from numdaplot.plots.figure.placement import Placement, require_cell_inside, require_free_cells
+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 import Plot
+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 Figure:
+	"""
+	Several Plots placed on a grid of cells, shown and saved as one image.
+
+	A Figure is immutable: ``place`` returns a new Figure. Each Plot keeps its own axes and its own PlotStyle,
+	except its size: the Figure gives it the size of its cells. A cell without Plot stays blank.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	layout
+		The grid of cells.
+	style
+		The title and the size of the Figure, the default ``FigureStyle`` when omitted.
+
+	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])
+	>>> visits = ndp.Array.from_list([900.0, 1100.0, 800.0, 1300.0])
+	>>> shop = ndp.Table.from_arrays({"month": months, "sales": sales, "visits": visits})
+	>>> sales_plot = ndp.Plot.bar(shop, ndp.BarChart(x="month", y=["sales"]))
+	>>> visits_plot = ndp.Plot.line(shop, ndp.LineChart(x="month", y=["visits"]))
+	>>> figure = ndp.Figure(ndp.Layout(rows=1, columns=2), ndp.FigureStyle(title="Shop"))
+	>>> figure = figure.place(sales_plot, ndp.Cell(row=0, column=0))
+	>>> figure = figure.place(visits_plot, ndp.Cell(row=0, column=1))
+	>>> figure.show()
+	"""
+
+	@checked_arguments
+	def __init__(self, layout: Layout, style: FigureStyle | None = None) -> None:
+		"""
+		Keep the grid and the style of an empty Figure.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		layout
+			The grid of cells.
+		style
+			The title and the size of the Figure, the default ``FigureStyle`` when omitted.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		"""
+		if style is None:
+			style = FigureStyle()
+
+		self._layout = layout
+		self._style = style
+		self._placements = list[Placement]()
+
+	@checked_arguments
+	def place(self, plot: Plot, cell: Cell) -> Self:
+		"""
+		Return a new Figure with a Plot placed on a cell, and on the cells it spans.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		plot
+			The Plot placed, which keeps its PlotStyle but takes the size of its cells.
+		cell
+			Its first cell, from row 0 and column 0, and the number of cells it spans.
+
+		Returns
+		-------
+		Self
+			A new Figure; this one is left unchanged.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		CellOutOfRangeError
+			When a cell covered is outside the Layout.
+		OccupiedCellError
+			When a cell covered already holds a Plot.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+		>>> plot = ndp.Plot.line(prices, style=ndp.PlotStyle(title="Prices"))
+		>>> figure = ndp.Figure(ndp.Layout(rows=1, columns=2))
+		>>> placed_figure = figure.place(plot, ndp.Cell(row=0, column=1))
+		>>> placed_figure.show()
+		"""
+		require_cell_inside(cell, self._layout)
+		require_free_cells(cell, self._placements)
+		placement = Placement(plot, cell)
+		figure_class = type(self)
+		placed_figure = figure_class(self._layout, self._style)
+		placed_figure._placements = [*self._placements, placement]
+
+		return placed_figure
+
+	def to_matplotlib(self) -> MatplotlibFigure:
+		"""
+		Return a new matplotlib figure of the Figure, to change it with matplotlib.
+
+		Each Plot is drawn on a matplotlib subfigure. Changing the figure never changes the Figure.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		matplotlib.figure.Figure
+			The figure, with one subfigure per Plot.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> plot = ndp.Plot.line(ndp.Array.from_list([12.0, 15.5]))
+		>>> figure = ndp.Figure(ndp.Layout(rows=2, columns=2)).place(plot, ndp.Cell(row=1, column=1))
+		>>> matplotlib_figure = figure.to_matplotlib()
+		>>> len(matplotlib_figure.subfigs), matplotlib_figure.get_size_inches().tolist()
+		(1, [9.6, 7.2])
+		"""
+		drawing = self._describe_drawing()
+		matplotlib_figure = build_figure(drawing)
+
+		return matplotlib_figure
+
+	@checked_arguments
+	def save(self, path: FilePath, options: ImageOptions | None = None, on_conflict: Conflict = Conflict.ERROR) -> None:
+		"""
+		Save the Figure 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.
+
+		.. 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()) / "shop.pdf"
+		>>> plot = ndp.Plot.line(ndp.Array.from_list([12.0, 15.5]))
+		>>> figure = ndp.Figure(ndp.Layout(rows=1, columns=2)).place(plot, ndp.Cell(row=0, column=0))
+		>>> figure.save(path)
+		>>> path.read_bytes()[:4]
+		b'%PDF'
+		"""
+		drawing = self._describe_drawing()
+		write_image(drawing, path, options, on_conflict)
+
+	def show(self) -> None:
+		"""
+		Show the Figure: 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 Figure instead.
+
+		.. versionadded:: 0.1.0
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+		>>> line_plot = ndp.Plot.line(prices, style=ndp.PlotStyle(title="Line"))
+		>>> bar_plot = ndp.Plot.bar(prices, style=ndp.PlotStyle(title="Bars"))
+		>>> figure = ndp.Figure(ndp.Layout(rows=1, columns=2), ndp.FigureStyle(title="Prices"))
+		>>> figure = figure.place(line_plot, ndp.Cell(row=0, column=0))
+		>>> figure = figure.place(bar_plot, ndp.Cell(row=0, column=1))
+		>>> figure.show()
+		"""
+		drawing = self._describe_drawing()
+		show_drawing(drawing, ShownObject.FIGURE)
+
+	def _draw_on(self, target: FigureBase) -> None:
+		"""
+		Draw the Figure on an empty matplotlib figure.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		target
+			The figure drawn on.
+		"""
+		draw_figure(target, self._layout, self._placements, self._style.title)
+
+	def _describe_drawing(self) -> FigureDrawing:
+		"""
+		Return what the Figure draws, and its size.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		FigureDrawing
+			The drawing of the Figure.
+		"""
+		size_inches = choose_figure_size(self._layout, self._style.size)
+		drawing = FigureDrawing(self._draw_on, size_inches)
+
+		return drawing

numdaplot/plots/figure/figure_drawing.py

@@ -0,0 +1,99 @@
+"""
+Drawing of a Figure: its title and the Plots in their cells.
+
+.. versionadded:: 0.1.0
+"""
+
+# The matplotlib stubs leave the keyword arguments of most drawing methods untyped.
+# pyright: reportUnknownMemberType=false
+
+from matplotlib.figure import FigureBase
+
+from numdaplot.plots.drawing.plot_theme import BACKGROUND_COLOR
+from numdaplot.plots.drawing.size_inches import convert_size_to_inches
+from numdaplot.plots.figure.layout import Layout
+from numdaplot.plots.figure.placement import Placement
+from numdaplot.plots.style.size import Size
+
+CELL_WIDTH = 4.8
+CELL_HEIGHT = 3.6
+
+
+def draw_figure(target: FigureBase, layout: Layout, placements: list[Placement], title: str | None) -> None:
+	"""
+	Draw the title of a Figure and each of its Plots on the cells it covers, the empty cells staying blank.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	target
+		An empty matplotlib figure.
+	layout
+		The grid of the Figure.
+	placements
+		The Plots and their cells.
+	title
+		The title above the grid, or None.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.figure.figure_drawing import draw_figure
+	>>> from numdaplot.plots.figure.placement import Placement
+	>>> plot = ndp.Plot.line(ndp.Array.from_list([12.0, 15.5]))
+	>>> figure = Figure()
+	>>> draw_figure(figure, ndp.Layout(rows=1, columns=2), [Placement(plot, ndp.Cell(row=0, column=1))], "Sales")
+	>>> len(figure.subfigs), figure.get_suptitle()
+	(1, 'Sales')
+	"""
+	target.set_facecolor(BACKGROUND_COLOR)
+	if title is not None:
+		target.suptitle(title)
+
+	cell_grid = target.add_gridspec(layout.rows, layout.columns)
+
+	for placement in placements:
+		cell = placement.cell
+		row_end = cell.row + cell.row_span
+		column_end = cell.column + cell.column_span
+		cell_area = cell_grid[cell.row : row_end, cell.column : column_end]
+		subfigure = target.add_subfigure(cell_area)
+		# A Figure draws its Plots with the drawing they use for themselves, which is not public.
+		placement.plot._draw_on(subfigure)  # pyright: ignore[reportPrivateUsage]
+
+
+def choose_figure_size(layout: Layout, size: Size | None) -> tuple[float, float]:
+	"""
+	Return the width and the height of a Figure in inches.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	layout
+		The grid of the Figure.
+	size
+		The size chosen, or None for 4.8 by 3.6 inches per cell.
+
+	Returns
+	-------
+	tuple[float, float]
+		The width and the height.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.figure.figure_drawing import choose_figure_size
+	>>> choose_figure_size(ndp.Layout(rows=2, columns=3), None)
+	(14.399999999999999, 7.2)
+	"""
+	if size is not None:
+		chosen_size = convert_size_to_inches(size)
+		return chosen_size
+
+	width = CELL_WIDTH * layout.columns
+	height = CELL_HEIGHT * layout.rows
+
+	return width, height

numdaplot/plots/figure/figure_style.py

@@ -0,0 +1,60 @@
+"""
+Look of a whole Figure.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.plots.style.size import Size
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class FigureStyle:
+	"""
+	Look of a whole Figure: its title and its size, used by ``Figure``.
+
+	The look of each Plot belongs to its ``PlotStyle``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	title
+		The title above the grid, no title when omitted.
+	size
+		The width and the height of the whole Figure, 4.8 by 3.6 inches per cell when omitted.
+
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> plot = ndp.Plot.line(prices)
+	>>> style = ndp.FigureStyle(title="Prices", size=ndp.Size(width=8, height=3))
+	>>> figure = ndp.Figure(ndp.Layout(rows=1, columns=1), style)
+	>>> figure = figure.place(plot, ndp.Cell(row=0, column=0))
+	>>> figure.show()
+	"""
+
+	title: str | None = None
+	size: Size | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check the type of every setting.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		"""
+		require_field_types(self)

numdaplot/plots/figure/layout.py

@@ -0,0 +1,71 @@
+"""
+Grid of cells of a Figure.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.invalid_count_error import InvalidCountError
+from numdaplot.settings.field_types import require_field_types
+
+MINIMUM_LINE_COUNT = 1
+
+
+@dataclass(frozen=True)
+class Layout:
+	"""
+	Grid of cells of a ``Figure``, each cell holding a Plot or left blank.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	rows
+		The number of rows of cells, at least 1.
+	columns
+		The number of columns of cells, at least 1.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidCountError
+		When ``rows`` or ``columns`` is lower than 1.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> line_plot = ndp.Plot.line(prices)
+	>>> bar_plot = ndp.Plot.bar(prices)
+	>>> layout = ndp.Layout(rows=2, columns=1)
+	>>> figure = ndp.Figure(layout)
+	>>> figure = figure.place(line_plot, ndp.Cell(row=0, column=0))
+	>>> figure = figure.place(bar_plot, ndp.Cell(row=1, column=0))
+	>>> figure.show()
+	"""
+
+	rows: int
+	columns: int
+
+	def __post_init__(self) -> None:
+		"""
+		Check the number of rows and of columns.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidCountError
+			When ``rows`` or ``columns`` is lower than 1.
+		"""
+		require_field_types(self)
+
+		if self.rows < MINIMUM_LINE_COUNT:
+			raise InvalidCountError(self.rows, MINIMUM_LINE_COUNT)
+
+		if self.columns < MINIMUM_LINE_COUNT:
+			raise InvalidCountError(self.columns, MINIMUM_LINE_COUNT)