analysis.residuals#

Utilities to compute vectors of residuals.

bulkdgd.analysis.residuals.get_genes_by_residual_threshold(df_res: DataFrame, le_than: int | float = -1, ge_than: int | float = 1, sort_genes: bool = False, ascending: bool = False) → tuple[DataFrame, DataFrame, DataFrame, DataFrame]#

Get the genes whose residuals fall in specified intervals and are common to a certain number of samples.

Parameters:
df_respandas.DataFrame

A data frame containing the residual vectors for a set of samples.

le_thanint or float, -1

Consider only genes whose residual value in all samples is lower than or equal to the provided value.

ge_thanint or float, 1

Consider only genes whose residual value in all samples is greater than or equal to the provided value.

Returns:
df_samples_count_lepandas.DataFrame

A data frame containing each gene with the count of samples where the gene’s residual value is lower than or equal to le_than.

The data frame’s rows are identified by each gene’s ID (as provided in the input data frame) and the data frame includes one column:

  • ‘n_samples’: the number of samples where the gene’s residual meets the condition.

df_genes_distribution_lepandas.DataFrame

A data frame displaying the distribution of genes having a residual value lower than or equal to le_than across different sample counts.

Each row represents the number of samples, and the columns are:

  • ‘n_genes’: the number of genes that meet the condition in exactly that many samples.

  • ‘genes’: a period-separated string listing the genes that meet the condition in exactly that many samples.

df_samples_count_gepandas.DataFrame

A data frame containing each gene with the count of samples where the gene’s residual value is greater than or equal to ge_than.

The data frame’s rows are identified by each gene’s ID (as provided in the input data frame) and the data frame includes one column:

  • ‘n_samples’: the number of samples where the gene’s residual meets the condition.

df_genes_distribution_gepandas.DataFrame

A data frame displaying the distribution of genes having a residual value greater than or equal to le_than across different sample counts.

Each row represents the number of samples, and the columns are:

  • ‘n_genes’: the number of genes that meet the condition in exactly that many samples.

  • ‘genes’: a period-separated string listing the genes that meet the condition in exactly that many samples..

bulkdgd.analysis.residuals.get_residuals(obs_counts: Series, pred_means: Series, r_values: Series | None = None, sample_name: str | None = None) → Series#

Calculate the vector of residuals between the observed gene expression (counts) and the predicted means of the negative binomials modeling the expression of the different genes for a single sample.

Parameters:
obs_countspandas.Series

The observed gene counts in a single sample.

This is a series whose index contains either the genes’ Ensembl IDs or names of fields containing additional information about the sample.

pred_meanspandas.Series

The predicted means of the distributions modelling the genes’ counts in a single sample.

This is a series whose index contains either the genes’ Ensembl IDs or names of fields containing additional information about the sample.

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

r_valuespandas.Series, optional

The predicted r-values of the negative binomial distributions modelling the genes’ counts in a single sample, if the genes’ counts were modelled using negative binomial distributions.

This is a series whose index contains either the genes’ Ensembl IDs or names of fields containing additional information about the sample.

If r_values is not provided, it is assumed that the genes’ counts were modelled using Poisson distributions.

sample_namestr, optional

The name of the sample under consideration. It is used as name for the pandas.Series returned.

If not passed, the series will be unnamed.

Returns:
series_residualspandas.Series

A series containing the residuals for all genes.

bulkdgd.analysis.residuals.get_significant_genes(series_residuals: Series, res_pos_threshold: int | float = 1, res_neg_threshold: int | float = -1) → Series#

Get the genes that are significant at a given significance level.

Parameters:
series_residualspandas.Series

A series containing the residuals for all genes in a single sample.

The series’ index contains the genes’ Ensembl IDs, and its values are the residuals.

res_pos_thresholdint or float, 1

The threshold above which a gene is considered significantly up-regulated.

res_neg_thresholdint or float, -1

The threshold below which a gene is considered significantly down-regulated.