API Reference¶
Complete reference for all public classes, pipelines, and functions in HARMONSMILE. Documentation is auto-generated from NumPy-style docstrings in the source code.
Configuration¶
PubChemConfig¶
harmonsmile.PubChemConfig
dataclass
¶
Immutable configuration for :class:~harmonsmile.pipelines.PubChemIngest.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_path
|
str
|
Path to the input file (CSV, TSV, XLSX). Must not be empty or contain path traversal patterns ('..'). |
required |
cid_col
|
str
|
Name of the PubChem CID column. Must not be empty or whitespace-only when provided. Defaults to None, which enables deterministic alias-based auto-detection. |
None
|
props
|
tuple of str
|
PubChem properties to fetch. Must contain at least one valid property name. Defaults to all available properties. |
('SMILES', 'ConnectivitySMILES', 'MolecularFormula', 'MolecularWeight', 'InChI', 'InChIKey', 'XLogP', 'TPSA', 'Charge', 'HBondDonorCount', 'HBondAcceptorCount', 'RotatableBondCount', 'HeavyAtomCount')
|
keep_extra_columns
|
bool
|
Preserve input metadata columns outside the declared output schema. Defaults to False. |
False
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
ValueError
|
If |
ValueError
|
If |
Examples:
>>> from harmonsmile import PubChemConfig
>>> cfg = PubChemConfig(
... input_path="examples/example_pubchem.csv",
... )
ChEMBLConfig¶
harmonsmile.ChEMBLConfig
dataclass
¶
Immutable configuration for :class:~harmonsmile.pipelines.ChEMBLIngest.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_path
|
str
|
Path to the input file (CSV, TSV, XLSX). Must not be empty or contain path traversal patterns ('..'). |
required |
chembl_id_col
|
str
|
Name of the ChEMBL ID column in the input file. Must not be empty or whitespace-only. Defaults to 'ChEMBL ID'. |
'ChEMBL ID'
|
keep_extra_columns
|
bool
|
Preserve input metadata columns outside the declared output schema. Defaults to False. |
False
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
ValueError
|
If |
Examples:
>>> from harmonsmile import ChEMBLConfig
>>> cfg = ChEMBLConfig(
... input_path="examples/example_chembl.csv",
... )
SMILESConfig¶
harmonsmile.SMILESConfig
dataclass
¶
Immutable configuration for :class:~harmonsmile.pipelines.SMILESPrep.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_path
|
str
|
Path to the input file (CSV, TSV, XLSX). Must not be empty or contain path traversal patterns ('..'). |
required |
smiles_col
|
str
|
Name of the column containing SMILES strings. Must not be empty or whitespace-only. |
required |
keep_extra_columns
|
bool
|
Preserve input metadata columns outside the declared output schema. Defaults to False. |
False
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
ValueError
|
If |
Examples:
>>> from harmonsmile import SMILESConfig
>>> cfg = SMILESConfig(
... input_path="examples/example_smiles.csv",
... smiles_col="SMILES",
... )
Pipelines¶
PubChemIngest¶
harmonsmile.PubChemIngest
¶
Pipeline for ingesting and harmonizing PubChem compound data.
Fetches properties from the PubChem REST API and appends SMILES_RDKit plus lab harmonization value/status/error columns. PubChem-provided ConnectivitySMILES is preserved when available.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cfg
|
PubChemConfig
|
Pipeline configuration. |
required |
client
|
_PubChemClient
|
PubChem API client. Created automatically if not provided. |
None
|
std
|
RDKitStandardizer
|
SMILES standardizer. Created automatically if not provided. |
None
|
Examples:
>>> from harmonsmile import PubChemIngest, PubChemConfig
>>> cfg = PubChemConfig(
... input_path="examples/example_pubchem.csv",
... )
>>> df = PubChemIngest(cfg).run()
run()
¶
Execute the PubChem ingestion pipeline.
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame following the PubChem output schema. Extra metadata columns are included only when keep_extra_columns=True. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the configured CID column is not found in the input file. |
ValueError
|
If the input file has zero rows. |
ChEMBLIngest¶
harmonsmile.ChEMBLIngest
¶
Pipeline for ingesting and harmonizing ChEMBL compound data.
Fetches properties from the ChEMBL REST API by ChEMBL ID and appends SMILES_RDKit plus lab harmonization value/status/error columns.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cfg
|
ChEMBLConfig
|
Pipeline configuration. |
required |
client
|
_ChEMBLClient or None
|
ChEMBL API client. Created automatically if not provided. |
None
|
std
|
RDKitStandardizer or None
|
SMILES standardizer. Created automatically if not provided. |
None
|
Examples:
>>> from harmonsmile import ChEMBLIngest, ChEMBLConfig
>>> cfg = ChEMBLConfig(
... input_path="examples/example_chembl.csv",
... )
>>> df = ChEMBLIngest(cfg).run()
run()
¶
Execute the ChEMBL ingestion pipeline.
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame following the ChEMBL output schema. Extra metadata columns are included only when keep_extra_columns=True. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the configured ChEMBL ID column is not found in the input file. |
ValueError
|
If the input file has zero rows. |
SMILESPrep¶
harmonsmile.SMILESPrep
¶
Pipeline for preparing SMILES from any tabular source.
Reads a tabular file and appends SMILES_RDKit plus lab harmonization value/status/error columns for the configured source SMILES column.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cfg
|
SMILESConfig
|
Pipeline configuration. |
required |
std
|
RDKitStandardizer
|
SMILES standardizer. Created automatically if not provided. |
None
|
Examples:
>>> from harmonsmile import SMILESPrep, SMILESConfig
>>> cfg = SMILESConfig(
... input_path="examples/example_smiles.csv",
... smiles_col="SMILES",
... )
>>> df = SMILESPrep(cfg).run()
run()
¶
Execute the SMILES preparation pipeline.
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame following the SMILES output schema. Extra metadata columns are included only when keep_extra_columns=True. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the specified SMILES column is not found in the input file. |
ValueError
|
If the input file has zero rows. |
Standardization¶
RDKitStandardizer¶
harmonsmile.RDKitStandardizer
¶
Standardize and harmonize SMILES strings using RDKit.
to_iso_kek preserves the v0.2.5 RDKit canonicalization contract.
to_lab_harmonized applies the v0.3.x lab harmonization policy.
to_conn_kek(smiles)
staticmethod
¶
Convert SMILES to canonical + connectivity-only + Kekulized form.
Stereochemistry is stripped. Useful for connectivity-based comparisons where chirality is not relevant.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
smiles
|
str
|
Input SMILES string. |
required |
Returns:
| Type | Description |
|---|---|
str or None
|
Standardized SMILES without stereochemistry, or None if invalid. |
Examples:
>>> RDKitStandardizer.to_conn_kek("C[C@@H](O)F")
'CC(O)F'
>>> RDKitStandardizer.to_conn_kek("invalid")
>>> RDKitStandardizer.to_conn_kek("")
to_iso_kek(smiles)
staticmethod
¶
Convert SMILES to canonical + isomeric + Kekulized form.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
smiles
|
str
|
Input SMILES string. |
required |
Returns:
| Type | Description |
|---|---|
str or None
|
Standardized SMILES, or None if input is invalid. |
Notes
This is a compatibility canonicalization layer, not full chemical harmonization. It does not intentionally desalt, neutralize, reionize, or canonicalize tautomers.
Chiral centers (e.g. [C@@H]) are preserved because RDKit encodes
tetrahedral stereochemistry independently of kekulization.
E/Z geometry on double bonds (/ and \ in SMILES) is preserved
only when RDKit can unambiguously determine the configuration after
parsing and sanitization. For some double bonds — particularly those
in conjugated systems or where the source SMILES omits directional
bonds on one side — RDKit cannot resolve the geometry and silently
drops the / and \ notation. This is a known RDKit behavior, not a
bug in harmonsmile. If E/Z fidelity is critical for your use case,
validate SMILES_RDKit against the source SMILES.
Examples:
>>> RDKitStandardizer.to_iso_kek("c1ccccc1")
'C1=CC=CC=C1'
>>> RDKitStandardizer.to_iso_kek("invalid")
>>> RDKitStandardizer.to_iso_kek("")
to_lab_harmonized(smiles, *, canonicalize_tautomers=True, max_tautomers=1000, max_transforms=1000)
classmethod
¶
Harmonize a SMILES string using explicit RDKit-native lab policy.
The policy is intentionally auditable and avoids broad parent/cleanup helpers. It validates input, generates a controlled parent for simple salts/counterions, rejects ambiguous or unsupported structures, applies normalization, uncharging, reionization, optional tautomer canonicalization, and finally serializes as canonical, isomeric, aromatic SMILES.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
smiles
|
Any
|
Input SMILES value. |
required |
canonicalize_tautomers
|
bool
|
If True, use RDKit TautomerEnumerator canonicalization. |
True
|
max_tautomers
|
int
|
Applied through TautomerEnumerator.SetMaxTautomers when available. |
1000
|
max_transforms
|
int
|
Applied through TautomerEnumerator.SetMaxTransforms when available. |
1000
|
Returns:
| Type | Description |
|---|---|
HarmonizationResult
|
Typed harmonization result with value, status, error, and warning. |
Notes
This method does not call RemoveStereochemistry. When available, RDKit tautomer stereo-removal defaults are overridden to preserve bond and sp3 stereo, and stereo reassignment is kept enabled. Residual assigned chiral-center changes after tautomer canonicalization are reported as warning="stereo_annotation_changed". This is a conservative caveat, not a complete stereochemistry audit. The method returns one canonical harmonized representation, not a tautomer ensemble, and it is not a pH-specific or bioactive-tautomer predictor.
I/O Utilities¶
load_table¶
harmonsmile.load_table(path)
¶
Load a tabular file into a DataFrame.
Supports CSV, TSV, TXT, XLSX, XLSM, and XLS formats. CSV files use
comma delimiters, TSV/TXT files use tab delimiters, and Excel files
are loaded with :func:pandas.read_excel.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str or PathLike
|
Path to the input file. |
required |
Returns:
| Type | Description |
|---|---|
DataFrame
|
Loaded DataFrame with cleaned 'id' column if present. |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If the file does not exist at the given path. |
ValueError
|
If the file format is not supported. |
ValueError
|
If the loaded DataFrame has zero rows. |
Examples:
>>> df = load_table("examples/example_chembl.csv")
>>> df = load_table("examples/example_pubchem.csv")
save_table¶
harmonsmile.save_table(df, path)
¶
Save a DataFrame to a CSV file.
Parent directories are created automatically if they do not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
df
|
DataFrame
|
DataFrame to save. |
required |
path
|
str or PathLike
|
Output file path. Parent directories are created as needed. |
required |
Examples:
>>> import pandas as pd
>>> df = pd.DataFrame({"SMILES": ["C1=CC=CC=C1"], "SMILES_RDKit": ["C1=CC=CC=C1"]})
>>> save_table(df, "results/output.csv")