Metadata-Version: 2.4
Name: fasthydromap
Version: 0.1.2
Summary: Predict per-residue Fdewet using SASA + MPNN
Author-email: Samuel Lobo <samuels.lobo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/samlobe/FastHydroMap
Project-URL: Repository, https://github.com/samlobe/FastHydroMap
Project-URL: Issues, https://github.com/samlobe/FastHydroMap/issues
Keywords: protein,hydrophobicity,molecular-dynamics,biophysics,machine-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3.0,>=1.26
Requires-Dist: pandas<3.0,>=2.2
Requires-Dist: mdtraj<2.0,>=1.10
Requires-Dist: pdbfixer
Requires-Dist: openmm<9,>=8.2
Requires-Dist: biopython>=1.85
Requires-Dist: tqdm
Requires-Dist: scipy>=1.11
Requires-Dist: scikit-learn
Requires-Dist: pyyaml
Requires-Dist: setuptools<81
Provides-Extra: torch
Requires-Dist: torch<2.12,>=2.2; extra == "torch"
Provides-Extra: inference
Requires-Dist: torch<2.12,>=2.2; extra == "inference"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# FastHydroMap

FastHydroMap predicts per-residue dewetting free energies (`Fdewet`) from protein structures and trajectories.

<p align="center">
  <img
    src="https://raw.githubusercontent.com/samlobe/FastHydroMap/main/images/FastHydroMap_image.png"
    alt="FastHydroMap overview"
    width="720"
  />
</p>

## Quick Start

Use a fresh Python environment. Python `3.11` to `3.14` are supported.

```bash
pip install fasthydromap
fasthydromap install-torch
fasthydromap predict your_structure.pdb -o outputs/your_structure_fdewet
```

`fasthydromap install-torch` defaults to the CPU build, which is usually the right choice for current FastHydroMap workloads because SASA preprocessing dominates runtime.

Advanced installation options, Docker usage, GPU Torch variants, and release workflows are documented in [INSTALL.md](https://github.com/samlobe/FastHydroMap/blob/main/docs/INSTALL.md) and [PYPI_RELEASE.md](https://github.com/samlobe/FastHydroMap/blob/main/docs/PYPI_RELEASE.md).

## Inputs

FastHydroMap supports:

- Single protein structures in `PDB` format
- Protein trajectories in `DCD` or `XTC` format together with a matching topology `PDB`

Typical usage:

```bash
# Single structure
fasthydromap predict examples/1A1U.pdb -o outputs/1A1U_fdewet

# Trajectory
fasthydromap predict-trajectory examples/proteinG.pdb examples/proteinG_short.dcd -o outputs/proteinG_fdewet
```

## Outputs

For a single structure, FastHydroMap writes:

- `*.csv`: one row per residue with `Fdewet`; with `--parts`, intrinsic and context columns are included
- `*.pdb`: a copy of the input structure with predicted `Fdewet` written to B-factors

For a trajectory, FastHydroMap writes wide CSV files containing one row per frame and one column per residue.
Use `--parts` to also write intrinsic, context, and per-frame summary CSVs.

## Model Scope

FastHydroMap was trained on structured single-chain proteins and the 20 canonical amino-acid chemistries.
Predictions for PTMs and other non-canonical chemistries should be treated cautiously.

## Visualization

FastHydroMap writes `Fdewet` values to the B-factor column of output PDBs, so you can color structures directly in molecular viewers.

ChimeraX:

```bash
color bfactor range 4,6.5 palette ^lipophilicity
```

PyMOL:

```bash
spectrum b, red_white_blue, minimum=4, maximum=6.5
```

For dynamic hydrophobicity visualization in a MD trajectory, see the teaching-oriented example script
[`scripts/chimerax_fdewet_trajectory_example.py`](scripts/chimerax_fdewet_trajectory_example.py) with a ChimeraX implementation you can adjust.

## Acknowledgements

[Shell Lab](https://theshelllab.org/) and [Shea Group](https://labs.chem.ucsb.edu/shea/joan-emma/)
