gmxplot 0.1.0__py3-none-any.whl

gmxplot/__init__.py

@@ -0,0 +1,3 @@
+"""gmxplot - GROMACS XVG file visualization tool."""
+
+__version__ = "0.1.0"

gmxplot/cli.py

@@ -0,0 +1,314 @@
+"""Typer CLI entry point for gmxplot."""
+
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+import pandas as pd
+import typer
+from rich.console import Console
+
+from .parser import read_xvg
+from .plotting import create_plot, calculate_roll_avg
+from .comparison import compare_two, compare_multi
+from .stats import generate_stats_csv, format_stats_table
+
+app = typer.Typer(
+    name='gmxplot',
+    help='GROMACS XVG file visualization with auto type detection, comparison, and statistical summary.',
+    rich_markup_mode='rich',
+)
+
+console = Console()
+
+
+def _detect_latex() -> bool:
+    return shutil.which('latex') is not None
+
+
+def _setup_latex(use_latex: Optional[bool] = None) -> bool:
+    if use_latex is None:
+        use_latex = False  # default off — raw XVG labels often have ^ outside math mode
+    if use_latex:
+        plt.rcParams.update({
+            'text.usetex': True,
+            'font.family': 'sans-serif',
+            'font.size': 14,
+        })
+    return use_latex
+
+
+def _save_figure(fig, output_path: str, dpi: int = 300) -> None:
+    path = Path(output_path)
+    suffix = path.suffix.lower()
+    if suffix not in ('.png', '.jpg', '.jpeg', '.pdf', '.svg', '.eps', '.tiff'):
+        path = path.with_suffix('.png')
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fig.savefig(str(path), dpi=dpi, bbox_inches='tight')
+    console.print(f'Saved to: {path}')
+
+
+def _print_file_info(file_path: str, metadata) -> None:
+    console.print(f'File: {file_path}')
+    console.print(f'  Type: [cyan]{metadata.plot_type}[/cyan]')
+    console.print(f'  Title: {metadata.title}')
+    console.print(f'  X-axis: {metadata.x_label}')
+    console.print(f'  Y-axis: {metadata.y_label}')
+    console.print(f'  Columns: {metadata.df.columns.tolist() if hasattr(metadata, "df") else "N/A"}')
+    if hasattr(metadata, 'df') and metadata.df is not None:
+        console.print(f'  Data points: {len(metadata.df)}')
+
+
+@app.command()
+def plot(
+    file: str = typer.Argument(..., help='Path to XVG file'),
+    roll_avg: Optional[int] = typer.Option(None, '--roll-avg', '-r',
+        help='Rolling average window size (auto if not set)'),
+    output: Optional[str] = typer.Option(None, '--output', '-o',
+        help='Output file path (PNG, PDF, SVG, JPG)'),
+    dpi: int = typer.Option(300, '--dpi', '-d', help='DPI for saved image'),
+    show: bool = typer.Option(False, '--show', help='Display plot in window'),
+    mean: bool = typer.Option(False, '--mean', '-m', help='Plot mean line'),
+    std: bool = typer.Option(False, '--std', '-s', help='Plot mean +/- std lines'),
+    latex: Optional[bool] = typer.Option(None, '--latex/--no-latex',
+        help='Enable/disable LaTeX rendering (auto-detect if not set)'),
+):
+    """Plot a single XVG file with automatic type detection."""
+    if not os.path.exists(file):
+        console.print(f'[red]Error: File not found — {file}[/red]')
+        raise typer.Exit(1)
+
+    use_latex = _setup_latex(latex)
+    df, metadata = read_xvg(file)
+
+    if df.empty:
+        console.print(f'[red]Error: Could not parse data from {file}[/red]')
+        raise typer.Exit(1)
+
+    _print_file_info(file, metadata)
+
+    if roll_avg is None:
+        x_col = df.columns[0]
+        roll_avg = calculate_roll_avg(df, x_col)
+        console.print(f'  Auto roll-avg: {roll_avg}')
+
+    fig = create_plot(df, metadata, roll_avg=roll_avg, show_mean=mean, show_std=std)
+
+    if output:
+        _save_figure(fig, output, dpi)
+    else:
+        stem = Path(file).stem
+        auto_output = f'{stem}_plot.png'
+        _save_figure(fig, auto_output, dpi)
+
+    if show:
+        matplotlib.use('TkAgg')
+        plt.show()
+
+    plt.close(fig)
+
+
+@app.command()
+def compare(
+    file1: str = typer.Argument(..., help='Path to first XVG file'),
+    file2: str = typer.Argument(..., help='Path to second XVG file'),
+    label1: str = typer.Option('prot_1', '--label1', '-l1', help='Label for first dataset'),
+    label2: str = typer.Option('prot_2', '--label2', '-l2', help='Label for second dataset'),
+    roll_avg: int = typer.Option(50, '--roll-avg', '-r', help='Rolling average window size'),
+    output: Optional[str] = typer.Option(None, '--output', '-o', help='Output file path'),
+    dpi: int = typer.Option(300, '--dpi', '-d', help='DPI for saved image'),
+    latex: Optional[bool] = typer.Option(None, '--latex/--no-latex',
+        help='Enable/disable LaTeX rendering'),
+):
+    """Compare two XVG files with auto type detection."""
+    for f in (file1, file2):
+        if not os.path.exists(f):
+            console.print(f'[red]Error: File not found — {f}[/red]')
+            raise typer.Exit(1)
+
+    _setup_latex(latex)
+    df1, meta1 = read_xvg(file1)
+    df2, meta2 = read_xvg(file2)
+
+    if df1.empty or df2.empty:
+        console.print('[red]Error: Could not parse data[/red]')
+        raise typer.Exit(1)
+
+    _print_file_info(file1, meta1)
+    _print_file_info(file2, meta2)
+
+    if meta1.plot_type != meta2.plot_type:
+        console.print(f'[yellow]Warning: Different types ({meta1.plot_type} vs {meta2.plot_type})[/yellow]')
+
+    fig = compare_two(df1, meta1, df2, meta2, label1, label2, roll_avg)
+
+    if output:
+        _save_figure(fig, output, dpi)
+    else:
+        stem1 = Path(file1).stem
+        auto_output = f'{stem1}_compare.png'
+        _save_figure(fig, auto_output, dpi)
+
+    plt.close(fig)
+
+
+@app.command(name='multi-compare')
+def multi_compare(
+    files: List[str] = typer.Argument(..., help='Paths to XVG files (at least 2)'),
+    roll_avg: int = typer.Option(50, '--roll-avg', '-r', help='Rolling average window size'),
+    output: Optional[str] = typer.Option(None, '--output', '-o', help='Output file path'),
+    dpi: int = typer.Option(300, '--dpi', '-d', help='DPI for saved image'),
+    latex: Optional[bool] = typer.Option(None, '--latex/--no-latex',
+        help='Enable/disable LaTeX rendering'),
+):
+    """Compare multiple XVG files of the same type (3+ files)."""
+    valid_files = [f for f in files if os.path.exists(f)]
+    if len(valid_files) < 2:
+        console.print('[red]Error: Need at least 2 valid files[/red]')
+        raise typer.Exit(1)
+
+    _setup_latex(latex)
+    data_list = []
+    for f in valid_files:
+        df, meta = read_xvg(f)
+        if df.empty:
+            continue
+        label = Path(f).stem
+        data_list.append((df, meta, label))
+
+    if len(data_list) < 2:
+        console.print('[red]Error: Need at least 2 valid data files[/red]')
+        raise typer.Exit(1)
+
+    types = set(d[1].plot_type for d in data_list)
+    if len(types) > 1:
+        console.print(f'[yellow]Warning: Mixed types: {types}[/yellow]')
+
+    fig = compare_multi(data_list, roll_avg)
+
+    if output:
+        _save_figure(fig, output, dpi)
+    else:
+        auto_output = 'multi_compare.png'
+        _save_figure(fig, auto_output, dpi)
+
+    plt.close(fig)
+
+
+@app.command()
+def detect(
+    file: str = typer.Argument(..., help='Path to XVG file'),
+):
+    """Detect and print XVG file type and metadata without plotting."""
+    if not os.path.exists(file):
+        console.print(f'[red]Error: File not found — {file}[/red]')
+        raise typer.Exit(1)
+
+    df, metadata = read_xvg(file)
+    _print_file_info(file, metadata)
+    console.print(f'  Columns count: {metadata.n_columns}')
+
+
+@app.command()
+def batch(
+    input_dir: str = typer.Argument('.', help='Input directory with XVG files'),
+    output_dir: str = typer.Option('.', '--output-dir', '-o', help='Output directory for plots'),
+    roll_avg: Optional[int] = typer.Option(None, '--roll-avg', '-r',
+        help='Rolling average window size (auto if not set)'),
+    dpi: int = typer.Option(300, '--dpi', '-d', help='DPI for saved images'),
+    ext: str = typer.Option('png', '--ext', '-e', help='Export format (png, pdf, svg, jpg)'),
+    stats: bool = typer.Option(True, '--stats/--no-stats', help='Generate statistics CSV'),
+    stats_file: str = typer.Option('xvg-stats.csv', '--stats-file', help='Statistics CSV filename'),
+    mean: bool = typer.Option(False, '--mean', '-m', help='Plot mean lines'),
+    std: bool = typer.Option(False, '--std', '-s', help='Plot mean +/- std lines'),
+    latex: Optional[bool] = typer.Option(None, '--latex/--no-latex',
+        help='Enable/disable LaTeX rendering'),
+):
+    """Batch process all XVG files in a directory."""
+    input_path = Path(input_dir)
+    if not input_path.exists():
+        console.print(f'[red]Error: Directory not found — {input_dir}[/red]')
+        raise typer.Exit(1)
+
+    _setup_latex(latex)
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    xvg_files = sorted(input_path.glob('*.xvg'))
+    if not xvg_files:
+        console.print(f'[red]Error: No XVG files in {input_dir}[/red]')
+        raise typer.Exit(1)
+
+    console.print(f'Found {len(xvg_files)} XVG file(s)')
+    all_file_paths = []
+    results = []
+
+    for xvg_file in xvg_files:
+        console.print(f'\nProcessing: {xvg_file.name}')
+        df, metadata = read_xvg(str(xvg_file))
+
+        if df.empty:
+            console.print(f'  [red]Error: Could not parse[/red]')
+            results.append((xvg_file.name, 'error', 'parse failed'))
+            continue
+
+        if roll_avg is None:
+            ra = calculate_roll_avg(df, df.columns[0])
+        else:
+            ra = roll_avg
+
+        fig = create_plot(df, metadata, roll_avg=ra, show_mean=mean, show_std=std)
+        out_file = output_path / f'{xvg_file.stem}_plot.{ext}'
+        fig.savefig(str(out_file), dpi=dpi, bbox_inches='tight')
+        console.print(f'  Saved: {out_file}')
+        plt.close(fig)
+
+        all_file_paths.append(str(xvg_file))
+        results.append((xvg_file.name, 'success', metadata.plot_type))
+
+    # Statistics
+    if stats and all_file_paths:
+        stats_path = str(output_path / stats_file)
+        stats_df = generate_stats_csv(all_file_paths, stats_path)
+        if not stats_df.empty:
+            console.print(f'\nStatistics saved to: {stats_path}')
+            table = format_stats_table(stats_df)
+            console.print(table)
+
+    # Summary
+    console.print('\n' + '=' * 50)
+    console.print('BATCH SUMMARY')
+    console.print('=' * 50)
+    for filename, status, info in results:
+        icon = '[green]OK[/green]' if status == 'success' else '[red]ERR[/red]'
+        console.print(f'  {icon} {filename}: {info}')
+
+
+@app.command()
+def stats(
+    files: List[str] = typer.Argument(..., help='XVG files to analyze'),
+    output: str = typer.Option('xvg-stats.csv', '--output', '-o', help='Output CSV path'),
+):
+    """Generate statistical summary CSV for XVG files."""
+    valid_files = [f for f in files if os.path.exists(f)]
+    if not valid_files:
+        console.print('[red]Error: No valid files[/red]')
+        raise typer.Exit(1)
+
+    stats_df = generate_stats_csv(valid_files, output)
+    if not stats_df.empty:
+        console.print(f'Saved to: {output}')
+        table = format_stats_table(stats_df)
+        console.print(table)
+    else:
+        console.print('[red]Error: No data to summarize[/red]')
+        raise typer.Exit(1)
+
+
+if __name__ == '__main__':
+    app()

