Package {XYomics}

XYomics: Analysis of Sex Differences in Omics Data

Description

The **XYomics** package provides functions for performing differential expression analysis, pathway enrichment, gene regulatory network analysis, and comprehensive report generation for omics data.

Details

This package is designed to integrate various omics analyses (e.g., functional omics and single-cell data) with advanced visualization and reporting tools.

Author(s)

Maintainer: Enrico Glaab enrico.glaab@uni.lu

Authors:

• Sophie Le Bars sophie.lebars@uni.lu

• Mohamed Soudy mohamed.soudy@uni.lu

Other contributors:

• Murodzhon Akhmedov [copyright holder]

Prize-collecting Steiner Forest (PCSF)

Description

PCSF returns a subnetwork obtained by solving the PCSF on the given interaction network.

Usage

PCSF(ppi, terminals, w = 2, b = 1, mu = 5e-04, dummies)

Arguments

Details

The PCSF is a well-know problem in graph theory. Given an undirected graph G = (V, E), where the vertices are labeled with prizes p_{v} and the edges are labeled with costs c_{e} > 0, the goal is to identify a subnetwork G' = (V', E') with a forest structure. The target is to minimize the total edge costs in E', the total node prizes left out of V', and the number of trees in G'. This is equivalent to minimization of the following objective function:

