Metadata-Version: 2.4
Name: molraptor
Version: 0.3.0
Summary: Encode ordered SMILES as traceable Morgan fingerprints using RDKit.
Project-URL: Homepage, https://github.com/NanoBiostructuresRG/molraptor
Project-URL: Repository, https://github.com/NanoBiostructuresRG/molraptor
Project-URL: Issues, https://github.com/NanoBiostructuresRG/molraptor/issues
Project-URL: Documentation, https://nanobiostructuresrg.github.io/molraptor/
Author-email: "Flavio F. Contreras-Torres" <contreras.flavio@tec.mx>
License-Expression: LGPL-3.0-or-later
License-File: COPYING
License-File: COPYING.LESSER
License-File: LICENSE
Keywords: Morgan fingerprints,RDKit,cheminformatics,computational chemistry,drug discovery,machine learning,molecular fingerprints
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.11
Requires-Dist: numpy>=2.4
Requires-Dist: pandas>=1.5
Requires-Dist: pydantic>=2.11
Requires-Dist: rdkit>=2024.9.6
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: hatchling>=1.18; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Description-Content-Type: text/markdown

# MOLRAPTOR: Molecular Learning via Rapid Processing of Topological Representations


[![Version](https://img.shields.io/badge/version-v0.3.0-blue.svg)](https://pypi.org/project/molraptor/)
[![PyPI](https://img.shields.io/pypi/v/molraptor.svg)](https://pypi.org/project/molraptor/)
[![Python](https://img.shields.io/pypi/pyversions/molraptor.svg)](https://pypi.org/project/molraptor/)
[![License: LGPL v3+](https://img.shields.io/badge/License-LGPL_v3%2B-blue.svg)](LICENSE)
[![CI](https://github.com/NanoBiostructuresRG/molraptor/actions/workflows/ci.yml/badge.svg)](https://github.com/NanoBiostructuresRG/molraptor/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-teal.svg)](https://nanobiostructuresrg.github.io/molraptor/)


**MOLRAPTOR** is a SMILES-first scientific library and command-line tool for generating reproducible Morgan fingerprints from user-provided molecular representations.

MOLRAPTOR provides:

- an in-memory Python API for direct SMILES encoding;
- a command-line workflow for CSV and TXT inputs;
- explicit and serializable Morgan fingerprint profiles;
- deterministic input and profile hashes;
- traceable handling of valid and invalid inputs;
- NumPy and CSV fingerprint outputs.

MOLRAPTOR does not retrieve, curate, harmonize, canonicalize, or replace supplied SMILES. Each input string is parsed by RDKit only to construct the molecular graph required for Morgan fingerprint calculation.

## Project Identity

```text
Project: MOLRAPTOR
PyPI distribution: molraptor
Python package: molraptor
Command-line interface: molraptor
License: LGPL-3.0-or-later
Development status: alpha / pre-stable
```

From Molraptor v0.3.0, it is introduced a SMILES-only workflow and replaces the legacy PubChem-oriented pipeline.

## Documentation

The documentation is published at:

https://nanobiostructuresrg.github.io/molraptor/

Main pages:

- [Usage](https://nanobiostructuresrg.github.io/molraptor/usage/)
- [API Reference](https://nanobiostructuresrg.github.io/molraptor/api/)
- [Changelog](https://nanobiostructuresrg.github.io/molraptor/changelog/)

## Installation

Install the latest published version from PyPI:

```bash
python -m pip install molraptor
```

Install the current repository for local development:

```bash
git clone https://github.com/NanoBiostructuresRG/molraptor.git
cd molraptor
python -m pip install -e .
```

Install development or documentation dependencies:

```bash
python -m pip install -e ".[dev]"
python -m pip install -e ".[docs]"
```

## Command-Line Quick Start

### CSV input

For a CSV containing a `SMILES` column:

```bash
molraptor run \
  --input molecules.csv \
  --output-dir artifacts
```

Use `--smiles-column` when the source column has another name:

```bash
molraptor run \
  --input molecules.csv \
  --smiles-column SMILES_Harmonized \
  --output-dir artifacts
```

### TXT input

A TXT input must contain one SMILES per line:

```bash
molraptor run \
  --input molecules.txt \
  --output-dir artifacts
```

### Morgan settings

The default profile uses radius 2, 2048 bits, and chirality disabled.

```bash
molraptor run \
  --input molecules.csv \
  --smiles-column SMILES \
  --output-dir artifacts \
  --radius 3 \
  --fp-size 1024 \
  --include-chirality
```

View the complete CLI help:

```bash
molraptor --help
molraptor run --help
molraptor --version
```

## Python Quick Start

### In-memory encoding

```python
from molraptor import MorganFingerprintProfile, encode_fingerprints

profile = MorganFingerprintProfile(
    radius=2,
    fp_size=2048,
    include_chirality=False,
)

result = encode_fingerprints(
    ["CCO", "not-a-smiles", "c1ccccc1", "CCO"],
    profile,
)

print(result.fingerprints.shape)
# (3, 2048)

print(result.valid_indices)
# (0, 2, 3)

for status in result.input_statuses:
    print(status)
```

The returned fingerprint matrix:

- contains one row per valid input;
- has shape `(N_valid, fp_size)`;
- uses the `numpy.uint8` dtype;
- preserves the order and duplicates of valid inputs.

Invalid inputs remain traceable through `result.input_statuses` and are never represented by artificial zero vectors.

### File workflow

```python
from molraptor import (
    MolraptorConfig,
    MorganFingerprintProfile,
    run,
)

config = MolraptorConfig(
    input_path="molecules.csv",
    smiles_column="SMILES_Harmonized",
    output_dir="artifacts",
    profile=MorganFingerprintProfile(
        radius=2,
        fp_size=2048,
        include_chirality=False,
    ),
)

result = run(config)
```

The file workflow and command-line interface use the same in-memory scientific encoder.

## Inputs

MOLRAPTOR accepts:

### CSV

A CSV file with an explicitly selected SMILES column.

```csv
SMILES_Harmonized
CCO
c1ccccc1
not-a-smiles
```

The default column name is `SMILES`. MOLRAPTOR does not guess aliases or choose a column implicitly.

### TXT

A UTF-8 text file containing one SMILES per line.

```text
CCO
c1ccccc1
not-a-smiles
```

Input order, duplicates, and empty input records are preserved for validation and traceability.

## Outputs

A successful file workflow writes exactly four artifacts:

```text
artifacts/
├── fingerprints.npy
├── fingerprints.csv
├── input_statuses.csv
└── encoding_metadata.json
```

### `fingerprints.npy`

Binary Morgan fingerprint matrix stored as a NumPy array.

- shape: `(N_valid, fp_size)`
- dtype: `numpy.uint8`
- rows: valid inputs only

### `fingerprints.csv`

The same binary fingerprint matrix in tabular CSV form.

### `input_statuses.csv`

One record for every original input:

```text
input_index
input_smiles
status
fingerprint_index
invalid_reason
```

- `input_index` is the zero-based position in the original input sequence.
- `input_smiles` is the exact string supplied to MOLRAPTOR.
- `status` is `valid` or `invalid`.
- `fingerprint_index` identifies the corresponding matrix row for a valid input.
- `invalid_reason` records `parse_failure` or `empty_molecule` for invalid inputs.

MOLRAPTOR does not add a canonicalized or alternative SMILES representation.

### `encoding_metadata.json`

Encoding-level metadata containing:

- source filename and input format;
- configured CSV SMILES column, when applicable;
- total, valid, and invalid input counts;
- complete effective Morgan profile;
- matrix shape and dtype;
- valid-input alignment;
- MOLRAPTOR and RDKit versions;
- deterministic ordered-input and profile hashes.

The metadata stores the source filename but not its local filesystem path.

## Failure Isolation

MOLRAPTOR separates row-level failures from global workflow failures.

An invalid individual SMILES:

- receives an entry in `input_statuses.csv`;
- does not produce a fingerprint matrix row;
- does not prevent valid inputs from being processed.

The file workflow stops without producing final artifacts when:

- the input configuration is invalid;
- the CSV SMILES column is missing;
- the input file cannot be accessed;
- no valid SMILES remain.

## Public API

The public package exports are:

```python
from molraptor import (
    DataValidator,
    FingerprintEncodingResult,
    FingerprintInputStatus,
    MolraptorConfig,
    MorganFingerprintProfile,
    encode_fingerprints,
    run,
    validate_config,
    __version__,
)
```

The main scientific contracts are:

- `MorganFingerprintProfile`: complete effective Morgan settings;
- `encode_fingerprints`: deterministic in-memory SMILES encoding;
- `FingerprintEncodingResult`: fingerprint matrix and reproducibility metadata;
- `FingerprintInputStatus`: per-input validity and matrix-row alignment;
- `MolraptorConfig`: validated CSV/TXT workflow configuration;
- `run`: file workflow execution.

Modules and objects not exported from `molraptor.__all__` are internal implementation details and may change before version 1.0.

## Scientific and Architectural Scope

| MOLRAPTOR does | MOLRAPTOR does not |
|---|---|
| Accept user-provided SMILES from Python, CSV, or TXT. | Retrieve molecular records from PubChem or other databases. |
| Parse SMILES with RDKit for fingerprint calculation. | Curate, harmonize, canonicalize, or replace SMILES. |
| Generate binary Morgan fingerprints. | Generate labels or activity classes. |
| Preserve order and duplicates. | Train or evaluate machine-learning models. |
| Isolate invalid individual inputs. | Calculate molecular descriptors or 3D conformations. |
| Record profiles, hashes, versions, and row alignment. | Provide alternative fingerprint algorithms in v0.3.0. |

MOLRAPTOR uses a lightweight modular boundary:

```text
Python API / CSV / TXT / CLI
              ↓
     in-memory Morgan core
              ↓
      NumPy / CSV / JSON
```

Input readers, workflow orchestration, and output writers depend on the scientific core. The core performs no file I/O and has no dependency on the command-line interface or external applications.

## Reproducibility

Each encoding result records:

- `ordered_input_hash`: SHA-256 digest of the exact ordered input strings, including duplicates and empty strings;
- `profile_hash`: SHA-256 digest of the complete effective Morgan profile;
- MOLRAPTOR version;
- RDKit version;
- fingerprint matrix shape and dtype.

These values allow consumers to identify the input sequence, scientific configuration, and runtime used for an encoding result.

## Development Validation

Run the test suite:

```bash
python -m pytest tests -q
```

Validate documentation and package artifacts:

```bash
mkdocs build --strict
python -m build --no-isolation
python -m twine check dist/*
```

Check the command-line entry points:

```bash
molraptor --help
molraptor run --help
molraptor --version
```

## Citation

If you use MOLRAPTOR in your research, please cite it using the metadata in
[CITATION.cff](CITATION.cff).

```text
Contreras-Torres, F. F. (2026). MOLRAPTOR: Molecular Learning via Rapid Processing of Topological Representations. Zenodo. https://doi.org/10.5281/zenodo.20434420
```


## Author

Developed by **Flavio F. Contreras-Torres**
Tecnológico de Monterrey

## License

MOLRAPTOR is licensed under the [GNU Lesser General Public License version 3 or later](LICENSE).

SPDX identifier: `LGPL-3.0-or-later`
