numdaplot 0.1.0__py3-none-any.whl

numdaplot/plots/plot_series_creation.py

@@ -0,0 +1,213 @@
+"""
+Creation of a Plot of lines, bars or points, the charts ``add_*`` can also draw over a Plot.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Self
+
+from numdaplot.arrays.array import Array
+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.layer_reading import read_bar_layer, read_line_layer, read_scatter_layer
+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 PlotSeriesCreation(PlotData):
+	"""
+	Creation of a Plot of lines, bars or points.
+
+	Use ``ndp.Plot.line``, ``ndp.Plot.bar`` and ``ndp.Plot.scatter``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@classmethod
+	@checked_arguments
+	def line(cls, data: Table | Array, chart: LineChart | None = None, style: PlotStyle | None = None) -> Self:
+		"""
+		Return a Plot drawing columns of numbers or times of day as lines.
+
+		For a Table, ``LineChart.y`` names the columns drawn and ``LineChart.x`` the column of the positions. For an
+		Array of one or two dimensions, each column is a line and each row is placed at its number.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		data
+			The Table or the Array drawn.
+		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.
+		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 ``y`` columns, or an Array has ``x`` or ``y`` columns.
+		ColumnNotFoundError
+			When a column does not exist.
+		IncompatibleTypesError
+			When ``x`` holds booleans or durations, or a drawn column holds neither numbers nor times of day, or the
+			drawn columns mix them.
+		DimensionError
+			When an Array has more than two dimensions.
+		InvalidColorCountError
+			When the colors of the chart are not one per line.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> days = ndp.Array.from_list([1, 2, 3, 4, 5])
+		>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0, 16.0])
+		>>> costs = ndp.Array.from_list([8.0, 9.5, 9.0, None, 10.5])
+		>>> sales = ndp.Table.from_arrays({"day": days, "price": prices, "cost": costs})
+		>>> chart = ndp.LineChart(x="day", y=["price", "cost"], marker=ndp.MarkerShape.CIRCLE)
+		>>> style = ndp.PlotStyle(title="Sales", y_label="Euros")
+		>>> plot = ndp.Plot.line(sales, chart, style)
+		>>> plot.show()
+		"""
+		if chart is None:
+			chart = LineChart()
+
+		layer = read_line_layer(data, chart)
+		plot = cls._create_from_layer(layer, style)
+
+		return plot
+
+	@classmethod
+	@checked_arguments
+	def bar(cls, data: Table | Array, chart: BarChart | None = None, style: PlotStyle | None = None) -> Self:
+		"""
+		Return a Plot drawing columns of numbers as bars.
+
+		For a Table, ``BarChart.y`` names the columns drawn and ``BarChart.x`` the column labeling the bars. For an
+		Array of one or two dimensions, each column is a series of bars and each row is labeled with its number.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		data
+			The Table or the Array drawn.
+		chart
+			The columns drawn and the look of the bars.
+			The default ``BarChart`` 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 ``y`` columns, or an Array has ``x`` or ``y`` columns.
+		ColumnNotFoundError
+			When a column does not exist.
+		IncompatibleTypesError
+			When ``x`` holds booleans or durations, or a drawn column does not hold numbers.
+		DimensionError
+			When an Array has more than two dimensions.
+		InvalidColorCountError
+			When the colors of the chart are not one per series.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau", "Nice"])
+		>>> sales_2025 = ndp.Array.from_list([120.0, 80.0, 45.0, 60.0])
+		>>> sales_2026 = ndp.Array.from_list([150.0, 95.0, 40.0, 70.0])
+		>>> sales = ndp.Table.from_arrays({"city": cities, "2025": sales_2025, "2026": sales_2026})
+		>>> chart = ndp.BarChart(x="city", y=["2025", "2026"], layout=ndp.BarLayout.STACKED)
+		>>> style = ndp.PlotStyle(title="Sales per city", y_label="Thousands of euros")
+		>>> plot = ndp.Plot.bar(sales, chart, style)
+		>>> plot.show()
+		"""
+		if chart is None:
+			chart = BarChart()
+
+		layer = read_bar_layer(data, chart)
+		plot = cls._create_from_layer(layer, style)
+
+		return plot
+
+	@classmethod
+	@checked_arguments
+	def scatter(cls, data: Table | Array, chart: ScatterChart | None = None, style: PlotStyle | None = None) -> Self:
+		"""
+		Return a Plot drawing each row as a point.
+
+		For a Table, ``ScatterChart.y`` names the column of the vertical positions and ``ScatterChart.x`` the column of
+		the horizontal ones, and the points can be colored and sized by other columns. For an Array of one or two
+		dimensions, each column is a series of points and each row is placed at its number.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		data
+			The Table or the Array drawn.
+		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.
+		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 ``y`` column, or an Array has a column setting.
+		ColumnNotFoundError
+			When a column does not exist.
+		IncompatibleTypesError
+			When ``x`` holds booleans or durations, ``y`` holds neither numbers nor times of day, ``size_by`` does
+			not hold numbers, or ``color_by`` holds neither numbers, texts, booleans nor times of day.
+		DimensionError
+			When an Array has more than two dimensions.
+		InvalidColorCountError
+			When ``color`` is given for an Array of several columns.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> surfaces = ndp.Array.from_list([30.0, 45.0, 60.0, 80.0, 52.0, 38.0])
+		>>> prices = ndp.Array.from_list([150.0, 210.0, 260.0, 330.0, 190.0, 160.0])
+		>>> rooms = ndp.Array.from_list([1, 2, 3, 4, 3, 2])
+		>>> flats = ndp.Table.from_arrays({"surface": surfaces, "price": prices, "rooms": rooms})
+		>>> chart = ndp.ScatterChart(x="surface", y="price", color_by="rooms")
+		>>> style = ndp.PlotStyle(x_label="Surface (m2)", y_label="Price (thousands of euros)")
+		>>> plot = ndp.Plot.scatter(flats, chart, style)
+		>>> plot.show()
+		"""
+		if chart is None:
+			chart = ScatterChart()
+
+		layer = read_scatter_layer(data, chart)
+		plot = cls._create_from_layer(layer, style)
+
+		return plot

