iphasimulator.analysis_contacts =============================== .. py:module:: iphasimulator.analysis_contacts .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: iphasimulator.analysis_contacts.MODES iphasimulator.analysis_contacts.BACKBONE_NAMES iphasimulator.analysis_contacts.TIME_ATOL_NS Classes ------- .. autoapisummary:: iphasimulator.analysis_contacts.ContactConfig iphasimulator.analysis_contacts.AtomSelections iphasimulator.analysis_contacts.ContactResult Functions --------- .. autoapisummary:: iphasimulator.analysis_contacts.load_config iphasimulator.analysis_contacts.open_universe iphasimulator.analysis_contacts.valid_box iphasimulator.analysis_contacts.heavy_atom_mask iphasimulator.analysis_contacts.residue_metadata iphasimulator.analysis_contacts.select_atoms iphasimulator.analysis_contacts.inspect_trajectory iphasimulator.analysis_contacts.choose_frames iphasimulator.analysis_contacts.minimum_atom_distances iphasimulator.analysis_contacts.residue_minima iphasimulator.analysis_contacts.contact_occupancy iphasimulator.analysis_contacts.calculate_distances iphasimulator.analysis_contacts.summarise iphasimulator.analysis_contacts.save_distances iphasimulator.analysis_contacts.load_distances iphasimulator.analysis_contacts.plot_contacts iphasimulator.analysis_contacts.run_contacts iphasimulator.analysis_contacts.main Module Contents --------------- .. py:data:: MODES :value: ('all_heavy', 'sidechain_heavy') .. py:data:: BACKBONE_NAMES .. py:data:: TIME_ATOL_NS :value: 1e-05 .. py:class:: ContactConfig .. py:attribute:: topology :type: pathlib.Path .. py:attribute:: trajectory :type: pathlib.Path .. py:attribute:: output_root :type: pathlib.Path .. py:attribute:: pha_selection :type: str .. py:attribute:: protein_selection :type: str :value: 'protein' .. py:attribute:: start_ns :type: float | None :value: None .. py:attribute:: end_ns :type: float | None :value: None .. py:attribute:: sample_interval_ns :type: float | None :value: None .. py:attribute:: modes :type: tuple[str, ...] :value: ('all_heavy', 'sidechain_heavy') .. py:attribute:: primary_cutoff_A :type: float :value: 4.5 .. py:attribute:: extra_cutoffs_A :type: tuple[float, ...] :value: (4.0, 5.0) .. py:attribute:: preview_frames :type: int | None :value: 31 .. py:attribute:: label :type: str :value: 'PHA–enzyme' .. py:attribute:: distance_block_size :type: int :value: 1024 .. py:property:: cutoffs_A :type: tuple[float, ...] .. py:method:: validate() -> None .. py:function:: load_config(path: str | pathlib.Path) -> ContactConfig Load YAML; relative file/output paths are relative to the YAML directory. .. py:function:: 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. .. py:function:: valid_box(dimensions) -> numpy.ndarray Require a finite, nondegenerate orthorhombic or triclinic periodic cell. .. py:function:: 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. .. py:function:: residue_metadata(residue) -> dict .. py:class:: AtomSelections .. py:attribute:: protein :type: object .. py:attribute:: pha :type: object .. py:attribute:: heavy :type: object .. py:attribute:: residues :type: list[dict] .. py:attribute:: atom_rows :type: numpy.ndarray .. py:attribute:: mode_masks :type: dict[str, numpy.ndarray] .. py:attribute:: counts :type: dict[str, numpy.ndarray] .. py:function:: select_atoms(universe, protein_selection: str, pha_selection: str) -> AtomSelections Keep selected atom indices; residue.atoms is used only for identity metadata. .. py:function:: 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. .. py:function:: 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. .. py:function:: minimum_atom_distances(reference, pha, box, block_size: int = 1024) -> numpy.ndarray Minimum distance from each reference atom to PHA, with bounded pair buffers. .. py:function:: residue_minima(atom_distances, atom_rows, n_residues: int) -> numpy.ndarray .. py:function:: 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. .. py:class:: ContactResult .. py:attribute:: times_ns :type: numpy.ndarray .. py:attribute:: frame_indices :type: numpy.ndarray .. py:attribute:: boxes_A_degrees :type: numpy.ndarray .. py:attribute:: residues :type: list[dict] .. py:attribute:: selected_atom_counts :type: dict[str, numpy.ndarray] .. py:attribute:: distances_A :type: dict[str, numpy.ndarray] .. py:attribute:: provenance :type: dict .. py:function:: calculate_distances(universe, selections: AtomSelections, frame_indices, modes=MODES, block_size=1024, progress=None) -> dict[str, numpy.ndarray] .. py:function:: summarise(result: ContactResult, cutoffs_A=(4.0, 4.5, 5.0)) -> pandas.DataFrame .. py:function:: save_distances(result: ContactResult, path: str | pathlib.Path) -> None Save metadata as JSON strings so loading never requires pickle. .. py:function:: load_distances(path: str | pathlib.Path) -> ContactResult .. py:function:: 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. .. py:function:: run_contacts(config: ContactConfig, progress: Callable[[str], None] | None = print) -> pathlib.Path Inspect, calculate, and write one fresh, timestamped run; never overwrite. .. py:function:: main(argv=None) -> int