torchref.cli.validate_ded module

Validate difference electron density (DED) by correlating DFo and DFc maps.

Takes separate dark and light MTZ files, computes weighted difference amplitudes internally, then compares weighted DFo and DFcalc maps using dark-state phases.

Supports Phenix-style atom selections for regional correlation analysis (e.g., around a ligand binding site).

Examples

# Basic validation (full cell correlation)
torchref.validate-ded -dsf dark.mtz -lsf light.mtz \
    -dm dark.pdb -lm light.pdb

# With light fraction and ligand masking (both models, default)
torchref.validate-ded -dsf dark.mtz -lsf light.mtz \
    -dm dark.pdb -lm light.pdb \
    --fraction 0.20 --selection "chain B and resname IBL" --mask-radius 2.5

# Mask from light model only
torchref.validate-ded -dsf dark.mtz -lsf light.mtz \
    -dm dark.pdb -lm light.pdb \
    --fraction 0.20 --selection "resname IBL" --mask-source light

# Full output with plots and CCP4 maps
torchref.validate-ded -dsf dark.mtz -lsf light.mtz \
    -dm dark.pdb -lm light.pdb \
    --fraction 0.20 --selection "resname IBL" --plot --write-maps -o validation/

from torchref.cli.validate_ded import setup_ded_context, compute_ded_maps

ctx = setup_ded_context("dark.mtz", "light.mtz", dmin=2.2)
result = compute_ded_maps(
    ctx, model_dark, model_light, fraction=0.18,
    selection="resname IBL", mask_radius=2.5,
)
print(result["reciprocal_cc_overall"])
torchref.cli.validate_ded.build_atom_mask(selection_xyz, real_space_grid, cell, mask_radius, device)[source]

Build a boolean voxel mask around selected atom positions.

Parameters:

  • selection_xyz (torch.Tensor) – Cartesian coordinates of selected atoms, shape (N, 3).

  • real_space_grid (torch.Tensor) – Real-space grid from get_real_grid().

  • cell (Cell or torch.Tensor) – Unit cell parameters (or Cell object with .data attribute).

  • mask_radius (float) – Radius in Angstroms around each atom to include.

  • device (torch.device) – Device for tensor operations.

Returns:

Boolean mask of shape grid_shape[:3].

Return type:

torch.Tensor

torchref.cli.validate_ded.compute_correlation(map1, map2, mask)[source]

Pearson correlation coefficient between two maps within a mask.

torchref.cli.validate_ded.compute_map_from_coefficients(amplitudes, phases_rad, hkl_p1, gridsize)[source]

Compute a real-space map from Fourier coefficients.

Parameters:

  • amplitudes (torch.Tensor) – Structure factor amplitudes (can be signed), shape (N,).

  • phases_rad (torch.Tensor) – Phases in radians, shape (N,).

  • hkl_p1 (torch.Tensor) – P1-expanded Miller indices, shape (N, 3).

  • gridsize (tuple) – Grid dimensions (nx, ny, nz).

Returns:

Real-space 3D map.

Return type:

torch.Tensor

torchref.cli.validate_ded.generate_plots(results, map_dfo, map_dfc, mask_dict, outdir, verbose)[source]

Generate a 2-panel validation figure.

Parameters:

  • results (dict) – Correlation results dictionary.

  • map_dfo (torch.Tensor) – Real-space DFo and DFc maps.

  • map_dfc (torch.Tensor) – Real-space DFo and DFc maps.

  • mask_dict (dict) – Mapping of region name to boolean mask tensor.

  • outdir (Path) – Output directory for plots.

  • verbose (int) – Verbosity level.

torchref.cli.validate_ded.setup_ded_context(dark_sf, light_sf, dmin=None, device=None, col_dark=None, col_light=None, n_bins=20, verbose=0)[source]

Load reflection data and prepare shared state for DED validation.

This sets up the observation side (weighted DFo, P1 expansion, resolution bins, free/work masks) that is independent of any particular model.

Parameters:

  • dark_sf (str or Path) – Paths to dark and light structure factor files.

  • light_sf (str or Path) – Paths to dark and light structure factor files.

  • dmin (float, optional) – High-resolution cutoff in Angstroms.

  • device (torch.device, optional) – Compute device. Defaults to CPU.

  • col_dark (dict, optional) – Column name overrides for data loading.

  • col_light (dict, optional) – Column name overrides for data loading.

  • n_bins (int) – Number of resolution bins for reciprocal-space CC (default 20).

  • verbose (int) – Verbosity level.

Returns:

Context dictionary with keys: device, collection, data_dark, data_light, hkl_all, hkl, refl_mask, w_dfo, weights, d_spacing, cell_t, cell_np, sg_name, d_min, gridsize, hkl_p1, orig_idx, phase_shifts, w_dfo_p1, weights_p1, work_mask, free_mask.

Return type:

dict

torchref.cli.validate_ded.compute_ded_maps(ctx, model_dark, model_light, fraction, selection=None, mask_source='both', mask_radius=2.5, n_bins=None, verbose=0)[source]

Compute DED maps and correlations for one (dark, light) model pair.

Parameters:

  • ctx (dict) – Context from setup_ded_context().

  • model_dark (ModelFT) – Dark and light atomic models.

  • model_light (ModelFT) – Dark and light atomic models.

  • fraction (float) – Activated fraction for the light state.

  • selection (str, optional) – Phenix-style atom selection for masked correlation.

  • mask_source (str) – Which model(s) build the selection mask: “dark”, “light”, or “both”.

  • mask_radius (float) – Mask sphere radius in Angstroms.

  • n_bins (int, optional) – Number of resolution bins. Falls back to ctx["n_bins"].

  • verbose (int) – Verbosity level.

Returns:

Keys: map_dfo, map_dfc, mask_dict, realspace_correlation, resolution_bins, reciprocal_cc_overall, reciprocal_cc_work, reciprocal_cc_free, w_delta_fcalc_asu.

Return type:

dict

torchref.cli.validate_ded.run_validation(args)[source]

Run the DED validation pipeline.

torchref.cli.validate_ded.main()[source]