haddock.modules.analysis.dnascan.dnascan module

dnascan module.

Core logic for the DNA base-pair scan.

Unlike the RNA scan, where each interface nucleotide is mutated independently, DNA is double stranded and its bases are engaged in Watson-Crick base pairs (A:T and G:C). Mutating a single base in isolation would break the base pair and is not physically meaningful. Therefore every mutation performed by this module is a double mutation: the selected interface nucleotide is mutated to a target base and its base-pairing partner on the complementary strand is mutated to the complementary base so that a valid Watson-Crick pair is preserved (e.g. A:T -> G:C).

Same-ring-type base-pair mutations are applied simultaneously and scored in a single CNS call. Cross-ring-type base-pair mutations (where the two nucleotides swap ring type, one purine -> pyrimidine and its partner pyrimidine -> purine) are instead performed in two sequential, CNS-regularised steps: first the purine -> pyrimidine mutation is applied and energy-minimised by CNS, then the pyrimidine -> purine mutation is applied to that minimised intermediate and scored by CNS. The score and energies of the second (final) CNS call are the ones reported and plotted.

To keep the comparison consistent, each mutant is compared against a wild-type baseline that went through the same number of CNS minimisation passes: a one-pass baseline for same-ring-type mutants and a two-pass baseline (the wild type minimised and then re-scored) for cross-ring-type mutants.

class haddock.modules.analysis.dnascan.dnascan.AddDeltaBFactor(model: PDBFile, path: Path, model_results: List[MutationResult])

Bases: AddDeltaBFactor

Add dnascan delta score in the b-factor column of a PDB.

The delta score of a base-pair mutation is attributed to both nucleotides of the pair so that both light up when colouring by b-factor.

module_name: str = 'dnascan'

filename suffix / module identifier; overridden by subclasses

class haddock.modules.analysis.dnascan.dnascan.ClusterOutputer(cluster_scan_data: Dict[str, Dict[str, float | int]], clt_id: str, clt_population: int, scan_residue: str | None = None, generate_plot: bool = False, offline: bool = False, splitplot: bool = False)

Bases: ClusterOutputer

Manage the generation of dnascan outputs for cluster-based analysis.

default_scan_residue: str = 'DNA base pair'

module_name: str = 'dnascan'

plot_xaxis_title: str = 'Base-pair mutation'

x-axis label of the cluster plot; mutational scans override it

sort_columns = ['chain', 'resid', 'target_resname']

zscore_reference: str = 'mutations'

class haddock.modules.analysis.dnascan.dnascan.InterfaceScanner(model: str | Path | Any, scan_bases: List[str] | None = None, params: Dict[str, Any] | None = None)

Bases: BaseInterfaceScanner

Scan interface of a model to get target base pairs and create corresponding double-mutation jobs.

run()

Get interface base pairs and create the double-mutation jobs.

The jobs are returned (not executed): the caller hands them to a haddock Engine so that all mutations are scheduled together.

Returns:

List[ModelBasePairMutation] – The base-pair mutation jobs to perform for this model.

class haddock.modules.analysis.dnascan.dnascan.ModelBasePairMutation(model_path: Path, model_id: str, chain: str, resid: int, ori_resname: str, target_resname: str, partner_chain: str, partner_resid: int, partner_ori_resname: str, partner_target_resname: str, native_scores: Tuple[float, float, float, float, float], native_scores_2step: Tuple[float, float, float, float, float] | None = None, output_mutants: bool = False, ligand_param_fname: Path | str = '', ligand_top_fname: Path | str = '')

Bases: object

Executes a single Watson-Crick base-pair (double) mutation.

run()

Execute the base-pair (double) mutation.

haddock.modules.analysis.dnascan.dnascan.find_base_pairs(coords: Dict[Tuple[str, int, str, str], Any], cutoff: float = 3.5) → Dict[Tuple[str, int], Tuple[str, int, str]]