F(G')= Minimize \sum_{ e \in E'} c_{e} + \beta*\sum_{v \not\in V'} p_v + \omega*k

where, k is the number of trees in the forest, and it is regulated by parameter \omega. The parameter \beta is used to tune the prizes of nodes.

This optimization problem nicely maps onto the problem of finding differentially enriched subnetworks in the cell protein-protein interaction (PPI) network. The vertices of interaction network correspond to genes or proteins, and edges represent the interactions among them. We can assign prizes to vertices based on measurements of differential expression, copy number, or mutation, and costs to edges based on confidence scores for those intra-cellular interactions from experimental observation, yielding a proper input to the PCSF problem. Vertices that are assigned a prize are referred to terminal nodes, whereas the vertices which are not observed in patient data are not assigned a prize and are called Steiner nodes. After scoring the interactome, the PCSF is used to detect a relevant subnetwork (forest), which corresponds to a portion of the interactome, where many genes are highly correlated in terms of their functions and may regulate the differentially active biological process of interest. The PCSF aims to identify neighborhoods in interaction networks potentially belonging to the key dysregulated pathways of a disease. In order to avoid a bias towards the hub nodes of PPI networks to appear in solution of PCSF, we penalize the prizes of Steiner nodes according to their degree distribution in PPI, and it is regulated by parameter \mu:

p'_{v} = p_{v} - \mu*degree(v)

The parameter \mu also affects the total number of Steiner nodes in the solution. Higher the value of \mu smaller the number of Steiners in the subnetwork, and vice-versa. Based on our previous analysis the recommended range of \mu for biological networks is between 1e-4 and 5e-2, and users can choose the values resulting subnetworks with vertex sets that have desirable Steiner/terminal node ratio and average Steiner/terminal in-degree ratio in the template interaction network.

Value

The final subnetwork obtained by the PCSF. It return an igraph object with the node prize and edge cost attributes.

Author(s)

Murodzhon Akhmedov

References

Akhmedov M., LeNail A., Bertoni F., Kwee I., Fraenkel E., and Montemanni R. (2017) A Fast Prize-Collecting Steiner Forest Algorithm for Functional Analyses in Biological Networks. Lecture Notes in Computer Science, to appear.

Internal function call_sr

Description

This function is internally used to solve the PCST.

Usage

call_sr(from, to, cost, node_names, node_prizes)

Arguments

Author(s)

Murodzhon Akhmedov

Compute sex-specific differentially expressed genes (DEGs) per category

Description

Identifies male-specific, female-specific, sex-dimorphic, and sex-neutral DEGs from differential expression results. "sex-modulated" requires the interaction mode and is not identified by categorize_sex.

Usage

categorize_sex(
  male_degs,
  female_degs,
  alpha = 0.05,
  beta = 0.5,
  min_abs_logfc = 0.25
)

Arguments

Value

Data frame containing categorized DEGs with associated statistics.

Perform Pathway Enrichment Analysis for Pre-Categorized DEGs

Description

Performs pathway enrichment analysis for categorized DEGs using GO, KEGG, Reactome, or a custom TERM2GENE database.

Usage

categorized_enrich(
  DEGs_category,
  enrichment_db = "KEGG",
  organism = "hsa",
  gene_type = "SYMBOL",
  org_db = NULL,
  custom_db = NULL,
  pvalueCutoff = 0.05,
  qvalueCutoff = 0.2,
  return_df = FALSE
)

Arguments

Details

Gene IDs converted only when needed; KEGG/Reactome require ENTREZID; GO/CUSTOM use provided gene_type.

Value

Named list of enrichment results per DEG_Type.

Construct Protein-protein interaction Network using Prize-Collecting Steiner Forest

Description

Constructs a condition-specific gene regulatory network based on differential expression results using the PCSF algorithm.

Usage

construct_ppi_pcsf(
  g,
  prizes,
  w = 2,
  b = 1,
  mu = 5e-04,
  seed = 1,
  min_nodes = 1
)

Arguments

Value

An igraph object representing the extracted subnetwork. Returns NULL invisibly if no prize genes are present, the subnetwork is too small, or the PCSF algorithm fails.

An igraph object representing the extracted subnetwork. Returns NULL invisibly if no prize genes are present, the subnetwork is too small, or the PCSF algorithm fails

Convert gene identifiers in a DEG table

Description

Convert gene identifiers in a DEG table

Usage

convert_gene_ids(
  df,
  fromType,
  toType = "SYMBOL",
  org_db = NULL,
  gene_col = "Gene_Symbols",
  remove_na = TRUE,
  remove_duplicates = TRUE
)

Arguments

Value

Updated data frame with converted gene IDs

Generate a Comprehensive Analysis Report

Description

This function creates an integrated report that combines key analysis outputs,

Usage

generate_cat_report(
  results_cat,
  enrichment_cat,
  grn_cat,
  output_file = "cat_analysis_report.html",
  output_dir = tempdir(),
  template_path = NULL,
  quiet = TRUE
)

Arguments

Value

A character string with the path to the rendered report.

Generate dotplot of selected genes across groups

Description

Visualizes gene expression across Sex / Phenotype / Cell type combinations.

Usage

generate_dotplot_sc(
  seurat_obj,
  genes,
  sex = "sex",
  phenotype = "status",
  celltype_col = "cell_type",
  target_cell_type_flag = "all"
)

Arguments

Value

A ggplot object (DotPlot)

Generate Violin Plots for Bulk Expression Data

Description

Creates violin plots displaying the distribution of gene expression values across Sex and Phenotype groups for a set of selected genes. Multiple genes (up to 10) are visualized using faceting.

Usage

generate_violinplot_bulk(
  expression_data,
  sex,
  phenotype,
  genes,
  sex_labels_vector = c("F", "M"),
  phenotype_labels_vector = c("WT", "TG")
)

Arguments

Value

A 'ggplot' object containing the violin plots.

Download and Process STRING Protein-Protein Interaction Network

Description

Downloads and processes the STRING protein-protein interaction network, converting it to a simplified igraph object. The function downloads the network from STRING database, filters interactions by confidence score, converts STRING IDs to ENTREZ IDs, and returns the largest connected component as an undirected graph.

Usage

get_string_network(
  organism = "9606",
  score_threshold = 700,
  use_default = TRUE
)

Arguments

Details

STRING combined scores range from 0 (low confidence) to 1000 (high confidence). Because PCSF treats edge weights as traversal costs to be minimized, scores are inverted via 1 - score/1000 so that higher-confidence interactions correspond to lower costs. The function performs the following steps:

1. Downloads protein interactions from STRING database

2. Filters interactions based on combined score

3. Downloads and processes STRING ID to ENTREZ ID mappings

4. Creates an igraph object with filtered interactions

5. Removes self-loops and multiple edges

6. Extracts the largest connected component

Value

An igraph object representing the largest connected component of the filtered STRING network, with the following properties:

• Undirected edges

• No self-loops

• No multiple edges

• Edge weights (1 - combined_score/1000)

• Vertex names as ENTREZ IDs

Get Top Hub Genes by Betweenness Centrality

Description

Computes normalized betweenness centrality for an igraph network and returns the top N hub nodes ranked by centrality.

Usage

get_top_hubs(g, top_n = 10, directed = FALSE)

Arguments

Value

A named numeric vector of betweenness scores for the top hub nodes.

Create enrichment dotplots from enrichResult objects

Description

Generates dotplots from enrichment results. Input must contain enrichResult objects (clusterProfiler / ReactomePA). Invalid entries are skipped with messages. Works for single enrichResult, flat list (DEG types), or nested list (cell type → DEG type).

Usage

plot_enrichment_dotplots(enrichment_results, showCategory = 10, ncol = 2)

Arguments

Value

Named list of combined ggplots. For nested input, names correspond to cell types; for flat input, a single '"all"' entry is returned.

Plot a condition-specific protein–protein interaction network with DEG annotations

Description

Visualizes a gene or protein interaction network for a selected differential expression category. Nodes are sized by degree centrality, and hub genes can be optionally annotated with mini barplots showing sex-specific log fold changes.

Usage

plot_network(
  g,
  DEG_type,
  result_categories,
  cell_type = "",
  top_hubs = 20,
  show_barplot = FALSE
)

Arguments

Details

Nodes represent genes or proteins and edges represent interactions. Node size reflects degree centrality (number of connections). The top top_hubs nodes by degree are labeled. When show_barplot = TRUE, mini barplots are overlaid on hub nodes to display sex-specific log fold changes. The visualization is restricted to the largest connected component of the network.

Value

A ggplot object representing the network visualization.

Examples

# Minimal reproducible example (CRAN-safe)
library(igraph)

# Create a small toy network
g <- make_ring(5)
V(g)$name <- paste0("Gene", 1:5)

# Create minimal DEG table
result_categories <- data.frame(
  DEG_Type = rep("example", 5),
  Gene_Symbols = paste0("Gene", 1:5),
  Male_avg_logFC = runif(5, -1, 1),
  Female_avg_logFC = runif(5, -1, 1)
)

# Run function
plot_network(g, DEG_type = "example", result_categories = result_categories)

Generate protein-protein interaction network plots for single-cell DEGs

Description

Accepts a nested list of igraph networks (cell_type × DEG_type) object and produces annotated network visualizations.

Usage

plot_network_pipeline(
  network_list,
  result_categories_list,
  top_hubs = 20,
  ncol = 2,
  show_barplot = FALSE
)

Arguments

Value

Named list of network plots per cell type (or '"all"' for single network)

Generate volcano plots for categorized DEGs

Description

Creates volcano plots for all DEG categories (male-specific, female-specific, sex-dimorphic, sex-neutral). Accepts either a single data.frame (bulk) or a list of data.frames per cell type.

Usage

plot_volcano_deg(de_results, top_n = 5, logfc_thresh = 1.5, ncol = 2)

Arguments

Value

Named list of combined volcano plots per cell type or "all" for bulk.

Run PPI PCSf pipeline for single cell DEG categories

Description

Builds protein protein interaction subnetworks for each cell type based on DEG categories and FDR derived node prizes.

Usage

ppi_pipeline(result_categories, g, target_cell_type_flag = "all")

Arguments

Value

A named list containing PCSf networks per cell type and DEG category.

Perform Sex-Phenotype Interaction Analysis for Bulk Data

Description

Identifies genes whose expression is modulated by the interaction between sex and phenotype using a differential difference contrast

Usage

sex_interaction_analysis_bulk(
  expression_data,
  phenotype,
  sex,
  phenotype_labels_vector = c("WT", "TG"),
  sex_labels_vector = c("F", "M"),
  min_logfc = 0.25,
  alpha = 0.05,
  min_samples = 20
)

Arguments

Value

A list with all DE results, filtered significant DEGs, and summary statistics.

Perform Sex-Phenotype Interaction Analysis for Single-Cell Data

Description

Performs differential difference analysis for a given cell type to identify genes modulated by sex-phenotype interactions using limma.

Usage

sex_interaction_analysis_sc(
  seurat_obj,
  target_cell_type,
  sex = "sex",
  phenotype = "status",
  celltype_col = "cell_type",
  min_logfc = 0.25,
  alpha = 0.05,
  sex_labels_vector = c("F", "M"),
  phenotype_labels_vector = c("WT", "TG"),
  min_samples = 20
)

Arguments

Value

A list with all DE results, filtered significant DEGs, and summary statistics.

Run sex phenotype interaction analysis pipeline for single cell data

Description

Performs sex phenotype interaction analysis per cell type using a limma based difference in differences model.

Usage

sex_interaction_pipeline_sc(
  seurat_obj,
  target_cell_type_flag = "all",
  sex = "sex",
  phenotype = "status",
  celltype_col = "cell_type",
  min_logfc = 0.25,
  alpha = 0.05,
  sex_labels_vector = c("F", "M"),
  phenotype_labels_vector = c("WT", "TG"),
  min_samples = 20
)

Arguments

Value

A named list containing interaction analysis results per cell type.

Perform differential expression analysis within each sex

Description

This function identifies differentially expressed genes between phenotype groups separately for each sex using limma (default), DESeq2, or edgeR.

Usage

sex_stratified_analysis_bulk(
  expression_data,
  sex,
  phenotype,
  sex_labels_vector = c("F", "M"),
  phenotype_labels_vector = c("WT", "TG"),
  min_samples = 3,
  method = c("limma", "deseq2", "edger")
)

Arguments

Details

For each sex, the function subsets the data and fits the appropriate model:

• limma: Fits a linear model via lmFit + eBayes on the input matrix directly. Suitable for microarray, proteomics, or pre-normalized RNA-seq data. If raw RNA-seq counts are provided, the function automatically detects integer matrices and applies limma-voom internally with a warning. For full control, consider using "edger" or "deseq2" instead, or apply voom externally and pass the transformed data with method = "limma".

• DESeq2: Fits a negative binomial GLM via DESeq2::DESeq(). Requires raw integer counts. Performs internal normalization (median-of-ratios) and dispersion estimation.

• edgeR: Fits a negative binomial GLM via edgeR::glmQLFit() + edgeR::glmQLFTest(). Requires raw integer counts. Performs TMM normalization internally.

Positive logFC values indicate higher expression in the test phenotype (second element of phenotype_labels_vector) compared to the reference (first element).

Value

A list with three elements:

male_DEGs

A data.frame of DE results for males.

female_DEGs

A data.frame of DE results for females.

validation

Output from validate_input_bulk().

Regardless of the method, each DEG data.frame contains the standardized columns avg_log2FC, p_val, p_val_adj, and gene, with gene names as rownames. Additional method-specific columns (e.g. baseMean for DESeq2, logCPM for edgeR, AveExpr for limma) are retained for reference.

Perform sex-stratified differential expression analysis for single-cell Seurat object

Description

Perform sex-stratified differential expression analysis for single-cell Seurat object

Usage

sex_stratified_analysis_sc(
  seurat_obj,
  sex = "sex",
  phenotype = "status",
  celltype_col = "cell_type",
  sex_labels_vector = c("F", "M"),
  phenotype_labels_vector = c("WT", "TG"),
  test.use = "wilcox",
  min_samples = 3
)

Arguments

Value

A list with two elements: 'male_DEGs' and 'female_DEGs', each containing a list of DEGs per cell type.

Run sex stratified differential expression pipeline for single cell data

Description

Performs sex specific differential expression analysis per cell type and categorizes genes into male specific, female specific, sex dimorphic, and sex neutral groups.

Usage

sex_stratified_pipeline_sc(
  seurat_obj,
  target_cell_type_flag = "all",
  sex = "sex",
  phenotype = "status",
  celltype_col = "cell_type",
  sex_labels_vector = c("F", "M"),
  phenotype_labels_vector = c("WT", "TG"),
  test.use = "wilcox",
  alpha = 0.05,
  beta = 0.5,
  min_abs_logfc = 0.25,
  min_samples = 3
)

Arguments

Value

A named list of categorized differential expression results per cell type.

Validate bulk input data for sex-stratified analysis

Description

Validate bulk input data for sex-stratified analysis

Usage

validate_input_bulk(
  expression_data,
  sex,
  phenotype,
  sex_labels_vector = c("F", "M"),
  phenotype_labels_vector = c("WT", "TG"),
  min_samples = 3
)

Arguments

Value

A list with validation status, ratios, imbalance flag, and group counts

Validate single-cell input data for sex-stratified analysis

Description

Validate single-cell input data for sex-stratified analysis

Usage

validate_input_sc(
  seurat_obj,
  sex = "sex",
  phenotype = "status",
  celltype_col = "cell_type",
  sex_labels_vector = c("F", "M"),
  phenotype_labels_vector = c("WT", "TG"),
  min_cells = 3
)

Arguments

Value

A list with validation status, ratios, imbalance flag, and group counts