acadplot 0.1.0__py3-none-any.whl

acadplot/charts.py

@@ -0,0 +1,376 @@
+from itertools import cycle
+from typing import List, Optional, Sequence, Tuple
+
+import matplotlib.pyplot as plt
+from matplotlib.colors import to_rgba
+from matplotlib.patches import Patch
+
+from .draw import resolve_color_key
+from .styles import apply_axis_style, apply_grid, get_current_style
+from .utils import markers, new_alpha, save, styled_legend
+
+
+def _prepare_axes(ax, fig_size):
+    if ax is None:
+        return plt.subplots(figsize=fig_size)
+    return ax.figure, ax
+
+
+def _resolve_marker(marker_key: str | int):
+    if isinstance(marker_key, int):
+        return list(markers.values())[marker_key]
+    return markers[marker_key]
+
+
+def _resolve_text_sizes(style, font_size, label_size, tick_size, legend_size):
+    font_size_override = font_size
+    if font_size is None:
+        font_size = float(style["font_size"])
+    if label_size is None:
+        label_size = (
+            font_size_override
+            if font_size_override is not None
+            else float(style["label_size"])
+        )
+    if tick_size is None:
+        tick_size = (
+            font_size_override
+            if font_size_override is not None
+            else float(style["tick_size"])
+        )
+    if legend_size is None:
+        legend_size = (
+            font_size_override
+            if font_size_override is not None
+            else float(style["legend_size"])
+        )
+    return font_size, label_size, tick_size, legend_size
+
+
+def _parse_xy_marker_series(series):
+    if len(series) == 5:
+        x, y, color_key, marker_key, series_label = series
+        return x, y, color_key, marker_key, series_label
+    if len(series) == 4:
+        x, y, marker_key, series_label = series
+        return x, y, None, marker_key, series_label
+    raise ValueError(
+        "Series entries must be (x, y, color, marker, label) or (x, y, marker, label)."
+    )
+
+
+def _parse_errorbar_series(series):
+    if len(series) == 6:
+        x, y, yerr, color_key, marker_key, series_label = series
+        return x, y, yerr, color_key, marker_key, series_label
+    if len(series) == 5:
+        x, y, yerr, marker_key, series_label = series
+        return x, y, yerr, None, marker_key, series_label
+    raise ValueError(
+        "Errorbar entries must be (x, y, yerr, color, marker, label) or "
+        "(x, y, yerr, marker, label)."
+    )
+
+
+def _parse_box_group(group):
+    if len(group) == 3:
+        values, color_key, group_label = group
+        return values, color_key, group_label
+    if len(group) == 2:
+        values, group_label = group
+        return values, None, group_label
+    raise ValueError("Box groups must be (values, color, label) or (values, label).")
+
+
+def _add_legend(
+    ax,
+    location: str,
+    legend_size: float,
+    ncols: int,
+    columnspacing: float,
+    legend_outside: bool | str,
+):
+    return styled_legend(
+        ax,
+        location,
+        legend_size=legend_size,
+        ncols=ncols,
+        columnspacing=columnspacing,
+        legend_outside=legend_outside,
+    )
+
+
+def plot_scatter(
+    series: List[Tuple],
+    location: str = "best",
+    fig_size: Optional[Tuple[float, float]] = None,
+    label: Tuple[str, str] = ("x-label", "y-label"),
+    ax=None,
+    font_size: Optional[float] = None,
+    label_size: Optional[float] = None,
+    tick_size: Optional[float] = None,
+    legend_size: Optional[float] = None,
+    marker_size: Optional[float] = None,
+    ncols: int = 1,
+    columnspacing: float = 0.5,
+    grid: Optional[str] = None,
+    fname: Optional[str] = "scatter_plot.pdf",
+    legend_outside: bool | str = False,
+):
+    """Plot one or more scatter series."""
+    style = get_current_style()
+    if fig_size is None:
+        fig_size = style["fig_size"]
+    _, label_size, tick_size, legend_size = _resolve_text_sizes(
+        style, font_size, label_size, tick_size, legend_size
+    )
+    if marker_size is None:
+        marker_size = 28.0 * float(style["marker_scale"])
+
+    fig, ax = _prepare_axes(ax, fig_size)
+    ax.set_prop_cycle(color=list(style["palette"]))
+    ax.set_xlabel(label[0], fontsize=label_size)
+    ax.set_ylabel(label[1], fontsize=label_size)
+    apply_grid(ax, grid or str(style["line_grid"]))
+
+    palette_iter = cycle(style["palette"])
+    for item in series:
+        x, y, color_key, marker_key, series_label = _parse_xy_marker_series(item)
+        color = resolve_color_key(color_key)
+        if color is None:
+            color = next(palette_iter)
+        marker, _ = _resolve_marker(marker_key)
+        ax.scatter(
+            x,
+            y,
+            s=marker_size,
+            marker=marker,
+            facecolors=new_alpha(to_rgba(color), 0.3),
+            edgecolors=color,
+            linewidths=float(style["marker_edge_width"]),
+            label=series_label,
+            zorder=3,
+        )
+
+    _add_legend(ax, location, legend_size, ncols, columnspacing, legend_outside)
+    ax.tick_params(axis="both", labelsize=tick_size)
+    apply_axis_style(ax)
+
+    if fname:
+        save(fig, fname, close=False)
+    return fig, ax
+
+
+def plot_errorbar(
+    series: List[Tuple],
+    location: str = "best",
+    fig_size: Optional[Tuple[float, float]] = None,
+    label: Tuple[str, str] = ("x-label", "y-label"),
+    ax=None,
+    font_size: Optional[float] = None,
+    label_size: Optional[float] = None,
+    tick_size: Optional[float] = None,
+    legend_size: Optional[float] = None,
+    capsize: float = 2.5,
+    ncols: int = 1,
+    columnspacing: float = 0.5,
+    grid: Optional[str] = None,
+    fname: Optional[str] = "errorbar_plot.pdf",
+    legend_outside: bool | str = False,
+):
+    """Plot line series with error bars."""
+    style = get_current_style()
+    if fig_size is None:
+        fig_size = style["fig_size"]
+    _, label_size, tick_size, legend_size = _resolve_text_sizes(
+        style, font_size, label_size, tick_size, legend_size
+    )
+
+    fig, ax = _prepare_axes(ax, fig_size)
+    ax.set_prop_cycle(color=list(style["palette"]))
+    ax.set_xlabel(label[0], fontsize=label_size)
+    ax.set_ylabel(label[1], fontsize=label_size)
+    apply_grid(ax, grid or str(style["line_grid"]))
+
+    for item in series:
+        x, y, yerr, color_key, marker_key, series_label = _parse_errorbar_series(item)
+        color = resolve_color_key(color_key)
+        color_kwargs = {"color": color, "ecolor": color} if color is not None else {}
+        marker, marker_size = _resolve_marker(marker_key)
+        (line, _, _) = ax.errorbar(
+            x,
+            y,
+            yerr=yerr,
+            marker=marker,
+            markersize=marker_size * float(style["marker_scale"]),
+            markeredgewidth=float(style["marker_edge_width"]),
+            linewidth=float(style["line_width"]),
+            elinewidth=float(style["line_width"]) * 0.8,
+            capsize=capsize,
+            label=series_label,
+            zorder=3,
+            **color_kwargs,
+        )
+        resolved_color = line.get_color()
+        line.set_markerfacecolor(new_alpha(to_rgba(resolved_color), 0.3))
+        line.set_markeredgecolor(resolved_color)
+
+    _add_legend(ax, location, legend_size, ncols, columnspacing, legend_outside)
+    ax.tick_params(axis="both", labelsize=tick_size)
+    apply_axis_style(ax)
+
+    if fname:
+        save(fig, fname, close=False)
+    return fig, ax
+
+
+def plot_box(
+    groups: List[Tuple],
+    fig_size: Optional[Tuple[float, float]] = None,
+    label: Tuple[str, str] = ("Group", "Value"),
+    ax=None,
+    font_size: Optional[float] = None,
+    label_size: Optional[float] = None,
+    tick_size: Optional[float] = None,
+    legend_size: Optional[float] = None,
+    location: Optional[str] = None,
+    grid: Optional[str] = None,
+    fname: Optional[str] = "box_plot.pdf",
+    legend_outside: bool | str = False,
+):
+    """Plot grouped distributions as a box plot."""
+    style = get_current_style()
+    if fig_size is None:
+        fig_size = style["fig_size"]
+    _, label_size, tick_size, legend_size = _resolve_text_sizes(
+        style, font_size, label_size, tick_size, legend_size
+    )
+
+    values = []
+    labels = []
+    colors = []
+    palette_iter = cycle(style["palette"])
+    for group in groups:
+        group_values, color_key, group_label = _parse_box_group(group)
+        values.append(group_values)
+        labels.append(group_label)
+        color = resolve_color_key(color_key)
+        colors.append(color if color is not None else next(palette_iter))
+
+    fig, ax = _prepare_axes(ax, fig_size)
+    ax.set_xlabel(label[0], fontsize=label_size)
+    ax.set_ylabel(label[1], fontsize=label_size)
+    apply_grid(ax, grid or "major-y")
+
+    box = ax.boxplot(
+        values,
+        labels=labels,
+        patch_artist=True,
+        widths=0.55,
+        medianprops=dict(color=str(style["axis_color"])),
+    )
+    for patch, color in zip(box["boxes"], colors):
+        patch.set_facecolor(new_alpha(to_rgba(color), 0.28))
+        patch.set_edgecolor(color)
+        patch.set_linewidth(float(style["line_width"]))
+    for key in ("whiskers", "caps", "medians"):
+        for artist in box[key]:
+            artist.set_linewidth(float(style["line_width"]))
+            artist.set_color(str(style["axis_color"]))
+
+    if location is not None or legend_outside:
+        handles = [
+            Patch(facecolor=new_alpha(to_rgba(c), 0.28), edgecolor=c) for c in colors
+        ]
+        styled_legend(
+            ax,
+            location or "best",
+            legend_size=legend_size,
+            legend_outside=legend_outside,
+            handles=handles,
+            labels=labels,
+        )
+
+    ax.tick_params(axis="both", labelsize=tick_size)
+    apply_axis_style(ax)
+
+    if fname:
+        save(fig, fname, close=False)
+    return fig, ax
+
+
+def plot_heatmap(
+    matrix: Sequence[Sequence[float]],
+    fig_size: Optional[Tuple[float, float]] = None,
+    label: Tuple[str, str] = ("x-label", "y-label"),
+    ax=None,
+    xticklabels: Optional[Sequence[str]] = None,
+    yticklabels: Optional[Sequence[str]] = None,
+    cmap: str = "PuBuGn",
+    colorbar_label: Optional[str] = None,
+    annotate: bool = False,
+    fmt: str = ".2g",
+    font_size: Optional[float] = None,
+    label_size: Optional[float] = None,
+    tick_size: Optional[float] = None,
+    legend_size: Optional[float] = None,
+    fname: Optional[str] = "heatmap.pdf",
+):
+    """Plot a matrix heatmap with optional annotations and colorbar."""
+    style = get_current_style()
+    if fig_size is None:
+        fig_size = style["fig_size"]
+    _, label_size, tick_size, legend_size = _resolve_text_sizes(
+        style, font_size, label_size, tick_size, legend_size
+    )
+
+    fig, ax = _prepare_axes(ax, fig_size)
+    image = ax.imshow(matrix, cmap=cmap, aspect="auto", zorder=2)
+    ax.set_xlabel(label[0], fontsize=label_size)
+    ax.set_ylabel(label[1], fontsize=label_size)
+
+    if xticklabels is not None:
+        ax.set_xticks(range(len(xticklabels)))
+        ax.set_xticklabels(xticklabels, fontsize=tick_size)
+    if yticklabels is not None:
+        ax.set_yticks(range(len(yticklabels)))
+        ax.set_yticklabels(yticklabels, fontsize=tick_size)
+
+    if annotate:
+        colormap = plt.get_cmap(cmap)
+        for row_idx, row in enumerate(matrix):
+            for col_idx, value in enumerate(row):
+                cell_color = colormap(image.norm(value))
+                luminance = (
+                    0.299 * cell_color[0]
+                    + 0.587 * cell_color[1]
+                    + 0.114 * cell_color[2]
+                )
+                annotation_color = (
+                    "#F5F5F5" if luminance < 0.45 else str(style["text_color"])
+                )
+                ax.text(
+                    col_idx,
+                    row_idx,
+                    format(value, fmt),
+                    ha="center",
+                    va="center",
+                    fontsize=tick_size,
+                    color=annotation_color,
+                )
+
+    colorbar = fig.colorbar(image, ax=ax, fraction=0.046, pad=0.04)
+    colorbar.ax.tick_params(labelsize=tick_size, colors=str(style["tick_color"]))
+    if colorbar_label is not None:
+        colorbar.set_label(
+            colorbar_label,
+            fontsize=legend_size,
+            color=str(style["axis_label_color"]),
+        )
+
+    ax.tick_params(axis="both", labelsize=tick_size)
+    apply_axis_style(ax)
+
+    if fname:
+        save(fig, fname, close=False)
+    return fig, ax

