gmxplot 0.1.0__py3-none-any.whl

gmxplot/escape_codes.py

@@ -0,0 +1,54 @@
+"""GROMACS xmgrace escape code conversion for matplotlib."""
+
+import re
+from typing import Tuple
+
+_GROMACS_FONT_RE = re.compile(r'\\f\{[^}]*\}')
+_GROMACS_SUP_RE = re.compile(r'\\S(.*?)\\N')
+_GROMACS_SUB_RE = re.compile(r'\\s(.*?)\\N')
+
+
+def clean_gromacs_label(text: str) -> str:
+    """Convert GROMACS xmgrace escape codes into matplotlib-compatible notation.
+
+    - \\f{...} font switches -> removed
+    - \\S...\\N superscript -> $^{...}$ (matplotlib mathtext/LaTeX)
+    - \\s...\\N subscript -> $_{...}$ (matplotlib mathtext/LaTeX)
+    """
+    if not text:
+        return text
+    cleaned = _GROMACS_FONT_RE.sub('', text)
+    cleaned = _GROMACS_SUP_RE.sub(r'$^{\1}$', cleaned)
+    cleaned = _GROMACS_SUB_RE.sub(r'$_{\1}$', cleaned)
+    return cleaned
+
+
+# Per-type fallback axis titles
+TYPE_FALLBACKS: dict[str, tuple[str, str]] = {
+    'energy':   ('Time (ps)', ''),
+    'gyration': ('Time (ps)', 'Rg (nm)'),
+    'rmsd':     ('Time (ns)', 'RMSD (nm)'),
+    'rmsf':     ('Residue', 'RMSF (nm)'),
+    'sasa':     ('Time (ns)', 'Area (nm$^{2}$)'),
+    'pca':      ('PC1', 'PC2'),
+    'xy':       ('X', 'Y'),
+}
+
+
+def resolve_axis_titles(
+    metadata,
+    fallback_x: str = '',
+    fallback_y: str = '',
+) -> Tuple[str, str]:
+    """Return (x_title, y_title) preferring metadata, cleaned of GROMACS codes.
+
+    Uses TYPE_FALLBACKS when no fallback is explicitly provided.
+    """
+    if not fallback_x and metadata.plot_type in TYPE_FALLBACKS:
+        fallback_x = TYPE_FALLBACKS[metadata.plot_type][0]
+    if not fallback_y and metadata.plot_type in TYPE_FALLBACKS:
+        fallback_y = TYPE_FALLBACKS[metadata.plot_type][1]
+
+    x_title = clean_gromacs_label(metadata.x_label) if metadata.x_label else fallback_x
+    y_title = clean_gromacs_label(metadata.y_label) if metadata.y_label else fallback_y
+    return x_title, y_title

gmxplot/parser.py

