Usage

Command-line Interface

jazzy

Command line interface of Jazzy.

jazzy [OPTIONS] COMMAND [ARGS]...

vec

Calculate molecular descriptors.

jazzy vec [OPTIONS] SMILES

Options

--opt <opt>: Optimisation method (None, MMFF94, MMFF94s, or UFF).

--strength_only

Arguments

SMILES: Required argument

vis

Create SVG image.

jazzy vis [OPTIONS] SMILES

Options

--opt <opt>: Optimisation method (None, MMFF94, MMFF94s, or UFF).

--fig_size <fig_size>

Size of SVG image in pixels.

Default:: 500, 500

--sdc_threshold <sdc_threshold>

Treshold strength to depic Carbon donors.

Default:: 0.0

--sdx_threshold <sdx_threshold>

Treshold strength to depic non-Carbon donors.

Default:: 0.0

--sa_threshold <sa_threshold>

Treshold strength to depic acceptors.

Default:: 0.0

--base64

--flatten_molecule

--highlight_atoms

--ignore_sdc

--ignore_sdx

--ignore_sa

Arguments

SMILES: Required argument

Modules

API

Application programming interface for the jazzy package.

jazzy.api.atomic_map_from_smiles(smiles, minimisation_method=None, **kwargs)

API route to generate a condensed representation on the atomic map.

Recommended if serialization is needed.

Parameters:

smiles (str) – A molecule SMILES string representation (default ‘’)
minimisation_method –
One of the conformer energy minimisation methods as available in RDKit (available is ‘MMFF94’, ‘MMFF94s’, or ‘UFF’)

(default None)
kwargs – Keyword arguments

Keyword Arguments:

embedding_type – Molecule embedding method (available as ‘2D’ or ‘3D’) (default ‘3D’)
embedding_seed – Integer seed for the embedding process (default 11)
embedding_max_iterations – Maximum number of iterations for the embedding

Returns:

Condensed representation of the atomic map.

jazzy.api.atomic_strength_vis_from_smiles(smiles, minimisation_method=None, encode=False, fig_size=(500, 500), flatten_molecule=False, highlight_atoms=False, ignore_sdc=False, ignore_sdx=False, ignore_sa=False, sdc_threshold=0.0, sdx_threshold=0.0, sa_threshold=0.0, rounding_digits=4, **kwargs)

API route to generate an SVG image from SMILES string.

Parameters:

smiles (str) – A molecule SMILES string representation (default ‘’)
minimisation_method –
One of the conformer energy minimisation methods as available in RDKit (available is ‘MMFF94’, ‘MMFF94s’, or ‘UFF’)

(default None)
encode – If True, returns the base64-encoded SVG image (default False)
fig_size – Tuple representing the size of the generated image (default (500, 500))
flatten_molecule – If True, flattens the molecule (default False)
highlight_atoms – If True, highlights the atoms (default False)
ignore_sa – Ignore acceptor contributions (default False)
ignore_sdc – Ignore Carbon-donor contributions (default False)
ignore_sdx – Ignore Heteroatom-donor contributions (default False)
rounding_digits – Number of digits to round the strengths
sa_threshold – Acceptor threshold (default 0.0)
sdc_threshold – Carbon-donor threshold (default 0.0)
sdx_threshold – Heteroatom-donor threshold (default 0.0)
kwargs – Keyword arguments

Keyword Arguments:

embedding_type – Molecule embedding method (available as ‘2D’ or ‘3D’) (default ‘3D’)
embedding_seed – Integer seed for the embedding process (default 11)
embedding_max_iterations – Maximum number of iterations for the embedding

Returns:

SVG image either 2D or 3D.

jazzy.api.atomic_tuples_from_smiles(smiles, minimisation_method=None, **kwargs)

API route to generate a tuple representation on the atomic map.

Not recommended if serialization is needed.

Parameters:

smiles (str) – A molecule SMILES string representation (default ‘’)
minimisation_method –
One of the conformer energy minimisation methods as available in RDKit (available is ‘MMFF94’, ‘MMFF94s’, or ‘UFF’)

