CIDER package

Submodules

CIDER.cider module

MIT License.

Copyright (c) 2022 Hannah Busch, Jonas Schaub, Otto Brinkhaus, Kohulan Rajan, and Christoph Steinbeck

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

class CIDER.cider.ChemicalDatasetComparator

Bases: object

Wrapper class around all Cider functionalities.

ChemIcal DatasEt comparatoR (CIDER) is a Python package and ready-to-use Jupyter Notebook workflow which primarily utilizes RDKit to compare two or more chemical structure datasets (SD files) in different aspects, e.g. size, overlap, molecular descriptor distributions, chemical space clustering, etc., most of which can be visually inspected.

chemical_space_visualization(all_dicts, fp_radius=2, fp_bits=512, dimension_reduction='pca', interactive=True)

This function returns a 2D visualization of the chemical space of the.

molecules in all datasets using the chemplot module. On basis of the calculated identifier (self.identifier_keyname) for every molecule a Extended Connectivity Fingerprint (ECFP) will be calculated with a definable fingerprint radius (fp_radius) and length (fp_size). Subsequent, the fingerprints are reduced to 2D for plotting. The dimension reduction can be done with PCA, UMAP or t-SNE and the plot can be interactive.

Args:

all_dicts (dict): Dictionary with subdictionaries including an identifier list (self.identifier_keyname). fp_radius (int): Radius of the Extended Connectivity Fingerprints (default: 2). fp_bits (int): Size of the Extended Connectivity Fingerprints (default: 2048). dimension_reduction (str): Method of dimension reduction (default: pca). interactive (bool): Creating an interactive plot or not (default: True).

Raises:

KeyError: if the identifier list is missing. ValueError: if the dimension reduction is not pca, tsne or umap.

Returns:

Chemical space visualization

descriptor_counts_and_plot(all_dicts, descriptor_list_keyname, width_of_bins=10.0, data_type='png', save_dataframe=True, figsize=[15.0, 7.0], fontsize_tick_labels=15, fontsize_legend=15, fontsize_ylabel=20, fontsize_xlabel=20, fontsize_title=24)

This function updates the subdictionaries in the given dictionary with.

the binned descriptor values for a given descriptor value list. The values can either be continuous (binning with _get_continuous_descriptor_counts and plotted with _continuous_descriptor_plot) or discrete (binning with _get_discrete_descriptor_counts and plotted with _discrete_descriptor_plot). The created plots are saved in an output folder and the data frame can also be exported as CSV.

Return type:

Figure

Args:

all_dicts (dict): Dictionary with subdictionaries including a descriptor value list. descriptor_list_keyname (str): Name of the descriptor list for binning and plotting. width_of_bins (int, optional): interval size for the bins for continuous values (default: 10). data_type (str): Data type for the exported image (default: png). save_dataframe (bool): Export dataframe as csv file or not (default: True). figsize (float, float): Width, height of the image in inches (default: 15, 7). fontsize_tick_labels (int): Fontsize of the labels on the ticks of the axis (default: 15). fontsize_legend (int): Fontsize of the legend (default: 15). fontsize_ylabel (int): Fontsize of the label of the y-axis (default: 20). fontsize_xlabel (int): Fontsize of the label of the x-axis (default: 20). fontsize_title (int): Fontsize of the title (default: 24).

Raises:

KeyError: if there is not the needed descriptor list. ValueError: if the descriptor values are not int or float and can therefore not be plotted.

Returns:

fig (matplotlib.figure): Plot

draw_molecules(all_dicts, number_of_mols=10, mols_per_row=5, image_size=200, data_type='png', figsize=[20.0, 20.0], fontsize_title=24, fontsize_subtitle=20)

This function creates an grid image of the first molecules of each.

dataset and exports the image to an output folder.

Return type:

Figure

Args:

all_dicts (dict): Dictionary with subdictionaries for every dataset, including the key ‘self.import_keyname’. number_of_mols (int): number of molecules form each dataset that will be displayed (default: 12). mols_per_row (int): number of molecules per row in the grid (default: 3). image_size (int): the size of the image for a single molecule (default: 200). data_type (str): data type for the exported files (e.g. png, jpg, pdf, default: png). figsize (float, float): Width, height of the figure in inches (default: 20, 20) fontsize_title (int): Fontsize of the title (default: 24). fontsize_subtitle (int): Fontsize of the subtitles (default: 20).

Returns:

fig (matplotlib.figure): grid image of molecules

draw_most_frequent_scaffolds(all_dicts, number_of_structures=5, structures_per_row=5, image_size=200, framework=False, graph_framework=False, normalize=True, data_type='png', figsize=[20.0, 20.0], fontsize_title=24, fontsize_subtitle=20)

This function creates a grid images of a chosen number of scaffolds/.

frameworks/graph framework for every subdictionary in the given dictionary and shows them together. The scaffolds/frameworks/graph framework in each gird image are sorted by their frequency. The relative or absolute number of occurrence of a scaffold/framework/graph framework in the dataset of the respective subdictionary is shown below each image.

