Usage¶
This guide covers installation, supported fingerprint algorithms, command-line use, Python workflows, input formats, output artifacts, and failure behavior.
For the public Python contracts and encoding metadata, see the API Reference.
Installation¶
MOLRAPTOR requires Python 3.11 or later.
Install the current published version from PyPI:
python -m pip install molraptor
Verify the installation:
molraptor --help
molraptor run --help
molraptor --version
For development and contribution instructions, see CONTRIBUTING.md.
Choose an Interface¶
MOLRAPTOR provides two user interfaces backed by the same in-memory fingerprint encoder.
Use the command-line interface or Python file workflow when SMILES are stored in CSV or UTF-8 TXT files and you want persisted output artifacts.
Use the in-memory Python API when SMILES are already available as an ordered Python sequence and file I/O is not required.
Both interfaces preserve input order and duplicates. Invalid individual SMILES remain traceable without preventing valid inputs from being encoded.
Each execution uses one fingerprint algorithm.
Supported Fingerprint Algorithms¶
MOLRAPTOR v0.5.0 supports 10 fingerprint algorithms:
| 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 |
The selected algorithm determines the representation class.
Morgan is the default algorithm and exposes configurable settings. The other nine algorithms use fixed effective profiles.
The representation classes have different numerical meanings:
- Binary coordinates encode presence or absence according to the selected algorithm. Hashed fingerprints may map more than one molecular feature to the same bit.
- Count coordinates store multiplicities in fixed-width hashed bins. Different molecular features may contribute to the same bin through collisions.
- MinHash coordinates are sketch values summarizing an encoded shingle set. They are not molecular feature-presence bits or feature counts.
Command-Line Interface¶
CSV input¶
For a CSV file containing a SMILES column:
molraptor run \
--input molecules.csv \
--output-dir artifacts
When the source column has another name, select it explicitly:
molraptor run \
--input molecules.csv \
--smiles-column SMILES_Harmonized \
--output-dir artifacts
MOLRAPTOR does not guess column aliases or select another SMILES column implicitly.
TXT input¶
For a UTF-8 TXT file containing one SMILES record per line:
molraptor run \
--input molecules.txt \
--output-dir artifacts
Select a fingerprint algorithm¶
Use --fingerprint to select another algorithm:
molraptor run \
--input molecules.csv \
--fingerprint map4 \
--output-dir artifacts
Supported identifiers are:
morgan
featmorgan
atompair
rdk
torsion
layered
maccs
klekotaroth
mhfp6
map4
Configure Morgan¶
The default Morgan profile uses:
radius = 2
width = 2048
chirality = disabled
Configure these settings through the command line:
molraptor run \
--input molecules.csv \
--fingerprint morgan \
--radius 3 \
--fp-size 1024 \
--include-chirality \
--output-dir artifacts
--radius, --fp-size, and --include-chirality are valid only for Morgan.
MOLRAPTOR rejects these options for the other fingerprint algorithms rather
than silently ignoring them.
Command reference¶
The molraptor run command accepts:
| Option | Purpose |
|---|---|
--input PATH |
Source CSV or UTF-8 TXT file |
--smiles-column NAME |
CSV column containing SMILES; default: SMILES |
--fingerprint TYPE |
Fingerprint algorithm identifier; default: morgan |
--output-dir PATH |
Destination directory for output artifacts |
--radius INTEGER |
Morgan neighborhood radius; default: 2 |
--fp-size INTEGER |
Morgan fingerprint width; default: 2048 |
--include-chirality |
Include chirality in Morgan fingerprint generation |
Display the complete command help with:
molraptor --help
molraptor run --help
Input Formats¶
CSV¶
A CSV input must contain the configured SMILES column.
SMILES
CCO
c1ccccc1
not-a-smiles
CCO
The default column name is SMILES.
Only the selected column is used for fingerprint encoding. Input order, duplicates, and empty cells are preserved for validation and correspondence.
MOLRAPTOR does not retrieve molecular records or infer labels from the input.
It also does not curate, harmonize, canonicalize, or replace user-supplied SMILES as an input-preprocessing step.
TXT¶
A TXT input must be UTF-8 encoded and contain one SMILES record per line.
CCO
c1ccccc1
not-a-smiles
CCO
MOLRAPTOR removes only the trailing CRLF, CR, or LF line ending from each
record.
All other content is preserved, including:
- order;
- duplicates;
- whitespace;
- empty lines.
The supplied strings are parsed with RDKit to construct the molecular graph required for fingerprint calculation.
The source-input boundary described here does not constrain algorithm-internal transformations used to construct a fingerprint representation.
Python File Workflow¶
The file workflow can also be executed directly from Python.
Morgan¶
from molraptor import (
MolraptorConfig,
MorganFingerprintProfile,
run,
)
config = MolraptorConfig(
input_path="molecules.csv",
smiles_column="SMILES",
output_dir="artifacts",
fingerprint_type="morgan",
profile=MorganFingerprintProfile(
radius=2,
fp_size=2048,
include_chirality=False,
),
)
result = run(config)
print(result.fingerprints.shape)
print(result.valid_indices)
Another fingerprint algorithm¶
For another algorithm, set fingerprint_type and omit the Morgan profile:
from molraptor import MolraptorConfig, run
config = MolraptorConfig(
input_path="molecules.csv",
smiles_column="SMILES",
output_dir="artifacts",
fingerprint_type="map4",
)
result = run(config)
print(result.fingerprints.shape)
# (N_valid, 1024)
The API name fingerprint_type is retained for compatibility. Conceptually,
it selects a fingerprint algorithm; the representation is determined by that
algorithm.
For TXT input, smiles_column is not used:
from molraptor import MolraptorConfig, run
config = MolraptorConfig(
input_path="molecules.txt",
output_dir="artifacts",
fingerprint_type="rdk",
)
result = run(config)
run() reads the ordered input records, delegates encoding to the in-memory
API, validates the workflow result, and publishes the output artifacts.
In-Memory Encoding¶
Use encode_fingerprints() when the SMILES are already available as an ordered
Python sequence.
Morgan¶
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)
The positional MorganFingerprintProfile form remains supported for
compatibility.
Another fingerprint algorithm¶
Use the keyword-only fingerprint_type argument:
from molraptor import encode_fingerprints
result = encode_fingerprints(
["CCO", "not-a-smiles", "c1ccccc1", "CCO"],
fingerprint_type="map4",
)
print(result.fingerprints.shape)
# (3, 1024)
print(result.profile["algorithm"])
# map4
print(result.profile["representation"])
# minhash
print(result.valid_indices)
# (0, 2, 3)
The returned matrix:
- contains one row per valid input;
- has shape
(N_valid, fingerprint_width); - uses a representation-dependent dtype;
- preserves the order and duplicates of valid inputs;
- does not contain artificial zero-vector rows for invalid inputs.
The dtype contract is:
binary → uint8
count → uint32
minhash → uint32
For detailed Python contracts, effective profiles, and metadata fields, see the API Reference.
Output Artifacts¶
A successful file workflow writes exactly four artifacts:
artifacts/
├── fingerprints.npy
├── fingerprints.csv
├── input_statuses.csv
└── encoding_metadata.json
fingerprints.npy¶
NumPy matrix containing one fingerprint representation per valid input.
| Property | Value |
|---|---|
| Shape | (N_valid, fingerprint_width) |
| Rows | Valid inputs only |
| Dtype | binary → uint8; count → uint32; MinHash → uint32 |
| Values | Representation-dependent numerical coordinates |
fingerprints.csv¶
Tabular serialization of the same matrix values.
Its row order matches fingerprints.npy and follows fingerprint_index.
input_statuses.csv¶
Contains one record for every original input:
input_index
input_smiles
status
fingerprint_index
invalid_reason
| Column | Meaning |
|---|---|
input_index |
Zero-based position in the original input sequence |
input_smiles |
Exact string supplied to MOLRAPTOR |
status |
valid or invalid |
fingerprint_index |
Corresponding matrix row for a valid input |
invalid_reason |
Reason recorded for an invalid input |
input_index and fingerprint_index represent different coordinate systems.
input_index refers to the complete original input sequence.
fingerprint_index refers only to rows in the valid fingerprint matrix.
For example, if input index 1 is invalid, input index 2 may correspond to
fingerprint index 1.
Current invalid reasons are:
parse_failure— RDKit could not parse the supplied string;empty_molecule— parsing produced a molecule with zero atoms.
encoding_metadata.json¶
Records execution-level encoding metadata, including:
- source filename and input format;
- configured CSV SMILES column, when applicable;
- input counts;
- complete effective fingerprint profile;
- valid-input alignment;
- matrix shape and dtype;
- MOLRAPTOR version;
- RDKit version;
- ordered-input hash;
- profile hash.
The source filename is recorded without its local filesystem path.
Row-level input information remains in input_statuses.csv rather than being
duplicated in the metadata file.
For the exact metadata and hash contracts, see the API Reference.
Failure Behavior¶
MOLRAPTOR distinguishes invalid individual inputs from failures of the complete file workflow.
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 encoded.
The file workflow stops without publishing final artifacts when:
- configuration validation fails;
- the fingerprint algorithm identifier is unsupported;
- Morgan-only settings are supplied for another algorithm;
- the input file is inaccessible;
- the input format is unsupported;
- the configured CSV SMILES column is missing;
- no valid SMILES remain;
- artifact publication fails.
The in-memory API behaves differently when every supplied input is invalid: it can return an empty matrix with shape:
(0, fingerprint_width)
The requirement for at least one valid input belongs to the file workflow, not
to encode_fingerprints().
Next Steps¶
For public Python objects, effective profiles, result alignment, metadata, and hash definitions, continue to the API Reference.
For release-specific changes, see the Changelog.