eagleplot 3.0.0__py3-none-any.whl

eagleplot/plugin_loader.py

@@ -0,0 +1,208 @@
+"""Plugin loader for EaglePlot.
+
+Discovers and loads plugin_*.py files from the plugins/ directory.
+Each plugin is a standard Python module that optionally exposes:
+
+    PLUGIN_NAME: str          — human-readable name
+    PLUGIN_VERSION: str       — semver string
+    PLUGIN_DESCRIPTION: str   — one-line description
+
+    get_plot_types() -> list[dict]
+        Returns a list of plot-type registration dicts, each with keys:
+        - 'name': str  (unique identifier)
+        - 'label': str (display label)
+        - 'function': callable  (plotting function)
+        - 'description': str (optional)
+
+    get_analysis_tools() -> list[dict]
+        Returns a list of analysis-tool dicts with keys:
+        - 'name': str
+        - 'label': str
+        - 'function': callable
+        - 'description': str (optional)
+
+Public API
+----------
+discover_plugins(plugins_dir=None) -> dict[str, types.ModuleType]
+    Scan plugins_dir (default: repo-root/plugins/) for plugin_*.py files.
+    Import each valid plugin and return {filename_stem: module}.
+    Silently skips files that raise ImportError or other exceptions during load.
+
+get_plugin_plot_types(plugins=None) -> list[dict]
+    Return all plot-type dicts from all discovered plugins.
+    plugins: pass result of discover_plugins() to avoid re-scanning.
+
+get_plugin_analysis_tools(plugins=None) -> list[dict]
+    Return all analysis-tool dicts from all discovered plugins.
+
+list_plugins(plugins=None) -> list[dict]
+    Return a summary list of loaded plugins:
+    [{'name': ..., 'version': ..., 'description': ..., 'file': ...}, ...]
+"""
+
+import importlib.util
+import types
+from pathlib import Path
+from typing import Optional
+
+_PLUGINS_DIR = Path(__file__).parent.parent / "plugins"
+
+
+def discover_plugins(
+    plugins_dir: Optional[Path] = None,
+) -> dict[str, types.ModuleType]:
+    """Scan plugins_dir for plugin_*.py files and import each one.
+
+    Parameters
+    ----------
+    plugins_dir : Path, optional
+        Directory to scan. Defaults to ``<repo-root>/plugins/``.
+
+    Returns
+    -------
+    dict[str, types.ModuleType]
+        Mapping of filename stem (e.g. ``"plugin_example"``) to the loaded
+        module object. Files that fail to import are silently skipped.
+    """
+    if plugins_dir is None:
+        plugins_dir = _PLUGINS_DIR
+
+    plugins_dir = Path(plugins_dir)
+
+    if not plugins_dir.is_dir():
+        return {}
+
+    loaded: dict[str, types.ModuleType] = {}
+
+    for path in sorted(plugins_dir.glob("plugin_*.py")):
+        stem = path.stem
+        try:
+            spec = importlib.util.spec_from_file_location(stem, path)
+            if spec is None or spec.loader is None:
+                continue
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)  # type: ignore[union-attr]
+            loaded[stem] = module
+        except Exception:
+            # Bad plugins must never crash the app
+            pass
+
+    return loaded
+
+
+def get_plugin_plot_types(
+    plugins: Optional[dict[str, types.ModuleType]] = None,
+) -> list[dict]:
+    """Return all plot-type dicts contributed by discovered plugins.
+
+    Parameters
+    ----------
+    plugins : dict, optional
+        Pre-loaded plugins dict from :func:`discover_plugins`. If *None*,
+        :func:`discover_plugins` is called automatically.
+
+    Returns
+    -------
+    list[dict]
+        Concatenated list of plot-type dicts from every plugin that exposes
+        ``get_plot_types()``. Each dict has at minimum ``name``, ``label``,
+        and ``function`` keys.
+    """
+    if plugins is None:
+        plugins = discover_plugins()
+
+    result: list[dict] = []
+
+    for module in plugins.values():
+        if not hasattr(module, "get_plot_types"):
+            continue
+        try:
+            items = module.get_plot_types()
+            if isinstance(items, list):
+                result.extend(items)
+        except Exception:
+            pass
+
+    return result
+
+
+def get_plugin_analysis_tools(
+    plugins: Optional[dict[str, types.ModuleType]] = None,
+) -> list[dict]:
+    """Return all analysis-tool dicts contributed by discovered plugins.
+
+    Parameters
+    ----------
+    plugins : dict, optional
+        Pre-loaded plugins dict from :func:`discover_plugins`. If *None*,
+        :func:`discover_plugins` is called automatically.
+
+    Returns
+    -------
+    list[dict]
+        Concatenated list of analysis-tool dicts from every plugin that
+        exposes ``get_analysis_tools()``. Each dict has at minimum ``name``,
+        ``label``, and ``function`` keys.
+    """
+    if plugins is None:
+        plugins = discover_plugins()
+
+    result: list[dict] = []
+
+    for module in plugins.values():
+        if not hasattr(module, "get_analysis_tools"):
+            continue
+        try:
+            items = module.get_analysis_tools()
+            if isinstance(items, list):
+                result.extend(items)
+        except Exception:
+            pass
+
+    return result
+
+
+def list_plugins(
+    plugins: Optional[dict[str, types.ModuleType]] = None,
+) -> list[dict]:
+    """Return a human-readable summary of all loaded plugins.
+
+    Parameters
+    ----------
+    plugins : dict, optional
+        Pre-loaded plugins dict from :func:`discover_plugins`. If *None*,
+        :func:`discover_plugins` is called automatically.
+
+    Returns
+    -------
+    list[dict]
+        One dict per plugin with keys:
+
+        - ``name`` — ``PLUGIN_NAME`` attribute, or the file stem if absent
+        - ``version`` — ``PLUGIN_VERSION`` attribute, or ``"unknown"``
+        - ``description`` — ``PLUGIN_DESCRIPTION`` attribute, or ``""``
+        - ``file`` — absolute :class:`~pathlib.Path` to the plugin file
+    """
+    if plugins is None:
+        plugins = discover_plugins()
+
+    summary: list[dict] = []
+
+    for stem, module in plugins.items():
+        name = getattr(module, "PLUGIN_NAME", stem)
+        version = getattr(module, "PLUGIN_VERSION", "unknown")
+        description = getattr(module, "PLUGIN_DESCRIPTION", "")
+
+        # Retrieve the file path from the module's __file__ attribute
+        file_path = Path(getattr(module, "__file__", ""))
+
+        summary.append(
+            {
+                "name": name,
+                "version": version,
+                "description": description,
+                "file": file_path,
+            }
+        )
+
+    return summary

