acore.enrichment_analysis package

acore.enrichment_analysis package#

Enrichment Analysis Module. Contains different functions to perform enrichment analysis.

Most things in this module are covered in https://www.youtube.com/watch?v=2NC1QOXmc5o by Lars Juhl Jensen.

run_fisher(group1: list[int], group2: list[int], alternative: str = 'two-sided') → tuple[float, float][source]#

Run fisher’s exact test on two groups using scipy.stats.fisher_exact.

Example:

# annotated   not-annotated
# group1      a               b
# group2      c               d


odds, pvalue = stats.fisher_exact(group1=[a, b],
                                  group2 =[c, d]
                )
run_gsea(regulation_data: DataFrame, annotation: DataFrame, identifier: str = 'identifier', ranking_col: str = 'log2FC', annotation_col: str = 'annotation', identifier_col: str = 'identifier', min_size: int = 15, max_size: int = 500, permutation_num: int = 1000, seed: int = 42, weight: float = 1.0, ascending: bool = False, correction_alpha: float = 0.05) → DataFrame[source]#

Run Gene Set Enrichment Analysis (GSEA) on a pre-ranked gene list using gseapy.prerank.

Genes are ranked by ranking_col (e.g. log2 fold-change from differential expression analysis) and enrichment is computed for each gene set defined in annotation. Unlike overrepresentation analysis (ORA), GSEA does not require a significance cutoff to split genes into foreground/background; it uses the full ranked list instead.

Parameters:

  • regulation_data (pd.DataFrame) – DataFrame with differential regulation results. Must contain the column specified by identifier and the column specified by ranking_col. Each identifier must appear at most once (duplicates are not allowed).

  • annotation (pd.DataFrame) – DataFrame with functional annotations. Must contain annotation_col and identifier_col.

  • identifier (str) – Column in regulation_data containing feature identifiers. These must match the identifiers in annotation_col of the annotation DataFrame.

  • ranking_col (str) – Column in regulation_data used to rank the features (e.g. 'log2FC'). Features are ranked in descending order by default so that strongly up-regulated features appear at the top.

  • annotation_col (str) – Column in annotation containing annotation term names (e.g. pathway names).

  • identifier_col (str) – Column in annotation containing feature identifiers that map to identifier in regulation_data.

  • min_size (int) – Minimum number of features in a gene set that are also present in the ranking. Gene sets smaller than this threshold are excluded.

  • max_size (int) – Maximum number of features in a gene set that are also present in the ranking. Gene sets larger than this threshold are excluded.

  • permutation_num (int) – Number of permutations used to estimate nominal p-values. Higher values give more precise p-values but increase runtime. Default: 1000.

  • seed (int) – Random seed for reproducibility. Default: 42.

  • weight (float) – Exponent for the enrichment score weighting. weight=1 (default) corresponds to weighted GSEA; weight=0 gives classic (unweighted) GSEA.

  • ascending (bool) – Sort order for the ranking. False (default) means descending (highest ranking metric first, suited for log2FC).

  • correction_alpha (float) – FDR q-value cutoff used to define the 'rejected' column. Default: 0.05.

Returns:

DataFrame with one row per gene set. Columns are: 'Term', 'ES' (enrichment score), 'NES' (normalised enrichment score), 'NOM p-val' (nominal p-value), 'FDR q-val' (gseapy’s permutation-based FDR q-value), 'FWER p-val', 'Tag %', 'Gene %', 'Lead_genes' (semi-colon-separated leading-edge genes) and 'rejected' ('FDR q-val' <= correction_alpha).

Return type:

pd.DataFrame

Example:

result = run_gsea(
    regulation_data=diff_reg,
    annotation=annotations,
    identifier='identifier',
    ranking_col='log2FC',
    annotation_col='annotation',
    identifier_col='identifier',
    min_size=5,
    permutation_num=100,
)
run_kolmogorov_smirnov(dist1: list[float], dist2: list[float], alternative: str = 'two-sided') → tuple[float, float][source]#

Compute the Kolmogorov-Smirnov statistic on 2 samples. See scipy.stats.ks_2samp

Parameters:

  • dist1 (list) – sequence of 1-D ndarray (first distribution to compare) drawn from a continuous distribution

  • dist2 (list) – sequence of 1-D ndarray (second distribution to compare) drawn from a continuous distribution

  • alternative (str) – defines the alternative hypothesis (default is ‘two-sided’): * ‘two-sided’ * ‘less’ * ‘greater’

Returns:

statistic float and KS statistic pvalue float Two-tailed p-value.

Example:

