minor changes

Author: ritamtbsilva

R/PlotScores.R

@@ -786,16 +786,16 @@ PlotScores_Categorical <- function(data, metadata, gene_sets,
   if (!is.null(title)) title <- wrap_title(title, width = widthTitle)
 
   # Create label for y axis based on method.
-  if (method == "ssGSEA") {
-    ylab <- "ssGSEA Enrichment Score"
-  } else if (method == "logmedian") {
-    ylab <- "Normalised Signature Score"
-  } else if (method == "ranking") {
-    ylab <- "Signature Genes' Ranking"
-  }
+  # if (method == "ssGSEA") {
+  #   ylab <- "ssGSEA Enrichment Score"
+  # } else if (method == "logmedian") {
+  #   ylab <- "Normalised Signature Score"
+  # } else if (method == "ranking") {
+  #   ylab <- "Signature Genes' Ranking"
+  # }
 
   combined_plot <- ggpubr::annotate_figure(combined_plot,
-                                           left = grid::textGrob(ylab,
+                                           left = grid::textGrob(paste0("Gene Set's Score (", method, ")"),
                                                                  rot = 90, vjust = 1,
                                                                  gp = grid::gpar(cex = 1.3,
                                                                                  fontsize = labsize)),
@@ -1093,16 +1093,16 @@ PlotScores_Numeric <- function(data,
   if (!is.null(title)) title <- wrap_title(title, width = widthTitle)
 
   # Create label for y axis based on method.
-  if (method == "ssGSEA") {
-    ylab <- "ssGSEA Enrichment Score"
-  } else if (method == "logmedian") {
-    ylab <- "Normalised Signature Score"
-  } else if (method == "ranking") {
-    ylab <- "Signature Genes' Ranking"
-  }
+  # if (method == "ssGSEA") {
+  #   ylab <- "ssGSEA Enrichment Score"
+  # } else if (method == "logmedian") {
+  #   ylab <- "Normalised Signature Score"
+  # } else if (method == "ranking") {
+  #   ylab <- "Signature Genes' Ranking"
+  # }
 
   combined_plot <- ggpubr::annotate_figure(combined_plot,
-                                           left = grid::textGrob(ylab,
+                                           left = grid::textGrob(paste0("Gene Set's Score (", method, ")"),
                                                                  rot = 90,
                                                                  vjust = 1,
                                                                  gp = grid::gpar(cex = 1.3,

README.Rmd

@@ -26,13 +26,13 @@ knitr::opts_chunk$set(
 
 <!-- badges: end -->
 
-**markeR** provides a suite of methods for using gene sets to quantify and evaluate the extent to which a given gene signature marks a specific phenotype from gene expression data. The package implements various scoring, enrichment and classification approaches, along with tools to compute performance metrics and visualize results.
+**`markeR`** is an R package that provides a modular and extensible framework for the systematic evaluation of gene sets as phenotypic markers using transcriptomic data. The package is designed to support both quantitative analyses and visual exploration of gene set behaviour across experimental and clinical phenotypes.
 
-> **To cite markeR please use:** 
+> **To cite `markeR` please use:** 
 >
 >   Martins-Silva R, Kaizeler A, Barbosa-Morais N (2025). _markeR: an R Toolkit for Evaluating Gene Sets as Phenotypic Markers_. Gulbenkian Institute for Molecular Medicine, Faculdade de Medicina, Universidade de Lisboa, Lisbon, Portugal. R package version 0.99.4, https://github.com/DiseaseTranscriptomicsLab/markeR.
  
-The folder `inst/Paper/` is in the **paper** branch and contains all scripts and materials used in the original markeR paper to reproduce analyses and figures.  You can browse it [here](https://github.com/DiseaseTranscriptomicsLab/markeR/tree/paper/inst/Paper).
+The folder `inst/Paper/` is in the **paper** branch and contains all scripts and materials used in the original `markeR` paper to reproduce analyses and figures.  You can browse it [here](https://github.com/DiseaseTranscriptomicsLab/markeR/tree/paper/inst/Paper).
 
 
 ![](man/figures/Workflow.png)
@@ -69,7 +69,7 @@ library(markeR)
 ```
 
 
-Or install the latest development release of markeR from [GitHub](https://github.com/) with:
+Or install the latest development release of `markeR` from [GitHub](https://github.com/) with:
 
 ``` r
 # install.packages("devtools")
@@ -91,8 +91,6 @@ This package is officially supported on `R > 4.5.0`. ⚠️ Older versions of `R
 
 ## Common Workflow
 
-`markeR` provides a modular pipeline to quantify transcriptomic signatures and assess their association with phenotypic or clinical variables. The typical workflow includes the following steps:
-
 ### 1. Input Requirements 
 
 Depending on the analysis mode, inputs vary slightly.
@@ -129,7 +127,10 @@ gene_sets
 ```
 
 * **Expression Data Frame**:  
-  A filtered and normalised gene expression data frame (genes × samples). Row names must be gene identifiers, and column names must match the sample IDs in the metadata.
+  A filtered and normalised, non log-transformed, gene expression matrix (genes × samples). Row names must be gene identifiers; column names must match sample IDs in the metadata. 
+  
+  **Warning:** If you are using microarray data or outputs from common RNA-seq pipelines (*e.g.*, edgeR), note that the expression values may already be log2-normalised. The input to `markeR` must necessarily be **non-log-transformed**. If your data are log2-transformed, you can revert them by applying `2^data`.
+
 
 ```{r example-expression-matrix, echo=FALSE}
 # Simulate expression matrix: 10 genes × 5 samples
@@ -145,7 +146,7 @@ head(expr_df)
 ```
 
 * **Sample Metadata**:  
-  A data frame with annotations for each sample, with the sample ID in the first column. The row names must match the column names of the expression matrix.
+  A data frame with samples as rows and annotations as columns. The first column should contain sample IDs matching the expression matrix column names.
 
 ```{r example-metadata, echo=FALSE}
 # Simulate sample metadata
@@ -162,82 +163,79 @@ metadata
 
 ### 2. Select Mode of Analysis
 
-* **Discovery Mode**:
-  Explore how a single, well-characterised gene set relates to a specific variable of interest. Suitable for hypothesis generation.
+`markeR` provides two modes of operation:
 
-* **Benchmarking Mode**:
-  Evaluate one or more gene sets against multiple metadata variables using a standardised scoring and effect size framework. This mode provides comprehensive visualisations and comparisons across methods.
+* **Benchmarking**:
+evaluates gene sets' performance in marking a metadata variable, *i.e.*, a phenotype, returning comparative visualisations across scoring and enrichment methods.
+
+* **Discovery**:
+examines the relationship between a gene set and one or more variables of interest, suitable for exploratory or hypothesis-generating analyses. 
 
 ### 3. Choose a Quantification Approach
 
-`markeR` supports two complementary strategies for quantifying the association between gene sets and phenotypes:
+Two complementary strategies are implemented for quantifying associations between gene sets and phenotypes:
 
 #### 3.1 Score-Based Approach
 
-This strategy generates a **single numeric score per sample**, reflecting the activity of a gene set. It enables flexible downstream analyses, including comparisons across phenotypic groups.
-
-Three scoring methods are available:
 
-* **Log2-median**: Calculates the median log2 expression of the genes in the set. Sensitive to absolute shifts in expression.
+A score summarising the collective expression of a gene set therein is assigned **to each sample**. Scores can be visualised using built-in functions, or used directly in downstream analyses (*e.g.*, comparisons between phenotypic groups of samples, correlations with numerical phenotypes). 
 
-* **Ranking**: Ranks all genes within each sample and averages the ranks of gene set members. Captures relative ordering rather than magnitude.
+Available methods:
 
-* **ssGSEA**: Computes a single-sample gene set enrichment score using the ssGSEA algorithm. Reflects the coordinated up- or down-regulation of the set in each sample.
+* **Log2-median**: mean of the across-sample normalised log2 median-centred expression levels of the genes in the set; for bidirectional gene sets, the sample score is the partial score for the subset of putatively upregulated genes minus that of the downregulated subset.
 
-These methods vary in assumptions and sensitivity. Robust gene sets are expected to perform consistently across all three.
+* **Ranking**: mean expression rank of gene set members in each sample; for bidirectional gene sets, the sample score is the partial score for the subset of putatively upregulated genes minus that of the downregulated subset, and normalised by the number of genes in the set. 
 
-#### 3.2 Enrichment-Based Approach
+* **ssGSEA**: single-sample gene set enrichment score using ssGSEA; for bidirectional gene sets, the sample score is the partial score for the subset of putatively upregulated genes minus that of the downregulated subset.
 
-This approach uses a classical **gene set enrichment analysis (GSEA)** framework to evaluate whether the gene set is significantly overrepresented at the top or bottom of a ranked list of genes (e.g., ranked by fold change or correlation with phenotype).
+Gene sets that are robust phenotypic markers are expected to yield consistently high scores across methods.
 
-* **GSEA**: Computes a Normalised Enrichment Score (NES) for each contrast or variable of interest, adjusting for gene set size and multiple testing.
+#### 3.2 Enrichment-Based Approach
 
-Use this approach when interested in collective behaviour of gene sets in relation to ranked differential signals.
+Enrichment-based methods implement **Gene Set Enrichment Analysis (GSEA)**. Genes are ranked according to differential expression statistics, and a Normalised Enrichment Score (NES) per variable of interest is computed, accompanied by a p-value adjusted for multiple hypothesis testing.
 
 ### 4. Visualisation and Evaluation
 
-In **Benchmarking Mode**, `markeR` offers a range of visual summaries:
+In **Benchmarking Mode**, `markeR` offers a range of visual summaries: 
+
+* Violin plots of score distributions by categorical phenotype;
+* Scatter plots of association between scores and numerical phenotypes;
+* Volcano plots and heatmaps of scores or differential gene set expression based on effect sizes (Cohen’s *d* or *f*);
+* ROC curves and respective AUC values of gene sets' phenotypic classification performance;
+* Violin plots of effect size distributions (Cohen’s *d*) for pairwise group differences in scores, for original and simulated gene sets;
+* Plots summarising NES alongside adjusted p-values (*e.g.*, lollipop plots); 
+* GSEA plots showing running enrichment scores across ranked gene lists.
 
-* Violin or scatter plots showing score distributions by phenotype
-* Volcano plots and heatmaps based on effect sizes (Cohen’s *d* or *f*)
-* ROC curves and AUC values 
-* Null distribution testing using random gene sets matched for size and directionality
-* Lollipop plots summarising enrichment scores (NES) with adjusted p-values
-* Enrichment plots showing running enrichment scores across ranked gene lists
-* Volcano plots 
 
 In **Discovery Mode**, the output focuses on a single gene set:
 
-* Score distributions by phenotype
-* Pairwise contrasts (Cohen’s *d*) and overall effect sizes (Cohen’s *f*)
-* Enrichment score summaries (NES) with adjusted p-values (e.g., lollipop plots)
+* Score distributions stratified by variable;
+* Effect sizes for pairwise and multiple-group differences (Cohen's *d* and *f*, respectively);
+* Cross-variable summaries of NES and adjusted p-values (*e.g.*, lollipop plots).
 
-Benchmarking mode offers the most comprehensive set of features and allows users to seamlessly move from discovery to benchmarking mode once a variable of interest has been identified and further testing is required. The main difference from Discovery mode is that Benchmarking is designed to evaluate multiple gene sets simultaneously, whereas Discovery mode focuses on quantifying a single, robust gene set.
+The Benchmarking Mode offers the most comprehensive set of features. Users are allowed to seamlessly move from Discovery to Benchmarking once a variable of interest has been identified and further testing is required. Benchmarking is designed to evaluate multiple gene sets simultaneously, whereas Discovery focuses on the performance of a single gene set.
 
 ### 5. Individual Gene Exploration  
 
-To better understand the contribution of individual genes within a gene set and identify whether specific genes drive the overall signal, `markeR` offers a suite of gene-level exploratory analyses, including:
+To better understand the contribution of individual genes within a gene set, and identify whether specific genes drive the set's collective signal,  `markeR` provides `VisualiseIndividualGenes.` Available options include:
 
-* Expression heatmaps of genes across samples and groups
-* Violin plots showing expression distributions of individual genes
-* Correlation heatmaps to reveal co-expression patterns among genes in the set
-* ROC curves and AUC values for individual genes to evaluate their discriminatory power
-* Effect size calculations (Cohen’s *d*) per gene to quantify differential expression
-* Principal Component Analysis (PCA) on gene set genes to assess variance explained and sample clustering
+* Expression heatmaps of genes across samples or groups of samples;
+* Violin plots showing cross-sample expression distributions of individual genes; 
+* Heatmaps of pairwise cross-sample expression correlation between genes in the set;
+* ROC curves and AUC values to evaluate single genes' performance as phenotypic markers;
+* Effect size estimation (Cohen’s *d*) of expression differences between groups of samples;
+* Principal Component Analysis (PCA) of expression of genes in the set, to evaluate which genes dominate collective variance and how samples separate according to the gene set's expression.
 
 ### 6. Compare with Reference Gene Sets  
 
-`markeR` allows comparison of user-defined gene sets to reference sets (e.g., from MSigDB) using:
+`markeR` also supports comparison of user-defined gene sets against reference collections (e.g., MSigDB). Two complementary similarity metrics are implemented:
 
 * **Jaccard Index**:
-  Measures gene overlap relative to union size.
+the ratio of the number of genes in common over the total number of genes in the two sets.
 
-* **Log Odds Ratio (logOR)**:
-  Computes enrichment using a user-defined gene universe and Fisher’s exact test.
-
-Filters can be applied based on similarity thresholds (e.g., minimum Jaccard, OR, or p-value).
- 
+* **Log Odds Ratio (logOR)** from Fisher’s exact test of association between gene sets, given a specified gene universe.
 
+Filters can be applied based on similarity thresholds (e.g., minimum Jaccard, OR, or Fisher's test p-value).
 
 ## Contact