MOLRAPTOR — Molecular Fingerprint Rapid Generator
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.