API

Classes in SLTL

EarlyStopping

EarlyStopping callback implementation.

EarlyStopper = SLTL.EarlyStopping(limit = 20)

Params:

  • limit: Number of iterations to check for earlystopping (Default: 20)

Attributes:

  • limit: Number of iterations to check for earlystopping
  • counter: A counter to keep in track of iterations for earlystopping
  • prev_loss: Stores the lowest previous loss

Returns:

  • An early stopping object.

SLModelSimple

A simple deep learning model framework, consisting of only three layers. Call using one of create_model functions.

model = SLTL.SLModelSimple(hyperparams, model = None, tol = 1e-3, masks = None)

Params:

  • hyperparams: Hyperparameter dict created by get_hyperparams function
  • model: A PyTorch model if transfer learning is used in training the model, None otherwise. (Default: None)
  • tol: Used to identify weights that are close to 0 within tolerance. (Default: 1e-3)
  • masks: A list of masks responding to each layer (i.e., weight and bias parameters) that should be frozen

Returns:

  • A PyTorch model

Standard functions in SLTL

extract_SLTL_notebook

Extracts the study SLTL notebook to the specified location.

SLTL.extract_SLTL_notebook(location = os.getcwd())

Params:

  • location: Location to extract SLTL notebook. (Default: Current working directory)

Returns:

  • None.

extract_template_notebook

Extracts the custom SLTL notebook to the specified location.

SLTL.extract_template_notebook(location = os.getcwd())

Params:

  • location: Location to extract SLTL notebook. (Default: Current working directory)

Returns:

  • None.

ensemble_avg

Obtains the ensemble prediction of the available transfer learning models.

predictions, labels = SLTL.ensemble_avg(ensembl_dict)

Params:

  • ensembl_dict: A dict containing TL methods' predictions and labels for the given instance

Returns:

  • A tuple of two elements:
    • predictions: Ensemble prediction of the input methods

read_results

Loads the results for a deep learning model's evaluation.

results_dict = SLTL.read_results(results_dict, regression_task, full_for_TL, res_location, task = 'deep_learning', category = ' (Target)')

Params:

  • results_dict: Metric evaluations of the trained model, returned as a dict
  • regression_task: TRUE if regression task (GCE), FALSE if classification task (SL)
  • full_for_TL: TRUE if entire dataset was used in model's training, FALSE otherwise
  • res_location: Path to result directory
  • task: One of the three: 'deep_learning', 'linear', or 'logistic'
    • 'deep_learning': deep learning model (Default)
    • 'logistic': logistic regression
    • 'linear': linear regression
  • category: The category of the transfer learning application result. Usually one of the three: ' (Source)', ' (Target)', or ' (Final)'
    • ' (Source)': performance of the source model
    • ' (Target)': performance of the target model (Default)
    • ' (Final)': performance of the final model. If transfer learning was not applied (i.e., no source model), then this result acts in place of either source or target performance in transfer learning task.

Returns:

  • results_dict: Metric evaluations of the trained model, including the new category results, returned as a dict

split_shapley

Categorizes Shapley values to the specific omics profiles.

EXP, CN, CE = SLTL.split_shapley(shapley_values)

Params:

  • shapley_values: A pandas dataframe of shapley values

Returns:

  • EXP: Shapley value of expression omics x gene set membership
  • CN: Shapley value of copy number omics x gene set membership
  • CE: Shapley value of CRISPR effect omics x gene set membership

obtain_results_TL

Extracts results from saved model performances.

results_df = SLTL.obtain_results_TL(res_location, 
                                    regression_task, 
                                    disinclude_status, 
                                    application, 
                                    full_for_TL, 
                                    target_study, 
                                    target_cl, 
                                    target_res_location, 
                                    train_data,
                                    test_data,
                                    val_data,
                                    left_out_genes,
                                    final_shapley,
                                    source_shapley = None,
                                    source_study = None, 
                                    source_cl = None, 
                                    source_res_location = None,
                                    TL_method = 'noTL')

Params:

  • res_location: Path to saved results.
  • regression_task: TRUE if regression task (GCE), FALSE if classification tasks (SL)
  • disincude_status: Based on evaluation category, either 'leave-gene-out' or 'random'
  • full_for_TL: If TRUE, all data was used for TL (suggested to be TRUE).
  • target_study: Study targeted in prediction.
  • target_cl: Cell line targeted in prediction.
  • target_res_location: Path to saved target results location.
  • train_data: Used training dataset.
  • test_data: Used testing dataset.
  • val_data: Used validation dataset.
  • left_out_genes: All genes left out of training, under 'leave-gene-out' category.
  • final_shapley: Shapley values calculated in the target data's evaluation.
  • source_shapley: Shapley values for source study (if extracting results from a TL instance)
  • source_study: Source study's name (if extracting results from a TL instance)
  • source_cl: Source study's cell line name (if extracting results from a TL instance)
  • source_res_location: Source study's saved results location (if extracting results from a TL instance)
  • TL_method: Applied TL method. One of the following:
    • 'noTL'
    • 'Finetune'
    • 'FeatureExtraction'
    • 'FreezeHighWeights'
    • 'ShapleyFreeze'

