eagleplot 3.0.0__py3-none-any.whl

eagleplot/pages/11_Batch_Analysis.py

@@ -0,0 +1,325 @@
+"""Batch Analysis Page.
+
+Run statistical summaries, curve fits, and peak analysis across multiple
+loaded datasets simultaneously.  Workflow presets let you save and recall
+named analysis configurations that persist across app restarts via config.json.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+import json
+
+import streamlit as st
+import pandas as pd
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from eagleplot.utils.session_state import initialize_session_state
+from eagleplot.batch import (
+    batch_statistics,
+    batch_curve_fit,
+    batch_peak_analysis,
+)
+from eagleplot.utils.user_settings import (
+    list_workflows,
+    save_workflow,
+    load_workflow,
+    delete_workflow,
+)
+
+initialize_session_state()
+
+st.title("Batch Analysis")
+st.caption(
+    "Run the same analysis across multiple loaded datasets at once. "
+    "Workflow presets let you save and reload named analysis configurations."
+)
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+_RESULT_OUTPUT_COLS = [
+    "dataset",
+    "column",
+    "n",
+    "mean",
+    "median",
+    "std",
+    "min",
+    "max",
+    "q1",
+    "q3",
+    "iqr",
+    "range",
+]
+
+
+def _csv_download(df: pd.DataFrame, filename: str, label: str = "Download CSV") -> None:
+    """Render a CSV download button for *df*."""
+    csv_bytes = df.to_csv(index=False).encode("utf-8")
+    st.download_button(label, data=csv_bytes, file_name=filename, mime="text/csv")
+
+
+# ── top-level tabs ─────────────────────────────────────────────────────────────
+tab_analysis, tab_workflows = st.tabs(["Batch Analysis", "Workflow Presets"])
+
+# ══════════════════════════════════════════════════════════════════════════════
+# TAB 1 — Batch Analysis
+# ══════════════════════════════════════════════════════════════════════════════
+with tab_analysis:
+    # Dataset selection — only DataFrames
+    all_datasets = st.session_state.get("datasets", {})
+    df_datasets = {k: v for k, v in all_datasets.items() if isinstance(v, pd.DataFrame)}
+
+    if not df_datasets:
+        st.warning(
+            "No tabular datasets loaded.  "
+            "Please upload CSV / Excel / TSV / JSON / Parquet files on the "
+            "**Data Upload** page first."
+        )
+        st.stop()
+
+    selected_names = st.multiselect(
+        "Select datasets to analyse",
+        list(df_datasets.keys()),
+        default=list(df_datasets.keys()),
+        key="ba_selected_datasets",
+    )
+
+    if not selected_names:
+        st.info("Select at least one dataset above to continue.")
+        st.stop()
+
+    selected_datasets: dict[str, pd.DataFrame] = {k: df_datasets[k] for k in selected_names}
+
+    # Common columns across all selected datasets
+    common_cols = set.intersection(*(set(df.columns.tolist()) for df in selected_datasets.values()))
+    common_cols_list = sorted(common_cols)
+
+    # ── sub-tabs ──────────────────────────────────────────────────────────────
+    sub_stats, sub_fit, sub_peaks = st.tabs(["Statistics", "Curve Fit", "Peak Analysis"])
+
+    # ── Statistics ────────────────────────────────────────────────────────────
+    with sub_stats:
+        st.subheader("Batch Statistics")
+        st.markdown(
+            "Compute descriptive statistics (mean, median, std, quartiles, …) "
+            "for every selected dataset."
+        )
+
+        col_filter = st.multiselect(
+            "Column filter (leave blank for all columns)",
+            common_cols_list,
+            key="ba_stats_cols",
+            help="Only columns common to all selected datasets are shown here. "
+            "Leave empty to include all columns in each dataset.",
+        )
+
+        if st.button("Run Statistics", key="ba_stats_run"):
+            cols_arg = col_filter if col_filter else None
+            try:
+                result_df = batch_statistics(selected_datasets, columns=cols_arg)
+                st.success(f"Statistics computed for {len(selected_names)} dataset(s).")
+                st.dataframe(result_df, width="stretch")
+                _csv_download(result_df, "batch_statistics.csv")
+            except Exception as exc:
+                st.error(f"Error: {exc}")
+
+    # ── Curve Fit ─────────────────────────────────────────────────────────────
+    with sub_fit:
+        st.subheader("Batch Curve Fit")
+        st.markdown("Fit the same model to the same x/y columns across all selected datasets.")
+
+        fit_x_col = st.text_input("X column name", value="x", key="ba_fit_x")
+        fit_y_col = st.text_input("Y column name", value="y", key="ba_fit_y")
+        fit_type = st.selectbox(
+            "Fit type",
+            ["linear", "polynomial", "exponential"],
+            key="ba_fit_type",
+        )
+
+        fit_degree = 2
+        if fit_type == "polynomial":
+            fit_degree = int(
+                st.number_input(
+                    "Polynomial degree",
+                    min_value=2,
+                    max_value=5,
+                    value=2,
+                    step=1,
+                    key="ba_fit_degree",
+                )
+            )
+
+        if st.button("Run Curve Fit", key="ba_fit_run"):
+            if not fit_x_col.strip() or not fit_y_col.strip():
+                st.warning("Enter both an X column name and a Y column name.")
+            else:
+                try:
+                    result_df = batch_curve_fit(
+                        selected_datasets,
+                        x_col=fit_x_col.strip(),
+                        y_col=fit_y_col.strip(),
+                        fit_type=fit_type,
+                        degree=fit_degree,
+                    )
+                    st.success(f"Curve fit complete for {len(selected_names)} dataset(s).")
+                    st.dataframe(result_df, width="stretch")
+                    _csv_download(result_df, "batch_curve_fit.csv")
+                except Exception as exc:
+                    st.error(f"Error: {exc}")
+
+    # ── Peak Analysis ─────────────────────────────────────────────────────────
+    with sub_peaks:
+        st.subheader("Batch Peak Analysis")
+        st.markdown(
+            "Detect and characterise peaks in the same column across all selected datasets."
+        )
+
+        pa_y_col = st.text_input("Y column (signal)", value="y", key="ba_pa_y")
+        pa_x_col = st.text_input(
+            "X column (optional — leave blank to use row indices)",
+            value="",
+            key="ba_pa_x",
+        )
+
+        pa_use_height = st.checkbox("Set minimum height", value=False, key="ba_pa_use_height")
+        pa_height: float | None = None
+        if pa_use_height:
+            pa_height = st.number_input(
+                "Minimum height (absolute)",
+                value=0.0,
+                step=0.01,
+                format="%.4f",
+                key="ba_pa_height",
+            )
+
+        pa_use_prominence = st.checkbox("Set minimum prominence", value=False, key="ba_pa_use_prom")
+        pa_prominence: float | None = None
+        if pa_use_prominence:
+            pa_prominence = st.number_input(
+                "Minimum prominence (absolute)",
+                value=0.0,
+                step=0.01,
+                format="%.4f",
+                key="ba_pa_prominence",
+            )
+
+        pa_distance = int(
+            st.number_input(
+                "Minimum distance between peaks (samples)",
+                min_value=1,
+                value=1,
+                step=1,
+                key="ba_pa_distance",
+            )
+        )
+
+        if st.button("Run Peak Analysis", key="ba_pa_run"):
+            if not pa_y_col.strip():
+                st.warning("Enter a Y column name.")
+            else:
+                try:
+                    result_df = batch_peak_analysis(
+                        selected_datasets,
+                        y_col=pa_y_col.strip(),
+                        x_col=pa_x_col.strip() if pa_x_col.strip() else None,
+                        height=pa_height,
+                        prominence=pa_prominence,
+                        distance=pa_distance,
+                    )
+                    st.success(f"Peak analysis complete for {len(selected_names)} dataset(s).")
+                    st.dataframe(result_df, width="stretch")
+                    _csv_download(result_df, "batch_peak_analysis.csv")
+                except Exception as exc:
+                    st.error(f"Error: {exc}")
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# TAB 2 — Workflow Presets
+# ══════════════════════════════════════════════════════════════════════════════
+with tab_workflows:
+    st.subheader("Workflow Presets")
+    st.info(
+        "Workflows are saved in **config.json** and persist across app restarts.  "
+        "A workflow is a named list of analysis steps stored as JSON."
+    )
+
+    _TEMPLATE_STEPS = [
+        {"operation": "batch_statistics", "params": {"columns": []}},
+        {
+            "operation": "batch_curve_fit",
+            "params": {"x_col": "x", "y_col": "y", "fit_type": "linear"},
+        },
+    ]
+
+    # ── Load section ──────────────────────────────────────────────────────────
+    st.markdown("### Load a Workflow")
+    existing_workflows = list_workflows()
+
+    if not existing_workflows:
+        st.caption("No workflows saved yet.  Use the **Save** section below to create one.")
+    else:
+        load_name = st.selectbox("Select workflow", existing_workflows, key="wf_load_name")
+        if st.button("Load workflow description", key="wf_load_btn"):
+            try:
+                steps = load_workflow(load_name)
+                st.json(steps)
+            except Exception as exc:
+                st.error(f"Could not load workflow: {exc}")
+
+    st.divider()
+
+    # ── Save section ──────────────────────────────────────────────────────────
+    st.markdown("### Save a Workflow")
+
+    wf_save_name = st.text_input(
+        "Workflow name",
+        value="my_workflow",
+        key="wf_save_name",
+        help="Use a descriptive name; spaces and special characters are allowed.",
+    )
+    wf_json_text = st.text_area(
+        "Workflow steps (JSON list)",
+        value=json.dumps(_TEMPLATE_STEPS, indent=2),
+        height=200,
+        key="wf_json_text",
+        help="Each step is an object with an 'operation' key and a 'params' dict.",
+    )
+
+    if st.button("Save Workflow", key="wf_save_btn"):
+        name = wf_save_name.strip()
+        if not name:
+            st.warning("Enter a workflow name.")
+        else:
+            try:
+                steps = json.loads(wf_json_text)
+                if not isinstance(steps, list):
+                    st.error("Workflow steps must be a JSON **list** (array).")
+                else:
+                    save_workflow(name, steps)
+                    st.success(f"Workflow **{name}** saved.")
+                    st.rerun()
+            except json.JSONDecodeError as exc:
+                st.error(f"Invalid JSON: {exc}")
+            except Exception as exc:
+                st.error(f"Error saving workflow: {exc}")
+
+    st.divider()
+
+    # ── Delete section ────────────────────────────────────────────────────────
+    st.markdown("### Delete a Workflow")
+
+    existing_for_delete = list_workflows()
+    if not existing_for_delete:
+        st.caption("No workflows to delete.")
+    else:
+        del_name = st.selectbox("Select workflow to delete", existing_for_delete, key="wf_del_name")
+        if st.button("Delete", key="wf_del_btn", type="primary"):
+            removed = delete_workflow(del_name)
+            if removed:
+                st.success(f"Workflow **{del_name}** deleted.")
+                st.rerun()
+            else:
+                st.error(f"Workflow **{del_name}** not found.")

eagleplot/pages/12_Help.py

@@ -0,0 +1,199 @@
+"""Help & Documentation page."""
+
+import sys
+from pathlib import Path
+import streamlit as st
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from eagleplot.utils.session_state import initialize_session_state
+
+initialize_session_state()
+
+st.title("Help")
+st.caption("Documentation, quick reference, and tips for using EaglePlot.")
+
+tab_start, tab_plots, tab_analysis, tab_formats, tab_tips = st.tabs(
+    ["Getting Started", "Plot Types", "Analysis Tools", "File Formats", "Tips & Tricks"]
+)
+
+with tab_start:
+    st.markdown("""
+    ## Workflow
+
+    1. **Upload Data** — Go to *Data Upload* and upload a file, or load a built-in example dataset.
+    2. **Quick Plot** — Choose from 27 plot types, configure parameters interactively
+       in the sidebar.
+    3. **Analysis Tools** — Statistical tests, curve fitting, signal processing,
+       peak analysis, and more.
+    4. **Export Results** — Download plots as PNG/PDF/SVG, data as CSV/JSON,
+       or save your full session.
+
+    ## Navigation
+
+    All pages are listed in the left sidebar. Your session data (loaded datasets, plot history)
+    persists as you navigate between pages.
+
+    ## Example Datasets
+
+    Go to *Data Upload → Example Datasets* to load built-in artificial datasets
+    — no file needed. Each one is designed to demonstrate specific plot types.
+    """)
+
+with tab_plots:
+    st.markdown("## 27 Plot Types")
+
+    col1, col2, col3 = st.columns(3)
+    with col1:
+        st.markdown("""
+        **Matplotlib (static)**
+        - Histogram
+        - Line Plot
+        - Scatter Plot
+        - Bar Chart
+        - Heatmap
+        - Contour Plot
+        - Waterfall Plot
+        - Dual Axis Plot
+        - Broken Axis Plot
+        - Inset Plot
+        - Z-Colored Scatter
+        - Bubble Chart
+        - Polar Plot
+        - 2D Histogram / Hexbin
+        - Residual Plot
+        - Scatter with Regression
+        """)
+    with col2:
+        st.markdown("""
+        **Seaborn (statistical)**
+        - Distribution Plot
+        - Box / Violin / Swarm Plot
+        - Regression Plot
+        - Pair Plot
+
+        **Plotly (interactive)**
+        - Interactive Histogram
+        - Interactive Scatter
+        - Interactive Line
+        - Interactive Heatmap
+        - Interactive 3D Surface
+        - Interactive 3D Scatter
+        - Interactive Ternary
+        """)
+    with col3:
+        st.markdown("""
+        **Choosing the right plot**
+
+        | Goal | Plot type |
+        |---|---|
+        | Single distribution | Histogram |
+        | Two-variable relationship | Scatter |
+        | Time series | Line Plot |
+        | Compare groups | Box / Violin |
+        | 2D density | 2D Histogram |
+        | 3-component data | Ternary |
+        | 3D exploration | 3D Scatter |
+        | Matrix data | Heatmap |
+        | Compositions | Polar |
+        """)
+
+    st.markdown("""
+    **Zoom and pan on static plots:** Click *Convert to Plotly* below any matplotlib
+    figure in Quick Plot to get an interactive version.
+    """)
+
+with tab_analysis:
+    st.markdown("""
+    ## Analysis Tools (page 3)
+
+    | Tab | Capabilities |
+    |---|---|
+    | Statistics | Descriptive stats, normality tests, distribution fitting |
+    | Curve Fitting | Linear, polynomial, exponential, custom functions |
+    | Signal Processing | Smoothing, filtering, FFT, baseline correction, derivatives |
+    | Peak Analysis | Auto peak finding, FWHM, integration, Gaussian/Lorentzian/Voigt fitting |
+    | Statistical Tests | t-tests, ANOVA (one-way, two-way), Mann-Whitney, Tukey HSD, chi-square |
+    | Optimization | Function minimization, root finding |
+    | Linear Algebra | Eigenvalues, linear systems, matrix decomposition |
+
+    ## Spectroscopy (page 10)
+
+    | Tab | Capabilities |
+    |---|---|
+    | IR / Raman | ATR correction, spectral subtraction, band assignment, cosmic ray removal |
+    | NMR | Chemical shift calibration, line broadening, FFT, peak picking, integration |
+    | UV-Vis | Beer-Lambert law, molar absorptivity, spectral overlap integral |
+    | Mass Spec | m/z peak finding, centroid spectrum |
+
+    Also includes NIST WebBook lookup (fetch IR spectra by CAS number).
+
+    ## Data Tools (page 9)
+
+    Formula columns, normalization, transpose, pivot/melt, filter, sort, merge,
+    fill/drop NaN, resample, rolling transform.
+    """)
+
+with tab_formats:
+    st.markdown("""
+    ## Supported Input Formats
+
+    | Format | Extensions | Notes |
+    |---|---|---|
+    | CSV | .csv | Auto-detected delimiter |
+    | TSV | .tsv | Tab-separated |
+    | Excel | .xlsx, .xls | First sheet by default |
+    | JSON | .json | Records or columns orientation |
+    | Parquet | .parquet | Apache Parquet columnar |
+    | NumPy | .npy, .npz | Single array or dict of arrays |
+    | Pickle | .pkl | Any Python object |
+    | JCAMP-DX | .jdx, .dx | Spectroscopy (requires `jcamp`) |
+    | HDF5 | .h5, .hdf5 | Hierarchical data (requires `h5py`) |
+    | NetCDF | .nc, .cdf | Climate/scientific arrays (requires `xarray`) |
+    | SPC | .spc | Thermo spectroscopy (requires `spc`) |
+    | ASC | .asc | Generic whitespace-delimited text |
+    | mzML/mzXML | .mzml, .mzxml | Mass spectrometry (requires `pymzml`) |
+
+    ## Export Formats
+
+    **Figures:** PNG (150/300 DPI), SVG, PDF, HTML (Plotly only)
+    **Data:** CSV, JSON, NPY, PKL
+    **Reports:** Multi-page PDF via Export Results page
+    **Session:** Full session save/load (JSON)
+    """)
+
+with tab_tips:
+    col1, col2 = st.columns(2)
+    with col1:
+        st.markdown("### Session Management")
+        st.markdown("""
+        - Datasets persist as you navigate between pages
+        - Use *Export Results → Save Session* to preserve work between restarts
+        - Reload a session from the same Export Results page
+        - Plot history and analysis results are included in saved sessions
+        """)
+
+        st.markdown("### Publication Figures")
+        st.markdown("""
+        - Apply *Publication Style* in the Quick Plot sidebar
+        - Export at 300 DPI from Export Results for print quality
+        - Use SVG export for vector graphics in manuscripts
+        - The colorblind-safe palette (Okabe-Ito) is available in Color Palette settings
+        """)
+
+    with col2:
+        st.markdown("### Performance")
+        st.markdown("""
+        - Files >50 MB or >10,000 rows show a downsampled preview automatically
+        - Full data is always stored; only the preview is reduced
+        - Interactive Plotly plots are slower than Matplotlib for large datasets
+        - Clear plot history in Export Results to free memory
+        """)
+
+        st.markdown("### Plugins")
+        st.markdown("""
+        - Drop `plugin_*.py` files into the `plugins/` directory
+        - Plugins are auto-discovered at startup
+        - See `plugins/plugin_example.py` for the plugin template
+        - Plugin status is shown in Settings (page 6)
+        """)