@@ -0,0 +1,247 @@
+"""XVG file parsing and plot type classification."""
+
+import re
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+import pandas as pd
+
+
+@dataclass
+class XVGMetadata:
+    """Metadata extracted from an XVG file header."""
+    title: str = ''
+    subtitle: str = ''
+    x_label: str = ''
+    y_label: str = ''
+    plot_type: str = ''  # energy, gyration, rmsd, rmsf, sasa, pca, xy, unknown
+    x_unit: str = ''
+    y_unit: str = ''
+    legend_labels: List[str] = field(default_factory=list)
+    n_columns: int = 0
+    file_path: str = ''
+    command: str = ''  # Original GROMACS command (e.g., rms, gyrate)
+    gmx_version: str = ''
+
+
+def read_xvg(file_path: str) -> Tuple[pd.DataFrame, XVGMetadata]:
+    """Read an XVG file and return (DataFrame, XVGMetadata)."""
+    metadata = XVGMetadata(file_path=file_path)
+    data_lines: List[str] = []
+    legend_labels: dict = {}
+    command = ''
+    gmx_version = ''
+
+    with open(file_path, 'r') as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+
+            # Comment lines — extract GROMACS version info
+            if line.startswith('#'):
+                if 'GROMACS' in line:
+                    m = re.search(r'GROMACS(?: - gmx (\w+))?,?\s*(\d+)', line)
+                    if m:
+                        command = m.group(1) or command
+                        gmx_version = m.group(2)
+                continue
+
+            # @ directives
+            if line.startswith('@'):
+                directive = line[1:].strip()
+
+                # Title
+                if directive.startswith('title'):
+                    m = re.search(r'"([^"]*)"', line)
+                    if m:
+                        metadata.title = m.group(1)
+
+                # Subtitle
+                elif directive.startswith('subtitle'):
+                    m = re.search(r'"([^"]*)"', line)
+                    if m:
+                        metadata.subtitle = m.group(1)
+
+                # X axis label (handle variable spacing)
+                elif re.match(r'^xaxis\s+label\s*', directive):
+                    m = re.search(r'"([^"]*)"', line)
+                    if m:
+                        metadata.x_label = m.group(1)
+
+                # Y axis label
+                elif re.match(r'^yaxis\s+label\s*', directive):
+                    m = re.search(r'"([^"]*)"', line)
+                    if m:
+                        metadata.y_label = m.group(1)
+
+                # Legend labels (s0, s1, etc.)
+                elif re.match(r's\d+\s+legend', directive):
+                    m = re.search(r's(\d+)\s+legend\s+"([^"]+)"', line)
+                    if m:
+                        legend_labels[int(m.group(1))] = m.group(2)
+
+                # Command line info
+                elif 'command' in directive.lower() and 'gmx' in line:
+                    m = re.search(r'gmx (\w+)', line)
+                    if m:
+                        command = m.group(1)
+
+                continue
+
+            # Numeric data lines — skip &, @, #
+            if line.startswith(('&', '#', '@')):
+                continue
+
+            parts = line.split()
+            if len(parts) >= 2:
+                try:
+                    float(parts[0])
+                    float(parts[1])
+                    data_lines.append(line)
+                except ValueError:
+                    continue
+
+    metadata.command = command
+    metadata.gmx_version = gmx_version
+    metadata.legend_labels = [
+        legend_labels.get(i, f'Col{i}') for i in range(len(legend_labels))
+    ]
+
+    # Parse numeric data
+    if data_lines:
+        metadata = _parse_data_to_dataframe(data_lines, metadata)
+
+    # Classify plot type
+    metadata.plot_type = _classify_plot_type(metadata)
+
+    if not hasattr(metadata, 'df') or metadata.df is None:
+        metadata.df = pd.DataFrame()
+
+    return metadata.df, metadata
+
+
+def _parse_data_to_dataframe(
+    data_lines: List[str], metadata: XVGMetadata
+) -> XVGMetadata:
+    """Parse data lines into DataFrame with intelligent column naming."""
+    parsed = []
+    for line in data_lines:
+        parts = re.split(r'[,\s\t]+', line)
+        parsed.append([p for p in parts if p])
+
+    if not parsed:
+        metadata.df = pd.DataFrame()
+        return metadata
+
+    num_cols = len(parsed[0])
+    metadata.n_columns = num_cols
+    title_lower = metadata.title.lower()
+    x_label_lower = metadata.x_label.lower()
+
+    if num_cols >= 2:
+        columns: List[str] = ['X'] + [f'Y{i}' for i in range(1, num_cols)]
+
+    # --- X column naming ---
+    if 'time' in x_label_lower or 'time' in title_lower:
+        columns[0] = 'Time'
+    elif 'step' in x_label_lower:
+        columns[0] = 'Step'
+    elif 'residue' in x_label_lower or 'residue' in title_lower:
+        columns[0] = 'Residue'
+    elif 'atom' in x_label_lower:
+        columns[0] = 'Atom'
+    elif 'eigen' in x_label_lower:
+        columns[0] = 'Eigenvalue'
+    elif 'projection' in x_label_lower:
+        columns[0] = 'PC1'
+        columns[1] = 'PC2'
+
+    # --- Y column naming ---
+    if 'potential' in title_lower or 'energ' in title_lower:
+        if metadata.legend_labels and len(metadata.legend_labels) >= num_cols - 1:
+            columns = ['Time'] + metadata.legend_labels[:num_cols - 1]
+        else:
+            defaults = ['Potential', 'Temperature', 'Pressure', 'Density']
+            columns = ['Time'] + defaults[:num_cols - 1]
+
+    elif 'gyration' in title_lower or re.search(r'\brg\b', title_lower):
+        if num_cols >= 4:
+            columns = ['Time', 'Rg', 'RgX', 'RgY', 'RgZ']
+        else:
+            columns = ['Time', 'Rg']
+
+    elif ('area' in metadata.y_label.lower()
+          or 'sasa' in title_lower
+          or 'solvent' in title_lower):
+        if 'time' in x_label_lower:
+            columns = ['Time', 'Area', 'StdDev'][:num_cols]
+        else:
+            columns = ['Residue', 'Area', 'StdDev'][:num_cols]
+
+    elif 'rmsd' in title_lower or 'rmsd' in metadata.y_label.lower():
+        columns = ['Time', 'RMSD']
+
+    elif 'rmsf' in title_lower or 'fluctuation' in title_lower:
+        columns = ['Residue', 'RMSF']
+
+    elif 'pca' in title_lower or 'projection' in title_lower:
+        columns = ['PC1', 'PC2']
+
+    # Build DataFrame
+    df = pd.DataFrame(parsed, columns=columns[:num_cols])
+    for col in df.columns:
+        df[col] = pd.to_numeric(df[col], errors='coerce')
+
+    metadata.df = df
+    return metadata
+
+
+def _classify_plot_type(metadata: XVGMetadata) -> str:
+    """Classify plot type from title (primary) and axis labels / column count (fallback)."""
+    title = metadata.title.lower()
+
+    # ── Title-based detection ────────────────────────────────────────
+    title_rules: List[Tuple[str, str]] = [
+        ('2d projection', 'pca'),
+        ('projection of trajectory', 'pca'),
+        ('energies', 'energy'),
+        ('energy', 'energy'),
+        ('solvent accessible surface', 'sasa'),
+        ('area per residue', 'sasa'),
+        ('sasa', 'sasa'),
+        ('rms fluctuation', 'rmsf'),
+        ('rmsf', 'rmsf'),
+        ('rmsd', 'rmsd'),
+        ('radius of gyration', 'gyration'),
+        ('gyration', 'gyration'),
+    ]
+
+    for pattern, plot_type in title_rules:
+        if pattern in title:
+            return plot_type
+
+    # ── Fallback heuristics ─────────────────────────────────────────
+    x_label = metadata.x_label.lower()
+    y_label = metadata.y_label.lower()
+    n_cols = metadata.n_columns
+
+    if n_cols >= 4 and 'time' in x_label:
+        if any(kw in y_label for kw in ['kj/mol', '(k)', '(bar)', 'kg/m']):
+            return 'energy'
+    if 'eigenvector' in x_label and 'eigenvector' in y_label:
+        return 'pca'
+    if 'fluctuation' in y_label or 'rmsf' in y_label:
+        return 'rmsf'
+    if 'residue' in x_label and 'rmsf' in y_label:
+        return 'rmsf'
+    if 'rmsd' in y_label:
+        return 'rmsd'
+    if 'radius of gyration' in y_label or re.search(r'\brg\b', y_label):
+        return 'gyration'
+    if 'area' in y_label and 'nm' in y_label:
+        return 'sasa'
+    if n_cols >= 2:
+        return 'xy'
+
+    return 'unknown'