eagleplot/report.py

@@ -0,0 +1,448 @@
+"""PDF Report Generator for EaglePlot sessions.
+
+Builds a multi-page PDF from a session's plots, datasets, and analysis results
+using matplotlib.backends.backend_pdf.PdfPages — no extra dependencies required.
+
+Public API
+----------
+generate_pdf_report(filepath, title, plot_entries, datasets, analysis_results,
+                    author='', dpi=150) -> Path
+    Write a PDF report and return the output Path.
+
+_make_title_page(title, author, n_plots, n_datasets, n_analyses) -> Figure
+    (internal) Render a title page as a matplotlib Figure.
+
+_dataframe_to_figure(df, title, max_rows) -> Figure
+    (internal) Render a DataFrame as a matplotlib table Figure.
+
+_analysis_result_to_figure(result) -> Figure
+    (internal) Render one analysis result dict as a text/table Figure.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+from matplotlib.backends.backend_pdf import PdfPages
+from matplotlib.figure import Figure
+
+
+# ── Internal helpers ──────────────────────────────────────────────────────────
+
+
+def _make_title_page(
+    title: str,
+    author: str,
+    n_plots: int,
+    n_datasets: int,
+    n_analyses: int,
+) -> Figure:
+    """Render a title page as a matplotlib Figure.
+
+    Parameters
+    ----------
+    title:
+        Report title string.
+    author:
+        Author name (may be empty).
+    n_plots:
+        Number of matplotlib plot entries included in the report.
+    n_datasets:
+        Number of DataFrame datasets included in the report.
+    n_analyses:
+        Number of analysis result entries included in the report.
+
+    Returns
+    -------
+    Figure
+        A matplotlib Figure (caller is responsible for closing it).
+    """
+    fig = plt.figure(figsize=(8.5, 11), facecolor="white")
+    ax = fig.add_axes((0.0, 0.0, 1.0, 1.0))
+    ax.set_axis_off()
+
+    # Decorative horizontal rules
+    ax.axhline(0.78, xmin=0.08, xmax=0.92, color="#333333", linewidth=1.5)
+    ax.axhline(0.20, xmin=0.08, xmax=0.92, color="#333333", linewidth=0.8)
+
+    # Title
+    fig.text(
+        0.5,
+        0.65,
+        title,
+        ha="center",
+        va="center",
+        fontsize=24,
+        fontweight="bold",
+        color="#111111",
+        wrap=True,
+    )
+
+    # Subtitle
+    fig.text(
+        0.5,
+        0.57,
+        "Generated by EaglePlot",
+        ha="center",
+        va="center",
+        fontsize=13,
+        color="#555555",
+        style="italic",
+    )
+
+    # Author
+    if author:
+        fig.text(
+            0.5,
+            0.50,
+            f"Author: {author}",
+            ha="center",
+            va="center",
+            fontsize=11,
+            color="#333333",
+        )
+
+    # Date
+    date_str = datetime.now().strftime("%Y-%m-%d %H:%M")
+    fig.text(
+        0.5,
+        0.44,
+        f"Date: {date_str}",
+        ha="center",
+        va="center",
+        fontsize=11,
+        color="#333333",
+    )
+
+    # Contents summary
+    fig.text(
+        0.5,
+        0.34,
+        "Contents",
+        ha="center",
+        va="center",
+        fontsize=13,
+        fontweight="bold",
+        color="#111111",
+    )
+    summary_lines = [
+        f"Plots (matplotlib):  {n_plots}",
+        f"Datasets:            {n_datasets}",
+        f"Analysis results:    {n_analyses}",
+    ]
+    fig.text(
+        0.5,
+        0.27,
+        "\n".join(summary_lines),
+        ha="center",
+        va="center",
+        fontsize=11,
+        color="#333333",
+        family="monospace",
+    )
+
+    # Footer
+    fig.text(
+        0.5,
+        0.08,
+        "NCCU Schultz Lab  ·  EaglePlot",
+        ha="center",
+        va="center",
+        fontsize=9,
+        color="#888888",
+    )
+
+    return fig
+
+
+def _dataframe_to_figure(
+    df: pd.DataFrame,
+    title: str = "",
+    max_rows: int = 30,
+) -> Figure:
+    """Render a DataFrame as a matplotlib table Figure.
+
+    Parameters
+    ----------
+    df:
+        The DataFrame to display.
+    title:
+        Title shown above the table.
+    max_rows:
+        Maximum number of data rows to render (additional rows are omitted
+        with a note).
+
+    Returns
+    -------
+    Figure
+        A matplotlib Figure (caller is responsible for closing it).
+    """
+    max_cols = 10
+
+    truncated_rows = len(df) > max_rows
+    truncated_cols = len(df.columns) > max_cols
+
+    display_df = df.iloc[:max_rows, :max_cols].copy()
+
+    # Convert all values to short strings for display
+    for col in display_df.columns:
+        display_df[col] = display_df[col].apply(
+            lambda v: f"{v:.4g}" if isinstance(v, (float, np.floating)) else str(v)[:20]
+        )
+
+    n_rows, n_cols = display_df.shape
+
+    # Figure height: scale with number of rows, bounded
+    row_height = 0.35
+    fig_height = max(3.0, min(14.0, 1.5 + n_rows * row_height))
+    fig = plt.figure(figsize=(11, fig_height), facecolor="white")
+    ax = fig.add_axes((0.02, 0.02, 0.96, 0.96))
+    ax.set_axis_off()
+
+    # Title
+    notes: list[str] = []
+    if truncated_rows:
+        notes.append(f"showing first {max_rows} of {len(df)} rows")
+    if truncated_cols:
+        notes.append(f"showing first {max_cols} of {len(df.columns)} columns")
+    note_str = f"  ({', '.join(notes)})" if notes else ""
+    ax.set_title(
+        f"{title}{note_str}",
+        fontsize=12,
+        fontweight="bold",
+        pad=8,
+    )
+
+    if display_df.empty:
+        ax.text(
+            0.5,
+            0.5,
+            "(empty DataFrame)",
+            ha="center",
+            va="center",
+            fontsize=11,
+            color="#888888",
+            transform=ax.transAxes,
+        )
+        return fig
+
+    col_labels = list(display_df.columns)
+    cell_data = display_df.values.tolist()
+
+    table = ax.table(
+        cellText=cell_data,
+        colLabels=col_labels,
+        loc="center",
+        cellLoc="center",
+    )
+    table.auto_set_font_size(False)
+    table.set_fontsize(8)
+    table.auto_set_column_width(list(range(n_cols)))
+
+    # Style header row
+    for col_idx in range(n_cols):
+        cell = table[0, col_idx]
+        cell.set_facecolor("#2c5f8a")
+        cell.set_text_props(color="white", fontweight="bold")
+
+    # Alternate row shading
+    for row_idx in range(1, n_rows + 1):
+        bg = "#f0f4f8" if row_idx % 2 == 0 else "white"
+        for col_idx in range(n_cols):
+            table[row_idx, col_idx].set_facecolor(bg)
+
+    return fig
+
+
+def _analysis_result_to_figure(result: dict) -> Figure:
+    """Render one analysis result dict as a text Figure.
+
+    Parameters
+    ----------
+    result:
+        A dict with keys ``type``, ``dataset``, ``timestamp``, and
+        ``results`` (the actual analysis output dict).
+
+    Returns
+    -------
+    Figure
+        A matplotlib Figure (caller is responsible for closing it).
+    """
+    fig = plt.figure(figsize=(8.5, 6), facecolor="white")
+    ax = fig.add_axes((0.05, 0.05, 0.90, 0.90))
+    ax.set_axis_off()
+
+    r_type = result.get("type", "analysis")
+    r_dataset = result.get("dataset", "—")
+    r_ts = result.get("timestamp", "")[:19].replace("T", " ")
+
+    heading = f"{r_type}  ·  dataset: {r_dataset}  ·  {r_ts}"
+    ax.set_title(heading, fontsize=11, fontweight="bold", pad=10)
+
+    ax.plot([0, 1], [0.96, 0.96], color="#cccccc", linewidth=0.8, transform=ax.transAxes)
+
+    raw_results = result.get("results", {})
+
+    def _fmt_value(v) -> str:
+        """Convert a value to a display string, skipping callables."""
+        if callable(v):
+            return "<function>"
+        if isinstance(v, np.ndarray):
+            if v.size <= 8:
+                return np.array2string(v, precision=5, suppress_small=True)
+            return f"array(shape={v.shape}, dtype={v.dtype})"
+        if isinstance(v, float):
+            return f"{v:.6g}"
+        if isinstance(v, dict):
+            return (
+                "{" + ", ".join(f"{k}: {_fmt_value(val)}" for k, val in list(v.items())[:6]) + "}"
+            )
+        if isinstance(v, (list, tuple)) and len(v) > 8:
+            return f"[{type(v).__name__} of length {len(v)}]"
+        return str(v)[:120]
+
+    if not raw_results:
+        ax.text(
+            0.5,
+            0.5,
+            "(no results data)",
+            ha="center",
+            va="center",
+            fontsize=10,
+            color="#888888",
+            transform=ax.transAxes,
+        )
+        return fig
+
+    lines: list[str] = []
+    for key, val in raw_results.items():
+        if callable(val):
+            continue
+        lines.append(f"{key}:  {_fmt_value(val)}")
+
+    # Render as evenly-spaced text lines
+    n = len(lines)
+    y_start = 0.88
+    y_step = min(0.07, 0.80 / max(n, 1))
+    for i, line in enumerate(lines):
+        ax.text(
+            0.02,
+            y_start - i * y_step,
+            line,
+            fontsize=9,
+            family="monospace",
+            va="top",
+            transform=ax.transAxes,
+            color="#222222",
+        )
+
+    return fig
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+
+def generate_pdf_report(
+    filepath: str | Path,
+    title: str,
+    plot_entries: list[dict],
+    datasets: dict[str, pd.DataFrame],
+    analysis_results: list[dict],
+    author: str = "",
+    dpi: int = 150,
+) -> Path:
+    """Write a PDF report and return the output Path.
+
+    Parameters
+    ----------
+    filepath:
+        Destination path for the PDF file.
+    title:
+        Report title string (shown on the title page).
+    plot_entries:
+        List of plot history dicts (from ``st.session_state.plot_history``).
+        Each dict may have keys ``type``, ``dataset``, ``timestamp``, and
+        ``figure`` (a matplotlib Figure, a Plotly Figure, or None).
+        Plotly figures and ``None`` entries are silently skipped.
+    datasets:
+        Mapping of dataset name → value.  Only ``pd.DataFrame`` values are
+        included; other types are skipped.
+    analysis_results:
+        List of analysis result dicts (from ``st.session_state.analysis_results``).
+        Each dict should have keys ``type``, ``dataset``, ``timestamp``, and
+        ``results``.
+    author:
+        Optional author name for the title page and PDF metadata.
+    dpi:
+        Resolution used when rasterising matplotlib figures (default 150).
+
+    Returns
+    -------
+    Path
+        The path of the written PDF file.
+    """
+    try:
+        from matplotlib.figure import Figure as MplFigure
+
+        _mpl_figure_cls: type | None = MplFigure
+    except ImportError:
+        _mpl_figure_cls = None
+
+    # Count how many matplotlib plots will actually be written
+    mpl_plot_count = sum(
+        1
+        for e in plot_entries
+        if _mpl_figure_cls is not None and isinstance(e.get("figure"), _mpl_figure_cls)
+    )
+    df_count = sum(1 for v in datasets.values() if isinstance(v, pd.DataFrame))
+    analysis_count = len(analysis_results)
+
+    filepath = Path(filepath)
+
+    with PdfPages(str(filepath)) as pdf:
+        # ── Title page ────────────────────────────────────────────────────
+        title_fig = _make_title_page(
+            title=title,
+            author=author,
+            n_plots=mpl_plot_count,
+            n_datasets=df_count,
+            n_analyses=analysis_count,
+        )
+        pdf.savefig(title_fig, dpi=dpi, bbox_inches="tight")
+        plt.close(title_fig)
+
+        # ── Plot pages ────────────────────────────────────────────────────
+        for entry in plot_entries:
+            fig = entry.get("figure")
+            if fig is None:
+                continue
+            if _mpl_figure_cls is not None and isinstance(fig, _mpl_figure_cls):
+                pdf.savefig(fig, dpi=dpi, bbox_inches="tight")
+            # Plotly figures are silently skipped
+
+        # ── Dataset pages ─────────────────────────────────────────────────
+        for name, data in datasets.items():
+            if not isinstance(data, pd.DataFrame):
+                continue
+            df_fig = _dataframe_to_figure(data, title=f"Dataset: {name}")
+            pdf.savefig(df_fig, dpi=dpi, bbox_inches="tight")
+            plt.close(df_fig)
+
+        # ── Analysis result pages ─────────────────────────────────────────
+        for result in analysis_results:
+            res_fig = _analysis_result_to_figure(result)
+            pdf.savefig(res_fig, dpi=dpi, bbox_inches="tight")
+            plt.close(res_fig)
+
+        # ── PDF metadata ──────────────────────────────────────────────────
+        info = pdf.infodict()
+        info["Title"] = title
+        info["Author"] = author
+        info["Subject"] = "EaglePlot session report"
+        info["Creator"] = "EaglePlot"
+
+    return filepath