neurosnap.chemistry package#
Public chemistry package exports.
- class neurosnap.chemistry.CharacterizationReport(diversity, network, islands, frontier=<factory>, counts=<factory>, metadata=<factory>)[source]#
Bases:
objectEverything the engine can say about a library.
-
diversity:
DiversityMetrics#
-
islands:
IslandResult#
-
network:
NetworkMetrics#
-
diversity:
- class neurosnap.chemistry.ChemicalGraph(node_type, smiles, compound_id, level, frequency, n_atoms, n_rings, mw, method, murcko, src, dst, edge_type, weight)[source]#
Bases:
objectColumn-store heterogeneous chemical graph.
Nodes: compounds, scaffolds, fragments. Edges: compound-scaffold, compound-fragment, similarity, scaffold hierarchy, fragment sharing. Flat NumPy arrays plus a cached SciPy CSR adjacency for graph algorithms.
- adjacency(edge_types=None)[source]#
Unweighted undirected CSR adjacency, optionally restricted to types.
- Return type:
csr_matrix
- average_path_length(sources)[source]#
Average shortest-path length estimated from BFS trees of
sources.
- class neurosnap.chemistry.ChemicalLandscape(source=None, smiles_column='smiles', id_column=None, config=None, *, compound_ids=None, **overrides)[source]#
Bases:
objectA molecular library and the chemical landscape built from it.
The source may be a path or an in-memory SMILES sequence:
landscape = ChemicalLandscape(“library.csv”, smiles_column=”smiles”) landscape.build_all() report = landscape.characterize() print(report.summary()) landscape.save(“out/”) reloaded = ChemicalLandscape.from_store(“out/”)
- Parameters:
source (
Union[str,Path,Sequence[str],None]) – Input path or in-memory SMILES sequence.smiles_column (
str) – SMILES column for delimited input files.id_column (
Optional[str]) – Optional compound identifier column.config (
Optional[LandscapeConfig]) – Optional complete landscape configuration.compound_ids (
Optional[Sequence[str]]) – IDs corresponding to an in-memory SMILES sequence.**overrides (
Any) – Configuration field overrides.
- build_fragments()[source]#
Fragment every compound (BRICS, rotatable bonds, linkers).
When
FragmentConfig.reversibleis enabled, each compound also keeps aReverseFragmentRecord(attachment points + cut orders) so it can be rebuilt withreassemble().- Return type:
- build_scaffolds()[source]#
Annotate Bemis-Murcko scaffolds and build the scaffold network.
- Return type:
- characterize(n_samples=512, seed=0, resolution=1.0)[source]#
Run the full characterization and cache the report.
- Return type:
- decompose(core_smiles=None, *, params=None)[source]#
Decompose the library into a core + per-position R-groups.
If
core_smilesis omitted, the most frequent scaffold is used.- Parameters:
- Return type:
- Returns:
Per-molecule R-group decomposition.
- enumerate(core_smiles, rgroups_by_label, *, max_products=100000)[source]#
Enumerate all products of a labeled core with R-groups per position.
rgroups_by_labelmaps an attachment label to a list of R-group SMILES (each carrying a matching labeled dummy, e.g.CO[*:1]).
- property fingerprints: FingerprintBlock | None#
Packed Morgan fingerprints, if the library has been loaded.
- classmethod from_store(path)[source]#
Load a previously persisted landscape.
- Parameters:
path (
Union[str,Path]) – Landscape directory created bysave().- Return type:
- Returns:
Restored
ChemicalLandscapeinstance.
- property graph: ChemicalGraph#
The heterogeneous chemical graph (assembled on first access).
- island_of(compound_id)[source]#
Island id of a compound (-1 if it was not part of the analysis).
- Return type:
- neighbors(compound_id, edge_types=None)[source]#
Return labels of the direct neighbours of a compound.
- reassemble(compound_id)[source]#
Rebuild a compound’s canonical SMILES from its fragments.
Uses the reversible fragment record (attachment points + cut orders) captured during
build_fragments(). Returns""if the compound was not fragmented reversibly.- Return type:
- property report: CharacterizationReport#
Return the cached characterization report, building it if needed.
- save(path)[source]#
Persist the landscape as JSON plus an optional NPZ fingerprint store.
- Return type:
- swap_rgroup(compound_id, position, new_rgroup, core_smiles=None)[source]#
Replace an R-group at
positionand return the new molecule.new_rgroupshould carry a dummy labeled forposition(e.g.CO[*:1]for position 1). The compound is decomposed against a core, the labelled position is substituted, and the product is reassembled with the other R-groups left in place.- Return type:
- class neurosnap.chemistry.EdgeType(*values)[source]#
Bases:
IntEnumEdge types of the heterogeneous chemical graph.
- COMPOUND_FRAGMENT = 2#
- COMPOUND_SCAFFOLD = 1#
- COMPOUND_SIMILARITY = 3#
- FRAGMENT_SHARED = 5#
- SCAFFOLD_HIERARCHY = 4#
- class neurosnap.chemistry.FingerprintConfig(radii=(2, 3), n_bits=2048, use_chirality=False, use_features=False)[source]#
Bases:
objectMorgan fingerprint settings.
radiimay hold several radii; bits of all radii are OR-ed into one packed vector, which keeps one fingerprint per compound while still covering multiple resolutions (radius 2 and 3 by default).
- class neurosnap.chemistry.FragmentConfig(use_brics=True, use_rotatable_bonds=True, use_linkers=True, min_fragment_atoms=3, max_fragments_per_molecule=32, max_rotatable_cuts=8, shared_links_per_fragment=4, reversible=True)[source]#
Bases:
objectFragmentation settings, in priority order.
- class neurosnap.chemistry.FragmentMethod(*values)[source]#
Bases:
IntEnumProvenance of a fragment node.
- BRICS = 1#
- LINKER = 3#
- ROTATABLE_BOND = 2#
- UNKNOWN = 0#
- class neurosnap.chemistry.LandscapeConfig(smiles_column='smiles', id_column=None, delimiter=None, chunk_size=20000, workers=1, limit=None, fingerprints=<factory>, scaffolds=<factory>, fragments=<factory>, similarity=<factory>)[source]#
Bases:
objectTop-level build settings.
-
fingerprints:
FingerprintConfig#
-
fragments:
FragmentConfig#
-
scaffolds:
ScaffoldConfig#
-
similarity:
SimilarityConfig#
-
fingerprints:
- class neurosnap.chemistry.NodeType(*values)[source]#
Bases:
IntEnumNode types of the heterogeneous chemical graph.
- COMPOUND = 0#
- FRAGMENT = 2#
- SCAFFOLD = 1#
- class neurosnap.chemistry.RGroupDecompositionResult(core_smiles='', rows=<factory>, n_failed=0)[source]#
Bases:
objectA library decomposed into a core plus per-position R-groups.
rowsis a list of per-molecule dicts keyed by R-group label ('Core','R1','R2', …) mapping to the group SMILES.- property positions#
Sorted integer attachment labels present (excluding the core).
- class neurosnap.chemistry.ReverseFragmentRecord(pieces=None, cut_orders=None, methods=None)[source]#
Bases:
objectA compound’s fragments kept with their attachment points so the molecule can be rebuilt.
Cutting a set of bonds produces pieces whose cut ends are capped with dummy atoms carrying a unique cut-id isotope.
piecesstores those reactive SMILES;cut_orders[k]is the bond order of the cut that produced thek-th isotope pair. Reassembly matches the two dummies of each cut id and reconnects their neighbours with the recorded bond order.
- class neurosnap.chemistry.ScaffoldConfig(max_level=6, include_generic=False, flatten_chirality=True, keep_only_first_fragment=True, strip_attachments=True, max_nodes_per_molecule=64)[source]#
Bases:
objectScaffold network settings (Bemis-Murcko is only the entry point).
- class neurosnap.chemistry.SimilarityConfig(threshold=0.55, k=8, n_permutations=128, n_bands=32, bucket_cap=64, max_candidate_pairs=20000000, mutual_only=False, seed=12648430, metric='tanimoto', exact_below=2000)[source]#
Bases:
objectSparse similarity graph settings (never all-vs-all above a size cap).
- neurosnap.chemistry.align_molecule_to_reference(mol, ref_mol)[source]#
Aligns a molecule to a reference molecule and returns the aligned copy.
The alignment is performed using RDKit’s coordinate-based molecular alignment routine. The input molecule is copied before alignment, so the original object remains unchanged.
- Parameters:
mol (Chem.Mol) – Molecule to align, with at least one conformer.
ref_mol (Chem.Mol) – Reference molecule defining the target orientation.
- Returns:
A copy of
molaligned toref_mol.- Return type:
Chem.Mol
- Raises:
ValueError – If either molecule is
Noneor lacks conformers.
- neurosnap.chemistry.attach_rgroup(core_smiles, rgroup_smiles, label)[source]#
Connect an R-group onto a core at the labeled attachment point.
Both the core and the R-group carry a matching labeled dummy (isotope or map-number form). The two dummies are removed and a single bond joins their neighbours. Returns the product SMILES (still carrying any other labels).
- neurosnap.chemistry.calculate_distance_matrix(mol)[source]#
Calculates the pairwise 3D distance matrix for a molecule.
Distances are computed from the atomic coordinates stored in the molecule’s active conformer. The returned matrix is square with one row and column per atom.
- Parameters:
mol (Chem.Mol) – Input RDKit molecule with at least one conformer.
- Returns:
- A square NumPy array of shape
(n_atoms, n_atoms) containing pairwise Euclidean distances in Angstroms.
- A square NumPy array of shape
- Return type:
np.ndarray
- Raises:
ValueError – If the input molecule is
Noneor has no conformers.
- neurosnap.chemistry.calculate_rmsd(mol_a, mol_b)[source]#
Calculates the best-fit RMSD between two molecules.
This function uses RDKit’s alignment-based RMSD calculation, meaning the molecules are optimally superimposed before the RMSD value is reported. As a result, pure rigid-body translations and rotations do not by themselves increase the returned RMSD.
- Parameters:
mol_a (Chem.Mol) – First RDKit molecule with at least one conformer.
mol_b (Chem.Mol) – Second RDKit molecule with at least one conformer.
- Returns:
Best-fit root-mean-square deviation between the two molecules.
- Return type:
- Raises:
ValueError – If either molecule is
Noneor lacks conformers.
- neurosnap.chemistry.canonicalize_smiles(smiles)[source]#
Converts a SMILES string into its canonical RDKit representation.
This is useful for normalizing equivalent SMILES strings into a stable text form for storage, comparison, or deduplication.
- Parameters:
smiles (str) – Input SMILES string to canonicalize.
- Returns:
Canonical SMILES string produced by RDKit.
- Return type:
- Raises:
ValueError – If the input string cannot be parsed as a valid SMILES.
- neurosnap.chemistry.decompose_molecules(mol_smiles, core_smiles, *, params=None)[source]#
Decompose a set of molecules into a core + R-groups (R-group linkage).
core_smilesmay be labeled ([*:1],[*:2], …) or unlabeled; an unlabeled core is matched and its attachment points detected automatically.- Parameters:
- Return type:
- Returns:
Decomposition rows and the matched core SMILES.
- neurosnap.chemistry.enumerate_core(core_smiles, rgroups_by_label, *, max_products=100000, dedupe=True)[source]#
Enumerate all products of a labeled core with lists of R-groups per label.
rgroups_by_labelmaps an attachment label to a list of R-group SMILES (each carrying a matching dummy). Returns the cartesian product as SMILES.- Parameters:
- Return type:
- Returns:
Enumerated product SMILES.
- neurosnap.chemistry.find_LCS(mol)[source]#
Find the largest common substructure (LCS) between a set of conformers and aligns all conformers to the LCS.
- neurosnap.chemistry.generate(input_mol, output_name='unique_conformers', write_multi=False, num_confs=1000, min_method='auto', max_atoms=500)[source]#
Generate conformers for an input molecule.
Performs the following actions in order: 1. Generate conformers using ETKDG method 2. Minimize energy of all conformers and remove those below a dynamic threshold 3. Align & create RMSD matrix of all conformers 4. Clusters using Butina method to remove structurally redundant conformers 5. Return most energetically favorable conformers in each cluster
- Parameters:
input_mol (
Any) – Input molecule can be a path to a molecule file, a SMILES string, or an instance of rdkit.Chem.rdchem.Moloutput_name (
str) – Output to write SDF files of passing conformerswrite_multi (
bool) – If True will write all unique conformers to a single SDF file, if False will write all unique conformers in separate SDF files in output_namenum_confs (
int) – Number of conformers to generatemin_method (
Optional[str]) – Method for minimization, can be either “auto”, “UFF”, “MMFF94”, “MMFF94s”, or None for no minimizationmax_atoms (
int) – Maximum number of atoms allowed for the input molecule
- Return type:
DataFrame- Returns:
A dataframe with all conformer statistics. Note if energy minimization is disabled or fails then energy column will consist of None values.
- neurosnap.chemistry.get_mol_center(mol, use_mass=False)[source]#
Computes the geometric center or center of mass of a molecule.
- Parameters:
mol (Mol) – An RDKit molecule object with 3D coordinates.
use_mass (bool, optional) – If True, computes the center of mass using atomic masses. If False, computes the simple geometric center. Defaults to False.
- Returns:
- A NumPy array of shape (3,) representing the [x, y, z] center coordinates.
Returns None if the molecule has no conformers.
- Return type:
np.ndarray
- Raises:
ValueError – If no conformer is found in the molecule.
- neurosnap.chemistry.largest_fragment(mol)[source]#
Selects the largest fragment from a multi-component molecule.
This is typically useful for salts, mixtures, or counterion-containing inputs where only the primary chemical component should be retained.
- Parameters:
mol (Chem.Mol) – Input RDKit molecule, which may contain multiple fragments.
- Returns:
A copy containing only the largest fragment.
- Return type:
Chem.Mol
- Raises:
ValueError – If the input molecule is
None.
- neurosnap.chemistry.minimize(mol, method='MMFF94', percentile=100.0)[source]#
Minimize conformer energy (kcal/mol) using RDkit and filter out conformers based on energy percentile.
- Parameters:
mol (
Mol) – RDkit mol object containing the conformers you want to minimize. (rdkit.Chem.rdchem.Mol)method (
str) – Can be either UFF, MMFF94, or MMFF94s (str)percentile (
float) – Filters out conformers above a given energy percentile (0 to 100). For example, 10.0 will retain conformers within the lowest 10% energy. (float)
- Return type:
- Returns:
A tuple of the form
(mol_filtered, energies)-mol_filtered: Molecule object with filtered conformers. -energies: Dictionary where keys are conformer IDs and values are calculated energies in kcal/mol.
- neurosnap.chemistry.move_ligand_to_center(ligand_sdf_path, receptor_pdb_path, output_sdf_path, use_mass=False)[source]#
Moves the center of a ligand in an SDF file to match the center of a receptor in a PDB file.
This function reads a ligand from an SDF file and a receptor from a PDB file, calculates their respective centers (center of mass or geometric center), and translates the ligand such that its center aligns with the receptor’s center. The modified ligand is then saved to a new SDF file.
- Parameters:
ligand_sdf_path (str) – Path to the input ligand SDF file.
receptor_pdb_path (str) – Path to the input receptor PDB file.
output_sdf_path (str) – Path where the adjusted ligand SDF will be saved.
use_mass (bool, optional) – If True, compute center of mass; otherwise use geometric center. Defaults to False.
- Returns:
Path to the output SDF file with the translated ligand.
- Return type:
- Raises:
ValueError – If the ligand cannot be parsed from the input SDF file.
- neurosnap.chemistry.neutralize_molecule(mol)[source]#
Neutralizes formal charges in a molecule where chemically supported.
This function uses RDKit’s uncharging logic to neutralize ionized atoms when a valid neutral form can be produced. Charges that cannot be safely neutralized are preserved.
- Parameters:
mol (Chem.Mol) – Input RDKit molecule to neutralize.
- Returns:
A copy of the molecule with reducible charges neutralized.
- Return type:
Chem.Mol
- Raises:
ValueError – If the input molecule is
None.
- neurosnap.chemistry.reassemble_fragments(pieces, cut_orders)[source]#
Join reactive fragment pieces back into the original molecule.
Two dummies sharing a cut-id isotope are reconnected with the recorded bond order, then all dummies are removed and the result is sanitized.
- neurosnap.chemistry.remove_salts(mol)[source]#
Removes common salt fragments while retaining the main molecular component.
The function first strips recognized salts and small counterions using RDKit’s salt remover, then selects the largest remaining fragment to produce a single primary molecule.
- Parameters:
mol (Chem.Mol) – Input RDKit molecule that may contain salts or counterions.
- Returns:
A desalted copy of the molecule.
- Return type:
Chem.Mol
- Raises:
ValueError – If the input molecule is
None.
- neurosnap.chemistry.reversible_fragment_record(smiles, cfg=None)[source]#
Fragment a molecule reversibly.
- Parameters:
smiles (
Union[str,Mol]) – SMILES string or RDKit molecule to fragment.cfg (
Optional[FragmentConfig]) – Optional fragmentation settings.
- Return type:
- Returns:
A reversible fragment record, or
Nonewhen no reversible cut applies.
- neurosnap.chemistry.sdf_to_smiles(fpath)[source]#
Converts molecules in an SDF file to SMILES strings.
Reads an input SDF file and extracts SMILES strings from its molecules. Invalid or unreadable molecules are skipped, with warnings logged.
- Parameters:
fpath (str) – Path to the input SDF file.
- Returns:
A list of SMILES strings corresponding to valid molecules in the SDF file.
- Return type:
List[str]
- Raises:
FileNotFoundError – If the SDF file cannot be found.
IOError – If the file cannot be read.
- neurosnap.chemistry.smiles_to_sdf(smiles, output_path)[source]#
Converts a SMILES string to an sdf file. Will overwrite existing results.
NOTE: This function does the bare minimum in terms of generating the SDF molecule. The
neurosnap.chemistry.conformersmodule should be used in most cases.
- neurosnap.chemistry.standardize_molecule(mol)[source]#
Standardizes a molecule using RDKit’s cleanup workflow.
The standardization process applies RDKit’s built-in molecular cleanup rules, which can normalize representations such as functional groups, charges, and related valence patterns into a more consistent form.
- Parameters:
mol (Chem.Mol) – Input RDKit molecule to standardize.
- Returns:
A standardized copy of the input molecule.
- Return type:
Chem.Mol
- Raises:
ValueError – If the input molecule is
None.
- neurosnap.chemistry.translate_molecule(mol, vector)[source]#
Translates all atomic coordinates in a molecule by a vector.
The input molecule is not modified in place. Instead, a copy is made and every atom position in the first conformer is shifted by the provided
[x, y, z]vector.- Parameters:
mol (Chem.Mol) – Input RDKit molecule with at least one conformer.
vector – Translation vector of length 3 containing the x, y, and z shifts.
- Returns:
A translated copy of the input molecule.
- Return type:
Chem.Mol
- Raises:
ValueError – If the molecule is
None, has no conformers, or the translation vector is not length 3.
- neurosnap.chemistry.validate_smiles(smiles)[source]#
Validates a SMILES (Simplified Molecular Input Line Entry System) string.
Submodules#
- neurosnap.chemistry.conformers module
- neurosnap.chemistry.geometry module
- neurosnap.chemistry.landscape module
CharacterizationReportChemicalGraphChemicalGraph.adjacency()ChemicalGraph.average_path_length()ChemicalGraph.connected_components()ChemicalGraph.count_edges()ChemicalGraph.count_nodes()ChemicalGraph.degrees()ChemicalGraph.edges_of_type()ChemicalGraph.from_dict()ChemicalGraph.label()ChemicalGraph.n_edgesChemicalGraph.n_nodesChemicalGraph.neighborhood()ChemicalGraph.neighbors()ChemicalGraph.node_id_of_compound()ChemicalGraph.node_id_of_smiles()ChemicalGraph.nodes_of_type()ChemicalGraph.pagerank()ChemicalGraph.shortest_path()ChemicalGraph.to_dict()ChemicalGraph.weighted_adjacency()
ChemicalLandscapeChemicalLandscape.build_all()ChemicalLandscape.build_fragments()ChemicalLandscape.build_scaffolds()ChemicalLandscape.build_similarity_graph()ChemicalLandscape.characterize()ChemicalLandscape.common_cores()ChemicalLandscape.compound_idsChemicalLandscape.decompose()ChemicalLandscape.enumerate()ChemicalLandscape.export_graphml()ChemicalLandscape.export_json()ChemicalLandscape.failuresChemicalLandscape.fingerprintsChemicalLandscape.from_store()ChemicalLandscape.graphChemicalLandscape.island_of()ChemicalLandscape.load()ChemicalLandscape.neighbors()ChemicalLandscape.node_of()ChemicalLandscape.path_between()ChemicalLandscape.plot()ChemicalLandscape.reassemble()ChemicalLandscape.reportChemicalLandscape.rgroups_at()ChemicalLandscape.save()ChemicalLandscape.smilesChemicalLandscape.swap_rgroup()
DiversityMetricsDiversityMetrics.chemical_coverageDiversityMetrics.compounds_per_scaffoldDiversityMetrics.fragment_coverageDiversityMetrics.fragment_entropyDiversityMetrics.fragment_entropy_normalizedDiversityMetrics.n_compoundsDiversityMetrics.n_fragmentsDiversityMetrics.n_murcko_scaffoldsDiversityMetrics.n_populated_scaffoldsDiversityMetrics.n_scaffold_nodesDiversityMetrics.scaffold_entropyDiversityMetrics.scaffold_entropy_normalizedDiversityMetrics.scaffold_giniDiversityMetrics.scaffold_levelsDiversityMetrics.scaffold_redundancyDiversityMetrics.singleton_scaffold_fractionDiversityMetrics.to_dict()DiversityMetrics.top_fragmentsDiversityMetrics.top_scaffolds
EdgeTypeFingerprintBlockFingerprintConfigFragmentConfigFragmentMethodFragmentResultGraphBuilderIslandResultLandscapeConfigLandscapeConfig.chunk_sizeLandscapeConfig.delimiterLandscapeConfig.fingerprintsLandscapeConfig.fragmentsLandscapeConfig.from_dict()LandscapeConfig.id_columnLandscapeConfig.limitLandscapeConfig.scaffoldsLandscapeConfig.similarityLandscapeConfig.smiles_columnLandscapeConfig.to_dict()LandscapeConfig.workers
NetworkMetricsNetworkMetrics.average_path_lengthNetworkMetrics.central_nodesNetworkMetrics.component_size_distributionNetworkMetrics.degree_histogramNetworkMetrics.densityNetworkMetrics.edge_type_countsNetworkMetrics.largest_component_fractionNetworkMetrics.largest_component_sizeNetworkMetrics.max_degreeNetworkMetrics.mean_degreeNetworkMetrics.median_degreeNetworkMetrics.n_componentsNetworkMetrics.n_edgesNetworkMetrics.n_nodesNetworkMetrics.n_singletonsNetworkMetrics.node_type_countsNetworkMetrics.path_length_exactNetworkMetrics.path_sample_pairsNetworkMetrics.to_dict()
NodeTypeRGroupDecompositionResultReverseFragmentRecordScaffoldConfigScaffoldNetworkResultSimilarityConfigapply_reversible_cut()attach_rgroup()build_similarity_edges()characterize()decompose_molecules()detect_islands()diversity_metrics()enumerate_core()export_graphml()export_json()fragment_cut_bonds()fragment_library()fragment_molecule()frontier_scaffolds()load_landscape()louvain_local_moving()minhash_signatures()morgan_packed()murcko_smiles()network_metrics()popcount_rows()popcount_words()reassemble_fragments()reversible_fragment_record()save_landscape()scaffold_network()shannon_entropy()shared_fragment_edges()stream_chunks()
- neurosnap.chemistry.smiles module