Collisions

molfp.collisions

Hash collision detection for folded/hashed molecular fingerprints.

Detects when multiple distinct substructures hash to the same bit position, which degrades ML model performance and corrupts SHAP attributions (see: Collision-Free Morgan Fingerprints, J Cheminform 2026).

detect_collisions(smiles_or_mol, fp_type='ecfp4', n_bits=1024)

Detect bit collisions in a hashed fingerprint for a single molecule.

Returns dict mapping bit_idx → list of distinct hash values that folded to that bit. Bits with len > 1 have collisions.

Only works for hashed FPs: ecfp4, atompairs2d, rdk, rdk_ext, rdk_graphonly.

collision_rate(smiles_list, fp_type='ecfp4', n_bits=1024)

Compute collision statistics across a dataset.

Returns dict with

molecules: number of molecules analyzed total_unique_hashes: total distinct hashes across all molecules total_bits_set: total bits set (after folding) collided_bits: bits with >1 hash mapped to them collision_rate: fraction of set bits that have collisions avg_collisions_per_mol: mean collisions per molecule

collision_pairs(smiles_list, fp_type='ecfp4', n_bits=1024)

Find pairs of distinct molecules with identical fingerprints.

Returns list of (smiles_a, smiles_b, idx_a, idx_b) tuples.

remove_collisions(X, smiles_list, fp_type='ecfp4', n_bits=1024)

Remove columns (bits) that have hash collisions in the dataset.

Scans all molecules for colliding bits, builds a collision-free mask, and returns the filtered feature matrix.

Parameters:

Name	Type	Description	Default
X		numpy array (n_samples, n_bits) — fingerprint matrix.	required
smiles_list		list of SMILES (same order as X rows).	required
fp_type		hashed fingerprint type ("ecfp4", "atompairs2d", "rdk", etc.).	'ecfp4'
n_bits		bit size used to compute X.	1024

Returns:

Type	Description
	dict with: X: filtered array (n_samples, n_clean_bits) mask: boolean mask of collision-free bits n_removed: number of colliding bits removed n_remaining: number of clean bits kept colliding_bits: set of bit indices that had collisions