topo.analysis package

Submodules

topo.analysis.native_contacts module

Per-domain and per-interface fraction of native contacts (Q).

Computes the fraction of native contacts Q for every domain (intra-domain) and every domain-domain interface (inter-domain) declared in a domain.yaml, for each frame of a coarse-grained (CG, Cα-only) trajectory.

Method

  1. Native contacts are defined ONCE from the all-atom reference structure: residues i, j form a native contact when they are more than local_separation residues apart in sequence (abs(i - j) > 3 by default) AND at least one pair of heavy atoms (one per residue) is within cutoff (4.5 Å by default). The reference Cα–Cα distance of each contact is stored.

  2. Contacts are grouped by domain using the residue sets in domain.yaml: - intra-domain : both residues in the same domain - interface : one residue in each of two domains

  3. For every CG frame, a native contact (i, j) is counted as formed when the instantaneous Cα–Cα distance satisfies d_CG(i, j) <= tolerance * d_native(i, j) (tolerance = 1.2). Q is the fraction of that group’s native contacts formed.

Use as a library (e.g. from the nscale optimizer) by importing the functions, or as a CLI:

python -m topo.analysis.native_contacts -d domain.yaml -r ref.pdb

-p cg.psf -f cg.dcd -o Q.csv

Residue numbering: domain.yaml uses 1-based residue numbers that run 1..n_residues in CG bead order; internally these map to 0-based indices (n - 1), which is also the Cα/bead order of the reference and CG models.

topo.analysis.native_contacts.build_native_contacts(group1, group2, heavy_positions, heavy_res, ca_positions, cutoff, local_separation)[source]

Build the native-contact list for one domain or interface.

Parameters:

  • group1 (set[int] or None) – 0-based residue-index sets: - group1 is None, group2 is None -> all residues (whole protein) - group1 set, group2 is None -> intra-domain (both in group1) - group1 set, group2 set -> interface (one in each)

  • group2 (set[int] or None) – 0-based residue-index sets: - group1 is None, group2 is None -> all residues (whole protein) - group1 set, group2 is None -> intra-domain (both in group1) - group1 set, group2 set -> interface (one in each)

  • heavy_positions ((A, 3) array) – Coordinates of all reference heavy (non-H) atoms.

  • heavy_res ((A,) int array) – 0-based residue index of each heavy atom.

  • ca_positions ((N, 3) array) – Reference Cα coordinates in 0-based residue order.

  • cutoff (float) – Heavy-atom distance defining a contact (Å).

  • local_separation (int) – Minimum sequence separation (abs(i - j) > local_separation).

Returns:

  • pairs ((M, 2) int array) – Native-contact residue index pairs (i < j), 0-based.

  • native_dist ((M,) float array) – Reference Cα–Cα distance for each contact.

topo.analysis.native_contacts.fraction_native_contacts(ca_positions, pairs, native_dist, tolerance)[source]

Q for one CG frame: fraction of native contacts with d_CG <= tolerance * d_native. Returns NaN if the group has no contacts.

topo.analysis.native_contacts.load_domains(domain_yaml, n_res)[source]

Read domains from domain.yaml as 0-based residue-index sets.

Returns:

  • domains (dict[str, np.ndarray]) – Domain name -> sorted array of 0-based residue indices.

  • n_residues (int) – n_residues declared in the file (validated against the structure).

topo.analysis.native_contacts.load_universe(*args, **kwargs)[source]

mda.Universe with the harmless placeholder-CRYST1 warning suppressed.

Some PDBs carry a dummy CRYST1  1 1 1 record; MDAnalysis then warns “1 A^3 CRYST1 record, this is usually a placeholder. Unit cell dimensions will be set to None.” That is expected for these non-periodic CG inputs, so we silence only that one UserWarning and let any others through.

topo.analysis.native_contacts.main()[source]

Score per-domain and per-interface native contacts for a CG trajectory.

Builds the native-contact lists once from the all-atom reference (whole protein, each domain, and each domain pair interface), then computes the fraction of native contacts (Q) for every frame of the CG DCD trajectory and writes the per-frame results to the output CSV.

Raises:

  • FileNotFoundError – If any of the reference, PSF, DCD or domain input files is missing.

  • ValueError – If the domain definition or CG bead count does not match the reference protein’s residue count.

topo.analysis.native_contacts.parse_args()[source]

Parse command-line arguments for the native-contacts (Q) driver.

Returns:

Parsed arguments: domain, reference, psf, dcd, output paths plus the cutoff, local_separation, tolerance, start_frame and end_frame scoring options.

Return type:

argparse.Namespace

topo.analysis.native_contacts.reference_residue_geometry(ref_universe)[source]

Return reference Cα positions (0-based residue order) and a mapping from each heavy atom to its 0-based protein-residue index.

Building an explicit universe-resindex -> 0-based position map makes the indexing robust to hetero residues or non-sequential numbering.

Module contents

Post-simulation trajectory analysis for TOPO CG models.

Currently provides native-contact order parameters (Q), per domain and per interface; future order parameters (dRMS, RMSD, inter-domain distances) belong here too.

topo.analysis.build_native_contacts(group1, group2, heavy_positions, heavy_res, ca_positions, cutoff, local_separation)[source]

Build the native-contact list for one domain or interface.

Parameters:

  • group1 (set[int] or None) – 0-based residue-index sets: - group1 is None, group2 is None -> all residues (whole protein) - group1 set, group2 is None -> intra-domain (both in group1) - group1 set, group2 set -> interface (one in each)

  • group2 (set[int] or None) – 0-based residue-index sets: - group1 is None, group2 is None -> all residues (whole protein) - group1 set, group2 is None -> intra-domain (both in group1) - group1 set, group2 set -> interface (one in each)

  • heavy_positions ((A, 3) array) – Coordinates of all reference heavy (non-H) atoms.

  • heavy_res ((A,) int array) – 0-based residue index of each heavy atom.

  • ca_positions ((N, 3) array) – Reference Cα coordinates in 0-based residue order.

  • cutoff (float) – Heavy-atom distance defining a contact (Å).

  • local_separation (int) – Minimum sequence separation (abs(i - j) > local_separation).

Returns:

  • pairs ((M, 2) int array) – Native-contact residue index pairs (i < j), 0-based.

  • native_dist ((M,) float array) – Reference Cα–Cα distance for each contact.

topo.analysis.fraction_native_contacts(ca_positions, pairs, native_dist, tolerance)[source]

Q for one CG frame: fraction of native contacts with d_CG <= tolerance * d_native. Returns NaN if the group has no contacts.

topo.analysis.load_domains(domain_yaml, n_res)[source]

Read domains from domain.yaml as 0-based residue-index sets.

Returns:

  • domains (dict[str, np.ndarray]) – Domain name -> sorted array of 0-based residue indices.

  • n_residues (int) – n_residues declared in the file (validated against the structure).

topo.analysis.reference_residue_geometry(ref_universe)[source]

Return reference Cα positions (0-based residue order) and a mapping from each heavy atom to its 0-based protein-residue index.

Building an explicit universe-resindex -> 0-based position map makes the indexing robust to hetero residues or non-sequential numbering.