### Example: plotScoreLandscape with ranked and scored data

Source: https://github.com/davislaboratory/singscore/blob/master/man/plotScoreLandscape.Rd

This example ranks genes, scores them with simpleScore for two gene sets, and plots the landscape. It uses the toy_expr_se, toy_gs_up, and toy_gs_dn datasets.

```R
ranked <- rankGenes(toy_expr_se)
scoredf <- simpleScore(ranked, upSet = toy_gs_up, downSet = toy_gs_dn)
scoredf2 <- simpleScore(ranked, upSet = toy_gs_up)
plotScoreLandscape(scoredf, scoredf2)
```

--------------------------------

### Install singscore from Bioconductor

Source: https://github.com/davislaboratory/singscore/blob/master/vignettes/singscore.Rmd

Installs the singscore package using BiocManager. Requires BiocManager to be installed first. Use this method for the stable Bioconductor release.

```R
if (!requireNamespace("BiocManager", quietly=TRUE))
    install.packages("BiocManager")
BiocManager::install("singscore")
```

--------------------------------

### Install singscore with BiocManager

Source: https://github.com/davislaboratory/singscore/blob/master/README.md

Installs the singscore package from Bioconductor using BiocManager. The comment notes that build_vignettes = TRUE is used to build vignettes upon installation. Requires BiocManager to be installed first.

```R
# build_vignettes = TRUE to build vignettes upon installation
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("singscore", version = "3.8")
```

--------------------------------

### Install singscore from GitHub using devtools

Source: https://github.com/davislaboratory/singscore/blob/master/vignettes/singscore.Rmd

Installs the development version of singscore from GitHub. Requires the devtools package. Optionally set build_vignette = TRUE to browse vignettes. The package depends on several Bioconductor and CRAN packages.

```R
# You would need to install 'devtools' package first.
 install.packages("devtools")

# And install the 'singscore' package from the GitHub repository
# 'singscore' requires these packages to be installed: methods, stats, graphics, ggplot2, ggsci, grDevices,
#  ggrepel, plotly, tidyr, plyr, magrittr, reshape, edgeR, RColorBrewer, Biobase, GSEABase, BiocParallel
 devtools::install_github('DavisLaboratory/singscore')
# Set build_vignette = TRUE if would like to browseVignette()
```

--------------------------------

### simpleScore

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/simpleScore.md

Documentation for the simpleScore function, including its usage, arguments, and an example.

```APIDOC
## simpleScore

### Description
Scores a sample against a gene signature using ranked data. When the ranked data was built with stable genes, the score bounds are automatically set to 0..1.

### Usage
```r
simpleScore(rankData, upSet, downSet)
```

### Arguments
- **rankData** (matrix) - Required - A matrix of ranked gene expression data, typically produced by `rankGenes`.
- **upSet** (GeneSet) - Required - A gene set representing the up-regulated signature.
- **downSet** (GeneSet) - Required - A gene set representing the down-regulated signature.

### Details
When `rankData` was built by `rankGenes(..., stableGenes = <genes>)` (so `attr(rankData, 'stable') == TRUE`), `simpleScore` automatically uses score bounds `0..1` via `calcBounds(..., stableSc = TRUE)`. This is the scoring mode for panel-based measurements (nanostring, RT-qPCR).

### Example
```r
stable_genes <- getStableGenes(5)
measured     <- unique(c(stable_genes, geneIds(toy_gs_up), geneIds(toy_gs_dn)))
rankData_st  <- rankGenes(toy_expr_se[measured, ], stableGenes = stable_genes)
scoredf_st   <- simpleScore(rankData_st, upSet = toy_gs_up, downSet = toy_gs_dn)
```

### Value
A data.frame with scores, as documented in [types](../types.md).
```

--------------------------------

### getStableGenes usage and examples

Source: https://github.com/davislaboratory/singscore/blob/master/man/getStableGenes.Rd

The usage section shows the function signature with default arguments. The examples demonstrate calling getStableGenes with different parameters: default type and id, ensembl IDs, and blood tissue type.

```r
getStableGenes(
  n_stable,
  type = c("carcinoma", "blood", "protein"),
  id = c("geneid", "ensembl")
)
```

```r
getStableGenes(5)
```

```r
getStableGenes(5, id = 'ensembl')
```

```r
getStableGenes(5, type = 'blood')
```

--------------------------------

### Load example datasets and inspect gene sets

