Skip to content

API Reference

MOLRAPTOR exposes 18 public symbols through molraptor.__all__.

The public API separates four concepts that should not be treated as interchangeable:

molecular input
      ↓
fingerprint algorithm
      ↓
representation + effective profile
      ↓
numerical matrix

The project is currently pre-stable. Public interfaces may change before 1.0. Objects not exported through molraptor.__all__ are implementation details and are not part of the supported top-level API.

Public API

Symbol Purpose
__version__ Installed MOLRAPTOR version
MolraptorConfig Configuration for the CSV/TXT file workflow
run Execute the configured file workflow
validate_config Validate the workflow configuration object type
DataValidator Public tabular and SMILES validation utilities
FingerprintAlgorithm Type identifying supported fingerprint algorithms
FingerprintRepresentation Type identifying representation classes
FINGERPRINT_ALGORITHMS Ordered registry of supported algorithms
FINGERPRINT_REPRESENTATIONS Ordered registry of representation classes
ALGORITHM_REPRESENTATIONS Mapping from algorithm to representation
FingerprintType v0.4 compatibility alias for FingerprintAlgorithm
FINGERPRINT_TYPES v0.4 compatibility alias for FINGERPRINT_ALGORITHMS
MorganFingerprintProfile Configurable effective Morgan profile
ResolvedFingerprintProfile Resolved algorithm, representation, width, profile, and profile hash
FingerprintEncodingResult Numerical result with alignment and encoding metadata
FingerprintInputStatus Per-input validity and matrix-row correspondence
resolve_fingerprint_profile Resolve an effective profile without encoding SMILES
encode_fingerprints Encode an ordered sequence of SMILES in memory

The compatibility name fingerprint_type is retained in existing function and configuration signatures. Conceptually, it selects a fingerprint algorithm. The representation is derived from that algorithm and is not selected independently.

Algorithm and Representation Contract

MOLRAPTOR v0.5.0 supports 10 algorithms and three representation classes.

Algorithm identifier Representation Width Dtype
morgan binary configurable; default 2048 uint8
featmorgan binary 2048 uint8
atompair count 2048 uint32
rdk binary 2048 uint8
torsion count 2048 uint32
layered binary 2048 uint8
maccs binary 167 uint8
klekotaroth binary 4860 uint8
mhfp6 MinHash 2048 uint32
map4 MinHash 1024 uint32

The public registries expose this contract directly:

from molraptor import (
    ALGORITHM_REPRESENTATIONS,
    FINGERPRINT_ALGORITHMS,
    FINGERPRINT_REPRESENTATIONS,
)

print(FINGERPRINT_ALGORITHMS)
print(FINGERPRINT_REPRESENTATIONS)
print(ALGORITHM_REPRESENTATIONS["map4"])
# minhash

The representation classes have different numerical semantics:

Binary Coordinates encode presence or absence according to the selected algorithm. For hashed binary fingerprints, more than one molecular feature may map 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 MinHash sketch values summarizing the encoded shingle set. They are not molecular feature-presence bits or feature counts.

The same numerical dtype therefore does not imply the same representation semantics. In particular, count and MinHash matrices both use uint32, but their coordinates have different meanings.

Effective Fingerprint Profiles

An effective profile records the settings used to construct a fingerprint representation.

Morgan is the only configurable algorithm in v0.5.0. The other nine algorithms use fixed effective profiles.

All serialized profiles include:

profile_schema_version
algorithm
representation
output_type
dtype

and the algorithm-specific settings required by the encoder.

The representation output contract is:

binary  → binary-bit-vector → uint8
count   → count-vector      → uint32
minhash → minhash-sketch    → uint32

Resolve a profile without encoding

Use resolve_fingerprint_profile() when the effective encoding contract is needed before any SMILES are parsed:

from molraptor import resolve_fingerprint_profile

resolved = resolve_fingerprint_profile("maccs")

print(resolved.algorithm)
# maccs

print(resolved.representation)
# binary

print(resolved.width)
# 167

print(resolved.profile_hash)

width is the canonical v0.5 dimension property of ResolvedFingerprintProfile.

fp_size remains available on that object as a v0.4 compatibility alias for width. Serialized profiles continue to use their defined fp_size field.

For Morgan, pass a MorganFingerprintProfile when a non-default profile is required:

from molraptor import (
    MorganFingerprintProfile,
    resolve_fingerprint_profile,
)

