conformatlas 1.0.0__tar.gz

conformatlas-1.0.0/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-10-11
+
+First release after 0.1.1; all changes are described relative to 0.1.1.
+
+### Changed
+- **Frames are superposed before PCA.** The Python (MDAnalysis) backend least-squares fits every frame (Kabsch, proper rotations only) on the `--lsq-group` atoms to the reference structure and applies the transform to the `--cov-group` atoms before the covariance matrix is built, matching `gmx covar -fit`. In 0.1.1 `--lsq-group` was honoured only by the GROMACS backend and the Python backend ran Cartesian PCA on unfitted coordinates, so PC1/PC2 contained rigid-body translation and rotation. In `compare` all systems are superposed on one shared reference (the reference system's structure restricted to the common fit atoms). New options `--fit/--no-fit`, `--mass-weighted-fit`; YAML keys `pca.fit`, `pca.mass_weighted_fit`. With a `.tpr` topology (no reference coordinates) the first trajectory frame is the reference.
+- **'Backbone' follows the GROMACS definition (N, CA, C)** in both backends; the Python backend used the MDAnalysis `backbone` keyword (N, CA, C, O), so the two backends analysed different atoms and their eigenvalues differed by ~50 %. New group name `MainChain` = N, CA, C, O. Results obtained with the default group differ slightly from 0.1.1.
+- **Basin segmentation.** Density maxima on the grid border are valid watershed markers; every connected region of sampled space receives at least one marker; watershed runs on the full finite-energy support and isolated occupied bins inherit the nearest basin, so every frame is assigned (in 0.1.1, 43.5 % of the demo frames were "Unassigned"). Sub-basins separated by a barrier below `--min-barrier` (default 1 kT) are merged. Frames lying exactly on the right-most histogram edge are binned instead of dropped. Frames in sub-threshold minor basins are reported as "Unassigned / Minor".
+- **Convergence diagnostics.** Half-vs-half RMSIP pools the first halves of all replicates against the second halves (0.1.1 used the first replicate only) and reports each replicate in `rmsip.csv`; progressive overlap is computed for every fraction (0.1.1 hard-coded 1.0 at 100 %); population stability is computed on the first f % of every replicate (0.1.1 sliced the concatenated table, so the 25 % point contained replicate 1 only); cosine content is evaluated on the mean-centred series as in Hess's definition; interpretative notes use wording that matches the value. Fewer than 50 effective samples force the sampling verdict to "Insufficient evidence".
+- **Demonstration dataset.** `conformatlas example` and the bundled `examples/demo_dataset` encode genuine internal motion (hinge bending vs. twisting of the C-terminal half, switched by a two-state Markov chain) plus random rigid-body motion per frame; the 0.1.1 generator translated the whole peptide, i.e. its "states" disappeared under superposition.
+- `--bins` accepts `auto` (Freedman–Diaconis rule, clipped to 16–128 bins; now the default) or an integer; a warning is printed when the grid holds fewer than two frames per occupied bin.
+- `--lig` is functional: the ligand's atoms join the analysis group and the ligand RMSD after protein superposition is reported.
+- Figure axis labels follow the collective variables in use (PC, dPC, IC, RMSD/Rg, user labels; nm for the GROMACS backend, Å for the Python backend); CSV columns keep `PC1..PCn` for every decomposition.
+- Figures are written once as `<name>.png` and `<name>_unannotated.png` (the duplicate `<name>_non_annotated.png` copies are gone); the convergence figure wraps its notes so the panels keep their size; population error bars are clipped to [0, 100] %.
+- `cli.analyze` is a thin wrapper over `conformatlas.pipeline.run_analysis`, the full single-system workflow as a library function.
+- CLI: the banner is printed only on a terminal and never for `--help`/`--version`; `--quiet`; friendly messages instead of tracebacks for malformed YAML (with line/column), missing files, unknown group names (available groups are listed) and missing optional dependencies (with the `pip install` command); exit codes 0 (success), 1 (analysis error), 2 (usage error).
+- Common-atom mapping for comparisons is chain-aware (`chain/residue/atom` keys with automatic fallback when chain labels differ), so repeated residue numbers in multi-chain systems are no longer collapsed.
+- Project logo and brand assets (`docs/assets/`, generated by `docs/assets/make_logo.py`); README header uses the logo; Sphinx documentation carries the logo and favicon.
+
+### Added
+
+#### Inputs, time window and configuration
+- Time window `-b/--begin`, `-e/--end` (ps); GROMACS index files `-n/--index` for every group option and for comparisons (same atom numbering required across systems); group names may also be MDAnalysis selection strings.
+- Input validation before the run: structure/trajectory atom-count mismatch, broken Cα chains (periodic-boundary artefacts), memory estimate with a warning above 8 GB.
+- YAML configuration for `analyze` (`conformatlas init-config --type analyze`, `conformatlas analyze --config run.yaml`; command-line flags override the file). Comparison YAML accepts `begin_ps`, `end_ps`, `index_file`, `bins: auto`, `n_bootstrap`, `seed`, `bootstrap_mode` and the figure options.
+- `run_metadata.json` records every option, the superposition settings, the time window, equilibration, decomposition, CVs, weights, bootstrap and representative settings, all warnings, and the software environment (Python, NumPy, SciPy, pandas, matplotlib, scikit-image, click, Jinja2, PyYAML, MDAnalysis, WeasyPrint, GROMACS, platform; module `conformatlas.provenance`). `summary.json` carries uncertainties and N_eff.
+
+#### Decompositions and collective variables
+- `--pca-type dihedral`: dihedral PCA on sin/cos of backbone φ/ψ, optionally with side-chain χ₁/χ₂ or nucleic-acid backbone/glycosidic torsions (`--dihedral-set backbone|backbone+chi|chi|nucleic`).
+- `--pca-type tica --tica-lag N`: time-lagged independent component analysis with implied timescales (lags computed within replicates; PCA pre-reduction when frames do not greatly outnumber coordinates).
+- `--fel-pcs i,j` (any two retained components), `--n-components`, `--cv rmsd-rg`, and external CVs `--cv file --cv-file … --cv-cols … --cv-labels …` (PLUMED COLVAR, `.xvg`, CSV; one file per trajectory).
+- Per-frame statistical weights `--weights-file` for histogram, populations and bootstrap (kinetics are skipped for weighted frames).
+- SVD (dual) route for the covariance eigenproblem when 3N exceeds the number of frames.
+
+#### Uncertainty and sampling quality
+- **Block bootstrap** (`--bootstrap N`, default 200; `--seed`): circular blocks within each replicate, block length from the statistical inefficiency; standard deviation and 95 % interval of ΔG per bin (`fel/free_energy_bootstrap_*.npy`, `figures/fel_uncertainty.png`), of state populations (merged into `statistics/state_populations.csv`), state free energies (`states/state_free_energies.csv`) and barriers; 1-D projections of the landscape with bootstrap bands (`figures/fel_1d.png`).
+- `--bootstrap-mode resegment`: the watershed segmentation is re-run on every resample; reports the distribution of the number of states and per-state population intervals that include segmentation uncertainty.
+- Statistical inefficiency g and effective sample size N_eff per replicate (exact FFT autocorrelation estimator; `convergence/effective_samples.csv`).
+- Equilibration detection by the maximum-N_eff criterion (Chodera 2016) on the fit RMSD or on the landscape CVs (`--equilibration-on rmsd|cv`), reported in `convergence/equilibration.csv` and applied with `--equilibration auto`.
+- Per-replicate landscapes on the shared grid as a convergence view.
+
+#### States, barriers, kinetics and Markov state models
+- Saddle-point barriers between adjacent basins (`states/barriers.csv`).
+- Lag-1 kinetics within replicates: transition counts and probabilities, dwell times per visit with censoring flags, Markov mean first-passage times (`kinetics/`, `figures/state_timeseries.png`).
+- **Markov state models** (`--msm`; `--msm-lag`, `--msm-lags`, `--msm-clusters`, `--msm-clustering kmeans|regular-space`, `--msm-dmin`, `--msm-components`, …): microstates by k-means or regular-space clustering in the retained components, sliding-window counts within replicates, reversible maximum-likelihood transition matrix, implied-timescale scan with a reported (never auto-applied) plateau lag, Chapman–Kolmogorov test, PCCA+ metastable sets, mean first-passage times between sets, and an overlap table between metastable sets and watershed basins (`msm/`, with figures).
+
+#### Enhanced sampling
+- `conformatlas reweight metad`: metadynamics reweighting from PLUMED HILLS + COLVAR (final bias, or the time-dependent c(t) correction of Tiwary & Parrinello), writing weight files for `--weights-file`.
+- `conformatlas reweight umbrella`: umbrella-sampling weights and PMF by MBAR or WHAM (`pmf.csv`). Module `conformatlas.reweighting` with PLUMED COLVAR/HILLS readers.
+
+#### Structures, residues and descriptors
+- Representative structures: `--n-representatives N`, `--representative minimum|medoid`; per-state `average.pdb`, `rmsf_atoms.csv`, `rmsf_residues.csv`; `states/state_ensemble_summary.csv`.
+- Mode interpretation: per-atom and per-residue mode contributions (`pca/mode_contributions_*.csv`, `figures/mode_contributions.png`), `pca/modes.nmd` (VMD NMWiz / ProDy), `pca/average.pdb`, `pca/PC*_extremes.pdb`, `pca/eigenvectors.npy`.
+- Descriptors: backbone RMSD, radius of gyration, RMSF per atom and residue, and ligand RMSD with `--lig` (`descriptors/`, `figures/descriptors.png`).
+- `--residue-analysis`: dynamic cross-correlation maps (overall and per state), per-residue differences between states (ΔRMSF, displacement of state means), ligand–residue contact persistence per state and binding-site RMSF (`residues/`, with figures).
+
+#### Comparisons
+- `compare` with any number of systems: ΔΔG maps with bootstrap standard deviation against the reference system (`comparison/fel_diff_<SYS>_vs_<REF>.csv/.npy`, `figures/ddg_map_*.png`, hatched where |ΔΔG| < 2 SD); population differences with block-bootstrap interval and p-value and Welch's t-test across replicates (when each system has at least two); state ΔΔG with intervals; landscape overlap (Bhattacharyya coefficient, Hellinger distance, Jensen–Shannon divergence, sampled-bin Jaccard; `fel_overlap.csv`); RMSIP between each system's own essential subspace (`subspace_overlap.csv`); `comparison_summary.json`; bootstrap error bars on the population figures; side-by-side interactive comparison landscape.
+
+#### Performance and programmatic use
+- Streaming PCA engine (`--engine auto|memory|streaming`): chunked two-pass covariance accumulation with per-frame superposition that never holds the whole trajectory in memory, numerically identical to the in-memory path; `--n-workers` (one process per replicate), `--precision float32`, memory-mapped projection storage; `auto` switches to streaming above a memory threshold.
+- `--from <results_dir>`: re-bin, re-segment, re-bootstrap or build an MSM from an existing results directory without re-reading trajectories or recomputing PCA.
+- `--save-hdf5`: single-file results container `results.h5` (`conformatlas.results_io`: `save_results`, `load_results`, `load_results_dir`, `rebin`).
+- TTY-aware progress bars (`rich` when installed; silent in pipes and logs).
+- Python API `conformatlas.api` (`load_trajectories`, `pca`, `landscape`, `states`, `kinetics`, `convergence`, `analyze`, `plot_landscape`) returning in-memory objects; `conformatlas.mda_analysis.ConformAtlasPCA`, an MDAnalysis `AnalysisBase` implementation; notebook `examples/notebooks/neuraminidase_walkthrough.ipynb`; streaming benchmark in `benchmarks/`.
+
+#### Report and figures
+- Interactive HTML report: Plotly landscape with hover ΔG/probability/state, basin outlines, time-coloured per-replicate paths and a time slider, 1-D profile panel; embedded NGL viewer of the state representatives and the average structure coloured by per-residue RMSF; all JavaScript and structures are inlined (no external resources; `--plotly-js cdn` for a smaller file; `--interactive/--no-interactive`).
+- Interpretive sentences next to every table (N_eff and its consequence, RMSIP wording, interval widths, barriers in kT), a "Limits of this analysis" section and a warnings box; `report_interpretation.json`. Optional `report.pdf` (`--pdf`; static figures, stated in the PDF).
+- Figure control: `--fig-format png|svg|pdf|all` (SVG/PDF are vector), `--colormap`, `--font-scale`, `--fig-dpi`, `--path-overlay` (trajectory path on the static landscape).
+
+#### Validation, tests and documentation
+- Scientific validation suite `validation/validate.py` (report `validation/VALIDATION.md`): checks against analytical results and independent implementations — GROMACS `covar`, `anaeig`, `sham` and `gyrate`; MDAnalysis PCA, QCP superposition, RMSD/Rg/RMSF, Ramachandran and Janin dihedrals; pymbar (statistical inefficiency, equilibration, MBAR); deeptime (TICA, reversible MSM estimator, PCCA+); `plumed sum_hills`; SciPy; ProDy; analytical double wells, Gaussians and Markov chains; coverage of the bootstrap intervals and type-I error of the comparison test.
+- Unit and integration tests, including a real-protein fixture (influenza neuraminidase Cα + zanamivir heavy atoms, 81 frames, `tests/data/h1n1_ca/`).
+- Documentation: real-data tutorial (`docs/tutorial_neuraminidase.md`), FAQ of common pitfalls, validation/benchmark page generated from the validation results, Python API guide, methods sections for every new component with a "validated vs heuristic" summary; Sphinx builds with `-W`.
+- Project: `CONTRIBUTING.md` (including how to add a validation check), Contributor Covenant 2.1, issue forms and pull-request template, Codecov upload and a documentation job in CI, conda-forge recipe draft (`conda-recipe/`), JOSS paper draft (`paper/`), `.zenodo.json`, `requirements-lock.txt`.
+- Optional dependency groups: `pdf` (WeasyPrint), `interactive` (Plotly), `hdf5` (h5py), `progress` (rich), `all`.
+
+### Fixed
+- **GROMACS PCA backend**: `gmx anaeig -proj` writes one `&`-separated data set per eigenvector; the parser read them as a single column, so every component after the first was lost. Projections are now parsed per set.
+- **GROMACS PCA backend** built the covariance from the first trajectory only and projected the other replicates onto it; all trajectories are now concatenated (`gmx trjcat -cat`) before `gmx covar`, and the GROMACS and Python backends give identical explained variance.
+- XPM parser: `gmx sham` writes bin *edges* (width + 1 values) on the axis lines, which were rejected with a size error; edges are converted to centres, so `--fel-backend gromacs` works with current GROMACS.
+- Representative-structure extraction indexed the raw trajectory with the streamed frame index, which is wrong under `--stride`; frames are now located by time.
+
+### Removed
+- Second author entry in `pyproject.toml`; machine-specific paths in `TESTING_REPORT.md`.
+
+---
+
+## [0.1.1] - 2026-09-19
+
+### Added
+- Integrated comprehensive **ReadTheDocs** (`readthedocs.io`) documentation infrastructure:
+  - Added `.readthedocs.yaml` (v2 build configuration).
+  - Configured Sphinx documentation suite in `docs/conf.py` with MyST Markdown parser, MathJax, autodoc, and `sphinx_rtd_theme`.
+  - Created master documentation hub `docs/index.rst` and Python API reference `docs/api.rst`.
+  - Added `docs` optional dependencies (`sphinx`, `sphinx-rtd-theme`, `myst-parser`) in `pyproject.toml` and `docs/requirements.txt`.
+  - Added ReadTheDocs documentation status badge in `README.md`.
+- Hardened GitHub Actions CI/CD workflows:
+  - Structured pipeline into dedicated stages: `lint`, multi-OS matrix `test` (Python 3.10–3.12 on Ubuntu and macOS), and `build`.
+  - Added defensive integration testing safeguards (`@pytest.mark.skipif`) for headless CI environments lacking binary trajectory drivers.
+  - Added `MDAnalysis` and `twine` to developer test dependencies.
+
+### Changed
+- Standardized and formatted entire codebase using Ruff.
+- Incremented package version to `0.1.1`.
+
+---
+
+## [0.1.0] - 2026-09-19
+
+### Added
+- Initial public release of **ConformAtlas** (`conformatlas`).
+- Standard PEP 517/621 Python packaging layout (`pyproject.toml`, `src/conformatlas/`).
+- Subcommand-based command-line interface (`conformatlas`):
+  - `conformatlas analyze`: Single and multi-replicate trajectory PCA and FEL evaluation.
+  - `conformatlas compare`: WT vs mutant comparison in shared PCA coordinate space.
+  - `conformatlas doctor`: Environment, dependency, and GROMACS diagnostics.
+  - `conformatlas init-config`: Interactive and starter YAML template generation.
+  - `conformatlas example`: Miniature demonstration dataset generation.
+- Python-native 2D Free Energy Landscape (FEL) evaluation with Boltzmann inversion, explicit temperature validation ($T > 0$ K), and zero-occupancy masking.
+- Topological watershed segmentation on free energy grids for discrete conformational basin identification.
+- Automated extraction of full-atom representative PDB structures closest to basin energy minima with provenance metadata.
+- Multi-replicate analysis preserving replicate identity with balanced weighting (`equal-replicate` vs `frames`).
+- Shared-PCA space WT vs Mutant comparison with atom selection validation.
+- Rigorous sampling and convergence diagnostics:
+  - First-half vs second-half subspace overlap (RMSIP).
+  - Progressive subspace overlap (25%, 50%, 75%, 100%).
+  - Principal component cosine content (diffusion check).
+  - State population stability trajectories.
+- Statistical uncertainty reporting (replicate Mean, SD, SEM, and 95% Confidence Intervals).
+- Standalone 300-DPI publication figures with boundary-aware labels, dynamic headroom, and unannotated variants.
+- Self-contained interactive HTML report with embedded figures and parameter manifests.
+- Machine-readable execution logs and metadata (`run_metadata.json`, `summary.json`).
+- Automated test suite covering unit and end-to-end integration workflows.

conformatlas-1.0.0/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "If you use ConformAtlas in your research, please cite it as below."
+title: "ConformAtlas: mapping conformational landscapes from molecular simulations"
+version: 1.0.0
+date-released: 2026-10-11
+url: "https://github.com/AtharvaTilewale/ConformAtlas"
+repository-code: "https://github.com/AtharvaTilewale/ConformAtlas"
+authors:
+  - family-names: "Tilewale"
+    given-names: "Atharva"
+  - family-names: "Patel"
+    given-names: "Dhaval"
+keywords:
+  - "molecular dynamics"
+  - "GROMACS"
+  - "principal component analysis"
+  - "free energy landscape"
+  - "conformational states"
+  - "biophysics"
+  - "conformatlas"
+license: "MIT"

conformatlas-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Atharva Tilewale and ConformAtlas Contributors
+
+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.

conformatlas-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md
+include CITATION.cff
+include requirements.txt

conformatlas-1.0.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: conformatlas
+Version: 1.0.0
+Summary: ConformAtlas: mapping conformational landscapes from molecular simulations
+Author: Atharva Tilewale, Dhaval Patel
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AtharvaTilewale/ConformAtlas
+Project-URL: Documentation, https://conformatlas.readthedocs.io
+Project-URL: Repository, https://github.com/AtharvaTilewale/ConformAtlas
+Keywords: molecular-dynamics,gromacs,pca,free-energy-landscape,biophysics,structural-biology,conformatlas
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22.0
+Requires-Dist: scipy>=1.8.0
+Requires-Dist: pandas>=1.4.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scikit-image>=0.19.0
+Requires-Dist: MDAnalysis>=2.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: build>=0.10.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: plotly>=5.18; extra == "dev"
+Requires-Dist: h5py>=3.6; extra == "dev"
+Requires-Dist: rich>=12; extra == "dev"
+Requires-Dist: deeptime>=0.4; extra == "dev"
+Requires-Dist: pymbar>=4.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=6.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
+Requires-Dist: myst-parser>=1.0.0; extra == "docs"
+Provides-Extra: pdf
+Requires-Dist: weasyprint>=59.0; extra == "pdf"
+Provides-Extra: interactive
+Requires-Dist: plotly>=5.18; extra == "interactive"
+Provides-Extra: hdf5
+Requires-Dist: h5py>=3.6; extra == "hdf5"
+Provides-Extra: progress
+Requires-Dist: rich>=12; extra == "progress"
+Provides-Extra: all
+Requires-Dist: weasyprint>=59.0; extra == "all"
+Requires-Dist: plotly>=5.18; extra == "all"
+Requires-Dist: h5py>=3.6; extra == "all"
+Requires-Dist: rich>=12; extra == "all"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AtharvaTilewale/ConformAtlas/main/docs/assets/conformatlas-logo-on-white.png" alt="ConformAtlas" width="560" />
+</p>
+
+<h3 align="center">Mapping conformational landscapes from molecular simulations</h3>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg" alt="Python 3.10 | 3.11 | 3.12"></a>
+  <a href="https://github.com/AtharvaTilewale/ConformAtlas/actions/workflows/ci.yml"><img src="https://github.com/AtharvaTilewale/ConformAtlas/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://conformatlas.readthedocs.io/en/latest/"><img src="https://readthedocs.org/projects/conformatlas/badge/?version=latest" alt="Documentation"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#what-you-get">Outputs</a> ·
+  <a href="#documentation">Documentation</a> ·
+  <a href="#citation">Citation</a>
+</p>
+
+---
+
+**ConformAtlas** turns molecular dynamics trajectories into a quantitative map of conformational space: principal components, a free-energy landscape with error bars, the metastable states on it, the barriers and rates between them, and a verdict on whether the sampling supports those numbers. It runs as a single command (`conformatlas analyze`) and as a Python library, reads anything [MDAnalysis](https://www.mdanalysis.org/) can open, and ships with a [validation suite](docs/benchmarks.md) that checks every numerical component against analytical results or an independent implementation.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AtharvaTilewale/ConformAtlas/main/docs/assets/readme-landscape.png" alt="Free-energy landscape of influenza neuraminidase bound to zanamivir" width="860" />
+  <br>
+  <sub>Influenza A/H1N1 neuraminidase bound to zanamivir, 2001 frames at 300 K: free-energy landscape on the first two Cα principal components with three watershed states (48 / 41 / 11 %). Unmodified <code>figures/fel_2d_3d.png</code> from a single <code>conformatlas analyze</code> run; see the <a href="docs/tutorial_neuraminidase.md">tutorial</a>.</sub>
+</p>
+
+## Features
+
+| | |
+|---|---|
+| **Decompositions** | Cartesian PCA after Kabsch superposition, backbone / side-chain / nucleic dihedral PCA, TICA with implied timescales; landscapes on any component pair, on RMSD vs R<sub>g</sub>, or on user-supplied collective variables |
+| **Free-energy landscape** | Boltzmann inversion at the simulation temperature (kJ/mol), automatic grid resolution, unsampled bins left empty; agrees with `gmx sham` on the same input |
+| **Uncertainty** | Circular block bootstrap within replicates: standard deviation and 95 % CI of every bin, state population, state free energy and barrier |
+| **States and kinetics** | Watershed segmentation with barrier-based merging, saddle-point barriers, transition matrix, dwell times, mean first-passage times; optional Markov state model (microstates, reversible estimator, implied-timescale scan, Chapman–Kolmogorov test, PCCA+) |
+| **Convergence** | Statistical inefficiency and effective sample size, equilibration detection, first/second-half subspace overlap, cosine content, population stability per replicate |
+| **Structures** | Representative and average structures per state, RMSF profiles, per-residue mode contributions, NMWiz mode files, dynamic cross-correlation maps, ligand–residue contacts |
+| **Comparisons** | Any number of systems projected into a shared PCA space: ΔΔG maps with uncertainty, population differences with bootstrap confidence intervals and p-values, landscape overlap metrics |
+| **Enhanced sampling** | `conformatlas reweight` turns PLUMED metadynamics or umbrella-sampling output into per-frame weights (final bias, Tiwary–Parrinello, WHAM, MBAR) for a reweighted landscape |
+| **Scale** | Streaming two-pass PCA engine with memory independent of trajectory length, multi-replicate aware, HDF5 results container, re-analysis of saved results without re-reading trajectories |
+| **Reporting** | Self-contained HTML report with interactive landscape and 3-D structure viewer, publication-ready PNG/SVG/PDF figures, optional PDF report |
+
+## Installation
+
+```bash
+pip install conformatlas            # core (includes MDAnalysis)
+pip install "conformatlas[all]"     # + interactive figures, HDF5, progress bars, PDF report
+```
+
+From source:
+
+```bash
+git clone https://github.com/AtharvaTilewale/ConformAtlas.git
+cd ConformAtlas
+pip install -e ".[dev]"
+conformatlas doctor                 # checks Python dependencies and GROMACS (optional)
+```
+
+Requires Python ≥ 3.10. GROMACS is optional and only needed for `--pca-backend gromacs`.
+
+## Quick start
+
+**Analyse one system** (any number of replicates):
+
+```bash
+conformatlas analyze -s topology.gro -f rep1.xtc -f rep2.xtc -f rep3.xtc -T 300 -o results/WT
+```
+
+**Protein–ligand complex**, discarding the equilibration phase and adding a Markov state model:
+
+```bash
+conformatlas analyze -s md.gro -f md_noPBC.xtc -n index.ndx \
+    --cov-group C-alpha --lig ZMR -T 300 \
+    --equilibration auto --bootstrap 200 --msm \
+    -o results/complex
+```
+
+**Compare conditions** (wild type vs mutant, apo vs holo, …) in a shared PCA space:
+
+```bash
+conformatlas compare --config comparison.yaml -o results/comparison
+```
+
+**Try it** on the bundled synthetic two-state peptide:
+
+```bash
+conformatlas example -o demo
+conformatlas analyze -s demo/WT/topology.pdb -f demo/WT/rep1.xtc -f demo/WT/rep2.xtc -T 300 --bins 32 --smooth-sigma 1.0 -o demo/results
+```
+
+Every option can live in a YAML file (`conformatlas init-config --type analyze -o run.yaml`). Trajectories must be made whole across periodic boundaries first (`gmx trjconv -pbc mol`). The full option reference is in [docs/cli.md](docs/cli.md).
+
+From Python:
+
+```python
+from conformatlas import api
+
+ens  = api.load_trajectories("topology.gro", ["rep1.xtc", "rep2.xtc"], group="C-alpha")
+pcs  = api.pca(ens)
+land = api.landscape(pcs, temperature=300)
+st   = api.states(land)
+fig, ax, _ = api.plot_landscape(land, states=st.states)
+```
+
+## What you get
+
+```text
+results/
+├── report.html         # interactive landscape, structure viewer, interpretation
+├── summary.json        # state populations and minima, convergence assessment
+├── pca/                # eigenvalues, projections, eigenvectors, modes.nmd, mode contributions
+├── fel/                # free-energy grid, probability, bootstrap SD and CI
+├── states/             # basins, frame assignments, barriers, state ΔG, representative structures
+├── statistics/         # populations with block SD/SEM and bootstrap 95 % CI
+├── kinetics/  msm/     # transition matrices, dwell times, MFPT; MSM diagnostics (--msm)
+├── convergence/        # RMSIP, N_eff, equilibration, cosine content, population stability
+├── residues/           # DCCM, state differences, ligand contacts (--residue-analysis)
+└── figures/            # 2-D/3-D landscapes, uncertainty maps, kinetics, MSM, DCCM panels
+```
+
+Units: Å, ps, kJ/mol. The complete file manifest is in [docs/outputs.md](docs/outputs.md).
+
+## Validation
+
+`validation/validate.py` compares every numerical component with an analytical result or an independent implementation — MDAnalysis, GROMACS (`covar`, `anaeig`, `sham`), pymbar, deeptime, SciPy and ProDy — and writes the report that is published as [docs/benchmarks.md](docs/benchmarks.md) (147/147 checks). Components that are conventions rather than derivations (convergence thresholds, grid heuristics, MSM lag selection) are labelled as such in [docs/methods.md](docs/methods.md).
+
+Boltzmann inversion assumes an unbiased equilibrium ensemble; for biased simulations use `conformatlas reweight` and `--weights-file`. See the [FAQ](docs/faq.md) for this and other pitfalls.
+
+## Documentation
+
+Full documentation: **[conformatlas.readthedocs.io](https://conformatlas.readthedocs.io)**
+
+| Getting started | Reference | Background |
+|---|---|---|
+| [Installation](docs/installation.md) | [Command line](docs/cli.md) | [Methods](docs/methods.md) |
+| [Quickstart](docs/quickstart.md) | [Python API](docs/python_api.md) | [Interpreting results](docs/interpretation.md) |
+| [Tutorial: neuraminidase–zanamivir](docs/tutorial_neuraminidase.md) | [Output files](docs/outputs.md) | [Convergence diagnostics](docs/convergence.md) |
+| [FAQ](docs/faq.md) | [Comparing systems](docs/comparison.md) | [Validation and benchmarks](docs/benchmarks.md) |
+
+## Citation
+
+```bibtex
+@software{conformatlas2026,
+  author  = {Tilewale, Atharva and Patel, Dhaval},
+  title   = {ConformAtlas: mapping conformational landscapes from molecular simulations},
+  year    = {2026},
+  version = {1.0.0},
+  url     = {https://github.com/AtharvaTilewale/ConformAtlas}
+}
+```
+
+A machine-readable citation is in [CITATION.cff](CITATION.cff).
+
+## Contributing
+
+Bug reports, feature requests and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Please run `ruff check`, the test suite and `validation/validate.py` before opening a pull request.
+
+## Authors and license
+
+Developed by **Atharva Tilewale** and **Dhaval Patel**. Released under the [MIT License](LICENSE).

conformatlas-1.0.0/README.md

@@ -0,0 +1,164 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AtharvaTilewale/ConformAtlas/main/docs/assets/conformatlas-logo-on-white.png" alt="ConformAtlas" width="560" />
+</p>
+
+<h3 align="center">Mapping conformational landscapes from molecular simulations</h3>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg" alt="Python 3.10 | 3.11 | 3.12"></a>
+  <a href="https://github.com/AtharvaTilewale/ConformAtlas/actions/workflows/ci.yml"><img src="https://github.com/AtharvaTilewale/ConformAtlas/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://conformatlas.readthedocs.io/en/latest/"><img src="https://readthedocs.org/projects/conformatlas/badge/?version=latest" alt="Documentation"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#what-you-get">Outputs</a> ·
+  <a href="#documentation">Documentation</a> ·
+  <a href="#citation">Citation</a>
+</p>
+
+---
+
+**ConformAtlas** turns molecular dynamics trajectories into a quantitative map of conformational space: principal components, a free-energy landscape with error bars, the metastable states on it, the barriers and rates between them, and a verdict on whether the sampling supports those numbers. It runs as a single command (`conformatlas analyze`) and as a Python library, reads anything [MDAnalysis](https://www.mdanalysis.org/) can open, and ships with a [validation suite](docs/benchmarks.md) that checks every numerical component against analytical results or an independent implementation.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AtharvaTilewale/ConformAtlas/main/docs/assets/readme-landscape.png" alt="Free-energy landscape of influenza neuraminidase bound to zanamivir" width="860" />
+  <br>
+  <sub>Influenza A/H1N1 neuraminidase bound to zanamivir, 2001 frames at 300 K: free-energy landscape on the first two Cα principal components with three watershed states (48 / 41 / 11 %). Unmodified <code>figures/fel_2d_3d.png</code> from a single <code>conformatlas analyze</code> run; see the <a href="docs/tutorial_neuraminidase.md">tutorial</a>.</sub>
+</p>
+
+## Features
+
+| | |
+|---|---|
+| **Decompositions** | Cartesian PCA after Kabsch superposition, backbone / side-chain / nucleic dihedral PCA, TICA with implied timescales; landscapes on any component pair, on RMSD vs R<sub>g</sub>, or on user-supplied collective variables |
+| **Free-energy landscape** | Boltzmann inversion at the simulation temperature (kJ/mol), automatic grid resolution, unsampled bins left empty; agrees with `gmx sham` on the same input |
+| **Uncertainty** | Circular block bootstrap within replicates: standard deviation and 95 % CI of every bin, state population, state free energy and barrier |
+| **States and kinetics** | Watershed segmentation with barrier-based merging, saddle-point barriers, transition matrix, dwell times, mean first-passage times; optional Markov state model (microstates, reversible estimator, implied-timescale scan, Chapman–Kolmogorov test, PCCA+) |
+| **Convergence** | Statistical inefficiency and effective sample size, equilibration detection, first/second-half subspace overlap, cosine content, population stability per replicate |
+| **Structures** | Representative and average structures per state, RMSF profiles, per-residue mode contributions, NMWiz mode files, dynamic cross-correlation maps, ligand–residue contacts |
+| **Comparisons** | Any number of systems projected into a shared PCA space: ΔΔG maps with uncertainty, population differences with bootstrap confidence intervals and p-values, landscape overlap metrics |
+| **Enhanced sampling** | `conformatlas reweight` turns PLUMED metadynamics or umbrella-sampling output into per-frame weights (final bias, Tiwary–Parrinello, WHAM, MBAR) for a reweighted landscape |
+| **Scale** | Streaming two-pass PCA engine with memory independent of trajectory length, multi-replicate aware, HDF5 results container, re-analysis of saved results without re-reading trajectories |
+| **Reporting** | Self-contained HTML report with interactive landscape and 3-D structure viewer, publication-ready PNG/SVG/PDF figures, optional PDF report |
+
+## Installation
+
+```bash
+pip install conformatlas            # core (includes MDAnalysis)
+pip install "conformatlas[all]"     # + interactive figures, HDF5, progress bars, PDF report
+```
+
+From source:
+
+```bash
+git clone https://github.com/AtharvaTilewale/ConformAtlas.git
+cd ConformAtlas
+pip install -e ".[dev]"
+conformatlas doctor                 # checks Python dependencies and GROMACS (optional)
+```
+
+Requires Python ≥ 3.10. GROMACS is optional and only needed for `--pca-backend gromacs`.
+
+## Quick start
+
+**Analyse one system** (any number of replicates):
+
+```bash
+conformatlas analyze -s topology.gro -f rep1.xtc -f rep2.xtc -f rep3.xtc -T 300 -o results/WT
+```
+
+**Protein–ligand complex**, discarding the equilibration phase and adding a Markov state model:
+
+```bash
+conformatlas analyze -s md.gro -f md_noPBC.xtc -n index.ndx \
+    --cov-group C-alpha --lig ZMR -T 300 \
+    --equilibration auto --bootstrap 200 --msm \
+    -o results/complex
+```
+
+**Compare conditions** (wild type vs mutant, apo vs holo, …) in a shared PCA space:
+
+```bash
+conformatlas compare --config comparison.yaml -o results/comparison
+```
+
+**Try it** on the bundled synthetic two-state peptide:
+
+```bash
+conformatlas example -o demo
+conformatlas analyze -s demo/WT/topology.pdb -f demo/WT/rep1.xtc -f demo/WT/rep2.xtc -T 300 --bins 32 --smooth-sigma 1.0 -o demo/results
+```
+
+Every option can live in a YAML file (`conformatlas init-config --type analyze -o run.yaml`). Trajectories must be made whole across periodic boundaries first (`gmx trjconv -pbc mol`). The full option reference is in [docs/cli.md](docs/cli.md).
+
+From Python:
+
+```python
+from conformatlas import api
+
+ens  = api.load_trajectories("topology.gro", ["rep1.xtc", "rep2.xtc"], group="C-alpha")
+pcs  = api.pca(ens)
+land = api.landscape(pcs, temperature=300)
+st   = api.states(land)
+fig, ax, _ = api.plot_landscape(land, states=st.states)
+```
+
+## What you get
+
+```text
+results/
+├── report.html         # interactive landscape, structure viewer, interpretation
+├── summary.json        # state populations and minima, convergence assessment
+├── pca/                # eigenvalues, projections, eigenvectors, modes.nmd, mode contributions
+├── fel/                # free-energy grid, probability, bootstrap SD and CI
+├── states/             # basins, frame assignments, barriers, state ΔG, representative structures
+├── statistics/         # populations with block SD/SEM and bootstrap 95 % CI
+├── kinetics/  msm/     # transition matrices, dwell times, MFPT; MSM diagnostics (--msm)
+├── convergence/        # RMSIP, N_eff, equilibration, cosine content, population stability
+├── residues/           # DCCM, state differences, ligand contacts (--residue-analysis)
+└── figures/            # 2-D/3-D landscapes, uncertainty maps, kinetics, MSM, DCCM panels
+```
+
+Units: Å, ps, kJ/mol. The complete file manifest is in [docs/outputs.md](docs/outputs.md).
+
+## Validation
+
+`validation/validate.py` compares every numerical component with an analytical result or an independent implementation — MDAnalysis, GROMACS (`covar`, `anaeig`, `sham`), pymbar, deeptime, SciPy and ProDy — and writes the report that is published as [docs/benchmarks.md](docs/benchmarks.md) (147/147 checks). Components that are conventions rather than derivations (convergence thresholds, grid heuristics, MSM lag selection) are labelled as such in [docs/methods.md](docs/methods.md).
+
+Boltzmann inversion assumes an unbiased equilibrium ensemble; for biased simulations use `conformatlas reweight` and `--weights-file`. See the [FAQ](docs/faq.md) for this and other pitfalls.
+
+## Documentation
+
+Full documentation: **[conformatlas.readthedocs.io](https://conformatlas.readthedocs.io)**
+
+| Getting started | Reference | Background |
+|---|---|---|
+| [Installation](docs/installation.md) | [Command line](docs/cli.md) | [Methods](docs/methods.md) |
+| [Quickstart](docs/quickstart.md) | [Python API](docs/python_api.md) | [Interpreting results](docs/interpretation.md) |
+| [Tutorial: neuraminidase–zanamivir](docs/tutorial_neuraminidase.md) | [Output files](docs/outputs.md) | [Convergence diagnostics](docs/convergence.md) |
+| [FAQ](docs/faq.md) | [Comparing systems](docs/comparison.md) | [Validation and benchmarks](docs/benchmarks.md) |
+
+## Citation
+
+```bibtex
+@software{conformatlas2026,
+  author  = {Tilewale, Atharva and Patel, Dhaval},
+  title   = {ConformAtlas: mapping conformational landscapes from molecular simulations},
+  year    = {2026},
+  version = {1.0.0},
+  url     = {https://github.com/AtharvaTilewale/ConformAtlas}
+}
+```
+
+A machine-readable citation is in [CITATION.cff](CITATION.cff).
+
+## Contributing
+
+Bug reports, feature requests and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Please run `ruff check`, the test suite and `validation/validate.py` before opening a pull request.
+
+## Authors and license
+
+Developed by **Atharva Tilewale** and **Dhaval Patel**. Released under the [MIT License](LICENSE).