Source: https://github.com/davislaboratory/singscore/blob/master/vignettes/singscore.Rmd

Loads the singscore and GSEABase libraries, then loads example expression data and gene signatures. Inspects the expression object, sample names, and gene set sizes. Use this to prepare for scoring with simpleScore().

```R
library(singscore)
library(GSEABase)
# The example expression dataset and gene signatures are included in the package
# distribution, one can directly access them using the variable names

# To see the description of 'tgfb_expr_10_se','tgfb_gs_up','tgfb_gs_dn', look at 
# their help pages using:

# ?tgfb_expr_10_se
# ?tgfb_gs_up
# ?tgfb_gs_dn

# Have a look at the object tgfb_expr_10_se containing gene expression data
# for 10 samples 
tgfb_expr_10_se

# Get the sample names by
colnames(tgfb_expr_10_se)

# View what tgfb_gs_up/dn contains
tgfb_gs_up
tgfb_gs_dn

# Get the size of the gene sets
length(GSEABase::geneIds(tgfb_gs_up))
length(GSEABase::geneIds(tgfb_gs_dn))
```

--------------------------------

### Basic usage example

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/getPvals.md

Shows the typical workflow: rank genes, compute scores, generate null distribution, and obtain p-values for a subset of samples.

```r
library(singscore)

ranked <- rankGenes(toy_expr_se)
scoredf <- simpleScore(ranked, upSet = toy_gs_up, downSet = toy_gs_dn)

permuteResult <- generateNull(
  upSet = toy_gs_up, downSet = toy_gs_dn, ranked,
  B = 10, seed = 1, useBPPARAM = BiocParallel::registered()[[1]]
)

pvals <- getPvals(permuteResult, scoredf, subSamples = 1:5)
pvals   # named numeric vector, one p-value per sample
```

--------------------------------

### plotDispersion example: basic and interactive plots

Source: https://github.com/davislaboratory/singscore/blob/master/man/plotDispersion.Rd

Example usage of plotDispersion with a ranked expression set and simpleScore output. The first call creates a basic plot, the second enables interactive mode.

```r
ranked <- rankGenes(toy_expr_se)
scoredf <- simpleScore(ranked, upSet = toy_gs_up, downSet = toy_gs_dn)
plotDispersion(scoredf)
plotDispersion(scoredf, isInteractive = TRUE)
```

--------------------------------

### plotScoreLandscape

Source: https://github.com/davislaboratory/singscore/blob/master/man/plotScoreLandscape.Rd

Documentation for the plotScoreLandscape function, including usage, arguments, return value, and examples.

```APIDOC
## plotScoreLandscape

### Description
Plots the landscape of two gene signature scores, showing the relationship between scores from two signatures on the same set of samples. It takes two data frames that are outputs from the `simpleScore()` function and produces a scatter plot (or hex bin plot) of the two scores.

### Usage
```r
plotScoreLandscape(
  scoredf1,
  scoredf2,
  scorenames = c(),
  textSize = 1.2,
  isInteractive = FALSE,
  hexMin = 100
)
```

### Arguments
- **scoredf1** (data.frame) - Required - Result of the `simpleScore()` function which scores the gene expression matrix against a gene set of interest.
- **scoredf2** (data.frame) - Required - Result of the `simpleScore()` function which scores the gene expression matrix against another gene set of interest.
- **scorenames** (character vector of length 2) - Optional - Names for the two scored gene set/signatures stored in `scoredf1` and `scoredf2`. Default is `c()`.
- **textSize** (numeric) - Optional - Set the text size for the plot. Default is `1.2`.
- **isInteractive** (boolean) - Optional - Whether the plot is interactive. Default is `FALSE`.
- **hexMin** (integer) - Optional - The threshold which decides whether hex bin plot or scatter plot is displayed. Default is `100`.

### Value
A ggplot object, a scatter plot, demonstrating the relationship between scores from two signatures on the same set of samples.

### Details
`scoredf1` and `scoredf2` are two scoring results of the same set of samples against two different gene signatures. If you wish to use the plotting function with customized inputs (instead of outputs from the `simpleScore` function), you need to make sure the formats are the same. Specifically, you need to have column names `"TotalScore"`, `"TotalDispersion"`, `"UpScore"`, `"UpDispersion"`, `"DownScore"`, `"DownDispersion"` and row names as samples.

### Examples
```r
ranked <- rankGenes(toy_expr_se)
scoredf <- simpleScore(ranked, upSet = toy_gs_up, downSet = toy_gs_dn)
scoredf2 <- simpleScore(ranked, upSet = toy_gs_up)
plotScoreLandscape(scoredf, scoredf2)
```
```