acadplot/draw.py

@@ -0,0 +1,126 @@
+from typing import List
+
+from matplotlib.colors import is_color_like, to_rgba
+
+from .styles import get_current_style
+from .utils import colors, markers, new_alpha, patterns
+
+
+def resolve_color_key(color_key: str | int | None) -> str | None:
+    """Resolve an AcadPlot color key, raw Matplotlib color, or default cycle color."""
+    if color_key is None:
+        return None
+    if isinstance(color_key, int):
+        return list(colors.values())[color_key]
+    if color_key in colors:
+        return colors[color_key]
+    if is_color_like(color_key):
+        return color_key
+    raise ValueError(
+        f"Unknown color {color_key!r}. Use a theme color name, index, or Matplotlib color."
+    )
+
+
+def resolve_pattern_key(pattern_key: str | int | None) -> str | None:
+    """Resolve an AcadPlot pattern preset, index, raw hatch string, or no hatch."""
+    if pattern_key is None:
+        return None
+    if isinstance(pattern_key, int):
+        return list(patterns.values())[pattern_key]
+    if pattern_key in patterns:
+        return patterns[pattern_key]
+    return pattern_key
+
+
+def draw(
+    ax,
+    x: List[float],
+    y: List[float],
+    color_key: str | int | None,
+    marker_key: str | int,
+    label: str,
+):
+    """Draw a line with markers on the given axes.
+
+    Args:
+        ax: The axes to draw on.
+        x (List[float]): x values.
+        y (List[float]): y values.
+        color_key (str | int | None): Color name, index, raw Matplotlib color,
+            or None to use the active theme palette cycle.
+        marker_key (str | int): Marker name or index.
+        label (str): Label for the line.
+    """
+    color = resolve_color_key(color_key)
+
+    if isinstance(marker_key, int):
+        marker = list(markers.values())[marker_key]
+    elif isinstance(marker_key, str):
+        marker = markers[marker_key]
+
+    style = get_current_style()
+    marker_style, marker_size = marker
+    color_kwargs = {"color": color} if color is not None else {}
+
+    (line,) = ax.plot(
+        x,
+        y,
+        marker=marker_style,
+        markersize=marker_size * float(style["marker_scale"]),
+        markeredgewidth=float(style["marker_edge_width"]),
+        linewidth=float(style["line_width"]),
+        label=label,
+        zorder=3,
+        **color_kwargs,
+    )
+    resolved_color = line.get_color()
+    line.set_markerfacecolor(new_alpha(to_rgba(resolved_color), 0.3))
+    line.set_markeredgecolor(resolved_color)
+
+
+def draw_bar(
+    ax,
+    x: List[float],
+    y: List[float],
+    color_key: str | int | None,
+    label: str,
+    width: float = 0.35,
+    pattern_key: str | int | None = None,
+):
+    """Draw a bar on the given axes.
+
+    Args:
+        ax: The axes to draw on.
+        x (List[float]): x positions.
+        y (List[float]): bar heights.
+        color_key (str | int | None): Color name, index, raw Matplotlib color,
+            or None to use the active theme palette cycle.
+        label (str): Label for the bar.
+        width (float): Bar width. Defaults to 0.35.
+        pattern_key (str | int | None): Hatch pattern name, index, raw Matplotlib
+            hatch string, or None.
+    """
+    color = resolve_color_key(color_key)
+    pattern = resolve_pattern_key(pattern_key)
+    style = get_current_style()
+    bar_alpha = float(style["bar_alpha"])
+    bar_edge_color = str(style["bar_edge_color"])
+    color_kwargs = {"edgecolor": str(style["bar_edge_color"])}
+    if color is not None:
+        color_kwargs["facecolor"] = new_alpha(to_rgba(color), bar_alpha)
+
+    container = ax.bar(
+        x,
+        y,
+        width,
+        linewidth=float(style["bar_edge_width"]),
+        hatch=pattern,
+        label=label,
+        zorder=3,
+        **color_kwargs,
+    )
+    for patch in container.patches:
+        if color is None:
+            patch.set_facecolor(new_alpha(to_rgba(patch.get_facecolor()), bar_alpha))
+        patch.set_edgecolor(bar_edge_color)
+        patch.set_alpha(None)

