neurosnap.database.pubchem module#

PubChem compound lookup and similarity-search helpers.

class neurosnap.database.pubchem.PubChemCompound(cid, name, smiles, molecular_formula, molecular_weight)[source]#

Bases: object

Minimal PubChem compound record.

Variables:

  • cid – PubChem Compound Identifier.

  • name – Preferred IUPAC name (or the best available record title).

  • smiles – Isomeric SMILES, falling back to the connectivity SMILES.

  • molecular_formula – Hill-notation molecular formula.

  • molecular_weight – Molecular weight in g/mol.

cid: int#
molecular_formula: str#
molecular_weight: float#
name: str#
smiles: str#
property url: str#

Return the public PubChem page URL for the compound.

class neurosnap.database.pubchem.PubChemHit(query, cid, rank, name, smiles, molecular_formula, molecular_weight, similarity)[source]#

Bases: object

A single compound returned by a PubChem similarity search.

Variables:

  • query – SMILES string the hit was found for.

  • cid – PubChem Compound Identifier.

  • rank – PubChem’s 1-based similarity rank for the hit.

  • name – Preferred IUPAC name (or the best available record title).

  • smiles – Isomeric SMILES, falling back to the connectivity SMILES.

  • molecular_formula – Hill-notation molecular formula.

  • molecular_weight – Molecular weight in g/mol.

  • similarity – Local RDKit Morgan/Tanimoto score in the 0-1 range.

cid: int#
molecular_formula: str#
molecular_weight: float#
name: str#
query: str#
rank: int#
similarity: float#
smiles: str#
property url: str#

Return the public PubChem page URL for the compound.

neurosnap.database.pubchem.fetch_pubchem_sdfs(cids, *, prefer_3d=True, timeout=30)[source]#

Download SDF records for one or more PubChem CIDs.

Records are retrieved in batches. When prefer_3d is set, 3D conformers are requested first and any CID without a 3D record falls back to its 2D record.

Parameters:

  • cids (Iterable[int]) – PubChem Compound Identifiers to download.

  • prefer_3d (bool) – If True, request 3D SDF records before falling back to 2D.

  • timeout (int) – HTTP timeout in seconds per batch request.

Return type:

Dict[int, str]

Returns:

Dictionary mapping each resolved CID to its SDF record text.

neurosnap.database.pubchem.get_pubchem_compound(query, *, timeout=30)[source]#

Fetch a PubChem compound by name or Compound Identifier (CID).

Parameters:

  • query (Union[str, int]) – Compound name or numeric PubChem CID.

  • timeout (int) – HTTP timeout in seconds.

Return type:

PubChemCompound

Returns:

The resolved PubChemCompound record.

Raises:

ValueError – If the compound cannot be found or its record is incomplete.

neurosnap.database.pubchem.search_pubchem_similar(smiles, *, threshold=0.9, max_records=100, timeout=30)[source]#

Find PubChem compounds structurally similar to a query SMILES.

Results are ordered by the local RDKit Tanimoto score (descending) while retaining PubChem’s own similarity rank for each hit. The local score uses RDKit Morgan fingerprints and approximates PubChem’s ranking; the two fingerprints are not identical.

Parameters:

  • smiles (str) – Query SMILES string.

  • threshold (float) – Similarity threshold in the 0-1 range, scaled to PubChem’s 1-100 Threshold parameter.

  • max_records (int) – Maximum number of hits to request from PubChem.

  • timeout (int) – HTTP timeout in seconds.

Return type:

List[PubChemHit]

Returns:

A list of PubChemHit records, possibly empty.

Raises:

ValueError – If smiles is empty or cannot be parsed.