--------------------------------

### Error handling example

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/getPvals.md

Demonstrates the error when sample counts mismatch: a single-row scoredf against a 5-sample permutation matrix triggers stopifnot.

```r
# scoredf subset with only 1 row vs. a 5-sample permutation matrix
res <- tryCatch(
  getPvals(permuteResult, scoredf[1, , drop = FALSE]),
  error = function(e) e
)   # stopifnot(ncol(permuteResult) == nrow(scoredf)) fires
```

--------------------------------

### simpleScore(rankData, upSet, downSet, subSamples, centerScore, dispersionFun, knownDirection)

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/simpleScore.md

Documentation for the simpleScore S4 generic function, including its four method signatures, arguments, return value, and usage examples.

```APIDOC
## simpleScore(rankData, upSet, downSet, subSamples, centerScore, dispersionFun, knownDirection)

### Description
Computes single-sample scores for gene expression data using up- and down-regulated gene sets. Supports multiple input types for gene sets (character vectors or GeneSet objects) and optional sample subsetting and centering.

### Usage
```r
simpleScore(rankData, upSet, downSet = NULL, subSamples = NULL, centerScore = TRUE, dispersionFun = mad, knownDirection = TRUE)
```

### Arguments
- **rankData** (matrix) - Required - A matrix of ranked gene expression data (e.g., output of `rankGenes`).
- **upSet** (vector or GeneSet) - Required - Gene set of up-regulated genes. Character vectors are coerced to GeneSet objects.
- **downSet** (vector or GeneSet) - Optional - Gene set of down-regulated genes. Default is NULL.
- **subSamples** (character vector) - Optional - Subset of sample names to score. Default is NULL (all samples).
- **centerScore** (logical) - Optional - Whether to center scores. Default is TRUE.
- **dispersionFun** (function) - Optional - Dispersion function. Note: the source hard-codes `mad` at call sites; the argument is accepted but not forwarded. Effective behavior is `mad`.
- **knownDirection** (logical) - Optional - Whether the direction of the gene sets is known. Default is TRUE. Must be logical; otherwise an error is raised.

### Details
All four S4 method signatures delegate to `singleSingscore(rankData, upSet, downSet, subSamples, centerScore, dispersionFun, knownDirection)`. The `vector` methods coerce via `GSEABase::GeneSet(as.character(upSet))`.

### Value
A data.frame with columns: `TotalScore`, `TotalDispersion`, `UpScore`, `UpDispersion`, `DownScore`, `DownDispersion`. If no genes overlap with the data, an empty (0-row) data.frame is returned.

### Examples
```r
library(singscore)
rankData <- rankGenes(toy_expr_se)

# up/down gene-set pair (GeneSet objects shipped with the package)
scoredf <- simpleScore(rankData, upSet = toy_gs_up, downSet = toy_gs_dn)
scoredf
#   TotalScore TotalDispersion UpScore UpDispersion DownScore DownDispersion

# single gene set with unknown direction
scoredf1 <- simpleScore(rankData, upSet = toy_gs_up, knownDirection = FALSE)

# character vectors are accepted anywhere a GeneSet is accepted
scoredf2 <- simpleScore(rankData,
                        upSet = c('geneA', 'geneB'),
                        downSet = c('geneC'))

# subset of samples and centering off
scoredf3 <- simpleScore(rankData, upSet = toy_gs_up, downSet = toy_gs_dn,
                        subSamples = c('D_Ctrl_R1'), centerScore = FALSE)
```

### Error Handling
- Invalid `knownDirection` (non-logical) raises an error via `stopifnot()`.
- Gene sets with no overlap with the data return an empty (0-row) data.frame.
- Genes not measured in the dataset are dropped with a warning.
```

--------------------------------

### Generate Static Rank Density Plots

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/plotRankDensity.md

Examples of generating static plots using GeneSet objects or character vectors. Note that drop = FALSE is required when subsetting the ranked matrix.