Return type:

Figure

args:

all_dicts (dict): Dictionary with subdictionaries including the key ‘self.import_keyname’. number_of_scaffolds (int): Number of scaffolds displayed in the grid images (default: 5). scaffolds_per_row (int): Number of scaffolds in every row of the grid image (default: 5). image_size (int): Size of the image for a single molecule (default: 200). framework (bool): Remove terminal atoms with double bond (default: False). graph_framework (bool): Creating graph framework (default: False). normalize (bool): Using relative numbers for scaffold analysis (default: True). data_type (str): Data type for the exported image (default: png). figsize (float, float): Width, height of the image in inches (default: 20, 20) fontsize_title (int): Fontsize of the title (default: 24). fontsize_subtitle (int): Fontsize of the subtitles (default: 20).

returns:

fig (PIL.PngImageFile): Grid images with most frequent scaffolds/ frameworks/graph framework for each subdictionary.

exception_handler(exc_value, exc_tb)

This function is a callable exception handler when NOT working in.

IPython. It logs the exception including the traceback into the log file.

Args:

exc_type: Type of the exception. exc_value: Value of the exception. exc_tb: Tracback of the exception. tb_offset: Traceback offset.

exception_handler_IP(exc_type, exc_value, exc_tb, tb_offset=None)

This function is a callable exception handler when working in IPython.

It logs the exception including the traceback into the log file.

Args:

exc_type: Type of the exception. exc_value: Value of the exception. exc_tb: Traceback of the exception. tb_offset: Traceback offset.

export_figure_report(all_dicts)

This function exports a pdf including some general information and all.

created figures form the figures subdictionary.

Return type:

None

Args:

all_dicts (dict): Dictionary with subdictionary ‘self. figure_dict_keyname’ containing all created plots

export_single_dict_values(all_dicts)

This function exports only the (not-binned) descriptor values for each.

dictionary according to the imported SDFile as a single csv file in the output folder.

Return type:

None

Args:

all_dicts (dict): Dictionary with subdictionaries containing the calculated descriptor values.

get_database_id(all_dicts, id_name)

This function updates subdictionaries of a given dictionary with a list.

of database IDs for the single molecules as new key-value pairs. Depending on which database the molecules are coming from, the key as a class variable can be changed accordingly. (To get the database ID the rdkit_mol Objects (rdkit.Chem.rdmol.Mol or rdkit.Chem.rdmolfiles.SDMolSupplier) needs to be parsed, this may take same time because no parsed molecules are saved in the dictionary to save memory.)

Return type:

None

Args:

all_dicts (dict): Dictionary with subdictionaries for every dataset, including the key ‘self.import_keyname’. id_name (str): ID name in the original SDFile.

get_descriptor_list_key(all_dicts, descriptor, descriptor_list_keyname)

This function updates the subdictionaries in the given dictionary with.

a list of descriptor values as a new key-value pair using _get_descriptor_list on the rdkit_mol Objects (rdkit.Chem.rdmol.Mol or rdkit.Chem.rdmolfiles.SDMolSupplier) in the subdictionaries.

Return type:

None

Args:

all_dicts (dict): Dictionary with subdictionaries for every dataset, including the key ‘self.import_keyname’. descriptor (callable): RDKit method that returns a molecular descriptor for a given molecule descriptor_list_keyname (str): Key name for the dictionary entry (should match the descriptor)

get_duplicate_key(all_dicts)

This function updates the subdictionaries in the given dictionary with.

the number of duplicates in the identifier list as a new key-value-Pair (key: self.duplicates_keyname), a list of the duplicated identifier (key: self.duplicates_id_keyname) and a list of the indices of the duplicates in the rdkit_mol Object (key self.duplicates_index_keyname).

Return type:

None

Args:

all_dicts (dict): Dictionary with subdictionaries including a list of identifiers (self.identifier_keyname).

Raises:

KeyError: if there is no identifier list.

get_identifier_list_key(all_dicts, id_type='inchi')

This function updates the subdictionaries in the given dictionary.

(created with the import_as_data_dict function) with a list of identifiers (InChI, InChIKey, canonical SMILES strings) as a new key-value pair using _get_identifier_list on the rdkit_mol Objects (rdkit.Chem.rdmol.Mol or rdkit.Chem.rdmolfiles.SDMolSupplier). The key self.identifier_keyname (class variable) can be changed.

Return type:

None

Args:

all_dicts (dict): Dictionary with subdictionaries for every dataset, including the key ‘self.import_keyname’. id_type (str): Type of Identifier (“inchi”, “inchikey” or “smiles”)

get_lipinski_key(all_dicts)

This function updates the subdictionaries in the given dictionary with.

the list of the number of broken Lipinski Rules for every molecule (lipinski_list_keyname) and a summary of the broken rules (lipinski_summary_keyname) using _test_for_lipinski.

Return type:

None

Args:

all_dicts (dict): Dictionary with subdictionaries including the key ‘self.import_keyname’.

get_number_of_molecules(all_dicts)

