torchref.io.ihm module

IHM mmCIF reader and writer for kinetic ensemble data.

Provides IHMReader and IHMWriter for reading and writing IHM (Integrative/Hybrid Methods) mmCIF files that describe multi-state kinetic ensembles.

Requires the optional python-ihm dependency:

pip install torchref[ihm]

Detection of IHM files (via is_ihm_file) uses only gemmi and does not require python-ihm.

class torchref.io.ihm.IHMReader(filepath, verbose=0)[source]

Bases: object

Read IHM mmCIF files into torchref ModelCollection + IHMEnsembleMapping.

Uses python-ihm to parse IHM-specific categories (_ihm_multi_state_modeling, _ihm_model_group, etc.) and gemmi / ModelCIFReader to parse standard _atom_site data.

Parameters:

  • filepath (str) – Path to IHM mmCIF file.

  • verbose (int) – Verbosity level (0=silent, 1=info, 2=debug).

Examples

reader = IHMReader("ensemble.cif")
model_collection, mapping = reader(max_res=1.5)

# Or step by step:
mapping = reader.read_mapping()
mapping.atom_data_per_state = reader.read_atom_data(mapping)
model_collection = reader.build_model_collection(mapping)
__init__(filepath, verbose=0)[source]
static is_ihm_file(filepath)[source]

Quick check whether a CIF file contains IHM categories.

Uses gemmi to avoid requiring python-ihm for detection. Looks for _ihm_model_list or _ihm_multi_state_modeling loops.

Parameters:

filepath (str) – Path to a CIF/mmCIF file.

Return type:

bool

read_mapping()[source]

Parse IHM categories and build an IHMEnsembleMapping.

Reads the following IHM categories: - _ihm_multi_state_modeling -> states - _ihm_model_list -> model enumeration - _ihm_model_group + _ihm_model_group_link -> groups - _ihm_multi_state_model_group_link -> state-group fractions

Also extracts cell and spacegroup from standard mmCIF categories.

Return type:

IHMEnsembleMapping

read_atom_data(mapping)[source]

Extract per-state atom DataFrames using pdbx_PDB_model_num.

Reuses ModelCIFReader for robust _atom_site parsing, then splits by model number and maps to state IDs.

Parameters:

mapping (IHMEnsembleMapping) – Mapping with state info (specifically model_num per state).

Returns:

Mapping of state_id -> atom DataFrame.

Return type:

dict of int -> pandas.DataFrame

build_model_collection(mapping, max_res=1.5, radius_angstrom=4.0, device=None)[source]

Build a ModelCollection from parsed IHM data.

For each state, creates a ModelFT and loads atom data. Then assembles a ModelCollection with one timepoint per model group.

Parameters:

  • mapping (IHMEnsembleMapping) – Must have atom_data_per_state populated.

  • max_res (float) – Maximum resolution for FFT grid setup.

  • radius_angstrom (float) – Radius for electron density calculation.

  • device (torch.device, optional) – Device for model tensors.

Return type:

ModelCollection

__call__(max_res=1.5, radius_angstrom=4.0, device=None)[source]

Read IHM file and return (ModelCollection, IHMEnsembleMapping).

Parameters:

  • max_res (float) – Maximum resolution for FFT grid.

  • radius_angstrom (float) – Radius for electron density calculation.

  • device (torch.device, optional) – Device for tensors.

Return type:

tuple of (ModelCollection, IHMEnsembleMapping)

class torchref.io.ihm.IHMWriter(model_collection, mapping=None, datasets=None, verbose=0)[source]

Bases: object

Write a torchref ModelCollection to IHM mmCIF format.

Uses python-ihm to build a complete IHM System object and write it as a compliant mmCIF file.

Parameters:

  • model_collection (ModelCollection) – The collection to write.

  • mapping (IHMEnsembleMapping, optional) – Original mapping for round-tripping metadata. If None, creates a minimal mapping from the collection structure.

  • verbose (int) – Verbosity level.

Examples

writer = IHMWriter(model_collection, mapping=mapping)
writer.write("refined_ensemble.cif")

# Or without a pre-existing mapping:
writer = IHMWriter(model_collection)
writer.write("refined_ensemble.cif")
__init__(model_collection, mapping=None, datasets=None, verbose=0)[source]
write(filepath)[source]

Write IHM mmCIF file.

Builds a python-ihm System object with: - Entity and assembly from base model atom data - Multi-state definitions from mapping states - Model groups from mapping groups with population fractions - Atom coordinates per state via pdbx_PDB_model_num

Parameters:

filepath (str) – Output file path.

static mapping_from_kinetic_refinement(model_collection, state_names=None, time_delays=None)[source]

Build an IHMEnsembleMapping from a ModelCollection with optional kinetic metadata.

Parameters:

  • model_collection (ModelCollection) – The refined model collection.

  • state_names (list of str, optional) – Names for each base model / state. Default: state_1, state_2, …

  • time_delays (dict, optional) – Mapping of timepoint name -> time delay in seconds.

Return type:

IHMEnsembleMapping