Returns:

  • results_df: Dataframe containing results.

calculate_batch_size

Calculates batch size for a dataset based on fraction.

batch_size = SLTL.calculate_batch_size(data, frac = 0.1)

Params:

  • data: A pandas dataframe
  • frac: Fraction of data to use in batches.

Returns:

  • batch_size: Batch size matching the fraction

create_all_input_based_on_data

Creates gene pair features from the input data.

generated_features = SLTL.create_all_input_based_on_data(input_data, node_features, way = 'sum')

Params:

  • input_data: A pandas dataframe, containing gene pair information within columns 'gene_1' and 'gene_2'
  • node_features: Generated gene set features for the individual genes
  • way: The way to generate the features. 'sum' for adding the two genes' features, and 'matrix' for their matrix multiplication. Default: sum

Returns:

  • generated_features: A pandas dataframe of the generated gene pair features

Calculates metrics of SL classification and GCE regression tasks.

all_metrics = SLTL.print_metrics(call_out, ground_truth, silent = False, regression = False, limit = 0.5)

Params:

  • call_out: Model prediction
  • ground_truth: Golden labels
  • silent: TRUE to print out metrics as they are calculated, FALSE otherwise. Default: FALSE
  • regression: TRUE if regression task (GCE), FALSE if classification task (SL)
  • limit: If classification task, the threshold to determine SL relationship

Returns:

  • all_metrics: Calculated metrics. The full metric list is as follows:
    • F-1
    • Accuracy
    • AUC-ROC
    • Precision
    • Recall
    • Average Precision (AUPR)
    • Hinge
    • KL Divergence
    • Cosine Similarity
    • MSE
    • MAE
    • R2 Score
    • Pearson correlation
    • Spearman correlation

pad_missing

Pad missing values.

res = SLTL.pad_missing(curr_data, gene_list, pad_val = 0)

Params:

  • curr_data: pandas dataframe with existing values
  • gene_list: gene list that we want to have values for
  • pad_val: padding value. Default: 0

Returns:

  • res: Pandas dataframe of existing and padded values for the input gene list

merge_dict

Merge MSigDB dicts.

dd = SLTL.merge_dict(d1, d2)

Params:

  • d1: d1 dict
  • d2: d2 dict

Returns:

  • dd: d1 and d2 dict combined

Helper functions

downsampler

Downsampler for SL tasks.

train, test, val = SLTL.downsampler(df, train_perc, test_perc, val_perc, seed, downsampling, pos_idx, neg_idx)

Params:

  • df: input data dataframe
  • train_perc: percentage of data samples to use in training
  • test_perc: percentage of data samples to use in testing
  • val_perc: percentage of data samples to use in validation
  • seed: the seed for downsampler
  • pos_idx: positive sample indices
  • neg_idx: negative sample indices

Returns:

  • A tuple of three elements:
    • train: trainining set dataframe
    • test: testing set dataframe
    • val: validation set dataframe

leave_out_type_split

Separate data based on leave-gene-out setting.

train, test, val = SLTL.leave_out_type_split(df, leave_out_setting, train_perc = 0.8, test_perc = 0.1, val_perc = 0.1, seed = 42)

Params:

  • df: input data dataframe
  • leave_out_setting: A dict of two elements; 'select' indicates list of genes and 'mode' indicates whether to have at least one sampled gene ('1 gene') or two sampled genes ('2 gene') within gene pair.
  • train_perc: percentage of data samples to use in training
  • test_perc: percentage of data samples to use in testing (unused)
  • val_perc: percentage of data samples to use in validation (unused)

Returns:

  • A tuple of three elements:
    • train: trainining set dataframe
    • test: testing set dataframe
    • val: validation set dataframe

pandas_to_train_split_validation

Create train, test, and validation splits of input dataset.

train, test, val = SLTL.pandas_to_train_split_validation(df, train_perc = 0.8, test_perc = 0.1, val_perc = 0.1, seed = 42, downsampling = True, regression = False, leave_out_setting = {'select': None, 'mode': '1 gene'})

Params:

  • df: input data dataframe
  • leave_out_setting: A dict of two elements; 'select' indicates list of genes and 'mode' indicates whether to have at least one sampled gene ('1 gene') or two sampled genes ('2 gene') within gene pair.
  • train_perc: percentage of data samples to use in training
  • test_perc: percentage of data samples to use in testing (unused)
  • val_perc: percentage of data samples to use in validation (unused)

