Skip to main content

MOLRAPTOR — Molecular Fingerprint Rapid Generator

Version PyPI Python License: LGPL v3+ CI Docs

MOLRAPTOR is an open-source Python package and command-line tool for generating molecular fingerprints from ordered SMILES. It preserves the relationship between the supplied molecular input, the effective encoding profile, and the resulting numerical representation.

MOLRAPTOR provides a common workflow for binary, count, and MinHash fingerprints while keeping input correspondence and encoding metadata available for inspection.

Why MOLRAPTOR?

A fingerprint matrix alone does not identify all the information required to interpret how it was generated. The selected algorithm, representation semantics, effective parameters, source-input correspondence, and software versions are also part of the encoding context.

MOLRAPTOR keeps this information associated with the fingerprint result. Its purpose is not to select a preferred molecular representation, but to make fingerprint encoding explicit and traceable.

Installation

Install MOLRAPTOR from PyPI:

python -m pip install molraptor

MOLRAPTOR requires Python 3.11 or later.

Quick Start

Python

from molraptor import encode_fingerprints

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

print(result.fingerprints.shape)
# (2, 1024)

print(result.profile["algorithm"])
# map4

print(result.profile["representation"])
# minhash

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

Invalid inputs remain traceable and do not produce artificial zero-vector rows.

Command line

For a CSV file containing a SMILES column:

molraptor run \
  --input molecules.csv \
  --fingerprint map4 \
  --output-dir artifacts

For a UTF-8 TXT file containing one SMILES per line:

molraptor run \
  --input molecules.txt \
  --fingerprint klekotaroth \
  --output-dir artifacts

Morgan is the default fingerprint algorithm.

Current Capabilities

MOLRAPTOR supports 10 fingerprint algorithms and three representation classes.

Identifier Fingerprint Representation Width Dtype
morgan Morgan binary configurable; default 2048 uint8
featmorgan Feature Morgan binary 2048 uint8
atompair Atom Pair count 2048 uint32
rdk RDKit topological binary 2048 uint8
torsion Topological Torsion count 2048 uint32
layered Layered binary 2048 uint8
maccs MACCS keys binary 167 uint8
klekotaroth Klekota–Roth binary 4860 uint8
mhfp6 MHFP6 MinHash 2048 uint32
map4 MAP4 MinHash 1024 uint32

Morgan supports configurable radius, fingerprint width, and chirality through the public interface. The other nine algorithms use fixed effective profiles.

Each execution uses one fingerprint algorithm. The representation is determined by that algorithm.

The API name fingerprint_type is retained for compatibility; conceptually, it selects a fingerprint algorithm.

Inputs and Outputs

MOLRAPTOR accepts user-provided SMILES through:

  • the in-memory Python API;
  • CSV files;
  • UTF-8 TXT files.

Input order and duplicates are preserved. Invalid individual SMILES are recorded separately from valid fingerprint rows.

A successful file workflow writes four artifacts:

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

The numerical matrix contains valid inputs only. Its dtype depends on the selected representation:

binary  → uint8
count   → uint32
minhash → uint32

input_statuses.csv preserves the correspondence between the original input sequence and matrix rows, while encoding_metadata.json records the effective encoding profile, matrix properties, software versions, and deterministic input and profile hashes.

See the Usage guide for the complete input and output contracts.

Scientific Scope

MOLRAPTOR does MOLRAPTOR does not
Accept user-provided SMILES through Python, CSV, or TXT. Retrieve molecular records from external databases.
Parse supplied SMILES for fingerprint calculation. Curate, harmonize, canonicalize, or replace supplied SMILES as an input-preprocessing step.
Generate binary, count, and MinHash fingerprint representations. Select or recommend a scientifically preferred fingerprint.
Preserve input order, duplicates, and row-level correspondence. Generate labels or activity classes.
Record effective encoding profiles and execution metadata. Train or evaluate machine-learning models.
Isolate invalid individual inputs. Calculate molecular descriptors or 3D conformations.

MOLRAPTOR does not modify the user-supplied SMILES as a preprocessing step. The supplied strings are parsed to construct the molecular graph required by the selected fingerprint algorithm. This source-input boundary does not constrain algorithm-internal transformations used to construct a fingerprint representation.

Encoding Traceability

MOLRAPTOR preserves four related elements of an encoding:

ordered molecular input
          ↓
fingerprint algorithm
          ↓
effective encoding profile
          ↓
numerical representation

Each result also records input validity and matrix-row correspondence, MOLRAPTOR and RDKit versions, matrix shape and dtype, and deterministic input and profile hashes.

This allows the numerical representation to be interpreted together with the conditions under which it was generated.

Documentation

Full documentation is available at:

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

  • Usage — installation, CLI, Python workflows, inputs, outputs, and failure handling.
  • API Reference — public Python contracts, fingerprint profiles, representations, metadata, and hashes.
  • Changelog — release history.

Help and Contributing

Questions and bug reports can be submitted through the GitHub issue tracker.

Contributions are welcome. See CONTRIBUTING.md for development setup, testing, documentation, and contribution guidelines.

MOLRAPTOR is maintained by the Nano and Biostructures Research Group.

Citation

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

Contreras-Torres, F. F. (2026). MOLRAPTOR: Molecular Fingerprint Rapid Generator. Zenodo. https://doi.org/10.5281/zenodo.20434420

License

MOLRAPTOR is licensed under the GNU Lesser General Public License version 3 or later.

SPDX identifier: LGPL-3.0-or-later

Metadata

Release files for molraptor 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for molraptor 0.5.0
File Size Uploaded Provenance Actions
molraptor-0.5.0.tar.gz 73.0 kB With provenance Details for molraptor-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for molraptor 0.5.0
File Interpreter ABI Platform Actions
molraptor-0.5.0-py3-none-any.whl Python 3 none any Details for molraptor-0.5.0-py3-none-any.whl

Total release size: 130.5 kB

Release files / molraptor-0.5.0.tar.gz

Download URL molraptor-0.5.0.tar.gz
Size 73.0 kB
Tags Source
SHA-256 checksum
How to use checksums
cab4b0d2db2a71bb7c439a7fa4d6e8f1ebf460a87ca01ee5934b196673268b08
BLAKE2b-256 checksum
How to use checksums
2e595a2ba5a4a119fc381b15c2103fbf8d6bb1ce21d838d8d999701d7c7a315a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Release files / molraptor-0.5.0-py3-none-any.whl

Download URL molraptor-0.5.0-py3-none-any.whl
Size 57.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
567c5d8d27167144559f488d533e1173ee5b212bf70f84857b0826a1d5410ad6
BLAKE2b-256 checksum
How to use checksums
06bbf7ca5e6055a8d96899acac913c2fc6580cf4ffa839aa766c0202dc589419
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Security for molraptor 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for molraptor-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page