gmxplot/plotting.py

@@ -0,0 +1,268 @@
+"""Matplotlib plotting functions for all XVG plot types."""
+
+import re
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import seaborn as sns
+
+from .escape_codes import clean_gromacs_label, resolve_axis_titles
+from .config import (
+    FIGURE_SIZE_SINGLE, FIGURE_SIZE_MULTI_ROW_HEIGHT, DPI_DEFAULT,
+    LINE_WIDTH_RAW, LINE_WIDTH_RA, RAW_ALPHA, RA_COLOR, RAW_COLOR,
+    ROLL_AVG_MIN, ROLL_AVG_MAX, ROLL_AVG_FRACTION,
+)
+
+# Apply seaborn style defaults
+sns.set_style('whitegrid')
+sns.set_context('paper', font_scale=1.2)
+
+
+def calculate_roll_avg(df: pd.DataFrame, x_col: str = 'Time') -> int:
+    """Calculate rolling average window: 5% of data range, min 3, max 100."""
+    if x_col not in df.columns or len(df) < 10:
+        return 10
+    x_range = df[x_col].max() - df[x_col].min()
+    window = max(ROLL_AVG_MIN, min(ROLL_AVG_MAX, int(x_range * ROLL_AVG_FRACTION)))
+    return max(3, window)
+
+
+def _add_ra_trace(ax, x, y, roll_avg, raw_color=RAW_COLOR, ra_color=RA_COLOR):
+    """Add raw data line + rolling average overlay to axes."""
+    y_ra = y.rolling(window=roll_avg, min_periods=1, center=True).mean()
+    ax.plot(x, y, color=raw_color, alpha=RAW_ALPHA, linewidth=LINE_WIDTH_RAW, label='Raw')
+    ax.plot(x, y_ra, color=ra_color, linewidth=LINE_WIDTH_RA, label=f'RA (n={roll_avg})')
+
+
+def _add_mean_std_lines(ax, df, y_col, show_mean=False, show_std=False):
+    """Optionally draw mean and mean +/- std horizontal lines."""
+    if y_col not in df.columns:
+        return
+    y_data = df[y_col]
+    mean = y_data.mean()
+    std = y_data.std()
+    color = RA_COLOR
+    if show_mean:
+        ax.axhline(y=mean, color=color, linestyle='--', linewidth=1, alpha=0.8)
+    if show_std:
+        ax.axhline(y=mean + std, color=color, linestyle=':', linewidth=0.5, alpha=0.6)
+        ax.axhline(y=mean - std, color=color, linestyle=':', linewidth=0.5, alpha=0.6)
+
+
+def plot_energy(df: pd.DataFrame, metadata, roll_avg=None,
+                show_mean=False, show_std=False) -> plt.Figure:
+    """Plot energy components with rolling average in dynamic subplot grid."""
+    if roll_avg is None:
+        roll_avg = calculate_roll_avg(df, 'Time')
+
+    y_cols = [c for c in df.columns if c != 'Time']
+    n_y = len(y_cols)
+    if n_y == 0:
+        return plot_xy(df, metadata, roll_avg, show_mean, show_std)
+
+    # Grid layout
+    n_cols = min(2, n_y) if n_y > 1 else 1
+    n_rows = max(1, (n_y + n_cols - 1) // n_cols)
+
+    fig, axes = plt.subplots(n_rows, n_cols, figsize=(12, n_rows * FIGURE_SIZE_MULTI_ROW_HEIGHT),
+                              sharex=True, squeeze=False)
+    axes_flat = axes.flatten()
+
+    # Parse per-column units from y_label
+    units = _parse_y_units(metadata.y_label)
+    y_titles = _build_y_titles(y_cols, units)
+
+    for idx, y_col in enumerate(y_cols):
+        ax = axes_flat[idx]
+        _add_ra_trace(ax, df['Time'], df[y_col], roll_avg)
+        _add_mean_std_lines(ax, df, y_col, show_mean, show_std)
+        ax.set_ylabel(y_titles.get(y_col, y_col))
+        ax.set_title(y_col)
+
+    # Hide unused axes
+    for idx in range(n_y, len(axes_flat)):
+        axes_flat[idx].set_visible(False)
+
+    x_title, _ = resolve_axis_titles(metadata, 'Time (ps)', '')
+    for ax_row in axes[-1]:
+        if ax_row.get_visible():
+            ax_row.set_xlabel(x_title)
+
+    fig.suptitle('Energy Components', fontsize=14)
+    fig.tight_layout()
+    return fig
+
+
+def plot_gyration(df: pd.DataFrame, metadata, roll_avg=None,
+                  show_mean=False, show_std=False) -> plt.Figure:
+    """Plot radius of gyration (Rg only)."""
+    if roll_avg is None:
+        roll_avg = calculate_roll_avg(df, 'Time')
+
+    fig, ax = plt.subplots(figsize=FIGURE_SIZE_SINGLE)
+
+    if 'Rg' in df.columns:
+        _add_ra_trace(ax, df['Time'], df['Rg'], roll_avg)
+        _add_mean_std_lines(ax, df, 'Rg', show_mean, show_std)
+
+    x_title, y_title = resolve_axis_titles(metadata, 'Time (ps)', 'Rg (nm)')
+    ax.set_xlabel(x_title)
+    ax.set_ylabel(y_title)
+    ax.set_title(f'Radius of Gyration — {metadata.title}')
+    ax.legend()
+    fig.tight_layout()
+    return fig
+
+
+def plot_rmsd(df: pd.DataFrame, metadata, roll_avg=None,
+              show_mean=False, show_std=False) -> plt.Figure:
+    """Plot RMSD with rolling average."""
+    if roll_avg is None:
+        roll_avg = calculate_roll_avg(df, 'Time')
+
+    fig, ax = plt.subplots(figsize=FIGURE_SIZE_SINGLE)
+
+    if 'RMSD' in df.columns:
+        _add_ra_trace(ax, df['Time'], df['RMSD'], roll_avg)
+        _add_mean_std_lines(ax, df, 'RMSD', show_mean, show_std)
+
+    x_title, y_title = resolve_axis_titles(metadata, 'Time (ns)', 'RMSD (nm)')
+    ax.set_xlabel(x_title)
+    ax.set_ylabel(y_title)
+    ax.set_title(f'RMSD — {metadata.title}')
+    ax.legend()
+    fig.tight_layout()
+    return fig
+
+
+def plot_rmsf(df: pd.DataFrame, metadata, roll_avg=None,
+              show_mean=False, show_std=False) -> plt.Figure:
+    """Plot RMSF per residue (no rolling average)."""
+    fig, ax = plt.subplots(figsize=FIGURE_SIZE_SINGLE)
+
+    if 'RMSF' in df.columns:
+        ax.plot(df['Residue'], df['RMSF'], color=RA_COLOR, linewidth=LINE_WIDTH_RA)
+        _add_mean_std_lines(ax, df, 'RMSF', show_mean, show_std)
+
+    x_title, y_title = resolve_axis_titles(metadata, 'Residue', 'RMSF (nm)')
+    ax.set_xlabel(x_title)
+    ax.set_ylabel(y_title)
+    ax.set_title(f'RMSF — {metadata.title}')
+    fig.tight_layout()
+    return fig
+
+
+def plot_sasa(df: pd.DataFrame, metadata, roll_avg=None,
+              show_mean=False, show_std=False) -> plt.Figure:
+    """Plot SASA — time-series with RA, or per-residue without RA."""
+    fig, ax = plt.subplots(figsize=FIGURE_SIZE_SINGLE)
+
+    if 'Time' in df.columns:
+        x_col = 'Time'
+        fallback_x = 'Time (ns)'
+    elif 'Residue' in df.columns:
+        x_col = 'Residue'
+        fallback_x = 'Residue'
+    else:
+        x_col = df.columns[0]
+        fallback_x = x_col
+
+    x_title, y_title = resolve_axis_titles(metadata, fallback_x, 'Area (nm$^{2}$)')
+
+    if 'Area' in df.columns:
+        if x_col == 'Residue':
+            ax.plot(df[x_col], df['Area'], color=RA_COLOR, linewidth=LINE_WIDTH_RA)
+        else:
+            if roll_avg is None:
+                roll_avg = calculate_roll_avg(df, x_col)
+            _add_ra_trace(ax, df[x_col], df['Area'], roll_avg)
+        _add_mean_std_lines(ax, df, 'Area', show_mean, show_std)
+
+    ax.set_xlabel(x_title)
+    ax.set_ylabel(y_title)
+    ax.set_title(f'SASA — {metadata.title}')
+    if x_col == 'Time':
+        ax.legend()
+    fig.tight_layout()
+    return fig
+
+
+def plot_pca(df: pd.DataFrame, metadata, roll_avg=None,
+             show_mean=False, show_std=False) -> plt.Figure:
+    """Plot PCA projection as 2D hexbin density with viridis colormap."""
+    fig, ax = plt.subplots(figsize=FIGURE_SIZE_SINGLE)
+
+    if 'PC1' in df.columns and 'PC2' in df.columns:
+        hb = ax.hexbin(df['PC1'], df['PC2'], cmap='viridis', gridsize=30, mincnt=1)
+        fig.colorbar(hb, ax=ax, label='Density')
+
+    x_title, y_title = resolve_axis_titles(metadata, 'PC1', 'PC2')
+    ax.set_xlabel(x_title)
+    ax.set_ylabel(y_title)
+    ax.set_title(f'PCA Projection — {metadata.title}')
+    fig.tight_layout()
+    return fig
+
+
+def plot_xy(df: pd.DataFrame, metadata, roll_avg=None,
+            show_mean=False, show_std=False) -> plt.Figure:
+    """Generic XY plot for unrecognized types."""
+    x_col = df.columns[0]
+    y_col = df.columns[1] if len(df.columns) > 1 else df.columns[0]
+
+    if roll_avg is None:
+        roll_avg = calculate_roll_avg(df, x_col)
+
+    fig, ax = plt.subplots(figsize=FIGURE_SIZE_SINGLE)
+
+    # Multiple Y columns: each as separate line
+    y_cols = list(df.columns[1:])
+    if len(y_cols) <= 1:
+        _add_ra_trace(ax, df[x_col], df[y_col], roll_avg)
+        _add_mean_std_lines(ax, df, y_col, show_mean, show_std)
+    else:
+        for yc in y_cols:
+            y_ra = df[yc].rolling(window=roll_avg, min_periods=1, center=True).mean()
+            ax.plot(df[x_col], y_ra, linewidth=LINE_WIDTH_RA, label=yc)
+            _add_mean_std_lines(ax, df, yc, show_mean, show_std)
+
+    x_title, y_title = resolve_axis_titles(metadata, x_col, y_col)
+    ax.set_xlabel(x_title)
+    ax.set_ylabel(y_title)
+    ax.set_title(f'Plot — {metadata.title}')
+    ax.legend()
+    fig.tight_layout()
+    return fig
+
+
+def create_plot(df: pd.DataFrame, metadata, roll_avg=None,
+                show_mean=False, show_std=False) -> plt.Figure:
+    """Dispatch to type-specific plot function."""
+    plot_type = metadata.plot_type
+    func_map = {
+        'energy': plot_energy,
+        'gyration': plot_gyration,
+        'rmsd': plot_rmsd,
+        'rmsf': plot_rmsf,
+        'sasa': plot_sasa,
+        'pca': plot_pca,
+        'xy': plot_xy,
+        'unknown': plot_xy,
+    }
+    func = func_map.get(plot_type, plot_xy)
+    return func(df, metadata, roll_avg, show_mean, show_std)
+
+
+def _parse_y_units(y_label: str) -> list:
+    """Parse per-column units from y_label like '(kJ/mol), (K), (bar), (kg/m^3)'."""
+    return re.findall(r'\(([^)]+)\)', y_label)
+
+def _build_y_titles(y_cols: list, units: list) -> dict:
+    """Build column-name -> 'Name (unit)' map from y_label units."""
+    result = {}
+    for idx, col in enumerate(y_cols):
+        if idx < len(units):
+            result[col] = f'{col} ({clean_gromacs_label(units[idx])})'
+        else:
+            result[col] = col
+    return result

gmxplot/stats.py

@@ -0,0 +1,84 @@
+"""Statistical summary generation for XVG data."""
+
+import os
+from pathlib import Path
+from typing import List
+
+import pandas as pd
+from rich.console import Console
+from rich.table import Table
+
+from .parser import read_xvg
+
+
+def compute_column_stats(df: pd.DataFrame, metadata) -> List[dict]:
+    """Compute per-column statistics: mean, std, min, q10, q50, q90, max."""
+    results = []
+    fp = Path(metadata.file_path)
+    for col in df.columns[1:]:
+        series = df[col].dropna()
+        results.append({
+            'dir': str(fp.parent),
+            'file': fp.name,
+            'plot': col,
+            'mean': series.mean(),
+            'std': series.std(),
+            'min': series.min(),
+            'q10': series.quantile(0.1),
+            'q50': series.quantile(0.5),
+            'q90': series.quantile(0.9),
+            'max': series.max(),
+        })
+    return results
+
+
+def generate_stats_csv(
+    file_paths: List[str],
+    output_path: str,
+) -> pd.DataFrame:
+    """Generate statistical summary CSV for multiple XVG files."""
+    all_stats = []
+    for fp in file_paths:
+        if not os.path.exists(fp):
+            continue
+        df, metadata = read_xvg(fp)
+        if df.empty:
+            continue
+        all_stats.extend(compute_column_stats(df, metadata))
+
+    stats_df = pd.DataFrame(all_stats)
+    if not stats_df.empty:
+        stats_df.to_csv(output_path, index=False, float_format='%.6f')
+    return stats_df
+
+
+def format_stats_table(stats_df: pd.DataFrame, console: Console = None) -> Table:
+    """Format statistics DataFrame as a Rich console table."""
+    if console is None:
+        console = Console()
+
+    table = Table(title='XVG Statistics Summary')
+    table.add_column('File', style='cyan')
+    table.add_column('Plot', style='green')
+    table.add_column('Mean', justify='right')
+    table.add_column('Std', justify='right')
+    table.add_column('Min', justify='right')
+    table.add_column('Q10', justify='right')
+    table.add_column('Q50', justify='right')
+    table.add_column('Q90', justify='right')
+    table.add_column('Max', justify='right')
+
+    for _, row in stats_df.iterrows():
+        table.add_row(
+            str(row['file']),
+            str(row['plot']),
+            f'{row["mean"]:.4f}',
+            f'{row["std"]:.4f}',
+            f'{row["min"]:.4f}',
+            f'{row["q10"]:.4f}',
+            f'{row["q50"]:.4f}',
+            f'{row["q90"]:.4f}',
+            f'{row["max"]:.4f}',
+        )
+
+    return table