Generate a PCA from a qseaSet

Source: R/PCA.R

Convenience wrapper around getDimRed() with method = "PCA".

Convenience wrapper around getDimRed() with method = "UMAP".

Run PCA or UMAP on methylation signal matrices extracted from a qsea::qseaSet. This is the core workhorse for dimensionality reduction; wrappers such as getPCA() and getUMAP() provide simplified access.

getPCA(
  qseaSet,
  dataTable = NULL,
  regionsToOverlap = NULL,
  normMethod = "beta",
  minEnrichment = 3,
  useGroupMeans = FALSE,
  minDensity = 0,
  topVarNum = 1000,
  topVarSamples = NULL,
  center = TRUE,
  scale = FALSE,
  nPC = 5,
  returnDataTable = FALSE,
  verbose = TRUE
)

getUMAP(
  qseaSet,
  dataTable = NULL,
  regionsToOverlap = NULL,
  normMethod = "beta",
  minEnrichment = 3,
  useGroupMeans = FALSE,
  minDensity = 0,
  topVarNum = 1000,
  topVarSamples = NULL,
  returnDataTable = FALSE,
  verbose = TRUE,
  ...
)

getDimRed(
  qseaSet,
  dataTable = NULL,
  method = "PCA",
  regionsToOverlap = NULL,
  normMethod = "beta",
  minEnrichment = 3,
  useGroupMeans = FALSE,
  minDensity = 0,
  topVarNum = 1000,
  topVarSamples = NULL,
  center = TRUE,
  scale = FALSE,
  nPC = 5,
  returnDataTable = FALSE,
  verbose = TRUE,
  ...
)

Arguments

qseaSet

qseaSet. Input object providing windows, counts and sampleTable.

dataTable

data.frame or GRanges or NULL. Normalised values with windows in rows and samples in columns. Must contain seqnames, start, end (if data.frame), or metadata columns with values (if GRanges). If NULL, the matrix is derived internally (see normMethod, minEnrichment). Default: NULL.

regionsToOverlap

GRanges, coercible data.frame, or NULL. If supplied, only windows overlapping these regions are used. Default: NULL.

normMethod

character(1). Name of predefined normalisation (e.g., "beta", "nrpm"); passed to qsea::normMethod() when dataTable = NULL. Default: "beta".

minEnrichment

numeric(1). Minimum reads required for beta values to be non-NA; forwarded to getDataTable() when building data internally. Default: 3.

useGroupMeans

logical(1). If TRUE, average samples within the group column (combine replicates) before dimensionality reduction. Default: FALSE.

minDensity

numeric(1). Minimum CpG density; windows below this are removed. Default: 0.

topVarNum

numeric(1) or integer(1) or Inf or NULL or a vector. Keep the topVarNum most variable windows (by SD). If NA, NULL, Inf, or >= available windows, use all. If a vector, dimensionality reduction is run once per value and results are returned in a list. Default: 1000.

topVarSamples

NULL, character(), list, or regex string. Samples used to compute variability. If NULL/NA, use all samples. If a vector/regex, select matching samples. If a list, perform dimensionality reduction per list element (should match length(topVarNum) when vectorised). Default: NULL.

center

logical(1). Centre features to mean zero (PCA only). Default: TRUE.

scale

logical(1). Scale features to unit variance (PCA only). Default: FALSE.

nPC

integer(1). Number of principal components to compute (PCA only). Default: 5.

returnDataTable

logical(1). If TRUE, include the matrix used for the dimensionality reduction in the return object. Default: FALSE.

verbose

logical(1). If TRUE, print messages regarding the function execution. Default: TRUE.

...

Additional arguments passed to uwot::umap() (when method="UMAP"), e.g. n_neighbors, min_dist, metric.

method

character(1). One of "PCA" or "UMAP". Default: "PCA".

Value

A mesaDimRed object with:

  • res: Named list of dimensionality reduction results; each element is a mesaPCA (for PCA) or mesaUMAP (for UMAP). Names correspond to entries in params$topVar. The sample IDs are the row names of each result (sample group names when useGroupMeans = TRUE).

  • dataTable (optional): The numeric matrix used for dimensionality reduction when returnDataTable = TRUE. It reflects filtering by regionsToOverlap and minDensity, removal of rows with missing values, and may include columns of window SDs when applicable (named per params$topVar).

  • params: List of parameters used (method, selection/filter settings, etc.).

  • sampleTable: Copy of qsea::getSampleTable(qseaSet).

Details

:

  • For method = "PCA", dimensionality reduction is performed via stats::prcomp() with center and scale controls.

  • For method = "UMAP", dimensionality reduction is performed via uwot::umap().

  • Prior to dimensionality reduction, optional filtering is applied: enrichment cut-off (minEnrichment), CpG density (minDensity), region restriction (regionsToOverlap), and most-variable windows (topVarNum).

  • When topVarNum or topVarSamples are vectorised/lists, multiple runs are performed and collected in res.

Functions

  • getPCA(): Principal component analysis of a qseaSet.

  • getUMAP(): Uniform manifold approximation and projection of a qseaSet.

