Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,12 @@

## Unreleased

- Added `remove-lipids` (`remove_cavity_lipids`) to detect and remove lipids
packed inside a protein cavity (e.g. a beta barrel interior), ported from
the standalone MemGen `remove_cavity_lipids.py` script. Lipid residues are
recognized from a bundled `lipid_fragments.json`, optionally overridden
with `--lipid-fragments-json`.

## 0.2.0 - 2026-07-29

- Added configurable cap inversion through the Python API and command-line interface.
Expand Down
10 changes: 9 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# MolPACD

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

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,
Expand Down Expand Up @@ -91,6 +92,13 @@ 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`.

Remove lipids packed inside a protein cavity (e.g. by packmol-memgen inside a
beta barrel interior):

```bash
molpacd remove-lipids packed.pdb -o cleaned.pdb
```

## Format Notes

MolPACD reads PDB and mmCIF files and writes minimal PDB/mmCIF outputs focused
Expand Down
8 changes: 8 additions & 0 deletions docs/advanced-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,14 @@ import-root API.

::: molpacd.capper

## Cavity Lipid Removal

::: molpacd.cavity_lipids

## Lipid Names

::: molpacd.lipids

## Data Models

::: molpacd.models
Expand Down
30 changes: 30 additions & 0 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,3 +79,33 @@ Additional options:
- `--force`: allow removal by residue/chain/atom match when metadata is absent
or overridden.
- `--json`: write machine-readable JSON.

## Remove Cavity Lipids

Remove lipids that packing tools (such as packmol-memgen) placed inside a
protein cavity, e.g. the interior of a beta barrel, instead of only in the
surrounding bilayer.

```bash
molpacd remove-lipids packed.pdb -o cleaned.pdb
molpacd remove-lipids packed.pdb -o cleaned.pdb --cavity-radius 8.0 --margin 2.0 --json
```

The cavity is estimated from the protein's CA atoms (falling back to all
protein atoms if none are found): a principal axis and center from PCA, and
an inner radius from the average backbone radius. Lipid residues (grouped by
chain and residue number, since a lipid is often stored as separate head/tail
fragment residues) whose center of mass falls inside that cavity, plus
`--margin`, are removed.

Lipid residue names are recognized from a bundled `lipid_fragments.json`
mapping full lipid names (e.g. `POPC`) to their head/tail fragment residue
names (e.g. `OL`, `PA`, `PC`). Additional options:

- `--cavity-radius`: override the automatically estimated inner radius, in
Angstrom.
- `--margin`: additional margin added around the estimated cavity boundary
(default: 2.0 Angstrom).
- `--lipid-fragments-json`: path to a `lipid_fragments.json` file overriding
the bundled lipid fragment list.
- `--json`: write machine-readable JSON.
13 changes: 13 additions & 0 deletions docs/examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,16 @@ molpacd remove capped.pdb -o decapped.pdb --json
Removal uses MolPACD metadata when present. If metadata is absent, or if you
intentionally override metadata values, pass `--force` with explicit matching
criteria.

## Remove Lipids Packed Inside A Cavity

```bash
molpacd remove-lipids packed.pdb -o cleaned.pdb --json
```

Override the estimated cavity radius or margin when the automatic estimate
needs adjustment:

```bash
molpacd remove-lipids packed.pdb -o cleaned.pdb --cavity-radius 8.0 --margin 3.0
```
7 changes: 4 additions & 3 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

**MolPACD** is the **Molecular Pore Aperture Cap Designer**. It provides a
Python API and command line interface for analyzing pore openings, adding
molecular aperture caps, and removing MolPACD-generated caps from protein
structure files.
molecular aperture caps, removing MolPACD-generated caps, and removing lipids
packed inside protein cavities, from protein structure files.

MolPACD works with PDB and mmCIF inputs and writes minimal PDB/mmCIF outputs
focused on atom records plus MolPACD provenance metadata.
Expand Down Expand Up @@ -38,7 +38,8 @@ make docs-serve
## Start Here

- Follow the [Quick Start](quickstart.md) for common CLI and Python examples.
- Use the [Command Line](cli.md) reference for `analyze`, `add`, and `remove`.
- Use the [Command Line](cli.md) reference for `analyze`, `add`, `remove`, and
`remove-lipids`.
- Browse the [Basic API](api.md) for the import-root interface.
- Use the [Advanced API](advanced-api.md) for module-level details.

Expand Down
9 changes: 9 additions & 0 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,15 @@ requires `--force`.
molpacd remove capped.pdb -o decapped.pdb --resname DUM --chain Z --force
```

## Remove Cavity Lipids

```bash
molpacd remove-lipids packed.pdb -o cleaned.pdb --json
```

The cavity is estimated from the protein's CA atoms; override it with
`--cavity-radius` and `--margin` if needed.

