neurosnap.database package#

Database and remote-search helpers.

class neurosnap.database.CCD(code, name, smiles, type)[source]#

Bases: object

Minimal Chemical Component Dictionary entry.

Variables:

  • code – CCD identifier, typically 1-5 characters.

  • name – Human-readable component name.

  • smiles – SMILES string for the component (technically canonicalized but the canonicalization algorithm used by wwPDB is inconsistent with that of RDkit).

  • type – CCD component type.

code: str#
name: str#
smiles: str#
smiles_canonical()[source]#

Return the RDKit-canonicalized SMILES string for this CCD entry.

Return type:

str

to_mol()[source]#

Return an RDKit molecule parsed from the canonical SMILES string.

Return type:

Mol

Returns:

RDKit molecule for the CCD entry.

Raises:

ValueError – If the stored canonical SMILES cannot be parsed.

type: str#
class neurosnap.database.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.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.fetch_accessions(accessions, batch_size=150)[source]#

Fetch sequences corresponding to a list of UniProt accession numbers.

This function queries UniParc first and then UniProtKB for any missing accessions. Accessions are processed in batches to handle large lists efficiently.

Parameters:

  • accessions (Iterable[str]) – A list of UniProt accession numbers. Duplicate accessions are removed automatically.

  • batch_size (int) – Number of accessions to query per request.

Return type:

Dict[str, Optional[str]]

Returns:

Dictionary mapping accession numbers to protein sequences. Missing accessions are assigned None.

Raises:

requests.exceptions.HTTPError – If an API request fails.

neurosnap.database.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.fetch_uniprot(uniprot_id, head=False)[source]#

Fetch a UniProtKB or UniParc FASTA entry by identifier.

Parameters:

  • uniprot_id (str) – UniProtKB or UniParc accession ID.

  • head (bool) – If True, perform a HEAD request and return whether the entry exists.

Return type:

Union[str, bool]

Returns:

True when head is enabled and the accession exists, otherwise the fetched protein sequence.

Raises:

  • Exception – If the accession is not found in UniProtKB or UniParc.

  • ValueError – If the returned FASTA does not contain exactly one sequence.

Perform a protein structure search using the Foldseek API.

Parameters:

  • structure (Union[Structure, StructureEnsemble, StructureStack, str, Path]) – A Neurosnap structure container or a path to a PDB file.

  • mode (str) – Search mode. Must be one of "3diaa" or "tm-align".

  • databases (Optional[List[str]]) – Databases to search. Defaults to Foldseek’s common public structure databases.

  • max_retries (int) – Maximum number of retries when polling job status.

  • retry_interval (int) – Seconds between job-status polls.

  • output_format (str) – Output format, either "json" or "dataframe".

Return type:

Union[str, DataFrame]

Returns:

Search results in the requested format.

Raises:

  • RuntimeError – If job submission or retrieval fails.

  • TimeoutError – If the job does not complete before retries are exhausted.

  • ValueError – If output_format is invalid.

neurosnap.database.get_ccd(code, *, cache_path='~/.cache/neurosnap/ccd_entries.json', overwrite=False, max_age_days=7, timeout=30)[source]#

Return a CCD entry by its component code.

Return type:

Optional[CCD]

neurosnap.database.get_ccd_canonical_aa(ccd, *, standard=True, cache_path='~/.cache/neurosnap/ccd_entries.json', overwrite=False, max_age_days=7, timeout=30)[source]#

Return the most similar canonical or standard amino acid for a CCD entry.

If the input CCD code already has an explicit amino-acid mapping in the amino-acid residue tables, that mapping is reused directly. Otherwise, the CCD entry is compared against canonical amino-acid CCD entries using RDKit Morgan fingerprints and the highest-similarity amino acid is returned. Selenium-containing residues are also compared after conservative selenium-to-sulfur normalization so common analogs such as MSE can map to their sulfur parent without being hard-coded into the amino-acid constants.

Parameters:

  • ccd (Union[str, CCD]) – CCD code string or a CCD instance.

  • standard (bool) – If True (default), collapse results to the 20 standard amino acids. If False, allow all canonical residues, including SEC and PYL.

  • cache_path (str) – Local cache file path for the CCD JSON payload.

  • overwrite (bool) – If True, force a fresh CCD payload download.

  • max_age_days (int) – Maximum accepted payload age in days.

  • timeout (int) – HTTP timeout in seconds for CCD payload downloads.

Return type:

AARecord

Returns:

The best-matching amino-acid record under the requested mode.

Raises:

  • TypeError – If ccd is not a string or CCD.

  • ValueError – If the CCD code is unknown or its SMILES cannot be parsed.

neurosnap.database.get_ccd_entries(*, cache_path='~/.cache/neurosnap/ccd_entries.json', overwrite=False, max_age_days=7, timeout=30)[source]#

Fetch and cache CCD metadata entries.

The CCD payload is cached locally and refreshed when the cached payload exceeds max_age_days based on its embedded created_at timestamp.

Parameters:

  • cache_path (str) – Local cache file path for the raw JSON payload.

  • overwrite (bool) – If True, force a fresh download.

  • max_age_days (int) – Maximum accepted payload age in days.

  • timeout (int) – HTTP timeout in seconds for the download request.

Return type:

Dict[str, CCD]

Returns:

Dictionary mapping CCD code to CCD.

neurosnap.database.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.run_blast(sequence, email, matrix='BLOSUM62', alignments=250, scores=250, evalue=10.0, filter=False, gapalign=True, database='uniprotkb_refprotswissprot', output_format=None, output_path=None, return_df=True)[source]#

Submit a BLASTP job to the EBI service and optionally return hits as a dataframe.

Return type:

Optional[DataFrame]

neurosnap.database.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.

Submodules#