acadplot/line.py

@@ -0,0 +1,184 @@
+from typing import List, Optional, Tuple
+
+import matplotlib.pyplot as plt
+
+from .draw import draw
+from .styles import (
+    apply_axis_style,
+    apply_grid,
+    configure_plot_style,
+    get_current_style,
+)
+from .utils import save, styled_legend
+
+
+def _parse_line(line):
+    if len(line) == 5:
+        x, y, color_key, marker_key, line_label = line
+        return x, y, color_key, marker_key, line_label
+    if len(line) == 4:
+        x, y, marker_key, line_label = line
+        return x, y, None, marker_key, line_label
+    raise ValueError(
+        "Line entries must be (x, y, color, marker, label) or (x, y, marker, label)."
+    )
+
+
+def _resolve_text_sizes(style, font_size, label_size, tick_size, legend_size):
+    font_size_override = font_size
+    if font_size is None:
+        font_size = float(style["font_size"])
+    if label_size is None:
+        label_size = (
+            font_size_override
+            if font_size_override is not None
+            else float(style["label_size"])
+        )
+    if tick_size is None:
+        tick_size = (
+            font_size_override
+            if font_size_override is not None
+            else float(style["tick_size"])
+        )
+    if legend_size is None:
+        legend_size = (
+            font_size_override
+            if font_size_override is not None
+            else float(style["legend_size"])
+        )
+    return font_size, label_size, tick_size, legend_size
+
+
+def plot_line(
+    lines: List[Tuple],
+    location: str,
+    fig_size: Optional[Tuple[float, float]] = None,
+    label: Tuple[str, str] = ("x-label", "y-label"),
+    ax=None,
+    xticks: Optional[List[float] | range] = None,
+    yticks: Optional[List[float] | range] = None,
+    xstart: Optional[float] = None,
+    ystart: Optional[float] = None,
+    font_size: Optional[float] = None,
+    label_size: Optional[float] = None,
+    tick_size: Optional[float] = None,
+    legend_size: Optional[float] = None,
+    ncols: int = 1,
+    columnspacing: float = 0.5,
+    grid: Optional[str] = None,
+    fname: Optional[str] = "plot.pdf",
+    legend_outside: bool | str = False,
+):
+    """Plot multiple lines with markers and a legend.
+
+    Args:
+        lines (List[Tuple]): List of lines to plot, each defined by
+            (x values, y values, color name/index, marker name/index, label)
+            or (x values, y values, marker name/index, label). Omit color to
+            use the active theme palette cycle.
+        location (str): Location of the legend.
+        fig_size (Tuple[float, float], optional): Figure size. Defaults to the active style.
+        label (Tuple[str, str], optional): Labels for the x and y axes. Defaults to ("x-label", "y-label").
+        ax (Optional[plt.Axes], optional): Axes to plot on. Creates new if None. Defaults to None.
+        xticks (Optional[List[float] | range], optional): Custom x-axis ticks. Defaults to None.
+        yticks (Optional[List[float] | range], optional): Custom y-axis ticks. Defaults to None.
+        xstart (Optional[float], optional): Minimum x-axis value. Defaults to None.
+        ystart (Optional[float], optional): Minimum y-axis value. Defaults to None.
+        font_size (float, optional): Base font size for labels, ticks, and legend. Defaults to the active style.
+        label_size (float, optional): Axis label size. Defaults to font_size or the active style.
+        tick_size (float, optional): Tick label size. Defaults to font_size or the active style.
+        legend_size (float, optional): Legend text size. Defaults to font_size or the active style.
+        ncols (int, optional): Number of columns in the legend. Defaults to 1.
+        columnspacing (float, optional): Spacing between legend columns. Defaults to 0.5.
+        grid (str, optional): Grid preset: "major-y", "major", "major-minor", or "none".
+        fname (Optional[str], optional): Filename to save the plot. Defaults to "plot.pdf".
+    """
+    style = get_current_style()
+    if fig_size is None:
+        fig_size = style["fig_size"]
+    font_size, label_size, tick_size, legend_size = _resolve_text_sizes(
+        style,
+        font_size,
+        label_size,
+        tick_size,
+        legend_size,
+    )
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=fig_size)
+    else:
+        fig = ax.figure
+
+    ax.set_prop_cycle(color=list(style["palette"]))
+    ax.set_xlabel(label[0], fontsize=label_size)
+    ax.set_ylabel(label[1], fontsize=label_size)
+    apply_grid(ax, grid or str(style["line_grid"]))
+
+    for line in lines:
+        draw(ax, *_parse_line(line))
+
+    styled_legend(
+        ax,
+        location,
+        legend_size=legend_size,
+        ncols=ncols,
+        columnspacing=columnspacing,
+        legend_outside=legend_outside,
+    )
+
+    if xticks is not None:
+        ax.set_xticks(xticks)
+    if yticks is not None:
+        ax.set_yticks(yticks)
+
+    ax.tick_params(axis="both", labelsize=tick_size)
+    apply_axis_style(ax)
+
+    if xstart is not None:
+        ax.set_xlim(left=xstart)
+    if ystart is not None:
+        ax.set_ylim(bottom=ystart)
+
+    if fname:
+        save(fig, fname, close=False)
+
+    return fig, ax
+
+
+if __name__ == "__main__":
+    configure_plot_style()
+    data: List[Tuple[List[float], List[float], str | int, str | int, str]] = [
+        ([10, 20, 30, 40, 50], [5, 10, 15, 20, 25], "blue", 8, "Method A"),
+        (
+            [10, 20, 30, 40, 50],
+            [6, 11, 14, 18, 22],
+            "orange",
+            0,
+            "Method B",
+        ),
+        (
+            [10, 20, 30, 40, 50],
+            [7, 9, 13, 19, 24],
+            "green",
+            1,
+            "Method C",
+        ),
+    ]
+
+    # Single plot usage (unchanged)
+    plot_line(
+        data,
+        "upper left",
+        ystart=min(min(y) for _, y, _, _, _ in data),
+        yticks=range(0, 30, 5),
+        fname="examples/plot.png",
+        font_size=8,
+    )
+
+    # Subplot usage example
+    fig, axes = plt.subplots(1, 2, figsize=(6, 2))
+    plot_line(data, "upper left", ax=axes[0], yticks=range(0, 30, 5), fname=None)
+    plot_line(data, "upper left", ax=axes[1], yticks=range(0, 30, 5), fname=None)
+    plt.tight_layout(pad=0.2)
+    plt.subplots_adjust(wspace=0.27)  # Add horizontal space between subplots
+    save(fig, "examples/subplot.png")