numdaplot/plots/style/__init__.py

@@ -0,0 +1,5 @@
+"""
+Look of a whole Plot: title, axis labels, legend, grid lines, size and colors.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/plots/style/axis_settings.py

@@ -0,0 +1,60 @@
+"""
+Check of the style of a chart without axes.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.refused_setting_error import RefusedSettingError
+from numdaplot.plots.style.plot_style import PlotStyle
+
+CHART_NAME = "PieChart"
+X_LABEL_SETTING = "x_label"
+Y_LABEL_SETTING = "y_label"
+RIGHT_LABEL_SETTING = "right_label"
+X_TICK_ROTATION_SETTING = "x_tick_rotation"
+Y_TICK_ROTATION_SETTING = "y_tick_rotation"
+
+
+def require_no_axis_settings(style: PlotStyle | None) -> None:
+	"""
+	Check that the style of a pie has no axis setting, a pie having no axes.
+
+	The grid lines and the legend keep their default values, so a pie leaves them without effect.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	style
+		The style given, or None.
+
+	Raises
+	------
+	RefusedSettingError
+		When the style has an ``x_label``, a ``y_label``, a ``right_label``, an ``x_tick_rotation`` or a
+		``y_tick_rotation``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.style.axis_settings import require_no_axis_settings
+	>>> try:
+	... 	require_no_axis_settings(ndp.PlotStyle(x_tick_rotation=45))
+	... except ndp.RefusedSettingError as error:
+	... 	print(error)
+	PieChart does not accept x_tick_rotation.
+	"""
+	if style is None:
+		return
+
+	axis_settings = [
+		(X_LABEL_SETTING, style.x_label),
+		(Y_LABEL_SETTING, style.y_label),
+		(RIGHT_LABEL_SETTING, style.right_label),
+		(X_TICK_ROTATION_SETTING, style.x_tick_rotation),
+		(Y_TICK_ROTATION_SETTING, style.y_tick_rotation),
+	]
+
+	for setting_name, setting_value in axis_settings:
+		if setting_value is not None:
+			raise RefusedSettingError(setting_name, CHART_NAME)