```r
library(singscore)

ranked <- rankGenes(toy_expr_se)

# second sample only; upSet alone is fine for unpaired gene sets
plotRankDensity(ranked[, 2, drop = FALSE], upSet = toy_gs_up)

# paired gene sets
plotRankDensity(ranked[, 2, drop = FALSE],
                upSet = toy_gs_up, downSet = toy_gs_dn, isInteractive = FALSE)

# character vectors are accepted
plotRankDensity(ranked[, 1, drop = FALSE],
                upSet = c('geneA', 'geneB'), downSet = c('geneC'))
```

--------------------------------

### Estimate empirical p-values with getPvals

Source: https://github.com/davislaboratory/singscore/blob/master/man/getPvals.Rd

Runs the full workflow: rank genes, score samples, generate null distributions with generateNull, then compute p-values with getPvals. The example checks registered BiocParallel backends and uses B=10 permutations with a seed. The p-value for each sample is estimated using a one-tailed test; a p-value of 1/B indicates the estimated p-value is less than or equal to 1/B.

```R
ranked <- rankGenes(toy_expr_se)
scoredf <- simpleScore(ranked, upSet = toy_gs_up, downSet = toy_gs_dn)
# find out what backends can be registered on your machine
BiocParallel::registered()
# the first one is the default backend, and it can be changed explicitly.
# See vignette for more details
permuteResult = generateNull(upSet = toy_gs_up, downSet = toy_gs_dn, ranked,
B =10, seed = 1, useBPPARAM = NULL)

# call the permutation function to generate the empirical scores
# for B times.
pvals <- getPvals(permuteResult,scoredf)
```

--------------------------------

### Generate null distribution with generateNull

Source: https://github.com/davislaboratory/singscore/blob/master/man/generateNull.Rd

Ranks the toy expression data, scores it with simpleScore, then calls generateNull to produce a permutation result. The example checks registered BiocParallel backends and uses B=10, seed=1, and ncores=1.

```R
ranked <- rankGenes(toy_expr_se)
scoredf <- simpleScore(ranked, upSet = toy_gs_up, downSet = toy_gs_dn)

# find out what backends can be registered on your machine
BiocParallel::registered()
# the first one is the default backend
# ncores = ncores <- parallel::detectCores() - 2
permuteResult = generateNull(upSet = toy_gs_up, downSet = toy_gs_dn, ranked,
centerScore = TRUE, B =10, seed = 1, ncores = 1 )
```

--------------------------------

### Plot rank density for one sample using toy expression data

Source: https://github.com/davislaboratory/singscore/blob/master/man/plotRankDensity.Rd

Example from the documentation showing how to rank a toy expression dataset and plot the rank density for the second sample using an up-regulated gene set. The rankData argument is subset with drop = FALSE to preserve the data frame structure.

```R
ranked <- rankGenes(toy_expr_se)
plotRankDensity(ranked[,2,drop = FALSE], upSet = toy_gs_up)
```

--------------------------------

### Scoring a GeneSetCollection with multiScore

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/multiScore.md

Example from the documentation showing how to score a GeneSetCollection. Each gene set must be named first because the returned row names come from the collection names. The result contains 'Scores' and 'Dispersions' components.

```r
library(singscore)
library(GSEABase)

ranked <- rankGenes(toy_expr_se)

GSEABase::setName(toy_gs_up) <- "toy_gs_up"
GSEABase::setName(toy_gs_dn) <- "toy_gs_dn"
gslist <- list(toy_gs_up, toy_gs_dn)
gscolc <- GSEABase::GeneSetCollection(gslist)

scoredf <- multiScore(ranked, upSetColc = gscolc)
scoredf$Scores        # genesets x samples
scoredf$Dispersions
```

--------------------------------

### Get stable genes with getStableGenes

Source: https://github.com/davislaboratory/singscore/blob/master/vignettes/singscore.Rmd

Retrieves the top stable genes for a given context (carcinoma or blood) and optionally returns Ensembl IDs instead of gene symbols. The example requests the top 5 stable genes for each type and demonstrates the 'id' parameter.

```R
#get the top 5 stable genes in carcinomas
getStableGenes(5, type = 'carcinoma')

#get the top 5 stable genes in blood
getStableGenes(5, type = 'blood')

#get ensembl IDs instead of gene symbold
getStableGenes(5, type = 'carcinoma', id = 'ensembl')
```

--------------------------------

### Project samples with custom labels using projectScoreLandscape

Source: https://github.com/davislaboratory/singscore/blob/master/vignettes/singscore.Rmd

Projects CCLE samples onto the TCGA landscape with custom sample labels. The sampleLabels argument accepts a character vector of labels. The annot argument provides sample annotations for the projected points.

