diff --git a/.gitignore b/.gitignore index 733bbf9e..f9cb175a 100644 --- a/.gitignore +++ b/.gitignore @@ -161,6 +161,7 @@ cython_debug/ #.idea/ # configs/ # commented as new configs can be added as a part of a feature + /.idea /data /logs diff --git a/chebai/__init__.py b/chebai/__init__.py index 81185395..9f508aaa 100644 --- a/chebai/__init__.py +++ b/chebai/__init__.py @@ -1,10 +1,30 @@ import os +from typing import Any import torch +# Get the absolute path of the current file's directory MODULE_PATH = os.path.abspath(os.path.dirname(__file__)) class CustomTensor(torch.Tensor): - def __new__(cls, data): + """ + A custom tensor class inheriting from `torch.Tensor`. + + This class allows for the creation of tensors using the provided data. + + Attributes: + data (Any): The data to be converted into a tensor. + """ + + def __new__(cls, data: Any) -> "CustomTensor": + """ + Creates a new instance of CustomTensor. + + Args: + data (Any): The data to be converted into a tensor. + + Returns: + CustomTensor: A tensor containing the provided data. + """ return torch.tensor(data) diff --git a/chebai/__main__.py b/chebai/__main__.py index cc0f2f34..0afee8ed 100644 --- a/chebai/__main__.py +++ b/chebai/__main__.py @@ -1,4 +1,10 @@ from chebai.cli import cli if __name__ == "__main__": + """ + Entry point for the CLI application. + + This script calls the `cli` function from the `chebai.cli` module + when executed as the main program. + """ cli() diff --git a/chebai/callbacks.py b/chebai/callbacks.py index af306ccb..764db443 100644 --- a/chebai/callbacks.py +++ b/chebai/callbacks.py @@ -1,31 +1,76 @@ import json import os +from typing import Any, Dict, List, Literal, Union import torch from lightning.pytorch.callbacks import BasePredictionWriter class ChebaiPredictionWriter(BasePredictionWriter): - def __init__(self, output_dir, write_interval, target_file="predictions.json"): + """ + A custom prediction writer for saving batch and epoch predictions during model training. + + This class inherits from `BasePredictionWriter` and is designed to save predictions + in a specified output directory at specified intervals. + + Args: + output_dir (str): The directory where predictions will be saved. + write_interval (str): The interval at which predictions will be written. + target_file (str): The name of the file where epoch predictions will be saved (default: "predictions.json"). + """ + + def __init__( + self, + output_dir: str, + write_interval: Literal["batch", "epoch", "batch_and_epoch"], + target_file: str = "predictions.json", + ) -> None: super().__init__(write_interval) self.output_dir = output_dir self.target_file = target_file def write_on_batch_end( self, - trainer, - pl_module, - prediction, - batch_indices, - batch, - batch_idx, - dataloader_idx, - ): - outpath = os.path.join(self.output_dir, dataloader_idx, f"{batch_idx}.pt") - os.makedirs(outpath, exist_ok=True) + trainer: Any, + pl_module: Any, + prediction: Union[torch.Tensor, List[torch.Tensor]], + batch_indices: List[int], + batch: Any, + batch_idx: int, + dataloader_idx: int, + ) -> None: + """ + Saves batch predictions at the end of each batch. + + Args: + trainer (Any): The trainer instance. + pl_module (Any): The LightningModule instance. + prediction (Union[torch.Tensor, List[torch.Tensor]]): The prediction output from the model. + batch_indices (List[int]): The indices of the batch. + batch (Any): The current batch. + batch_idx (int): The index of the batch. + dataloader_idx (int): The index of the dataloader. + """ + outpath = os.path.join(self.output_dir, str(dataloader_idx), f"{batch_idx}.pt") + os.makedirs(os.path.dirname(outpath), exist_ok=True) torch.save(prediction, outpath) - def write_on_epoch_end(self, trainer, pl_module, predictions, batch_indices): + def write_on_epoch_end( + self, + trainer: Any, + pl_module: Any, + predictions: List[Dict[str, Any]], + batch_indices: List[int], + ) -> None: + """ + Saves all predictions at the end of each epoch in a JSON file. + + Args: + trainer (Any): The trainer instance. + pl_module (Any): The LightningModule instance. + predictions (List[Dict[str, Any]]): The list of prediction outputs from the model. + batch_indices (List[int]): The indices of the batches. + """ pred_list = [] for p in predictions: idents = p["data"]["idents"] @@ -35,7 +80,7 @@ def write_on_epoch_end(self, trainer, pl_module, predictions, batch_indices): else: labels = [None for _ in idents] output = torch.sigmoid(p["output"]["logits"]).tolist() - for i, l, p in zip(idents, labels, output): - pred_list.append(dict(ident=i, labels=l, predictions=p)) + for i, l, o in zip(idents, labels, output): + pred_list.append(dict(ident=i, labels=l, predictions=o)) with open(os.path.join(self.output_dir, self.target_file), "wt") as fout: json.dump(pred_list, fout) diff --git a/chebai/callbacks/epoch_metrics.py b/chebai/callbacks/epoch_metrics.py index 52dd4fdc..c1cf7bd3 100644 --- a/chebai/callbacks/epoch_metrics.py +++ b/chebai/callbacks/epoch_metrics.py @@ -2,13 +2,38 @@ import torchmetrics -def custom_reduce_fx(input): +def custom_reduce_fx(input: torch.Tensor) -> torch.Tensor: + """ + Custom reduction function for distributed training. + + Args: + input (torch.Tensor): The input tensor to be reduced. + + Returns: + torch.Tensor: The reduced tensor. + """ print(f"called reduce (device: {input.device})") return torch.sum(input, dim=0) class MacroF1(torchmetrics.Metric): - def __init__(self, num_labels, dist_sync_on_step=False, threshold=0.5): + """ + Computes the Macro F1 score, which is the unweighted mean of F1 scores for each class. + This implementation differs from torchmetrics.classification.MultilabelF1Score in the behaviour for undefined + values (i.e., classes where TP+FN=0). The torchmetrics implementation sets these classes to a default value. + Here, the mean is only taken over classes which have at least one positive sample. + + Args: + num_labels (int): Number of classes/labels. + dist_sync_on_step (bool, optional): Synchronize metric state across processes at each forward + before returning the value at the step. Default: False. + threshold (float, optional): Threshold for converting predicted probabilities to binary (0, 1) predictions. + Default: 0.5. + """ + + def __init__( + self, num_labels: int, dist_sync_on_step: bool = False, threshold: float = 0.5 + ): super().__init__(dist_sync_on_step=dist_sync_on_step) self.add_state( @@ -28,7 +53,14 @@ def __init__(self, num_labels, dist_sync_on_step=False, threshold=0.5): ) self.threshold = threshold - def update(self, preds: torch.Tensor, labels: torch.Tensor): + def update(self, preds: torch.Tensor, labels: torch.Tensor) -> None: + """ + Update the state (TPs, Positive Predictions, Positive labels) with the current batch of predictions and labels. + + Args: + preds (torch.Tensor): Predictions from the model. + labels (torch.Tensor): Ground truth labels. + """ tps = torch.sum( torch.logical_and(preds > self.threshold, labels.to(torch.bool)), dim=0 ) @@ -36,7 +68,14 @@ def update(self, preds: torch.Tensor, labels: torch.Tensor): self.positive_predictions += torch.sum(preds > self.threshold, dim=0) self.positive_labels += torch.sum(labels, dim=0) - def compute(self): + def compute(self) -> torch.Tensor: + """ + Compute the Macro F1 score. + + Returns: + torch.Tensor: The computed Macro F1 score. + """ + # ignore classes without positive labels # classes with positive labels, but no positive predictions will get a precision of "nan" (0 divided by 0), # which is propagated to the classwise_f1 and then turned into 0 @@ -50,14 +89,22 @@ def compute(self): class BalancedAccuracy(torchmetrics.Metric): - """Balanced Accuracy = (TPR + TNR) / 2 = ( TP/(TP + FN) + (TN)/(TN + FP) ) / 2 - - This metric computes the balanced accuracy, which is the average of true positive rate (TPR) - and true negative rate (TNR). It is useful for imbalanced datasets where the classes are not - represented equally. + """ + Computes the Balanced Accuracy, which is the average of true positive rate (TPR) and true negative rate (TNR). + Useful for imbalanced datasets. + Balanced Accuracy = (TPR + TNR)/2 = (TP/(TP + FN) + (TN)/(TN + FP))/2 + + Args: + num_labels (int): Number of classes/labels. + dist_sync_on_step (bool, optional): Synchronize metric state across processes at each forward + before returning the value at the step. Default: False. + threshold (float, optional): Threshold for converting predicted probabilities to binary (0, 1) predictions. + Default: 0.5. """ - def __init__(self, num_labels, dist_sync_on_step=False, threshold=0.5): + def __init__( + self, num_labels: int, dist_sync_on_step: bool = False, threshold: float = 0.5 + ): super().__init__(dist_sync_on_step=dist_sync_on_step) self.add_state( @@ -86,8 +133,14 @@ def __init__(self, num_labels, dist_sync_on_step=False, threshold=0.5): self.threshold = threshold - def update(self, preds: torch.Tensor, labels: torch.Tensor): - """Update the TPs, TNs ,FPs and FNs""" + def update(self, preds: torch.Tensor, labels: torch.Tensor) -> None: + """ + Update the state (TPs, TNs, FPs, FNs) with the current batch of predictions and labels. + + Args: + preds (torch.Tensor): Predictions from the model. + labels (torch.Tensor): Ground truth labels. + """ # Size: Batch_size x Num_of_Classes; # summing over 1st dimension (dim=0), gives us the True positives per class @@ -110,9 +163,13 @@ def update(self, preds: torch.Tensor, labels: torch.Tensor): self.true_negatives += tns self.false_negatives += fns - def compute(self): - """Compute the average value of Balanced accuracy from each batch""" + def compute(self) -> torch.Tensor: + """ + Compute the Balanced Accuracy. + Returns: + torch.Tensor: The computed Balanced Accuracy. + """ tpr = self.true_positives / (self.true_positives + self.false_negatives) tnr = self.true_negatives / (self.true_negatives + self.false_positives) # Convert the nan values to 0 diff --git a/chebai/callbacks/model_checkpoint.py b/chebai/callbacks/model_checkpoint.py index 0d8369f7..dbdbab17 100644 --- a/chebai/callbacks/model_checkpoint.py +++ b/chebai/callbacks/model_checkpoint.py @@ -10,13 +10,25 @@ class CustomModelCheckpoint(ModelCheckpoint): - """Checkpoint class that resolves checkpoint paths s.t. for the CustomLogger, checkpoints get saved to the - same directory as the other logs""" + """ + Custom checkpoint class that resolves checkpoint paths to ensure checkpoints are saved in the same directory + as other logs when using CustomLogger. + Inherits from PyTorch Lightning's ModelCheckpoint class. + """ - def setup( - self, trainer: "Trainer", pl_module: "LightningModule", stage: str - ) -> None: - """Same as in parent class, duplicated to be able to call self.__resolve_ckpt_dir""" + def setup(self, trainer: Trainer, pl_module: LightningModule, stage: str) -> None: + """ + Setup the directory path for saving checkpoints. If the directory path is not set, it resolves the checkpoint + directory using the custom logger's directory. + + Note: + Same as in parent class, duplicated to be able to call self.__resolve_ckpt_dir + + Args: + trainer (Trainer): The Trainer instance. + pl_module (LightningModule): The LightningModule instance. + stage (str): The stage of training (e.g., 'fit'). + """ if self.dirpath is not None: self.dirpath = None dirpath = self.__resolve_ckpt_dir(trainer) @@ -26,7 +38,15 @@ def setup( self.__warn_if_dir_not_empty(self.dirpath) def __warn_if_dir_not_empty(self, dirpath: _PATH) -> None: - """Same as in parent class, duplicated because method in parent class is not accessible""" + """ + Warn if the checkpoint directory is not empty. + + Note: + Same as in parent class, duplicated because method in parent class is not accessible + + Args: + dirpath (_PATH): The path to the checkpoint directory. + """ if ( self.save_top_k != 0 and _is_dir(self._fs, dirpath, strict=True) @@ -34,8 +54,20 @@ def __warn_if_dir_not_empty(self, dirpath: _PATH) -> None: ): rank_zero_warn(f"Checkpoint directory {dirpath} exists and is not empty.") - def __resolve_ckpt_dir(self, trainer: "Trainer") -> _PATH: - """Overwritten for compatibility with wandb -> saves checkpoints in same dir as wandb logs""" + def __resolve_ckpt_dir(self, trainer: Trainer) -> _PATH: + """ + Resolve the checkpoint directory path, ensuring compatibility with WandbLogger by saving checkpoints + in the same directory as Wandb logs. + + Note: + Overwritten for compatibility with wandb -> saves checkpoints in same dir as wandb logs + + Args: + trainer (Trainer): The Trainer instance. + + Returns: + _PATH: The resolved checkpoint directory path. + """ rank_zero_info(f"Resolving checkpoint dir (custom)") if self.dirpath is not None: # short circuit if dirpath was passed to ModelCheckpoint diff --git a/chebai/callbacks/prediction_callback.py b/chebai/callbacks/prediction_callback.py index 07e8b82c..b36197d4 100644 --- a/chebai/callbacks/prediction_callback.py +++ b/chebai/callbacks/prediction_callback.py @@ -1,17 +1,46 @@ import os import pickle +from typing import Any, Literal, Sequence import torch +from lightning.pytorch import LightningModule, Trainer from lightning.pytorch.callbacks import BasePredictionWriter class PredictionWriter(BasePredictionWriter): - def __init__(self, output_dir, write_interval): + """ + Custom callback for writing predictions to a file at the end of each epoch. + + Args: + output_dir (str): The directory where prediction files will be saved. + write_interval (str): When to write predictions. Options are "batch" or "epoch". + """ + + def __init__( + self, + output_dir: str, + write_interval: Literal["batch", "epoch", "batch_and_epoch"], + ): super().__init__(write_interval) self.output_dir = output_dir self.prediction_file_name = "predictions.pkl" - def write_on_epoch_end(self, trainer, pl_module, predictions, batch_indices): + def write_on_epoch_end( + self, + trainer: Trainer, + pl_module: LightningModule, + predictions: Sequence[Any], + batch_indices: Sequence[Any], + ) -> None: + """ + Writes the predictions to a file at the end of the epoch. + + Args: + trainer (Trainer): The Trainer instance. + pl_module (LightningModule): The LightningModule instance. + predictions (Sequence[Any]): Any sequence of predictions for the epoch. + batch_indices (Sequence[Any]): Any sequence of batch indices. + """ results = [ dict( ident=row["data"]["idents"][0], diff --git a/chebai/cli.py b/chebai/cli.py index 910dfac7..f2ad1072 100644 --- a/chebai/cli.py +++ b/chebai/cli.py @@ -6,10 +6,38 @@ class ChebaiCLI(LightningCLI): + """ + Custom CLI subclass for Chebai project based on PyTorch Lightning's LightningCLI. + + Args: + save_config_kwargs (dict): Keyword arguments for saving configuration. + parser_kwargs (dict): Keyword arguments for parser configuration. + + Attributes: + save_config_kwargs (dict): Configuration options for saving. + parser_kwargs (dict): Configuration options for the argument parser. + """ + def __init__(self, *args, **kwargs): + """ + Initialize ChebaiCLI with custom trainer and configure parser settings. + + Args: + args (list): List of arguments for LightningCLI. + kwargs (dict): Keyword arguments for LightningCLI. + save_config_kwargs (dict): Keyword arguments for saving configuration. + parser_kwargs (dict): Keyword arguments for parser configuration. + """ super().__init__(trainer_class=CustomTrainer, *args, **kwargs) def add_arguments_to_parser(self, parser: LightningArgumentParser): + """ + Link input parameters that are used by different classes (e.g. number of labels) + see https://lightning.ai/docs/pytorch/stable/cli/lightning_cli_expert.html#argument-linking + + Args: + parser (LightningArgumentParser): Argument parser instance. + """ for kind in ("train", "val", "test"): for average in ("micro-f1", "macro-f1", "balanced-accuracy"): parser.link_arguments( @@ -25,7 +53,12 @@ def add_arguments_to_parser(self, parser: LightningArgumentParser): @staticmethod def subcommands() -> Dict[str, Set[str]]: - """Defines the list of available subcommands and the arguments to skip.""" + """ + Defines the list of available subcommands and the arguments to skip. + + Returns: + Dict[str, Set[str]]: Dictionary where keys are subcommands and values are sets of arguments to skip. + """ return { "fit": {"model", "train_dataloaders", "val_dataloaders", "datamodule"}, "validate": {"model", "dataloaders", "datamodule"}, @@ -36,6 +69,9 @@ def subcommands() -> Dict[str, Set[str]]: def cli(): + """ + Main function to instantiate and run the ChebaiCLI. + """ r = ChebaiCLI( save_config_kwargs={"config_filename": "lightning_config.yaml"}, parser_kwargs={"parser_mode": "omegaconf"}, diff --git a/chebai/loggers/custom.py b/chebai/loggers/custom.py index bb11ea66..d1b4282d 100644 --- a/chebai/loggers/custom.py +++ b/chebai/loggers/custom.py @@ -9,7 +9,23 @@ class CustomLogger(WandbLogger): - """Adds support for custom naming of runs and cross-validation""" + """ + A custom logger that extends WandbLogger to add support for custom naming of runs and cross-validation. + + Args: + save_dir (_PATH): Directory where logs are saved. + name (str): Name of the logging run. + version (Optional[Union[int, str]]): Version of the logging run. + prefix (str): Prefix for logging. + fold (Optional[int]): Cross-validation fold number. + project (Optional[str]): Wandb project name. + entity (Optional[str]): Wandb entity name. + offline (bool): Whether to log offline. + log_model (Union[Literal["all"], bool]): Whether to log the model. + verbose_hyperparameters (bool): Whether to log hyperparameters verbosely. + tags (Optional[List[str]]): List of tags for the run. + **kwargs: Additional keyword arguments for WandbLogger. + """ def __init__( self, @@ -48,6 +64,9 @@ def __init__( @property def name(self) -> Optional[str]: + """ + Returns the name of the logging run, including the version and fold number if applicable. + """ name = f"{self._name}_{self.version}" if self._fold is not None: name += f"_fold{self._fold}" @@ -55,14 +74,23 @@ def name(self) -> Optional[str]: @property def version(self) -> Optional[str]: + """ + Returns the version of the logging run. + """ return self._version @property def root_dir(self) -> Optional[str]: + """ + Returns the root directory for saving logs. + """ return os.path.join(self.save_dir, self.name) @property def log_dir(self) -> str: + """ + Returns the directory for saving logs, including the version and fold number if applicable. + """ version = ( self.version if isinstance(self.version, str) else f"version_{self.version}" ) @@ -70,19 +98,30 @@ def log_dir(self) -> str: return os.path.join(self.root_dir, version) return os.path.join(self.root_dir, version, f"fold_{self._fold}") - def set_fold(self, fold: int): + def set_fold(self, fold: int) -> None: + """ + Sets the fold number and restarts the Wandb experiment with the new fold number. + + Args: + fold (int): Cross-validation fold number. + """ if fold != self._fold: self._fold = fold - # start new experiment + # Start new experiment wandb.finish() self._wandb_init["name"] = self.name self._experiment = None _ = self.experiment @property - def fold(self): + def fold(self) -> Optional[int]: + """ + Returns the current fold number. + """ return self._fold def after_save_checkpoint(self, checkpoint_callback: ModelCheckpoint) -> None: - # don't save checkpoint as wandb artifact + """ + Override method to prevent saving checkpoints as Wandb artifacts. + """ pass diff --git a/chebai/loss/bce_weighted.py b/chebai/loss/bce_weighted.py index 09ed7276..b69fff43 100644 --- a/chebai/loss/bce_weighted.py +++ b/chebai/loss/bce_weighted.py @@ -1,5 +1,5 @@ import os -import pickle +from typing import Optional import pandas as pd import torch @@ -9,14 +9,21 @@ class BCEWeighted(torch.nn.BCEWithLogitsLoss): - """BCEWithLogitsLoss with weights automatically computed according to beta parameter (formula from - https://openaccess.thecvf.com/content_CVPR_2019/papers/Cui_Class-Balanced_Loss_Based_on_Effective_Number_of_Samples_CVPR_2019_paper.pdf) + """ + BCEWithLogitsLoss with weights automatically computed according to the beta parameter. + + This class computes weights based on the formula from the paper: + https://openaccess.thecvf.com/content_CVPR_2019/papers/Cui_Class-Balanced_Loss_Based_on_Effective_Number_of_Samples_CVPR_2019_paper.pdf + + Args: + beta (float, optional): The beta parameter for weight calculation. Default is None. + data_extractor (XYBaseDataModule, optional): The data extractor for loading the dataset. Default is None. """ def __init__( self, - beta: float = None, - data_extractor: XYBaseDataModule = None, + beta: Optional[float] = None, + data_extractor: Optional[XYBaseDataModule] = None, ): self.beta = beta if isinstance(data_extractor, LabeledUnlabeledMixed): @@ -25,7 +32,13 @@ def __init__( super().__init__() - def set_pos_weight(self, input): + def set_pos_weight(self, input: torch.Tensor) -> None: + """ + Sets the positive weights for the loss function based on the input tensor. + + Args: + input (torch.Tensor): The input tensor for which to set the positive weights. + """ if ( self.beta is not None and self.data_extractor is not None @@ -61,5 +74,15 @@ def set_pos_weight(self, input): ) def forward(self, input: torch.Tensor, target: torch.Tensor) -> torch.Tensor: + """ + Forward pass for the loss calculation. + + Args: + input (torch.Tensor): The input tensor (predictions). + target (torch.Tensor): The target tensor (labels). + + Returns: + torch.Tensor: The computed loss. + """ self.set_pos_weight(input) return super().forward(input, target) diff --git a/chebai/loss/mixed.py b/chebai/loss/mixed.py index ce24ea6b..edfc5cb0 100644 --- a/chebai/loss/mixed.py +++ b/chebai/loss/mixed.py @@ -1,12 +1,37 @@ +import torch from torch import nn class MixedDataLoss(nn.Module): + """ + A wrapper for applying a base loss function to a subset of input data. + + This class allows for selective application of a loss function based on the provided + non-null labels. + + Args: + base_loss (nn.Module): The base loss function to be applied. + """ + def __init__(self, base_loss: nn.Module): super().__init__() self.base_loss = base_loss - def forward(self, input, target, **kwargs): + def forward( + self, input: torch.Tensor, target: torch.Tensor, **kwargs + ) -> torch.Tensor: + """ + Forward pass for applying the base loss function. + + Args: + input (torch.Tensor): The input tensor (predictions). + target (torch.Tensor): The target tensor (labels). + **kwargs: Additional keyword arguments. The 'non_null_labels' key can be used + to specify the indices of the non-null labels. + + Returns: + torch.Tensor: The computed loss. + """ nnl = kwargs.pop("non_null_labels", None) if nnl: inp = input[nnl] diff --git a/chebai/loss/pretraining.py b/chebai/loss/pretraining.py index d5af9bb1..e2f51dac 100644 --- a/chebai/loss/pretraining.py +++ b/chebai/loss/pretraining.py @@ -2,14 +2,45 @@ class ElectraPreLoss(torch.nn.Module): + """ + Custom loss module for pre-training ELECTRA-like models. + + This module computes a combined loss from two CrossEntropyLosses: + one for generator predictions and another for discriminator predictions. + + Attributes: + ce (torch.nn.CrossEntropyLoss): Cross entropy loss function. + + Methods: + forward(input, target, **loss_kwargs): + Computes the combined loss for generator and discriminator predictions. + + """ + def __init__(self): + """ + Initializes the ElectraPreLoss module. + """ super().__init__() self.ce = torch.nn.CrossEntropyLoss() def forward(self, input, target, **loss_kwargs): + """ + Forward pass for computing the combined loss. + + Args: + input (tuple): A tuple containing generator predictions (gen_pred, disc_pred). + target (tuple): A tuple containing generator targets (gen_tar, disc_tar). + **loss_kwargs: Additional keyword arguments. + + Returns: + torch.Tensor: Combined loss of generator and discriminator predictions. + """ t, p = input gen_pred, disc_pred = t gen_tar, disc_tar = p + + # Compute losses for generator and discriminator gen_loss = self.ce(target=torch.argmax(gen_tar.int(), dim=-1), input=gen_pred) disc_loss = self.ce( target=torch.argmax(disc_tar.int(), dim=-1), input=disc_pred diff --git a/chebai/loss/semantic.py b/chebai/loss/semantic.py index 6dfac3e2..78938d22 100644 --- a/chebai/loss/semantic.py +++ b/chebai/loss/semantic.py @@ -2,26 +2,38 @@ import math import os import pickle +from typing import List, Literal, Union import torch -from typing import Literal, Union - from chebai.loss.bce_weighted import BCEWeighted from chebai.preprocessing.datasets.chebi import ChEBIOver100, _ChEBIDataExtractor from chebai.preprocessing.datasets.pubchem import LabeledUnlabeledMixed class ImplicationLoss(torch.nn.Module): + """ + Implication Loss module. + + Args: + data_extractor (Union[_ChEBIDataExtractor, LabeledUnlabeledMixed]): Data extractor for labels. + base_loss (torch.nn.Module, optional): Base loss function. Defaults to None. + tnorm (Literal["product", "lukasiewicz", "xu19"], optional): T-norm type. Defaults to "product". + impl_loss_weight (float, optional): Weight of implication loss relative to base loss. Defaults to 0.1. + pos_scalar (int, optional): Positive scalar exponent. Defaults to 1. + pos_epsilon (float, optional): Epsilon value for numerical stability. Defaults to 0.01. + multiply_by_softmax (bool, optional): Whether to multiply by softmax. Defaults to False. + """ + def __init__( self, data_extractor: Union[_ChEBIDataExtractor, LabeledUnlabeledMixed], base_loss: torch.nn.Module = None, tnorm: Literal["product", "lukasiewicz", "xu19"] = "product", - impl_loss_weight=0.1, # weight of implication loss in relation to base_loss - pos_scalar=1, - pos_epsilon=0.01, - multiply_by_softmax=False, + impl_loss_weight: float = 0.1, + pos_scalar: int = 1, + pos_epsilon: float = 0.01, + multiply_by_softmax: bool = False, ): super().__init__() # automatically choose labeled subset for implication filter in case of mixed dataset @@ -48,7 +60,18 @@ def __init__( self.eps = pos_epsilon self.multiply_by_softmax = multiply_by_softmax - def forward(self, input, target, **kwargs): + def forward(self, input: torch.Tensor, target: torch.Tensor, **kwargs) -> tuple: + """ + Forward pass of the implication loss module. + + Args: + input (torch.Tensor): Input tensor. + target (torch.Tensor): Target tensor. + **kwargs: Additional arguments. + + Returns: + tuple: Tuple containing total loss, base loss, and implication loss. + """ nnl = kwargs.pop("non_null_labels", None) if nnl: labeled_input = input[nnl] @@ -70,7 +93,19 @@ def forward(self, input, target, **kwargs): implication_loss, ) - def _calculate_implication_loss(self, l, r): + def _calculate_implication_loss( + self, l: torch.Tensor, r: torch.Tensor + ) -> torch.Tensor: + """ + Calculate implication loss based on T-norm and other parameters. + + Args: + l (torch.Tensor): Left part of implication. + r (torch.Tensor): Right part of implication. + + Returns: + torch.Tensor: Calculated implication loss. + """ assert not l.isnan().any() assert not r.isnan().any() if self.pos_scalar != 1: @@ -100,7 +135,16 @@ def _calculate_implication_loss(self, l, r): dim=0, ) - def _load_implications(self, path_to_chebi): + def _load_implications(self, path_to_chebi: str) -> dict: + """ + Load class hierarchy implications. + + Args: + path_to_chebi (str): Path to the ChEBI ontology file. + + Returns: + dict: Loaded hierarchy of implications. + """ if os.path.isfile(self.implication_cache_file): with open(self.implication_cache_file, "rb") as fin: hierarchy = pickle.load(fin) @@ -112,12 +156,23 @@ def _load_implications(self, path_to_chebi): class DisjointLoss(ImplicationLoss): + """ + Disjoint Loss module, extending ImplicationLoss. + + Args: + path_to_disjointness (str): Path to the disjointness data file (a csv file containing pairs of disjoint classes) + data_extractor (Union[_ChEBIDataExtractor, LabeledUnlabeledMixed]): Data extractor for labels. + base_loss (torch.nn.Module, optional): Base loss function. Defaults to None. + disjoint_loss_weight (float, optional): Weight of disjointness loss. Defaults to 100. + **kwargs: Additional arguments. + """ + def __init__( self, - path_to_disjointness, + path_to_disjointness: str, data_extractor: Union[_ChEBIDataExtractor, LabeledUnlabeledMixed], base_loss: torch.nn.Module = None, - disjoint_loss_weight=100, + disjoint_loss_weight: float = 100, **kwargs, ): super().__init__(data_extractor, base_loss, **kwargs) @@ -126,7 +181,18 @@ def __init__( ) self.disjoint_weight = disjoint_loss_weight - def forward(self, input, target, **kwargs): + def forward(self, input: torch.Tensor, target: torch.Tensor, **kwargs) -> tuple: + """ + Forward pass of the disjoint loss module. + + Args: + input (torch.Tensor): Input tensor. + target (torch.Tensor): Target tensor. + **kwargs: Additional arguments. + + Returns: + tuple: Tuple containing total loss, base loss, implication loss, and disjointness loss. + """ loss, base_loss, impl_loss = super().forward(input, target, **kwargs) pred = torch.sigmoid(input) l = pred[:, self.disjoint_filter_l] @@ -140,13 +206,32 @@ def forward(self, input, target, **kwargs): ) -def _load_label_names(path_to_label_names): +def _load_label_names(path_to_label_names: str) -> List: + """ + Load label names from a file. + + Args: + path_to_label_names (str): Path to the label names file. + + Returns: + list: List of label names. + """ with open(path_to_label_names) as fin: label_names = [int(line.strip()) for line in fin] return label_names -def _build_implication_filter(label_names, hierarchy): +def _build_implication_filter(label_names: List, hierarchy: dict) -> torch.Tensor: + """ + Build implication filter based on label names and hierarchy. + + Args: + label_names (list): List of label names. + hierarchy (dict): Hierarchy of implications. + + Returns: + torch.Tensor: Tensor representing implication filter. + """ return torch.tensor( [ (i1, i2) @@ -157,7 +242,20 @@ def _build_implication_filter(label_names, hierarchy): ) -def _build_disjointness_filter(path_to_disjointness, label_names, hierarchy): +def _build_disjointness_filter( + path_to_disjointness: str, label_names: List, hierarchy: dict +) -> tuple: + """ + Build disjointness filter based on disjointness data and hierarchy. + + Args: + path_to_disjointness (str): Path to the disjointness data file. + label_names (list): List of label names. + hierarchy (dict): Hierarchy of implications. + + Returns: + tuple: Tuple containing tensors representing disjointness filter. + """ disjoints = set() label_dict = dict(map(reversed, enumerate(label_names))) diff --git a/chebai/models/base.py b/chebai/models/base.py index 8b7b65c1..77f714a1 100644 --- a/chebai/models/base.py +++ b/chebai/models/base.py @@ -1,9 +1,9 @@ import logging -import typing -from typing import Optional +from typing import Any, Dict, Optional, Union import torch from lightning.pytorch.core.module import LightningModule +from torchmetrics import Metric from chebai.preprocessing.structures import XYData @@ -19,11 +19,11 @@ class ChebaiBaseNet(LightningModule): Args: criterion (torch.nn.Module, optional): The loss criterion for the model. Defaults to None. out_dim (int, optional): The output dimension of the model. Defaults to None. - train_metrics (torch.nn.Module, optional): The metrics to be used during training. Defaults to None. - val_metrics (torch.nn.Module, optional): The metrics to be used during validation. Defaults to None. - test_metrics (torch.nn.Module, optional): The metrics to be used during testing. Defaults to None. + train_metrics (Dict[str, Metric], optional): The metrics to be used during training. Defaults to None. + val_metrics (Dict[str, Metric], optional): The metrics to be used during validation. Defaults to None. + test_metrics (Dict[str, Metric], optional): The metrics to be used during testing. Defaults to None. pass_loss_kwargs (bool, optional): Whether to pass loss kwargs to the criterion. Defaults to True. - optimizer_kwargs (typing.Dict, optional): Additional keyword arguments for the optimizer. Defaults to None. + optimizer_kwargs (Dict[str, Any], optional): Additional keyword arguments for the optimizer. Defaults to None. **kwargs: Additional keyword arguments. Attributes: @@ -36,11 +36,11 @@ def __init__( self, criterion: torch.nn.Module = None, out_dim: Optional[int] = None, - train_metrics: Optional[torch.nn.Module] = None, - val_metrics: Optional[torch.nn.Module] = None, - test_metrics: Optional[torch.nn.Module] = None, - pass_loss_kwargs=True, - optimizer_kwargs: Optional[typing.Dict] = None, + train_metrics: Optional[Dict[str, Metric]] = None, + val_metrics: Optional[Dict[str, Metric]] = None, + test_metrics: Optional[Dict[str, Metric]] = None, + pass_loss_kwargs: bool = True, + optimizer_kwargs: Optional[Dict[str, Any]] = None, **kwargs, ): super().__init__() @@ -59,18 +59,56 @@ def __init__( self.pass_loss_kwargs = pass_loss_kwargs def __init_subclass__(cls, **kwargs): + """ + Automatically registers subclasses in the model registry to prevent duplicates. + + Args: + **kwargs: Additional keyword arguments. + """ if cls.NAME in _MODEL_REGISTRY: raise ValueError(f"Model {cls.NAME} does already exist") else: _MODEL_REGISTRY[cls.NAME] = cls - def _get_prediction_and_labels(self, data, labels, output): + def _get_prediction_and_labels( + self, data: Dict[str, Any], labels: torch.Tensor, output: torch.Tensor + ) -> (torch.Tensor, torch.Tensor): + """ + Gets the predictions and labels from the model output. + + Args: + data (Dict[str, Any]): The processed batch data. + labels (torch.Tensor): The true labels. + output (torch.Tensor): The model output. + + Returns: + Tuple[torch.Tensor, torch.Tensor]: Predictions and labels. + """ return output, labels - def _process_labels_in_batch(self, batch): + def _process_labels_in_batch(self, batch: XYData) -> torch.Tensor: + """ + Processes the labels in the batch. + + Args: + batch (XYData): The input batch of data. + + Returns: + torch.Tensor: The processed labels. + """ return batch.y.float() - def _process_batch(self, batch, batch_idx): + def _process_batch(self, batch: XYData, batch_idx: int) -> Dict[str, Any]: + """ + Processes the batch data. + + Args: + batch (XYData): The input batch of data. + batch_idx (int): The index of the current batch. + + Returns: + Dict[str, Any]: Processed batch data. + """ return dict( features=batch.x, labels=self._process_labels_in_batch(batch), @@ -79,41 +117,115 @@ def _process_batch(self, batch, batch_idx): idents=batch.additional_fields["idents"], ) - def _process_for_loss(self, model_output, labels, loss_kwargs): + def _process_for_loss( + self, + model_output: torch.Tensor, + labels: torch.Tensor, + loss_kwargs: Dict[str, Any], + ) -> (torch.Tensor, torch.Tensor, Dict[str, Any]): + """ + Processes the data for loss computation. + + Args: + model_output (torch.Tensor): The model output. + labels (torch.Tensor): The true labels. + loss_kwargs (Dict[str, Any]): Additional keyword arguments for the loss function. + + Returns: + Tuple[torch.Tensor, torch.Tensor, Dict[str, Any]]: Model output, labels, and loss kwargs. + """ return model_output, labels, loss_kwargs - def training_step(self, batch, batch_idx): + def training_step( + self, batch: XYData, batch_idx: int + ) -> Dict[str, Union[torch.Tensor, Any]]: + """ + Defines the training step. + + Args: + batch (XYData): The input batch of data. + batch_idx (int): The index of the current batch. + + Returns: + Dict[str, Union[torch.Tensor, Any]]: The result of the training step. + """ return self._execute( batch, batch_idx, self.train_metrics, prefix="train_", sync_dist=True ) - def validation_step(self, batch, batch_idx): + def validation_step( + self, batch: XYData, batch_idx: int + ) -> Dict[str, Union[torch.Tensor, Any]]: + """ + Defines the validation step. + + Args: + batch (XYData): The input batch of data. + batch_idx (int): The index of the current batch. + + Returns: + Dict[str, Union[torch.Tensor, Any]]: The result of the validation step. + """ return self._execute( batch, batch_idx, self.validation_metrics, prefix="val_", sync_dist=True ) - def test_step(self, batch, batch_idx): + def test_step( + self, batch: XYData, batch_idx: int + ) -> Dict[str, Union[torch.Tensor, Any]]: + """ + Defines the test step. + + Args: + batch (XYData): The input batch of data. + batch_idx (int): The index of the current batch. + + Returns: + Dict[str, Union[torch.Tensor, Any]]: The result of the test step. + """ return self._execute( batch, batch_idx, self.test_metrics, prefix="test_", sync_dist=True ) - def predict_step(self, batch, batch_idx, **kwargs): + def predict_step( + self, batch: XYData, batch_idx: int, **kwargs + ) -> Dict[str, Union[torch.Tensor, Any]]: + """ + Defines the prediction step. + + Args: + batch (XYData): The input batch of data. + batch_idx (int): The index of the current batch. + **kwargs: Additional keyword arguments. + + Returns: + Dict[str, Union[torch.Tensor, Any]]: The result of the prediction step. + """ return self._execute(batch, batch_idx, self.test_metrics, prefix="", log=False) - def _execute(self, batch, batch_idx, metrics, prefix="", log=True, sync_dist=False): + def _execute( + self, + batch: XYData, + batch_idx: int, + metrics: Dict[str, Metric], + prefix: Optional[str] = "", + log: Optional[bool] = True, + sync_dist: Optional[bool] = False, + ) -> Dict[str, Union[torch.Tensor, Any]]: """ Executes the model on a batch of data and returns the model output and predictions. Args: batch (XYData): The input batch of data. batch_idx (int): The index of the current batch. - metrics (dict): A dictionary of metrics to track. + metrics (Dict[str, Metric]): A dictionary of metrics to track. prefix (str, optional): A prefix to add to the metric names. Defaults to "". log (bool, optional): Whether to log the metrics. Defaults to True. sync_dist (bool, optional): Whether to synchronize distributed training. Defaults to False. Returns: - dict: A dictionary containing the processed data, labels, model_output, predictions, and loss (if applicable). + Dict[str, Union[torch.Tensor, Any]]: A dictionary containing the processed data, labels, model output, + predictions, and loss (if applicable). """ assert isinstance(batch, XYData) batch = batch.to(self.device) @@ -163,13 +275,13 @@ def _execute(self, batch, batch_idx, metrics, prefix="", log=True, sync_dist=Fal self._log_metrics(prefix, metrics, len(batch)) return d - def _log_metrics(self, prefix, metrics, batch_size): + def _log_metrics(self, prefix: str, metrics: Dict[str, Metric], batch_size: int): """ Logs the metrics for the given prefix. Args: prefix (str): The prefix to be added to the metric names. - metrics (dict): A dictionary containing the metrics to be logged. + metrics (Dict[str, Metric]): A dictionary containing the metrics to be logged. batch_size (int): The batch size used for logging. Returns: @@ -203,8 +315,26 @@ def _log_metrics(self, prefix, metrics, batch_size): logger=True, ) - def forward(self, x): + def forward(self, x: Dict[str, Any]) -> torch.Tensor: + """ + Defines the forward pass. + + Args: + x (Dict[str, Any]): The input data. + + Returns: + torch.Tensor: The model output. + """ raise NotImplementedError - def configure_optimizers(self, **kwargs): + def configure_optimizers(self, **kwargs) -> torch.optim.Optimizer: + """ + Configures the optimizers. + + Args: + **kwargs: Additional keyword arguments. + + Returns: + torch.optim.Optimizer: The optimizer. + """ return torch.optim.Adamax(self.parameters(), **self.optimizer_kwargs) diff --git a/chebai/models/electra.py b/chebai/models/electra.py index 4377c29f..3b2807c8 100644 --- a/chebai/models/electra.py +++ b/chebai/models/electra.py @@ -1,9 +1,10 @@ import logging from math import pi from tempfile import TemporaryDirectory +from typing import Any, Dict, Optional, Tuple import torch -from torch import nn +from torch import Tensor, nn from torch.nn.utils.rnn import pad_sequence from transformers import ( ElectraConfig, @@ -36,12 +37,11 @@ class ElectraPre(ChebaiBaseNet): discriminator_config (ElectraConfig): Configuration for the discriminator model. discriminator (ElectraForPreTraining): Discriminator model for pre-training. replace_p (float): Probability of replacing tokens during training. - """ NAME = "ElectraPre" - def __init__(self, config=None, **kwargs): + def __init__(self, config: Dict[str, Any] = None, **kwargs: Any): super().__init__(config=config, **kwargs) self.generator_config = ElectraConfig(**config["generator"]) self.generator = ElectraForMaskedLM(self.generator_config) @@ -50,20 +50,30 @@ def __init__(self, config=None, **kwargs): self.replace_p = 0.1 @property - def as_pretrained(self): + def as_pretrained(self) -> ElectraForPreTraining: """ Returns the discriminator model as a pre-trained model. Returns: ElectraForPreTraining: The discriminator model. - """ return self.discriminator - def _process_labels_in_batch(self, batch): + def _process_labels_in_batch(self, batch: Dict[str, Any]) -> None: + """ + Processes the labels in the batch. + + Args: + batch (Dict[str, Any]): The input batch of data. + + Returns: + torch.Tensor: The processed labels. + """ return None - def forward(self, data, **kwargs): + def forward( + self, data: Dict[str, Any], **kwargs: Any + ) -> Tuple[Tuple[Tensor, Tensor], Tuple[Tensor, Tensor]]: """ Forward pass of the ElectraPre model. @@ -75,7 +85,6 @@ def forward(self, data, **kwargs): tuple: A tuple containing the raw generator output and discriminator output. The generator output is a tensor of shape (batch_size, max_seq_len, vocab_size). The discriminator output is a tensor of shape (batch_size, max_seq_len). - """ features = data["features"] features = features.long() @@ -120,11 +129,34 @@ def forward(self, data, **kwargs): ).logits return (raw_gen_out, disc_out), (gen_tar_one_hot, disc_tar_one_hot) - def _get_prediction_and_labels(self, batch, labels, output): + def _get_prediction_and_labels( + self, batch: Dict[str, Any], labels: Tensor, output: Tensor + ) -> Tuple[Tensor, Tensor]: + """ + Gets the predictions and labels from the model output. + + Args: + data (Dict[str, Any]): The processed batch data. + labels (torch.Tensor): The true labels. + output (torch.Tensor): The model output. + + Returns: + Tuple[torch.Tensor, torch.Tensor]: Predictions and labels. + """ return torch.softmax(output[0][1], dim=-1), output[1][1].int() -def filter_dict(d, filter_key): +def filter_dict(d: Dict[str, Any], filter_key: str) -> Dict[str, Any]: + """ + Filters a dictionary by a given key prefix. + + Args: + d (dict): The dictionary to filter. + filter_key (str): The key prefix to filter by. + + Returns: + dict: A dictionary containing only the key-value pairs where the key starts with the given prefix. + """ return { str(k)[len(filter_key) :]: v for k, v in d.items() @@ -137,30 +169,28 @@ class Electra(ChebaiBaseNet): Electra model implementation inherited from ChebaiBaseNet. Args: - config (dict, optional): Configuration parameters for the Electra model. Defaults to None. + config (Dict[str, Any], optional): Configuration parameters for the Electra model. Defaults to None. pretrained_checkpoint (str, optional): Path to the pretrained checkpoint file. Defaults to None. load_prefix (str, optional): Prefix to filter the state_dict keys from the pretrained checkpoint. Defaults to None. **kwargs: Additional keyword arguments. Attributes: NAME (str): Name of the Electra model. - """ NAME = "Electra" - def _process_batch(self, batch, batch_idx): + def _process_batch(self, batch: Dict[str, Any], batch_idx: int) -> Dict[str, Any]: """ Process a batch of data. Args: - batch (XYData): The input batch of data. + batch (Dict[str, Any]): The input batch of data. batch_idx (int): The index of the batch (not used). Returns: dict: A dictionary containing the processed batch, keys are `features`, `labels`, `model_kwargs`, `loss_kwargs` and `idents`. - """ model_kwargs = dict() loss_kwargs = batch.additional_fields["loss_kwargs"] @@ -187,18 +217,21 @@ def _process_batch(self, batch, batch_idx): ) @property - def as_pretrained(self): + def as_pretrained(self) -> ElectraModel: """ Get the pretrained Electra model. Returns: ElectraModel: The pretrained Electra model. - """ return self.electra.electra def __init__( - self, config=None, pretrained_checkpoint=None, load_prefix=None, **kwargs + self, + config: Optional[Dict[str, Any]] = None, + pretrained_checkpoint: Optional[str] = None, + load_prefix: Optional[str] = None, + **kwargs: Any, ): # Remove this property in order to prevent it from being stored as a # hyper parameter @@ -234,36 +267,41 @@ def __init__( else: self.electra = ElectraModel(config=self.config) - def _process_for_loss(self, model_output, labels, loss_kwargs): + def _process_for_loss( + self, + model_output: Dict[str, Tensor], + labels: Tensor, + loss_kwargs: Dict[str, Any], + ) -> Tuple[Tensor, Tensor, Dict[str, Any]]: """ Process the model output for calculating the loss. Args: - model_output (dict): The output of the model. + model_output (Dict[str, Tensor]): The output of the model. labels (Tensor): The target labels. - loss_kwargs (dict): Additional loss arguments. + loss_kwargs (Dict[str, Any]): Additional loss arguments. Returns: tuple: A tuple containing the processed model output, labels, and loss arguments. - """ kwargs_copy = dict(loss_kwargs) if labels is not None: labels = labels.float() return model_output["logits"], labels, kwargs_copy - def _get_prediction_and_labels(self, data, labels, model_output): + def _get_prediction_and_labels( + self, data: Dict[str, Any], labels: Tensor, model_output: Dict[str, Tensor] + ) -> Tuple[Tensor, Tensor]: """ Get the predictions and labels from the model output. Applies a sigmoid to the model output. Args: - data (dict): The input data. + data (Dict[str, Any]): The input data. labels (Tensor): The target labels. - model_output (dict): The output of the model. + model_output (Dict[str, Tensor]): The output of the model. Returns: tuple: A tuple containing the predictions and labels. - """ d = model_output["logits"] loss_kwargs = data.get("loss_kwargs", dict()) @@ -272,12 +310,12 @@ def _get_prediction_and_labels(self, data, labels, model_output): d = d[n] return torch.sigmoid(d), labels.int() if labels is not None else None - def forward(self, data, **kwargs): + def forward(self, data: Dict[str, Tensor], **kwargs: Any) -> Dict[str, Any]: """ Forward pass of the Electra model. Args: - data (dict): The input data (expects a key `features`). + data (Dict[str, Tensor]): The input data (expects a key `features`). **kwargs: Additional keyword arguments for `self.electra`. Returns: diff --git a/chebai/molecule.py b/chebai/molecule.py index 52c055ce..db191976 100644 --- a/chebai/molecule.py +++ b/chebai/molecule.py @@ -1,6 +1,7 @@ from __future__ import absolute_import, division import logging +from typing import Any, List, Optional, Union try: from rdkit import Chem @@ -9,16 +10,72 @@ import networkx as nx import numpy as np -import six import torch logger = logging.getLogger(__name__) class Molecule: + """ + Represents a molecule and provides methods for graph creation and feature extraction. + + Attributes: + max_number_of_parents (int): Maximum number of parent atoms for any given atom. + smile (str): SMILES representation of the molecule. + logp (Optional[float]): LogP (partition coefficient) of the molecule. + atoms (list): List of atom objects. + no_of_atoms (int): Number of atoms in the molecule. + graph (nx.Graph): Graph representation of the molecule. + directed_graphs (np.ndarray): Directed graphs for each atom. + dag_to_node (dict): Mapping of atom index to its directed acyclic graph (DAG). + + Methods: + __init__(self, smile, logp=None, contract_rings=False): + Initializes a Molecule object from SMILES representation. + create_directed_graphs(self): + Creates directed graphs (DAGs) for each atom in the molecule. + create_feature_vectors(self): + Creates feature vectors based on local environments of atoms. + get_cycle(self): + Attempts to find a cycle in the molecule graph. + collect_atom_features(self): + Collects atom features into a dictionary. + get_atom_features(self, node_id): + Retrieves features of a specific atom. + get_bond_features(self, node1, node2): + Retrieves features of a specific bond between two atoms. + + Static Methods: + atom_features(atom): + Computes features of an atom based on its properties. + atom_features_of_contract_rings(degree): + Computes features of an atom under contract rings condition. + bond_features_between_contract_rings(): + Computes features of a bond between contracted rings. + bond_features(bond): + Computes features of a bond based on its type and properties. + num_of_features(): + Computes total number of features in the feature vector. + one_of_k_encoding(x, allowable_set): + Encodes categorical input into a one-hot vector. + one_of_k_encoding_unk(x, allowable_set): + Encodes input into a one-hot vector with an 'unknown' handling. + + """ + max_number_of_parents = 7 - def __init__(self, smile, logp=None, contract_rings=False): + def __init__( + self, smile: str, logp: Optional[float] = None, contract_rings: bool = False + ): + """ + Initializes a Molecule object. + + Args: + smile (str): SMILES representation of the molecule. + logp (float, optional): LogP (partition coefficient) of the molecule. + contract_rings (bool, optional): Whether to contract rings during initialization. + """ self.smile = smile self.logp = logp # logger.info("Parsing Molecule {:},contract rings: {:}".format(smile, contract_rings)) @@ -49,7 +106,7 @@ def __init__(self, smile, logp=None, contract_rings=False): def create_directed_graphs(self): """ - :return: + Creates directed graphs (DAGs) for each atom in the molecule. """ self.directed_graphs = np.empty( (self.no_of_atoms, self.no_of_atoms - 1, 3), dtype=int @@ -72,11 +129,11 @@ def create_directed_graphs(self): def create_feature_vectors(self): """ - :return: - """ - # create a three dimesnional matrix I, - # such that Iij is the local input vector for jth vertex in ith DAG + Creates feature vectors based on local environments of atoms. + Note: + create a three-dimensional matrix I, such that I_{i,j} is the local input vector for jth vertex in ith DAG + """ length_of_bond_features = Molecule.num_bond_features() length_of_atom_features = Molecule.num_atom_features() @@ -117,12 +174,21 @@ def create_feature_vectors(self): ) def get_cycle(self): + """ + Attempts to find a cycle in the molecule graph. + + Returns: + list: List of edges forming a cycle in the graph. + """ try: return nx.find_cycle(self.graph) except: return [] def collect_atom_features(self): + """ + Collects atom features into a dictionary. + """ self.af = { node_id: torch.tensor( self.graph.nodes[node_id]["attr_dict"]["atom_features"] @@ -130,15 +196,43 @@ def collect_atom_features(self): for node_id in range(self.no_of_atoms) } - def get_atom_features(self, node_id): + def get_atom_features(self, node_id: int) -> torch.Tensor: + """ + Retrieves features of a specific atom. + + Args: + node_id (int): Index of the atom. + + Returns: + torch.Tensor: Tensor representing atom features. + """ return self.af[node_id] - def get_bond_features(self, node1, node2): + def get_bond_features(self, node1: int, node2: int) -> np.ndarray: + """ + Retrieves features of a specific bond between two atoms. + + Args: + node1 (int): Index of the first atom. + node2 (int): Index of the second atom. + + Returns: + np.ndarray: Array representing bond features. + """ attrs = self.graph.get_edge_data(node1, node2) return attrs["bond_features"] @staticmethod - def atom_features(atom): + def atom_features(atom: Any) -> np.ndarray: + """ + Computes features of an atom based on its properties. + + Args: + atom (Chem.Atom): RDKit Atom object. + + Returns: + np.ndarray: Array representing atom features. + """ return np.array( Molecule.one_of_k_encoding_unk( atom.GetSymbol(), @@ -198,7 +292,16 @@ def atom_features(atom): ) @staticmethod - def atom_features_of_contract_rings(degree): + def atom_features_of_contract_rings(degree: int) -> np.ndarray: + """ + Computes features of an atom under contract rings condition. + + Args: + degree (int): Degree of the atom. + + Returns: + np.ndarray: Array representing atom features under contract rings. + """ return np.array( Molecule.one_of_k_encoding_unk( "Unknown", @@ -256,11 +359,26 @@ def atom_features_of_contract_rings(degree): ) @staticmethod - def bond_features_between_contract_rings(): + def bond_features_between_contract_rings() -> np.ndarray: + """ + Computes features of a bond between contracted rings. + + Returns: + np.ndarray: Array representing bond features between contracted rings. + """ return np.array([1, 0, 0, 0, 0, 0]) @staticmethod - def bond_features(bond): + def bond_features(bond) -> np.ndarray: + """ + Computes features of a bond based on its type and properties. + + Args: + bond (Chem.Bond): RDKit Bond object. + + Returns: + np.ndarray: Array representing bond features. + """ bt = bond.GetBondType() return np.array( [ @@ -274,14 +392,30 @@ def bond_features(bond): ) @staticmethod - def num_of_features(): + def num_of_features() -> int: + """ + Computes total number of features in the feature vector. + + Returns: + int: Total number of features. + """ return ( Molecule.max_number_of_parents * Molecule.num_bond_features() + Molecule.num_atom_features() ) @staticmethod - def one_of_k_encoding(x, allowable_set): + def one_of_k_encoding(x: Union[int, str], allowable_set: List) -> List: + """ + Encodes categorical input into a one-hot vector. + + Args: + x: Input value to encode. + allowable_set (list): List of allowable values. + + Returns: + list: One-hot encoded vector. + """ if x not in allowable_set: raise Exception( "input {0} not in allowable set{1}:".format(x, allowable_set) @@ -289,23 +423,45 @@ def one_of_k_encoding(x, allowable_set): return list(map(lambda s: x == s, allowable_set)) @staticmethod - def one_of_k_encoding_unk(x, allowable_set): - """Maps inputs not in the allowable set to the last element.""" + def one_of_k_encoding_unk(x: Union[int, str], allowable_set: List) -> List: + """ + Encodes input into a one-hot vector with an 'unknown' handling. + + Note: + Maps inputs not in the allowable set to the last element. + + Args: + x: Input value to encode. + allowable_set (list): List of allowable values. + + Returns: + list: One-hot encoded vector. + """ if x not in allowable_set: x = allowable_set[-1] return list(map(lambda s: x == s, allowable_set)) @staticmethod - def num_atom_features(): - # Return length of feature vector using a very simple molecule. + def num_atom_features() -> int: + """ + Computes the length of the atom feature vector using a simple molecule. + + Returns: + int: Length of atom feature vector. + """ m = Chem.MolFromSmiles("CC") alist = m.GetAtoms() a = alist[0] return len(Molecule.atom_features(a)) @staticmethod - def num_bond_features(): - # Return length of feature vector using a very simple molecule. + def num_bond_features() -> int: + """ + Computes the length of the bond feature vector using a simple molecule. + + Returns: + int: Length of bond feature vector. + """ simple_mol = Chem.MolFromSmiles("CC") Chem.SanitizeMol(simple_mol) return len(Molecule.bond_features(simple_mol.GetBonds()[0])) diff --git a/chebai/preprocessing/collate.py b/chebai/preprocessing/collate.py index 8e0a703d..4e5e9e16 100644 --- a/chebai/preprocessing/collate.py +++ b/chebai/preprocessing/collate.py @@ -1,27 +1,61 @@ +from typing import Dict, List, Tuple, Union + import torch from torch.nn.utils.rnn import pad_sequence from chebai.preprocessing.structures import XYData -class Collater: +class Collator: + """Base class for collating data samples into a batch.""" + def __init__(self, **kwargs): pass - def __call__(self, data) -> XYData: + def __call__(self, data: List[Dict]) -> XYData: + """Collate a list of data samples into a batch. + + Args: + data (List[Dict]): List of data samples. + + Returns: + XYData: Batched data. + """ raise NotImplementedError -class DefaultCollater(Collater): - def __call__(self, data): +class DefaultCollator(Collator): + """Default collator that extracts features and labels.""" + + def __call__(self, data: List[Dict]) -> XYData: + """Collate data samples by extracting features and labels. + + Args: + data (List[Dict]): List of data samples. + + Returns: + XYData: Batched data. + """ x, y = zip(*((d["features"], d["labels"]) for d in data)) return XYData(x, y) -class RaggedCollater(Collater): - def __call__(self, data): - model_kwargs = dict() - loss_kwargs = dict() +class RaggedCollator(Collator): + """Collator for handling ragged data samples.""" + + def __call__(self, data: List[Union[Dict, Tuple]]) -> XYData: + """Collate ragged data samples (i.e., samples of unequal size such as string representations of molecules) into + a batch. + + Args: + data (List[Union[Dict, Tuple]]): List of ragged data samples. + + Returns: + XYData: Batched data with appropriate padding and masks. + """ + model_kwargs: Dict = dict() + loss_kwargs: Dict = dict() + if isinstance(data[0], tuple): # For legacy data x, y, idents = zip(*data) @@ -45,6 +79,7 @@ def __call__(self, data): lens = torch.tensor(list(map(len, x))) model_kwargs["mask"] = torch.arange(max(lens))[None, :] < lens[:, None] model_kwargs["lens"] = lens + return XYData( pad_sequence([torch.tensor(a) for a in x], batch_first=True), y, @@ -53,7 +88,15 @@ def __call__(self, data): idents=idents, ) - def process_label_rows(self, labels): + def process_label_rows(self, labels: Tuple) -> torch.Tensor: + """Process label rows by padding sequences. + + Args: + labels (Tuple): Tuple of label rows. + + Returns: + torch.Tensor: Padded label sequences. + """ return pad_sequence( [ torch.tensor([v if v is not None else False for v in row]) diff --git a/chebai/preprocessing/datasets/base.py b/chebai/preprocessing/datasets/base.py index 1d7da9d5..30aa6551 100644 --- a/chebai/preprocessing/datasets/base.py +++ b/chebai/preprocessing/datasets/base.py @@ -1,7 +1,6 @@ import os import random -import typing -from typing import List, Union +from typing import Any, Dict, Generator, List, Optional, Union import lightning as pl import torch @@ -25,14 +24,14 @@ class XYBaseDataModule(LightningDataModule): train_split (float): The ratio of training data to total data and of test data to (validation + test) data. Default is 0.85. reader_kwargs (dict): Additional keyword arguments to be passed to the data reader. Default is None. prediction_kind (str): The kind of prediction to be performed (only relevant for the predict_dataloader). Default is "test". - data_limit (int): The maximum number of data samples to load. If set to None, the complete dataset will be used. Default is None. - label_filter (int): The index of the label to filter. Default is None. - balance_after_filter (float): The ratio of negative samples to positive samples after filtering. Default is None. + data_limit (Optional[int]): The maximum number of data samples to load. If set to None, the complete dataset will be used. Default is None. + label_filter (Optional[int]): The index of the label to filter. Default is None. + balance_after_filter (Optional[float]): The ratio of negative samples to positive samples after filtering. Default is None. num_workers (int): The number of worker processes for data loading. Default is 1. chebi_version (int): The version of ChEBI to use. Default is 200. inner_k_folds (int): The number of folds for inner cross-validation. Use -1 to disable inner cross-validation. Default is -1. - fold_index (int): The index of the fold to use for training and validation. Default is None. - base_dir (str): The base directory for storing processed and raw data. Default is None. + fold_index (Optional[int]): The index of the fold to use for training and validation. Default is None. + base_dir (Optional[str]): The base directory for storing processed and raw data. Default is None. **kwargs: Additional keyword arguments. Attributes: @@ -41,14 +40,14 @@ class XYBaseDataModule(LightningDataModule): train_split (float): The ratio of training data to total data. batch_size (int): The batch size for data loading. prediction_kind (str): The kind of prediction to be performed. - data_limit (int): The maximum number of data samples to load. - label_filter (int): The index of the label to filter. - balance_after_filter (float): The ratio of negative samples to positive samples after filtering. + data_limit (Optional[int]): The maximum number of data samples to load. + label_filter (Optional[int]): The index of the label to filter. + balance_after_filter (Optional[float]): The ratio of negative samples to positive samples after filtering. num_workers (int): The number of worker processes for data loading. chebi_version (int): The version of ChEBI to use. inner_k_folds (int): The number of folds for inner cross-validation. If it is less than to, no cross-validation will be performed. - fold_index (int): The index of the fold to use for training and validation (only relevant for cross-validation) - _base_dir (str): The base directory for storing processed and raw data. + fold_index (Optional[int]): The index of the fold to use for training and validation (only relevant for cross-validation). + _base_dir (Optional[str]): The base directory for storing processed and raw data. raw_dir (str): The directory for storing raw data. processed_dir (str): The directory for storing processed data. fold_dir (str): The name of the directory where the folds from inner cross-validation are stored. @@ -60,18 +59,18 @@ class XYBaseDataModule(LightningDataModule): def __init__( self, - batch_size=1, - train_split=0.85, - reader_kwargs=None, - prediction_kind="test", - data_limit: typing.Optional[int] = None, - label_filter: typing.Optional[int] = None, - balance_after_filter: typing.Optional[float] = None, + batch_size: int = 1, + train_split: float = 0.85, + reader_kwargs: Optional[dict] = None, + prediction_kind: str = "test", + data_limit: Optional[int] = None, + label_filter: Optional[int] = None, + balance_after_filter: Optional[float] = None, num_workers: int = 1, chebi_version: int = 200, inner_k_folds: int = -1, # use inner cross-validation if > 1 - fold_index: typing.Optional[int] = None, - base_dir=None, + fold_index: Optional[int] = None, + base_dir: Optional[str] = None, **kwargs, ): super().__init__() @@ -111,47 +110,57 @@ def __init__( self.save_hyperparameters() @property - def identifier(self): + def identifier(self) -> tuple: """Identifier for the dataset.""" return (self.reader.name(),) @property - def full_identifier(self): + def full_identifier(self) -> tuple: """Full identifier for the dataset.""" return (self._name, *self.identifier) @property - def base_dir(self): - """Common base directory for processed and raw directories""" + def base_dir(self) -> str: + """Common base directory for processed and raw directories.""" if self._base_dir is not None: return self._base_dir return os.path.join("data", self._name) @property - def processed_dir(self): - """name of dir where the processed data is stored""" + def processed_dir(self) -> str: + """Name of the directory where the processed data is stored.""" return os.path.join(self.base_dir, "processed", *self.identifier) @property - def raw_dir(self): - """name of dir where the raw data is stored""" + def raw_dir(self) -> str: + """Name of the directory where the raw data is stored.""" return os.path.join(self.base_dir, "raw") @property - def fold_dir(self): - """name of dir where the folds from inner cross-validation (i.e., the train and val sets) are stored""" + def fold_dir(self) -> str: + """Name of the directory where the folds from inner cross-validation (i.e., the train and val sets) are stored.""" return f"cv_{self.inner_k_folds}_fold" @property - def _name(self): + def _name(self) -> str: raise NotImplementedError - def _filter_labels(self, row): - """filter labels based on label_filter""" + def _filter_labels(self, row: dict) -> dict: + """ + Filter labels based on `label_filter`. + + Args: + row (dict): A dictionary containing the row data. + + Returns: + dict: The filtered row data. + """ row["labels"] = [row["labels"][self.label_filter]] return row - def load_processed_data(self, kind: str = None, filename: str = None) -> List: + def load_processed_data( + self, kind: Optional[str] = None, filename: Optional[str] = None + ) -> List: """ Load processed data from a file. @@ -183,7 +192,7 @@ def load_processed_data(self, kind: str = None, filename: str = None) -> List: filename = f"{kind}.pt" return torch.load(os.path.join(self.processed_dir, filename)) - def dataloader(self, kind, **kwargs) -> DataLoader: + def dataloader(self, kind: str, **kwargs) -> DataLoader: """ Returns a DataLoader object for the specified kind (train, val or test) of data. @@ -193,7 +202,6 @@ def dataloader(self, kind, **kwargs) -> DataLoader: Returns: DataLoader: A DataLoader object. - """ dataset = self.load_processed_data(kind) if "ids" in kwargs: @@ -220,13 +228,15 @@ def dataloader(self, kind, **kwargs) -> DataLoader: dataset = dataset[: self.data_limit] return DataLoader( dataset, - collate_fn=self.reader.collater, + collate_fn=self.reader.collator, batch_size=self.batch_size, **kwargs, ) @staticmethod - def _load_dict(input_file_path): + def _load_dict( + input_file_path: str, + ) -> Generator[Dict[str, Any], None, None]: """ Load data from a file and return a dictionary. @@ -242,11 +252,20 @@ def _load_dict(input_file_path): yield dict(features=smiles, labels=labels) @staticmethod - def _get_data_size(input_file_path): + def _get_data_size(input_file_path: str) -> int: + """ + Get the number of lines in a file. + + Args: + input_file_path (str): The path to the input file. + + Returns: + int: The number of lines in the file. + """ with open(input_file_path, "r") as f: return sum(1 for _ in f) - def _load_data_from_file(self, path): + def _load_data_from_file(self, path: str) -> List[Dict[str, Any]]: """ Load data from a file and return a list of dictionaries. @@ -268,7 +287,17 @@ def _load_data_from_file(self, path): return data - def train_dataloader(self, *args, **kwargs) -> DataLoader: + def train_dataloader(self, *args, **kwargs) -> Union[DataLoader, List[DataLoader]]: + """ + Returns the train DataLoader. + + Args: + *args: Additional positional arguments. + **kwargs: Additional keyword arguments. + + Returns: + DataLoader: A DataLoader object for training data. + """ return self.dataloader( "train", shuffle=True, @@ -278,6 +307,16 @@ def train_dataloader(self, *args, **kwargs) -> DataLoader: ) def val_dataloader(self, *args, **kwargs) -> Union[DataLoader, List[DataLoader]]: + """ + Returns the validation DataLoader. + + Args: + *args: Additional positional arguments (unused). + **kwargs: Additional keyword arguments, passed to dataloader(). + + Returns: + Union[DataLoader, List[DataLoader]]: A DataLoader object for validation data. + """ return self.dataloader( "validation", shuffle=False, @@ -287,14 +326,42 @@ def val_dataloader(self, *args, **kwargs) -> Union[DataLoader, List[DataLoader]] ) def test_dataloader(self, *args, **kwargs) -> Union[DataLoader, List[DataLoader]]: + """ + Returns the test DataLoader. + + Args: + *args: Additional positional arguments (unused). + **kwargs: Additional keyword arguments, passed to dataloader(). + + Returns: + Union[DataLoader, List[DataLoader]]: A DataLoader object for test data. + """ return self.dataloader("test", shuffle=False, **kwargs) def predict_dataloader( self, *args, **kwargs ) -> Union[DataLoader, List[DataLoader]]: + """ + Returns the predict DataLoader. + + Args: + *args: Additional positional arguments (unused). + **kwargs: Additional keyword arguments, passed to dataloader(). + + Returns: + Union[DataLoader, List[DataLoader]]: A DataLoader object for prediction data. + """ return self.dataloader(self.prediction_kind, shuffle=False, **kwargs) def setup(self, **kwargs): + """ + Setup the data module. + + This method checks for the processed data and sets up the data module for training, validation, and testing. + + Args: + **kwargs: Additional keyword arguments. + """ rank_zero_info(f"Check for processed data in {self.processed_dir}") rank_zero_info(f"Cross-validation enabled: {self.use_inner_cross_validation}") if any( @@ -307,30 +374,70 @@ def setup(self, **kwargs): self.reader.on_finish() def setup_processed(self): + """ + Setup the processed data. + + This method should be implemented by subclasses to handle the specific setup of processed data. + """ raise NotImplementedError @property - def processed_file_names(self): + def processed_file_names(self) -> List[str]: + """ + Returns the list of processed file names. + + This property should be implemented by subclasses to provide the list of processed file names. + + Returns: + List[str]: The list of processed file names. + """ raise NotImplementedError @property - def raw_file_names(self): + def raw_file_names(self) -> List[str]: + """ + Returns the list of raw file names. + + This property should be implemented by subclasses to provide the list of raw file names. + + Returns: + List[str]: The list of raw file names. + """ raise NotImplementedError @property def processed_file_names_dict(self) -> dict: + """ + Returns the dictionary of processed file names. + + This property should be implemented by subclasses to provide the dictionary of processed file names. + + Returns: + dict: The dictionary of processed file names. + """ raise NotImplementedError @property def raw_file_names_dict(self) -> dict: + """ + Returns the dictionary of raw file names. + + This property should be implemented by subclasses to provide the dictionary of raw file names. + + Returns: + dict: The dictionary of raw file names. + """ raise NotImplementedError @property - def label_number(self): + def label_number(self) -> int: """ - Number of labels - :return: - Returns -1 for seq2seq encoding, otherwise the number of labels + Returns the number of labels. + + This property should be implemented by subclasses to provide the number of labels. + + Returns: + int: The number of labels. Returns -1 for seq2seq encoding. """ raise NotImplementedError @@ -339,10 +446,26 @@ class MergedDataset(XYBaseDataModule): MERGED = [] @property - def _name(self): + def _name(self) -> str: + """ + Returns a concatenated name of all subset names. + """ return "+".join(s._name for s in self.subsets) - def __init__(self, batch_size=1, train_split=0.85, reader_kwargs=None, **kwargs): + def __init__( + self, + batch_size: int = 1, + train_split: float = 0.85, + reader_kwargs: Union[None, List[dict]] = None, + **kwargs, + ): + """ + Args: + batch_size (int): Batch size for data loaders. + train_split (float): Fraction of data to use for training. + reader_kwargs (Union[None, List[dict]]): Optional arguments for subset readers. + **kwargs: Additional arguments to pass to LightningDataModule. + """ if reader_kwargs is None: reader_kwargs = [None for _ in self.MERGED] self.train_split = train_split @@ -356,14 +479,35 @@ def __init__(self, batch_size=1, train_split=0.85, reader_kwargs=None, **kwargs) super(pl.LightningDataModule, self).__init__(**kwargs) def prepare_data(self): + """ + Placeholder for data preparation logic. + """ for s in self.subsets: s.prepare_data() def setup(self, **kwargs): + """ + Setup the data module. + + This method checks for the processed data and sets up the data module for training, validation, and testing. + + Args: + **kwargs: Additional keyword arguments. + """ for s in self.subsets: s.setup(**kwargs) - def dataloader(self, kind, **kwargs): + def dataloader(self, kind: str, **kwargs) -> DataLoader: + """ + Creates a DataLoader for a specific subset. + + Args: + kind (str): Kind of data loader ('train', 'validation', or 'test'). + **kwargs: Additional arguments passed to DataLoader. + + Returns: + DataLoader: DataLoader object for the specified subset. + """ subdatasets = [ torch.load(os.path.join(s.processed_dir, f"{kind}.pt")) for s in self.subsets @@ -375,36 +519,67 @@ def dataloader(self, kind, **kwargs): ] return DataLoader( dataset, - collate_fn=self.reader.collater, + collate_fn=self.reader.collator, batch_size=self.batch_size, **kwargs, ) - def train_dataloader(self, *args, **kwargs) -> DataLoader: + def train_dataloader(self, *args, **kwargs) -> Union[DataLoader, List[DataLoader]]: + """ + Returns the training DataLoader. + """ return self.dataloader("train", shuffle=True, **kwargs) def val_dataloader(self, *args, **kwargs) -> Union[DataLoader, List[DataLoader]]: + """ + Returns the validation DataLoader. + """ return self.dataloader("validation", shuffle=False, **kwargs) def test_dataloader(self, *args, **kwargs) -> Union[DataLoader, List[DataLoader]]: + """ + Returns the test DataLoader. + """ return self.dataloader("test", shuffle=False, **kwargs) - def _process_data(self, subset_id, data): + def _process_data(self, subset_id: int, data: dict) -> dict: + """ + Processes data from a subset. + + Args: + subset_id (int): Index of the subset. + data (dict): Data from the subset. + + Returns: + dict: Processed data with 'features', 'labels', and 'ident' keys. + """ return dict( features=data["features"], labels=data["labels"], ident=data["ident"] ) def setup_processed(self): + """ + Placeholder for setup logic after data processing. + """ pass @property - def processed_file_names(self): + def processed_file_names(self) -> List[str]: + """ + Returns the list of processed file names. + """ return ["test.pt", "train.pt", "validation.pt"] @property - def label_number(self): + def label_number(self) -> int: + """ + Returns the number of labels from the first subset. + """ return self.subsets[0].label_number @property def limits(self): + """ + Returns None, assuming no limits on data slicing. + """ return None diff --git a/chebai/preprocessing/datasets/chebi.py b/chebai/preprocessing/datasets/chebi.py index 93d7be65..41999551 100644 --- a/chebai/preprocessing/datasets/chebi.py +++ b/chebai/preprocessing/datasets/chebi.py @@ -11,11 +11,9 @@ import os import pickle -import queue -import random from abc import ABC from collections import OrderedDict -from typing import List, Union +from typing import Any, Dict, Generator, List, Optional, Tuple, Union import fastobo import networkx as nx @@ -125,16 +123,20 @@ class _ChEBIDataExtractor(XYBaseDataModule, ABC): **kwargs: Additional keyword arguments (passed to XYBaseDataModule). Attributes: - single_class (int): The ID of the single class to predict. - chebi_version_train (int): The version of ChEBI to use for training and validation. + single_class (Optional[int]): The ID of the single class to predict. + chebi_version_train (Optional[int]): The version of ChEBI to use for training and validation. dynamic_data_split_seed (int): The seed for random data splitting, default is 42. - dynamic_df_train (pd.DataFrame): DataFrame to store the training data split. - dynamic_df_test (pd.DataFrame): DataFrame to store the test data split. - dynamic_df_val (pd.DataFrame): DataFrame to store the validation data split. + dynamic_df_train (Optional[pd.DataFrame]): DataFrame to store the training data split. + dynamic_df_test (Optional[pd.DataFrame]): DataFrame to store the test data split. + dynamic_df_val (Optional[pd.DataFrame]): DataFrame to store the validation data split. + splits_file_path (Optional[str]): Path to csv file containing split assignments. """ def __init__( - self, chebi_version_train: int = None, single_class: int = None, **kwargs + self, + chebi_version_train: Optional[int] = None, + single_class: Optional[int] = None, + **kwargs, ): # predict only single class (given as id of one of the classes present in the raw data set) self.single_class = single_class @@ -163,15 +165,15 @@ def __init__( ) @staticmethod - def _validate_splits_file_path(splits_file_path=None): + def _validate_splits_file_path(splits_file_path: Optional[str]) -> Optional[str]: """ Validates the provided splits file path. Args: - splits_file_path (str or None): Path to the splits CSV file. + splits_file_path (Optional[str]): Path to the splits CSV file. Returns: - str or None: Validated splits file path if checks pass, None if splits_file_path is None. + Optional[str]: Validated splits file path if checks pass, None if splits_file_path is None. Raises: FileNotFoundError: If the splits file does not exist. @@ -203,7 +205,7 @@ def _validate_splits_file_path(splits_file_path=None): return splits_file_path - def extract_class_hierarchy(self, chebi_path): + def extract_class_hierarchy(self, chebi_path: str) -> nx.DiGraph: """ Extracts the class hierarchy from the ChEBI ontology. @@ -230,9 +232,20 @@ def extract_class_hierarchy(self, chebi_path): def select_classes(self, g, split_name, *args, **kwargs): raise NotImplementedError - def graph_to_raw_dataset(self, g, split_name=None): - """Preparation step before creating splits, uses graph created by extract_class_hierarchy(), - split_name is only relevant, if a separate train_version is set""" + def graph_to_raw_dataset( + self, g: nx.DiGraph, split_name: Optional[str] = None + ) -> pd.DataFrame: + """ + Preparation step before creating splits, uses graph created by extract_class_hierarchy(), + split_name is only relevant, if a separate train_version is set. + + Args: + g (nx.DiGraph): The class hierarchy graph. + split_name (Optional[str], optional): Name of the split. Defaults to None. + + Returns: + pd.DataFrame: The raw dataset created from the graph. + """ smiles = nx.get_node_attributes(g, "smiles") names = nx.get_node_attributes(g, "name") @@ -259,13 +272,27 @@ def graph_to_raw_dataset(self, g, split_name=None): data = data[data.iloc[:, 3:].any(axis=1)] return data - def save_raw(self, data: pd.DataFrame, filename: str): + def save_raw(self, data: pd.DataFrame, filename: str) -> None: + """ + Save the raw dataset to a pickle file. + + Args: + data (pd.DataFrame): The raw dataset to be saved. + filename (str): The filename for the pickle file. + """ pd.to_pickle(data, open(os.path.join(self.raw_dir, filename), "wb")) - def save_processed(self, data: pd.DataFrame, filename: str): + def save_processed(self, data: pd.DataFrame, filename: str) -> None: + """ + Save the processed dataset to a pickle file. + + Args: + data (pd.DataFrame): The processed dataset to be saved. + filename (str): The filename for the pickle file. + """ pd.to_pickle(data, open(os.path.join(self.processed_dir_main, filename), "wb")) - def _load_dict(self, input_file_path): + def _load_dict(self, input_file_path: str) -> Generator[Dict[str, Any], None, None]: """ Loads a dictionary from a pickled file, yielding individual dictionaries for each row. @@ -273,7 +300,7 @@ def _load_dict(self, input_file_path): input_file_path (str): The path to the file. Yields: - dict: The dictionary, keys are `features`, `labels` and `ident`. + Dict[str, Any]: The dictionary, keys are `features`, `labels` and `ident`. """ with open(input_file_path, "rb") as input_file: df = pd.read_pickle(input_file) @@ -287,14 +314,31 @@ def _load_dict(self, input_file_path): yield dict(features=row[2], labels=labels, ident=row[0]) @staticmethod - def _get_data_size(input_file_path): + def _get_data_size(input_file_path: str) -> int: + """ + Get the size of the data from a pickled file. + + Args: + input_file_path (str): The path to the file. + + Returns: + int: The size of the data. + """ with open(input_file_path, "rb") as f: return len(pd.read_pickle(f)) def _setup_pruned_test_set( self, df_test_chebi_version: pd.DataFrame ) -> pd.DataFrame: - """Create a test set with the same leaf nodes, but use only classes that appear in the training set""" + """ + Create a test set with the same leaf nodes, but use only classes that appear in the training set. + + Args: + df_test_chebi_version (pd.DataFrame): The test dataset. + + Returns: + pd.DataFrame: The pruned test dataset. + """ # TODO: find a more efficient way to do this filename_old = "classes.txt" # filename_new = f"classes_v{self.chebi_version_train}.txt" @@ -338,7 +382,19 @@ def _setup_pruned_test_set( # ) return df_test_chebi_version - def setup_processed(self): + def setup_processed(self) -> None: + """ + Transform and prepare processed data for the ChEBI dataset. + + This method sets up the processed data directories and files based on the ChEBI version + and train version (if specified). It ensures that the required processed data files exist + by loading raw data, transforming it into processed format, and saving it. + + It also handles special cases, such as generating a pruned test set if `chebi_version_train` + is specified and the test set does not already exist. This pruned test set includes only + classes that appear in the training set. + + """ print("Transform data") os.makedirs(self.processed_dir, exist_ok=True) # -------- Commented the code for Data Handling Restructure for Issue No.10 @@ -407,7 +463,9 @@ def setup_processed(self): print("Call the setup method related to it") self._chebi_version_train_obj.setup() - def get_test_split(self, df: pd.DataFrame, seed: int = None): + def get_test_split( + self, df: pd.DataFrame, seed: Optional[int] = None + ) -> Tuple[pd.DataFrame, pd.DataFrame]: """ Split the input DataFrame into training and testing sets based on multilabel stratified sampling. @@ -415,22 +473,16 @@ def get_test_split(self, df: pd.DataFrame, seed: int = None): in the training and testing sets is approximately the same. The split is based on the "labels" column in the DataFrame. - Parameters: - ---------- - df : pd.DataFrame - The input DataFrame containing the data to be split. It must contain a column named "labels" - with the multilabel data. - - seed : int, optional - The random seed to be used for reproducibility. Default is None. + Args: + df (pd.DataFrame): The input DataFrame containing the data to be split. It must contain a column + named "labels" with the multilabel data. + seed (int, optional): The random seed to be used for reproducibility. Default is None. Returns: - ------- - df_train : pd.DataFrame - The training set split from the input DataFrame. + Tuple[pd.DataFrame, pd.DataFrame]: A tuple containing the training set and testing set DataFrames. - df_test : pd.DataFrame - The testing set split from the input DataFrame. + Raises: + ValueError: If the DataFrame does not contain a column named "labels". """ print("\nGet test data split") @@ -449,7 +501,7 @@ def get_test_split(self, df: pd.DataFrame, seed: int = None): def get_train_val_splits_given_test( self, df: pd.DataFrame, test_df: pd.DataFrame, seed: int = None - ): + ) -> Union[Dict[str, pd.DataFrame], Tuple[pd.DataFrame, pd.DataFrame]]: """ Split the dataset into train and validation sets, given a test set. Use test set (e.g., loaded from another chebi version or generated in get_test_split), to avoid overlap @@ -457,10 +509,13 @@ def get_train_val_splits_given_test( Args: df (pd.DataFrame): The original dataset. test_df (pd.DataFrame): The test dataset. + seed (int, optional): The random seed to be used for reproducibility. Default is None. Returns: - dict: A dictionary containing the train and validation sets. - The keys are the names of the train and validation sets, and the values are the corresponding DataFrames. + Union[Dict[str, pd.DataFrame], Tuple[pd.DataFrame, pd.DataFrame]]: A dictionary containing train and + validation sets if self.use_inner_cross_validation is True, otherwise a tuple containing the train + and validation DataFrames. The keys are the names of the train and validation sets, and the values + are the corresponding DataFrames. """ print(f"Split dataset into train / val with given test set") @@ -506,7 +561,13 @@ def get_train_val_splits_given_test( return df_train, df_validation @property - def processed_dir_main(self): + def processed_dir_main(self) -> str: + """ + Return the main directory path for processed data. + + Returns: + str: The path to the main processed data directory. + """ return os.path.join( self.base_dir, self._name, @@ -514,7 +575,13 @@ def processed_dir_main(self): ) @property - def processed_dir(self): + def processed_dir(self) -> str: + """ + Return the directory path for processed data. + + Returns: + str: The path to the processed data directory. + """ res = os.path.join( self.processed_dir_main, *self.identifier, @@ -525,11 +592,23 @@ def processed_dir(self): return os.path.join(res, f"single_{self.single_class}") @property - def base_dir(self): + def base_dir(self) -> str: + """ + Return the base directory path for data. + + Returns: + str: The base directory path for data. + """ return os.path.join("data", f"chebi_v{self.chebi_version}") @property def processed_file_names_dict(self) -> dict: + """ + Return a dictionary of processed file names. + + Returns: + dict: A dictionary where keys are file names and values are paths. + """ train_v_str = ( f"_v{self.chebi_version_train}" if self.chebi_version_train else "" ) @@ -550,6 +629,12 @@ def processed_file_names_dict(self) -> dict: @property def raw_file_names_dict(self) -> dict: + """ + Return a dictionary of raw file names. + + Returns: + dict: A dictionary where keys are file names and values are paths. + """ train_v_str = ( f"_v{self.chebi_version_train}" if self.chebi_version_train else "" ) @@ -571,14 +656,26 @@ def raw_file_names_dict(self) -> dict: return res @property - def processed_file_names(self): + def processed_file_names(self) -> List[str]: + """ + Return a list of processed file names. + + Returns: + List[str]: A list containing processed file names. + """ return list(self.processed_file_names_dict.values()) @property - def raw_file_names(self): + def raw_file_names(self) -> List[str]: + """ + Return a list of raw file names. + + Returns: + List[str]: A list containing raw file names. + """ return list(self.raw_file_names_dict.values()) - def _load_chebi(self, version: int): + def _load_chebi(self, version: int) -> str: """ Load the ChEBI ontology file. @@ -599,7 +696,7 @@ def _load_chebi(self, version: int): open(chebi_path, "wb").write(r.content) return chebi_path - def prepare_data(self, *args, **kwargs): + def prepare_data(self, *args: Any, **kwargs: Any) -> None: """ Prepares the data for the Chebi dataset. @@ -677,8 +774,20 @@ def prepare_data(self, *args, **kwargs): # Generate the "chebi_version_train" data if it doesn't exist self._chebi_version_train_obj.prepare_data(*args, **kwargs) - def _generate_dynamic_splits(self): - """Generate data splits during run-time and saves in class variables""" + def _generate_dynamic_splits(self) -> None: + """ + Generate data splits during runtime and save them in class variables. + + This method loads encoded data derived from either `chebi_version` or `chebi_version_train` + and generates train, validation, and test splits based on the loaded data. + If `chebi_version_train` is specified, the test set is pruned to include only labels that + exist in `chebi_version_train`. + + Raises: + FileNotFoundError: If the required data file (`data.pt`) for either `chebi_version` or `chebi_version_train` + does not exist. It advises calling `prepare_data` or `setup` methods to generate + the dataset files. + """ print("Generate dynamic splits...") # Load encoded data derived from "chebi_version" try: @@ -748,7 +857,15 @@ def _generate_dynamic_splits(self): self.dynamic_df_val = df_val self.dynamic_df_test = df_test - def _retrieve_splits_from_csv(self): + def _retrieve_splits_from_csv(self) -> None: + """ + Retrieve previously saved data splits from splits.csv file or from provided file path. + + This method loads the splits.csv file located at `self.splits_file_path`. + It then loads the encoded data (`data.pt`) derived from `chebi_version` and filters + it based on the IDs retrieved from splits.csv to reconstruct the train, validation, + and test splits. + """ print(f"Loading splits from {self.splits_file_path}...") splits_df = pd.read_csv(self.splits_file_path) @@ -771,7 +888,18 @@ def _retrieve_splits_from_csv(self): ] @property - def dynamic_split_dfs(self): + def dynamic_split_dfs(self) -> Dict[str, pd.DataFrame]: + """ + Property to retrieve dynamic train, validation, and test splits. + + This property checks if dynamic data splits (`dynamic_df_train`, `dynamic_df_val`, `dynamic_df_test`) + are already loaded. If any of them is None, it either generates them dynamically or retrieves them + from data file with help of pre-existing Split csv file (`splits_file_path`) containing splits assignments. + + Returns: + dict: A dictionary containing the dynamic train, validation, and test DataFrames. + Keys are 'train', 'validation', and 'test'. + """ if any( split is None for split in [ @@ -792,19 +920,21 @@ def dynamic_split_dfs(self): "test": self.dynamic_df_test, } - def load_processed_data(self, kind: str = None, filename: str = None) -> List: + def load_processed_data( + self, kind: Optional[str] = None, filename: Optional[str] = None + ) -> List[Dict[str, Any]]: """ Load processed data from a file. Args: - kind (str, optional): The kind of dataset to load such as "train", "val" or "test". Defaults to None. + kind (str, optional): The kind of dataset to load such as "train", "val", or "test". Defaults to None. filename (str, optional): The name of the file to load the dataset from. Defaults to None. Returns: - List: The loaded processed data. + List[Dict[str, Any]] : The loaded processed data. Raises: - ValueError: If both kind and filename are None. + KeyError: If specified kind key doesn't exist. FileNotFoundError: If the specified file does not exist. """ if kind is None and filename is None: @@ -859,25 +989,37 @@ class ChEBIOverX(_ChEBIDataExtractor): THRESHOLD (None): The threshold for selecting classes. """ - LABEL_INDEX = 3 - SMILES_INDEX = 2 - READER = dr.ChemDataReader - THRESHOLD = None + LABEL_INDEX: int = 3 + SMILES_INDEX: int = 2 + READER: dr.ChemDataReader = dr.ChemDataReader + THRESHOLD: int = None @property - def label_number(self): + def label_number(self) -> int: + """ + Returns the number of labels in the dataset. + + Returns: + int: The number of labels. + """ return 854 @property - def _name(self): + def _name(self) -> str: + """ + Returns the name of the dataset. + + Returns: + str: The dataset name. + """ return f"ChEBI{self.THRESHOLD}" - def select_classes(self, g, split_name, *args, **kwargs): + def select_classes(self, g: nx.Graph, split_name: str, *args, **kwargs) -> List: """ Selects classes from the ChEBI dataset. Args: - g (Graph): The graph representing the dataset. + g (nx.Graph): The graph representing the dataset. split_name (str): The name of the split. *args: Additional arguments (not used). **kwargs: Additional keyword arguments (not used). @@ -911,44 +1053,126 @@ def select_classes(self, g, split_name, *args, **kwargs): class ChEBIOverXDeepSMILES(ChEBIOverX): - READER = dr.DeepChemDataReader + """ + A class for extracting data from the ChEBI dataset with DeepChem SMILES reader. + + Inherits from ChEBIOverX. + + Attributes: + READER (DeepChemDataReader): The reader used for reading the dataset (DeepChem SMILES). + """ + + READER: dr.DeepChemDataReader = dr.DeepChemDataReader class ChEBIOverXSELFIES(ChEBIOverX): - READER = dr.SelfiesReader + """ + A class for extracting data from the ChEBI dataset with SELFIES reader. + + Inherits from ChEBIOverX. + + Attributes: + READER (SelfiesReader): The reader used for reading the dataset (SELFIES). + """ + + READER: dr.SelfiesReader = dr.SelfiesReader class ChEBIOver100(ChEBIOverX): - THRESHOLD = 100 + """ + A class for extracting data from the ChEBI dataset with a threshold of 100 for selecting classes. - def label_number(self): + Inherits from ChEBIOverX. + + Attributes: + THRESHOLD (int): The threshold for selecting classes (100). + """ + + THRESHOLD: int = 100 + + def label_number(self) -> int: + """ + Returns the number of labels in the dataset. + + Overrides the base class method to return the correct number of labels for this threshold. + + Returns: + int: The number of labels. + """ return 854 class ChEBIOver50(ChEBIOverX): - THRESHOLD = 50 + """ + A class for extracting data from the ChEBI dataset with a threshold of 50 for selecting classes. - def label_number(self): + Inherits from ChEBIOverX. + + Attributes: + THRESHOLD (int): The threshold for selecting classes (50). + """ + + THRESHOLD: int = 50 + + def label_number(self) -> int: + """ + Returns the number of labels in the dataset. + + Overrides the base class method to return the correct number of labels for this threshold. + + Returns: + int: The number of labels. + """ return 1332 class ChEBIOver100DeepSMILES(ChEBIOverXDeepSMILES, ChEBIOver100): + """ + A class for extracting data from the ChEBI dataset with DeepChem SMILES reader and a threshold of 100. + + Inherits from ChEBIOverXDeepSMILES and ChEBIOver100. + """ + pass class ChEBIOver100SELFIES(ChEBIOverXSELFIES, ChEBIOver100): + """ + A class for extracting data from the ChEBI dataset with SELFIES reader and a threshold of 100. + + Inherits from ChEBIOverXSELFIES and ChEBIOver100. + """ + pass class ChEBIOverXPartial(ChEBIOverX): - """Dataset that doesn't use the full ChEBI, but extracts a part of ChEBI (subclasses of a given top class)""" + """ + Dataset that doesn't use the full ChEBI, but extracts a part of ChEBI (subclasses of a given top class) + + Attributes: + top_class_id (int): The ID of the top class from which to extract subclasses. + """ def __init__(self, top_class_id: int, **kwargs): - self.top_class_id = top_class_id + """ + Initializes the ChEBIOverXPartial dataset. + + Args: + top_class_id (int): The ID of the top class from which to extract subclasses. + **kwargs: Additional keyword arguments passed to the superclass initializer. + """ + self.top_class_id: int = top_class_id super().__init__(**kwargs) @property - def processed_dir_main(self): + def processed_dir_main(self) -> str: + """ + Returns the main processed data directory specific to the top class. + + Returns: + str: The processed data directory path. + """ return os.path.join( self.base_dir, self._name, @@ -956,7 +1180,16 @@ def processed_dir_main(self): "processed", ) - def extract_class_hierarchy(self, chebi_path): + def extract_class_hierarchy(self, chebi_path: str) -> nx.DiGraph: + """ + Extracts a subset of ChEBI based on subclasses of the top class ID. + + Args: + chebi_path (str): The file path to the ChEBI ontology file. + + Returns: + nx.DiGraph: The extracted class hierarchy as a directed graph. + """ with open(chebi_path, encoding="utf-8") as chebi: chebi = "\n".join(l for l in chebi if not l.startswith("xref:")) elements = [ @@ -976,6 +1209,13 @@ def extract_class_hierarchy(self, chebi_path): class ChEBIOver50Partial(ChEBIOverXPartial, ChEBIOver50): + """ + Dataset that extracts a part of ChEBI based on subclasses of a given top class, + with a threshold of 50 for selecting classes. + + Inherits from ChEBIOverXPartial and ChEBIOver50. + """ + pass @@ -991,11 +1231,20 @@ class JCIExtSelfies(JCIExtendedBase): READER = dr.SelfiesReader -def chebi_to_int(s): +def chebi_to_int(s: str) -> int: + """ + Converts a ChEBI term string representation to an integer ID. + + Args: + - s (str): A ChEBI term string, e.g., "CHEBI:12345". + + Returns: + - int: The integer ID extracted from the ChEBI term string. + """ return int(s[s.index(":") + 1 :]) -def term_callback(doc): +def term_callback(doc) -> dict: """ Extracts information from a ChEBI term document. This function takes a ChEBI term document as input and extracts relevant information such as the term ID, parents, diff --git a/chebai/preprocessing/datasets/pubchem.py b/chebai/preprocessing/datasets/pubchem.py index 5b18add0..5ba76cc4 100644 --- a/chebai/preprocessing/datasets/pubchem.py +++ b/chebai/preprocessing/datasets/pubchem.py @@ -14,6 +14,7 @@ import tempfile import time from datetime import datetime +from typing import Generator, List, Optional, Tuple, Type import numpy as np import pandas as pd @@ -37,13 +38,23 @@ class PubChem(XYBaseDataModule): + """ + Dataset module for PubChem compounds. + """ + SMILES_INDEX = 0 LABEL_INDEX = 1 FULL = 0 UNLABELED = True READER = dr.ChemDataReader - def __init__(self, *args, k=100000, **kwargs): + def __init__(self, *args, k: Optional[int] = 100000, **kwargs): + """ + Args: + k (Optional[int]): Number of samples to use. Set to `PubChem.FULL` for full dataset. + *args: Additional arguments for superclass initialization. + **kwargs: Additional keyword arguments for superclass initialization. + """ self._k = k current_year = datetime.today().year current_month = datetime.today().month @@ -52,32 +63,58 @@ def __init__(self, *args, k=100000, **kwargs): super(PubChem, self).__init__(*args, **kwargs) @property - def _name(self): + def _name(self) -> str: + """ + Returns: + str: Name of the dataset. + """ return f"Pubchem" @property - def identifier(self): + def identifier(self) -> tuple: + """ + Returns: + tuple: Tuple containing reader name and split label. + """ return self.reader.name(), self.split_label @property - def split_label(self): + def split_label(self) -> str: + """ + Returns: + str: Label indicating the split of the dataset ('full' or a specific number). + """ if self._k and self._k != self.FULL: return str(self._k) else: return "full" @property - def raw_dir(self): + def raw_dir(self) -> str: + """ + Returns: + str: Directory path where raw data is stored. + """ return os.path.join(self.base_dir, "raw", self.split_label) @staticmethod - def _load_dict(input_file_path): + def _load_dict(input_file_path: str) -> Generator[dict, None, None]: + """ + Args: + input_file_path (str): Path to the input file. + + Yields: + dict: Dictionary containing 'features', 'labels' (None), and 'ident' fields. + """ with open(input_file_path, "r") as input_file: for row in input_file: ident, smiles = row.split("\t") yield dict(features=smiles, labels=None, ident=ident) def download(self): + """ + Downloads PubChem data based on `_k` parameter. + """ if not os.path.isfile(os.path.join(self.raw_dir, "smiles.txt")): if self._k == PubChem.FULL: print("Download from", self.pubchem_url) @@ -110,7 +147,9 @@ def download(self): f_out.writelines([l for i, l in selected_lines]) def setup_processed(self): - # Collect token distribution + """ + Prepares processed data and saves them as Torch tensors. + """ filename = os.path.join(self.raw_dir, self.raw_file_names[0]) print("Load data from file", filename) data = self._load_data_from_file(filename) @@ -125,14 +164,25 @@ def setup_processed(self): self.reader.on_finish() @property - def raw_file_names(self): + def raw_file_names(self) -> List[str]: + """ + Returns: + List[str]: List of raw data file names. + """ return ["smiles.txt"] @property - def processed_file_names(self): + def processed_file_names(self) -> List[str]: + """ + Returns: + List[str]: List of processed data file names. + """ return ["test.pt", "train.pt", "validation.pt"] def prepare_data(self, *args, **kwargs): + """ + Checks for raw data and downloads if necessary. + """ print("Check for raw data in", self.raw_dir) if any( not os.path.isfile(os.path.join(self.raw_dir, f)) @@ -144,24 +194,45 @@ def prepare_data(self, *args, **kwargs): class PubChemDissimilar(PubChem): - """Subset of PubChem, but choosing the most dissimilar molecules (according to fingerprint)""" + """ + Subset of PubChem, but choosing the most dissimilar molecules (according to fingerprint) + """ def __init__( - self, *args, k=100000, n_random_subsets=100, random_size_factor=5, **kwargs + self, + *args, + k: Optional[int] = 100000, + n_random_subsets: Optional[int] = 100, + random_size_factor: Optional[int] = 5, + **kwargs, ): - """k: number of entries in this dataset, - n_random_subsets: number of subsets of random data from which to draw - the most dissimilar molecules, - random_size_factor: size of random subsets (in total) in relation to k""" + """ + Args: + k (Optional[int]): Number of entries in this dataset. + n_random_subsets (Optional[int]): Number of subsets of random data to draw most dissimilar molecules from. + random_size_factor (Optional[int]): Size of random subsets in relation to k. + *args: Additional arguments for superclass initialization. + **kwargs: Additional keyword arguments for superclass initialization. + """ self.n_random_subsets = n_random_subsets self.random_size_factor = random_size_factor super(PubChemDissimilar, self).__init__(*args, k=k, **kwargs) @property - def _name(self): + def _name(self) -> str: + """ + Returns: + str: Name of the dataset. + """ return f"PubchemDissimilar" def download(self): + """ + Downloads the PubChemDissimilar dataset. + + If `k` is set to `PubChem.FULL`, downloads the full dataset. + Otherwise, generates random subsets to select the most dissimilar molecules based on fingerprints. + """ if self._k == PubChem.FULL: super().download() else: @@ -217,21 +288,31 @@ def download(self): class PubChemKMeans(PubChem): + """ + Dataset class representing a subset of PubChem dataset clustered using K-Means algorithm. + """ def __init__( self, *args, - n_clusters=1e4, - random_size=1e6, + n_clusters: int = 1e4, + random_size: int = 1e6, exclude_data_from: _ChEBIDataExtractor = None, - validation_size_limit=4000, - include_min_n_clusters=100, + validation_size_limit: int = 4000, + include_min_n_clusters: int = 100, **kwargs, ): - """k: number of entries in this dataset, - n_random_subsets: number of subsets of random data from which to draw - the most dissimilar molecules, - random_size_factor: size of random subsets (in total) in relation to k""" + """ + Args: + n_clusters (int): Number of clusters to create using K-Means. + random_size (int): Size of random dataset to download. + exclude_data_from (_ChEBIDataExtractor): Dataset extractor to exclude data clusters from. + validation_size_limit (int): Size limit for validation dataset. + include_min_n_clusters (int): Minimum number of clusters to include after exclusion. + + *args: Additional arguments for superclass initialization. + **kwargs: Additional keyword arguments for superclass initialization. + """ self.n_clusters = int(n_clusters) self.exclude_data_from = exclude_data_from self.validation_size_limit = validation_size_limit @@ -244,22 +325,38 @@ def __init__( self._cluster_centers_superclustered = None @property - def _name(self): + def _name(self) -> str: + """ + Returns: + str: Name of the dataset. + """ return f"PubchemKMeans" @property - def split_label(self): + def split_label(self) -> str: + """ + Returns: + str: Label describing the split based on number of clusters. + """ if self._k and self._k != self.FULL: return f"{self.n_clusters}_centers_out_of_{self._k}" else: return f"{self.n_clusters}_centers_out_of_full" @property - def raw_file_names(self): + def raw_file_names(self) -> List[str]: + """ + Returns: + List[str]: List of raw file names expected in the raw directory. + """ return ["train.txt", "validation.txt", "test.txt"] @property - def fingerprints(self): + def fingerprints(self) -> pd.DataFrame: + """ + Returns: + pd.DataFrame: DataFrame containing SMILES and corresponding fingerprints. + """ if self._fingerprints is None: fingerprints_path = os.path.join(self.raw_dir, "fingerprints.pkl") if not os.path.exists(fingerprints_path): @@ -288,7 +385,13 @@ def fingerprints(self): self._fingerprints = pd.read_pickle(open(fingerprints_path, "rb")) return self._fingerprints - def _build_clusters(self): + def _build_clusters(self) -> tuple[pd.DataFrame, pd.DataFrame]: + """ + Performs K-Means clustering on fingerprints and saves cluster information. + + Returns: + tuple: Tuple containing cluster centers DataFrame and clustered fingerprints DataFrame. + """ fingerprints_clustered_path = os.path.join( self.raw_dir, "fingerprints_clustered.pkl" ) @@ -319,7 +422,16 @@ def _build_clusters(self): return cluster_df, fingerprints_df - def _exclude_clusters(self, cluster_centers): + def _exclude_clusters(self, cluster_centers: pd.DataFrame) -> pd.DataFrame: + """ + Excludes clusters based on data from an exclusion dataset. + + Args: + cluster_centers (pd.DataFrame): DataFrame of cluster centers. + + Returns: + pd.DataFrame: DataFrame of filtered cluster centers. + """ exclusion_data_path = os.path.join(self.raw_dir, "exclusion_data_clustered.pkl") cluster_centers_np = np.array( [ @@ -377,7 +489,11 @@ def _exclude_clusters(self, cluster_centers): return cluster_centers @property - def cluster_centers(self): + def cluster_centers(self) -> pd.DataFrame: + """ + Returns: + pd.DataFrame: DataFrame of cluster centers. + """ cluster_centers_path = os.path.join(self.raw_dir, f"cluster_centers.pkl") if self._cluster_centers is None: if os.path.exists(cluster_centers_path): @@ -387,7 +503,11 @@ def cluster_centers(self): return self._cluster_centers @property - def fingerprints_clustered(self): + def fingerprints_clustered(self) -> pd.DataFrame: + """ + Returns: + pd.DataFrame: DataFrame of clustered fingerprints. + """ fingerprints_path = os.path.join(self.raw_dir, f"fingerprints_clustered.pkl") if self._fingerprints_clustered is None: if os.path.exists(fingerprints_path): @@ -399,7 +519,11 @@ def fingerprints_clustered(self): return self._fingerprints_clustered @property - def cluster_centers_superclustered(self): + def cluster_centers_superclustered(self) -> pd.DataFrame: + """ + Returns: + pd.DataFrame: DataFrame of superclustered cluster centers. + """ cluster_centers_path = os.path.join( self.raw_dir, f"cluster_centers_superclustered.pkl" ) @@ -434,6 +558,9 @@ def cluster_centers_superclustered(self): return self._cluster_centers_superclustered def download(self): + """ + Downloads the PubChemKMeans dataset. + """ if self._k == PubChem.FULL: super().download() else: @@ -462,77 +589,188 @@ def download(self): class PubChemDissimilarSMILES(PubChemDissimilar): - READER = dr.ChemDataReader + """ + Subset of PubChem, selecting most dissimilar molecules based on fingerprints. + + Inherits from PubChemDissimilar. + + Attributes: + READER (type): Data reader type for chemical data. + """ + + READER: Type[dr.ChemDataReader] = dr.ChemDataReader class SWJPreChem(PubChem): - UNLABELED = True + """ + Subset of PubChem with unlabeled data, specific to SWJPre. + + Inherits from PubChem. + + Attributes: + UNLABELED (bool): Indicates if the data is unlabeled. + _name (str): Name of the dataset. + """ + + UNLABELED: bool = True @property - def _name(self): + def _name(self) -> str: + """ + Returns the name of the dataset. + """ return f"SWJpre" def download(self): + """ + Raises an exception since required raw files are not found. + """ raise Exception("Required raw files not found") @property - def identifier(self): + def identifier(self) -> Tuple[str]: + """ + Returns the identifier for the dataset. + """ return (self.reader.name(),) @property - def raw_dir(self): + def raw_dir(self) -> str: + """ + Returns the directory path for raw data. + """ return os.path.join("data", self._name, "raw") class SWJSelfies(SWJPreChem): - READER = dr.SelfiesReader + """ + Subset of SWJPreChem using SelfiesReader for data reading. + + Inherits from SWJPreChem. + + Attributes: + READER (type): Data reader type for chemical data (SelfiesReader). + """ + + READER: Type[dr.SelfiesReader] = dr.SelfiesReader class PubchemChem(PubChem): - READER = dr.ChemDataReader + """ + Subset of PubChem using ChemDataReader for data reading. + + Inherits from PubChem. + + Attributes: + READER (type): Data reader type for chemical data (ChemDataReader). + """ + + READER: Type[dr.ChemDataReader] = dr.ChemDataReader @property - def label_number(self): + def label_number(self) -> int: + """ + Returns the label number. + """ return -1 class PubchemBPE(PubChem): - READER = dr.ChemBPEReader + """ + Subset of PubChem using ChemBPEReader for data reading. + + Inherits from PubChem. + + Attributes: + READER (type): Data reader type for chemical data (ChemBPEReader). + """ + + READER: Type[dr.ChemBPEReader] = dr.ChemBPEReader @property - def label_number(self): + def label_number(self) -> int: + """ + Returns the label number. + """ return -1 class SWJChem(SWJPreChem): - READER = dr.ChemDataUnlabeledReader + """ + Subset of SWJPreChem using ChemDataUnlabeledReader for data reading. + + Inherits from SWJPreChem. + + Attributes: + READER (type): Data reader type for chemical data (ChemDataUnlabeledReader). + """ + + READER: Type[dr.ChemDataUnlabeledReader] = dr.ChemDataUnlabeledReader @property - def label_number(self): + def label_number(self) -> int: + """ + Returns the label number. + """ return -1 class SWJBPE(SWJPreChem): - READER = dr.ChemBPEReader + """ + Subset of SWJPreChem using ChemBPEReader for data reading. + + Inherits from SWJPreChem. + + Attributes: + READER (type): Data reader type for chemical data (ChemBPEReader). + """ + + READER: Type[dr.ChemBPEReader] = dr.ChemBPEReader @property - def label_number(self): + def label_number(self) -> int: + """ + Returns the label number. + """ return -1 class PubChemTokens(PubChem): - READER = dr.ChemDataReader + """ + Subset of PubChem using ChemDataReader for data reading. + + Inherits from PubChem. + + Attributes: + READER (type): Data reader type for chemical data (ChemDataReader). + """ + + READER: Type[dr.ChemDataReader] = dr.ChemDataReader class Hazardous(SWJChem): - READER = dr.ChemDataUnlabeledReader + """ + Subset of SWJChem for hazardous compounds. + + Inherits from SWJChem. + + Attributes: + READER (type): Data reader type for chemical data (ChemDataUnlabeledReader). + """ + + READER: Type[dr.ChemDataUnlabeledReader] = dr.ChemDataUnlabeledReader @property - def _name(self): + def _name(self) -> str: + """ + Returns the name of the dataset. + """ return f"PubChemHazardous" def setup_processed(self): - # Collect token distribution + """ + Sets up the processed data. + """ filename = os.path.join(self.raw_dir, self.raw_file_names[0]) print("Load data from file", filename) data = self._load_data_from_file(filename) @@ -540,10 +778,16 @@ def setup_processed(self): self.reader.on_finish() - def processed_file_names(self): + def processed_file_names(self) -> List[str]: + """ + Returns the list of processed file names. + """ return ["all.pt"] def download(self): + """ + Downloads hazardous compound data from PubChem. + """ # requires the / a hazardous subset from pubchem, e.g. obtained by entering # "PubChem: PubChem Compound TOC: GHS Classification" in the pubchem search -> download -> csv csv_path = os.path.join(self.raw_dir, "pubchem_hazardous_compound_list.csv") @@ -560,35 +804,92 @@ def download(self): class SWJPreChem(PubChem): - UNLABELED = True + """ + Subset of PubChem specific to SWJpre with unlabeled data. + + Inherits from PubChem. + + Attributes: + UNLABELED (bool): Indicates if the data is unlabeled. + _name (str): Name of the dataset. + """ + + UNLABELED: bool = True @property - def _name(self): + def _name(self) -> str: + """ + Returns the name of the dataset. + + Returns: + str: Name of the dataset. + """ return f"SWJpre" - def download(self): + def download(self) -> None: + """ + Raises an exception since required raw files are not found. + + Raises: + Exception: If required raw files are not found. + """ raise Exception("Required raw files not found") @property - def identifier(self): + def identifier(self) -> Tuple[str]: + """ + Returns the identifier for the dataset. + + Returns: + tuple: A tuple containing the name of the reader. + """ return (self.reader.name(),) class LabeledUnlabeledMixed(XYBaseDataModule): - READER = dr.ChemDataReader + """ + Mixed dataset combining labeled and unlabeled data. + + Inherits from XYBaseDataModule. + + Attributes: + READER (type): Data reader type for chemical data (ChemDataReader). + """ + + READER: Type[dr.ChemDataReader] = dr.ChemDataReader def __init__( self, labeled: XYBaseDataModule, unlabeled: XYBaseDataModule, *args, **kwargs ): + """ + Args: + labeled (XYBaseDataModule): Labeled dataset module. + unlabeled (XYBaseDataModule): Unlabeled dataset module. + *args: Additional positional arguments. + **kwargs: Additional keyword arguments. + """ self.labeled = labeled self.unlabeled = unlabeled super().__init__(*args, **kwargs) @property - def _name(self): + def _name(self) -> str: + """ + Returns the name of the dataset. + """ return f"Mixed_{self.labeled._name}_{self.unlabeled._name}" - def dataloader(self, kind, **kwargs): + def dataloader(self, kind: str, **kwargs) -> DataLoader: + """ + Returns a dataloader for the specified kind. + + Args: + kind (str): Type of data (e.g., 'train', 'validation', 'test'). + **kwargs: Additional keyword arguments for DataLoader. + + Returns: + DataLoader: DataLoader instance. + """ labeled_data = torch.load( os.path.join(self.labeled.processed_dir, f"{kind}.pt") ) @@ -600,49 +901,112 @@ def dataloader(self, kind, **kwargs): unlabeled_data = unlabeled_data[: self.data_limit] return DataLoader( labeled_data + unlabeled_data, - collate_fn=self.reader.collater, + collate_fn=self.reader.collator, batch_size=self.batch_size, **kwargs, ) @property - def raw_file_names(self): + def raw_file_names(self) -> List[str]: + """ + Returns the list of raw file names (empty for mixed dataset). + """ return [] @property - def processed_file_names(self): + def processed_file_names(self) -> List[str]: + """ + Returns the list of processed file names. + """ return ["test.pt", "train.pt", "validation.pt"] def setup_processed(self): + """ + Sets up the processed data by setting up labeled and unlabeled datasets. + """ self.labeled.setup() self.unlabeled.setup() class PubToxAndChebiX(LabeledUnlabeledMixed): - READER = dr.ChemDataReader - CHEBI_X = ChEBIOverX + """ + Mixed dataset combining PubChem and ChEBI datasets. + + Inherits from LabeledUnlabeledMixed. + + Attributes: + READER (type): Data reader type for chemical data (ChemDataReader). + CHEBI_X (type): Specific ChEBI dataset type. + """ + + READER: Type[dr.ChemDataReader] = dr.ChemDataReader + CHEBI_X: Type[ChEBIOverX] = ChEBIOverX def __init__(self, *args, **kwargs): + """ + Args: + *args: Additional positional arguments. + **kwargs: Additional keyword arguments. + """ super().__init__( self.CHEBI_X(*args, **kwargs), PubchemChem(*args, **kwargs), *args, **kwargs ) @property - def _name(self): + def _name(self) -> str: + """ + Returns the name of the dataset. + """ return "PubToxU" + self.labeled._name class PubToxAndChebi100(PubToxAndChebiX): - CHEBI_X = ChEBIOver100 + """ + Mixed dataset combining PubChem and ChEBI datasets with over 100 entries. + + Inherits from PubToxAndChebiX. + + Attributes: + CHEBI_X (type): ChEBI dataset with over 100 entries. + """ + + CHEBI_X: Type[ChEBIOver100] = ChEBIOver100 class PubToxAndChebi50(PubToxAndChebiX): - CHEBI_X = ChEBIOver50 + """ + Mixed dataset combining PubChem and ChEBI datasets with over 50 entries. + + Inherits from PubToxAndChebiX. + + Attributes: + CHEBI_X (type): ChEBI dataset with over 50 entries. + """ + + CHEBI_X: Type[ChEBIOver50] = ChEBIOver50 class PubChemDeepSMILES(PubChem): - READER = dr.DeepChemDataReader + """ + Subset of PubChem using DeepChemDataReader for data reading. + + Inherits from PubChem. + + Attributes: + READER (type): Data reader type for chemical data (DeepChemDataReader). + """ + + READER: Type[dr.DeepChemDataReader] = dr.DeepChemDataReader class PubChemSELFIES(PubChem): - READER = dr.SelfiesReader + """ + Subset of PubChem using SelfiesReader for data reading. + + Inherits from PubChem. + + Attributes: + READER (type): Data reader type for chemical data (SelfiesReader). + """ + + READER: Type[dr.SelfiesReader] = dr.SelfiesReader diff --git a/chebai/preprocessing/datasets/tox21.py b/chebai/preprocessing/datasets/tox21.py index ba101ff5..4bdfbdee 100644 --- a/chebai/preprocessing/datasets/tox21.py +++ b/chebai/preprocessing/datasets/tox21.py @@ -1,25 +1,24 @@ import csv import gzip import os -import random import shutil import zipfile from tempfile import NamedTemporaryFile, TemporaryDirectory +from typing import Dict, Generator, List, Optional from urllib import request import numpy as np -import pysmiles import torch from rdkit import Chem from sklearn.model_selection import GroupShuffleSplit, train_test_split from chebai.preprocessing import reader as dr -from chebai.preprocessing.datasets.base import MergedDataset, XYBaseDataModule -from chebai.preprocessing.datasets.chebi import JCIExtendedTokenData -from chebai.preprocessing.datasets.pubchem import Hazardous +from chebai.preprocessing.datasets.base import XYBaseDataModule class Tox21MolNet(XYBaseDataModule): + """Data module for Tox21MolNet dataset.""" + HEADERS = [ "NR-AR", "NR-AR-LBD", @@ -36,22 +35,27 @@ class Tox21MolNet(XYBaseDataModule): ] @property - def _name(self): + def _name(self) -> str: + """Returns the name of the dataset.""" return "Tox21MN" @property - def label_number(self): + def label_number(self) -> int: + """Returns the number of labels.""" return 12 @property - def raw_file_names(self): + def raw_file_names(self) -> List[str]: + """Returns a list of raw file names.""" return ["tox21.csv"] @property - def processed_file_names(self): + def processed_file_names(self) -> List[str]: + """Returns a list of processed file names.""" return ["test.pt", "train.pt", "validation.pt"] - def download(self): + def download(self) -> None: + """Downloads and extracts the dataset.""" with NamedTemporaryFile("rb") as gout: request.urlretrieve( "https://deepchemdata.s3-us-west-1.amazonaws.com/datasets/tox21.csv.gz", @@ -61,7 +65,8 @@ def download(self): with open(os.path.join(self.raw_dir, "tox21.csv"), "wt") as fout: fout.write(gfile.read().decode()) - def setup_processed(self): + def setup_processed(self) -> None: + """Processes and splits the dataset.""" print("Create splits") data = self._load_data_from_file(os.path.join(self.raw_dir, f"tox21.csv")) groups = np.array([d["group"] for d in data]) @@ -111,7 +116,8 @@ def setup_processed(self): os.path.join(self.processed_dir, f"{k}.pt"), ) - def setup(self, **kwargs): + def setup(self, **kwargs) -> None: + """Sets up the dataset by downloading and processing if necessary.""" if any( not os.path.isfile(os.path.join(self.raw_dir, f)) for f in self.raw_file_names @@ -123,7 +129,15 @@ def setup(self, **kwargs): ): self.setup_processed() - def _load_dict(self, input_file_path): + def _load_data_from_file(self, input_file_path: str) -> List[Dict]: + """Loads data from a CSV file. + + Args: + input_file_path (str): Path to the CSV file. + + Returns: + List[Dict]: List of data dictionaries. + """ with open(input_file_path, "r") as input_file: reader = csv.DictReader(input_file) for row in reader: @@ -135,6 +149,8 @@ def _load_dict(self, input_file_path): class Tox21Challenge(XYBaseDataModule): + """Data module for Tox21Challenge dataset.""" + HEADERS = [ "NR-AR", "NR-AR-LBD", @@ -151,15 +167,18 @@ class Tox21Challenge(XYBaseDataModule): ] @property - def _name(self): + def _name(self) -> str: + """Returns the name of the dataset.""" return "Tox21Chal" @property - def label_number(self): + def label_number(self) -> int: + """Returns the number of labels.""" return 12 @property - def raw_file_names(self): + def raw_file_names(self) -> List[str]: + """Returns a list of raw file names.""" return [ "train.sdf", "validation.sdf", @@ -169,10 +188,12 @@ def raw_file_names(self): ] @property - def processed_file_names(self): + def processed_file_names(self) -> List[str]: + """Returns a list of processed file names.""" return ["test.pt", "train.pt", "validation.pt"] - def download(self): + def download(self) -> None: + """Downloads and extracts the dataset.""" self._retrieve_file( "https://tripod.nih.gov/tox21/challenge/download?id=tox21_10k_data_allsdf&sec=", "train.sdf", @@ -192,7 +213,16 @@ def download(self): "test_results.txt", ) - def _retrieve_file(self, url, target_file, compression=None): + def _retrieve_file( + self, url: str, target_file: str, compression: Optional[str] = None + ) -> None: + """Retrieves a file from a URL and saves it locally. + + Args: + url (str): The URL to download the file from. + target_file (str): The name of the target file. + compression (str, optional): Compression type. Defaults to None. + """ target_path = os.path.join(self.raw_dir, target_file) if not os.path.isfile(target_path): with NamedTemporaryFile("rb") as gout: @@ -213,7 +243,15 @@ def _retrieve_file(self, url, target_file, compression=None): assert len(files_in_zip) == 1 shutil.move(os.path.join(td.name, f), target_path) - def _load_data_from_file(self, path): + def _load_data_from_file(self, path: str) -> List[Dict]: + """Loads data from an SDF file. + + Args: + path (str): Path to the SDF file. + + Returns: + List[Dict]: List of data dictionaries. + """ sdf = Chem.SDMolSupplier(path) data = [] for mol in sdf: @@ -233,7 +271,8 @@ def _load_data_from_file(self, path): data.append(self.reader.to_data(d)) return data - def setup_processed(self): + def setup_processed(self) -> None: + """Processes and splits the dataset.""" for k in ("train", "validation"): d = self._load_data_from_file(os.path.join(self.raw_dir, f"{k}.sdf")) torch.save(d, os.path.join(self.processed_dir, f"{k}.pt")) @@ -259,7 +298,8 @@ def setup_processed(self): ] torch.save(test_data, os.path.join(self.processed_dir, f"test.pt")) - def setup(self, **kwargs): + def setup(self, **kwargs) -> None: + """Sets up the dataset by downloading and processing if necessary.""" if any( not os.path.isfile(os.path.join(self.raw_dir, f)) for f in self.raw_file_names @@ -271,7 +311,15 @@ def setup(self, **kwargs): ): self.setup_processed() - def _load_dict(self, input_file_path): + def _load_dict(self, input_file_path: str) -> Generator[Dict, None, None]: + """Loads data from a CSV file as a generator. + + Args: + input_file_path (str): Path to the CSV file. + + Yields: + Generator[Dict, None, None]: Generator of data dictionaries. + """ with open(input_file_path, "r") as input_file: reader = csv.DictReader(input_file) for row in reader: @@ -283,8 +331,12 @@ def _load_dict(self, input_file_path): class Tox21ChallengeChem(Tox21Challenge): + """Chemical data reader for Tox21Challenge dataset.""" + READER = dr.ChemDataReader class Tox21MolNetChem(Tox21MolNet): + """Chemical data reader for Tox21MolNet dataset.""" + READER = dr.ChemDataReader diff --git a/chebai/preprocessing/migration/chebi_data_migration.py b/chebai/preprocessing/migration/chebi_data_migration.py index 6ea2d7e2..5a438b44 100644 --- a/chebai/preprocessing/migration/chebi_data_migration.py +++ b/chebai/preprocessing/migration/chebi_data_migration.py @@ -1,4 +1,3 @@ -import argparse import os import shutil from typing import Dict, List, Optional, Tuple, Type @@ -28,6 +27,18 @@ def __init__(self, datamodule: _ChEBIDataExtractor): @classmethod def from_args(cls, class_name: str, chebi_version: int, single_class: int = None): + """ + Class method to create an instance of the class using the provided arguments. + + Args: + class_name (str): The name of the ChEBI class to be dynamically imported. + chebi_version (int): The version of ChEBI to be used. + single_class (int, optional): A specific class identifier if single class extraction is needed. + Default is None. + + Returns: + Subclass of _ChEBIDataExtractor + """ chebi_cls: _ChEBIDataExtractor = ChebiDataMigration._dynamic_import_chebi_cls( class_name, chebi_version, single_class ) diff --git a/chebai/preprocessing/reader.py b/chebai/preprocessing/reader.py index 120011df..902f1e92 100644 --- a/chebai/preprocessing/reader.py +++ b/chebai/preprocessing/reader.py @@ -1,11 +1,12 @@ import os +from typing import Any, Dict, List, Optional import deepsmiles import selfies as sf from pysmiles.read_smiles import _tokenize from transformers import RobertaTokenizerFast -from chebai.preprocessing.collate import DefaultCollater, RaggedCollater +from chebai.preprocessing.collate import DefaultCollator, RaggedCollator EMBEDDING_OFFSET = 10 PADDING_TOKEN_INDEX = 0 @@ -14,36 +15,57 @@ class DataReader: - COLLATER = DefaultCollater - - def __init__(self, collator_kwargs=None, token_path=None, **kwargs): + """ + Base class for reading and preprocessing data. Turns the raw input data (e.g., a SMILES string) into the model + input format (e.g., a list of tokens). + + Args: + collator_kwargs: Optional dictionary of keyword arguments for the collator. + token_path: Optional path for the token file. + kwargs: Additional keyword arguments (not used). + """ + + COLLATOR = DefaultCollator + + def __init__( + self, + collator_kwargs: Optional[Dict[str, Any]] = None, + token_path: Optional[str] = None, + **kwargs, + ): if collator_kwargs is None: collator_kwargs = dict() - self.collater = self.COLLATER(**collator_kwargs) + self.collator = self.COLLATOR(**collator_kwargs) self.dirname = os.path.dirname(__file__) self._token_path = token_path - def _get_raw_data(self, row): + def _get_raw_data(self, row: Dict[str, Any]) -> Any: + """Get raw data from the row.""" return row["features"] - def _get_raw_label(self, row): + def _get_raw_label(self, row: Dict[str, Any]) -> Any: + """Get raw label from the row.""" return row["labels"] - def _get_raw_id(self, row): + def _get_raw_id(self, row: Dict[str, Any]) -> Any: + """Get raw ID from the row.""" return row.get("ident", row["features"]) - def _get_raw_group(self, row): + def _get_raw_group(self, row: Dict[str, Any]) -> Any: + """Get raw group from the row.""" return row.get("group", None) - def _get_additional_kwargs(self, row): + def _get_additional_kwargs(self, row: Dict[str, Any]) -> Dict[str, Any]: + """Get additional keyword arguments from the row.""" return row.get("additional_kwargs", dict()) - def name(cls): + def name(cls) -> str: + """Returns the name of the data reader.""" raise NotImplementedError @property - def token_path(self): - """Get token path, create file if it does not exist yet""" + def token_path(self) -> str: + """Get token path, create file if it does not exist yet.""" if self._token_path is not None: return self._token_path token_path = os.path.join(self.dirname, "bin", self.name(), "tokens.txt") @@ -53,19 +75,24 @@ def token_path(self): pass return token_path - def _read_id(self, raw_data): + def _read_id(self, raw_data: Any) -> Any: + """Read and return ID from raw data.""" return raw_data - def _read_data(self, raw_data): + def _read_data(self, raw_data: Any) -> Any: + """Read and return data from raw data.""" return raw_data - def _read_label(self, raw_label): + def _read_label(self, raw_label: Any) -> Any: + """Read and return label from raw label.""" return raw_label - def _read_group(self, raw): + def _read_group(self, raw: Any) -> Any: + """Read and return group from raw group data.""" return raw - def _read_components(self, row): + def _read_components(self, row: Dict[str, Any]) -> Dict[str, Any]: + """Read and return components from the row.""" return dict( features=self._get_raw_data(row), labels=self._get_raw_label(row), @@ -74,7 +101,8 @@ def _read_components(self, row): additional_kwargs=self._get_additional_kwargs(row), ) - def to_data(self, row): + def to_data(self, row: Dict[str, Any]) -> Dict[str, Any]: + """Convert raw row data to processed data.""" d = self._read_components(row) return dict( features=self._read_data(d["features"]), @@ -84,16 +112,26 @@ def to_data(self, row): **d["additional_kwargs"], ) - def on_finish(self): + def on_finish(self) -> None: """Hook to run at the end of preprocessing.""" return class ChemDataReader(DataReader): - COLLATER = RaggedCollater + """ + Data reader for chemical data using SMILES tokens. + + Args: + collator_kwargs: Optional dictionary of keyword arguments for the collator. + token_path: Optional path for the token file. + kwargs: Additional keyword arguments. + """ + + COLLATOR = RaggedCollator @classmethod - def name(cls): + def name(cls) -> str: + """Returns the name of the data reader.""" return "smiles_token" def __init__(self, *args, **kwargs): @@ -101,17 +139,18 @@ def __init__(self, *args, **kwargs): with open(self.token_path, "r") as pk: self.cache = [x.strip() for x in pk] - def _get_token_index(self, token): - """Returns a unique number for each token, automatically adds new tokens""" + def _get_token_index(self, token: str) -> int: + """Returns a unique number for each token, automatically adds new tokens.""" if not str(token) in self.cache: self.cache.append(str(token)) return self.cache.index(str(token)) + EMBEDDING_OFFSET - def _read_data(self, raw_data): + def _read_data(self, raw_data: str) -> List[int]: + """Read and tokenize raw data.""" return [self._get_token_index(v[1]) for v in _tokenize(raw_data)] - def on_finish(self): - """write contents of self.cache into tokens.txt""" + def on_finish(self) -> None: + """Write contents of self.cache into tokens.txt.""" with open(self.token_path, "w") as pk: print(f"saving {len(self.cache)} tokens to {self.token_path}...") print(f"first 10 tokens: {self.cache[:10]}") @@ -119,16 +158,27 @@ def on_finish(self): class DeepChemDataReader(ChemDataReader): + """ + Data reader for chemical data using DeepSMILES tokens. + + Args: + collator_kwargs: Optional dictionary of keyword arguments for the collator. + token_path: Optional path for the token file. + kwargs: Additional keyword arguments. + """ + def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) self.converter = deepsmiles.Converter(rings=True, branches=True) self.error_count = 0 @classmethod - def name(cls): + def name(cls) -> str: + """Returns the name of the data reader.""" return "deepsmiles_token" - def _read_data(self, raw_data): + def _read_data(self, raw_data: str) -> Optional[List[int]]: + """Read and tokenize raw data using DeepSMILES.""" try: tokenized = _tokenize(self.converter.encode(raw_data)) tokenized = [self._get_token_index(v[1]) for v in tokenized] @@ -143,46 +193,99 @@ def _read_data(self, raw_data): class ChemDataUnlabeledReader(ChemDataReader): - COLLATER = RaggedCollater + """ + Data reader for unlabeled chemical data using SMILES tokens. + + Args: + collator_kwargs: Optional dictionary of keyword arguments for the collator. + token_path: Optional path for the token file. + kwargs: Additional keyword arguments. + """ + + COLLATOR = RaggedCollator @classmethod - def name(cls): + def name(cls) -> str: + """Returns the name of the data reader.""" return "smiles_token_unlabeled" - def _get_raw_label(self, row): + def _get_raw_label(self, row: Dict[str, Any]) -> None: + """Returns None as there are no labels.""" return None class ChemBPEReader(DataReader): - COLLATER = RaggedCollater + """ + Data reader for chemical data using BPE tokenization. + + Args: + data_path: Path for the pretrained BPE tokenizer. + max_len: Maximum length of the tokenized sequence. + vsize: Vocabulary size for the tokenizer (not used). + collator_kwargs: Optional dictionary of keyword arguments for the collator. + token_path: Optional path for the token file. + kwargs: Additional keyword arguments. + """ + + COLLATOR = RaggedCollator @classmethod - def name(cls): + def name(cls) -> str: + """Returns the name of the data reader.""" return "smiles_bpe" - def __init__(self, *args, data_path=None, max_len=1800, vsize=4000, **kwargs): + def __init__( + self, + *args, + data_path: Optional[str] = None, + max_len: int = 1800, + vsize: int = 4000, + **kwargs, + ): super().__init__(*args, **kwargs) self.tokenizer = RobertaTokenizerFast.from_pretrained( data_path, max_len=max_len ) - def _get_raw_data(self, row): + def _get_raw_data(self, row: Dict[str, Any]) -> List[int]: + """Tokenize raw data using BPE tokenizer.""" return self.tokenizer(row["features"])["input_ids"] class SelfiesReader(ChemDataReader): - COLLATER = RaggedCollater - - def __init__(self, *args, data_path=None, max_len=1800, vsize=4000, **kwargs): + """ + Data reader for chemical data using SELFIES tokens. + + Args: + data_path: Path for the pretrained BPE tokenizer. + max_len: Maximum length of the tokenized sequence. + vsize: Vocabulary size for the tokenizer. + collator_kwargs: Optional dictionary of keyword arguments for the collator. + token_path: Optional path for the token file. + kwargs: Additional keyword arguments. + """ + + COLLATOR = RaggedCollator + + def __init__( + self, + *args, + data_path: Optional[str] = None, + max_len: int = 1800, + vsize: int = 4000, + **kwargs, + ): super().__init__(*args, **kwargs) self.error_count = 0 sf.set_semantic_constraints("hypervalent") @classmethod - def name(cls): + def name(cls) -> str: + """Returns the name of the data reader.""" return "selfies" - def _read_data(self, raw_data): + def _read_data(self, raw_data: str) -> Optional[List[int]]: + """Read and tokenize raw data using SELFIES.""" try: tokenized = sf.split_selfies(sf.encoder(raw_data.strip(), strict=True)) tokenized = [self._get_token_index(v) for v in tokenized] @@ -198,11 +301,22 @@ def _read_data(self, raw_data): class OrdReader(DataReader): - COLLATER = RaggedCollater + """ + Data reader that converts characters to their ordinal values. + + Args: + collator_kwargs: Optional dictionary of keyword arguments for the collator. + token_path: Optional path for the token file. + kwargs: Additional keyword arguments. + """ + + COLLATOR = RaggedCollator @classmethod - def name(cls): + def name(cls) -> str: + """Returns the name of the data reader.""" return "ord" - def _read_data(self, raw_data): + def _read_data(self, raw_data: str) -> List[int]: + """Convert characters in raw data to their ordinal values.""" return [ord(s) for s in raw_data] diff --git a/chebai/preprocessing/structures.py b/chebai/preprocessing/structures.py index eb54fd41..1e384598 100644 --- a/chebai/preprocessing/structures.py +++ b/chebai/preprocessing/structures.py @@ -1,23 +1,46 @@ +from typing import Any, Tuple, Union + import networkx as nx import torch from torch.utils.data.dataset import T_co class XYData(torch.utils.data.Dataset): - def __getitem__(self, index) -> T_co: - return self.x[index], self.y[index] + """ + A dataset class for handling pairs of data (x, y). - def __len__(self): - # return batch size - return len(self.x) + Args: + x: Input data. + y: Target data. + kwargs: Additional fields to store in the dataset. + """ - def __init__(self, x, y, **kwargs): + def __init__( + self, x: Union[torch.Tensor, Tuple[Any, ...]], y: torch.Tensor, **kwargs + ): super().__init__() self.additional_fields = kwargs self.x = x self.y = y - def to_x(self, device): + def __getitem__(self, index: int) -> T_co: + """Returns the data and target at the given index.""" + return self.x[index], self.y[index] + + def __len__(self) -> int: + """Returns the size of the dataset.""" + return len(self.x) + + def to_x(self, device: torch.device) -> Union[torch.Tensor, Tuple[Any, ...]]: + """ + Moves the input data to the specified device. + + Args: + device: The device to move the data to. + + Returns: + The input data on the specified device. + """ if isinstance(self.x, tuple): res = [] for elem in self.x: @@ -30,10 +53,29 @@ def to_x(self, device): return tuple(res) return self.x.to(device) - def to_y(self, device): + def to_y(self, device: torch.device) -> torch.Tensor: + """ + Moves the target data to the specified device. + + Args: + device: The device to move the data to. + + Returns: + The target data on the specified device. + """ return self.y.to(device) - def _to_if_tensor(self, obj, device): + def _to_if_tensor(self, obj: Any, device: torch.device) -> Any: + """ + Recursively moves the object to the specified device if it is a tensor. + + Args: + obj: The object to move. + device: The device to move the object to. + + Returns: + The object on the specified device. + """ if isinstance(obj, torch.Tensor): return obj.to(device) elif isinstance(obj, dict): @@ -43,7 +85,16 @@ def _to_if_tensor(self, obj, device): else: return obj - def to(self, device): + def to(self, device: torch.device) -> "XYData": + """ + Moves the dataset to the specified device. + + Args: + device: The device to move the dataset to. + + Returns: + A new dataset on the specified device. + """ x = self.to_x(device) if self.y is not None: y = self.to_y(device) @@ -60,7 +111,25 @@ def to(self, device): class XYMolData(XYData): - def to_x(self, device): + """ + A dataset class for handling molecular data represented as NetworkX graphs. + + Args: + x: Input molecular graphs. + y: Target data. + kwargs: Additional fields to store in the dataset. + """ + + def to_x(self, device: torch.device) -> Tuple[nx.Graph, ...]: + """ + Moves the node attributes of the molecular graphs to the specified device. + + Args: + device: The device to move the data to. + + Returns: + A tuple of molecular graphs with node attributes on the specified device. + """ l = [] for g in self.x: graph = g.copy() diff --git a/chebai/result/analyse_sem.py b/chebai/result/analyse_sem.py index b77b8e85..2917f3a1 100644 --- a/chebai/result/analyse_sem.py +++ b/chebai/result/analyse_sem.py @@ -3,15 +3,12 @@ import sys import traceback from datetime import datetime +from typing import List, Union import pandas as pd import torch import wandb - from torchmetrics.functional.classification import multilabel_auroc, multilabel_f1_score -import gc -from typing import List, Union - from utils import * from chebai.loss.semantic import DisjointLoss diff --git a/chebai/result/base.py b/chebai/result/base.py index 1b8a9940..487be6ac 100644 --- a/chebai/result/base.py +++ b/chebai/result/base.py @@ -45,7 +45,7 @@ def _process_row(self, row): def _generate_predictions(self, data_path, raw=False, **kwargs): self._model.eval() - collate = self._reader.COLLATER() + collate = self._reader.COLLATOR() if raw: data_tuples = [ (x["features"], x["ident"], self._reader.to_data(self._process_row(x))) diff --git a/chebai/result/classification.py b/chebai/result/classification.py index 69ccacce..c75c7b29 100644 --- a/chebai/result/classification.py +++ b/chebai/result/classification.py @@ -1,10 +1,9 @@ -import os +from typing import List import matplotlib.pyplot as plt import pandas as pd import seaborn as sns -import torch -import tqdm +from torch import Tensor from torchmetrics.classification import ( MultilabelF1Score, MultilabelPrecision, @@ -12,13 +11,16 @@ ) from chebai.callbacks.epoch_metrics import BalancedAccuracy, MacroF1 -from chebai.models import ChebaiBaseNet -from chebai.models.electra import Electra -from chebai.preprocessing.datasets import XYBaseDataModule from chebai.result.utils import * -def visualise_f1(logs_path): +def visualise_f1(logs_path: str) -> None: + """ + Visualize F1 scores from metrics.csv and save the plot as f1_plot.png. + + Args: + logs_path: The path to the directory containing metrics.csv. + """ df = pd.read_csv(os.path.join(logs_path, "metrics.csv")) df_loss = df.melt( id_vars="epoch", @@ -34,8 +36,26 @@ def visualise_f1(logs_path): plt.show() -def print_metrics(preds, labels, device, classes=None, top_k=10, markdown_output=False): - """Prints relevant metrics, including micro and macro F1, recall and precision, best k classes and worst classes.""" +def print_metrics( + preds: Tensor, + labels: Tensor, + device: torch.device, + classes: Optional[List[str]] = None, + top_k: int = 10, + markdown_output: bool = False, +) -> None: + """ + Prints relevant metrics, including micro and macro F1, recall and precision, + best k classes, and worst classes. + + Args: + preds: Predicted labels as a tensor. + labels: True labels as a tensor. + device: The device to perform computations on. + classes: Optional list of class names. + top_k: The number of top classes to display based on F1 score. + markdown_output: If True, print metrics in markdown format. + """ f1_micro = MultilabelF1Score(preds.shape[1], average="micro").to(device=device) my_f1_macro = MacroF1(preds.shape[1]).to(device=device) my_bal_acc = BalancedAccuracy(preds.shape[1]).to(device=device) diff --git a/chebai/result/pretraining.py b/chebai/result/pretraining.py index 7c469674..33c212c8 100644 --- a/chebai/result/pretraining.py +++ b/chebai/result/pretraining.py @@ -31,7 +31,7 @@ def evaluate_model(logs_base_path, model_filename, data_module): ) ) assert isinstance(model, electra.ElectraPre) - collate = data_module.reader.COLLATER() + collate = data_module.reader.COLLATOR() test_file = "test.pt" data_path = os.path.join(data_module.processed_dir, test_file) data_list = torch.load(data_path) diff --git a/chebai/result/utils.py b/chebai/result/utils.py index 08860d76..491eb148 100644 --- a/chebai/result/utils.py +++ b/chebai/result/utils.py @@ -1,4 +1,5 @@ import os +from typing import Optional, Tuple, Union import torch import tqdm @@ -12,13 +13,25 @@ def get_checkpoint_from_wandb( - epoch, - run, - root=os.path.join("logs", "downloaded_ckpts"), - model_class=None, - map_device_to=None, -): - """Gets wandb checkpoint based on run and epoch, downloads it if necessary""" + epoch: int, + run: wandb.apis.public.Run, + root: str = os.path.join("logs", "downloaded_ckpts"), + model_class: Optional[Union[Electra, ChebaiBaseNet]] = None, + map_device_to: Optional[torch.device] = None, +) -> Optional[ChebaiBaseNet]: + """ + Gets a wandb checkpoint based on run and epoch, downloads it if necessary. + + Args: + epoch: The epoch number of the checkpoint to retrieve. + run: The wandb run object. + root: The root directory to save the downloaded checkpoint. + model_class: The class of the model to load. + map_device_to: The device to map the model to. + + Returns: + The loaded model or None if no checkpoint is found. + """ api = wandb.Api() if model_class is None: model_class = Electra @@ -42,18 +55,33 @@ def get_checkpoint_from_wandb( def evaluate_model( model: ChebaiBaseNet, data_module: XYBaseDataModule, - # No need to provide "filename" parameter for Chebi dataset, "kind" parameter should be provided - filename=None, - buffer_dir=None, + filename: Optional[str] = None, + buffer_dir: Optional[str] = None, batch_size: int = 32, - skip_existing_preds=False, + skip_existing_preds: bool = False, kind: str = "test", -): - """Runs model on test set of data_module (or, if filename is not None, on data set found in that file). - If buffer_dir is set, results will be saved in buffer_dir. Returns tensors with predictions and labels. +) -> Tuple[torch.Tensor, Optional[torch.Tensor]]: + """ + Runs the model on the test set of the data module or on the dataset found in the specified file. + If buffer_dir is set, results will be saved in buffer_dir. + + Note: + No need to provide "filename" parameter for Chebi dataset, "kind" parameter should be provided. + + Args: + model: The model to evaluate. + data_module: The data module containing the dataset. + filename: Optional file name for the dataset. + buffer_dir: Optional directory to save the results. + batch_size: The batch size for evaluation. + skip_existing_preds: Whether to skip evaluation if predictions already exist. + kind: Kind of split of the data to be used for testing the model. Default is `test`. + + Returns: + Tensors with predictions and labels. """ model.eval() - collate = data_module.reader.COLLATER() + collate = data_module.reader.COLLATOR() if isinstance(data_module, _ChEBIDataExtractor): # As the dynamic split change is implemented only for chebi-dataset as of now @@ -115,8 +143,19 @@ def evaluate_model( return test_preds, None -def load_results_from_buffer(buffer_dir, device): - """Load results stored in evaluate_model()""" +def load_results_from_buffer( + buffer_dir: str, device: torch.device +) -> Tuple[Optional[torch.Tensor], Optional[torch.Tensor]]: + """ + Load results stored in evaluate_model() from the buffer directory. + + Args: + buffer_dir: The directory containing the buffered results. + device: The device to load the results onto. + + Returns: + Tensors with predictions and labels. + """ preds_list = [] labels_list = [] diff --git a/chebai/train.py b/chebai/train.py index f6638733..06deec27 100644 --- a/chebai/train.py +++ b/chebai/train.py @@ -2,6 +2,8 @@ import multiprocessing as mp import os import pickle +import random +from typing import List, Tuple import numpy as np import pandas as pd @@ -19,7 +21,23 @@ LEARNING_RATE = 0.01 -def eval_model(model, dataset, test_labels): +def eval_model( + model: nn.Module, dataset: data.DataLoader, test_labels: List[torch.Tensor] +) -> Tuple[List[torch.Tensor], List[List[float]], List[float], float]: + """ + Evaluate the model on the provided dataset. + + Args: + - model (nn.Module): The neural network model. + - dataset (data.DataLoader): DataLoader containing the evaluation dataset. + - test_labels (List[torch.Tensor]): List of ground truth labels for the evaluation dataset. + + Returns: + - raw_values (List[torch.Tensor]): List of raw output values from the model. + - predictions (List[List[float]]): List of binary predictions (0 or 1) from the model. + - final_scores (List[float]): List of F1 scores computed for each prediction. + - avg_f1 (float): Average F1 score over all predictions. + """ raw_values = [] predictions = [] final_scores = [] @@ -37,7 +55,23 @@ def eval_model(model, dataset, test_labels): return raw_values, predictions, final_scores, avg_f1 -def crawl_info(DAG, sink_parents): +def crawl_info( + DAG: List[Tuple[str, str]], sink_parents: List[str] +) -> Tuple[List[int], List[int], dict, int, List[str]]: + """ + Crawl information from the Directed Acyclic Graph (DAG). + + Args: + - DAG (List[Tuple[str, str]]): List of tuples representing edges in the DAG. + - sink_parents (List[str]): List of parent nodes of the sink node. + + Returns: + - topological_order (List[int]): Nodes in topological order. + - sources (List[int]): List of source nodes in the DAG. + - parents (dict): Dictionary mapping nodes to their parent nodes. + - sink (int): Sink node in the DAG. + - sink_parents (List[str]): Updated list of parent nodes of the sink node. + """ topological_order = [int(i[0]) for i in DAG] target_nodes = [int(i[1]) for i in DAG] sink = target_nodes[-1] @@ -58,21 +92,53 @@ def crawl_info(DAG, sink_parents): return topological_order, sources, parents, sink, sink_parents -import random +def collate( + batch: List[Tuple[Molecule, torch.Tensor]] +) -> Tuple[List[Molecule], torch.Tensor]: + """ + Collate function for DataLoader. + Args: + - batch (List[Tuple[Molecule, torch.Tensor]]): List of tuples containing molecules and labels. -def collate(batch): + Returns: + - input (List[Molecule]): List of Molecule objects. + - labels (torch.Tensor): Tensor of labels. + """ input, labels = zip(*batch) return input, torch.stack(labels) -def _execute(model, loss_fn, optimizer, data, device, with_grad=True): - train_running_loss = 0 +def _execute( + model: nn.Module, + loss_fn: nn.Module, + optimizer: torch.optim.Optimizer, + data: data.DataLoader, + device: str, + with_grad: bool = True, +) -> Tuple[float, float]: + """ + Execute a single training or evaluation step. + + Args: + - model (nn.Module): The neural network model. + - loss_fn (nn.Module): Loss function. + - optimizer (torch.optim.Optimizer): Optimizer for updating model parameters. + - data (data.DataLoader): DataLoader containing the batched data. + - device (str): Device (CPU or GPU) on which to run the operations. + - with_grad (bool): Whether to compute gradients. Default is True (for training). + + Returns: + - train_running_loss (float): Average loss over the data. + - f1 (float): Average F1 score over the data. + """ + train_running_loss = 0.0 data_size = 0 f1 = 0 model.train(with_grad) num_batches = len(data) num_batch = 0 + for molecules, labels in data: num_batch += 1 optimizer.zero_grad() @@ -81,16 +147,39 @@ def _execute(model, loss_fn, optimizer, data, device, with_grad=True): data_size += 1 f1 += f1_score(prediction > 0.5, labels > 0.5, average="micro") train_running_loss += loss.item() + if with_grad: print(f"Batch {num_batch}/{num_batches}") loss.backward() optimizer.step() + return train_running_loss / data_size, f1 / data_size def execute_network( - model, loss_fn, optimizer, train_data, validation_data, epochs, device -): + model: nn.Module, + loss_fn: nn.Module, + optimizer: torch.optim.Optimizer, + train_data: data.DataLoader, + validation_data: data.DataLoader, + epochs: int, + device: str, +) -> None: + """ + Execute the training and evaluation loop over multiple epochs. + + Args: + - model (nn.Module): The neural network model. + - loss_fn (nn.Module): Loss function. + - optimizer (torch.optim.Optimizer): Optimizer for updating model parameters. + - train_data (data.DataLoader): DataLoader containing the training dataset. + - validation_data (data.DataLoader): DataLoader containing the validation dataset. + - epochs (int): Number of epochs to train the model. + - device (str): Device (CPU or GPU) on which to run the operations. + + Returns: + - None + """ model.to(device) model.device = device @@ -118,6 +207,7 @@ def execute_network( eval_running_loss, eval_running_f1 = _execute( model, loss_fn, optimizer, validation_data, device, with_grad=False ) + print( f"Epoch {epoch}: loss={train_running_loss:.5f}, f1={train_running_f1:.5f}, val_loss={eval_running_loss:.5f}, val_f1={eval_running_f1:.5f}".format( epoch, train_running_f1 @@ -135,7 +225,16 @@ def execute_network( writer.writerow(fields) -def prepare_data(infile): +def prepare_data(infile: pickle.Pickler) -> pd.DataFrame: + """ + Prepare the data from a pickle file. + + Args: + - infile (pickle.Pickler): Pickle file containing the raw data. + + Returns: + - train_df (pd.DataFrame): Processed DataFrame containing the data. + """ data = pickle.load(infile) infile.close() @@ -162,7 +261,17 @@ def prepare_data(infile): return train_df -def batchify(x, y): +def batchify(x: List, y: List) -> List: + """ + Batchify the input data and labels. + + Args: + - x (List): List of input data. + - y (List): List of labels. + + Returns: + - List: Batched data. + """ data = list(zip(x, y)) return [ data[i * BATCH_SIZE : (i + 1) * BATCH_SIZE] @@ -170,7 +279,18 @@ def batchify(x, y): ] -def load_data(): +def load_data() -> ( + Tuple[List[Molecule], List[torch.Tensor], List[Molecule], List[torch.Tensor]] +): + """ + Load and preprocess the data. + + Returns: + - train_dataset (List[Molecule]): List of Molecule objects for training. + - train_actual_labels (List[torch.Tensor]): List of ground truth labels for training. + - validation_dataset (List[Molecule]): List of Molecule objects for validation. + - validation_actual_labels (List[torch.Tensor]): List of ground truth labels for validation. + """ fpath = "data/full.pickle" if os.path.isfile(fpath): with open(fpath, "rb") as f: @@ -236,7 +356,16 @@ def load_data(): ) -def move_molecule(m): +def move_molecule(m: Molecule) -> Molecule: + """ + Move a molecule and collect its atom features. + + Args: + - m (Molecule): The Molecule object to process. + + Returns: + - Molecule: Processed Molecule object. + """ m.collect_atom_features() return m @@ -277,8 +406,10 @@ def move_molecule(m): collate_fn=collate, ) + # Initialize model model = ChEBIRecNN() + # Configure logging tb_logger = pl_loggers.CSVLogger("../logs/") trainer = pl.Trainer( logger=tb_logger, @@ -286,8 +417,11 @@ def move_molecule(m): max_epochs=NUM_EPOCHS, **trainer_kwargs, ) + + # Train the model trainer.fit(model, train_data, val_dataloaders=validation_data) +# Uncomment below section for saving the model and executing network training directly """ model = ChEBIRecNN() loss_fn = nn.BCEWithLogitsLoss() diff --git a/chebai/trainer/CustomTrainer.py b/chebai/trainer/CustomTrainer.py index 61115b83..874d6b35 100644 --- a/chebai/trainer/CustomTrainer.py +++ b/chebai/trainer/CustomTrainer.py @@ -1,5 +1,5 @@ import logging -from typing import List, Optional +from typing import Any, List, Optional, Tuple import pandas as pd import torch @@ -16,6 +16,13 @@ class CustomTrainer(Trainer): def __init__(self, *args, **kwargs): + """ + Initializes the CustomTrainer class, logging additional hyperparameters to the custom logger if specified. + + Args: + *args: Positional arguments for the Trainer class. + **kwargs: Keyword arguments for the Trainer class. + """ self.init_args = args self.init_kwargs = kwargs super().__init__(*args, **kwargs) @@ -32,7 +39,17 @@ def __init__(self, *args, **kwargs): log_kwargs[log_key] = log_value self.logger.log_hyperparams(log_kwargs) - def _resolve_logging_argument(self, key, value): + def _resolve_logging_argument(self, key: str, value: Any) -> Tuple[str, Any]: + """ + Resolves logging arguments, handling nested structures such as lists and complex objects. + + Args: + key: The key of the argument. + value: The value of the argument. + + Returns: + A tuple containing the resolved key and value. + """ if isinstance(value, list): key_value_pairs = [ self._resolve_logging_argument(f"{key}_{i}", v) @@ -58,7 +75,17 @@ def predict_from_file( input_path: _PATH, save_to: _PATH = "predictions.csv", classes_path: Optional[_PATH] = None, - ): + ) -> None: + """ + Loads a model from a checkpoint and makes predictions on input data from a file. + + Args: + model: The model to use for predictions. + checkpoint_path: Path to the model checkpoint. + input_path: Path to the input file containing SMILES strings. + save_to: Path to save the predictions CSV file. + classes_path: Optional path to a file containing class names. + """ loaded_model = model.__class__.load_from_checkpoint(checkpoint_path) with open(input_path, "r") as input: smiles_strings = [inp.strip() for inp in input.readlines()] @@ -71,7 +98,19 @@ def predict_from_file( predictions_df.index = smiles_strings predictions_df.to_csv(save_to) - def _predict_smiles(self, model: LightningModule, smiles: List[str]): + def _predict_smiles( + self, model: LightningModule, smiles: List[str] + ) -> torch.Tensor: + """ + Predicts the output for a list of SMILES strings using the model. + + Args: + model: The model to use for predictions. + smiles: A list of SMILES strings. + + Returns: + A tensor containing the predictions. + """ reader = ChemDataReader() parsed_smiles = [reader._read_data(s) for s in smiles] x = pad_sequence( @@ -91,6 +130,12 @@ def _predict_smiles(self, model: LightningModule, smiles: List[str]): @property def log_dir(self) -> Optional[str]: + """ + Returns the logging directory. + + Returns: + The path to the logging directory if available, else the default root directory. + """ if len(self.loggers) > 0: logger = self.loggers[0] if isinstance(logger, WandbLogger): diff --git a/tests/testChebiData.py b/tests/testChebiData.py index 5bf8d388..65a89c54 100644 --- a/tests/testChebiData.py +++ b/tests/testChebiData.py @@ -1,17 +1,36 @@ import unittest +from typing import List + +import pandas as pd from chebai.preprocessing.datasets.chebi import ChEBIOver50 class TestChebiData(unittest.TestCase): + """ + Test case for ChEBIOver50 dataset integrity, focusing on data splits and overlaps. + + Attributes: + overlaps_train_val (List): List of overlapping entities between train and validation splits based on SMILES. + overlaps_train_test (List): List of overlapping entities between train and test splits based on SMILES. + overlaps_val_test (List): List of overlapping entities between validation and test splits based on SMILES. + overlaps_train_val_ids (List): List of overlapping entity IDs between train and validation splits. + overlaps_train_test_ids (List): List of overlapping entity IDs between train and test splits. + overlaps_val_test_ids (List): List of overlapping entity IDs between validation and test splits. + """ @classmethod def setUpClass(cls) -> None: + """ + Set up class method to initialize ChEBIOver50 instance and generate data splits and overlaps. + """ cls.getDataSplitsOverlaps() @classmethod - def getDataSplitsOverlaps(cls): - """Get the overlap between data splits""" + def getDataSplitsOverlaps(cls) -> None: + """ + Get the overlap between data splits based on SMILES and IDs. + """ chebi_class_obj = ChEBIOver50() # Get the raw/processed data if missing chebi_class_obj.prepare_data() @@ -25,12 +44,12 @@ def getDataSplitsOverlaps(cls): val_smiles, val_smiles_ids = cls.get_features_ids(val_set) test_smiles, test_smiles_ids = cls.get_features_ids(test_set) - # ----- Get the overlap between data splits based on smiles tokens/features ----- + # Get the overlap between data splits based on smiles tokens/features cls.overlaps_train_val = cls.get_overlaps(train_smiles, val_smiles) cls.overlaps_train_test = cls.get_overlaps(train_smiles, test_smiles) cls.overlaps_val_test = cls.get_overlaps(val_smiles, test_smiles) - # ----- Get the overlap between data splits based on IDs ----- + # Get the overlap between data splits based on IDs cls.overlaps_train_val_ids = cls.get_overlaps(train_smiles_ids, val_smiles_ids) cls.overlaps_train_test_ids = cls.get_overlaps( train_smiles_ids, test_smiles_ids @@ -38,15 +57,33 @@ def getDataSplitsOverlaps(cls): cls.overlaps_val_test_ids = cls.get_overlaps(val_smiles_ids, test_smiles_ids) @staticmethod - def get_features_ids(data_split_df): - """Returns SMILES features/tokens and SMILES IDs from the data""" + def get_features_ids(data_split_df: pd.DataFrame) -> tuple[List, List]: + """ + Returns SMILES features/tokens and SMILES IDs from the data. + + Args: + data_split_df: DataFrame containing data to extract features and IDs from. + + Returns: + Tuple of lists: SMILES features/tokens list and SMILES IDs list. + """ smiles_features = data_split_df["features"].tolist() smiles_ids = data_split_df["ident"].tolist() return smiles_features, smiles_ids @staticmethod - def get_overlaps(list_1, list_2): + def get_overlaps(list_1: List, list_2: List) -> List: + """ + Get overlaps between two lists. + + Args: + list_1: First list. + list_2: Second list. + + Returns: + List: List of elements present in both lists. + """ overlap = [] for element in list_1: if element in list_2: @@ -54,8 +91,9 @@ def get_overlaps(list_1, list_2): return overlap @unittest.expectedFailure - def test_train_val_overlap_based_on_smiles(self): - """Check that train-val splits are performed correctly i.e.every entity + def test_train_val_overlap_based_on_smiles(self) -> None: + """ + Check that train-val splits are performed correctly i.e.every entity only appears in one of the train and validation set based on smiles tokens/features """ self.assertEqual( @@ -65,9 +103,11 @@ def test_train_val_overlap_based_on_smiles(self): ) @unittest.expectedFailure - def test_train_test_overlap_based_on_smiles(self): - """Check that train-test splits are performed correctly i.e.every entity - only appears in one of the train and test set based on smiles tokens/features""" + def test_train_test_overlap_based_on_smiles(self) -> None: + """ + Check that train-test splits are performed correctly i.e.every entity + only appears in one of the train and test set based on smiles tokens/features + """ self.assertEqual( len(self.overlaps_train_test), 0, @@ -75,8 +115,9 @@ def test_train_test_overlap_based_on_smiles(self): ) @unittest.expectedFailure - def test_val_test_overlap_based_on_smiles(self): - """Check that val-test splits are performed correctly i.e.every entity + def test_val_test_overlap_based_on_smiles(self) -> None: + """ + Check that val-test splits are performed correctly i.e.every entity only appears in one of the validation and test set based on smiles tokens/features """ self.assertEqual( @@ -85,27 +126,33 @@ def test_val_test_overlap_based_on_smiles(self): "Duplicate entities present in Validation and Test set based on SMILES", ) - def test_train_val_overlap_based_on_ids(self): - """Check that train-val splits are performed correctly i.e.every entity - only appears in one of the train and validation set based on smiles IDs""" + def test_train_val_overlap_based_on_ids(self) -> None: + """ + Check that train-val splits are performed correctly i.e.every entity + only appears in one of the train and validation set based on smiles IDs + """ self.assertEqual( len(self.overlaps_train_val_ids), 0, "Duplicate entities present in Train and Validation set based on IDs", ) - def test_train_test_overlap_based_on_ids(self): - """Check that train-test splits are performed correctly i.e.every entity - only appears in one of the train and test set based on smiles IDs""" + def test_train_test_overlap_based_on_ids(self) -> None: + """ + Check that train-test splits are performed correctly i.e.every entity + only appears in one of the train and test set based on smiles IDs + """ self.assertEqual( len(self.overlaps_train_test_ids), 0, "Duplicate entities present in Train and Test set based on IDs", ) - def test_val_test_overlap_based_on_ids(self): - """Check that val-test splits are performed correctly i.e.every entity - only appears in one of the validation and test set based on smiles IDs""" + def test_val_test_overlap_based_on_ids(self) -> None: + """ + Check that val-test splits are performed correctly i.e.every entity + only appears in one of the validation and test set based on smiles IDs + """ self.assertEqual( len(self.overlaps_val_test_ids), 0, diff --git a/tests/testChebiDynamicDataSplits.py b/tests/testChebiDynamicDataSplits.py index d928c394..807e67b2 100644 --- a/tests/testChebiDynamicDataSplits.py +++ b/tests/testChebiDynamicDataSplits.py @@ -1,5 +1,6 @@ import hashlib import unittest +from typing import Any, List, Tuple import numpy as np import pandas as pd @@ -8,10 +9,19 @@ class TestChebiDynamicDataSplits(unittest.TestCase): - """Test dynamic splits implementation's consistency""" + """ + Test dynamic splits implementation's consistency for ChEBIOver50 dataset. + + Attributes: + chebi_50_v231 (ChEBIOver50): Instance of ChEBIOver50 with ChEBI version 231. + chebi_50_v231_vt200 (ChEBIOver50): Instance of ChEBIOver50 with ChEBI version 231 and train version 200. + """ @classmethod - def setUpClass(cls): + def setUpClass(cls) -> None: + """ + Set up class method to initialize instances of ChEBIOver50 and generate data. + """ cls.chebi_50_v231 = ChEBIOver50(chebi_version=231) cls.chebi_50_v231_vt200 = ChEBIOver50( chebi_version=231, chebi_version_train=200 @@ -19,9 +29,10 @@ def setUpClass(cls): cls._generate_chebi_class_data(cls.chebi_50_v231) cls._generate_chebi_class_data(cls.chebi_50_v231_vt200) - def testDynamicDataSplitsConsistency(self): - """Test Dynamic Data Splits consistency across every run""" - + def testDynamicDataSplitsConsistency(self) -> None: + """ + Test Dynamic Data Splits consistency across multiple runs. + """ # Dynamic Data Splits in Run 1 train_hash_1, val_hash_1, test_hash_1 = self._get_hashed_splits() @@ -34,9 +45,10 @@ def testDynamicDataSplitsConsistency(self): self.assertEqual(val_hash_1, val_hash_2, "Validation data hashes do not match.") self.assertEqual(test_hash_1, test_hash_2, "Test data hashes do not match.") - def test_same_ids_and_in_test_sets(self): - """Check if test sets of both classes have same IDs""" - + def test_same_ids_and_in_test_sets(self) -> None: + """ + Check if test sets of both classes have the same IDs. + """ v231_ids = set(self.chebi_50_v231.dynamic_split_dfs["test"]["ident"]) v231_vt200_ids = set( self.chebi_50_v231_vt200.dynamic_split_dfs["test"]["ident"] @@ -46,9 +58,10 @@ def test_same_ids_and_in_test_sets(self): v231_ids, v231_vt200_ids, "Test sets do not have the same IDs." ) - def test_labels_vector_size_in_test_sets(self): - """Check if test sets of both classes have different size/shape of labels""" - + def test_labels_vector_size_in_test_sets(self) -> None: + """ + Check if test sets of both classes have different sizes/shapes of labels. + """ v231_labels_shape = len( self.chebi_50_v231.dynamic_split_dfs["test"]["labels"].iloc[0] ) @@ -59,11 +72,13 @@ def test_labels_vector_size_in_test_sets(self): self.assertEqual( v231_labels_shape, v231_vt200_label_shape, - "Test sets have the different size of labels", + "Test sets have different sizes of labels", ) - def test_no_overlaps_in_chebi_v231_vt200(self): - """Test the overlaps for the ChEBIOver50(chebi_version=231, chebi_version_train=200)""" + def test_no_overlaps_in_chebi_v231_vt200(self) -> None: + """ + Test the overlaps for the ChEBIOver50(chebi_version=231, chebi_version_train=200) dataset. + """ train_set = self.chebi_50_v231_vt200.dynamic_split_dfs["train"] val_set = self.chebi_50_v231_vt200.dynamic_split_dfs["validation"] test_set = self.chebi_50_v231_vt200.dynamic_split_dfs["test"] @@ -72,7 +87,7 @@ def test_no_overlaps_in_chebi_v231_vt200(self): val_set_ids = val_set["ident"].tolist() test_set_ids = test_set["ident"].tolist() - # ----- Get the overlap between data splits based on IDs ----- + # Get the overlap between data splits based on IDs self.overlaps_train_val_ids = self.get_overlaps(train_set_ids, val_set_ids) self.overlaps_train_test_ids = self.get_overlaps(train_set_ids, test_set_ids) self.overlaps_val_test_ids = self.get_overlaps(val_set_ids, test_set_ids) @@ -93,10 +108,13 @@ def test_no_overlaps_in_chebi_v231_vt200(self): "Duplicate entities present in Validation and Test set based on IDs", ) - def _get_hashed_splits(self): - """Returns hashed dynamic data splits""" + def _get_hashed_splits(self) -> Tuple[str, str, str]: + """ + Returns hashed dynamic data splits. - # Get the raw/processed data if missing + Returns: + Tuple[str, str, str]: Hashes for train, validation, and test data splits. + """ chebi_class_obj = self.chebi_50_v231 # Get dynamic splits from class variables @@ -112,16 +130,32 @@ def _get_hashed_splits(self): return train_hash, val_hash, test_hash @staticmethod - def compute_hash(data): - """Returns hash for the given data partition""" + def compute_hash(data: pd.DataFrame) -> str: + """ + Returns hash for the given data partition. + + Args: + data (pd.DataFrame): DataFrame containing data to be hashed. + + Returns: + str: Hash computed for the DataFrame. + """ data_for_hashing = data.map(TestChebiDynamicDataSplits.convert_to_hashable) return hashlib.md5( pd.util.hash_pandas_object(data_for_hashing, index=True).values ).hexdigest() @staticmethod - def convert_to_hashable(item): - """To Convert lists and numpy arrays within the DataFrame to tuples for hashing""" + def convert_to_hashable(item: Any) -> Any: + """ + Convert lists and numpy arrays within the DataFrame to tuples for hashing. + + Args: + item (Any): Item to convert to a hashable form. + + Returns: + Any: Hashable representation of the input item. + """ if isinstance(item, list): return tuple(item) elif isinstance(item, np.ndarray): @@ -130,13 +164,28 @@ def convert_to_hashable(item): return item @staticmethod - def _generate_chebi_class_data(chebi_class_obj): - # Get the raw/processed data if missing + def _generate_chebi_class_data(chebi_class_obj: ChEBIOver50) -> None: + """ + Generate ChEBI class data if not already generated. + + Args: + chebi_class_obj (ChEBIOver50): Instance of ChEBIOver50 class. + """ chebi_class_obj.prepare_data() chebi_class_obj.setup() @staticmethod - def get_overlaps(list_1, list_2): + def get_overlaps(list_1: List[Any], list_2: List[Any]) -> List[Any]: + """ + Get overlaps between two lists. + + Args: + list_1 (List[Any]): First list. + list_2 (List[Any]): Second list. + + Returns: + List[Any]: List of elements present in both lists. + """ overlap = [] for element in list_1: if element in list_2: diff --git a/tests/testCustomBalancedAccuracyMetric.py b/tests/testCustomBalancedAccuracyMetric.py index d257114e..30cbe1d5 100644 --- a/tests/testCustomBalancedAccuracyMetric.py +++ b/tests/testCustomBalancedAccuracyMetric.py @@ -8,15 +8,22 @@ class TestCustomBalancedAccuracyMetric(unittest.TestCase): + """ + Unit tests for the Custom Balanced Accuracy metric. + """ @classmethod def setUpClass(cls) -> None: + """ + Set up class-level variables. + """ cls.device = "cuda" if torch.cuda.is_available() else "cpu" - def test_iterative_vs_single_call_approach(self): - """Test the custom metric implementation in update fashion approach against - the single call approach""" - + def test_iterative_vs_single_call_approach(self) -> None: + """ + Test the custom metric implementation in update fashion approach against + the single call approach. + """ preds = torch.tensor([[1, 1, 0, 1], [1, 0, 1, 1], [0, 1, 0, 1]]) label = torch.tensor([[0, 0, 0, 0], [0, 0, 1, 1], [0, 1, 0, 1]]) @@ -31,8 +38,10 @@ def test_iterative_vs_single_call_approach(self): self.assertEqual(iterative_custom_metric_score, single_call_custom_metric_score) - def test_metric_against_realistic_data(self): - """Test the custom metric against the standard on realistic data""" + def test_metric_against_realistic_data(self) -> None: + """ + Test the custom metric against the standard on realistic data. + """ directory_path = os.path.join("tests", "test_data", "CheBIOver100_test") abs_path = os.path.join(os.getcwd(), directory_path) print(f"Checking data from - {abs_path}") @@ -59,8 +68,10 @@ def test_metric_against_realistic_data(self): balanced_acc_custom_score = balanced_acc_custom.compute().item() print(f"Balanced Accuracy for realistic data: {balanced_acc_custom_score}") - def test_case_when_few_class_has_no_labels(self): - """Test custom metric against standard metric for the scenario where some class has no labels""" + def test_case_when_few_class_has_no_labels(self) -> None: + """ + Test custom metric against standard metric for the scenario where some class has no labels. + """ preds = torch.tensor([[1, 1, 0, 1], [1, 0, 1, 1], [0, 1, 0, 1]]) label = torch.tensor([[0, 0, 0, 0], [0, 0, 1, 1], [0, 1, 0, 1]]) # no labels @@ -76,9 +87,11 @@ def test_case_when_few_class_has_no_labels(self): self.assertAlmostEqual(balanced_acc_score, 0.6041666666, places=4) - def test_all_predictions_are_1_half_labels_are_1(self): - """Test custom metric against standard metric for the scenario where all prediction are 1 but only half of - the labels are 1""" + def test_all_predictions_are_1_half_labels_are_1(self) -> None: + """ + Test custom metric against standard metric for the scenario where all predictions are 1 but only half of + the labels are 1. + """ preds = torch.ones((1, 900), dtype=torch.int) label = torch.ones((1, 900), dtype=torch.int) @@ -100,9 +113,11 @@ def test_all_predictions_are_1_half_labels_are_1(self): ) self.assertAlmostEqual(balanced_acc_custom_score, 0.25, places=4) - def test_all_labels_are_1_half_predictions_are_1(self): - """Test custom metric against standard metric for the scenario where all labels are 1 but only half of - the predictions are 1""" + def test_all_labels_are_1_half_predictions_are_1(self) -> None: + """ + Test custom metric against standard metric for the scenario where all labels are 1 but only half of + the predictions are 1. + """ preds = torch.ones((1, 900), dtype=torch.int) label = torch.ones((1, 900), dtype=torch.int) @@ -125,7 +140,20 @@ def test_all_labels_are_1_half_predictions_are_1(self): self.assertAlmostEqual(balanced_acc_custom_score, 0.25, places=4) @staticmethod - def __get_custom_metric_score(preds, labels, num_labels): + def __get_custom_metric_score( + preds: torch.Tensor, labels: torch.Tensor, num_labels: int + ) -> float: + """ + Helper function to compute the custom metric score. + + Args: + - preds (torch.Tensor): Predictions tensor. + - labels (torch.Tensor): Labels tensor. + - num_labels (int): Number of labels/classes. + + Returns: + - float: Computed custom metric score. + """ balanced_acc_custom = BalancedAccuracy(num_labels=num_labels) return balanced_acc_custom(preds, labels).item() diff --git a/tests/testCustomMacroF1Metric.py b/tests/testCustomMacroF1Metric.py index 685f2901..a7bbbaa2 100644 --- a/tests/testCustomMacroF1Metric.py +++ b/tests/testCustomMacroF1Metric.py @@ -9,17 +9,19 @@ class TestCustomMacroF1Metric(unittest.TestCase): - @classmethod def setUpClass(cls) -> None: cls.device = "cuda" if torch.cuda.is_available() else "cpu" - def test_all_predictions_are_1_half_labels_are_1(self): - """Test custom metric against standard metric for the scenario where all prediction are 1 but only half of - the labels are 1""" + def test_all_predictions_are_1_half_labels_are_1(self) -> None: + """ + Test custom metric against standard metric for the scenario where all predictions are 1 + but only half of the labels are 1. + """ preds = torch.ones((1, 900), dtype=torch.int) label = torch.ones((1, 900), dtype=torch.int) + # Randomly set half of the labels to 0 mask = [ [True] * (label.size(1) // 2) + [False] * (label.size(1) - (label.size(1) // 2)) @@ -27,6 +29,7 @@ def test_all_predictions_are_1_half_labels_are_1(self): random.shuffle(mask[0]) label[torch.tensor(mask)] = 0 + # Get custom and standard metric scores macro_f1_custom_score, macro_f1_standard_score = ( self.__get_custom_and_standard_metric_scores(label.shape[1], preds, label) ) @@ -54,18 +57,21 @@ def test_all_predictions_are_1_half_labels_are_1(self): # precision = [1, 1, 1, 1, 1] / [1, 1, 1, 1, 1] = [1, 1, 1, 1, 1] # recall = [1, 1, 1, 1, 1] / [1, 1, 1, 1, 1] = [1, 1, 1, 1, 1] # classwise_f1 = [2, 2, 2, 2, 2] / [2, 2, 2, 2, 2] = [1, 1, 1, 1, 1] - # mean = 5/5 = 1 (because of masking we averaging with across positive labels only) + # mean = 5/5 = 1 (because of masking we're averaging with across positive labels only) self.assertAlmostEqual(macro_f1_custom_score, 1, places=4) self.assertNotAlmostEqual( macro_f1_custom_score, macro_f1_standard_score, places=4 ) - def test_all_labels_are_1_half_predictions_are_1(self): - """Test custom metric against standard metric for the scenario where all labels are 1 but only half of - the predictions are 1""" + def test_all_labels_are_1_half_predictions_are_1(self) -> None: + """ + Test custom metric against standard metric for the scenario where all labels are 1 + but only half of the predictions are 1. + """ preds = torch.ones((1, 900), dtype=torch.int) label = torch.ones((1, 900), dtype=torch.int) + # Randomly set half of the predictions to 0 mask = [ [True] * (label.size(1) // 2) + [False] * (label.size(1) - (label.size(1) // 2)) @@ -73,6 +79,7 @@ def test_all_labels_are_1_half_predictions_are_1(self): random.shuffle(mask[0]) preds[torch.tensor(mask)] = 0 + # Get custom and standard metric scores macro_f1_custom_score, macro_f1_standard_score = ( self.__get_custom_and_standard_metric_scores(label.shape[1], preds, label) ) @@ -81,9 +88,11 @@ def test_all_labels_are_1_half_predictions_are_1(self): # and since all labels are positive in this scenario, custom and std metric are same self.assertAlmostEqual(macro_f1_custom_score, macro_f1_standard_score, places=4) - def test_iterative_vs_single_call_approach(self): - """Test the custom metric implementation in update fashion approach against - the single call approach""" + def test_iterative_vs_single_call_approach(self) -> None: + """ + Test the custom metric implementation in update fashion approach against + the single call approach. + """ preds = torch.tensor([[1, 1, 0, 1], [1, 0, 1, 1], [0, 1, 0, 1]]) label = torch.tensor([[0, 0, 0, 0], [0, 0, 1, 1], [0, 1, 0, 1]]) @@ -96,16 +105,19 @@ def test_iterative_vs_single_call_approach(self): single_call_custom_metric = MacroF1(num_labels=num_labels) single_call_custom_metric_score = single_call_custom_metric(preds, label).item() + # Assert iterative and single call approaches give the same metric score self.assertEqual(iterative_custom_metric_score, single_call_custom_metric_score) - def test_metric_against_realistic_data(self): - """Test the custom metric against the standard on realistic data""" + def test_metric_against_realistic_data(self) -> None: + """ + Test the custom metric against the standard on realistic data. + """ directory_path = os.path.join("tests", "test_data", "CheBIOver100_test") abs_path = os.path.join(os.getcwd(), directory_path) print(f"Checking data from - {abs_path}") num_of_files = len(os.listdir(abs_path)) // 2 - # load single file to get the num of labels for metric class instantiation + # Load single file to get the number of labels for metric class instantiation labels = torch.load( f"{directory_path}/labels{0:03d}.pt", map_location=torch.device(self.device) ) @@ -113,7 +125,7 @@ def test_metric_against_realistic_data(self): macro_f1_custom = MacroF1(num_labels=num_labels) macro_f1_standard = MultilabelF1Score(num_labels=num_labels, average="macro") - # load each file in the directory and update the stats + # Load each file in the directory and update the metrics for i in range(num_of_files): labels = torch.load( f"{directory_path}/labels{i:03d}.pt", @@ -132,14 +144,19 @@ def test_metric_against_realistic_data(self): f"Realistic Data - Custom F1 score: {macro_f1_custom_score}, Std. F1 score: {macro_f1_standard_score}" ) + # Assert custom metric score is not equal to standard metric score self.assertNotAlmostEqual( macro_f1_custom_score, macro_f1_standard_score, places=4 ) - def test_case_when_few_class_has_no_labels(self): - """Test custom metric against standard metric for the scenario where some class has no labels""" + def test_case_when_few_class_has_no_labels(self) -> None: + """ + Test custom metric against standard metric for the scenario where some class has no labels. + """ preds = torch.tensor([[1, 1, 0, 1], [1, 0, 1, 1], [0, 1, 0, 1]]) label = torch.tensor([[0, 0, 0, 0], [0, 0, 1, 1], [0, 1, 0, 1]]) + + # Get custom and standard metric scores macro_f1_custom_score, macro_f1_standard_score = ( self.__get_custom_and_standard_metric_scores(label.shape[1], preds, label) ) @@ -172,7 +189,22 @@ def test_case_when_few_class_has_no_labels(self): ) @staticmethod - def __get_custom_and_standard_metric_scores(num_labels, preds, labels): + def __get_custom_and_standard_metric_scores( + num_labels: int, preds: torch.Tensor, labels: torch.Tensor + ) -> tuple: + """ + Helper method to calculate custom and standard macro F1 scores. + + Args: + num_labels (int): Number of labels/classes. + preds (torch.Tensor): Predicted tensor of shape (batch_size, num_labels). + labels (torch.Tensor): True labels tensor of shape (batch_size, num_labels). + + Returns: + tuple: A tuple containing two floats: + - macro_f1_custom_score: Custom macro F1 score. + - macro_f1_standard_score: Standard macro F1 score. + """ # Custom metric score macro_f1_custom = MacroF1(num_labels=num_labels) macro_f1_custom_score = macro_f1_custom(preds, labels).item() diff --git a/tests/testPubChemData.py b/tests/testPubChemData.py index 00dc8579..dfc43028 100644 --- a/tests/testPubChemData.py +++ b/tests/testPubChemData.py @@ -1,5 +1,6 @@ import os import unittest +from typing import Dict, List, Tuple import torch @@ -7,15 +8,32 @@ class TestPubChemData(unittest.TestCase): + """ + Unit tests for PubChem dataset preprocessing. + + Attributes: + pubChem (PubChem): Instance of PubChem dataset handler. + overlaps_train_val (List): List of overlaps between training and validation sets based on SMILES features. + overlaps_train_test (List): List of overlaps between training and test sets based on SMILES features. + overlaps_val_test (List): List of overlaps between validation and test sets based on SMILES features. + overlaps_train_val_ids (List): List of overlaps between training and validation sets based on SMILES IDs. + overlaps_train_test_ids (List): List of overlaps between training and test sets based on SMILES IDs. + overlaps_val_test_ids (List): List of overlaps between validation and test sets based on SMILES IDs. + """ @classmethod def setUpClass(cls) -> None: + """ + Set up PubChem dataset and compute overlaps between data splits. + """ cls.pubChem = PubChem() cls.getDataSplitsOverlaps() @classmethod - def getDataSplitsOverlaps(cls): - """Get the overlap between data splits""" + def getDataSplitsOverlaps(cls) -> None: + """ + Get the overlap between data splits based on SMILES features and IDs. + """ processed_path = os.path.join(os.getcwd(), cls.pubChem.processed_dir) print(f"Checking Data from - {processed_path}") @@ -27,22 +45,12 @@ def getDataSplitsOverlaps(cls): val_smiles, val_smiles_ids = cls.get_features_ids(val_set) test_smiles, test_smiles_ids = cls.get_features_ids(test_set) - # ----- Get the overlap between data splits based on smiles tokens/features ----- - - # train_smiles.append(val_smiles[0]) - # train_smiles.append(test_smiles[0]) - # val_smiles.append(test_smiles[0]) - + # Get overlaps based on SMILES features cls.overlaps_train_val = cls.get_overlaps(train_smiles, val_smiles) cls.overlaps_train_test = cls.get_overlaps(train_smiles, test_smiles) cls.overlaps_val_test = cls.get_overlaps(val_smiles, test_smiles) - # ----- Get the overlap between data splits based on IDs ----- - - # train_smiles_ids.append(val_smiles_ids[0]) - # train_smiles_ids.append(test_smiles_ids[0]) - # val_smiles_ids.append(test_smiles_ids[0]) - + # Get overlaps based on SMILES IDs cls.overlaps_train_val_ids = cls.get_overlaps(train_smiles_ids, val_smiles_ids) cls.overlaps_train_test_ids = cls.get_overlaps( train_smiles_ids, test_smiles_ids @@ -50,8 +58,16 @@ def getDataSplitsOverlaps(cls): cls.overlaps_val_test_ids = cls.get_overlaps(val_smiles_ids, test_smiles_ids) @staticmethod - def get_features_ids(data_split): - """Returns SMILES features/tokens and SMILES IDs from the data""" + def get_features_ids(data_split: List[Dict]) -> Tuple[List, List]: + """ + Returns SMILES features/tokens and SMILES IDs from the data. + + Args: + data_split (List[Dict]): List of dictionaries containing SMILES features and IDs. + + Returns: + Tuple[List, List]: Tuple of lists containing SMILES features and SMILES IDs. + """ smiles_features, smiles_ids = [], [] for entry in data_split: smiles_features.append(entry["features"]) @@ -60,16 +76,26 @@ def get_features_ids(data_split): return smiles_features, smiles_ids @staticmethod - def get_overlaps(list_1, list_2): + def get_overlaps(list_1: List, list_2: List) -> List: + """ + Get overlaps between two lists. + + Args: + list_1 (List): First list. + list_2 (List): Second list. + + Returns: + List: List of elements common to both input lists. + """ overlap = [] for element in list_1: if element in list_2: overlap.append(element) return overlap - def test_train_val_overlap_based_on_smiles(self): - """Check that train-val splits are performed correctly i.e.every entity - only appears in one of the train and validation set based on smiles tokens/features + def test_train_val_overlap_based_on_smiles(self) -> None: + """ + Check that train-val splits are performed correctly based on SMILES features. """ self.assertEqual( len(self.overlaps_train_val), @@ -77,18 +103,19 @@ def test_train_val_overlap_based_on_smiles(self): "Duplicate entities present in Train and Validation set based on SMILES", ) - def test_train_test_overlap_based_on_smiles(self): - """Check that train-test splits are performed correctly i.e.every entity - only appears in one of the train and test set based on smiles tokens/features""" + def test_train_test_overlap_based_on_smiles(self) -> None: + """ + Check that train-test splits are performed correctly based on SMILES features. + """ self.assertEqual( len(self.overlaps_train_test), 0, "Duplicate entities present in Train and Test set based on SMILES", ) - def test_val_test_overlap_based_on_smiles(self): - """Check that val-test splits are performed correctly i.e.every entity - only appears in one of the validation and test set based on smiles tokens/features + def test_val_test_overlap_based_on_smiles(self) -> None: + """ + Check that val-test splits are performed correctly based on SMILES features. """ self.assertEqual( len(self.overlaps_val_test), @@ -96,27 +123,30 @@ def test_val_test_overlap_based_on_smiles(self): "Duplicate entities present in Validation and Test set based on SMILES", ) - def test_train_val_overlap_based_on_ids(self): - """Check that train-val splits are performed correctly i.e.every entity - only appears in one of the train and validation set based on smiles IDs""" + def test_train_val_overlap_based_on_ids(self) -> None: + """ + Check that train-val splits are performed correctly based on SMILES IDs. + """ self.assertEqual( len(self.overlaps_train_val_ids), 0, "Duplicate entities present in Train and Validation set based on IDs", ) - def test_train_test_overlap_based_on_ids(self): - """Check that train-test splits are performed correctly i.e.every entity - only appears in one of the train and test set based on smiles IDs""" + def test_train_test_overlap_based_on_ids(self) -> None: + """ + Check that train-test splits are performed correctly based on SMILES IDs. + """ self.assertEqual( len(self.overlaps_train_test_ids), 0, "Duplicate entities present in Train and Test set based on IDs", ) - def test_val_test_overlap_based_on_ids(self): - """Check that val-test splits are performed correctly i.e.every entity - only appears in one of the validation and test set based on smiles IDs""" + def test_val_test_overlap_based_on_ids(self) -> None: + """ + Check that val-test splits are performed correctly based on SMILES IDs. + """ self.assertEqual( len(self.overlaps_val_test_ids), 0, diff --git a/tests/testTox21MolNetData.py b/tests/testTox21MolNetData.py index 91e34e3d..99424e83 100644 --- a/tests/testTox21MolNetData.py +++ b/tests/testTox21MolNetData.py @@ -1,21 +1,39 @@ import os import unittest +from typing import Dict, List, Tuple import torch from chebai.preprocessing.datasets.tox21 import Tox21MolNetChem -class TestPubChemData(unittest.TestCase): +class TestTox21Data(unittest.TestCase): + """ + Unit tests for Tox21 dataset preprocessing. + + Attributes: + tox21 (Tox21MolNetChem): Instance of Tox21 dataset handler. + overlaps_train_val (List): List of overlaps between training and validation sets based on SMILES features. + overlaps_train_test (List): List of overlaps between training and test sets based on SMILES features. + overlaps_val_test (List): List of overlaps between validation and test sets based on SMILES features. + overlaps_train_val_ids (List): List of overlaps between training and validation sets based on SMILES IDs. + overlaps_train_test_ids (List): List of overlaps between training and test sets based on SMILES IDs. + overlaps_val_test_ids (List): List of overlaps between validation and test sets based on SMILES IDs. + """ @classmethod def setUpClass(cls) -> None: + """ + Set up Tox21 dataset and compute overlaps between data splits. + """ cls.tox21 = Tox21MolNetChem() cls.getDataSplitsOverlaps() @classmethod - def getDataSplitsOverlaps(cls): - """Get the overlap between data splits""" + def getDataSplitsOverlaps(cls) -> None: + """ + Get the overlap between data splits based on SMILES features and IDs. + """ processed_path = os.path.join(os.getcwd(), cls.tox21.processed_dir) print(f"Checking Data from - {processed_path}") @@ -27,22 +45,12 @@ def getDataSplitsOverlaps(cls): val_smiles, val_smiles_ids = cls.get_features_ids(val_set) test_smiles, test_smiles_ids = cls.get_features_ids(test_set) - # ----- Get the overlap between data splits based on smiles tokens/features ----- - - # train_smiles.append(val_smiles[0]) - # train_smiles.append(test_smiles[0]) - # val_smiles.append(test_smiles[0]) - + # Get overlaps based on SMILES features cls.overlaps_train_val = cls.get_overlaps(train_smiles, val_smiles) cls.overlaps_train_test = cls.get_overlaps(train_smiles, test_smiles) cls.overlaps_val_test = cls.get_overlaps(val_smiles, test_smiles) - # ----- Get the overlap between data splits based on IDs ----- - - # train_smiles_ids.append(val_smiles_ids[0]) - # train_smiles_ids.append(test_smiles_ids[0]) - # val_smiles_ids.append(test_smiles_ids[0]) - + # Get overlaps based on SMILES IDs cls.overlaps_train_val_ids = cls.get_overlaps(train_smiles_ids, val_smiles_ids) cls.overlaps_train_test_ids = cls.get_overlaps( train_smiles_ids, test_smiles_ids @@ -50,8 +58,16 @@ def getDataSplitsOverlaps(cls): cls.overlaps_val_test_ids = cls.get_overlaps(val_smiles_ids, test_smiles_ids) @staticmethod - def get_features_ids(data_split): - """Returns SMILES features/tokens and SMILES IDs from the data""" + def get_features_ids(data_split: List[Dict]) -> Tuple[List, List]: + """ + Returns SMILES features/tokens and SMILES IDs from the data. + + Args: + data_split (List[Dict]): List of dictionaries containing SMILES features and IDs. + + Returns: + Tuple[List, List]: Tuple of lists containing SMILES features and SMILES IDs. + """ smiles_features, smiles_ids = [], [] for entry in data_split: smiles_features.append(entry["features"]) @@ -60,16 +76,26 @@ def get_features_ids(data_split): return smiles_features, smiles_ids @staticmethod - def get_overlaps(list_1, list_2): + def get_overlaps(list_1: List, list_2: List) -> List: + """ + Get overlaps between two lists. + + Args: + list_1 (List): First list. + list_2 (List): Second list. + + Returns: + List: List of elements common to both input lists. + """ overlap = [] for element in list_1: if element in list_2: overlap.append(element) return overlap - def test_train_val_overlap_based_on_smiles(self): - """Check that train-val splits are performed correctly i.e.every entity - only appears in one of the train and validation set based on smiles tokens/features + def test_train_val_overlap_based_on_smiles(self) -> None: + """ + Check that train-val splits are performed correctly based on SMILES features. """ self.assertEqual( len(self.overlaps_train_val), @@ -77,18 +103,19 @@ def test_train_val_overlap_based_on_smiles(self): "Duplicate entities present in Train and Validation set based on SMILES", ) - def test_train_test_overlap_based_on_smiles(self): - """Check that train-test splits are performed correctly i.e.every entity - only appears in one of the train and test set based on smiles tokens/features""" + def test_train_test_overlap_based_on_smiles(self) -> None: + """ + Check that train-test splits are performed correctly based on SMILES features. + """ self.assertEqual( len(self.overlaps_train_test), 0, "Duplicate entities present in Train and Test set based on SMILES", ) - def test_val_test_overlap_based_on_smiles(self): - """Check that val-test splits are performed correctly i.e.every entity - only appears in one of the validation and test set based on smiles tokens/features + def test_val_test_overlap_based_on_smiles(self) -> None: + """ + Check that val-test splits are performed correctly based on SMILES features. """ self.assertEqual( len(self.overlaps_val_test), @@ -96,27 +123,30 @@ def test_val_test_overlap_based_on_smiles(self): "Duplicate entities present in Validation and Test set based on SMILES", ) - def test_train_val_overlap_based_on_ids(self): - """Check that train-val splits are performed correctly i.e.every entity - only appears in one of the train and validation set based on smiles IDs""" + def test_train_val_overlap_based_on_ids(self) -> None: + """ + Check that train-val splits are performed correctly based on SMILES IDs. + """ self.assertEqual( len(self.overlaps_train_val_ids), 0, "Duplicate entities present in Train and Validation set based on IDs", ) - def test_train_test_overlap_based_on_ids(self): - """Check that train-test splits are performed correctly i.e.every entity - only appears in one of the train and test set based on smiles IDs""" + def test_train_test_overlap_based_on_ids(self) -> None: + """ + Check that train-test splits are performed correctly based on SMILES IDs. + """ self.assertEqual( len(self.overlaps_train_test_ids), 0, "Duplicate entities present in Train and Test set based on IDs", ) - def test_val_test_overlap_based_on_ids(self): - """Check that val-test splits are performed correctly i.e.every entity - only appears in one of the validation and test set based on smiles IDs""" + def test_val_test_overlap_based_on_ids(self) -> None: + """ + Check that val-test splits are performed correctly based on SMILES IDs. + """ self.assertEqual( len(self.overlaps_val_test_ids), 0,