(default None)
kwargs – Keyword arguments

Keyword Arguments:

embedding_type – Molecule embedding method (available as ‘2D’ or ‘3D’) (default ‘3D’)
embedding_seed – Integer seed for the embedding process (default 11)
embedding_max_iterations – Maximum number of iterations for the embedding

Returns:

Tuple representation of the atomic map.

jazzy.api.deltag_from_smiles(smiles, minimisation_method=None, **kwargs)

API route to calculate molecular free energy scalar.

Parameters:

smiles (str) – A molecule SMILES string representation (default ‘’)
minimisation_method –
One of the conformer energy minimisation methods as available in RDKit (available is ‘MMFF94’, ‘MMFF94s’, or ‘UFF’)

(default None)
kwargs – Keyword arguments

Keyword Arguments:

embedding_type – Molecule embedding method (available as ‘2D’ or ‘3D’) (default ‘3D’)
embedding_seed – Integer seed for the embedding process (default 11)
embedding_max_iterations – Maximum number of iterations for the embedding

Returns:

Free energy as scalar rounded

jazzy.api.molecular_vector_from_smiles(smiles, minimisation_method=None, only_strengths=False, **kwargs)

API route to calculate molecular free energy vector.

Calculates the apolar (dga), the polar (dgp), and the interaction (dgi) contribution to the free energy.

Parameters:

smiles (str) – A molecule SMILES string representation (default ‘’)
minimisation_method –
One of the conformer energy minimisation methods as available in RDKit (available as ‘MMFF94’, ‘MMFF94s’, or ‘UFF’)

(default None)
only_strengths – Boolean value that determines wheather to calculate only strengts or even more
kwargs – Keyword arguments

Keyword Arguments:

embedding_type – Molecule embedding method (available as ‘2D’ or ‘3D’) (default ‘3D’)
embedding_seed – Integer seed for the embedding process (default 11)
embedding_max_iterations – Maximum number of iterations for the embedding

Returns:

Molecular strength vector with or without free energy contributions

Core

Core functions of the jazzy package.

jazzy.core.any_hydrogen_neighbors(rdkit_atom)

Returns True is Hydrogen is a neighbor else False.

Written because rdkit.Chem.rdchem.Atom.GetTotalHs() does not work on embedded molecules.

Parameters:: rdkit_atom (Atom) – rdkit.Chem.rdchem.Atom object
Returns:: Boolean

jazzy.core.calculate_delta_apolar(rdkit_molecule, mol_map, g0, gs, gr, gpi1, gpi2)

Calculate apolar free energy contribution.

Calculate the apolar contribution to the free energy. Equation 7-8 - parameter names are adapted.

Parameters:

rdkit_molecule (Mol) – RDKit molecule
mol_map (dict) – molecular map of polar properties
g0 (float) – zeroth order parameter
gs (float) – surface parameter
gr (float) – ring parameter
gpi1 (float) – first pi parameter
gpi2 (float) – second pi parameter

Returns:

Apolar free energy contribution (float)

Return type:

float

jazzy.core.calculate_delta_interaction(rdkit_molecule, mol_map, atoms_and_nbrs, gi, expa, f)

Calculate interaction contribution to free energy.

Calculate the interation contribution to the free energy. Equation 15 - parameter names adapted.

Parameters:

rdkit_molecule (Mol) – RDKit molecule
mol_map (dict) – molecular map of polar properties as obtained by
atoms_and_nbrs (list) – list of lists of atoms and their bonded atoms
gi (float) – interaction parameter
expa (float) – exponent hydrogen bond acceptor
f (float) – correction parameter

Returns:

Interaction free energy contribution (float)

jazzy.core.calculate_delta_polar(mol_map, atoms_and_nbrs, gd, ga, expd, expa)

Calculate polar contribution to free energy.

Calculate the polar contribution to the free energy. Equation 14 - parameter names adapted.

Parameters:

mol_map (dict) – molecular map of polar properties as obtained by the calculate_polar_strength_map() function
atoms_and_nbrs (list) – list of lists of atoms and their bonded atoms
gd (float) – hydrogen bond donor parameter
ga (float) – hydrogen bond acceptor parameter
expd (float) – exponent for hydrogen bond donor
expa (float) – exponent for hydrogen bond acceptor

Returns:

Polar free energy contribution (float)

Raises:

NegativeLonePairsError – if the input compound contains atoms with negative number of lone pairs (lone pairs < 0)

Return type:

float

jazzy.core.calculate_polar_strength_map(rdkit_molecule, kallisto_molecule, atoms_and_nbrs, charges, d=6.1475, a=-2.2316, t=0.274)

Calculate the polar strength map.

Generates a molecular dictionary where keys correspond to atom indices, and values are dictionaries of calculated properties. These properties include polar acceptor strength (sa), polar donor strength of Hydrogens bonded to Carbon (sdc) or other non-Hydrogen atoms (sdx), number of lone pairs (num_lp), atomic number (z), and formal charge (q).

Parameters:

rdkit_molecule (Mol) – RDKit molecule
kallisto_molecule (Molecule) – kallisto molecule
atoms_and_nbrs (list) – list of lists of atoms and their bonded atoms
charges (list) – list of atomic partial charges
d – parameter that ensures that the donor strength (sdx) of Hydrogen in H2O is equal to 1.000
a – parameter that ensures that the acceptor strength (sa) of one lone pair on Oxygen in H2O is equal to 1.000
t – bond reduction factor (fixed to ensure conditions above)

Returns:

Map of molecular polar properties (plus some extras)

Return type:

dict

jazzy.core.calculate_q_and_delta_q(atom_idx, atoms_and_nbrs, charges, t=0.274)

Calculates charge and delta charge.

Suitable for both donor and acceptor strength calculations.

Parameters:

atom_idx (int) –
atoms_and_nbrs (list) –
charges (list) –

jazzy.core.get_acceptor_atom_strength(atom_idx, atoms_and_nbrs, charges, a=-4.4362, t=0.274)

Acceptor strength calculation - equation 12 and 13.

Parameters:

atom_idx (int) –
atoms_and_nbrs (list) –
charges (list) –

Return type:

float

jazzy.core.get_all_neighbours(rdkit_molecule, molecule_covalent_nbrs)

Get all alpha, beta, and gamma neighbours.

Create dictionaries for covalent bonding partner (alpha), all nearest neighbours (beta), and nearest-nearest (gamma) neighbours. Every dictionary contains the atomic index within the molecule as key and a list of neighbours as the value.

Parameters:

rdkit_molecule (Mol) – RDKit molecule
molecule_covalent_nbrs (list) – List of lists containing covalent neighbours

Returns:

Dictionaries for alpha, beta, and gamma neighbours

jazzy.core.get_atom_and_nbrs_idxs_dict(atom_idx, molecule_covalent_nbrs)

Get all neighbours for atom_idx.

Extract all covalent bonding partner (alpha), all nearest neighbours (beta), and all nearest-nearest neighbours (gamma) for atom with index ‘atom_idx’.

Parameters:

atom_idx (int) – index of atom to extract neighbours for
molecule_covalent_nbrs (list) – List of lists containing covalent neighbours

Returns:

list of all covalent bonding atom indices of atom_idx beta: list of nearest neighbour atom indices of atom_idx gamma: list of nearest-nearest neighbour atom indices of atom_idx

Return type:

alpha

jazzy.core.get_charges_from_atom_list(atom_idxs, charges)

List-based function for charge retrieval.

Parameters:

atom_idxs (list) –
charges (list) –

Return type:

list

jazzy.core.get_charges_from_kallisto_molecule(kallisto_molecule, charge)

Calculate electronegativity equilibration (EEQ) atomic partial charges.

Parameters:

kallisto_molecule (Molecule) – kallisto molecule
charge (int) – molecular charge (int)

Returns:

List of electronegativity equilibration atomic partial charges

Raises:

KallistoError – If ‘charges’ contains any NaNs.

Return type:

list

jazzy.core.get_covalent_atom_idxs(rdkit_molecule)

