numdaplot 0.1.0__py3-none-any.whl

numdaplot/plots/style/legend_position.py

@@ -0,0 +1,149 @@
+"""
+Where the legend of a Plot is placed.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class LegendPosition(Enum):
+	"""
+	Where the legend of a Plot is placed, used by ``PlotStyle``.
+
+	The legend names the series, and is only drawn when a chart has several of them.
+
+	.. 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.LineChart(x="day", y=["price", "cost"])
+	>>> style = ndp.PlotStyle(legend=ndp.LegendPosition.UPPER_LEFT)
+	>>> plot = ndp.Plot.line(sales, chart, style)
+	>>> plot.show()
+	"""
+
+	BEST = auto()
+	"""
+	Inside the axes, where it hides the fewest values. With an axis on the right, the values of both axes leave little
+	room inside: the legend is placed as with ``OUTSIDE_RIGHT``. 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.LineChart(x="day", y=["price", "cost"])
+	>>> style = ndp.PlotStyle(legend=ndp.LegendPosition.BEST)
+	>>> plot = ndp.Plot.line(sales, chart, style)
+	>>> plot.show()
+	"""
+
+	UPPER_LEFT = auto()
+	"""
+	Inside the axes, in the upper left corner.
+
+	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.LineChart(x="day", y=["price", "cost"])
+	>>> style = ndp.PlotStyle(legend=ndp.LegendPosition.UPPER_LEFT)
+	>>> plot = ndp.Plot.line(sales, chart, style)
+	>>> plot.show()
+	"""
+
+	UPPER_RIGHT = auto()
+	"""
+	Inside the axes, in the upper right corner.
+
+	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.LineChart(x="day", y=["price", "cost"])
+	>>> style = ndp.PlotStyle(legend=ndp.LegendPosition.UPPER_RIGHT)
+	>>> plot = ndp.Plot.line(sales, chart, style)
+	>>> plot.show()
+	"""
+
+	LOWER_LEFT = auto()
+	"""
+	Inside the axes, in the lower left corner.
+
+	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.LineChart(x="day", y=["price", "cost"])
+	>>> style = ndp.PlotStyle(legend=ndp.LegendPosition.LOWER_LEFT)
+	>>> plot = ndp.Plot.line(sales, chart, style)
+	>>> plot.show()
+	"""
+
+	LOWER_RIGHT = auto()
+	"""
+	Inside the axes, in the lower right corner.
+
+	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.LineChart(x="day", y=["price", "cost"])
+	>>> style = ndp.PlotStyle(legend=ndp.LegendPosition.LOWER_RIGHT)
+	>>> plot = ndp.Plot.line(sales, chart, style)
+	>>> plot.show()
+	"""
+
+	OUTSIDE_RIGHT = auto()
+	"""
+	Outside the axes, on their right and past an axis on the right if any, so it never hides a 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.LineChart(x="day", y=["price", "cost"])
+	>>> style = ndp.PlotStyle(legend=ndp.LegendPosition.OUTSIDE_RIGHT)
+	>>> plot = ndp.Plot.line(sales, chart, style)
+	>>> plot.show()
+	"""
+
+	HIDDEN = auto()
+	"""
+	No legend.
+
+	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.LineChart(x="day", y=["price", "cost"])
+	>>> style = ndp.PlotStyle(legend=ndp.LegendPosition.HIDDEN)
+	>>> plot = ndp.Plot.line(sales, chart, style)
+	>>> plot.show()
+	"""

numdaplot/plots/style/plot_style.py

@@ -0,0 +1,136 @@
+"""
+Look of a whole Plot.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.invalid_rotation_error import InvalidRotationError
+from numdaplot.plots.style.grid_lines import GridLines
+from numdaplot.plots.style.legend_position import LegendPosition
+from numdaplot.plots.style.size import Size
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.columns.renaming import Renaming
+
+MINIMUM_ROTATION = -90
+MAXIMUM_ROTATION = 90
+
+
+@dataclass(frozen=True)
+class PlotStyle:
+	"""
+	Look of a whole Plot: title, axis labels, rotation of the values, legend, grid lines and size.
+
+	The look of the series, such as their colors, belongs to the chart drawing them.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	title
+		The title above the axes: when omitted, the ``y`` label by the ``x`` label such as ``sales by month``, and for a
+		map of missing values ``Map of missing values``. An empty text draws no title.
+	x_label
+		The label of the axis of the ``x`` values: when omitted, the name of the ``x`` column, else ``Row``, or
+		``Column`` for a box or a heatmap without group. An empty text draws no label.
+	y_label
+		The label of the axis of the ``y`` values: when omitted, the names of the ``y`` columns one after the other, the
+		first 3 and the number of the others beyond 3, or ``Value`` for an Array. An empty text draws no label.
+	right_label
+		The label of the axis on the right, drawn when a chart is added with ``ValueAxis.RIGHT``: when omitted, written
+		as ``y_label`` for the first chart on the right. An empty text draws no label. It has no effect while no chart
+		is on the right.
+	x_tick_rotation
+		The angle of the labels of the ``x`` values, in degrees from -90 to 90. When omitted, 45 degrees for texts,
+		dates, datetimes and numbers without enough room, and no rotation for other numbers and for the texts on the
+		left of horizontal bars. Labels without enough room at this angle are left out, one out of as many as needed
+		from the first one, with a ``ReadabilityWarning`` when they may be texts.
+	y_tick_rotation
+		The angle of the labels of the ``y`` values, in degrees from -90 to 90, no rotation when omitted. The values of
+		the axis on the right keep no rotation. Labels without enough room are left out as for ``x_tick_rotation``.
+	legend
+		Where the legend is placed, ``LegendPosition.BEST`` by default, past the axes for a map of missing values. It is
+		only drawn for several series, so never on a pie or a heatmap. It names each series after its column, or after
+		the name ``renaming`` gives it.
+	grid_lines
+		Whether light grid lines are drawn behind the values, ``GridLines.SHOWN`` by default. A pie and a heatmap have
+		none.
+	size
+		The width and the height, 6.4 by 4.8 inches by default. A Plot placed in a ``Figure`` takes the size of
+		its cells instead.
+	renaming
+		The names under which some columns are shown, every column under its own name when omitted. Each
+		``NameChange`` applies to the legend, the labels of boxes, heatmaps and missing value charts, the legends of
+		``color_by`` and ``size_by``, and the default title and axis labels, on every chart of the Plot. The columns
+		of an Array are named ``"0"``, ``"1"``... The values themselves, such as the parts of a pie, are never
+		renamed. A title or a label given here keeps its text.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidRotationError
+		When ``x_tick_rotation`` or ``y_tick_rotation`` is outside -90 to 90 degrees.
+
+	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.LineChart(x="day", y=["price", "cost"])
+	>>> style = ndp.PlotStyle(title="Sales", x_label="Day", y_label="Euros", legend=ndp.LegendPosition.OUTSIDE_RIGHT)
+	>>> plot = ndp.Plot.line(sales, chart, style)
+	>>> plot.show()
+
+	The labels of the ``x`` values can take another angle.
+
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Marseille"])
+	>>> totals = ndp.Array.from_list([120.0, 80.0, 95.0])
+	>>> city_sales = ndp.Table.from_arrays({"city": cities, "total": totals})
+	>>> city_chart = ndp.BarChart(x="city", y=["total"])
+	>>> city_plot = ndp.Plot.bar(city_sales, city_chart, ndp.PlotStyle(x_tick_rotation=90))
+	>>> city_plot.show()
+
+	The columns can be shown under other names, without renaming them in the Table.
+
+	>>> shown_names = ndp.Renaming(changes=[ndp.NameChange(old_name="total", new_name="Total sales")])
+	>>> named_plot = ndp.Plot.bar(city_sales, city_chart, ndp.PlotStyle(renaming=shown_names))
+	>>> named_plot.show()
+	"""
+
+	title: str | None = None
+	x_label: str | None = None
+	y_label: str | None = None
+	right_label: str | None = None
+	x_tick_rotation: float | None = None
+	y_tick_rotation: float | None = None
+	legend: LegendPosition = LegendPosition.BEST
+	grid_lines: GridLines = GridLines.SHOWN
+	size: Size = Size()
+	renaming: Renaming | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check the rotations of the labels of the values.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidRotationError
+			When ``x_tick_rotation`` or ``y_tick_rotation`` is outside -90 to 90 degrees.
+		"""
+		require_field_types(self)
+
+		for rotation in (self.x_tick_rotation, self.y_tick_rotation):
+			if rotation is None:
+				continue
+
+			is_accepted = MINIMUM_ROTATION <= rotation <= MAXIMUM_ROTATION
+			if not is_accepted:
+				raise InvalidRotationError(rotation)

numdaplot/plots/style/size.py

@@ -0,0 +1,70 @@
+"""
+Width and height of a Plot.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.invalid_size_error import InvalidSizeError
+from numdaplot.plots.style.size_unit import SizeUnit
+from numdaplot.settings.field_types import require_field_types
+
+DEFAULT_WIDTH = 6.4
+DEFAULT_HEIGHT = 4.8
+
+
+@dataclass(frozen=True)
+class Size:
+	"""
+	Width and height of a Plot, used by ``PlotStyle``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	width
+		The width, 6.4 inches by default.
+	height
+		The height, 4.8 inches by default.
+	unit
+		The unit of the width and the height, ``SizeUnit.INCH`` by default.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidSizeError
+		When the width or the height is zero or negative.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> style = ndp.PlotStyle(size=ndp.Size(width=6, height=2.5))
+	>>> plot = ndp.Plot.line(prices, style=style)
+	>>> plot.show()
+	"""
+
+	width: float = DEFAULT_WIDTH
+	height: float = DEFAULT_HEIGHT
+	unit: SizeUnit = SizeUnit.INCH
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the width and the height are positive.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidSizeError
+			When the width or the height is zero or negative.
+		"""
+		require_field_types(self)
+
+		is_positive = self.width > 0 and self.height > 0
+		if not is_positive:
+			raise InvalidSizeError(self.width, self.height)

numdaplot/plots/style/size_unit.py

@@ -0,0 +1,62 @@
+"""
+Units of the width and the height of a Plot.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class SizeUnit(Enum):
+	"""
+	Units of the width and the height of a Plot, used by ``Size``.
+
+	.. 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(size=ndp.Size(width=16, height=8, unit=ndp.SizeUnit.CENTIMETER))
+	>>> plot = ndp.Plot.line(prices, style=style)
+	>>> plot.show()
+	"""
+
+	INCH = auto()
+	"""
+	Inches, as matplotlib counts sizes. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> style = ndp.PlotStyle(size=ndp.Size(width=6, height=3, unit=ndp.SizeUnit.INCH))
+	>>> plot = ndp.Plot.line(prices, style=style)
+	>>> plot.show()
+	"""
+
+	CENTIMETER = auto()
+	"""
+	Centimeters, 2.54 per inch.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> style = ndp.PlotStyle(size=ndp.Size(width=16, height=8, unit=ndp.SizeUnit.CENTIMETER))
+	>>> plot = ndp.Plot.line(prices, style=style)
+	>>> plot.show()
+	"""
+
+	PIXEL = auto()
+	"""
+	Pixels, 100 per inch, the resolution of a PNG image saved without ``ImageOptions``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0, 17.0])
+	>>> style = ndp.PlotStyle(size=ndp.Size(width=600, height=300, unit=ndp.SizeUnit.PIXEL))
+	>>> plot = ndp.Plot.line(prices, style=style)
+	>>> plot.show()
+	"""

