Metadata-Version: 2.4
Name: fragment-explorer
Version: 0.1.0
Summary: Extract, visualize, and inspect molecular fragments (fingerprint bits) shared by molecules within a class
Author-email: Hamid Irannejad <hirannejad@alumnus.tums.ac.ir>
License: MIT
Project-URL: Homepage, https://github.com/hamid-irannejad/fragment_explorer
Project-URL: Repository, https://github.com/hamid-irannejad/fragment_explorer
Project-URL: Issues, https://github.com/hamid-irannejad/fragment_explorer/issues
Keywords: cheminformatics,rdkit,fingerprint,fragment,molecule,drug-discovery
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rdkit>=2023.3.1
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.23
Provides-Extra: png
Requires-Dist: Pillow>=9.0; extra == "png"
Dynamic: license-file

# fragment-explorer

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

## Install

```bash
pip install fragment-explorer
```

## Use as a library

```python
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

```bash
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
