Interpret

molfp.interpret

SHAP-based feature interpretation with chemical meaning.

Connects SHAP feature importance to fingerprint bit annotations and atom-level explanations. Answers: "Which molecular substructures drive active vs inactive predictions, and what do they chemically mean?"

interpret(smiles_list, activities, fp_type='maccs', metric='pchembl', thresholds=None, model=None, top_n=20, n_background=50, collision_aware=False)

Full interpretation pipeline: FP → model → SHAP → chemical meaning.

Parameters:

Name	Type	Description	Default
smiles_list	list[str]	list of SMILES	required
activities	list[float] | ndarray	list of activity values	required
fp_type	str	fingerprint type	'maccs'
metric	str	activity metric for classification ("pchembl", "pic50", etc.)	'pchembl'
thresholds	dict[str, float] | None	custom activity thresholds	None
model	Any	sklearn classifier (default: RandomForestClassifier)	None
top_n	int	number of top features to return	20
n_background	int	SHAP background samples	50
collision_aware	bool	if True, detect collisions and flag ambiguous SHAP bits	False

Returns:

Type	Description
dict[str, Any]	dict with: shap_values: raw SHAP array (n_samples, n_bits) or per-class feature_importance: sorted list of (bit, mean_abs_shap, annotation) class_drivers: {class: [(bit, shap, annotation, direction), ...]} model: the trained model labels: activity class labels

interpret_molecule(smiles, interpretation_result)

Explain a single molecule's prediction using a previous interpret() result.

Maps SHAP values to specific atoms in the molecule.

Returns:

Type	Description
dict[str, Any]	dict with: prediction: predicted class prediction_proba: class probabilities top_bits: [(bit, shap, annotation, matching_atoms), ...]

compare_molecules(smiles_a, smiles_b, interpretation_result)

Compare two molecules: which bits differ and how important are they?

Returns:

Type	Description
dict[str, Any]	dict with shared_important_bits, unique_to_a, unique_to_b,
dict[str, Any]	each annotated with chemical meaning and SHAP importance.