torchref.io.metadata module

Unified metadata dictionary for PDB deposition headers and mmCIF categories.

This module provides a RefinementMetadata dataclass that serves as the single source of truth for all deposition-related information. The same metadata can be rendered as PDB REMARK 3 header records or as PDBx/mmCIF _refine category fields.

Examples

from torchref.io.metadata import RefinementMetadata

# Build from a completed refinement
meta = RefinementMetadata.from_refinement(refinement)

# Render for output
pdb_header = meta.render_pdb_header()
cif_dict   = meta.render_cif_categories()

# Merge pass-through headers from input file
input_meta = RefinementMetadata.from_pdb_file("input.pdb")
meta = input_meta.merge(meta)

# Serialization
d = meta.to_dict()
meta2 = RefinementMetadata.from_dict(d)

class torchref.io.metadata.RefinementMetadata(program='TORCHREF', program_version='', refinement_method='', resolution_high=None, resolution_low=None, n_reflections_work=None, n_reflections_test=None, n_reflections_all=None, percent_free=None, r_work=None, r_free=None, b_mean_overall=None, b_min=None, b_max=None, rmsd_bond_lengths=None, rmsd_bond_angles=None, n_atoms_total=None, n_atoms_protein=None, n_atoms_solvent=None, solvent_model_ksol=None, solvent_model_bsol=None, cell=None, spacegroup=None, title='', authors=<factory>, passthrough_pdb_remarks=<factory>, passthrough_cif_categories=<factory>, custom_remarks=<factory>)[source]

Bases: object

Unified metadata for PDB headers and mmCIF categories.

Fields map to both PDB REMARK 3 lines and PDBx/mmCIF _refine category items. Only populated (non-None) fields are rendered.

Parameters:

program (str) – Refinement program name.
program_version (str) – Program version string.

program: str = 'TORCHREF'

program_version: str = ''

refinement_method: str = ''

resolution_high: float | None = None

resolution_low: float | None = None

n_reflections_work: int | None = None

n_reflections_test: int | None = None

n_reflections_all: int | None = None

percent_free: float | None = None

r_work: float | None = None

r_free: float | None = None

b_mean_overall: float | None = None

b_min: float | None = None

b_max: float | None = None

rmsd_bond_lengths: float | None = None

rmsd_bond_angles: float | None = None

n_atoms_total: int | None = None

n_atoms_protein: int | None = None

n_atoms_solvent: int | None = None

solvent_model_ksol: float | None = None

solvent_model_bsol: float | None = None

cell: List[float] | None = None

spacegroup: str | None = None

title: str = ''

authors: List[str]

passthrough_pdb_remarks: List[str]

passthrough_cif_categories: Dict[str, Any]

custom_remarks: List[str]

to_dict()[source]

Serialize to a JSON-compatible dictionary, dropping None values.

classmethod from_dict(d)[source]

Reconstruct from a dictionary (inverse of to_dict).

classmethod from_refinement(refinement)[source]

Extract metadata from a completed Refinement object.

Reuses existing statistics from collect_metrics(), get_rfactor(), and reflection data attributes. Silently skips any unavailable statistics.

Parameters:: refinement (torchref.refinement.Refinement) – A refinement object (after refinement is complete).

classmethod from_pdb_file(filepath)[source]

Extract header metadata from an existing PDB file.

Captures TITLE, AUTHOR, and REMARK records for pass-through.

classmethod from_cif_file(filepath)[source]

Extract refinement metadata from an existing mmCIF file.

Captures _struct.title, _audit_author.name, and _refine category items for pass-through.

merge(other)[source]

Merge other into self. Non-None values in other take precedence.

Pass-through containers are combined (not replaced).

Parameters:: other (RefinementMetadata) – Metadata to merge in (takes precedence for non-None fields).
Returns:: A new merged instance.
Return type:: RefinementMetadata

render_pdb_header()[source]

Render metadata as PDB header records (REMARK 3, TITLE, AUTHOR).

Returns:: Multi-line string ready to insert into a PDB file.
Return type:: str

render_cif_categories()[source]

Render metadata as mmCIF category dictionaries.

Returns a dict of dicts keyed by mmCIF category, with item names as keys and string values. Uses official PDBx/mmCIF field names.

Returns:: Nested dictionary {category: {field: value}}.
Return type:: dict

__init__(program='TORCHREF', program_version='', refinement_method='', resolution_high=None, resolution_low=None, n_reflections_work=None, n_reflections_test=None, n_reflections_all=None, percent_free=None, r_work=None, r_free=None, b_mean_overall=None, b_min=None, b_max=None, rmsd_bond_lengths=None, rmsd_bond_angles=None, n_atoms_total=None, n_atoms_protein=None, n_atoms_solvent=None, solvent_model_ksol=None, solvent_model_bsol=None, cell=None, spacegroup=None, title='', authors=<factory>, passthrough_pdb_remarks=<factory>, passthrough_cif_categories=<factory>, custom_remarks=<factory>)