Metadata-Version: 2.4
Name: molpacd
Version: 0.1.0
Summary: Molecular Pore Aperture Cap Designer
Author: Jayadev Joshi, Bryan Raubenolt, Daniel Blankenberg
License-Expression: MIT
Project-URL: Homepage, https://github.com/BlankenbergLab/molpacd
Project-URL: Repository, https://github.com/BlankenbergLab/molpacd
Project-URL: Issues, https://github.com/BlankenbergLab/molpacd/issues
Keywords: protein,pore,channel,membrane,pdb,mmcif,molecular-dynamics
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: biopython>=1.80
Requires-Dist: numpy<2.5,>=1.21
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: mypy<2,>=1.8; extra == "dev"
Requires-Dist: nox>=2024.4.15; extra == "dev"
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: setuptools>=68; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Dynamic: license-file

# MolPACD

**MolPACD** is the **Molecular Pore Aperture Cap Designer**. It designs, adds,
analyzes, and removes molecular aperture caps in protein structures.

The first implementation is derived from the MemGen beta-barrel water-cap script,
but generalizes the workflow for PDB and mmCIF structures with configurable axes,
cap identity, and cap removal metadata.

## Install

From PyPI:

```bash
python -m pip install molpacd
```

From a local checkout:

```bash
python -m pip install .
```

For development:

```bash
python -m pip install -e ".[dev]"
```

With Conda, keep the environment local to the checkout:

```bash
conda env create -p .conda/molpacd-dev -f environment-dev.yml
conda run -p .conda/molpacd-dev python -m nox -s lint format mypy tests-3.13 build
```

Common development tasks are also available through `make`:

```bash
make env
make check
```

For documentation work:

```bash
make docs-deps
make docs-serve
```

## CLI

Analyze candidate apertures:

```bash
molpacd analyze input.pdb --json
```

Add caps to both apertures:

```bash
molpacd add input.pdb -o capped.pdb
```

Use a membrane-oriented z-axis and a fixed cap residue name:

```bash
molpacd add input.pdb -o capped.pdb --axis z --resname DUM
```

Use each aperture's inferred radius instead of sharing the larger radius:

```bash
molpacd add input.pdb -o capped.pdb --axis z --independent-radius
```

Remove MolPACD-generated caps:

```bash
molpacd remove capped.pdb -o decapped.pdb
```

Remove matching caps from a file without MolPACD metadata:

```bash
molpacd remove capped.pdb -o decapped.pdb --resname DUM --chain Z --force
```

MolPACD writes cap provenance metadata and uses it during removal so matching
non-cap atoms are not removed accidentally. If metadata is absent, or if you
override metadata values such as residue name, chain, or atom name, removal
requires `--force`.

## Format Notes

MolPACD reads PDB and mmCIF files and writes minimal PDB/mmCIF outputs focused
on atom records plus MolPACD metadata. It preserves PDB header lines before the
coordinate section, but it does not attempt to reproduce every original record
or mmCIF category. Multi-model structures are not supported for analysis or cap
addition; split those structures into single-model inputs before running
MolPACD.

## Library

```python
from pathlib import Path

from molpacd import CapOptions, add_caps, read_structure, write_structure

structure = read_structure(Path("input.pdb"))
capped, result = add_caps(structure, CapOptions(axis="z", resname="DUM"))
write_structure(capped, Path("capped.pdb"))

print(result.resname, result.added_count)
```

## Development Checks

```bash
python -m nox
```

The nox sessions run tests, linting, formatting checks, type checks, and package
build validation. GitHub Actions runs the same checks on pushes and pull requests.

## Documentation

The project documentation is built with MkDocs:

```bash
make docs
```