result = run_kolmogorov_smirnov(dist1, dist2, alternative='two-sided')
run_site_regulation_enrichment(regulation_data: DataFrame, annotation: DataFrame, identifier: str = 'identifier', groups: list[str] = ('group1', 'group2'), annotation_col: str = 'annotation', rejected_col: str = 'rejected', group_col: str = 'group', method: str = 'fisher', regex: str = '(\\w+~.+)_\\w\\d+\\-\\w+', correction: str = 'fdr_bh', remove_duplicates: bool = False) → DataFrame[EnrichmentAnalysisSchema][source]#

This function runs a simple enrichment analysis for significantly regulated protein sites in a dataset.

Parameters:

  • regulation_data – pandas.DataFrame resulting from differential regulation analysis.

  • annotation – pandas.DataFrame with annotations for features (columns: ‘annotation’, ‘identifier’ (feature identifiers), and ‘source’).

  • identifier (str) – name of the column from annotation containing feature identifiers.

  • groups (list) – column names from regulation_data containing group identifiers.

  • annotation_col (str) – name of the column from annotation containing annotation terms.

  • rejected_col (str) – name of the column from regulation_data containing boolean for rejected null hypothesis.

  • group_col (str) – column name for new column in annotation dataframe determining if feature belongs to foreground or background.

  • method (str) – method used to compute enrichment (only ‘fisher’ is supported currently).

  • regex (str) – how to extract the annotated identifier from the site identifier

Returns:

pandas.DataFrame with columns: ‘terms’, ‘identifiers’, ‘foreground’, ‘background’, foreground_pop, background_pop, ‘pvalue’, ‘padj’ and ‘rejected’.

Raises:

ValueError – if regulation_data is None or empty.

Example:

result = run_site_regulation_enrichment(regulation_data,
    annotation,
    identifier='identifier',
    groups=['group1', 'group2'],
    annotation_col='annotation',
    rejected_col='rejected',
    group_col='group',
    method='fisher',
    match="(\\w+~.+)_\\w\\d+\\-\\w+"
)
run_up_down_regulation_enrichment(regulation_data: DataFrame, annotation: DataFrame, identifier: str = 'identifier', groups: list[str] = ('group1', 'group2'), annotation_col: str = 'annotation', pval_col: str = 'pval', group_col: str = 'group', log2fc_col: str = 'log2FC', method: str = 'fisher', min_detected_in_set: int = 2, correction: str = 'fdr_bh', correction_alpha: float = 0.05, lfc_cutoff: float = 1, permutations: int = 0, seed: int | None = None) → DataFrame[EnrichmentAnalysisSchema][source]#

This function runs a simple enrichment analysis for significantly regulated proteins distinguishing between upregulation per group defined by the groups. Only overrepresentation is tested using one-sided Fisher’s exact tests.

Parameters:

  • regulation_data (pandas.DataFrame) – pandas.DataFrame resulting from differential regulation analysis (CKG’s regulation table).

  • annotation (pandas.DataFrame) – pandas.DataFrame with annotations for features (columns: ‘annotation’, ‘identifier’ (feature identifiers), and ‘source’).

  • identifier (str) – name of the column from annotation containing feature identifiers.

  • groups (list[str]) –

    column names from regulation_data containing group identifiers. See pandas.DataFrame.groupby for more information.

  • annotation_col (str) – name of the column from annotation containing annotation terms.

  • rejected_col (str) – name of the column from regulation_data containing boolean for rejected null hypothesis.

  • group_col (str) – column name for new column in annotation dataframe determining if feature belongs to foreground or background.

  • method (str) – method used to compute enrichment (only ‘fisher’ is supported currently).

  • correction (str) – method to be used for multiple-testing correction. Use 'efdr' to apply empirical FDR via permutation (requires permutations > 0).

  • alpha (float) – adjusted p-value cutoff to define significance

  • lfc_cutoff (float) – log fold-change cutoff to define practical significance

  • permutations (int) – number of permutations used to estimate the empirical FDR when correction='efdr'. Ignored for other correction methods.

  • seed (int | None) – seed of the random number generator used for the permutations when correction='efdr', for reproducible results.

Returns:

DataFrame adhering to EnrichmentAnalysisSchema

Return type:

DataFrame[EnrichmentAnalysisSchema]

Example:

result = run_up_down_regulation_enrichment(
    regulation_data,
    annotation,
    identifier='identifier',
    groups=['group1',
    'group2'],
    annotation_col='annotation',
    rejected_col='rejected',
    group_col='group',
    method='fisher',
    correction='fdr_bh',
    alpha=0.05,
    lfc_cutoff=1,
)

Subpackages#

Submodules#