molforge.structure¶
structure ¶
Structural analysis: superposition, RMSD, contacts, geometry, DSSP, SASA, dihedrals, clashes.
Workhorses for analyzing the geometric properties of protein structures and comparing them.
Common entry points
- :func:
rmsd— RMSD between two structures (with optional superposition). - :func:
superpose— Kabsch / Umeyama optimal rigid-body alignment. - :func:
contact_map/ :func:distance_map— residue-residue contact and distance matrices. - :func:
residue_contacts— all-atom contacts as a sorted list. - :func:
radius_of_gyration, :func:centroid, :func:center_of_mass— bulk geometric properties. - :func:
translate, :func:rotate, :func:center_at_origin— in-place coordinate transforms. - :func:
dssp/ :func:dssp_3state— Kabsch-Sander secondary- structure assignment (8-state and 3-state). - :func:
sasa/ :func:sasa_per_residue/ :func:total_sasa— solvent-accessible surface area (Shrake-Rupley). - :func:
phi/ :func:psi/ :func:omega/ :func:phi_psi_omega/ :func:ramachandran/ :func:dihedral— backbone dihedral angles.
BondLengthOutlier
dataclass
¶
BondLengthOutlier(
atom_i: int,
atom_j: int,
name_i: str,
name_j: str,
residue_i: tuple[str, int, str],
residue_j: tuple[str, int, str],
bond: str,
length: float,
ideal: float,
sigma: float,
deviation: float,
z_score: float,
)
A bond whose length deviates from ideal by more than max_z.
Attributes:
| Name | Type | Description |
|---|---|---|
atom_i, |
atom_j
|
Global atom indices into |
name_i, |
name_j
|
Atom names (e.g. |
residue_i, |
residue_j
|
|
bond |
str
|
Bond key from :data: |
length |
float
|
Measured length in Å. |
ideal |
float
|
Engh & Huber ideal length in Å. |
sigma |
float
|
Ideal standard deviation in Å. |
deviation |
float
|
|
z_score |
float
|
|
ChiralityResult
dataclass
¶
ChiralityResult(
residue: tuple[str, int, str],
ca_index: int,
configuration: ChiralityConfig,
volume: float,
)
Cα handedness of one residue.
Attributes:
| Name | Type | Description |
|---|---|---|
residue |
tuple[str, int, str]
|
|
ca_index |
int
|
Global atom index of the Cα. |
configuration |
ChiralityConfig
|
|
volume |
float
|
Signed tetrahedral volume in ų
( |
Clash
dataclass
¶
Clash(
atom_i: int,
atom_j: int,
element_i: str,
element_j: str,
distance: float,
vdw_sum: float,
overlap: float,
residue_i: tuple[str, int, str],
residue_j: tuple[str, int, str],
)
A single clashing pair of atoms.
Attributes:
| Name | Type | Description |
|---|---|---|
atom_i, |
atom_j
|
Global atom indices into |
element_i, |
element_j
|
Element symbols (upper-cased). |
distance |
float
|
Inter-atom distance in Å. |
vdw_sum |
float
|
Sum of the two van der Waals radii in Å. |
overlap |
float
|
|
residue_i, |
residue_j
|
|
RamachandranResult
dataclass
¶
RamachandranResult(
residue: tuple[str, int, str],
phi: float,
psi: float,
category: RamachandranCategory,
classification: RamachandranClass,
)
Classification of one residue's backbone conformation.
Attributes:
| Name | Type | Description |
|---|---|---|
residue |
tuple[str, int, str]
|
|
phi, |
psi
|
Backbone dihedrals in degrees. |
category |
RamachandranCategory
|
Which region set was used ( |
classification |
RamachandranClass
|
|
SuperpositionResult
dataclass
¶
SuperpositionResult(
rotation: NDArray[float64],
translation: NDArray[float64],
rmsd: float,
n_atoms: int,
mobile_aligned: NDArray[float32],
)
Result of a structural superposition.
Attributes:
| Name | Type | Description |
|---|---|---|
rotation |
NDArray[float64]
|
|
translation |
NDArray[float64]
|
|
rmsd |
float
|
Root-mean-square deviation of the superposed structures. |
n_atoms |
int
|
Number of atoms used in the superposition. |
mobile_aligned |
NDArray[float32]
|
|
bond_length_rmsd ¶
RMS deviation of all checked bonds from their ideal lengths (Å).
A standard-geometry quality metric: near zero for a well-refined model. Returns 0.0 when there are no checkable bonds.
check_bond_lengths ¶
check_bond_lengths(
protein: Protein,
*,
max_z: float = DEFAULT_MAX_Z,
include_cb: bool = True,
) -> list[BondLengthOutlier]
Backbone bonds whose length is more than max_z σ from ideal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
protein
|
Protein
|
Structure to check. |
required |
max_z
|
float
|
Outlier threshold in standard deviations (default 4). |
DEFAULT_MAX_Z
|
include_cb
|
bool
|
Also check the |
True
|
Returns:
| Type | Description |
|---|---|
list[BondLengthOutlier]
|
Outliers sorted by absolute z-score, worst first. |
has_bond_length_outliers ¶
has_bond_length_outliers(
protein: Protein,
*,
max_z: float = DEFAULT_MAX_Z,
include_cb: bool = True,
) -> bool
Whether protein has any backbone bond-length outlier.
ca_chirality ¶
ca_chirality(
n: NDArray[float64],
ca: NDArray[float64],
c: NDArray[float64],
cb: NDArray[float64],
*,
planar_tolerance: float = DEFAULT_PLANAR_TOLERANCE,
) -> ChiralityConfig
Classify a Cα centre as L / D / Planar.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
NDArray[float64]
|
Cartesian coordinates of the backbone N. |
required |
ca
|
NDArray[float64]
|
Cartesian coordinates of the Cα. |
required |
c
|
NDArray[float64]
|
Cartesian coordinates of the carbonyl C. |
required |
cb
|
NDArray[float64]
|
Cartesian coordinates of the Cβ. |
required |
planar_tolerance
|
float
|
|signed volume| (ų) at or below which the
centre is reported as |
DEFAULT_PLANAR_TOLERANCE
|
Returns:
| Type | Description |
|---|---|
ChiralityConfig
|
The chirality label. |
chirality_outliers ¶
chirality_outliers(
protein: Protein,
*,
planar_tolerance: float = DEFAULT_PLANAR_TOLERANCE,
) -> list[ChiralityResult]
Residues whose Cα is not the natural L configuration.
Returns the D and Planar residues (everything that is not a
clean L centre).
classify_chirality ¶
classify_chirality(
protein: Protein,
*,
planar_tolerance: float = DEFAULT_PLANAR_TOLERANCE,
) -> list[ChiralityResult]
Classify the Cα chirality of every eligible residue.
Residues without a full N / CA / C / CB set — glycine, or any residue missing one of those atoms — are skipped (glycine is achiral). Only protein residues are considered.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
protein
|
Protein
|
Structure to analyze. |
required |
planar_tolerance
|
float
|
See :func: |
DEFAULT_PLANAR_TOLERANCE
|
Returns:
| Name | Type | Description |
|---|---|---|
One |
list[ChiralityResult]
|
class: |
list[ChiralityResult]
|
chain/sequence order. |
has_chirality_outliers ¶
has_chirality_outliers(
protein: Protein,
*,
planar_tolerance: float = DEFAULT_PLANAR_TOLERANCE,
) -> bool
Whether protein has any non-L Cα centre.
clash_score ¶
clash_score(
protein: Protein,
*,
tolerance: float = DEFAULT_TOLERANCE,
bonded_separation: int = 3,
include_hydrogens: bool = False,
) -> float
Clashes per 1000 atoms — a single-number quality gate.
Lower is better; a well-refined structure scores near zero. The
denominator is the number of atoms actually considered (heavy atoms
unless include_hydrogens is set), so the score is comparable
across structures of different sizes. Returns 0.0 for an empty
structure.
find_clashes ¶
find_clashes(
protein: Protein,
*,
tolerance: float = DEFAULT_TOLERANCE,
bonded_separation: int = 3,
include_hydrogens: bool = False,
) -> list[Clash]
Find all steric clashes in protein.
A pair of atoms clashes when their van der Waals shells overlap by
at least tolerance Å and they are more than bonded_separation
inferred covalent bonds apart (see the module docstring).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
protein
|
Protein
|
The structure to check. |
required |
tolerance
|
float
|
Minimum overlap (Å) to count as a clash. Smaller values flag more (softer) contacts. |
DEFAULT_TOLERANCE
|
bonded_separation
|
int
|
Exclude atom pairs separated by at most this many inferred bonds (default 3 → 1-2, 1-3, 1-4 neighbours). Set to 0 to disable bonded exclusion. |
3
|
include_hydrogens
|
bool
|
Consider hydrogen atoms too. Off by default since folding output usually omits them. |
False
|
Returns:
| Type | Description |
|---|---|
list[Clash]
|
Clashes sorted worst-first (largest overlap). Empty when the |
list[Clash]
|
structure is clean or has fewer than two eligible atoms. |
has_clashes ¶
has_clashes(
protein: Protein,
*,
tolerance: float = DEFAULT_TOLERANCE,
bonded_separation: int = 3,
include_hydrogens: bool = False,
) -> bool
Whether protein has at least one steric clash.
contact_map ¶
contact_map(
protein: Protein,
*,
cutoff: float = 8.0,
atom_choice: AtomChoice = "cb",
exclude_neighbors: int = 0,
) -> NDArray[np.bool_]
Binary contact map at cutoff Å.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
protein
|
Protein
|
structure to analyze. |
required |
cutoff
|
float
|
distance below which residues are in contact (default 8.0 Å, the CASP standard for CB-CB). |
8.0
|
atom_choice
|
AtomChoice
|
which atom defines the residue position — defaults
to |
'cb'
|
exclude_neighbors
|
int
|
Set the diagonal band of width
|
0
|
Returns:
| Type | Description |
|---|---|
NDArray[bool_]
|
|
NDArray[bool_]
|
residue |
distance_map ¶
Compute a residue-by-residue distance map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
protein
|
Protein
|
structure to analyze. |
required |
atom_choice
|
AtomChoice
|
per-residue representative point — |
'ca'
|
Returns:
| Type | Description |
|---|---|
NDArray[float32]
|
|
NDArray[float32]
|
between the representative points. |
residue_contacts ¶
residue_contacts(
protein: Protein,
*,
cutoff: float = 5.0,
chain_a: str | None = None,
chain_b: str | None = None,
) -> list[tuple[tuple[str, int], tuple[str, int], float]]
List inter-residue contacts at the all-atom level.
Unlike :func:contact_map, this enumerates contacts as triples of
((chain_a, resid_a), (chain_b, resid_b), distance) and uses the
"any atom within cutoff" definition.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
protein
|
Protein
|
structure to analyze. |
required |
cutoff
|
float
|
distance threshold in Å (default 5.0). |
5.0
|
chain_a
|
str | None
|
If both |
None
|
chain_b
|
str | None
|
see |
None
|
Returns:
| Type | Description |
|---|---|
list[tuple[tuple[str, int], tuple[str, int], float]]
|
Sorted list of contact tuples. |
classify_ramachandran ¶
Classify every residue with a defined (φ, ψ) pair.
Residues at chain termini or across chain breaks (where φ or ψ is undefined) are skipped, so the result holds one entry per residue that actually has a backbone conformation to judge.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
protein
|
Protein
|
Structure to analyze. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
One |
list[RamachandranResult]
|
class: |
list[RamachandranResult]
|
chain/sequence order. |
dihedral ¶
dihedral(
p1: NDArray[floating],
p2: NDArray[floating],
p3: NDArray[floating],
p4: NDArray[floating],
) -> float
Compute the dihedral angle (in degrees) between four 3D points.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
p1
|
NDArray[floating]
|
|
required |
p2
|
NDArray[floating]
|
|
required |
p3
|
NDArray[floating]
|
|
required |
p4
|
NDArray[floating]
|
|
required |
Returns:
| Name | Type | Description |
|---|---|---|
float
|
Angle in degrees in |
|
convention |
matching Biopython's ``calc_dihedral``
|
a right-handed |
float
|
α-helix is φ ≈ −60°, ψ ≈ −45°. Uses the atan2 formula, which avoids |
|
float
|
the numerical issues of acos near |
|
float
|
sign. |
dihedrals_batch ¶
Vectorized dihedral over an array of atom quartets.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
quartets
|
NDArray[floating]
|
|
required |
Returns:
| Type | Description |
|---|---|
NDArray[float64]
|
|
omega ¶
ω (omega) angles per residue, degrees, NaN where undefined.
phi ¶
φ (phi) angles per residue, degrees, NaN where undefined.
phi_psi_omega ¶
phi_psi_omega(
protein: Protein,
) -> tuple[
NDArray[np.float64],
NDArray[np.float64],
NDArray[np.float64],
]
Per-residue backbone dihedrals (φ, ψ, ω) in degrees.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
protein
|
Protein
|
structure to analyze. |
required |
Returns:
| Type | Description |
|---|---|
NDArray[float64]
|
Three |
NDArray[float64]
|
degrees. Entries where the angle is undefined (chain termini, |
NDArray[float64]
|
missing backbone atoms) are |
psi ¶
ψ (psi) angles per residue, degrees, NaN where undefined.
ramachandran ¶
Per-residue (φ, ψ) pairs for Ramachandran-plot construction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
protein
|
Protein
|
structure to analyze. |
required |
Returns:
| Type | Description |
|---|---|
NDArray[float64]
|
|
NDArray[float64]
|
undefined contain |
ramachandran_favored_fraction ¶
Fraction of classifiable residues in the favored region.
A quality metric in the spirit of MolProbity's "Ramachandran
favored" percentage (here from the simplified region model). Returns
1.0 for a structure with no classifiable residues (nothing to
fault).
ramachandran_outliers ¶
Just the residues classified as Ramachandran outliers.
ramachandran_type ¶
ramachandran_type(
phi: float,
psi: float,
*,
category: RamachandranCategory = "General",
) -> RamachandranClass
Classify a single (φ, ψ) pair as Favored / Allowed / Outlier.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
phi
|
float
|
Backbone φ dihedral in degrees, in |
required |
psi
|
float
|
Backbone ψ dihedral in degrees, in |
required |
category
|
RamachandranCategory
|
Region set to use — |
'General'
|
Returns:
| Type | Description |
|---|---|
RamachandranClass
|
The region the pair falls in. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
dssp_3state ¶
Return the per-residue 3-state secondary-structure string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
protein
|
Protein
|
structure to analyze. |
required |
Returns:
| Type | Description |
|---|---|
str
|
A string of |
str
|
residue. |
bounding_box ¶
Axis-aligned bounding box of a structure.
Returns:
| Type | Description |
|---|---|
tuple[NDArray[float64], NDArray[float64]]
|
|
center_at_origin ¶
Translate the structure so its centroid is at the origin (in place).
center_of_mass ¶
Mass-weighted center of mass. Alias for centroid(mass_weighted=True).
centroid ¶
Geometric (or mass-weighted) centroid of a structure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
protein
|
Protein
|
input structure. |
required |
mass_weighted
|
bool
|
If True, weight by atomic mass (i.e. compute the center of mass instead). |
False
|
Returns:
| Type | Description |
|---|---|
NDArray[float64]
|
|
radius_of_gyration ¶
Radius of gyration — RMS distance from atoms to the center of mass.
A standard compactness metric: smaller Rg means more globular.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
protein
|
Protein
|
input structure. |
required |
mass_weighted
|
bool
|
If True (default), use mass-weighted Rg. |
True
|
Returns:
| Type | Description |
|---|---|
float
|
Radius of gyration in angstroms. |
rotate ¶
Apply a 3x3 rotation in place around the origin.
For a rotation around the centroid, translate to origin first, rotate,
then translate back. Use :func:center_at_origin as a helper.
translate ¶
Translate protein in place by vector.
Mutates the underlying AtomArray.coords directly — both
hierarchical and linear views reflect the change immediately.
rmsd_per_residue ¶
rmsd_per_residue(
mobile: Protein,
reference: Protein,
*,
subset: AtomSubset = "ca",
align: bool = True,
) -> NDArray[np.float32]
Per-residue RMSD after (optionally) aligning the structures globally.
Useful for spotting which loops moved between two conformations or where a folding model disagrees with experiment.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mobile
|
Protein
|
First structure (the one that is moved to align with reference). |
required |
reference
|
Protein
|
Second structure; must have the same residue count as |
required |
subset
|
AtomSubset
|
Atom selector for both the global alignment and the per-residue comparison. |
'ca'
|
align
|
bool
|
Whether to superpose first. |
True
|
Returns:
| Type | Description |
|---|---|
NDArray[float32]
|
|
rmsd_raw ¶
RMSD between two equal-length coordinate sets, no alignment.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
a
|
NDArray[floating]
|
First |
required |
b
|
NDArray[floating]
|
Second |
required |
Returns:
| Type | Description |
|---|---|
float
|
Root-mean-square deviation in the input units (Å for biology). |
sasa_per_residue ¶
sasa_per_residue(
protein: Protein,
*,
probe_radius: float = 1.4,
n_sphere_points: int = 100,
) -> NDArray[np.float64]
Per-residue SASA, summed across atoms in each residue.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
protein
|
Protein
|
input structure. |
required |
probe_radius
|
float
|
see :func: |
1.4
|
n_sphere_points
|
int
|
see :func: |
100
|
Returns:
| Type | Description |
|---|---|
NDArray[float64]
|
|
NDArray[float64]
|
in array order. |
total_sasa ¶
Total solvent-accessible surface area (Ų).
kabsch_rmsd ¶
kabsch_rmsd(
mobile: NDArray[floating],
reference: NDArray[floating],
*,
weights: NDArray[floating] | None = None,
) -> float
Return the minimum-RMSD over all rigid-body alignments.
Convenience wrapper around :func:superpose for when you only want
the RMSD value.
superpose ¶
superpose(
mobile: NDArray[floating],
reference: NDArray[floating],
*,
weights: NDArray[floating] | None = None,
) -> SuperpositionResult
Superpose mobile onto reference by optimal rigid-body fit.
Implements the Kabsch / Umeyama algorithm via SVD of the weighted covariance matrix. The returned rotation is guaranteed to be a proper rotation (det = +1), not a reflection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mobile
|
NDArray[floating]
|
|
required |
reference
|
NDArray[floating]
|
|
required |
weights
|
NDArray[floating] | None
|
Optional |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
SuperpositionResult
|
class: |
SuperpositionResult
|
post-superposition RMSD, and aligned mobile coords. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If shapes mismatch or fewer than 3 atoms are given (degenerate; rotation under-determined). |