profile = MorganFingerprintProfile(
    radius=3,
    fp_size=1024,
    include_chirality=True,
)

resolved = resolve_fingerprint_profile(
    "morgan",
    profile,
)

A MorganFingerprintProfile supplied for another algorithm is rejected rather than silently ignored.

MorganFingerprintProfile

Bases: BaseModel

Settings for a binary Morgan fingerprint calculation.

Attributes:

Name Type Description
profile_schema_version {'2.0'}

Version of the serialized profile schema.

algorithm {'morgan'}

Fingerprint algorithm identifier.

output_type {'binary-bit-vector'}

Representation produced by the encoder.

representation {'binary'}

Representation semantics selected for the algorithm.

dtype {'uint8'}

Numerical storage type 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.

fingerprint_type property

Return the algorithm through the v0.4 compatibility name.

fp_size property

Return the width through the v0.4 compatibility name.

resolve_fingerprint_profile

Resolve a complete effective fingerprint profile without encoding.

In-Memory Encoding

encode_fingerprints() is the scientific in-memory encoding interface.

Its public signature is:

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

smiles must be an ordered sequence of strings. Passing a single string or a sequence containing non-string elements raises TypeError.

Each call uses one fingerprint algorithm.

The encoder:

  • preserves the supplied strings, their order, and duplicates;
  • parses each string with RDKit;
  • records one status for every original input;
  • produces one matrix row for every valid input;
  • excludes invalid inputs from the matrix rather than inserting artificial zero vectors;
  • records the complete effective profile and encoding metadata;
  • returns deterministic ordered-input and profile hashes.

The matrix shape is:

(N_valid, fingerprint_width)

Its dtype is determined by the representation:

binary  → uint8
count   → uint32
minhash → uint32

The in-memory API performs no file I/O.

MOLRAPTOR does not retrieve, curate, harmonize, canonicalize, or replace the user-supplied SMILES as an input-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.

Compatibility behavior

Existing calls that provide a MorganFingerprintProfile as the second positional argument remain valid:

from molraptor import MorganFingerprintProfile, encode_fingerprints

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

result = encode_fingerprints(
    ["CCO", "c1ccccc1"],
    profile,
)

For another algorithm, use the keyword-only compatibility parameter fingerprint_type and do not provide a Morgan profile:

from molraptor import encode_fingerprints

result = encode_fingerprints(
    ["CCO", "c1ccccc1"],
    fingerprint_type="map4",
)

encode_fingerprints

Encode ordered SMILES with a selected fingerprint algorithm.

Existing calls that pass a :class:MorganFingerprintProfile as the second positional argument continue to calculate Morgan fingerprints. Other algorithms use their fixed effective profiles and reject a Morgan profile. Each algorithm has one fixed representation. Algorithms without an implemented encoder fail explicitly.

Result and Input Correspondence

FingerprintEncodingResult keeps the numerical representation and its encoding context together.

Its principal fields are:

Field Meaning
fingerprints NumPy matrix for valid inputs
profile Complete serialized effective profile
valid_indices Original input positions represented in the matrix
input_statuses One status object for every original input
valid_count Number of valid inputs
invalid_count Number of invalid inputs
matrix_shape Matrix dimensions
matrix_dtype NumPy matrix dtype
molraptor_version MOLRAPTOR version used for encoding
rdkit_version RDKit version used for parsing and encoding
ordered_input_hash Digest identifying the ordered source-input sequence
profile_hash Digest identifying the complete effective profile

valid_indices maps matrix rows back to positions in the original input sequence.

For example:

from molraptor import encode_fingerprints

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

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

The matrix contains two rows:

matrix row 0 ↔ input index 0
matrix row 1 ↔ input index 2

The invalid record at input index 1 remains represented in input_statuses.

FingerprintInputStatus

Each FingerprintInputStatus records:

input_index
input_smiles
status
fingerprint_index
invalid_reason

For a valid input:

  • status is valid;
  • fingerprint_index identifies its matrix row;
  • invalid_reason is absent.

For an invalid input:

  • status is invalid;
  • fingerprint_index is absent;
  • invalid_reason is recorded.

Current invalid reasons are:

  • parse_failure;
  • empty_molecule.

Zero-valid behavior

The in-memory encoder may return an empty matrix when all supplied records are invalid:

(0, fingerprint_width)

This is a valid in-memory result.