```R
projectScoreLandscape(plotObj = tcgaLandscape, scoredf_ccle_epi, scoredf_ccle_mes,
                      subSamples = rownames(scoredf_ccle_epi)[c(1,4,5,8,9)],
                      sampleLabels = c('l1','l2','l3','l4','l5'),
                      annot = rownames(scoredf_ccle_epi)[c(1,4,5,8,9)], 
                      isInteractive = FALSE)

```

--------------------------------

### Alternative input types: matrix, data.frame, ExpressionSet, DGEList

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/rankGenes.md

Shows that ranking is identical for matrix and data.frame inputs, and demonstrates usage with ExpressionSet and DGEList objects.

```r
emat <- SummarizedExperiment::assay(toy_expr_se)
ranked2 <- rankGenes(emat)                                  # matrix method
ranked3 <- rankGenes(as.data.frame(emat))                   # data.frame method
identical(ranked, ranked2)

# ExpressionSet and DGEList inputs
e <- Biobase::ExpressionSet(assayData = as.matrix(emat))
rankGenes(e)
d <- edgeR::DGEList(counts = as.matrix(emat))
rankGenes(d)
```

--------------------------------

### getPvals

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/getPvals.md

Documentation for the getPvals function in the singscore R package, including parameters, return value, errors, and examples.

```APIDOC
## getPvals(permuteResult, scoredf, subSamples = NULL)

### Description
Estimates one-tailed empirical p-values for the observed scores of each sample, given the permutation (null) distribution generated by `generateNull` and the observed scores from `simpleScore`. A minimum p-value of `1/B` can be achieved with `B` permutations.

### Function Signature
```r
getPvals <- function(permuteResult, scoredf, subSamples = NULL)
```

### Parameters
- **permuteResult** (matrix) - Required - Null distributions for each sample, generated by `generateNull()`; `B` rows x samples columns
- **scoredf** (data.frame) - Required - Observed scores generated by `simpleScore()` (the same samples as `permuteResult`)
- **subSamples** (vector of sample labels/indices) - Optional - Subset of samples; all samples when `NULL`

### Return
A named numeric vector of estimated p-values, one per sample (names are the row names of the subsetted `scoredf`). The estimation (`R/permuTest.R:144-146`):

```r
pvals <- colSums(permuteResult > matrix(1, nrow = nrow(permuteResult),
                                ncol = 1) %*% resultSc) / B
pvals <- sapply(pvals, max, 1/B)
```

i.e. the fraction of permuted scores exceeding the observed score (one-tailed), floored at `1/B`. A p-value equal to `1/B` therefore indicates that the estimated p-value is less than or equal to `1/B`.

### Errors
- **Condition**: `ncol(permuteResult) == nrow(scoredf)` is `FALSE` - number of samples in `permuteResult` does not match the number of rows of (the subsetted) `scoredf` — raised at `R/permuTest.R:136`

### Examples
Basic usage (from the vignette; note `subSamples` must select the same samples in both inputs):

```r
library(singscore)

ranked <- rankGenes(toy_expr_se)
scoredf <- simpleScore(ranked, upSet = toy_gs_up, downSet = toy_gs_dn)

permuteResult <- generateNull(
  upSet = toy_gs_up, downSet = toy_gs_dn, ranked,
  B = 10, seed = 1, useBPPARAM = BiocParallel::registered()[[1]]
)

pvals <- getPvals(permuteResult, scoredf, subSamples = 1:5)
pvals   # named numeric vector, one p-value per sample
```

Error handling — mismatched sample counts are rejected:

```r
# scoredf subset with only 1 row vs. a 5-sample permutation matrix
res <- tryCatch(
  getPvals(permuteResult, scoredf[1, , drop = FALSE]),
  error = function(e) e
)   # stopifnot(ncol(permuteResult) == nrow(scoredf)) fires
```

The p-values are then consumed by `plotNull`:

```r
plotNull(permuteResult, scoredf, pvals, sampleNames = names(pvals)[1])
```
```

--------------------------------

### Project CCLE samples with custom sample labels

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/projectScoreLandscape.md

Projects five CCLE samples with custom sample labels ('l1' through 'l5'). Labels are drawn with label-repel.

