Infrastructure

This module contains various infrastructure classes used in the GB-BI library.

Controller Class

class illumination.infrastructure.Controller(config)

Bases: object

A utility class for printing, logging, and controlling the status of the algorithm.

The class provides methods for generating and displaying generation-specific statistics, as well as storing basic statistics and printing the archive to CSV files.

Attributes:

archive: An archive object containing elite molecules and associated data. surrogate: A surrogate model object used in the optimization process. generation: The current generation of the optimization algorithm. fitness_calls: The number of fitness function calls made so far. memory_of_molecules: A list to store molecules across generations. max_generations: The maximum number of generations for the optimization process. max_fitness_calls: The maximum number of fitness function calls allowed. remaining_fitness_calls: The remaining number of fitness function calls.

Methods:

__init__(config): Initializes a Controller object with the given configuration. set_archive(archive): Sets the archive object for the controller. active(): Checks if the optimization process is still active. update(): Updates the controller state and archives statistics. add_fitness_calls(fitness_calls): Adds to the total number of fitness function calls. write_statistics(statistics, metrics): Prints archive statistics to the console. store_statistics(statistics, metrics): Appends archive statistics to a CSV file. calculate_statistics(archive_data): Calculates various statistics from archive data. calculate_surrogate_metrics(molecules): Calculates surrogate model metrics. get_archive_data(): Retrieves elite molecule attributes and creates a DataFrame. store_molecules(): Stores all molecules in memory to a CSV file.

active() → bool

Checks if the optimization process is still active.

Returns:

bool: True if the process is active, False otherwise.

add_fitness_calls(fitness_calls: int) → None

Adds to the total number of fitness function calls.

Args:

fitness_calls: The number of fitness calls to add.

calculate_statistics(archive_data) → Dict

Calculates various statistics from the provided archive data.

Args:

archive_data: A DataFrame containing data about the elite molecules of the archive.

Returns:

Dict: A dictionary containing the calculated statistics.

calculate_surrogate_metrics(molecules: List[Molecule]) → Dict

Calculates metrics for the surrogate model based on the provided molecules.

Args:

molecules (List[Molecule]): A list of Molecule objects.

Returns:

Dict: A dictionary containing surrogate model metrics.

get_archive_data() → None

Retrieves elite molecule attributes and creates a DataFrame.

Returns:

pd.DataFrame: A DataFrame containing attributes of elite molecules.

set_archive(archive) → None

Sets the archive object for the controller.

Args:

archive: An archive object containing elite molecules and associated data.

store_molecules() → None

Stores all molecules in memory to a CSV file.

store_statistics(statistics: DataFrame, metrics: DataFrame) → None

Appends basic archive statistics to a CSV file saved to disk.

Args:

statistics: A DataFrame containing various archive and quality-diversity metrics. metrics: A DataFrame containing surrogate model metrics.

update() → None

Updates the controller state and archives statistics.

This includes generating and printing statistics for the current generation, writing archive data to a CSV file, and appending basic statistics to another CSV file.

write_statistics(statistics: DataFrame, metrics: DataFrame) → None

Prints statistics about the archive to the console.

Args:

statistics: A DataFrame containing various archive and quality-diversity metrics. metrics: A DataFrame containing surrogate model metrics.

Archive Class

class illumination.infrastructure.Archive(config, archive_dimensions: int)

Bases: object

A composite class containing the current elite molecules in a CVT tree structure.

This class allows for processing new molecules, sampling existing elite molecules, and storing the current state of the archive on disk. The CVT centers are either loaded from or saved to cache disk storage.

Attributes:

archive_size: The size of the archive. archive_accuracy: The accuracy setting for the archive. archive_dimensions: The dimensionality of the archive. cache_string: The string for cache file naming. cvt_location: The location path for the CVT cache file. cvt_centers: The centers of the CVT clusters. cvt: A KDTree structure for CVT centers. elites: A list of Elite objects representing the archive. incoming_molecules: A list to store incoming molecules.

Methods:

__init__(config, archive_dimensions): Initializes the Archive with the given configuration and dimensions. cvt_index(descriptor): Returns the CVT index for the niche nearest to the given descriptor. update_niche_index(molecule): Calculates and stores the niche index of a molecule in the molecule object. add_to_archive(molecules): Adds molecules to the archive, keeping only the most fit molecule per niche. sample(size): Returns a list of elite molecules of the requested size, weighted by fitness. sample_pairs(size): Returns a list of pairs of elite molecules of the requested size, weighted by fitness.

add_to_archive(molecules: List[Molecule]) → None

Adds molecules to the archive, keeping only the most fit molecule per niche.

Args:

molecules: A list of molecules to be added to the archive.

cvt_index(descriptor: List[float]) → int

Returns the CVT index for the niche nearest to the given descriptor.

Args:

descriptor: A list of descriptor values for the molecule.

Returns:

int: The CVT index for the nearest niche.

sample(size: int) → List[Mol]

Returns a list of elite molecules of the requested size, weighted by fitness.

Args:

size: The number of elite molecules to sample.

Returns:

List[Chem.Mol]: A list of sampled elite molecules.

sample_pairs(size: int) → List[Tuple[Mol, Mol]]

Returns a list of pairs of elite molecules of the requested size, weighted by fitness.

Args:

size: The number of pairs of elite molecules to sample.

Returns:

List[Tuple[Chem.Mol, Chem.Mol]]: A list of sampled pairs of elite molecules.

update_niche_index(molecule: Molecule) → Molecule

Calculates and stores the niche index of a molecule in the molecule object.

Args:

molecule: The molecule for which to calculate the niche index.

Returns:

Molecule: The updated molecule with the niche index set.

Arbiter Class

class illumination.infrastructure.Arbiter(config)

Bases: object

A catalog class containing different drug-like filters for small molecules.

This class includes the option to run structural filters from ChEMBL.

Attributes:

cache_smiles: A list to store SMILES strings of molecules for duplication checks. rules_dict: A DataFrame containing filter rules loaded from a CSV file. rules_list: A list of SMARTS strings for the filter rules. tolerance_list: A list of tolerance values for the filter rules. pattern_list: A list of RDKit molecule patterns for the filter rules.

Methods:

__init__(arbiter_config): Initializes the Arbiter with the given configuration. __call__(molecules): Applies the chosen filters to a list of molecules and removes duplicates. unique_molecules(molecules): Checks if a molecule in a list of molecules is duplicated. molecule_filter(molecular_graph): Checks if a given molecular structure passes through the chosen filters. toxicity(molecular_graph): Checks if a given molecule fails the structural filters. hologenicity(molecular_graph): Checks if a given molecule fails the hologenicity filters. ring_infraction(molecular_graph): Checks if a given molecule fails the ring infraction filters. veber_infraction(molecular_graph): Checks if a given molecule fails the veber infraction filters.

static hologenicity(molecular_graph: Mol) → bool

Checks if a given molecule fails the hologenicity filters.

Args:

molecular_graph: The molecular graph to be checked.

Returns:

bool: True if the molecule fails the hologenicity filters, False otherwise.

molecule_filter(molecular_graph: Mol) → bool

Checks if a given molecular structure passes through the chosen filters (hologenicity, veber infractions, ChEMBL structural alerts, etc.).

Args:

molecular_graph: The molecular graph to be checked.

Returns:

bool: True if the molecule passes all filters, False otherwise.

static ring_infraction(molecular_graph: Mol) → bool

Checks if a given molecule fails the ring infraction filters.

Args:

molecular_graph: The molecular graph to be checked.

Returns:

bool: True if the molecule fails the ring infraction filters, False otherwise.

toxicity(molecular_graph: Mol) → bool

Checks if a given molecule fails the structural filters.

Args:

molecular_graph: The molecular graph to be checked.

Returns:

bool: True if the molecule fails the structural filters, False otherwise.

unique_molecules(molecules: List[Molecule]) → List[Molecule]

Checks if a molecule in a list of molecules is duplicated, either in this batch or before.

Args:

molecules: A list of molecules to check for duplicates.

Returns:

List[Molecule]: A list of unique molecules.

static veber_infraction(molecular_graph: Mol) → bool

Checks if a given molecule fails the veber infraction filters.

Args:

molecular_graph: The molecular graph to be checked.

Returns:

bool: True if the molecule fails the veber infraction filters, False otherwise.