core.dataclasses#

This module contains the classes defining the structure of the datasets to be used with the core.model.BulkDGD.

class bulkdgd.core.dataclasses.GeneExpressionDataset(df: DataFrame, labels: list[str] | None = None, scaling_factor: str = 'mean')#

Class implementing a dataset containing gene expression data for multiple samples.

This class is designed so that it can be used with the torch.utils.data.DataLoader utility, if needed.

__init__(df: DataFrame, labels: list[str] | None = None, scaling_factor: str = 'mean') → None#

Initialize an instance of the class.

Parameters:
dfpandas.DataFrame

A data frame whose rows must represent samples, and columns must represent genes.

Therefore, each cell of the data frame represents the expression of the gene on the column in the sample on the row.

For example:

,gene_1,gene_2,gene_3,gene_4
sample_1,123,12,2342,145
sample_2,189,184,2397,1980
sample_3,978,9467,563,23
labelslist, optional

A list of labels for the samples.

scaling_factorstr, {"mean", "median"}, "mean"

How to compute the scaling factor of a sample - the number the decoder’s predicted means are multiplied by to put them on the scale of the sample’s own counts.

  • "mean": the mean count over all of the sample’s genes.

  • "median": the median count over all of the sample’s genes.

The mean is what the model has always used, and it is not robust: a handful of genes take a large and variable share of a library, and they drag the mean with them. In GTEx the thirteen mitochondrial genes alone - 0.09% of the genes - take 14.49% of the reads, and the share runs from 0.10% to 90.85% from one sample to the next. That moves the mean by up to a factor of eleven between two samples, and the factor is a property of how the sample was handled rather than of the tissue it came from.

The median is not moved by them: over the same samples, the mitochondrial genes change it by at most 3.7%.

The two are not interchangeable in a trained model. The median is about a third of the mean, and the decoder is fitted against whichever it was trained with - a model trained with one and run with the other has its predicted means off by a factor of about three. This is why the option lives in the model’s configuration and not in the training one: it is a property of the model, and everything done with the model afterwards has to use the same one.

property data_exp#

A 2D tensor where:

  • The first dimension has a length equal to the number of samples in the dataset.

  • The second dimension has a length equal to the number of genes whose expression is reported in the dataset.

property genes#

The names of the genes included in the dataset.

property mean_exp#

A 1D tensor with length equal to the number of samples in the dataset containing the scaling factor of each sample - the mean or the median of its gene expression, according to scaling_factor.

property samples#

The names/IDs/indexes of the samples in the dataset.

property scaling_factor#

How the scaling factor of a sample is computed - either "mean" or "median".