The file workflow applies a stricter policy and treats zero valid SMILES as a global workflow failure.

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.

Encoding Metadata

FingerprintEncodingResult.serialize_metadata() returns a JSON-compatible dictionary containing encoding-level metadata without embedding either the fingerprint matrix or the row-level input_statuses.

It contains:

profile
valid_indices
valid_count
invalid_count
matrix_shape
matrix_dtype
molraptor_version
rdkit_version
ordered_input_hash
profile_hash

The file workflow extends this encoding metadata with source-file information and input_count before writing encoding_metadata.json.

Source-file metadata added by the file workflow are:

source_file_name
input_format
smiles_column
input_count

For TXT input, smiles_column is null.

The local filesystem path is not persisted in the metadata.

Hash Definitions

MOLRAPTOR uses two SHA-256 hashes to distinguish source-input identity from effective-profile identity.

Neither hash is a hash of the fingerprint matrix.

ordered_input_hash

ordered_input_hash is calculated from the complete ordered sequence of input strings.

The sequence preserves:

  • input order;
  • duplicate strings;
  • whitespace;
  • empty strings.

The sequence is serialized as compact JSON using:

json.dumps(
    value,
    ensure_ascii=False,
    separators=(",", ":"),
    sort_keys=False,
)

The UTF-8 encoded JSON bytes are then hashed with SHA-256.

Conceptually:

payload = json.dumps(
    ordered_smiles,
    ensure_ascii=False,
    separators=(",", ":"),
    sort_keys=False,
).encode("utf-8")

ordered_input_hash = hashlib.sha256(payload).hexdigest()

The hash therefore identifies the exact ordered source-input sequence used by the encoder. It does not identify chemical equivalence.

Different SMILES strings may produce the same numerical fingerprint while retaining different ordered_input_hash values.

profile_hash

profile_hash is calculated from the complete effective profile.

The profile is serialized as compact JSON using:

json.dumps(
    value,
    ensure_ascii=False,
    separators=(",", ":"),
    sort_keys=True,
)

The UTF-8 encoded JSON bytes are then hashed with SHA-256.

Conceptually:

payload = json.dumps(
    effective_profile,
    ensure_ascii=False,
    separators=(",", ":"),
    sort_keys=True,
).encode("utf-8")

profile_hash = hashlib.sha256(payload).hexdigest()

Sorting the object keys makes the digest independent of dictionary key insertion order.

The hash identifies the effective encoding profile. It does not identify the source input or the resulting numerical matrix.

The two hashes therefore represent different identities:

ordered_input_hash → source-input identity
profile_hash       → effective-profile identity

MOLRAPTOR does not claim that these hashes capture the complete computational environment. Environment details such as operating system, Python version, and NumPy version are not included in either hash.

File Workflow API

The file workflow reads ordered SMILES from CSV or UTF-8 TXT, delegates fingerprint calculation to encode_fingerprints(), applies workflow-level validation, and writes the defined four-artifact output set.

MolraptorConfig

MolraptorConfig defines:

Field Meaning
input_path Input CSV or TXT path
smiles_column CSV column containing SMILES; default SMILES
output_dir Artifact destination; default artifacts
fingerprint_type Compatibility name selecting the fingerprint algorithm
profile MorganFingerprintProfile for Morgan; otherwise None

Morgan receives its default MorganFingerprintProfile when no explicit profile is supplied.

Non-Morgan algorithms reject a Morgan profile.

Bases: BaseModel

Inputs and outputs for one file-based fingerprint execution.

validate_config

validate_config() checks that the supplied object is a MolraptorConfig instance and returns that same validated instance.

Configuration-field validation itself is performed by MolraptorConfig.

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

run() executes the file workflow and returns the same FingerprintEncodingResult used to create the persisted artifacts.

A successful execution writes:

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

Individual invalid SMILES do not stop a batch when at least one input is valid. A batch containing zero valid SMILES is a global file-workflow failure and publishes no final artifacts.

For input formats, CLI operation, output schemas, and failure behavior, see the Usage guide.

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 provides public stateless validation helpers.

ensure_required_columns() verifies that specified columns exist in a pandas DataFrame.

is_valid_smiles() applies the same RDKit parsing rule used by the in-memory encoder and returns whether the supplied string produces a non-empty molecule.

Validation does not curate, harmonize, canonicalize, or replace the supplied SMILES.

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__.