core.model#

This module contains the class implementing the full BulkDGD model (core.model.BulkDGG).

class bulkdgd.core.model.BulkDGD(latent_dim: int, latent_options: dict[str, object], decoder_options: dict[str, object], latent_type: str = 'tgmm', genes_txt_file: str | None = None, device: str = 'cpu')#

Class implementing the BulkDGD model.

static rescale_pred_means(df_pred_means: DataFrame, df_pred_r_values: DataFrame) → DataFrame#

Rescale the means of the negative binomials modeling the genes’ counts.

Parameters:
df_pred_meanspandas.DataFrame

A data frame containing the predicted scaled means of the negative binomials modeling the genes’ counts.

Here, each row contains the scaled mean for a given representation/sample, and the columns contain either the values of the scaled means or additional information.

The columns containing the scaled means must be named after the corresponding genes’ Ensembl IDs.

df_pred_r_valuespandas.DataFrame

A data frame containing the predicted r-values of the negative binomials modeling the genes’ counts.

Here, each row contains the r-value for a given representation/sample, and the columns contain either the r-values or additional information.

The columns containing the r-values must be named after the corresponding genes’ Ensembl IDs.

Returns:
df_scaledpandas.DataFrame

A data frame containing the predicted means.

It contains the same columns of the df_pred_means data frame, in the same order they appear in the df_pred_means data frame.

However, the values in the columns containing the predicted means are scaled back by the corresponding r-values.

__init__(latent_dim: int, latent_options: dict[str, object], decoder_options: dict[str, object], latent_type: str = 'tgmm', genes_txt_file: str | None = None, device: str = 'cpu') → None#

Initialize an instance of the class.

The model is initialized on the CPU. To move the model to another device, modify the device property.

Parameters:
latent_dimint

The dimensionality of the latent space.

latent_typestr, {"lgmm", "tgmm"}, "tgmm"

The type of the latent space to use.

The available options are:

latent_optionsdict

The options for setting up the latent space.

For the available options, refer to the Configuration for creating an instance of the BulkDGD model page.

decoder_optionsdict

The options for setting up the decoder.

For the available options, refer to the Configuration for creating an instance of the BulkDGD model page.

genes_txt_filestr

A plain text file containing the Ensembl IDs of the genes included in the model.

Training data will be checked to ensure counts are reported for all genes.

The number of output units in the decoder is initialized from the number of genes found in this file.

devicestr, "cpu"

The device where the model will be initialized. The model is initialized on the CPU by default.

get_probability_density(df_rep: DataFrame) → DataFrame#

Given a set of representations, get the probability density of each component of the Gaussian mixture model for each representation and the representation(s) having the maximum probability density for each component.

Parameters:
df_reppandas.DataFrame

A data frame containing the representations.

Returns:
df_prob_reppandas.DataFrame

A data frame containing the probability densities for each representation, together with an indication of what the maximum probability density found is and for which component it is found.

df_prob_comppandas.DataFrame

A data frame containing, for each component, the representation(s) having the maximum probability density for the component, together with the probability density for that(those) representation(s).

get_representations(df_samples: DataFrame, config_rep: dict[str, object], get_saliency_map: bool = False) → tuple[DataFrame, DataFrame, DataFrame | None, DataFrame]#

Find the best representations for a set of samples.

Parameters:
df_samplespandas.DataFrame

A data frame containing the samples.

config_repdict

A dictionary of options for the optimization(s). It varies according to the selected method.

The supported options for all available methods can be found here.

get_saliency_mapbool, optional

Whether to also compute and return the saliency maps showing the importance of each latent dimension for each gene’s expression based on the obtained representations. Default: False.

Returns:
df_reppandas.DataFrame

A data frame containing the representations.

Here, each row contains a representation and the columns contain either the values of the representations’ along the latent space’s dimensions or additional information about the input samples found in the input data frame. Columns containing additional information, if present in the input data frame, will appear last in the data frame.

df_pred_meanspandas.DataFrame

A data frame containing the predicted means of the distributions modelling the genes’ counts for the representations found.