See also

getPCA(), getUMAP(), mesaDimRed, mesaPCA, mesaUMAP, qsea::normMethod(), uwot::umap(), stats::prcomp()

Other dimred-helpers: plotDimRed(), plotUMAP()

Examples

data(exampleTumourNormal, package = "mesa")

# Default PCA (beta-normalised, top 1000 most variable windows, 5 PCs)
exampleTumourNormal %>%
    getPCA()
#> ------------------------------
#> Initial number of windows = 819.
#> -----------
#> Generating table of beta values for 819 regions across 10 samples.
#> -----------
#> Filtered out 220 windows with at least one missing value: 599 windows remaining.
#> ------------------------------
#> The following topVarNum values are larger than the number of remaining windows (= 599): 1000
#> These values are not used; PCA will be done with all remaining windows instead.
#> ------------------------------
#> No filtering of windows based on window standard deviation.
#> Performing PCA with 10 samples and 599 windows
#> -> pca1.
#> ------------------------------
#> Object containing 1 dimensionality reduction objects for 10 samples

# Request only the top 3 PCs
exampleTumourNormal %>%
    getPCA(nPC = 3)
#> ------------------------------
#> Initial number of windows = 819.
#> -----------
#> Generating table of beta values for 819 regions across 10 samples.
#> -----------
#> Filtered out 220 windows with at least one missing value: 599 windows remaining.
#> ------------------------------
#> The following topVarNum values are larger than the number of remaining windows (= 599): 1000
#> These values are not used; PCA will be done with all remaining windows instead.
#> ------------------------------
#> No filtering of windows based on window standard deviation.
#> Performing PCA with 10 samples and 599 windows
#> -> pca1.
#> ------------------------------
#> Object containing 1 dimensionality reduction objects for 10 samples

# Use multiple cutoffs for most-variable windows
# (returns list of PCA results)
exampleTumourNormal %>%
    getPCA(topVarNum = c(10, 100, 500, NA)) %>%
    slot("res") %>%
    names()
#> ------------------------------
#> Initial number of windows = 819.
#> -----------
#> Generating table of beta values for 819 regions across 10 samples.
#> -----------
#> Filtered out 220 windows with at least one missing value: 599 windows remaining.
#> ------------------------------
#> Calculating standard deviation for each window across all 10 samples:
#> Colon1_N, Colon1_T, Colon2_N, Colon2_T, Lung1_N, Lung1_T, Lung2_N, Lung2_T, Lung3_N, Lung3_T.
#> -> column name windowSd1.
#> ------------------------------
#> Filtering windows based on standard deviation
#> across all 10 samples (windowSd1).
#> Standard deviation threshold = 0.308 resulting in 10 windows.
#> Performing PCA with 10 samples and 10 windows
#> -> pca1.
#> ------------------------------
#> Filtering windows based on standard deviation
#> across all 10 samples (windowSd1).
#> Standard deviation threshold = 0.19 resulting in 100 windows.
#> Performing PCA with 10 samples and 100 windows
#> -> pca2.
#> ------------------------------
#> Filtering windows based on standard deviation
#> across all 10 samples (windowSd1).
#> Standard deviation threshold = 0.0485 resulting in 500 windows.
#> Performing PCA with 10 samples and 500 windows
#> -> pca3.
#> ------------------------------
#> No filtering of windows based on window standard deviation.
#> Performing PCA with 10 samples and 599 windows
#> -> pca4.
#> ------------------------------
#> [1] "pca1" "pca2" "pca3" "pca4"
# Default UMAP
exampleTumourNormal %>%
    getUMAP(n_neighbors = 5)
#> ------------------------------
#> Initial number of windows = 819.
#> -----------
#> Generating table of beta values for 819 regions across 10 samples.
#> -----------
#> Filtered out 220 windows with at least one missing value: 599 windows remaining.
#> ------------------------------
#> The following topVarNum values are larger than the number of remaining windows (= 599): 1000
#> These values are not used; UMAP will be done with all remaining windows instead.
#> ------------------------------
#> No filtering of windows based on window standard deviation.
#> Performing UMAP with 10 samples and 599 windows
#> -> umap1.
#> ------------------------------
#> Object containing 1 dimensionality reduction objects for 10 samples

# Alter UMAP hyperparameters
exampleTumourNormal %>%
    getUMAP(n_neighbors = 5, min_dist = 1)
#> ------------------------------
#> Initial number of windows = 819.
#> -----------
#> Generating table of beta values for 819 regions across 10 samples.
#> -----------
#> Filtered out 220 windows with at least one missing value: 599 windows remaining.
#> ------------------------------
#> The following topVarNum values are larger than the number of remaining windows (= 599): 1000
#> These values are not used; UMAP will be done with all remaining windows instead.
#> ------------------------------
#> No filtering of windows based on window standard deviation.
#> Performing UMAP with 10 samples and 599 windows
#> -> umap1.
#> ------------------------------
#> Object containing 1 dimensionality reduction objects for 10 samples

# Use top 500 most variable windows only
exampleTumourNormal %>%
    getUMAP(n_neighbors = 5, topVarNum = 500)