numdaplot/positions/__init__.py

@@ -0,0 +1,5 @@
+"""
+Positions and axes: which rows and columns an operation works on.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/positions/axis.py

@@ -0,0 +1,54 @@
+"""
+Direction in which an operation runs on two-dimensional data.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class Axis(Enum):
+	"""
+	Direction in which an operation runs on two-dimensional data.
+
+	Each name describes the result: ``EACH_ROW`` handles every row on its own,
+	so a statistic gives one value per row.
+
+	Every method working along an axis takes it as its own ``axis`` argument, next to its settings:
+	``Array.compute``, ``Array.sort``, ``Table.count_missing`` and ``Table.drop_missing``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> sales = ndp.Array.from_list([[1, 2], [3, 4]])
+	>>> sales.compute(ndp.Sum(), axis=ndp.Axis.EACH_ROW)
+	Array([3, 7], dtype=INT64)
+	>>> sales.compute(ndp.Sum(), axis=ndp.Axis.EACH_COLUMN)
+	Array([4, 6], dtype=INT64)
+	"""
+
+	EACH_ROW = auto()
+	"""
+	Every row is handled on its own: one result per row.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> sales = ndp.Array.from_list([[1, 2], [3, 4]])
+	>>> sales.compute(ndp.Sum(), axis=ndp.Axis.EACH_ROW)
+	Array([3, 7], dtype=INT64)
+	"""
+
+	EACH_COLUMN = auto()
+	"""
+	Every column is handled on its own: one result per column.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> sales = ndp.Array.from_list([[1, 2], [3, 4]])
+	>>> sales.compute(ndp.Sum(), axis=ndp.Axis.EACH_COLUMN)
+	Array([4, 6], dtype=INT64)
+	"""