gmxplot/comparison.py

@@ -0,0 +1,293 @@
+"""Two-file and multi-file comparison plotting with matplotlib."""
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+from .escape_codes import resolve_axis_titles
+from .plotting import calculate_roll_avg, _parse_y_units, _build_y_titles, clean_gromacs_label
+from .config import (
+    FIGURE_SIZE_SINGLE, FIGURE_SIZE_MULTI_ROW_HEIGHT,
+    COMPARE_COLORS, MULTI_COLORS,
+    LINE_WIDTH_RA, ROLL_AVG_DEFAULT_COMPARE,
+)
+
+
+def compare_two(
+    df1: pd.DataFrame, meta1,
+    df2: pd.DataFrame, meta2,
+    label1: str = 'prot_1', label2: str = 'prot_2',
+    roll_avg: int = ROLL_AVG_DEFAULT_COMPARE,
+) -> plt.Figure:
+    """Create comparison plot for two XVG files, dispatching by type."""
+    plot_type = meta1.plot_type
+
+    if plot_type == 'energy':
+        return _compare_energy(df1, meta1, df2, meta2, label1, label2, roll_avg)
+    elif plot_type == 'pca':
+        return _compare_pca(df1, meta1, df2, meta2, label1, label2)
+
+    fig, ax = plt.subplots(figsize=FIGURE_SIZE_SINGLE)
+    color1, color2 = COMPARE_COLORS
+
+    if plot_type == 'gyration':
+        for col in ['Rg', 'RgX', 'RgY', 'RgZ']:
+            if col in df1.columns and col in df2.columns:
+                ra1 = df1[col].rolling(window=roll_avg, min_periods=1, center=True).mean()
+                ra2 = df2[col].rolling(window=roll_avg, min_periods=1, center=True).mean()
+                ax.plot(df1['Time'], ra1, color=color1, linewidth=LINE_WIDTH_RA,
+                        label=f'{label1} {col}')
+                ax.plot(df2['Time'], ra2, color=color2, linewidth=LINE_WIDTH_RA,
+                        label=f'{label2} {col}')
+
+    elif plot_type == 'rmsd':
+        if 'RMSD' in df1.columns and 'RMSD' in df2.columns:
+            ra1 = df1['RMSD'].rolling(window=roll_avg, min_periods=1, center=True).mean()
+            ra2 = df2['RMSD'].rolling(window=roll_avg, min_periods=1, center=True).mean()
+            ax.plot(df1['Time'], ra1, color=color1, linewidth=LINE_WIDTH_RA,
+                    label=f'{label1} RMSD')
+            ax.plot(df2['Time'], ra2, color=color2, linewidth=LINE_WIDTH_RA,
+                    label=f'{label2} RMSD')
+
+    elif plot_type == 'rmsf':
+        if 'RMSF' in df1.columns and 'RMSF' in df2.columns:
+            ax.plot(df1['Residue'], df1['RMSF'], color=color1, linewidth=LINE_WIDTH_RA,
+                    label=f'{label1} RMSF')
+            ax.plot(df2['Residue'], df2['RMSF'], color=color2, linewidth=LINE_WIDTH_RA,
+                    label=f'{label2} RMSF')
+
+    elif plot_type == 'sasa':
+        if 'Area' in df1.columns and 'Area' in df2.columns:
+            ra1 = df1['Area'].rolling(window=roll_avg, min_periods=1, center=True).mean()
+            ra2 = df2['Area'].rolling(window=roll_avg, min_periods=1, center=True).mean()
+            ax.plot(df1['Time'], ra1, color=color1, linewidth=LINE_WIDTH_RA,
+                    label=f'{label1} SASA')
+            ax.plot(df2['Time'], ra2, color=color2, linewidth=LINE_WIDTH_RA,
+                    label=f'{label2} SASA')
+
+    else:
+        # Generic XY comparison
+        x_col = df1.columns[0]
+        y_col = df1.columns[1] if len(df1.columns) > 1 else df1.columns[0]
+        if x_col in df1.columns and y_col in df1.columns:
+            ra1 = df1[y_col].rolling(window=roll_avg, min_periods=1, center=True).mean()
+            ra2 = df2[y_col].rolling(window=roll_avg, min_periods=1, center=True).mean()
+            ax.plot(df1[x_col], ra1, color=color1, linewidth=LINE_WIDTH_RA,
+                    label=f'{label1}')
+            ax.plot(df2[x_col], ra2, color=color2, linewidth=LINE_WIDTH_RA,
+                    label=f'{label2}')
+
+    x_title, y_title = resolve_axis_titles(meta1, 'X', 'Y')
+    ax.set_xlabel(x_title)
+    ax.set_ylabel(y_title)
+    ax.set_title(f'Comparison — {meta1.title}')
+    ax.legend()
+    fig.tight_layout()
+    return fig
+
+
+def compare_multi(
+    data_list: list,
+    roll_avg: int = ROLL_AVG_DEFAULT_COMPARE,
+) -> plt.Figure:
+    """Create comparison plot for multiple XVG files of the same type.
+
+    data_list: list of (DataFrame, XVGMetadata, label) tuples.
+    """
+    if not data_list:
+        raise ValueError('No data provided for comparison')
+
+    plot_type = data_list[0][1].plot_type
+
+    if plot_type == 'energy':
+        return _compare_multi_energy(data_list, roll_avg)
+    elif plot_type == 'pca':
+        return _compare_multi_pca(data_list)
+
+    fig, ax = plt.subplots(figsize=FIGURE_SIZE_SINGLE)
+
+    if plot_type == 'rmsf':
+        for idx, (df, meta, label) in enumerate(data_list):
+            if 'RMSF' in df.columns and 'Residue' in df.columns:
+                ax.plot(df['Residue'], df['RMSF'],
+                        color=MULTI_COLORS[idx % len(MULTI_COLORS)],
+                        linewidth=LINE_WIDTH_RA, label=label)
+
+    elif plot_type == 'sasa':
+        for idx, (df, meta, label) in enumerate(data_list):
+            if 'Area' in df.columns and 'Time' in df.columns:
+                ra = df['Area'].rolling(window=roll_avg, min_periods=1, center=True).mean()
+                ax.plot(df['Time'], ra,
+                        color=MULTI_COLORS[idx % len(MULTI_COLORS)],
+                        linewidth=LINE_WIDTH_RA, label=label)
+
+    elif plot_type in ('rmsd', 'gyration'):
+        y_col = 'RMSD' if plot_type == 'rmsd' else 'Rg'
+        y_fallback = 'RMSD (nm)' if plot_type == 'rmsd' else 'Rg (nm)'
+        title = 'RMSD' if plot_type == 'rmsd' else 'Radius of Gyration'
+        for idx, (df, meta, label) in enumerate(data_list):
+            if y_col in df.columns and 'Time' in df.columns:
+                ra = df[y_col].rolling(window=roll_avg, min_periods=1, center=True).mean()
+                ax.plot(df['Time'], ra,
+                        color=MULTI_COLORS[idx % len(MULTI_COLORS)],
+                        linewidth=LINE_WIDTH_RA, label=label)
+
+    else:
+        # Generic XY
+        for idx, (df, meta, label) in enumerate(data_list):
+            x_col = df.columns[0]
+            y_col = df.columns[1] if len(df.columns) > 1 else df.columns[0]
+            if x_col in df.columns and y_col in df.columns:
+                ra = df[y_col].rolling(window=roll_avg, min_periods=1, center=True).mean()
+                ax.plot(df[x_col], ra,
+                        color=MULTI_COLORS[idx % len(MULTI_COLORS)],
+                        linewidth=LINE_WIDTH_RA, label=label)
+
+    x_title, y_title = resolve_axis_titles(data_list[0][1], 'X', 'Y')
+    ax.set_xlabel(x_title)
+    ax.set_ylabel(y_title)
+    ax.set_title(f'Comparison ({len(data_list)} files)')
+    ax.legend()
+    fig.tight_layout()
+    return fig
+
+
+def _compare_energy(
+    df1, meta1, df2, meta2, label1, label2, roll_avg
+) -> plt.Figure:
+    """Energy comparison: multi-panel grid with both datasets per panel."""
+    y_cols = [c for c in df1.columns if c != 'Time' and c in df2.columns]
+    n_y = len(y_cols)
+    if n_y == 0:
+        fig, ax = plt.subplots(figsize=FIGURE_SIZE_SINGLE)
+        return fig
+
+    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()
+    color1, color2 = COMPARE_COLORS
+
+    units = _parse_y_units(meta1.y_label)
+    y_titles = _build_y_titles(y_cols, units)
+
+    for idx, y_col in enumerate(y_cols):
+        ax = axes_flat[idx]
+        ra1 = df1[y_col].rolling(window=roll_avg, min_periods=1, center=True).mean()
+        ra2 = df2[y_col].rolling(window=roll_avg, min_periods=1, center=True).mean()
+        ax.plot(df1['Time'], ra1, color=color1, linewidth=LINE_WIDTH_RA, label=label1)
+        ax.plot(df2['Time'], ra2, color=color2, linewidth=LINE_WIDTH_RA, label=label2)
+        ax.set_ylabel(y_titles.get(y_col, y_col))
+        ax.set_title(y_col)
+
+    for idx in range(n_y, len(axes_flat)):
+        axes_flat[idx].set_visible(False)
+
+    x_title, _ = resolve_axis_titles(meta1, 'Time (ps)', '')
+    for ax_row in axes[-1]:
+        if ax_row.get_visible():
+            ax_row.set_xlabel(x_title)
+
+    fig.suptitle(f'Energy Comparison — {label1} vs {label2}', fontsize=14)
+    fig.tight_layout()
+    return fig
+
+
+def _compare_pca(df1, meta1, df2, meta2, label1, label2) -> plt.Figure:
+    """PCA comparison: side-by-side hexbin density plots."""
+    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(14, 6))
+
+    if 'PC1' in df1.columns and 'PC2' in df1.columns:
+        hb1 = ax1.hexbin(df1['PC1'], df1['PC2'], cmap='viridis', gridsize=30, mincnt=1)
+        fig.colorbar(hb1, ax=ax1, label='Density')
+    ax1.set_title(label1)
+
+    if 'PC1' in df2.columns and 'PC2' in df2.columns:
+        hb2 = ax2.hexbin(df2['PC1'], df2['PC2'], cmap='viridis', gridsize=30, mincnt=1)
+        fig.colorbar(hb2, ax=ax2, label='Density')
+    ax2.set_title(label2)
+
+    x_title, y_title = resolve_axis_titles(meta1, 'PC1', 'PC2')
+    ax1.set_xlabel(x_title)
+    ax1.set_ylabel(y_title)
+    ax2.set_xlabel(x_title)
+    ax2.set_ylabel(y_title)
+
+    fig.suptitle(f'PCA Comparison — {label1} vs {label2}', fontsize=14)
+    fig.tight_layout()
+    return fig
+
+
+def _compare_multi_energy(data_list: list, roll_avg: int) -> plt.Figure:
+    """Multi-file energy comparison: multi-panel grid with all files per panel."""
+    y_cols = [c for c in data_list[0][0].columns
+              if c != 'Time' and all(c in d[0].columns for d in data_list)]
+    n_y = len(y_cols)
+    if n_y == 0:
+        fig, ax = plt.subplots(figsize=FIGURE_SIZE_SINGLE)
+        return fig
+
+    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()
+
+    units = _parse_y_units(data_list[0][1].y_label)
+    y_titles = _build_y_titles(y_cols, units)
+
+    for idx, y_col in enumerate(y_cols):
+        ax = axes_flat[idx]
+        for file_idx, (df, meta, label) in enumerate(data_list):
+            if y_col in df.columns:
+                ra = df[y_col].rolling(window=roll_avg, min_periods=1, center=True).mean()
+                ax.plot(df['Time'], ra,
+                        color=MULTI_COLORS[file_idx % len(MULTI_COLORS)],
+                        linewidth=LINE_WIDTH_RA, label=label)
+        ax.set_ylabel(y_titles.get(y_col, y_col))
+        ax.set_title(y_col)
+
+    for idx in range(n_y, len(axes_flat)):
+        axes_flat[idx].set_visible(False)
+
+    x_title, _ = resolve_axis_titles(data_list[0][1], 'Time (ps)', '')
+    for ax_row in axes[-1]:
+        if ax_row.get_visible():
+            ax_row.set_xlabel(x_title)
+
+    fig.suptitle(f'Energy Comparison ({len(data_list)} files)', fontsize=14)
+    fig.tight_layout()
+    return fig
+
+
+def _compare_multi_pca(data_list: list) -> plt.Figure:
+    """Multi-file PCA comparison: multi-panel hexbin layout."""
+    n_files = len(data_list)
+    n_cols = min(3, n_files)
+    n_rows = max(1, (n_files + n_cols - 1) // n_cols)
+
+    fig, axes = plt.subplots(n_rows, n_cols, figsize=(14, 6 * n_rows), squeeze=False)
+    axes_flat = axes.flatten()
+
+    x_title, y_title = resolve_axis_titles(data_list[0][1], 'PC1', 'PC2')
+
+    for idx, (df, meta, label) in enumerate(data_list):
+        ax = axes_flat[idx]
+        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')
+        ax.set_xlabel(x_title)
+        ax.set_ylabel(y_title)
+        ax.set_title(label)
+
+    for idx in range(n_files, len(axes_flat)):
+        axes_flat[idx].set_visible(False)
+
+    fig.suptitle(f'PCA Comparison ({n_files} files)', fontsize=14)
+    fig.tight_layout()
+    return fig

gmxplot/config.py

@@ -0,0 +1,37 @@
+"""Default configuration constants for gmxplot."""
+
+# Figure defaults
+FIGURE_SIZE_SINGLE = (10, 6)
+FIGURE_SIZE_MULTI_ROW_HEIGHT = 4  # inches per row for multi-panel
+DPI_DEFAULT = 300
+
+# Line styling
+LINE_WIDTH_RAW = 1.0
+LINE_WIDTH_RA = 1.5
+RAW_ALPHA = 0.5
+
+# Colors
+RA_COLOR = '#1f77b4'
+RAW_COLOR = '#aec6cf'
+COMPARE_COLORS = ('#1f77b4', '#d62728')
+
+# Multi-file color palette (tab10)
+MULTI_COLORS = [
+    '#1f77b4', '#d62728', '#2ca02c', '#9467bd',
+    '#ff7f0e', '#8c564b', '#e377c2', '#7f7f7f',
+    '#bcbd22', '#17becf',
+]
+
+# Rolling average
+ROLL_AVG_DEFAULT_PLOT = None  # None = auto-calculate
+ROLL_AVG_DEFAULT_COMPARE = 50
+ROLL_AVG_MIN = 3
+ROLL_AVG_MAX = 100
+ROLL_AVG_FRACTION = 0.05  # 5% of data range
+
+# Plot type names
+PLOT_TYPES = ['energy', 'gyration', 'rmsd', 'rmsf', 'sasa', 'pca', 'xy', 'unknown']
+
+# Energy subplot layout
+ENERGY_MAX_COLS = 2
+ENERGY_PER_ROW = 2