numdaplot/plots/style/color.py

@@ -0,0 +1,168 @@
+"""
+Named colors of the series of a chart.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class Color(Enum):
+	"""
+	Named colors of the series of a chart: the ten colors of the default cycle, then black.
+
+	Write any other color with ``CustomColor``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> chart = ndp.LineChart(colors=[ndp.Color.GREEN])
+	>>> plot = ndp.Plot.line(prices, chart)
+	>>> plot.show()
+	"""
+
+	BLUE = auto()
+	"""
+	Blue, ``#1f77b4``, the first color of the default cycle.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> chart = ndp.LineChart(colors=[ndp.Color.BLUE])
+	>>> plot = ndp.Plot.line(prices, chart)
+	>>> plot.show()
+	"""
+
+	ORANGE = auto()
+	"""
+	Orange, ``#ff7f0e``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> chart = ndp.LineChart(colors=[ndp.Color.ORANGE])
+	>>> plot = ndp.Plot.line(prices, chart)
+	>>> plot.show()
+	"""
+
+	GREEN = auto()
+	"""
+	Green, ``#2ca02c``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> chart = ndp.LineChart(colors=[ndp.Color.GREEN])
+	>>> plot = ndp.Plot.line(prices, chart)
+	>>> plot.show()
+	"""
+
+	RED = auto()
+	"""
+	Red, ``#d62728``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> chart = ndp.LineChart(colors=[ndp.Color.RED])
+	>>> plot = ndp.Plot.line(prices, chart)
+	>>> plot.show()
+	"""
+
+	PURPLE = auto()
+	"""
+	Purple, ``#9467bd``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> chart = ndp.LineChart(colors=[ndp.Color.PURPLE])
+	>>> plot = ndp.Plot.line(prices, chart)
+	>>> plot.show()
+	"""
+
+	BROWN = auto()
+	"""
+	Brown, ``#8c564b``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> chart = ndp.LineChart(colors=[ndp.Color.BROWN])
+	>>> plot = ndp.Plot.line(prices, chart)
+	>>> plot.show()
+	"""
+
+	PINK = auto()
+	"""
+	Pink, ``#e377c2``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> chart = ndp.LineChart(colors=[ndp.Color.PINK])
+	>>> plot = ndp.Plot.line(prices, chart)
+	>>> plot.show()
+	"""
+
+	GRAY = auto()
+	"""
+	Gray, ``#7f7f7f``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> chart = ndp.LineChart(colors=[ndp.Color.GRAY])
+	>>> plot = ndp.Plot.line(prices, chart)
+	>>> plot.show()
+	"""
+
+	OLIVE = auto()
+	"""
+	Olive, ``#bcbd22``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> chart = ndp.LineChart(colors=[ndp.Color.OLIVE])
+	>>> plot = ndp.Plot.line(prices, chart)
+	>>> plot.show()
+	"""
+
+	CYAN = auto()
+	"""
+	Cyan, ``#17becf``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> chart = ndp.LineChart(colors=[ndp.Color.CYAN])
+	>>> plot = ndp.Plot.line(prices, chart)
+	>>> plot.show()
+	"""
+
+	BLACK = auto()
+	"""
+	Black, ``#000000``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> chart = ndp.LineChart(colors=[ndp.Color.BLACK])
+	>>> plot = ndp.Plot.line(prices, chart)
+	>>> plot.show()
+	"""

numdaplot/plots/style/custom_color.py

@@ -0,0 +1,65 @@
+"""
+A color of a chart written as ``#rrggbb``.
+
+.. versionadded:: 0.1.0
+"""
+
+import re
+from dataclasses import dataclass
+
+from numdaplot.errors.invalid_color_error import InvalidColorError
+from numdaplot.settings.field_types import require_field_types
+
+COLOR_PATTERN = re.compile(r"#[0-9a-fA-F]{6}")
+
+
+@dataclass(frozen=True)
+class CustomColor:
+	"""
+	A color of a chart written as ``#`` followed by its red, green and blue parts in hexadecimal.
+
+	Accepted wherever a ``Color`` is, for the colors the named ones do not cover.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	code
+		The color, such as ``"#ff8800"`` for orange, in lowercase or uppercase.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidColorError
+		When the code is not ``#`` followed by six hexadecimal digits.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> chart = ndp.LineChart(colors=[ndp.CustomColor("#ff8800")])
+	>>> plot = ndp.Plot.line(prices, chart)
+	>>> plot.show()
+	"""
+
+	code: str
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the code is ``#`` followed by six hexadecimal digits.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidColorError
+			When the code is not ``#`` followed by six hexadecimal digits.
+		"""
+		require_field_types(self)
+
+		code_match = COLOR_PATTERN.fullmatch(self.code)
+		if code_match is None:
+			raise InvalidColorError(self.code)

