Permute sample labels to simulate null distribution of perturbation scores

Source: R/normalise_by_permutation.R

Simulate null distributions of perturbation scores for each pathway through sample permutation.

generate_permuted_scores(
  expreMatrix,
  numOfTreat,
  NB = 1000,
  gsTopology,
  weight,
  BPPARAM = BiocParallel::bpparam()
)

# S4 method for matrix
generate_permuted_scores(
  expreMatrix,
  numOfTreat,
  NB = 1000,
  gsTopology,
  weight,
  BPPARAM = BiocParallel::bpparam()
)

# S4 method for data.frame
generate_permuted_scores(
  expreMatrix,
  numOfTreat,
  NB = 1000,
  gsTopology,
  weight,
  BPPARAM = BiocParallel::bpparam()
)

# S4 method for DGEList
generate_permuted_scores(
  expreMatrix,
  numOfTreat,
  NB = 1000,
  gsTopology,
  weight,
  BPPARAM = BiocParallel::bpparam()
)

# S4 method for SummarizedExperiment
generate_permuted_scores(
  expreMatrix,
  numOfTreat,
  NB = 1000,
  gsTopology,
  weight,
  BPPARAM = BiocParallel::bpparam()
)

Arguments

expreMatrix

matrix and data.frame of logCPM, or DGEList/SummarizedExperiment storing gene expression counts. Feature names need to be gene entrez IDs

numOfTreat

Number of treatments (including control)

NB

Number of permutations

gsTopology

List of pathway topology matrices generated using function retrieve_topology

weight

A vector of gene-wise weights derived from function weight_ss_fc

BPPARAM

The parallel back-end to uses, if not specified, it is defaulted to the one returned by BiocParallel::bpparam().

Value

A list where each element is a vector of perturbation scores for a pathway.

Details

This generate_permuted_scores function is a generic function that can deal with multiple types of inputs. It firstly randomly permute sample labels NB times to generate permuted logFCs, which are then used to compute permuted perturbation scores for each pathway. The function outputs a list that is of the same length as the list storing pathway topology matrices. Each element of the output list is for a pathway and contains a vector of permuted perturbation score of length NB. It's assumed that the permuted perturbation scores can be used to estimate the null distributions of perturbation scores.

If the input is S4 object of DGEList or SummarizedExperiment, gene expression matrix will be extracted and converted to logCPM matrix.

The default number of permutation (NB) is set to 1000. If the requested NB is larger than the maximum number of permutations possible, NB will be set to the largest number of permutations possible instead.

Examples

#compute weighted single sample logFCs
data(metadata_example)
data(logCPM_example)
ls <- weight_ss_fc(logCPM_example, metadata = metadata_example,
 factor = "patient", control = "Vehicle")
# \donttest{
load(system.file("extdata", "gsTopology.rda", package = "sSNAPPY"))
#> Warning: cannot open compressed file '', probable reason 'No such file or directory'
#> Error in readChar(con, 5L, useBytes = TRUE): cannot open the connection
permutedScore <- generate_permuted_scores(logCPM_example, numOfTreat = 3,
 NB = 10, gsTopology = gsTopology, weight = ls$weight)
#> Error in lapply(gsTopology, rownames): object 'gsTopology' not found

# To see what other parallel back-end can be used:
 BiocParallel::registered()
#> $MulticoreParam
#> class: MulticoreParam
#>   bpisup: FALSE; bpnworkers: 8; bptasks: 0; bpjobname: BPJOB
#>   bplog: FALSE; bpthreshold: INFO; bpstopOnError: TRUE
#>   bpRNGseed: ; bptimeout: 2592000; bpprogressbar: FALSE
#>   bpexportglobals: TRUE; bpforceGC: TRUE
#>   bplogdir: NA
#>   bpresultdir: NA
#>   cluster type: FORK
#> 
#> $SnowParam
#> class: SnowParam
#>   bpisup: FALSE; bpnworkers: 8; bptasks: 0; bpjobname: BPJOB
#>   bplog: FALSE; bpthreshold: INFO; bpstopOnError: TRUE
#>   bpRNGseed: ; bptimeout: 2592000; bpprogressbar: FALSE
#>   bpexportglobals: TRUE; bpforceGC: FALSE
#>   bplogdir: NA
#>   bpresultdir: NA
#>   cluster type: SOCK
#> 
#> $SerialParam
#> class: SerialParam
#>   bpisup: FALSE; bpnworkers: 1; bptasks: 0; bpjobname: BPJOB
#>   bplog: FALSE; bpthreshold: INFO; bpstopOnError: TRUE
#>   bpRNGseed: ; bptimeout: 2592000; bpprogressbar: FALSE
#>   bpexportglobals: TRUE; bpforceGC: FALSE
#>   bplogdir: NA
#>   bpresultdir: NA
#> 
 # }