haddock.libs.libscan module

Shared helpers for the mutagenesis scan modules.

The alascan (alanine), rnascan (RNA base) and dnascan (DNA base pair) analysis modules share the same scoring, z-score, cluster-output, b-factor and TSV-writing machinery. The common, module-agnostic pieces live here; each module keeps only its own mutation logic (which residues/atoms are mutated, how the interface is scanned, and how mutation jobs are executed).

class haddock.libs.libscan.AddDeltaBFactor(model: PDBFile, path: Path, model_results: List[MutationResult])

Bases: object

Add the (normalised) delta score into the b-factor column of a PDB.

Subclasses set module_name (used for the output filename suffix, <model>_<module_name>.pdb) and may override _residue_keys() to control which residues each mutation result is attributed to (e.g. both nucleotides of a base pair for dnascan).

module_name: str = 'scan'

filename suffix / module identifier; overridden by subclasses

normalize_score(score: float) → float

Normalise the input score based on observed scores for this model

In case normalisation cannot be performed, returns 50.0

Parameters:

score (float) – Input score to be normalized

Returns:

norm100 (float) – Normalized score between 0 and 100

reorder_results() → None

Aggregate mutation results into a per-residue delta score map.

Organise mutation results into a dictionary with chain-resid keys and, as values, the mean delta score over all mutations attributed to that residue (e.g. {"A-115": 5.2}), and determine the min and max score within the model to normalise the data.

run() → PDBFile

Perform the addition of delta scores as bfactor in pdb file.

write_delta_score_to_pdb(output_path: Path) → Path

Add delta scores as b-factors in PDB file.

Parameters:

output_path (Path) – Path to the pdb file.

Returns:

output_path (Path) – Path to the pdb file with the b-factors added.

haddock.libs.libscan.CLUSTER_STAT_COLUMNS = ['delta_score', 'delta_score_std', 'delta_vdw', 'delta_vdw_std', 'delta_elec', 'delta_elec_std', 'delta_desolv', 'delta_desolv_std', 'delta_bsa', 'delta_bsa_std', 'frac_pres']

statistics columns appended after the per-module identity columns in the cluster TSV output (mean/std of each energy term plus the population fraction)

class haddock.libs.libscan.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: object

Base class writing the per-cluster scan TSV (and optional plot).

Subclasses provide the module-specific identity columns/rows (which depend on whether a mutation is a single residue or a base pair) via _identity_columns() and _identity_row(), and set the class attributes module_name, sort_columns, zscore_reference and default_scan_residue. The averaging, z-scoring, sorting, file writing and (harmonised) plot handling are shared.

default_scan_residue: str = 'residue'

gen_plot(df_scan_clt: DataFrame) → None

Generate the scan plot based on provided data.

Parameters:

df_scan_clt (pd.DataFrame) – The data frame containing the data to be plotted.

module_name: str = 'scan'

run() → str

Write cluster scan output to a scan_clt_X.tsv file (and plot).

Returns:

scan_clt_filename (str) – Name of the tsv file written

sort_columns = ['chain', 'resid']

zscore_reference: str = 'residues'

class haddock.libs.libscan.MutationResult(model_id: str, chain: str, resid: int, ori_resname: str, target_resname: str, mutant_scores: Tuple[float, float, float, float, float], delta_scores: Tuple[float, float, float, float, float], success: bool, error_msg: str | None = None, partner_chain: str | None = None, partner_resid: int | None = None, partner_ori_resname: str | None = None, partner_target_resname: str | None = None)

Bases: object

Result from a single mutation.

The partner_* fields are only used by modules that perform paired (double) mutations, such as dnascan (base-pair mutations); they default to None for single-residue mutations (alascan, rnascan).

chain: str

delta_scores: Tuple[float, float, float, float, float]

error_msg: str | None = None

model_id: str

mutant_scores: Tuple[float, float, float, float, float]

ori_resname: str

partner_chain: str | None = None

partner_ori_resname: str | None = None

partner_resid: int | None = None

partner_target_resname: str | None = None

resid: int

success: bool

target_resname: str

haddock.libs.libscan.STANDARD_SCAN_COLUMNS = ['chain', 'res', 'ori_resname', 'end_resname', 'score', 'vdw', 'elec', 'desolv', 'bsa', 'delta_score', 'delta_vdw', 'delta_elec', 'delta_desolv', 'delta_bsa']

columns of the per-model scan TSV shared by single-residue scans

haddock.libs.libscan.add_zscores(df_scan_clt, column='delta_score')

Add z-scores to the dataframe.

Parameters:

• df_scan (pandas.DataFrame) – Dataframe with the scan results for the model.