Returns:

  • A tuple of three elements:
    • train: trainining set dataframe
    • test: testing set dataframe
    • val: validation set dataframe

create_input_based_on_data

Generate gene pair features with or without multi-omics.

generated_features, input_labels = SLTL.create_input_based_on_data(input_data, input_labels, cl_annotations, node_features, way = 'sum', cl_specificity = None, set_ones = False)

Params:

  • input_data: input data dataframe
  • input_labels: labels for the data points. {0, 1} for SL, and [-1, 1] for GCE.
  • cl_annotations: A list of cell line annotations for each datapoint.
  • node_features: A dataframe of each gene and it's features, i.e. gene x features
  • way: the way to generate the features. Either 'sum', for summation, or 'matrix', for matrix multiplication.
  • cl_specificity: A dict of cell lines and their omics profiles. If None, no cell line omics are used.
  • set_ones: Enables setting the features that are higher than 1 as 1 before omics are added. Default: FALSE

Returns:

  • generated_features: A numpy array of generated features
  • input_labels: labels for the data points.

calculate_SHAP

Calculate shapley values for gene pairs in SL and GCE tasks, mainly for when using gene set information as features.

shapley_res = SLTL.calculate_SHAP(model, data, node_features, hyperparams)

Params:

  • model: trained model
  • data: data to calculate shapley values for
  • node_features: A dataframe of each gene and it's features, i.e. gene x features
  • hyperparams: hyperparameters dict, created via get_hyperparams function

Returns:

  • shapley_res: A pandas series of calculated shapley values for gene set and EXP, CN, and CE profiles.

fit_to_SL_LR

Fit a new or transfer learning model for SL classification or GCE regression task. 

results = SLTL.fit_to_SL_LR(input_data, node_features, hyperparams, cl_specificity = None, full_for_TL = False, model = None, grid_search_setting = 'loss')

Params:

  • input_data: data that contains gene pair information and target (SL/GCE) labels
  • node_features: A dataframe of each gene and it's features, i.e. gene x features
  • hyperparams: hyperparameters dict, created via get_hyperparams function
  • cl_specificity: A dict of cell lines and their omics profiles. If None, no cell line omics are used.
  • full_for_TL: TRUE if all data is used to train the model (to be used in transfer learning later), FALSE otherwise
  • model: A pytorch source model to use in transfer learning, or None for training a model without using transfer learning
  • grid_search_setting: Setting to use to get best learning rate. Default: 'loss'. Otherwise, 'score' uses F-1 or spearman correlation for SL and GCE tasks respectively.

Returns:

  • A dictionary of the following items for reproducibility:
    • res: train/test/val split of the data
    • model: trained model
    • hyperparams: a copy of hyperparameters dict
    • data: a copy of input_data
    • shap_expected: expected shapley value
    • shap_values: calculated shapley values for each input feature

evaluate_on_data

Evaluate a trained model on input data.

metrics_result, tuples = SLTL.evaluate_on_data(trained_model, input_data, node_features, hyperparams, mode = '50/50', limit = 0.5, silent = False, cl_specificity = None)

Params:

  • trained_model: Trained PyTorch model
  • input_data: data that contains gene pair information and target (SL/GCE) labels
  • node_features: A dataframe of each gene and it's features, i.e. gene x features
  • hyperparams: hyperparameters dict, created via get_hyperparams function
  • mode: How the test data should be prepared. One of the following:
    • 'train': Training data is used for testing
    • 'test': Testing data is used for testing
    • 'val': Validation data is used for testing
    • Other: All data is used for testing
  • cl_specificity: A dict of cell lines and their omics profiles. If None, no cell line omics are used.

Returns:

  • A tuple of the following items:
    • metrics_result: A dict of the all metrics evaluations for the selected testing data.
    • A tuple:
      • all_data: data used in evaluation
      • all_labels: labels used in evaluation
      • call_out: model predictions for evaluation data

Model saving and loading functions

save_results

Save results of model training.

SLTL.save_results(results, save_loc, name = 'save')

Params:

  • results: Output of fit_to_SL_LR
  • save_loc: Directory path to all results
  • name: Name of the directory for the results. Default: 'save'

Returns:

  • None

load_results

Load prior saved results.

results = SLTL.load_results(save_loc, name = 'save', set_device = None)

Params:

  • save_loc: Directory path to all results
  • name: Name of the directory for the results. Default: 'save'
  • set_device: Pytorch device to load the model to. Default: None

Returns:

  • A dict containing all hyperparams and training results from before.

get_hyperparams

Create hyperparameters to use in every model, transfer learning and otherwise.