This function updates the subdictionaries in the given dictionary.

(created from import_as_data_dict function) with the number of molecules in every dataset as new key-value pair. The key is the class variable ‘cider.dataset_length_keyname’.

Return type:

None

Args:

all_dicts (dict): Dictionary with subdictionaries for every dataset, including the key ‘self.import_keyname’.

get_shared_molecules_key(all_dicts)

This function updates the subdictionaries in the given dictionary.

(created with the import_as_data_dict function) with the number of molecules that can be found in all of the given datasets (key: self.shared_mols_keyname) and an identifier list of these molecules (key: self.shared_mols_id_keyname) as two new key-value pairs (number of compared datasets can be any number). The comparison of the molecules is based on the identifiers (string representation), not the rdkit_mol Object (rdkit.Chem.rdmol.Mol or rdkit.Chem.rdmolfiles.SDMolSupplier).

Return type:

None

Args:

all_dicts (dict): Dictionary with subdictionaries including a lists of identifiers (self.identifier_keyname).

Raises:

KeyError: if there is no identifier list. ValueError: if there is only one dataset.

import_as_data_dict(path_to_data)

This function creates a dictionary with the names of the imported file.

as keys. The values of each of these keys is a subdictionary. The first entry of every subdictionary is self.import_keyname (class variable, can be changed) as key and rdkit_mol_objects (either a rdkit.Chem. rdmolfiles.SDMolSupplier Object or a list of rdkit.Chem.rdchem.mol Objects) of the SDFile as value. To find faulty molecules every entry of the rdkit_mol_objects will be parsed once. (Parsed molecules will not be stored in the dictionary to save memory.)

Return type:

Dict

Args:

path_to_data (str): Path to the directory where the SDFiles are stored.

Returns:

all_dicts (dict): Dictionary with subdictionaries for every dataset, including the key ‘self.import_keyname’.

Raises:

FileNotFoundError: if the data path is invalid. KeyError: if no SDFiles are in the given directory.

import_smi_as_data_dict(path_to_data)

This function creates a dictionary with the names of the imported file.

as keys. The values of each of these keys is a subdictionary. The first entry of every subdictionary is self.import_keyname (class variable, can be changed) as key and rdkit_mol Objects (list of rdkit.Chem.rdchem. mol objects) of the SMI File as value. To find faulty molecules, every entry of the rdkit_mol Objects will be parsed once. (Parsed molecules will not be stored in the dictionary to save memory.)

Args:

path_to_data (str): Path to the directory where the SMI Files are stored.

Returns:

all_dicts (dict): Dictionary with subdictionaries for every dataset, including the key ‘self.import_keyname’.

Raises:

FileNotFoundError: if the data path is invalid. KeyError: if no SMI Files are in the given directory.

lipinski_plot(all_dicts, data_type='png', save_dataframe=True, figsize=[15.0, 7.0], fontsize_tick_labels=15, fontsize_legend=15, fontsize_ylabel=20, fontsize_xlabel=20, fontsize_title=24)

This function returns a bar plot for the number of molecules in every.

subdictionary breaking 0 to 4 Lipinski rules using the ‘lipinski_summary’ key in the given dictionary. The plot is saved in an output folder (data type can be chosen) and the created data frame can also be exported as CSV.

Return type:

Figure

args:

all_dicts (dict): Dictionary with subdictionaries including the key ‘self.lipinski_summary_keyname’. data_type (str): Data type for the exported image (default: png). save_dataframe (bool): Export dataframe as csv or not (default: True). fig_size (float, float): Width, height of the image in inches (default: 15, 7). fontsize_tick_labels (int): Fontsize of the labels on the ticks of the axis (default: 15). fontsize_legend (int): Fontsize of the legend (default: 15). fontsize_ylabel (int): Fontsize of the label of the y-axis (default: 20). fontsize_xlabel (int): Fontsize of the label of the x-axis (default: 20). fontsize_title (int): Fontsize of the title (default: 24).

Raises:

KeyError: if the Lipinski key is missing and therefore no plot can be generated.

Returns:

fig (matplotlib.figure.Figure): Plot

logger = <Logger CIDER (INFO)>

now = '2024-03-08 20-06-50'

visualize_intersection(all_dicts, data_type='png')

This function returns a Venn diagram of the intersection between the.

molecules in the subdictionaries of the given dictionary. Every subdictionary is represented as a circle and the overlaps between the circles indicate the molecules present in more than one subdictionary. (The function only works with two or three subdictionaries.) The intersection is based on the identifiers (string representation). The diagram is saved in an output folder.

Return type:

Figure

Args:

all_dicts (dict): Dictionary of dictionaries with identifier_keyname. data_type (str): Data type for the exported image (default: png).

Returns:

fig (matplotlib.figure): Venn diagram

Raises:

ValueError: If there is only one or more than three sets to be compared. KeyError: If there is no identifier list.

Module contents

CIDER Python Package.

e.g. size, overlap, molecular descriptor distributions, chemical space clustering, etc., most of which can be visually inspected in the notebook.