numdaplot 0.1.0__py3-none-any.whl

numdaplot/plots/charts/bar_chart.py

@@ -0,0 +1,98 @@
+"""
+Chart drawing each value as a bar.
+
+.. versionadded:: 0.1.0
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from numdaplot.plots.charts.bar_layout import BarLayout
+from numdaplot.plots.charts.chart import Chart
+from numdaplot.plots.charts.chart_settings import copy_colors, copy_columns
+from numdaplot.plots.charts.orientation import Orientation
+from numdaplot.plots.style.color import Color
+from numdaplot.plots.style.custom_color import CustomColor
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.columns.column_names import require_optional_column_name
+
+
+@dataclass(frozen=True)
+class BarChart(Chart):
+	"""
+	Chart drawing each value as a bar, used by ``Plot.bar``.
+
+	Each ``x`` value gets its own position, labeled with that value, in the order of the rows. A missing value
+	draws no bar, and a row whose ``x`` text is missing is left out.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	x
+		For a Table, the column labeling the bars: numbers, dates, datetimes, times of day (labeled ``HH:MM``), texts
+		or booleans, the row numbers when omitted. An Array takes none, its rows being numbered.
+	y
+		For a Table, the columns drawn, holding numbers, one series of bars each. A Table needs it, even for a single
+		column. An Array takes none: when omitted, each of its columns is a series.
+	orientation
+		The direction of the bars, ``Orientation.VERTICAL`` by default.
+	layout
+		How the bars of several series share a position, ``BarLayout.GROUPED`` by default.
+	colors
+		One color per series, the colors of the default cycle when omitted. The chart keeps its own list.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidColumnNameError
+		When ``x`` or a name in ``y`` is an empty text.
+	EmptyListError
+		When ``y`` or ``colors`` is an empty list.
+	DuplicateColumnError
+		When a column name appears twice in ``y``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau"])
+	>>> sales_2025 = ndp.Array.from_list([120.0, 80.0, 45.0])
+	>>> sales_2026 = ndp.Array.from_list([150.0, 95.0, 40.0])
+	>>> sales = ndp.Table.from_arrays({"city": cities, "2025": sales_2025, "2026": sales_2026})
+	>>> chart = ndp.BarChart(x="city", y=["2025", "2026"])
+	>>> plot = ndp.Plot.bar(sales, chart)
+	>>> plot.show()
+	"""
+
+	x: str | None = None
+	y: list[str] | None = None
+	orientation: Orientation = Orientation.VERTICAL
+	layout: BarLayout = BarLayout.GROUPED
+	colors: Sequence[Color | CustomColor] | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check the columns and the colors and replace them with copies that only the chart holds.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidColumnNameError
+			When ``x`` or a name in ``y`` is an empty text.
+		EmptyListError
+			When ``y`` or ``colors`` is an empty list.
+		DuplicateColumnError
+			When a column name appears twice in ``y``.
+		"""
+		require_field_types(self)
+
+		require_optional_column_name(self.x)
+
+		columns_copy = copy_columns(self.y)
+		colors_copy = copy_colors(self.colors)
+		object.__setattr__(self, "y", columns_copy)
+		object.__setattr__(self, "colors", colors_copy)

numdaplot/plots/charts/bar_layout.py

@@ -0,0 +1,58 @@
+"""
+How the bars of several series share a position of a BarChart.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class BarLayout(Enum):
+	"""
+	How the bars of several series share a position of a ``BarChart``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> days = ndp.Array.from_list([1, 2, 3, 4])
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> costs = ndp.Array.from_list([8.0, 9.5, 9.0, 10.0])
+	>>> sales = ndp.Table.from_arrays({"day": days, "price": prices, "cost": costs})
+	>>> chart = ndp.BarChart(x="day", y=["price", "cost"], layout=ndp.BarLayout.STACKED)
+	>>> plot = ndp.Plot.bar(sales, chart)
+	>>> plot.show()
+	"""
+
+	GROUPED = auto()
+	"""
+	Side by side. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> days = ndp.Array.from_list([1, 2, 3, 4])
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> costs = ndp.Array.from_list([8.0, 9.5, 9.0, 10.0])
+	>>> sales = ndp.Table.from_arrays({"day": days, "price": prices, "cost": costs})
+	>>> chart = ndp.BarChart(x="day", y=["price", "cost"], layout=ndp.BarLayout.GROUPED)
+	>>> plot = ndp.Plot.bar(sales, chart)
+	>>> plot.show()
+	"""
+
+	STACKED = auto()
+	"""
+	On top of each other, positive values above zero and negative values below it.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> days = ndp.Array.from_list([1, 2, 3, 4])
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> costs = ndp.Array.from_list([8.0, 9.5, 9.0, 10.0])
+	>>> sales = ndp.Table.from_arrays({"day": days, "price": prices, "cost": costs})
+	>>> chart = ndp.BarChart(x="day", y=["price", "cost"], layout=ndp.BarLayout.STACKED)
+	>>> plot = ndp.Plot.bar(sales, chart)
+	>>> plot.show()
+	"""

numdaplot/plots/charts/bin_count.py

@@ -0,0 +1,61 @@
+"""
+Bins of a histogram given by their number.
+
+.. 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_BIN_COUNT = 1
+
+
+@dataclass(frozen=True)
+class BinCount:
+	"""
+	Bins of a ``HistogramChart`` given by their number, of the same width from the smallest to the largest value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	count
+		The number of bins, at least 1.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidCountError
+		When the count is lower than 1.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0, 13.5, 16.0, 14.5, 15.0])
+	>>> chart = ndp.HistogramChart(bins=ndp.BinCount(4))
+	>>> plot = ndp.Plot.histogram(prices, chart)
+	>>> plot.show()
+	"""
+
+	count: int
+
+	def __post_init__(self) -> None:
+		"""
+		Check the number of bins.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidCountError
+			When the count is lower than 1.
+		"""
+		require_field_types(self)
+
+		if self.count < MINIMUM_BIN_COUNT:
+			raise InvalidCountError(self.count, MINIMUM_BIN_COUNT)

