search_classes

search_classes(classes_file: str | None = None, classes_name_id: str | None = None, classes_name_smarts: str | None = None, closest_only: bool = True, include_hierarchy: bool = False, input_smiles: str | None = None, smiles: str | list[str] | None = None, export: bool = True, output_dir: Path | str | None = None) → list[dict][source]

Perform substructure search to classify chemical structures.

This function matches input structures against a set of chemical class definitions using SMARTS patterns. Results include the class ID, matching SMARTS pattern, and structural similarity metrics.

Parameters:

  • classes_file – Path to TSV file with chemical class definitions. If None, uses the default package classes.

  • classes_name_id – Column name for class IDs in the classes file. Defaults to “class”.

  • classes_name_smarts – Column name for SMARTS in the classes file. Defaults to “structure”.

  • closest_only – If True, return only the closest matching class for each structure. Default is True.

  • include_hierarchy – If True, use chemical hierarchy for faster searching. Default is False.

  • input_smiles – Path to file containing SMILES strings to classify.

  • smiles – Single SMILES string or list of SMILES to classify.

  • export – If True, export results to files. Default is True.

  • output_dir – Directory for output files. Uses config default if None.

Returns:

List of dictionaries with classification results.

Raises:

ValueError – If no structures are provided and ChEMBL fallback fails.