eagleplot 3.0.0__tar.gz

eagleplot-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan D. Schultz, North Carolina Central University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eagleplot-3.0.0/PKG-INFO

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: eagleplot
+Version: 3.0.0
+Summary: A general-purpose Python toolkit for scientific data visualization and analysis
+Author-email: "Jonathan D. Schultz" <jschult3@nccu.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/The-Schultz-Lab/eagleplot
+Project-URL: Repository, https://github.com/The-Schultz-Lab/eagleplot
+Project-URL: Documentation, https://the-schultz-lab.github.io/eagleplot/
+Project-URL: Bug Tracker, https://github.com/The-Schultz-Lab/eagleplot/issues
+Project-URL: Changelog, https://github.com/The-Schultz-Lab/eagleplot/blob/main/CHANGELOG.md
+Keywords: visualization,plotting,science,chemistry,matplotlib,plotly,streamlit
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: !=3.9.7,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: seaborn>=0.12.0
+Requires-Dist: plotly>=5.14.0
+Requires-Dist: streamlit>=1.49.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tomli>=2.0.0; python_version < "3.11"
+Provides-Extra: formats
+Requires-Dist: h5py>=3.0.0; extra == "formats"
+Requires-Dist: xarray>=0.20.0; extra == "formats"
+Requires-Dist: netcdf4>=1.6.0; extra == "formats"
+Provides-Extra: nist
+Requires-Dist: requests>=2.28.0; extra == "nist"
+Provides-Extra: docs
+Requires-Dist: markdown>=3.5; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: eagleplot[test]; extra == "dev"
+Requires-Dist: ruff==0.17.3; extra == "dev"
+Requires-Dist: mypy==2.4.1; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.12.20250915; extra == "dev"
+Requires-Dist: types-requests>=2.28.0; extra == "dev"
+Requires-Dist: build>=1.4.3; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: eagleplot[formats,nist]; extra == "all"
+Dynamic: license-file
+
+# EaglePlot
+
+[![Tests](https://github.com/The-Schultz-Lab/eagleplot/actions/workflows/tests.yml/badge.svg)](https://github.com/The-Schultz-Lab/eagleplot/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/eagleplot)](https://pypi.org/project/eagleplot/)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/The-Schultz-Lab/eagleplot/main)
+
+A general-purpose Python toolkit for scientific data visualization and analysis, developed for research and teaching in computational science at North Carolina Central University.
+
+> **EaglePlot was called Plottle until version 3.0.** If you used Plottle, change
+> `import plottle` / `from plottle.… import …` to `eagleplot`, and run the `eagleplot`
+> command instead of `plottle`. Session files saved by Plottle still load.
+
+## Overview
+
+EaglePlot provides a unified interface for scientific data work:
+
+- **Data I/O** — 18 file formats (CSV, Excel, TSV, JSON, Parquet, NumPy, Pickle, JCAMP-DX, HDF5, NetCDF, SPC, ASC, mzML/mzXML, and more)
+- **Mathematical analysis** — statistics, curve fitting, signal processing, peak analysis, hypothesis testing, optimization, linear algebra
+- **Multi-library plotting** — 27 plot types across Matplotlib (static), Seaborn (statistical), and Plotly (interactive)
+- **14-page Streamlit GUI** — exploratory data analysis without writing code
+- **CLI** — batch processing and scripted workflows
+- **Plugin system** — drop `plugin_*.py` into `plugins/` for custom plot types and tools
+
+## Quick Start
+
+### Clone the repository
+
+#### 1 — Clone and enter the repository
+
+```bash
+git clone https://github.com/The-Schultz-Lab/eagleplot.git
+cd eagleplot
+```
+
+#### 2 — Set up and launch (double-click, no terminal needed)
+
+**Windows:**
+1. Double-click **`setup.bat`** — creates the virtual environment and installs all dependencies.
+2. Double-click **`launch.bat`** — starts EaglePlot. Use this every time you want to open the app.
+
+**macOS:**
+1. Double-click **`setup.command`** — creates the virtual environment and installs all dependencies.
+   *(If macOS asks "Are you sure you want to open it?", click Open.)*
+2. Double-click **`launch.command`** — starts EaglePlot. Use this every time you want to open the app.
+
+**Linux:**
+1. Run **`./setup.sh`** in a terminal — creates the virtual environment and installs all dependencies.
+   *(On Debian/Ubuntu you may first need `sudo apt install python3-venv`.)*
+2. Run **`./launch.sh`** — starts EaglePlot.
+
+After the app starts, open **`http://localhost:8501`** in your browser (Streamlit usually opens it automatically).
+
+#### 2 (alternative) — Set up and launch from the terminal
+
+```bash
+python -m venv .venv
+
+# Windows
+.venv\Scripts\activate
+
+# macOS / Linux
+source .venv/bin/activate
+
+# Install EaglePlot and its dependencies. The editable install is what puts the
+# `eagleplot` command on your PATH.
+pip install -e ".[formats,nist]"
+
+streamlit run eagleplot/Home.py
+```
+
+#### 3 — Or use the CLI
+
+```bash
+eagleplot --help
+eagleplot plot data.csv --plot scatter --x-column x --y-column y
+eagleplot stats data.csv
+```
+
+The `eagleplot` command comes from the `pip install` above. From a source checkout
+without installing, use `python -m eagleplot.cli` instead.
+
+## GUI Pages
+
+| Page | Description |
+| --- | --- |
+| **Home** | Dashboard overview and help tabs |
+| **1 — Data Upload** | Upload files in 18 formats; preview shape, column types, and summary statistics; batch folder import |
+| **2 — Quick Plot** | 27 plot types with live style controls, annotation panel, and Convert to Plotly toggle |
+| **3 — Analysis Tools** | 8 tabs: Statistics, Distribution, Curve Fit, Optimization, Linear Algebra, Signal Processing, Peak Analysis, Statistical Tests |
+| **4 — Multi-Plot Dashboard** | Up to 4×4 grid layouts with axis sharing and combined PNG/PDF export |
+| **5 — Advanced Plotting** | Seaborn statistical plots and Plotly interactive charts with HTML export |
+| **7 — Export Results** | Export plots, data, and analyses; save/load full sessions; generate PDF reports |
+| **8 — Gallery** | Pre-generated figure gallery with Load this config buttons |
+| **9 — Data Tools** | 10 operation tabs: formula columns, normalization, transpose, pivot/melt, filter, sort, merge, fill/drop NaN, resample, rolling transforms |
+| **10 — Spectroscopy** | IR/Raman, NMR, UV-Vis, Mass Spec tools; NIST WebBook spectral lookup by CAS number |
+| **11 — Molecular Viz** | Upload Gaussian/ORCA/Molden output files; 3D molecular structure and vibrational mode display |
+| **12 — Batch Analysis** | Batch statistics, curve fitting, and peak analysis with workflow presets |
+| **13 — Help** | Getting Started, Plot Types, Analysis Tools, Supported Formats, Tips |
+| **14 — Settings** | Theme, DPI, plot defaults, named preset CRUD, plugin status |
+
+## Supported File Formats (18)
+
+| Category | Formats |
+| --- | --- |
+| Tabular | `.csv`, `.tsv`, `.xlsx`, `.xls`, `.json`, `.parquet` |
+| Array | `.npy`, `.npz`, `.pkl` |
+| Instrument / Spectral | `.jdx` / `.dx` (JCAMP-DX), `.h5` / `.hdf5` (HDF5), `.nc` / `.cdf` (NetCDF), `.spc` (Thermo Fisher), `.asc` (generic text), `.mzml` / `.mzxml` (mass spectrometry, optional) |
+
+## CLI
+
+EaglePlot includes a command-line interface with 5 subcommands:
+
+```bash
+eagleplot plot    <file> --plot <type> --x-column X --y-column Y [--output out.png]
+eagleplot stats  <file>
+eagleplot batch  <config.json> [--verbose]
+eagleplot compare <file1> <file2> --plot line [--output comparison.png]
+eagleplot convert <input> <output>
+```
+
+See the [CLI Tutorial](docs/tutorials/cli_guide.md) for full usage and examples.
+
+## Python API
+
+EaglePlot's modules can be used directly in scripts or Jupyter notebooks:
+
+```python
+from eagleplot.io import load_data
+from eagleplot.plotting import line_plot, save_figure
+import numpy as np
+
+wavelength = np.linspace(400, 800, 200)
+absorbance = 0.8 * np.exp(-((wavelength - 520) ** 2) / (2 * 30**2))
+
+fig, ax, info = line_plot(
+    wavelength,
+    [absorbance],
+    xlabel="Wavelength (nm)",
+    ylabel="Absorbance",
+    title="UV-Vis Spectrum",
+    labels=["Sample A"],
+)
+save_figure(fig, "spectrum.png", dpi=300)
+```
+
+### Key modules
+
+| Module | Description |
+| --- | --- |
+| `eagleplot.io` | `load_data()` / `save_data()` — auto-detects format from extension |
+| `eagleplot.math` | 25 functions — statistics, curve fitting, hypothesis tests, optimization, linear algebra |
+| `eagleplot.plotting` | 27 plot types; Matplotlib → `(fig, ax, info)`, Plotly → `(fig, info)` |
+| `eagleplot.signal` | 16 functions — smoothing, filtering, FFT, derivatives, baseline correction, interpolation |
+| `eagleplot.peaks` | 5 functions — find, integrate, FWHM, fit (Gaussian/Lorentzian/Voigt/pseudo-Voigt) |
+| `eagleplot.data_tools` | 12 non-destructive DataFrame operations |
+| `eagleplot.spectroscopy` | 18 functions — IR/Raman, UV-Vis, NMR, MS |
+| `eagleplot.nist` | NIST WebBook integration — fetch IR spectra by CAS number |
+| `eagleplot.batch` | Batch load, statistics, curve fit, peak analysis |
+| `eagleplot.annotations` | 7 overlay types (hline, vline, hspan, vspan, text, rectangle, ellipse) |
+| `eagleplot.report` | PDF report generation via `matplotlib.PdfPages` |
+| `eagleplot.molecular` | CPK atom data, Gaussian/ORCA/Molden parsers, Plotly 3D molecule builder |
+
+## Plugin System
+
+Drop a `plugin_*.py` file into `plugins/` to add custom plot types or analysis tools.
+See [`plugins/plugin_example.py`](plugins/plugin_example.py) for the starter template.
+
+## Dependencies
+
+| Package | Purpose |
+| --- | --- |
+| `numpy` | Numerical computing |
+| `scipy` | Scientific algorithms, curve fitting, signal processing |
+| `pandas` | Tabular data |
+| `matplotlib` | Static plotting |
+| `seaborn` | Statistical visualizations |
+| `plotly` | Interactive plots |
+| `streamlit` | GUI framework |
+| `openpyxl` | Excel file support |
+| `requests` | NIST WebBook HTTP integration |
+| `h5py` | HDF5 file support |
+| `xarray` / `netcdf4` | NetCDF file support |
+
+**Optional:**
+
+| Package | Purpose |
+| --- | --- |
+| `statsmodels` | Two-way ANOVA (`anova_twoway` in `eagleplot.math`) |
+| `pymzml` | mzML/mzXML mass spectrometry files |
+| `jcamp` | Alternative JCAMP-DX parser |
+
+See [`requirements.txt`](requirements.txt) for pinned version ranges.
+
+## Project Structure
+
+```text
+eagleplot/                            ← repository root
+├── eagleplot/                        ← the installable package
+│   ├── Home.py                     ← Streamlit entry point
+│   ├── cli.py                      ← CLI entry point (5 subcommands)
+│   ├── io.py                       ← 18-format data loader/saver
+│   ├── math.py                     ← 25 analysis functions
+│   ├── plotting.py                 ← 27 plot types (Matplotlib, Seaborn, Plotly)
+│   ├── signal.py                   ← 16 signal processing functions
+│   ├── peaks.py                    ← 5 peak analysis functions
+│   ├── data_tools.py               ← 12 non-destructive DataFrame operations
+│   ├── annotations.py              ← 7 Matplotlib overlay types
+│   ├── spectroscopy.py             ← 18 spectroscopy functions
+│   ├── nist.py                     ← NIST WebBook integration
+│   ├── batch.py                    ← 5 batch processing functions
+│   ├── report.py                   ← PDF report generation
+│   ├── plugin_loader.py            ← plugin discovery and loading
+│   ├── molecular/                  ← CPK atom data + vibrational parsers
+│   ├── pages/                      ← 13 Streamlit pages (1_*.py – 13_*.py)
+│   ├── utils/                      ← session state, plot config, user settings
+│   ├── assets/                     ← logo + NCCU branding (shipped in the wheel)
+│   ├── gallery/                    ← pre-rendered gallery PNGs + manifest.json
+│   └── example-data/Artificial/    ← built-in sample datasets
+├── tests/                          ← pytest suite, 1,000+ tests
+├── plugins/                        ← plugin_example.py starter template
+├── examples/                       ← 15+ standalone scripts + batch_config.json
+├── docs/                           ← tutorials, cheatsheet, site built by build_docs.py
+├── generate_gallery.py             ← regenerates eagleplot/gallery/
+├── requirements.txt
+├── pyproject.toml
+├── setup.bat / .command / .sh      ← First-run setup (Windows / macOS / Linux)
+└── launch.bat / .command / .sh     ← App launcher (Windows / macOS / Linux)
+```
+
+Runtime assets (`assets/`, `gallery/`, `example-data/`) live **inside** the package
+rather than at the repository root, so they are present after `pip install`.
+
+## Documentation
+
+- [Getting Started](docs/getting_started.md) — installation walkthrough and API examples
+- [Cheatsheet](docs/cheatsheet.md) — quick reference for all plot functions
+- [CLI Tutorial](docs/tutorials/cli_guide.md) — step-by-step guide to all 5 CLI commands
+- [GUI Tutorial](docs/tutorials/gui_guide.md) — page-by-page walkthrough of the Streamlit app
+- [Examples](examples/) — 15+ standalone runnable scripts covering all major workflows
+
+## About
+
+**Author:** Jonathan D. Schultz, PhD — NCCU Department of Chemistry and Biochemistry
+**Institution:** North Carolina Central University
+**Use:** Research and teaching in computational science
+**License:** See [LICENSE](LICENSE)

eagleplot-3.0.0/README.md

@@ -0,0 +1,246 @@
+# EaglePlot
+
+[![Tests](https://github.com/The-Schultz-Lab/eagleplot/actions/workflows/tests.yml/badge.svg)](https://github.com/The-Schultz-Lab/eagleplot/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/eagleplot)](https://pypi.org/project/eagleplot/)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/The-Schultz-Lab/eagleplot/main)
+
+A general-purpose Python toolkit for scientific data visualization and analysis, developed for research and teaching in computational science at North Carolina Central University.
+
+> **EaglePlot was called Plottle until version 3.0.** If you used Plottle, change
+> `import plottle` / `from plottle.… import …` to `eagleplot`, and run the `eagleplot`
+> command instead of `plottle`. Session files saved by Plottle still load.
+
+## Overview
+
+EaglePlot provides a unified interface for scientific data work:
+
+- **Data I/O** — 18 file formats (CSV, Excel, TSV, JSON, Parquet, NumPy, Pickle, JCAMP-DX, HDF5, NetCDF, SPC, ASC, mzML/mzXML, and more)
+- **Mathematical analysis** — statistics, curve fitting, signal processing, peak analysis, hypothesis testing, optimization, linear algebra
+- **Multi-library plotting** — 27 plot types across Matplotlib (static), Seaborn (statistical), and Plotly (interactive)
+- **14-page Streamlit GUI** — exploratory data analysis without writing code
+- **CLI** — batch processing and scripted workflows
+- **Plugin system** — drop `plugin_*.py` into `plugins/` for custom plot types and tools
+
+## Quick Start
+
+### Clone the repository
+
+#### 1 — Clone and enter the repository
+
+```bash
+git clone https://github.com/The-Schultz-Lab/eagleplot.git
+cd eagleplot
+```
+
+#### 2 — Set up and launch (double-click, no terminal needed)
+
+**Windows:**
+1. Double-click **`setup.bat`** — creates the virtual environment and installs all dependencies.
+2. Double-click **`launch.bat`** — starts EaglePlot. Use this every time you want to open the app.
+
+**macOS:**
+1. Double-click **`setup.command`** — creates the virtual environment and installs all dependencies.
+   *(If macOS asks "Are you sure you want to open it?", click Open.)*
+2. Double-click **`launch.command`** — starts EaglePlot. Use this every time you want to open the app.
+
+**Linux:**
+1. Run **`./setup.sh`** in a terminal — creates the virtual environment and installs all dependencies.
+   *(On Debian/Ubuntu you may first need `sudo apt install python3-venv`.)*
+2. Run **`./launch.sh`** — starts EaglePlot.
+
+After the app starts, open **`http://localhost:8501`** in your browser (Streamlit usually opens it automatically).
+
+#### 2 (alternative) — Set up and launch from the terminal
+
+```bash
+python -m venv .venv
+
+# Windows
+.venv\Scripts\activate
+
+# macOS / Linux
+source .venv/bin/activate
+
+# Install EaglePlot and its dependencies. The editable install is what puts the
+# `eagleplot` command on your PATH.
+pip install -e ".[formats,nist]"
+
+streamlit run eagleplot/Home.py
+```
+
+#### 3 — Or use the CLI
+
+```bash
+eagleplot --help
+eagleplot plot data.csv --plot scatter --x-column x --y-column y
+eagleplot stats data.csv
+```
+
+The `eagleplot` command comes from the `pip install` above. From a source checkout
+without installing, use `python -m eagleplot.cli` instead.
+
+## GUI Pages
+
+| Page | Description |
+| --- | --- |
+| **Home** | Dashboard overview and help tabs |
+| **1 — Data Upload** | Upload files in 18 formats; preview shape, column types, and summary statistics; batch folder import |
+| **2 — Quick Plot** | 27 plot types with live style controls, annotation panel, and Convert to Plotly toggle |
+| **3 — Analysis Tools** | 8 tabs: Statistics, Distribution, Curve Fit, Optimization, Linear Algebra, Signal Processing, Peak Analysis, Statistical Tests |
+| **4 — Multi-Plot Dashboard** | Up to 4×4 grid layouts with axis sharing and combined PNG/PDF export |
+| **5 — Advanced Plotting** | Seaborn statistical plots and Plotly interactive charts with HTML export |
+| **7 — Export Results** | Export plots, data, and analyses; save/load full sessions; generate PDF reports |
+| **8 — Gallery** | Pre-generated figure gallery with Load this config buttons |
+| **9 — Data Tools** | 10 operation tabs: formula columns, normalization, transpose, pivot/melt, filter, sort, merge, fill/drop NaN, resample, rolling transforms |
+| **10 — Spectroscopy** | IR/Raman, NMR, UV-Vis, Mass Spec tools; NIST WebBook spectral lookup by CAS number |
+| **11 — Molecular Viz** | Upload Gaussian/ORCA/Molden output files; 3D molecular structure and vibrational mode display |
+| **12 — Batch Analysis** | Batch statistics, curve fitting, and peak analysis with workflow presets |
+| **13 — Help** | Getting Started, Plot Types, Analysis Tools, Supported Formats, Tips |
+| **14 — Settings** | Theme, DPI, plot defaults, named preset CRUD, plugin status |
+
+## Supported File Formats (18)
+
+| Category | Formats |
+| --- | --- |
+| Tabular | `.csv`, `.tsv`, `.xlsx`, `.xls`, `.json`, `.parquet` |
+| Array | `.npy`, `.npz`, `.pkl` |
+| Instrument / Spectral | `.jdx` / `.dx` (JCAMP-DX), `.h5` / `.hdf5` (HDF5), `.nc` / `.cdf` (NetCDF), `.spc` (Thermo Fisher), `.asc` (generic text), `.mzml` / `.mzxml` (mass spectrometry, optional) |
+
+## CLI
+
+EaglePlot includes a command-line interface with 5 subcommands:
+
+```bash
+eagleplot plot    <file> --plot <type> --x-column X --y-column Y [--output out.png]
+eagleplot stats  <file>
+eagleplot batch  <config.json> [--verbose]
+eagleplot compare <file1> <file2> --plot line [--output comparison.png]
+eagleplot convert <input> <output>
+```
+
+See the [CLI Tutorial](docs/tutorials/cli_guide.md) for full usage and examples.
+
+## Python API
+
+EaglePlot's modules can be used directly in scripts or Jupyter notebooks:
+
+```python
+from eagleplot.io import load_data
+from eagleplot.plotting import line_plot, save_figure
+import numpy as np
+
+wavelength = np.linspace(400, 800, 200)
+absorbance = 0.8 * np.exp(-((wavelength - 520) ** 2) / (2 * 30**2))
+
+fig, ax, info = line_plot(
+    wavelength,
+    [absorbance],
+    xlabel="Wavelength (nm)",
+    ylabel="Absorbance",
+    title="UV-Vis Spectrum",
+    labels=["Sample A"],
+)
+save_figure(fig, "spectrum.png", dpi=300)
+```
+
+### Key modules
+
+| Module | Description |
+| --- | --- |
+| `eagleplot.io` | `load_data()` / `save_data()` — auto-detects format from extension |
+| `eagleplot.math` | 25 functions — statistics, curve fitting, hypothesis tests, optimization, linear algebra |
+| `eagleplot.plotting` | 27 plot types; Matplotlib → `(fig, ax, info)`, Plotly → `(fig, info)` |
+| `eagleplot.signal` | 16 functions — smoothing, filtering, FFT, derivatives, baseline correction, interpolation |
+| `eagleplot.peaks` | 5 functions — find, integrate, FWHM, fit (Gaussian/Lorentzian/Voigt/pseudo-Voigt) |
+| `eagleplot.data_tools` | 12 non-destructive DataFrame operations |
+| `eagleplot.spectroscopy` | 18 functions — IR/Raman, UV-Vis, NMR, MS |
+| `eagleplot.nist` | NIST WebBook integration — fetch IR spectra by CAS number |
+| `eagleplot.batch` | Batch load, statistics, curve fit, peak analysis |
+| `eagleplot.annotations` | 7 overlay types (hline, vline, hspan, vspan, text, rectangle, ellipse) |
+| `eagleplot.report` | PDF report generation via `matplotlib.PdfPages` |
+| `eagleplot.molecular` | CPK atom data, Gaussian/ORCA/Molden parsers, Plotly 3D molecule builder |
+
+## Plugin System
+
+Drop a `plugin_*.py` file into `plugins/` to add custom plot types or analysis tools.
+See [`plugins/plugin_example.py`](plugins/plugin_example.py) for the starter template.
+
+## Dependencies
+
+| Package | Purpose |
+| --- | --- |
+| `numpy` | Numerical computing |
+| `scipy` | Scientific algorithms, curve fitting, signal processing |
+| `pandas` | Tabular data |
+| `matplotlib` | Static plotting |
+| `seaborn` | Statistical visualizations |
+| `plotly` | Interactive plots |
+| `streamlit` | GUI framework |
+| `openpyxl` | Excel file support |
+| `requests` | NIST WebBook HTTP integration |
+| `h5py` | HDF5 file support |
+| `xarray` / `netcdf4` | NetCDF file support |
+
+**Optional:**
+
+| Package | Purpose |
+| --- | --- |
+| `statsmodels` | Two-way ANOVA (`anova_twoway` in `eagleplot.math`) |
+| `pymzml` | mzML/mzXML mass spectrometry files |
+| `jcamp` | Alternative JCAMP-DX parser |
+
+See [`requirements.txt`](requirements.txt) for pinned version ranges.
+
+## Project Structure
+
+```text
+eagleplot/                            ← repository root
+├── eagleplot/                        ← the installable package
+│   ├── Home.py                     ← Streamlit entry point
+│   ├── cli.py                      ← CLI entry point (5 subcommands)
+│   ├── io.py                       ← 18-format data loader/saver
+│   ├── math.py                     ← 25 analysis functions
+│   ├── plotting.py                 ← 27 plot types (Matplotlib, Seaborn, Plotly)
+│   ├── signal.py                   ← 16 signal processing functions
+│   ├── peaks.py                    ← 5 peak analysis functions
+│   ├── data_tools.py               ← 12 non-destructive DataFrame operations
+│   ├── annotations.py              ← 7 Matplotlib overlay types
+│   ├── spectroscopy.py             ← 18 spectroscopy functions
+│   ├── nist.py                     ← NIST WebBook integration
+│   ├── batch.py                    ← 5 batch processing functions
+│   ├── report.py                   ← PDF report generation
+│   ├── plugin_loader.py            ← plugin discovery and loading
+│   ├── molecular/                  ← CPK atom data + vibrational parsers
+│   ├── pages/                      ← 13 Streamlit pages (1_*.py – 13_*.py)
+│   ├── utils/                      ← session state, plot config, user settings
+│   ├── assets/                     ← logo + NCCU branding (shipped in the wheel)
+│   ├── gallery/                    ← pre-rendered gallery PNGs + manifest.json
+│   └── example-data/Artificial/    ← built-in sample datasets
+├── tests/                          ← pytest suite, 1,000+ tests
+├── plugins/                        ← plugin_example.py starter template
+├── examples/                       ← 15+ standalone scripts + batch_config.json
+├── docs/                           ← tutorials, cheatsheet, site built by build_docs.py
+├── generate_gallery.py             ← regenerates eagleplot/gallery/
+├── requirements.txt
+├── pyproject.toml
+├── setup.bat / .command / .sh      ← First-run setup (Windows / macOS / Linux)
+└── launch.bat / .command / .sh     ← App launcher (Windows / macOS / Linux)
+```
+
+Runtime assets (`assets/`, `gallery/`, `example-data/`) live **inside** the package
+rather than at the repository root, so they are present after `pip install`.
+
+## Documentation
+
+- [Getting Started](docs/getting_started.md) — installation walkthrough and API examples
+- [Cheatsheet](docs/cheatsheet.md) — quick reference for all plot functions
+- [CLI Tutorial](docs/tutorials/cli_guide.md) — step-by-step guide to all 5 CLI commands
+- [GUI Tutorial](docs/tutorials/gui_guide.md) — page-by-page walkthrough of the Streamlit app
+- [Examples](examples/) — 15+ standalone runnable scripts covering all major workflows
+
+## About
+
+**Author:** Jonathan D. Schultz, PhD — NCCU Department of Chemistry and Biochemistry
+**Institution:** North Carolina Central University
+**Use:** Research and teaching in computational science
+**License:** See [LICENSE](LICENSE)