Plot¶

tinax.plot owns explicit-lifecycle Matplotlib figures. A figure is built directly on an Agg canvas without pyplot: no global backend is selected, no rcParams are read or written, and drawing works on a headless worker. close is idempotent and also runs on context exit; drawing on or saving a closed figure raises RuntimeError. Plot inputs are host numpy.ndarray values, so materializing device arrays stays explicit.

from tinax.plot import Figure, save, show

with Figure(width=8.0, height=3.0, title="loss") as figure:
    figure.line(steps, train_loss, label="train")
    save(figure, "runs/run-1/loss.png")
    show(figure)

save writes PNG bytes through a sibling temporary file and os.replace, and refuses to replace an existing file unless overwrite=True. show renders inline through IPython.display when a session is active; IPython is imported lazily, so Matplotlib is the module's only dependency.

Figure ¶

Figure(
    *,
    width: float = 6.4,
    height: float = 4.8,
    dpi: int = 100,
    title: str | None = None,
)

One Matplotlib figure with an explicit Agg canvas and explicit close.

The figure is built directly on FigureCanvasAgg without pyplot: no global backend is selected, no rcParams are read or written, and drawing works on a headless worker. close is idempotent and also runs on context exit; drawing on or saving a closed figure raises RuntimeError. Plot inputs are host numpy.ndarray values; materialize device arrays before plotting.

Parameters:

Name	Type	Description	Default
`width`	`float`	Figure width in inches. Must be positive.	`6.4`
`height`	`float`	Figure height in inches. Must be positive.	`4.8`
`dpi`	`int`	Figure resolution. Must be a positive integer.	`100`
`title`	`str \| None`	Optional axes title.	`None`

Raises:

Type	Description
`TypeError`	If a size is not a real number, `dpi` is not an integer (booleans rejected), or `title` is not a string or `None`.
`ValueError`	If a size is not positive, `dpi` is not positive, or `title` is empty.

line ¶

line(
    x: ndarray,
    y: ndarray,
    *,
    label: str | None = None,
    color: str | None = None,
    linewidth: float | None = None,
) -> None

Draw one line series from equal-length host arrays.

Parameters:

Name	Type	Description	Default
`x`	`ndarray`	One-dimensional host array of x coordinates.	required
`y`	`ndarray`	One-dimensional host array of y coordinates with the same shape as `x`.	required
`label`	`str \| None`	Optional legend label; labels are collected into one legend.	`None`
`color`	`str \| None`	Optional Matplotlib color string.	`None`
`linewidth`	`float \| None`	Optional positive line width.	`None`

Raises:

Type	Description
`RuntimeError`	If the figure was already closed.
`TypeError`	If an input is not a host `numpy.ndarray`, `label` or `color` is not a string or `None`, or `linewidth` is not a real number or `None`.
`ValueError`	If the arrays are not one-dimensional, are empty, contain non-finite values, or have different shapes, or `linewidth` is not positive.

image ¶

image(
    array: ndarray,
    *,
    cmap: str | None = None,
    vmin: float | None = None,
    vmax: float | None = None,
) -> None

Draw one 1-D or 2-D host array as an image.

Parameters:

Name	Type	Description	Default
`array`	`ndarray`	One- or two-dimensional host array.	required
`cmap`	`str \| None`	Optional Matplotlib colormap name.	`None`
`vmin`	`float \| None`	Optional lower color limit.	`None`
`vmax`	`float \| None`	Optional upper color limit.	`None`

Raises:

Type	Description
`RuntimeError`	If the figure was already closed.
`TypeError`	If `array` is not a host `numpy.ndarray`, `cmap` is not a string or `None`, or a limit is not a real number or `None`.
`ValueError`	If the array is empty, has more than two dimensions, contains non-finite values, or a limit is not finite.

histogram ¶

histogram(
    values: ndarray,
    *,
    bins: int = 30,
    label: str | None = None,
) -> None

Draw one histogram from a one-dimensional host array.

Parameters:

Name	Type	Description	Default
`values`	`ndarray`	One-dimensional host array of samples.	required
`bins`	`int`	Positive number of histogram bins.	`30`
`label`	`str \| None`	Optional legend label; labels are collected into one legend.	`None`

Raises:

Type	Description
`RuntimeError`	If the figure was already closed.
`TypeError`	If `values` is not a host `numpy.ndarray`, `bins` is not an integer (booleans rejected), or `label` is not a string or `None`.
`ValueError`	If the array is not one-dimensional, is empty, or contains non-finite values, or `bins` is not positive.

png ¶

png(*, dpi: int | None = None) -> bytes

Render the figure to PNG bytes, optionally at a different resolution.

Parameters:

Name	Type	Description	Default
`dpi`	`int \| None`	Optional positive resolution override; the figure's own dpi by default.	`None`

Returns:

Type	Description
`bytes`	The PNG-encoded figure as `bytes`.

Raises:

Type	Description
`RuntimeError`	If the figure was already closed.
`TypeError`	If `dpi` is not an integer or `None` (booleans rejected).
`ValueError`	If `dpi` is not positive.

close ¶

close() -> None

Release the figure's artists; subsequent calls are no-ops.

save ¶

save(
    figure: Figure,
    path: str | PathLike[str],
    *,
    overwrite: bool = False,
    dpi: int | None = None,
) -> Path

Write a figure to path as PNG through a sibling temporary file and atomic replace.

Parameters:

Name	Type	Description	Default
`figure`	`Figure`	Open figure to render.	required
`path`	`str \| PathLike[str]`	Destination PNG path; parent directories are created.	required
`overwrite`	`bool`	Whether an existing destination may be replaced. Defaults to `False`.	`False`
`dpi`	`int \| None`	Optional positive resolution override for the written file.	`None`

Returns:

Type	Description
`Path`	The destination `pathlib.Path`.

Raises:

Type	Description
`RuntimeError`	If the figure was already closed.
`TypeError`	If `figure` is not a `tinax.plot.Figure`, `path` is not a string or `os.PathLike`, `overwrite` is not a bool, or `dpi` is not an integer or `None` (booleans rejected).
`ValueError`	If `path` is empty or `dpi` is not positive.
`FileExistsError`	If the destination exists and `overwrite` is `False`.

show ¶

show(figure: Figure) -> None

Display a figure inline in IPython/Jupyter through IPython.display.

IPython is imported only here, so Matplotlib remains the module's sole dependency. Outside an IPython session, use save and open the PNG instead.

Parameters:

Name	Type	Description	Default
`figure`	`Figure`	Open figure to render inline.	required

Raises:

Type	Description
`RuntimeError`	If the figure was already closed, IPython is not installed, or no IPython session is active.
`TypeError`	If `figure` is not a `tinax.plot.Figure`.