```r
projectScoreLandscape(plotObj = tcgaLandscape,
                      scoredf_ccle_epi, scoredf_ccle_mes,
                      subSamples = rownames(scoredf_ccle_epi)[c(1, 4, 5, 8, 9)],
                      sampleLabels = c('l1', 'l2', 'l3', 'l4', 'l5'),
                      annot = rownames(scoredf_ccle_epi)[c(1, 4, 5, 8, 9)],
                      isInteractive = FALSE)
```

--------------------------------

### Handle Invalid Input Errors

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/plotRankDensity.md

Example of catching an error when providing an invalid data type for the textSize parameter.

```r
res <- tryCatch(
  plotRankDensity(ranked[, 2, drop = FALSE], upSet = toy_gs_up, textSize = 'big'),
  error = function(e) e
)   # stopifnot(is.numeric(textSize)) fires in plotRankDensity_intl
```

--------------------------------

### projectScoreLandscape

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/README.md

Plain function. Projects samples onto a score landscape.

```APIDOC
## projectScoreLandscape

### Description
Plain function. Projects samples onto a score landscape.

### Usage
projectScoreLandscape(...)

### Details
See [projectScoreLandscape](projectScoreLandscape.md) for full documentation.

```

--------------------------------

### Generate Interactive Rank Density Plot

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/plotRankDensity.md

Example of generating an interactive plotly object by setting isInteractive to TRUE.

```r
plotRankDensity(ranked[, 2, drop = FALSE],
                upSet = toy_gs_up, downSet = toy_gs_dn,
                isInteractive = TRUE)
```

--------------------------------

### Basic usage with SummarizedExperiment

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/rankGenes.md

Ranks genes in a SummarizedExperiment object using the toy dataset shipped with the package. The result is a matrix of genes by samples.

```r
library(singscore)

ranked <- rankGenes(toy_expr_se, tiesMethod = 'min')
dim(ranked)                 # genes x samples
head(ranked[, 1, drop = FALSE])
```

--------------------------------

### Generate null distributions with generateNull()

Source: https://github.com/davislaboratory/singscore/blob/master/vignettes/singscore.Rmd

Runs the permutation test to generate null distributions for the first 5 samples. Requires the upSet, downSet, rankData, and other parameters matching those used in simpleScore(). The ncores parameter controls CPU usage; useBPPARAM allows custom parallel backends. The result is a matrix of permuted scores.

```R
# tgfb_gs_up : up regulated gene set in the tgfb gene signature
# tgfb_gs_dn : down regulated gene set in the tgfb gene signature

# This permutation function uses BiocParallel::bplapply() parallel function, by 
# supplying the first 5 columns of rankData, we generate Null distribution for 
# the first 5 samples.

# detect how many CPU cores are available for your machine
# parallel::detectCores()

ncores <- 1

# Provide the generateNull() function the number of cores you would like
# the function to use by passing the ncore parameter

permuteResult <-
  generateNull(
    upSet = tgfb_gs_up,
    downSet = tgfb_gs_dn,
    rankData = rankData,
    subSamples = 1:5,
    centerScore = TRUE,
    knownDirection = TRUE,
    B = 1000,
    ncores = ncores,
    seed = 1,
    useBPPARAM = NULL
  )
# Note here, the useBPPARAM parameter allows user to supply a BPPARAM variable 
# as a parameter which decides the type of parallel ends to use.
# such as 
# snow <-  BiocParallel::SnowParam(type = "SOCK")
# permuteResult <-  generateNull(upSet = tgfb_gs_up, downSet = tgfb_gs_dn,
# rankData[,1:5],  B = 1000, seed = 1,ncores = ncores, useBPPARAM = snow)

# If you are not sure about this, just leave the value as NULL and set how many
# CPU cores to use via the ncores argument. It will use the default parallel 
# backend for your machine.

# For more information, please see the help page for ?generateNull()
# Please also note that one should pass the same values to the upSet, 
# downSet, centerScore and knownDirection arguments as what they provide 
# for the simpleScore() function to generate a proper null distribution.

head(permuteResult)
```

--------------------------------

### plotDispersion

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/plotDispersion.md

Documentation for the plotDispersion function in the singscore R package, including usage, arguments, details, value, examples, and error handling.

