Metadata-Version: 2.4
Name: rdfp
Version: 0.1.0
Summary: Parallel fingerprint computation using the RDKit fingerprint generator API
Project-URL: Homepage, https://github.com/mireklzicar/rdkit-fp
Project-URL: Repository, https://github.com/mireklzicar/rdkit-fp
Project-URL: Issues, https://github.com/mireklzicar/rdkit-fp/issues
License: BSD 3-Clause License
        
        Copyright (c) 2026, Miroslav Lzicar
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: joblib-progress>=1.0
Requires-Dist: joblib>=1.3
Requires-Dist: numpy>=1.24
Requires-Dist: rdkit>=2022.3
Provides-Extra: dev
Requires-Dist: bump2version>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

[![PyPI - Version](https://img.shields.io/pypi/v/rdfp)](https://pypi.org/project/rdfp/)
[![CI](https://github.com/mireklzicar/rdkit-fp/actions/workflows/ci.yml/badge.svg)](https://github.com/mireklzicar/rdkit-fp/actions/workflows/ci.yml)

# rdkit-fp

Parallel RDKit fingerprints with a beginner one-liner and an advanced staged pipeline.

## Install

```bash
pip install rdfp
```

## Quickstart (10 seconds)

```bash
rdfp examples/chembl_1k.smi outputs/fps/
```

With explicit preset:

```bash
rdfp examples/chembl_1k.smi outputs/fps/ --preset ecfp4
```

This default command is equivalent to `rdfp fps INPUT OUTPUT`.

## Common CLI usage

Simple run with explicit workers/chunk size:

```bash
rdfp examples/chembl_1k.smi outputs/fps/ --workers -1 --chunk 100000
```

Use IDs from a column and keep stable row mapping sidecars:

```bash
rdfp data/compounds.smi outputs/fps/ --smiles-col 0 --id-col 1
```

Resume a stopped large run:

```bash
rdfp data/compounds.smi outputs/fps/ --resume
```

Run built-in demo data:

```bash
rdfp demo
```

## Presets

| Preset | Meaning |
|--------|---------|
| `ecfp4` *(default)* | Morgan radius 2, 2048 bits |
| `ecfp6` | Morgan radius 3, 2048 bits |
| `rdkit` | RDKit topological, 2048 bits |
| `ap` | Atom-pair, 2048 bits |
| `tt` | Topological torsion, 2048 bits |
| `pattern` | Pattern fingerprint, 2048 bits |

You can override preset values with explicit flags (`--fp-type`, `--fp-size`, `--radius`, `--include-chirality`).

## Advanced lane

Stage 1 only (SMILES -> mols):

```bash
rdfp mols examples/chembl_1k.smi outputs/mols/
```

Stage 2 only (mols -> fingerprints):

```bash
rdfp fps-from-mols outputs/mols/ outputs/fps_from_mols/ --resume
```

Both stages with mol persistence:

```bash
rdfp fps examples/chembl_1k.smi outputs/fps/ --save-mols outputs/mols/
```

## Helpful flags

- `--workers` (alias of `--n-jobs`)
- `--chunk` (alias of `--chunk-size`)
- `--preset ecfp4|ecfp6|rdkit|ap|tt|pattern`
- `--input-smiles-col` (alias of `--smiles-col`)
- `--id-col N` include IDs in `.index.json` sidecars
- `--resume` skip existing chunk outputs
- `--no-include-row-mapping` disable row/ID mapping sidecars and mapping metadata
- `--format numpy|packed|pickle` (`pickle` default)

## Python API

```python
from pathlib import Path
import rdfp

smiles_path = Path("examples/chembl_1k.smi")
rdfp.smiles_to_fps_chunked(
    rdfp.iter_smiles_records(smiles_path),
    output_dir="outputs/fps_api/",
    fp_type="morgan",
    fp_size=2048,
    radius=2,
    fmt="pickle",
    n_jobs=-1,
    chunk_size=100_000,
    include_row_mapping=True,
    resume=True,
)
```

## Output layout

`pickle` output (default):

```
outputs/fps/
  fps_0000.pkl
  fps_0000.index.json   <- row_idx / id / valid per input row in chunk
  fps_0001.pkl
  fps_0001.index.json
  metadata.json
```

Each chunk stores only valid fingerprints in `fps`; mapping metadata + sidecars preserve provenance and failed rows.

## Compatibility and packaging

- Repo name stays `rdkit-fp`.
- Install/import/CLI are centered on `rdfp`.
- `rdkit_fp` remains as a compatibility alias for existing code.

## Release flow

- CI runs on pushes/PRs to `main`.
- PyPI publish runs from tags matching `v*` (for example `v0.1.1`).