Here, each row contains the predicted means for a given representation, and the columns contain either the mean of a distribution or additional information about the input samples found in the input data frame. Columns containing additional information, if present in the input data frame, will appear last in the data frame.

If the genes counts are modelled using negative binomial distributions, the predicted means are scaled by the corresponding distributions’ r-values.

df_pred_r_valuespandas.DataFrame, optional

A data frame containing the predicted r-values of the negative binomials for the representations found, if the genes’ counts are modelled by negative binomial distributions

Here, each row contains the predicted r-values for a given representation, and the columns contain either the r-value of a negative binomial or additional information about the input samples found in the input data frame. Columns containing additional information, if present in the input data frame, will appear last in the data frame.

df_pred_r_values is None if the genes’ counts are modelled by Poisson distributions.

df_timepandas.DataFrame

A data frame containing data about the CPU and wall clock time used by each epoch (and backpropagation step within each epoch) in each optimization step.

Here, each row represents an epoch of an optimization step, and the columns contain data about the platform where the calculation was run, the number of CPU threads used by the computation, and the CPU and wall clock time used by the entire epoch and by the backpropagation step run inside it.

df_saliency_mappandas.DataFrame, optional

A data frame containing the gradients indicating the importance of each latent dimension for each gene’s expression.

Here, each row is a gene (indexed by ENSG naming) and columns correspond to each latent dimension. Returned as an element of a tuple uniquely when get_saliency_map is True.

train(df_samples: DataFrame, names_train: list, names_test: list, config_train: dict[str, object], gmm_pth_file: str = 'gmm.pth', dec_pth_file: str = 'dec.pth', pathways: DataFrame | None = None, labels_train: object | None = None, labels_test: object | None = None) → tuple[tuple[DataFrame, DataFrame], tuple[DataFrame, DataFrame], tuple[DataFrame, DataFrame] | None, DataFrame, tuple[DataFrame, DataFrame] | None, DataFrame]#

Train the model.

Parameters:
df_samplespandas.DataFrame

A data frame containing the samples.

Each row should contain a unique sample, and each column should either contain a gene’s expression for that sample (if the column is named after the gene’s Ensembl ID) or additional information about the sample.

names_trainlist

A list of the names of the training samples, which should be a subset of the names of the samples in the input data frame.

names_testlist

A list of the names of the test samples, which should be a subset of the names of the samples in the input data frame.

config_traindict

A dictionary of options for the training.

gmm_pth_filestr, "gmm.pth"

The .pth file where to save the GMM’s trained parameters (means of the components, weights of the components, and log-variance of the components).

dec_pth_filestr, "dec.pth"

The .pth file where to save the decoder’s trained parameters (weights and biases).

pathwaysdict, optional

A dictionary where the keys are pathway names and the values are lists of genes’ Ensembl IDs belonging to each pathway.

It is needed if save_pathways_saliency_maps_epoch is set to True.

labels_trainnumpy.ndarray, optional

The ground-truth labels for the training samples.

labels_testnumpy.ndarray, optional

The ground-truth labels for the test samples.

Returns:
dfs_reptuple

A tuple (df_rep_train, df_rep_test) with the optimized latent representations for training and testing samples.

dfs_pred_meanstuple

A tuple (df_pred_means_train, df_pred_means_test) with the predicted decoder means for training and testing samples.

dfs_pred_r_valuesNone or pandas.DataFrame or tuple

The predicted r-values, depending on the output module:

df_losspandas.DataFrame

A data frame containing the losses calculated during training.

dfs_metricsNone or tuple

The per-epoch metrics rows for training and testing samples, depending on whether the user requested to calculate metrics during training:

  • None if the user did not request to calculate metrics during training.

  • A tuple (df_metrics_train, df_metrics_test) of data frames, where each data frame contains the metrics calculated for the training or test samples in a given epoch, if the user requested to calculate metrics during training.

df_timepandas.DataFrame

A data frame containing the training-time metrics.

property decoder#

The decoder.

property device#

The device where the model is.

property latent#

The latent space.