API Reference¶

MOLRAPTOR exposes thirteen public symbols through molraptor.__all__. The project is pre-stable, so this API may change before 1.0. Objects not listed here are implementation details and are not part of the supported public contract.

from molraptor import MolraptorConfig
from molraptor import validate_config
from molraptor import run
from molraptor import DataValidator
from molraptor import FingerprintType
from molraptor import FINGERPRINT_TYPES
from molraptor import MorganFingerprintProfile
from molraptor import ResolvedFingerprintProfile
from molraptor import FingerprintEncodingResult
from molraptor import FingerprintInputStatus
from molraptor import resolve_fingerprint_profile
from molraptor import encode_fingerprints
from molraptor import __version__

Scientific in-memory API¶

The scientific API encodes an ordered sequence of user-provided SMILES without reading or writing files. Each call calculates one fingerprint type.

Morgan is the default fingerprint and accepts a configurable MorganFingerprintProfile:

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,
)

fingerprints = result.fingerprints

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

print(fingerprints.dtype)
# uint8

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

Select another fingerprint with the keyword-only fingerprint_type argument:

from molraptor import encode_fingerprints

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

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

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

Supported fingerprint identifiers are:

morgan
featmorgan
atompair
rdk
torsion
layered
maccs

Morgan uses a configurable effective profile. The other fingerprint types use fixed effective profiles.

Resolve a profile before encoding¶

Use resolve_fingerprint_profile to inspect the complete effective profile as a read-only mapping, fingerprint width, and canonical profile hash without parsing or encoding SMILES:

from molraptor import resolve_fingerprint_profile

resolved = resolve_fingerprint_profile("maccs")

print(resolved.fp_size)
# 167

print(resolved.profile["algorithm"])
# maccs

print(resolved.profile_hash)

Pass a MorganFingerprintProfile as the second argument only when resolving the "morgan" fingerprint type.

encode_fingerprints:

performs no file I/O;
preserves exact input strings, order, and duplicates;
parses each supplied SMILES with RDKit;
generates one binary fingerprint row per valid input;
omits invalid inputs from the matrix instead of inserting zero vectors;
records one FingerprintInputStatus for every original input;
returns deterministic ordered-input and profile hashes.

The matrix has shape (N_valid, fingerprint_width) and dtype numpy.uint8. Its values are binary 0 or 1.

MOLRAPTOR uses the supplied SMILES to construct the molecular graph required for fingerprint calculation. It does not return, canonicalize, harmonize, or replace the caller's molecular representation.

Function contract¶

encode_fingerprints(
    smiles,
    profile=None,
    *,
    fingerprint_type="morgan",
)

The profile argument accepts a MorganFingerprintProfile only. Passing a Morgan profile with another fingerprint type is rejected rather than silently ignored.

Existing calls that pass a MorganFingerprintProfile as the second positional argument remain compatible and calculate Morgan fingerprints.

Result alignment¶

valid_indices maps fingerprint rows back to the zero-based positions of valid records in the original input sequence.

Each FingerprintInputStatus records:

input_index;
input_smiles;
status;
fingerprint_index;
invalid_reason.

For valid inputs, fingerprint_index identifies the corresponding matrix row. For invalid inputs, fingerprint_index is absent and invalid_reason records the failure.

Current invalid reasons are:

parse_failure;
empty_molecule.

Metadata and hashes¶

FingerprintEncodingResult contains:

the fingerprint matrix;
the complete effective fingerprint profile;
per-input statuses;
valid indices and counts;
matrix shape and dtype;
MOLRAPTOR and RDKit versions;
ordered_input_hash;
profile_hash.

serialize_metadata() returns a JSON-compatible dictionary and deliberately excludes the NumPy fingerprint matrix.

The ordered-input hash covers the exact ordered sequence, including duplicates, whitespace, and empty strings.

The profile hash covers the selected fingerprint algorithm and its complete effective profile, including defaults.

Zero-valid behavior¶

The in-memory encoder can return an empty matrix with shape (0, fingerprint_width) when all supplied records are invalid.

The file workflow treats zero valid SMILES as a global failure and does not publish final artifacts. This policy belongs to run, not to encode_fingerprints.

MorganFingerprintProfile¶

Bases: BaseModel

Settings for a binary Morgan fingerprint calculation.

Attributes:

Name	Type	Description
`profile_schema_version`	`{'1.0'}`	Version of the serialized profile schema.
`algorithm`	`{'morgan'}`	Fingerprint algorithm identifier.
`output_type`	`{'binary-bit-vector'}`	Representation produced by the encoder.
`radius`	`int`	Morgan neighborhood radius. Must be non-negative.
`fp_size`	`int`	Number of bits in each fingerprint. Must be positive.
`include_chirality`	`bool`	Whether the Morgan generator includes chirality information.
`use_bond_types`	`bool`	Whether bond types contribute to the fingerprint.
`include_ring_membership`	`bool`	Whether ring membership contributes to atom invariants.
`include_redundant_environments`	`bool`	Whether redundant atom environments are included.
`invariant_policy`	`{'rdkit-default'}`	Atom and bond invariant policy used by the encoder.

Notes

The model is frozen and rejects unknown settings. All effective defaults are fields, so serialization records the complete calculation profile.

`serialize()` ¶

Serialize the complete effective profile.

ResolvedFingerprintProfile¶

Complete effective fingerprint profile and its derived metadata.

resolve_fingerprint_profile¶

Resolve a complete effective fingerprint profile without encoding.

encode_fingerprints¶

