EaglePlot › Getting Started

Getting Started — EaglePlot

NCCU Department of Chemistry and Biochemistry

What Is This Tool?

EaglePlot is a Python toolkit plus Streamlit GUI that makes scientific data visualization straightforward for computational chemists and physical scientists. It wraps Matplotlib, Seaborn, and Plotly behind a clean API and an interactive point-and-click interface.

You can use it two ways:

Installation

Step 1 — Clone the repository

git clone https://github.com/The-Schultz-Lab/eagleplot.git
cd eagleplot

Step 2 — Create a virtual environment

python -m venv .venv

Step 3 — Activate the environment

Windows

.venv\Scripts\activate.bat

macOS / Linux

source .venv/bin/activate

Step 4 — Install EaglePlot

pip install -e ".[formats,nist]"

The formats extra adds HDF5 and NetCDF support; nist adds the NIST WebBook lookup. The editable install is also what puts the eagleplot command on your PATH.

Step 5 — Verify

python -c "import streamlit, numpy, pandas, matplotlib, seaborn, plotly; print('Ready!')"

Launching the GUI

Windows — double-click launch.bat or run from a terminal

launch.bat

Any platform

streamlit run eagleplot/Home.py

Open http://localhost:8501 in your browser. Use the sidebar to navigate between pages.

Your First Plot (GUI)

1. Data Upload — upload a CSV or drag-and-drop a .npy file.
2. Quick Plot — select your dataset, choose "Line Plot", pick X and Y columns.
3. Click Generate Plot — your figure appears instantly.
4. Expand Export plot & data to download PNG, SVG, PDF, or CSV.

Your First Plot (Python API)

import numpy as np
import sys

sys.path.insert(0, "path/to/eagleplot")

from eagleplot.plotting import line_plot, save_figure

# Simulate absorbance vs. wavelength
wavelength = np.linspace(400, 800, 200)
absorbance = 0.8 * np.exp(-((wavelength - 520) ** 2) / (2 * 30**2))

fig, ax = line_plot(
    wavelength,
    [absorbance],
    xlabel="Wavelength (nm)",
    ylabel="Absorbance",
    title="UV-Vis Spectrum",
    labels=["Sample A"],
)

save_figure(fig, "spectrum.png", dpi=300)

Loading Data

The eagleplot.io module supports eight common formats.

from eagleplot.io import load_data, save_data

# Auto-detect format from extension
df = load_data("experiment.csv")  # → pandas DataFrame
arr = load_data("matrix.npy")  # → numpy array
obj = load_data("session.pkl")  # → any Python object

Supported extensions:

Computing Statistics

from eagleplot.math import calculate_statistics

stats = calculate_statistics(arr)
print(f"Mean: {stats['mean']:.4f}")
print(f"Std:  {stats['std']:.4f}")
print(f"R:    [{stats['min']:.3f}, {stats['max']:.3f}]")

Returns: mean, median, std, var, min, max, q1, q3, iqr, range.

Curve Fitting

from eagleplot.math import fit_linear, fit_polynomial

# Beer-Lambert: A = ε·c·l  →  linear fit
result = fit_linear(concentration, absorbance)
print(f"Slope (ε·l):  {result['slope']:.4f}")
print(f"R²:           {result['r_squared']:.4f}")

# Polynomial fit (degree 2)
poly = fit_polynomial(x, y, degree=2)
y_fit = poly["predict"](x)  # call the returned predict function

All Plot Types

Saving Figures

from eagleplot.plotting import save_figure

save_figure(fig, "plot.png", dpi=300)  # high-res raster
save_figure(fig, "plot.svg")  # vector (no dpi needed)
save_figure(fig, "plot.pdf")  # vector, publication-ready

GUI Pages at a Glance

Common Workflows

Beer-Lambert calibration curve

from eagleplot.io import load_dataframe
from eagleplot.math import fit_linear
from eagleplot.plotting import scatter_plot, save_figure
import numpy as np

df = load_dataframe("calibration.csv")  # columns: concentration, absorbance
result = fit_linear(df["concentration"].values, df["absorbance"].values)

x_fit = np.linspace(df["concentration"].min(), df["concentration"].max(), 100)
y_fit = result["slope"] * x_fit + result["intercept"]

fig, ax = scatter_plot(
    df["concentration"].values,
    df["absorbance"].values,
    xlabel="Concentration (mM)",
    ylabel="Absorbance (a.u.)",
    title=f"Beer-Lambert: R² = {result['r_squared']:.4f}",
)
ax.plot(x_fit, y_fit, "r-", linewidth=2, label="Linear fit")
ax.legend()
save_figure(fig, "calibration.png", dpi=300)

Comparing multiple spectra

from eagleplot.plotting import line_plot

fig, ax = line_plot(
    wavelength,
    [spectrum_A, spectrum_B, spectrum_C],
    labels=["Sample A", "Sample B", "Sample C"],
    xlabel="Wavelength (nm)",
    ylabel="Absorbance",
    title="UV-Vis Comparison",
)

Next Steps

• Read the GUI Guide for a tour of every page.
• Read the CLI Guide for scripted and batch workflows.
• Keep the Cheatsheet handy as a quick reference to the Python API.
• Found a problem? See Reporting Bugs.
• Want something added? See Feature Requests.