```APIDOC
## plotDispersion

### Description
Plots the dispersion of scores from a `simpleScore` result, optionally annotated by sample groups. Supports customization of labels, point size, transparency, text size, and interactive mode.

### Usage
```r
plotDispersion(scoredf, annot = NULL, annot_name = NULL, sampleLabels = NULL, alpha = 1, size = 1, textSize = 1, isInteractive = FALSE)
```

### Arguments
- **scoredf** (data.frame) - Required - A data.frame produced by `simpleScore` containing sample scores.
- **annot** (character/factor vector or column name) - Optional - Annotation for each sample, either as a vector in sample order or a column name in `scoredf`.
- **annot_name** (character) - Optional - Name for the annotation variable (used when `annot` is a vector).
- **sampleLabels** (character vector) - Optional - Custom labels for each sample.
- **alpha** (numeric) - Optional - Transparency level for points (default 1).
- **size** (numeric) - Optional - Point size (default 1).
- **textSize** (numeric) - Optional - Text size for labels (default 1).
- **isInteractive** (logical) - Optional - If `TRUE`, returns an interactive plot (default `FALSE`).

### Details
- If `annot` is a vector, its length must match the number of samples in `scoredf`; otherwise an error is thrown.
- If `annot` is a column name, it must exist in `scoredf`.
- `textSize` must be numeric; otherwise an error is thrown.

### Value
A ggplot object (or plotly object if `isInteractive = TRUE`).

### Examples
```r
library(singscore)

ranked <- rankGenes(toy_expr_se)
scoredf <- simpleScore(ranked, upSet = toy_gs_up, downSet = toy_gs_dn)

# annotation via a character/factor vector, in sample order
annot <- c('Control', 'TGFb')
plotDispersion(scoredf, annot = annot, annot_name = 'Sample type')

# annotation stored as a column of the score data.frame
scoredf$Type <- c('Control', 'TGFb')
plotDispersion(scoredf, annot = 'Type')

# labels, alpha, and interactive mode
plotDispersion(scoredf,
               annot = c('Control', 'TGFb'),
               sampleLabels = c('ctrl-1', 'tgfb-1'),
               alpha = 0.7, size = 2, textSize = 1.5)

plotDispersion(scoredf, annot = c('Control', 'TGFb'), isInteractive = TRUE)
```

### Error Handling
- Mismatched annotation/label lengths are rejected with an error.
- Non-numeric `textSize` is rejected with an error.
```

--------------------------------

### Display R session information with sessionInfo()

Source: https://github.com/davislaboratory/singscore/blob/master/vignettes/singscore.Rmd

Use this snippet to print the R session details, including package versions and platform information. It is typically placed in a vignette or report to document the environment. The output is generated by the sessionInfo() function.

```R
```{r sessionInfo}
sessionInfo()
```
```

--------------------------------

### Project CCLE samples onto TCGA landscape with projectScoreLandscape()

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/projectScoreLandscape.md

Projects three CCLE samples onto a TCGA landscape created with plotScoreLandscape(). The samples are annotated and unlabelled (sampleLabels = NULL) and the plot is non-interactive.

```r
library(singscore)

tcgaLandscape <- plotScoreLandscape(scoredf_tcga_epi, scoredf_tcga_mes,
                                    scorenames = c('tcga_EPI', 'tcga_MES'))

# project 3 CCLE samples, annotated and unlabelled
projectScoreLandscape(plotObj = tcgaLandscape,
                      scoredf_ccle_epi, scoredf_ccle_mes,
                      subSamples = rownames(scoredf_ccle_epi)[c(1, 4, 5)],
                      annot = rownames(scoredf_ccle_epi)[c(1, 4, 5)],
                      sampleLabels = NULL,
                      isInteractive = FALSE)
```

--------------------------------

### Error handling and empty gene-set case

Source: https://github.com/davislaboratory/singscore/blob/master/_autodocs/api-reference/simpleScore.md

Examples showing error handling for invalid knownDirection, empty results when gene sets have no overlap, and warnings for unmeasured genes.

```r
# invalid knownDirection raises an error
res <- tryCatch(
  simpleScore(rankData, upSet = toy_gs_up, knownDirection = 'yes'),
  error = function(e) e
)
# 'knownDirection' must be logical — the stopifnot() validation fires

# gene sets with no overlap with the data return an empty (0-row) data.frame
scoredf_empty <- simpleScore(rankData, upSet = c('not_measured_1', 'not_measured_2'))
nrow(scoredf_empty)   # 0

# genes not measured in the dataset are dropped with a warning
scoredf_warn <- simpleScore(rankData,
                            upSet = c('geneA', 'geneB', 'unmeasured_gene'),
                            downSet = toy_gs_dn)
```