#> ------------------------------
#> Initial number of windows = 819.
#> -----------
#> Generating table of beta values for 819 regions across 10 samples.
#> -----------
#> Filtered out 220 windows with at least one missing value: 599 windows remaining.
#> ------------------------------
#> Calculating standard deviation for each window across all 10 samples:
#> Colon1_N, Colon1_T, Colon2_N, Colon2_T, Lung1_N, Lung1_T, Lung2_N, Lung2_T, Lung3_N, Lung3_T.
#> -> column name windowSd1.
#> ------------------------------
#> Filtering windows based on standard deviation
#> across all 10 samples (windowSd1).
#> Standard deviation threshold = 0.0485 resulting in 500 windows.
#> Performing UMAP with 10 samples and 500 windows
#> -> umap1.
#> ------------------------------
#> Object containing 1 dimensionality reduction objects for 10 samples
data(exampleTumourNormal, package = "mesa")

# PCA on default beta-normalised matrix, keep 3 PCs
exampleTumourNormal %>%
    getDimRed(method = "PCA", nPC = 3)
#> ------------------------------
#> Initial number of windows = 819.
#> -----------
#> Generating table of beta values for 819 regions across 10 samples.
#> -----------
#> Filtered out 220 windows with at least one missing value: 599 windows remaining.
#> ------------------------------
#> The following topVarNum values are larger than the number of remaining windows (= 599): 1000
#> These values are not used; PCA will be done with all remaining windows instead.
#> ------------------------------
#> No filtering of windows based on window standard deviation.
#> Performing PCA with 10 samples and 599 windows
#> -> pca1.
#> ------------------------------
#> Object containing 1 dimensionality reduction objects for 10 samples

# UMAP on the top 500 most variable windows
exampleTumourNormal %>%
    getDimRed(method = "UMAP", topVarNum = 500, n_neighbors = 5)
#> ------------------------------
#> Initial number of windows = 819.
#> -----------
#> Generating table of beta values for 819 regions across 10 samples.
#> -----------
#> Filtered out 220 windows with at least one missing value: 599 windows remaining.
#> ------------------------------
#> Calculating standard deviation for each window across all 10 samples:
#> Colon1_N, Colon1_T, Colon2_N, Colon2_T, Lung1_N, Lung1_T, Lung2_N, Lung2_T, Lung3_N, Lung3_T.
#> -> column name windowSd1.
#> ------------------------------
#> Filtering windows based on standard deviation
#> across all 10 samples (windowSd1).
#> Standard deviation threshold = 0.0485 resulting in 500 windows.
#> Performing UMAP with 10 samples and 500 windows
#> -> umap1.
#> ------------------------------
#> Object containing 1 dimensionality reduction objects for 10 samples

# Restrict dimensionality reduction to a set of regions (from a data.frame)
regs <- data.frame(seqnames = "chr7", start = 25002001, end = 25027900)
exampleTumourNormal %>%
    getDimRed(method = "PCA", regionsToOverlap = regs)
#> ------------------------------
#> Initial number of windows = 819.
#> Filtered out 807 windows using regionsToOverlap: 12 windows remaining.
#> -----------
#> Generating table of beta values for 12 regions across 10 samples.
#> -----------
#> Filtered out 4 windows with at least one missing value: 8 windows remaining.
#> ------------------------------
#> The following topVarNum values are larger than the number of remaining windows (= 8): 1000
#> These values are not used; PCA will be done with all remaining windows instead.
#> ------------------------------
#> No filtering of windows based on window standard deviation.
#> Performing PCA with 10 samples and 8 windows
#> -> pca1.
#> ------------------------------
#> Object containing 1 dimensionality reduction objects for 10 samples

# Vectorised topVarNum runs (returns a list of results)
exampleTumourNormal %>%
    getDimRed(method = "UMAP", topVarNum = c(500, 2000), n_neighbors = 5) %>%
    slot("res") %>%
    names()
#> ------------------------------
#> Initial number of windows = 819.
#> -----------
#> Generating table of beta values for 819 regions across 10 samples.
#> -----------
#> Filtered out 220 windows with at least one missing value: 599 windows remaining.
#> ------------------------------
#> The following topVarNum values are larger than the number of remaining windows (= 599): 2000
#> These values are not used; UMAP will be done with all remaining windows instead.
#> Calculating standard deviation for each window across all 10 samples:
#> Colon1_N, Colon1_T, Colon2_N, Colon2_T, Lung1_N, Lung1_T, Lung2_N, Lung2_T, Lung3_N, Lung3_T.
#> -> column name windowSd1.
#> ------------------------------
#> Filtering windows based on standard deviation
#> across all 10 samples (windowSd1).
#> Standard deviation threshold = 0.0485 resulting in 500 windows.
#> Performing UMAP with 10 samples and 500 windows
#> -> umap1.
#> ------------------------------
#> No filtering of windows based on window standard deviation.
#> Performing UMAP with 10 samples and 599 windows
#> -> umap2.
#> ------------------------------
#> [1] "umap1" "umap2"