• colunm (str) – Column to calculate the z-score.

Returns:

df_scan (pandas.DataFrame) – Dataframe with the z-scores added.

haddock.libs.libscan.calc_score(pdb_f: str, run_dir: str, outputpdb: bool = False, ligand_param_fname: Path | str = '', ligand_top_fname: Path | str = '') → Tuple[float, float, float, float, float]

Calculate the score of a model.

Parameters:

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

• run_dir (str) – Path to the run directory.

• outputpdb (bool, optional) – If True, the output, energy-minimized pdb file will be written. Default is False.

• ligand_param_fname (Union[Path, str]) – Path to additional parameter file used by CNS

• ligand_top_fname (Union[Path, str]) – Path to additional topology file used by CNS

Returns:

• Tuple[float, float, float, float, float] – All the scores

• score (float) – Haddock score.

• vdw (float) – Van der Waals energy.

• elec (float) – Electrostatic energy.

• desolv (float) – Desolvation energy.

• bsa (float) – Buried surface area.

Raises:

FileNotFoundError – Error when the file could not be located.

haddock.libs.libscan.get_score_string(pdb_f: str, run_dir: str, outputpdb: bool = False, ligand_param_fname: Path | str = '', ligand_top_fname: Path | str = '') → List[str]

Get score output from cli_score.main.

Parameters:

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

• run_dir (str) – Path to the run directory.

• outputpdb (bool, optional) – If True, the output, energy-minimized pdb file will be written. Default is False.

• ligand_param_fname (Union[Path, str]) – Path to additional parameter file used by CNS.

• ligand_top_fname (Union[Path, str]) – Path to additional topology file used by CNS.

Returns:

out (list[str]) – List of strings with the score output.

haddock.libs.libscan.group_scan_by_cluster(models: List[PDBFile], results_by_model: Dict[str, List[MutationResult]], ident_builder, metadata_builder=None) → Tuple[Dict[str, Dict[str, Dict[str, float | int]]], Dict[str, int]]

Group per-model scan data per cluster.

Parameters:

• models (List[PDBFile]) – List of input models.

• results_by_model (dict) – Mutation results keyed by model id.

• ident_builder (callable) – Function mapping a MutationResult to its unique string identifier.

• metadata_builder (callable, optional) – Function mapping a MutationResult to a dict of static metadata stored alongside the accumulated delta lists (used by paired-mutation modules).

Returns:

• clt_scan (dict) – Scan data for each cluster, grouped by mutation identifier.

• clt_pops (dict) – Number of entries for each cluster.

haddock.libs.libscan.make_scan_plot(df: DataFrame, clt_id, scan_res: str = 'residue', offline: bool = False, splitplot: bool = False) → str

Generate a scan cluster plot (harmonised across scan modules).

Shared plotting entry point for the alascan, rnascan and dnascan modules. Depending on splitplot the energy components are either drawn as separate stacked panels (one panel per energy term) or overlaid in a single grouped-bar panel.

Parameters:

• df (pandas.DataFrame) – Cluster scan data to plot.

• clt_id (int or str) – Cluster identifier.

• scan_res (str, optional) – Label used for the scan (e.g. "ALA", "RNA base").

• offline (bool, optional) – Whether the plot must be functional offline, by default False.

• splitplot (bool, optional) – If True draw one panel per energy component; if False (default) overlay all components in a single panel.

Returns:

html_output_filename (str) – Name of the plot generated.

haddock.libs.libscan.standard_scan_row(result: MutationResult) → list

Build a per-model TSV row for a single-residue mutation result.

haddock.libs.libscan.write_scan_out(results: ~typing.List[~haddock.libs.libscan.MutationResult], model_id: str, module_name: str, sort_columns: ~typing.List[str], row_builder=<function standard_scan_row>, columns: ~typing.List[str] | None = None, zscore_reference: str = 'residues', extra_header_lines=()) → None

Save mutation results for one model to scan_{model_id}.tsv.

Parameters:

• results (List[MutationResult]) – List of mutation results from scanning.

• model_id (str) – Identifier for the model used in the filename.

• module_name (str) – Module label used in the file header (alascan/rnascan/…).

• sort_columns (List[str]) – Column names used to sort the rows.

• row_builder (callable) – Function mapping a successful MutationResult to a TSV row.

• columns (List[str], optional) – Column names of the rows; defaults to STANDARD_SCAN_COLUMNS.

• zscore_reference (str) – Wording used in the z-score header comment (residues/mutations).

• extra_header_lines (iterable of str) – Extra comment lines added to the header (without the leading #).

Notes

If results is empty, no file is created.