molforge.chem¶

chem ¶

Cheminformatics operations on :class:~molforge.core.Molecule.

Where :mod:molforge.core holds the small-molecule type and :mod:molforge.io reads molecules from files, this package holds the chemistry operations — starting with standardization (cleaning) for consistent, deduplicable structures. Everything here is RDKit-backed and lazy: importing :mod:molforge.chem never pulls RDKit in, and an operation without RDKit raises :class:~molforge.core.RDKitNotInstalledError.

MoleculeDataset ¶

MoleculeDataset(molecules: Iterable[Molecule])

A lazy, immutable pipeline over a stream of molecules.

Wrap any iterable of :class:~molforge.core.Molecule; the combinators (:meth:map, :meth:take) return new datasets and nothing runs until the dataset is iterated or :meth:collect-ed.

Attributes are intentionally hidden: a dataset is defined only by what it yields when iterated.

Wrap an iterable of molecules (not consumed until iterated).

map ¶

map(fn: Callable[[Molecule], Molecule]) -> MoleculeDataset

Apply fn to every molecule, lazily.

Parameters:

Name	Type	Description	Default
`fn`	`Callable[[Molecule], Molecule]`	A per-molecule transform, e.g. :func:`molforge.chem.standardize`.	required

Returns:

Type	Description
`MoleculeDataset`	A new dataset yielding `fn(m)` for each molecule `m`.

take ¶

take(n: int) -> MoleculeDataset

Keep only the first n molecules.

Parameters:

Name	Type	Description	Default
`n`	`int`	How many molecules to keep; `take` short-circuits, so an unbounded source is fine.	required

Returns:

Type	Description
`MoleculeDataset`	A new dataset yielding at most `n` molecules.

Raises:

Type	Description
`ValueError`	If `n` is negative.

filter ¶

filter(criterion: Criterion) -> MoleculeDataset

Keep molecules whose descriptors satisfy criterion.

criterion is a :class:~molforge.validation.Criterion over molecule descriptors — see :func:molforge.chem.molecule_descriptors for the vocabulary (molecular_weight, formal_charge, n_atoms, n_heavy_atoms). Its referenced names are validated up front, and only those descriptors are computed per molecule::

from molforge.validation import Criterion
ds.filter(Criterion.lt("molecular_weight", 500) & Criterion.le("formal_charge", 0))

Parameters:

Name	Type	Description	Default
`criterion`	`Criterion`	A criterion over descriptor names.	required

Returns:

Type	Description
`MoleculeDataset`	A new dataset yielding only the molecules that satisfy
`MoleculeDataset`	`criterion`.

Raises:

Type	Description
`ValueError`	If the criterion references an unknown descriptor.
`RDKitNotInstalledError`	If RDKit isn't installed (on consumption).

valid ¶

valid() -> MoleculeDataset

Keep only molecules that pass RDKit sanitization.

A lazy filter over :func:molforge.chem.is_valid — structures RDKit rejects are dropped rather than raising.

Returns:

Type	Description
`MoleculeDataset`	A new dataset yielding only the valid molecules.

dedup ¶

dedup(*, key: str = 'inchikey') -> MoleculeDataset

Drop duplicate molecules by structural identity, keeping the first.

Streams with a running set of seen identities, so only the identities (not the molecules) are held in memory.

Parameters:

Name	Type	Description	Default
`key`	`str`	Identity to compare on — `"inchikey"` (default) or `"smiles"`.	`'inchikey'`

Returns:

Type	Description
`MoleculeDataset`	A new dataset yielding the first molecule of each identity, in
`MoleculeDataset`	order.

Raises:

Type	Description
`ValueError`	If `key` is neither `"inchikey"` nor `"smiles"`.

collect ¶

collect() -> list[Molecule]

Materialize the dataset into a list, running the whole pipeline.

molecule_descriptors ¶

molecule_descriptors(
    molecule: Molecule,
    *,
    names: Iterable[str] | None = None,
) -> dict[str, Any]

Compute filterable descriptors for a molecule.

Parameters:

Name	Type	Description	Default
`molecule`	`Molecule`	The molecule to describe.	required
`names`	`Iterable[str] \| None`	Which descriptors to compute; defaults to all of :data:`DESCRIPTOR_NAMES`. Restricting to the names a filter actually references avoids unnecessary RDKit work.	`None`

Returns:

Type	Description
`dict[str, Any]`	A flat `{name: value}` dict, ready for
`dict[str, Any]`	meth:`molforge.validation.Criterion.evaluate`.

Raises:

Type	Description
`ValueError`	If a requested name isn't a known descriptor.
`RDKitNotInstalledError`	If RDKit isn't installed.

is_valid ¶

is_valid(molecule: Molecule) -> bool

Whether molecule passes RDKit sanitization.

Sanitization (valence, aromaticity, kekulization) runs on a copy, so the molecule is never mutated. A structure RDKit rejects — a pentavalent carbon, an unkekulizable ring — is reported as invalid rather than raising, so this reads as a predicate you can filter a set on.

Parameters:

Name	Type	Description	Default
`molecule`	`Molecule`	The molecule to check.	required

Returns:

Type	Description
`bool`	`True` if the molecule sanitizes cleanly, `False` otherwise.

Raises:

Type	Description
`RDKitNotInstalledError`	If RDKit isn't installed.

unique ¶

unique(
    molecules: Iterable[Molecule], *, key: str = "inchikey"
) -> list[Molecule]

Deduplicate molecules by structural identity, keeping the first seen.

Parameters:

Name	Type	Description	Default
`molecules`	`Iterable[Molecule]`	The molecules to deduplicate.	required
`key`	`str`	Which identity to compare on — `"inchikey"` (the default, a stable structural hash) or `"smiles"` (canonical isomeric SMILES). InChIKey is the safer default; SMILES is there for when InChI generation is unavailable or undesirable.	`'inchikey'`

Returns:

Type	Description
`list[Molecule]`	A new list with duplicates removed, preserving input order and
`list[Molecule]`	keeping the first molecule of each identity.

Raises:

Type	Description
`ValueError`	If `key` is neither `"inchikey"` nor `"smiles"`.
`RDKitNotInstalledError`	If RDKit isn't installed.

canonical_tautomer ¶

canonical_tautomer(molecule: Molecule) -> Molecule

Convert to RDKit's canonical tautomer.

cleanup ¶

cleanup(molecule: Molecule) -> Molecule

Sanitize, normalize functional groups, and reionize.

largest_fragment ¶

largest_fragment(molecule: Molecule) -> Molecule

Keep the largest organic fragment — strips salts and solvents.

neutralize ¶

neutralize(molecule: Molecule) -> Molecule

Remove formal charges where chemically reasonable.