torchref.io.mtz module

MTZ file format reading and writing.

This module provides functions for reading and writing MTZ files containing crystallographic reflection data (structure factor amplitudes, intensities, R-free flags, etc.).

Space groups are returned as gemmi.SpaceGroup objects for consistency throughout torchref.

Functions

read: Read an MTZ file and return a reader object.
write: Write reflection data to an MTZ file.

Classes

MTZReader: Reader class for MTZ files.

Examples

from torchref.io import mtz

# Reading
reader = mtz.read('data.mtz', verbose=1)
data_dict, cell, spacegroup = reader()
print(spacegroup.short_name())  # gemmi.SpaceGroup object

# Writing
mtz.write(df, cell, spacegroup, 'output.mtz')

class torchref.io.mtz.MTZReader(verbose=0, column_names=None)[source]

Bases: object

Reader for MTZ files containing crystallographic structure factor data.

This class reads MTZ files using reciprocalspaceship and extracts: - Miller indices (h, k, l) - Structure factor amplitudes or intensities - Associated uncertainties (sigma values) - R-free test set flags

verbose

Verbosity level for logging (0=silent, 1=normal, 2=debug).

Type:: int

data

Dictionary containing extracted data arrays.

Type:: dict

cell

Unit cell parameters [a, b, c, alpha, beta, gamma].

Type:: np.ndarray

spacegroup

Space group object.

Type:: gemmi.SpaceGroup

Examples

reader = mtz.read('data.mtz', verbose=1)
data_dict, cell, spacegroup = reader()
print(f"Found {len(data_dict['HKL'])} reflections in {spacegroup.short_name()}")

AMPLITUDE_PRIORITY = ['F-obs', 'FOBS', 'FP', 'F', 'F-obs-filtered', 'FOBS-filtered', 'F(+)', 'FPLUS', 'FMEAN', 'F-pk', 'F_pk', 'FO', 'FODD', 'F-model', 'FC', 'FCALC']

INTENSITY_PRIORITY = ['I-obs', 'IOBS', 'I', 'IMEAN', 'I-obs-filtered', 'IOBS-filtered', 'I(+)', 'IPLUS', 'IP', 'I-pk', 'I_pk', 'IHLI', 'I_full', 'IOBS_full', 'IO']

RFREE_FLAG_NAMES = ['R-free-flags', 'RFREE', 'FreeR_flag', 'FREE', 'R-free', 'Rfree', 'FREER', 'FREE_FLAG', 'test', 'TEST', 'free', 'Free']

__init__(verbose=0, column_names=None)[source]

Initialize MTZ reader.

Parameters:

verbose (int, optional) – Verbosity level (0=silent, 1=normal, 2=debug). Default is 0.
column_names (dict, optional) – Explicit column name mapping to override automatic detection. Supported keys: "F", "SIGF", "I", "SIGI". Example: {"F": "DFo", "SIGF": "sig_DFo"}.

read(filepath)[source]

Read an MTZ file and extract reflection data.

Parameters:: filepath (str) – Path to the MTZ file.
Returns:: Self, for method chaining.
Return type:: MTZReader

__call__()[source]

Return extracted data in a standardized format.

Returns:

data (dict) – Dictionary with extracted data arrays.
cell (np.ndarray) – Unit cell parameters [a, b, c, alpha, beta, gamma].
spacegroup (str) – Space group name string.

Return type:

Tuple[dict, ndarray, str]

torchref.io.mtz.read(filepath, verbose=0)[source]

Read an MTZ file.

Parameters:

filepath (str) – Path to the MTZ file.
verbose (int, optional) – Verbosity level. Default is 0.

Returns:

Reader object with data loaded.

Return type:

MTZReader

torchref.io.mtz.write(df, cell, spacegroup, filepath)[source]

Write a DataFrame to an MTZ file.

Parameters:

df (pandas.DataFrame) – DataFrame containing reflection data. Expected columns include H, K, L (Miller indices) and data columns like F_obs, I_obs, etc.
cell (list, numpy.ndarray, or torch.Tensor) – Unit cell parameters [a, b, c, alpha, beta, gamma] in A and degrees.
spacegroup (str or gemmi.SpaceGroup) – Space group symbol or gemmi SpaceGroup object.
filepath (str) – Output MTZ filename.

Returns:

Returns 1 on success.

Return type:

int

torchref.io.mtz.MTZ: alias of MTZReader