Detect Watson-Crick base pairs from atomic coordinates.

For every DNA nucleotide, the Watson-Crick hydrogen-bonding ring nitrogen (N1 for purines, N3 for pyrimidines) is located and the closest nucleotide of the complementary ring type (purine <-> pyrimidine) whose corresponding nitrogen lies within cutoff is taken as its base-pairing partner. Base pairing is not restricted to a single chain: partners on the same strand (e.g. hairpin duplexes) or on a different chain are both detected.

Parameters:

• coords (dict) – Coordinate dictionary as returned by haddock.libs.libalign.load_coords() with add_resname=True; keys are (chain, resid, atom_name, resname) tuples.

• cutoff (float, optional) – Maximum N1…N3 distance (Å) for two bases to be considered paired.

Returns:

dict – Mapping (chain, resid) -> (partner_chain, partner_resid, partner_resname) for every nucleotide for which a partner was found.

haddock.modules.analysis.dnascan.dnascan.get_atoms_to_keep(ori_resname: str, target_resname: str) → Dict[str, str]

Return the atoms to preserve when mutating one DNA base into another.

Thin wrapper around haddock.libs.libscan.get_atoms_to_keep() bound to this module’s deoxyribose-phosphate backbone and DNA ring-type classification.

haddock.modules.analysis.dnascan.dnascan.group_scan_by_cluster(models, results_by_model)

Group dnascan data per cluster, keyed by base-pair mutation.

haddock.modules.analysis.dnascan.dnascan.is_cross_type(ori_resname: str, target_resname: str) → bool

Return True if a mutation changes the base ring type.

A cross-type mutation converts a purine into a pyrimidine or vice versa.

Parameters:

• ori_resname (str) – Original (wild-type) residue name.

• target_resname (str) – Target base residue name.

haddock.modules.analysis.dnascan.dnascan.mutate(pdb_f, target_chain, target_resid, mut_resname, partner_chain, partner_resid, partner_mut_resname)

Perform a Watson-Crick double mutation of a base pair in a PDB file.

Both the selected nucleotide and its base-pairing partner are mutated at once so that a valid Watson-Crick pair is preserved. See _mutate_residues for the details of how atoms are kept and renamed.

Parameters:

• pdb_f (str) – Path to the pdb file.

• target_chain (str) – Chain of the primary nucleotide to be mutated.

• target_resid (int) – Residue number of the primary nucleotide to be mutated.

• mut_resname (str) – Residue name of the target base for the primary nucleotide (e.g. DA, DC, DG, DT).

• partner_chain (str) – Chain of the base-pairing partner nucleotide.

• partner_resid (int) – Residue number of the base-pairing partner nucleotide.

• partner_mut_resname (str) – Residue name of the target base for the partner nucleotide (the Watson-Crick complement of mut_resname).

Returns:

mut_pdb_fname (Path) – Path to the mutated pdb file.

haddock.modules.analysis.dnascan.dnascan.validate_scan_bases(scan_bases: List[str]) → List[str]

Validate and normalise the list of target DNA bases.

Only the canonical two-letter DNA residue names (DA, DC, DG, DT) are accepted, in a case-insensitive manner. The one-letter names (A, C, G, U) denote RNA bases in HADDOCK and are therefore rejected by this DNA-specific module.

Thin wrapper around haddock.libs.libscan.validate_scan_bases().

haddock.modules.analysis.dnascan.dnascan.wc_atom(resname: str) → str

Return the Watson-Crick hydrogen-bonding ring nitrogen for a base.

Purines (DA, DG) pair through their N1, pyrimidines (DC, DT) through their N3. The distance between these two atoms is used to identify base pairs.

Parameters:

resname (str) – DNA residue name.

Returns:

str – Atom name of the Watson-Crick ring nitrogen (N1 or N3).

haddock.modules.analysis.dnascan.dnascan.write_scan_out(results, model_id)

Save dnascan base-pair mutation results for one model to a tsv file.