numdaplot/positions/index.py

@@ -0,0 +1,51 @@
+"""
+A single position in one dimension.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class Index:
+	"""
+	A single position in one dimension, used by ``Region``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	position
+		The position, starting at 0. A negative position counts from the end:
+		-1 is the last one.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> scores = ndp.Array.from_list([10, 20, 30])
+	>>> scores.take(ndp.Region(rows=ndp.Index(-1)))
+	Array([30], dtype=INT64)
+	"""
+
+	position: int
+
+	def __post_init__(self) -> None:
+		"""
+		Check the type of the position.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		"""
+		require_field_types(self)

numdaplot/positions/range.py

@@ -0,0 +1,90 @@
+"""
+A regular sequence of numbers between two bounds.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.invalid_step_error import InvalidStepError
+from numdaplot.rules.bounds import Bounds
+from numdaplot.settings.field_types import require_field_types
+
+DEFAULT_STEP = 1
+FORBIDDEN_STEP = 0
+
+
+@dataclass(frozen=True)
+class Range:
+	"""
+	A regular sequence of numbers from ``start`` to ``stop``, every ``step``.
+
+	It selects positions in ``Region`` and creates values in ``Array.from_range``.
+	In a ``Region``, ``start`` and ``step`` must be ``int``, since a position is a whole number.
+	Unlike the Python ``range``, the end is included by default, as in ``Between``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	start
+		First number of the sequence.
+	stop
+		Last number of the sequence, reached only when it falls on a step.
+	step
+		Gap between two numbers, 1 by default. A negative step goes downwards.
+	bounds
+		Which of ``start`` and ``stop`` are part of the sequence. Both are included by default.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidStepError
+		When ``step`` is zero, or goes away from ``stop``, such as a step of 1 from 5 to 1.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_range(ndp.Range(start=0, stop=10, step=2))
+	Array([ 0,  2,  4,  6,  8, 10], dtype=INT64)
+	>>> scores = ndp.Array.from_list([10, 20, 30, 40])
+	>>> scores.take(ndp.Region(rows=ndp.Range(start=1, stop=2)))
+	Array([20, 30], dtype=INT64)
+
+	The first 3 rows, without counting the last position: ``stop`` is left out with ``Bounds.LOW_ONLY``.
+
+	>>> first_count = 3
+	>>> first_rows = ndp.Range(start=0, stop=first_count, bounds=ndp.Bounds.LOW_ONLY)
+	>>> scores.take(ndp.Region(rows=first_rows))
+	Array([10, 20, 30], dtype=INT64)
+	"""
+
+	start: int | float
+	stop: int | float
+	step: int | float = DEFAULT_STEP
+	bounds: Bounds = Bounds.INCLUDED
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the step is not zero and goes from the start to the stop.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidStepError
+			When ``step`` is zero, or goes away from ``stop``.
+		"""
+		require_field_types(self)
+
+		if self.step == FORBIDDEN_STEP:
+			raise InvalidStepError(self.step)
+
+		distance = self.stop - self.start
+		signed_progress = distance * self.step
+		goes_away = signed_progress < 0
+		if goes_away:
+			raise InvalidStepError(self.step, self.start, self.stop)