Encode ordered SMILES as one selected binary fingerprint type.

Existing calls that pass a :class:MorganFingerprintProfile as the second positional argument continue to calculate Morgan fingerprints. Other fingerprint types use their fixed effective profiles and reject a Morgan profile.

FingerprintEncodingResult¶

Fingerprints with alignment and reproducibility metadata.

`effective_profile` `property` ¶

Return the effective profile used for encoding.

`input_hash` `property` ¶

Return the ordered-input digest.

`serialize_metadata()` ¶

Serialize encoding metadata without row-level statuses or bits.

FingerprintInputStatus¶

Bases: BaseModel

Encoding status and alignment for one original SMILES input.

`original_index` `property` ¶

Return the original input position.

`validate_status_contract()` ¶

Keep status-specific metadata complete and mutually exclusive.

File workflow API¶

The file workflow reads SMILES from CSV or UTF-8 TXT, delegates fingerprint generation to the same in-memory scientific API, and publishes the approved artifact set.

Configure a Morgan workflow:

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)

Configure another fingerprint type without a Morgan profile:

from molraptor import MolraptorConfig, run

config = MolraptorConfig(
    input_path="molecules.csv",
    smiles_column="SMILES",
    output_dir="artifacts",
    fingerprint_type="maccs",
)

result = run(config)

print(result.fingerprints.shape)
# (N_valid, 167)

A successful run writes exactly:

fingerprints.npy
fingerprints.csv
input_statuses.csv
encoding_metadata.json

The file workflow stops without publishing final artifacts when:

configuration validation fails;
the fingerprint type is unsupported;
Morgan-only settings are supplied for another fingerprint type;
input access or input-format validation fails;
the configured CSV column is missing;
no valid SMILES remain;
artifact publication fails.

MolraptorConfig¶

Bases: BaseModel

Inputs and outputs for one file-based fingerprint execution.

validate_config¶

Validate the workflow configuration type.

Parameters:

Name	Type	Description	Default
`config`	`MolraptorConfig`	Configuration to validate.	required

Returns:

Type	Description
`MolraptorConfig`	The same validated configuration instance.

Raises:

Type	Description
`ValueError`	If `config` is not a :class:`MolraptorConfig` instance.

run¶

Encode a configured CSV or TXT file and persist its artifacts.

Parameters:

Name	Type	Description	Default
`config`	`MolraptorConfig`	Input file, output directory, CSV column, and fingerprint settings.	required

Returns:

Type	Description
`FingerprintEncodingResult`	The single in-memory result used to create all output artifacts.

Raises:

Type	Description
`ValueError`	If the configuration object has the wrong type, the configured CSV SMILES column is missing, or the input contains zero valid SMILES.
`OSError`	If the input or output cannot be accessed through the file system.

Notes

Individual invalid SMILES do not stop a batch when another input is valid. A batch with zero valid SMILES is a global file-workflow failure and writes no artifacts.

A successful execution writes fingerprints.npy, fingerprints.csv, input_statuses.csv, and encoding_metadata.json. Encoding data derive from one :class:FingerprintEncodingResult; source-identification metadata derive from the validated configuration.

Examples:

>>> config = MolraptorConfig(input_path="molecules.csv")
>>> result = run(config)

Validation utility¶

DataValidator remains part of the public API for explicit validation tasks. It does not retrieve PubChem data, infer activity labels, harmonize SMILES, or generate alternative molecular representations.

DataValidator¶

Stateless validation utilities.

`ensure_required_columns(df, required)` `staticmethod` ¶

Require named columns in a tabular input.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Table whose columns are inspected.	required
`required`	`iterable of str`	Column names that must be present.	required

Raises:

Type	Description
`ValueError`	If one or more required columns are absent.

`is_valid_smiles(smiles)` `staticmethod` ¶

Return whether one SMILES produces a non-empty RDKit molecule.

Parameters:

Name	Type	Description	Default
`smiles`	`str`	Exact user-provided SMILES string to validate.	required

Returns:

Type	Description
`bool`	`True` when the in-memory encoder classifies the input as valid; otherwise `False`.

Notes

Validation delegates to the shared RDKit parsing rule; the supplied string is not curated, harmonized, canonicalized, or replaced.

Version¶

__version__ exposes the installed MOLRAPTOR package version.

Package version metadata for MOLRAPTOR.

This module is the single source of truth for the project version. It is read by hatchling at build time via [tool.hatch.version] and exposed through the public package API as __version__.

API Reference¶

Scientific in-memory API¶

Resolve a profile before encoding¶

Function contract¶

Result alignment¶

Metadata and hashes¶

Zero-valid behavior¶

MorganFingerprintProfile¶

serialize() ¶

ResolvedFingerprintProfile¶

resolve_fingerprint_profile¶

encode_fingerprints¶

FingerprintEncodingResult¶

effective_profile property ¶

input_hash property ¶

serialize_metadata() ¶

FingerprintInputStatus¶

original_index property ¶

validate_status_contract() ¶

File workflow API¶

MolraptorConfig¶

validate_config¶

run¶

Validation utility¶

DataValidator¶

ensure_required_columns(df, required) staticmethod ¶

is_valid_smiles(smiles) staticmethod ¶

Version¶

`serialize()` ¶

`effective_profile` `property` ¶

`input_hash` `property` ¶

`serialize_metadata()` ¶

`original_index` `property` ¶

`validate_status_contract()` ¶

`ensure_required_columns(df, required)` `staticmethod` ¶

`is_valid_smiles(smiles)` `staticmethod` ¶