## Python API

```python
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ Issues = "https://github.com/BlankenbergLab/molpacd/issues"
where = ["src"]

[tool.setuptools.package-data]
molpacd = ["py.typed"]
molpacd = ["py.typed", "data/lipid_fragments.json"]

[tool.pytest.ini_options]
addopts = "-ra"
Expand Down
15 changes: 14 additions & 1 deletion src/molpacd/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,31 @@

from molpacd._version import __version__
from molpacd.capper import add_caps, analyze_structure, remove_caps
from molpacd.cavity_lipids import remove_cavity_lipids
from molpacd.cavity_lipids_pdb import remove_cavity_lipids_pdb
from molpacd.io import read_structure, write_structure
from molpacd.models import AnalysisResult, CapOptions, CapResult, RemoveResult
from molpacd.models import (
AnalysisResult,
CapOptions,
CapResult,
CavityLipidOptions,
CavityLipidResult,
RemoveResult,
)

__all__ = [
"AnalysisResult",
"CapOptions",
"CapResult",
"CavityLipidOptions",
"CavityLipidResult",
"RemoveResult",
"__version__",
"add_caps",
"analyze_structure",
"read_structure",
"remove_caps",
"remove_cavity_lipids",
"remove_cavity_lipids_pdb",
"write_structure",
]
108 changes: 108 additions & 0 deletions src/molpacd/cavity_lipids.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
from __future__ import annotations

from typing import Optional, Tuple

import numpy as np

from molpacd.geometry import (
barrel_radii,
coord_tuple,
coords_from_atoms,
point_inside_cylinder,
principal_axis_pca,
)
from molpacd.lipids import classify_lipid_atoms, load_lipid_residue_names
from molpacd.models import (
CavityLipidOptions,
CavityLipidResult,
StructureData,
validate_cavity_lipid_options,
)


def remove_cavity_lipids(
structure: StructureData,
options: Optional[CavityLipidOptions] = None,
) -> Tuple[StructureData, CavityLipidResult]:
"""Remove lipids packed inside a protein cavity (e.g. a beta barrel).

Packmol-memgen can pack lipid tails into a protein's interior cavity
instead of only around its exterior. This estimates the cavity from the
protein's CA atoms and removes lipid residues whose center of mass falls
inside it, leaving lipids in the surrounding bilayer untouched.

This operates on an already-parsed `StructureData` (PDB or mmCIF, via
`molpacd.io.read_structure`), so writing the result back out goes through
molpacd's generic structure writer and does not reproduce the exact
formatting of the original input file. To preserve a PDB file's original
formatting exactly, use `remove_cavity_lipids_pdb` instead.
"""
options = options or CavityLipidOptions()
validate_cavity_lipid_options(options)
_ensure_single_model(structure)

lipid_residue_names = load_lipid_residue_names(options.lipid_fragments_json)
protein_atoms, lipid_residues, _other_atoms = classify_lipid_atoms(
structure.atoms, lipid_residue_names
)
if not protein_atoms:
raise ValueError("no protein atoms found; cannot determine a cavity")

ca_atoms = [atom for atom in protein_atoms if atom.name.strip().upper() == "CA"]
axis_atoms = ca_atoms if ca_atoms else protein_atoms
axis_coords = coords_from_atoms(axis_atoms)

center, axis = principal_axis_pca(axis_coords)
inner_radius, outer_radius, z_min, z_max = barrel_radii(axis_coords, center, axis)
if options.cavity_radius is not None:
inner_radius = options.cavity_radius

removed_keys = {
key
for key, atoms in lipid_residues.items()
if point_inside_cylinder(
np.mean(coords_from_atoms(atoms), axis=0),
center,
axis,
inner_radius,
z_min,
z_max,
options.margin,
)
}

kept_atoms = [
atom
for atom in structure.atoms
if not (
atom.resname.strip().upper() in lipid_residue_names
and (atom.chain_id, atom.res_seq) in removed_keys
)
]

result = CavityLipidResult(
total_lipid_residues=len(lipid_residues),
removed_lipid_residues=len(removed_keys),
kept_lipid_residues=len(lipid_residues) - len(removed_keys),
center=coord_tuple(center),
axis=coord_tuple(axis),
inner_radius=float(inner_radius),
outer_radius=float(outer_radius),
z_min=float(z_min),
z_max=float(z_max),
margin=options.margin,
)
cleaned = structure.with_atoms(kept_atoms)
return cleaned, result


def _ensure_single_model(structure: StructureData) -> None:
model_ids = structure.model_ids()
if len(model_ids) > 1:
raise ValueError(
"multi-model structures are not supported for cavity lipid removal; "
"split the structure into a single model first"
)


__all__ = ["remove_cavity_lipids"]
Loading
Loading