hyperparams = SLTL.get_hyperparams(model_name = 'model', learning_rate = 1e-3, device = 'cpu', batch_size = 128, epochs = 1000, feature_way = 'sum', callback_patience = 20, num_features = 1000, logs_dir = 'logs', optimizer = None, leave_out_setting = {'select': 15, 'mode': '1 gene'}, regression = True, downsample = True, seed = 42)

Params:

  • model_name: Name of the model
  • learning_rate: Learning rate to use in training (default: 1e-3)
  • device: PyTorch device to use for model training and inference (default: 'cpu')
  • batch_size: Batch size to use for model training (default: 128)
  • epochs: Number of iterations to train for (default: 1000)
  • feature_way: The style to use for generating gene pair features (default: 'sum')
  • callback_patience: Early stopping patience (default: 20)
  • num_features: Number of features to use as input (default: 1000)
  • logs_dir: Directory to use to save model logs (default: 'logs')
  • optimizer: Specific optimizer to use during model training. If None, BCELoss and L1Loss will be used for SL and GCE tasks respectively (Default: None)
  • leave_out_setting: A dict of two elements; 'select' indicates list of genes and 'mode' indicates whether to have at least one sampled gene ('1 gene') or two sampled genes ('2 gene') within gene pair.
  • regression: If True, regression task for GCE prediction. If False, classification tasks for SL prediction.
  • downsample: If True, data is downsampled (for SL data only)
  • seed: Seed to use for various purposes.

Returns:

  • A dict of hyperparameters

Functions for deep learning modeling

init_weights

Initialize weights for PyTorch's linear (i.e., fully connected) layers.

SLTL.init_weights(m)

Params:

  • m: model layer

Returns:

  • None

create_model

A simple function that creates and initializes a deep learning model, without transfer learning.

model = SLTL.create_model(hyperparams, silent = True)

Params:

  • hyperparams: Hyperparameter dict created by get_hyperparams function
  • silent: If True, messages will be silenced (Default: True)

Returns:

  • Model: A PyTorch model

create_model_w_transfer

A simple function that creates and initializes a deep learning model, to be used in transfer learning.

model = SLTL.create_model_w_transfer(model, hyperparams, silent = False, masks = None)

Params:

  • model: Model to use in transfer learning.
  • hyperparams: Hyperparameter dict created by get_hyperparams function
  • silent: If True, messages will be silenced (Default: False)
  • masks: List of masks to use in freezing features. Default: None

Returns:

  • model: A PyTorch model

get_top_informative_feature_idx

A function to get top N or relevant features that have an impact in the output via Shapley values. 

res = SLTL.get_top_informative_feature_idx(shap_values, n = 100, get_all_SL = False, include_non_SL = True, regression_task = True)

Params:

  • shap_values: Calculated shapley values
  • n: Top N features to get. Not used if get_all_SL is TRUE
  • get_all_SL: TRUE if all features that skew towards SL/nGCE are queried, FALSE otherwise (Default: False)
  • include_non_SL: TRUE to include features that skew towards non SL/pGCE predictions, FALSE otherwise (Default: True)
  • regression_task: TRUE if shapley values were calculated for GCE regression, FALSE otherwise (Default: TRUE)
    • Note: In SL predictions, a score over 0.5 is SL, and non SL otherwise otherwise. In GCE predictions, a negative and positive score indicates negative and positive GCE.
    • In summary, positive impacting shapley values in classification task are for SL labels, and negative impacting shapley values in regression are for negative GCE labels.

Returns:

  • res: Indeces of features to freeze

transfer_weights_w_freeze

A transfer learning model is created using the available transfer learning approaches.

model = SLTL.transfer_weights_w_freeze(source_model, hyperparams, type_of_transfer = 'Finetune', masks = None, silent = False)

Params:

  • source_model: Source model to use in transfer learning
  • hyperparams: Hyperparameter dict created by get_hyperparams function
  • type_of_transfer: Type of transfer learning approach to use
    • 'Finetune': A fine tuning approach (all layers are retrained) (Default)
    • 'FeatureExtraction': A feature extraction approach (first layer is frozen, remaining are retrained)
    • 'FreezeHighWeights': Approach where high impacting weights are frozen
    • 'ShapleyFreeze': Approach where the first layer's parameters are frozen if they are relevant to select shapley values, remaining are retrained
  • masks: List of masks to use in freezing features. Default: None

Returns:

  • transfer_model: A PyTorch model

identify_masks

A helper function to identify the parameters directly impacted by input features, only for the first layer.

masks = SLTL.identify_masks(model, idx_to_freeze, type_of_mask = 'first')

Params:

  • model: Model to use in transfer learning
  • idx_to_freeze: Indices of features to freeze (in the first layer)
  • type_of_mask: Type of parameter mask to create.
    • First: Mask generated only for the first layer and it's weights (not bias) (Default)

Returns:

  • masks: A list of masks corresponding to model parameter sizes.