Get covalent indices for atom_idx.

Creates a list of lists, where indices are atom indices and the content of the lists are indices of binding atoms (e.g., [[1],[0]] means that atom 0 is bound to atom 1 ([1]) and vice versa ([0]).

Parameters:: rdkit_molecule (Mol) –
Return type:: list

jazzy.core.get_donor_atom_strength(atom_idx, atoms_and_nbrs, charges, d=63.7, t=0.274)

Donor strength calculation - equation 10.

Parameters:

atom_idx (int) –
atoms_and_nbrs (list) –
charges (list) –

Return type:

float

jazzy.core.get_lone_pairs(atom)

Get the number of lone pairs for an atom.

The method is similar to that in https://github.com/rdkit/blob/master/Code/GraphMol/Aromaticity.cpp with the exception that it calculates the explicit valence via atom functions (not PeriodicTable). This is because the original method produces miscalculations for some systems (e.g., in molecules with SO2 groups).

Return type:: int

jazzy.core.interaction_strength(idx, mol_map, acceptor_exp)

Calculate interaction strength for atom with index idx.

Parameters:

idx (int) –
mol_map (dict) –
acceptor_exp (float) –

Return type:

float

jazzy.core.kallisto_molecule_from_rdkit_molecule(rdkit_molecule)

Create a kallisto molecule from RDKit molecule.

Parameters:: rdkit_molecule (Mol) – RDKit molecule
Returns:: A kallisto molecule (kallisto.molecule.Molecule)
Raises:: KallistoError – An error if the kallisto molecule cannot be created
Return type:: Molecule

jazzy.core.rdkit_molecule_from_smiles(smiles, minimisation_method=None, **kwargs)

Molecule preparation: Parse SMILES, add hydrogens, and does energy minimisation.

Parameters:

smiles (str) – A molecule SMILES string representation (default ‘’)
minimisation_method – One of the conformer energy minimisation methods as available in RDKit (available is ‘MMFF94’, ‘MMFF94s’, or ‘UFF’) (default None)
kwargs – Keyword arguments

Keyword Arguments:

embedding_type – Molecule embedding method (available as ‘2D’ or ‘3D’) (default ‘3D’)
embedding_seed – Integer seed for the embedding process (default 11)
embedding_max_iterations – Maximum number of iterations for the embedding

Returns:

An RDKit molecule (rdkit.Chem.rdchem.Mol) or None if the process fails

Return type:

Mol | None

Visualisation

RDKit functions to convert Jazzy data into rendering.

jazzy.visualisation.depict_strengths(rdkit_molecule, atomic_map, fig_size=(500, 500), flatten_molecule=False, highlight_atoms=False, ignore_sdc=False, ignore_sdx=False, ignore_sa=False, sdc_threshold=0.0, sdx_threshold=0.0, sa_threshold=0.0, rounding_digits=4)

Create an SVG image text from an RDKit molecule and its atomic map.

The default configuration simply produces a depiction of the input molecule and its strengths. highlight_atoms highlights atoms in red (donors) and blue (acceptors). flatten_molecule produces a 2-dimensional depiction of the molecule. Any threshold parameter allows to set a numeric threshold under which strengths are not included in the output depiction.

Parameters:

rdkit_molecule (Mol) – An RDKit molecule (rdkit.Chem.rdchem.Mol)
atomic_map (dict) – Molecular map of polar properties (dict)
fig_size – Size of the depiction in pixels (tuple)
flatten_molecule – Boolean to create 2D depiction (bool)
highlight_atoms – Show donors in red and acceptors in blue (bool)
ignore_sdc – Ignore donor contributions on Carbon (bool)
ignore_sdx – Ignore donor contributions on non-Carbon (bool)
ignore_sa – Ignore acceptor contributions (bool)
sdc_threshold – Threshold to show donor contribution on Carbon (float)
sdx_threshold – Threshold to show donor contribution on non-Carbon (float)
sa_threshold – Threshold to show acceptor contribution (float)
rounding_digits – Rounding digits (int)

Returns:

SVG depiction of given RDKit molecule and its atomic strength map.