fragment-explorer

Extract, visualize, and inspect molecular fragments (fingerprint bits) shared by molecules within a class — built on RDKit.

Install

pip install fragment-explorer

Use as a library

from fragment_explorer import load_molecules, load_features, load_labels
from fragment_explorer import get_best_bit, pick_diverse, compute_mcs
from fragment_explorer import draw_molecule_grid

mols = load_molecules("molecules.csv", smiles_col="SMILES")
mol_features = load_features("morgan_bits.csv")   # rows=molecules, cols=bit ids
y_labels = load_labels("labels.csv", label_col="labels")

actives = get_best_bit(mols, class_no=1, mol_features=mol_features,
                        y_labels=y_labels, bit_id=29)
draw_molecule_grid(actives, save_path="actives.svg")

Use from the command line

python -m fragment_explorer \
  --smiles-csv molecules.csv --smiles-col SMILES \
  --features-csv morgan_bits.csv \
  --labels-csv labels.csv --labels-col labels \
  --class-no 1 --bit-id 29 \
  --n-diverse 10 \
  --mol-index 0 --root-atom 0 --env-radius 6 \
  --output-dir results/class1_bit29

This runs the full pipeline:

1. loads molecules / fingerprint-bit matrix / class labels (all must be row-aligned — same molecule order in all three files)
2. pulls out the molecules of --class-no that have --bit-id set (as user defined)
3. label.csv contains encoded class labels of molecules as integer numbers
4. morgan_bits.csv contains molecular fingerprints. Each row is a molecule Bit-based vector and headers are Bit IDs
5. saves a grid image of all of them (*_all.svg)
6. MaxMin-picks --n-diverse diverse molecules and saves a grid of those (*_diverse.svg)
7. computes the Maximum Common Substructure and saves it (*_mcs.svg)
8. draws the Morgan-bit highlight for one chosen molecule (--mol-index) and the atom environment around --root-atom (--env-radius)

--mol-index and --root-atom are prompted for interactively (like the original notebook's input() calls) if you don't pass them as flags. Pass --skip-inspection to stop after step 5.

Run python -m fragment_explorer --help for the full flag list.

Notes

• --features-csv must have one row per molecule and one column per fingerprint bit id (column headers are coerced to int).
• --labels-csv can be .csv (pick a column with --labels-col) or .npy.
• Images are written as SVG by default. PNG output (use_svg=False) requires the optional Pillow dependency: pip install fragment-explorer[png].

License

MIT