numdaplot/plots/style/grid_lines.py

@@ -0,0 +1,49 @@
+"""
+Whether a Plot draws grid lines behind its values.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class GridLines(Enum):
+	"""
+	Whether a Plot draws light grid lines behind its values, used by ``PlotStyle``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> style = ndp.PlotStyle(grid_lines=ndp.GridLines.HIDDEN)
+	>>> plot = ndp.Plot.line(prices, style=style)
+	>>> plot.show()
+	"""
+
+	SHOWN = auto()
+	"""
+	Light grid lines at each tick of the axes. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> style = ndp.PlotStyle(grid_lines=ndp.GridLines.SHOWN)
+	>>> plot = ndp.Plot.line(prices, style=style)
+	>>> plot.show()
+	"""
+
+	HIDDEN = auto()
+	"""
+	No grid lines.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> style = ndp.PlotStyle(grid_lines=ndp.GridLines.HIDDEN)
+	>>> plot = ndp.Plot.line(prices, style=style)
+	>>> plot.show()
+	"""

numdaplot/plots/style/image_options.py

@@ -0,0 +1,71 @@
+"""
+Settings of a PNG image of a Plot.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.invalid_resolution_error import InvalidResolutionError
+from numdaplot.settings.field_types import require_field_types
+
+DEFAULT_DPI = 100
+MINIMUM_DPI = 1
+
+
+@dataclass(frozen=True)
+class ImageOptions:
+	"""
+	Settings of a PNG image of a Plot, used by ``Plot.save``.
+
+	The format of an image always comes from the extension of its path. SVG and PDF images are drawn with
+	lines and texts, so they have no resolution and refuse these options.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	dpi
+		The number of pixels per inch of the image, 100 by default. It only changes the sharpness: a Plot of
+		6.4 by 4.8 inches gives 640 by 480 pixels at 100, and 1280 by 960 pixels at 200.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidResolutionError
+		When ``dpi`` is lower than 1.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> from matplotlib.image import imread
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "prices.png"
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> plot = ndp.Plot.line(prices)
+	>>> plot.save(path, ndp.ImageOptions(dpi=200))
+	>>> imread(path).shape
+	(960, 1280, 4)
+	"""
+
+	dpi: int = DEFAULT_DPI
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the resolution is at least 1 dot per inch.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidResolutionError
+			When ``dpi`` is lower than 1.
+		"""
+		require_field_types(self)
+
+		if self.dpi < MINIMUM_DPI:
+			raise InvalidResolutionError(self.dpi)