numdaplot/plots/charts/bin_width.py

@@ -0,0 +1,78 @@
+"""
+Bins of a histogram given by their width.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+from datetime import timedelta
+
+from numdaplot.errors.invalid_bin_width_error import InvalidBinWidthError
+from numdaplot.settings.field_types import require_field_types
+
+NO_DURATION = timedelta(0)
+LONGEST_DURATION = timedelta(days=1)
+
+
+@dataclass(frozen=True)
+class BinWidth:
+	"""
+	Bins of a ``HistogramChart`` given by their width, their bounds being multiples of it.
+
+	With a width of 5, the bins are 10 to 15, 15 to 20 and so on, whatever the smallest value. Times of day take
+	a duration: with ``timedelta(minutes=30)``, the bins are 08:00 to 08:30, 08:30 to 09:00 and so on.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	width
+		The width of each bin: a number above 0 for numbers, a duration above 0 and of at most a day for times of
+		day.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidBinWidthError
+		When the width is 0 or negative, or a duration beyond a day.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0, 13.5, 16.0, 14.5, 21.0])
+	>>> chart = ndp.HistogramChart(bins=ndp.BinWidth(2.5))
+	>>> plot = ndp.Plot.histogram(prices, chart)
+	>>> plot.show()
+	>>> from datetime import time, timedelta
+	>>> hours = ndp.Array.from_list([time(8, 10), time(8, 40), time(9, 5), time(17, 50)])
+	>>> half_hours = ndp.HistogramChart(bins=ndp.BinWidth(timedelta(minutes=30)))
+	>>> ndp.Plot.histogram(hours, half_hours).show()
+	"""
+
+	width: float | timedelta
+
+	def __post_init__(self) -> None:
+		"""
+		Check the width of the bins.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidBinWidthError
+			When the width is 0 or negative, or a duration beyond a day.
+		"""
+		require_field_types(self)
+
+		if isinstance(self.width, timedelta):
+			is_outside_day = self.width <= NO_DURATION or self.width > LONGEST_DURATION
+			if is_outside_day:
+				raise InvalidBinWidthError(self.width)
+
+			return
+
+		if self.width <= 0:
+			raise InvalidBinWidthError(self.width)

numdaplot/plots/charts/box_chart.py

@@ -0,0 +1,97 @@
+"""
+Chart summing up the spread of values as boxes.
+
+.. versionadded:: 0.1.0
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from numdaplot.plots.charts.chart import Chart
+from numdaplot.plots.charts.chart_settings import copy_colors, copy_columns
+from numdaplot.plots.charts.outliers import Outliers
+from numdaplot.plots.style.color import Color
+from numdaplot.plots.style.custom_color import CustomColor
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.columns.column_names import require_optional_column_name
+
+
+@dataclass(frozen=True)
+class BoxChart(Chart):
+	"""
+	Chart summing up the spread of the values of each column as a box, used by ``Plot.box``.
+
+	The box goes from the first to the third quartile, with a line at the median. The whiskers reach the
+	furthest values within 1.5 box heights of the box, and the values beyond them are outliers. Missing values
+	are left out.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	columns
+		For a Table, the columns drawn, holding numbers or times of day, not both. A Table needs it, even for a
+		single column. An Array takes none: when omitted, each of its columns is drawn. Times of day are measured on
+		an axis labeled ``HH:MM``.
+	group_by
+		For a Table, a column of texts, categories, booleans or times of day (written ``HH:MM``) splitting the rows into
+		groups, each drawn at its own position in alphabetical order, with the boxes of the columns side by side. A row
+		whose group is missing is left out. One box per column when omitted.
+	outliers
+		Whether the outliers are drawn, ``Outliers.SHOWN`` by default.
+	colors
+		One color per column, the colors of the default cycle when omitted. The chart keeps its own list.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidColumnNameError
+		When ``group_by`` or a name in ``columns`` is an empty text.
+	EmptyListError
+		When ``columns`` or ``colors`` is an empty list.
+	DuplicateColumnError
+		When a column name appears twice in ``columns``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Paris", "Lyon", "Paris", "Lyon", "Paris", "Lyon"])
+	>>> prices_2025 = ndp.Array.from_list([12.0, 9.5, 14.0, 10.0, 13.5, 8.0, 15.0, 11.0])
+	>>> prices_2026 = ndp.Array.from_list([14.0, 10.5, 16.0, 11.0, 15.5, 9.0, 17.0, 12.5])
+	>>> prices = ndp.Table.from_arrays({"city": cities, "2025": prices_2025, "2026": prices_2026})
+	>>> chart = ndp.BoxChart(columns=["2025", "2026"], group_by="city")
+	>>> plot = ndp.Plot.box(prices, chart)
+	>>> plot.show()
+	"""
+
+	columns: list[str] | None = None
+	group_by: str | None = None
+	outliers: Outliers = Outliers.SHOWN
+	colors: Sequence[Color | CustomColor] | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check the columns and the colors and replace them with copies that only the chart holds.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidColumnNameError
+			When ``group_by`` or a name in ``columns`` is an empty text.
+		EmptyListError
+			When ``columns`` or ``colors`` is an empty list.
+		DuplicateColumnError
+			When a column name appears twice in ``columns``.
+		"""
+		require_field_types(self)
+
+		require_optional_column_name(self.group_by)
+
+		columns_copy = copy_columns(self.columns)
+		colors_copy = copy_colors(self.colors)
+		object.__setattr__(self, "columns", columns_copy)
+		object.__setattr__(self, "colors", colors_copy)

numdaplot/plots/charts/cell_values.py

@@ -0,0 +1,61 @@
+"""
+Whether the cells of a HeatmapChart show their value.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class CellValues(Enum):
+	"""
+	Whether the cells of a ``HeatmapChart`` show their value.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau"])
+	>>> january = ndp.Array.from_list([5.5, 3.0, 8.0])
+	>>> february = ndp.Array.from_list([6.0, 4.5, 9.0])
+	>>> march = ndp.Array.from_list([9.5, 8.0, 11.5])
+	>>> temperatures = ndp.Table.from_arrays({"city": cities, "jan": january, "feb": february, "mar": march})
+	>>> chart = ndp.HeatmapChart(columns=["jan", "feb", "mar"], labels="city", values=ndp.CellValues.SHOWN)
+	>>> plot = ndp.Plot.heatmap(temperatures, chart)
+	>>> plot.show()
+	"""
+
+	SHOWN = auto()
+	"""
+	Each cell shows its value with at most two decimals, in black or white to stay readable.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau"])
+	>>> january = ndp.Array.from_list([5.5, 3.0, 8.0])
+	>>> february = ndp.Array.from_list([6.0, 4.5, 9.0])
+	>>> march = ndp.Array.from_list([9.5, 8.0, 11.5])
+	>>> temperatures = ndp.Table.from_arrays({"city": cities, "jan": january, "feb": february, "mar": march})
+	>>> chart = ndp.HeatmapChart(columns=["jan", "feb", "mar"], labels="city", values=ndp.CellValues.SHOWN)
+	>>> plot = ndp.Plot.heatmap(temperatures, chart)
+	>>> plot.show()
+	"""
+
+	HIDDEN = auto()
+	"""
+	The cells only show their color. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau"])
+	>>> january = ndp.Array.from_list([5.5, 3.0, 8.0])
+	>>> february = ndp.Array.from_list([6.0, 4.5, 9.0])
+	>>> march = ndp.Array.from_list([9.5, 8.0, 11.5])
+	>>> temperatures = ndp.Table.from_arrays({"city": cities, "jan": january, "feb": february, "mar": march})
+	>>> chart = ndp.HeatmapChart(columns=["jan", "feb", "mar"], labels="city", values=ndp.CellValues.HIDDEN)
+	>>> plot = ndp.Plot.heatmap(temperatures, chart)
+	>>> plot.show()
+	"""

