torchref.io.cif module

CIF/mmCIF file format reading and writing.

This module provides functions for reading and writing CIF (Crystallographic Information File) format data, including: - Reflection data (structure factors) - Model data (atomic coordinates) - Restraint dictionaries - Electron density maps

Functions

read_reflections

Read reflection data from a CIF file.

read_model

Read atomic coordinates from a CIF file.

read_restraints

Read restraint dictionary from a CIF file.

list_data_blocks

List available data blocks in a CIF file.

write_map

Write electron density map to CCP4 format.

write_model

Write atomic coordinates to mmCIF format.

Classes

CIFReader

Generic CIF file reader.

ReflectionCIFReader

Reader for structure factor CIF files.

ModelCIFReader

Reader for mmCIF coordinate files.

RestraintCIFReader

Reader for restraint dictionary CIF files.

Examples

from torchref.io import cif

# Reading reflections
reader = cif.read_reflections('structure-sf.cif', verbose=1)
data_dict, cell, spacegroup = reader()

# Reading model
reader = cif.read_model('structure.cif')
df, cell, spacegroup = reader()

# Writing model (mmCIF)
from torchref.io.metadata import RefinementMetadata
meta = RefinementMetadata(r_work=0.18, r_free=0.21)
cif.write_model(df, 'refined.cif', metadata=meta)

# Reading restraints
reader = cif.read_restraints('ALA.cif')
restraints = reader.get_all_restraints()

# List data blocks
blocks = cif.list_data_blocks('multi-block.cif')

torchref.io.cif.read_reflections(filepath, data_block=None, verbose=0)

Read reflection data from a CIF file.

Parameters:

• filepath (str) – Path to the structure factor CIF file.

• data_block (str, optional) – Name of the data block to read. If None, uses the first block.

• verbose (int, optional) – Verbosity level. Default is 0.

Returns:

Reader object with data loaded.

Return type:

ReflectionCIFReader

Examples

reader = cif.read_reflections('structure-sf.cif')
data_dict, cell, spacegroup = reader()
hkl = data_dict['HKL']

torchref.io.cif.read_model(filepath, verbose=0)

Read atomic coordinates from a CIF file.

Parameters:

• filepath (str) – Path to the mmCIF coordinate file.

• verbose (int, optional) – Verbosity level. Default is 0.

Returns:

Reader object with data loaded.

Return type:

ModelCIFReader

Examples

reader = cif.read_model('structure.cif')
df, cell, spacegroup = reader()
print(f"Loaded {len(df)} atoms")

torchref.io.cif.read_restraints(filepath)

Read restraint dictionary from a CIF file.

Parameters:

filepath (str) – Path to the restraint dictionary CIF file.

Returns:

Reader object with restraints loaded.

Return type:

RestraintCIFReader

Examples

reader = cif.read_restraints('ALA.cif')
restraints = reader.get_all_restraints()

torchref.io.cif.list_data_blocks(filepath)

List available data blocks in a CIF file.

Parameters:

filepath (str) – Path to the CIF file.

Returns:

Names of available data blocks.

Return type:

list of str

Examples

blocks = cif.list_data_blocks('multi-dataset.cif')
print(f"Available blocks: {blocks}")

torchref.io.cif.write_map(data, cell, filepath, spacegroup='P1')

Write a 3D numpy array or torch tensor to a CCP4 map file.

Parameters:

• data (numpy.ndarray or torch.Tensor) – 3D array of map data.

• cell (list, numpy.ndarray, or torch.Tensor) – Unit cell parameters [a, b, c, alpha, beta, gamma] in A and degrees.

• filepath (str) – Output CCP4 filename.

• spacegroup (str, optional) – Space group symbol. Default is ‘P1’.

Returns:

Returns 1 on success.

Return type:

int

torchref.io.cif.dataframe_to_gemmi_structure(df, cell, spacegroup)

Convert a torchref atom DataFrame to a gemmi.Structure.

Parameters:

• df (pandas.DataFrame) – Atom DataFrame with standard torchref columns (ATOM, serial, name, altloc, resname, chainid, resseq, icode, x, y, z, occupancy, tempfactor, element, charge, anisou_flag, u11..u23).

• cell (list or numpy.ndarray) – Unit cell parameters [a, b, c, alpha, beta, gamma].

• spacegroup (str) – Space group name (Hermann-Mauguin notation).

Returns:

The constructed gemmi Structure object.

Return type:

gemmi.Structure

torchref.io.cif.write_model(df, filepath, metadata=None)

Write atomic coordinates to mmCIF file.

Parameters:

• df (pandas.DataFrame) – Atom DataFrame with standard torchref columns.

• filepath (str) – Output mmCIF file path.

• metadata (RefinementMetadata, optional) – Metadata to include in the mmCIF file (refinement statistics, title, authors, etc.).

torchref.io.cif.read(filepath, data_block=None, verbose=0)

Read reflection data from a CIF file.

Parameters:

• filepath (str) – Path to the structure factor CIF file.

• data_block (str, optional) – Name of the data block to read. If None, uses the first block.

• verbose (int, optional) – Verbosity level. Default is 0.

Returns:

Reader object with data loaded.

Return type:

ReflectionCIFReader

Examples

reader = cif.read_reflections('structure-sf.cif')
data_dict, cell, spacegroup = reader()
hkl = data_dict['HKL']