iphasimulator.analysis_contacts

Stream residue-to-whole-PHA minimum-image distances and sampled contacts.

Distances are in Å, public times in ns, and contact means strictly d < cutoff. No coordinate fitting, equilibration removal, or inference of binding/catalysis is performed. MDAnalysis/matplotlib are optional: install .[analysis].

Attributes

`MODES`
`BACKBONE_NAMES`
`TIME_ATOL_NS`

Classes

`ContactConfig`
`AtomSelections`
`ContactResult`

Functions

`load_config`(→ ContactConfig)	Load YAML; relative file/output paths are relative to the YAML directory.
`open_universe`(topology, trajectory)	Open exactly one trajectory, keeping XTC/TRR index sidecars off inputs.
`valid_box`(→ numpy.ndarray)	Require a finite, nondegenerate orthorhombic or triclinic periodic cell.
`heavy_atom_mask`(→ numpy.ndarray)	Exclude H/D/T and virtual sites using elements, then masses, then names.
`residue_metadata`(→ dict)
`select_atoms`(→ AtomSelections)	Keep selected atom indices; residue.atoms is used only for identity metadata.
`inspect_trajectory`(→ dict)	Stream every stored frame to validate its time, atom count, and box.
`choose_frames`(→ tuple[numpy.ndarray, dict])	Select an inclusive window; preview is evenly spread over eligible frames.
`minimum_atom_distances`(→ numpy.ndarray)	Minimum distance from each reference atom to PHA, with bounded pair buffers.
`residue_minima`(→ numpy.ndarray)
`contact_occupancy`(→ numpy.ndarray)	Residue × frame input; one binary event per frame, strict cutoff, % output.
`calculate_distances`(→ dict[str, numpy.ndarray])
`summarise`() → pandas.DataFrame)
`save_distances`(→ None)	Save metadata as JSON strings so loading never requires pickle.
`load_distances`(→ ContactResult)
`plot_contacts`([primary_cutoff_A, distance_vmax_A])	Regenerate figures from saved matrices; no trajectory access is needed.
`run_contacts`(→ pathlib.Path)	Inspect, calculate, and write one fresh, timestamped run; never overwrite.
`main`(→ int)

Module Contents

iphasimulator.analysis_contacts.MODES = ('all_heavy', 'sidechain_heavy')

iphasimulator.analysis_contacts.BACKBONE_NAMES

iphasimulator.analysis_contacts.TIME_ATOL_NS = 1e-05

class iphasimulator.analysis_contacts.ContactConfig

topology: pathlib.Path

trajectory: pathlib.Path

output_root: pathlib.Path

pha_selection: str

protein_selection: str = 'protein'

start_ns: float | None = None

end_ns: float | None = None

sample_interval_ns: float | None = None

modes: tuple[str, ...] = ('all_heavy', 'sidechain_heavy')

primary_cutoff_A: float = 4.5

extra_cutoffs_A: tuple[float, ...] = (4.0, 5.0)

preview_frames: int | None = 31

label: str = 'PHA–enzyme'

distance_block_size: int = 1024

property cutoffs_A: tuple[float, ...]

validate() → None

iphasimulator.analysis_contacts.load_config(path: str | pathlib.Path) → ContactConfig: Load YAML; relative file/output paths are relative to the YAML directory.

iphasimulator.analysis_contacts.open_universe(topology: str | pathlib.Path, trajectory: str | pathlib.Path)

Open exactly one trajectory, keeping XTC/TRR index sidecars off inputs.

MDAnalysis writes reader caches next to the supplied trajectory path. A temporary symlink directs those caches to scratch without copying the data. Neither the simulation files nor their directory is written to.

iphasimulator.analysis_contacts.valid_box(dimensions) → numpy.ndarray: Require a finite, nondegenerate orthorhombic or triclinic periodic cell.

iphasimulator.analysis_contacts.heavy_atom_mask(atoms) → numpy.ndarray

Exclude H/D/T and virtual sites using elements, then masses, then names.

Number-prefixed hydrogens (e.g. 1HB) are excluded in the name fallback. Element/mass data take precedence over names such as the heavy atom ND1.

iphasimulator.analysis_contacts.residue_metadata(residue) → dict

class iphasimulator.analysis_contacts.AtomSelections

protein: object

pha: object

heavy: object

residues: list[dict]

atom_rows: numpy.ndarray

mode_masks: dict[str, numpy.ndarray]

counts: dict[str, numpy.ndarray]

iphasimulator.analysis_contacts.select_atoms(universe, protein_selection: str, pha_selection: str) → AtomSelections: Keep selected atom indices; residue.atoms is used only for identity metadata.

iphasimulator.analysis_contacts.inspect_trajectory(universe, progress: Callable[[str], None] | None = None) → dict

Stream every stored frame to validate its time, atom count, and box.

XTC has no atom identities: count compatibility cannot prove atom ordering. Supply the corresponding unsliced topology/trajectory from the same system.

iphasimulator.analysis_contacts.choose_frames(times_ns, config: ContactConfig) → tuple[numpy.ndarray, dict]

Select an inclusive window; preview is evenly spread over eligible frames.

Explicit intervals require a regular native grid and an integer stride, so requested sampling is never silently rounded. The grid starts at the first stored frame inside the window. All-frame sampling may retain irregular times.

iphasimulator.analysis_contacts.minimum_atom_distances(reference, pha, box, block_size: int = 1024) → numpy.ndarray: Minimum distance from each reference atom to PHA, with bounded pair buffers.

iphasimulator.analysis_contacts.residue_minima(atom_distances, atom_rows, n_residues: int) → numpy.ndarray

iphasimulator.analysis_contacts.contact_occupancy(distances_A, cutoff_A: float) → numpy.ndarray

Residue × frame input; one binary event per frame, strict cutoff, % output.

Any missing frame makes that row unavailable; the denominator is never silently reduced to the number of finite observations.

class iphasimulator.analysis_contacts.ContactResult

times_ns: numpy.ndarray

frame_indices: numpy.ndarray

boxes_A_degrees: numpy.ndarray

residues: list[dict]

selected_atom_counts: dict[str, numpy.ndarray]

distances_A: dict[str, numpy.ndarray]

provenance: dict

iphasimulator.analysis_contacts.calculate_distances(universe, selections: AtomSelections, frame_indices, modes=MODES, block_size=1024, progress=None) → dict[str, numpy.ndarray]

iphasimulator.analysis_contacts.summarise(result: ContactResult, cutoffs_A=(4.0, 4.5, 5.0)) → pandas.DataFrame

iphasimulator.analysis_contacts.save_distances(result: ContactResult, path: str | pathlib.Path) → None: Save metadata as JSON strings so loading never requires pickle.

iphasimulator.analysis_contacts.load_distances(path: str | pathlib.Path) → ContactResult

iphasimulator.analysis_contacts.plot_contacts(result: ContactResult, output_dir: str | pathlib.Path, cutoffs_A=(4.0, 4.5, 5.0), primary_cutoff_A=4.5, distance_vmax_A=None) → list[pathlib.Path]: Regenerate figures from saved matrices; no trajectory access is needed.

iphasimulator.analysis_contacts.run_contacts(config: ContactConfig, progress: Callable[[str], None] | None = print) → pathlib.Path: Inspect, calculate, and write one fresh, timestamped run; never overwrite.

iphasimulator.analysis_contacts.main(argv=None) → int