numdaplot/plots/charts/chart.py

@@ -0,0 +1,59 @@
+"""
+Base class of every chart.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+
+CONSTRUCTOR_OPERATION = "Creating a Chart with ndp.Chart()"
+CONSTRUCTOR_ALTERNATIVE = "a chart such as ndp.LineChart"
+
+
+class Chart:
+	"""
+	Base class of every chart, which says what a Plot draws and how its series look.
+
+	A chart is immutable and checks its settings when it is created.
+
+	Only its subclasses are created: calling ``ndp.Chart()`` raises ``RefusedOperationError``.
+
+	Every chart, each passed to its own creation method of ``Plot``:
+
+	|Chart|What it draws|Example|
+	|---|---|---|
+	|``LineChart``|Each series as a line, with ``Plot.line``|``ndp.LineChart(x="month", y=["sales"])``|
+	|``BarChart``|Each value as a bar, with ``Plot.bar``|``ndp.BarChart(x="city", y=["sales"])``|
+	|``ScatterChart``|Each row as a point, with ``Plot.scatter``|``ndp.ScatterChart(x="price", y="stock")``|
+	|``HistogramChart``|The values per bin, with ``Plot.histogram``|``ndp.HistogramChart(columns=["price"])``|
+	|``BoxChart``|The spread of each column as a box, with ``Plot.box``|``ndp.BoxChart(columns=["price"])``|
+	|``PieChart``|Each row as a slice of a pie, with ``Plot.pie``|``ndp.PieChart(labels="city", values="sales")``|
+	|``HeatmapChart``|Each value as a colored cell, with ``Plot.heatmap``|``ndp.HeatmapChart()``|
+	|``MissingChart``|The missing values per column, with ``Plot.missing_by_column``|``ndp.MissingChart()``|
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> bar_plot = ndp.Plot.bar(prices, ndp.BarChart(orientation=ndp.Orientation.HORIZONTAL))
+	>>> bar_plot.show()
+	>>> line_plot = ndp.Plot.line(prices, ndp.LineChart(marker=ndp.MarkerShape.CIRCLE))
+	>>> line_plot.show()
+	"""
+
+	def __init__(self) -> None:
+		"""
+		Refuse the creation of the base class itself, and let a subclass be created.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		RefusedOperationError
+			When the created object is a Chart and not one of its subclasses.
+		"""
+		created_class = type(self)
+		if created_class is Chart:
+			raise RefusedOperationError(CONSTRUCTOR_OPERATION, CONSTRUCTOR_ALTERNATIVE)

numdaplot/plots/charts/chart_settings.py

@@ -0,0 +1,105 @@
+"""
+Checks shared by the column and color settings of the charts.
+
+.. versionadded:: 0.1.0
+"""
+
+from collections.abc import Sequence
+
+from numdaplot.errors.empty_list_error import EmptyListError
+from numdaplot.plots.style.color import Color
+from numdaplot.plots.style.custom_color import CustomColor
+from numdaplot.tables.columns.column_names import require_column_names
+
+COLUMN_ITEM_NAME = "column"
+COLOR_ITEM_NAME = "color"
+
+
+def copy_columns(columns: list[str] | None) -> list[str] | None:
+	"""
+	Check the names of the columns a chart draws and return a copy that only the chart holds.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	columns
+		The names of the columns, or None for an Array.
+
+	Returns
+	-------
+	list[str] or None
+		A copy of the names, or None.
+
+	Raises
+	------
+	EmptyListError
+		When the list is empty.
+	InvalidColumnNameError
+		When a column name is an empty text.
+	DuplicateColumnError
+		When a name appears twice.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.charts.chart_settings import copy_columns
+	>>> try:
+	... 	copy_columns(["price", "price"])
+	... except ndp.DuplicateColumnError as error:
+	... 	print(error)
+	The column name 'price' appears more than once.
+	"""
+	if columns is None:
+		return None
+
+	if columns == []:
+		raise EmptyListError(COLUMN_ITEM_NAME)
+
+	require_column_names(columns)
+	columns_copy = list(columns)
+
+	return columns_copy
+
+
+def copy_colors(colors: Sequence[Color | CustomColor] | None) -> list[Color | CustomColor] | None:
+	"""
+	Check the colors of the series of a chart and return a copy that only the chart holds.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	colors
+		One color per series, in a list or another sequence, or None for the colors of the default cycle.
+
+	Returns
+	-------
+	list[Color | CustomColor] or None
+		A copy of the colors, or None.
+
+	Raises
+	------
+	EmptyListError
+		When the list is empty.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.charts.chart_settings import copy_colors
+	>>> try:
+	... 	copy_colors([])
+	... except ndp.EmptyListError as error:
+	... 	print(error)
+	Expected at least one color, got an empty list.
+	"""
+	if colors is None:
+		return None
+
+	color_count = len(colors)
+	if color_count == 0:
+		raise EmptyListError(COLOR_ITEM_NAME)
+
+	colors_copy = list(colors)
+
+	return colors_copy