xPierGRs | R Documentation

## Function to prioritise genes given a list of genomic regions

### Description

`xPierGRs` is supposed to prioritise genes given a list of genomic regions with or without the significance level. To prioritise genes, it first defines and scores genes crosslinking to an input list of genomic regions (GR). With seed genes and their scores, it then uses Random Walk with Restart (RWR) to calculate the affinity score of all nodes in the input graph to the seed genes. The priority score is the affinity score. Parallel computing is also supported for Linux-like or Windows operating systems. It returns an object of class "pNode".

### Usage

    xPierGRs(data, significance.threshold = NULL, score.cap = NULL,
    build.conversion = c(NA, "hg38.to.hg19", "hg18.to.hg19"),
    crosslink = c("genehancer", "PCHiC_combined", "GTEx_V6p_combined",
    "nearby"), crosslink.customised = NULL, cdf.function = c("original",
    "empirical"), scoring.scheme = c("max", "sum", "sequential"),
    nearby.distance.max = 50000, nearby.decay.kernel = c("rapid", "slow",
    "linear", "constant"), nearby.decay.exponent = 2,
    network = c("STRING_highest", "STRING_high", "STRING_medium",
    "STRING_low", "PCommonsUN_high", "PCommonsUN_medium",
    "PCommonsDN_high",
    "PCommonsDN_medium", "PCommonsDN_Reactome", "PCommonsDN_KEGG",
    "PCommonsDN_HumanCyc", "PCommonsDN_PID", "PCommonsDN_PANTHER",
    "PCommonsDN_ReconX", "PCommonsDN_TRANSFAC", "PCommonsDN_PhosphoSite",
    "PCommonsDN_CTD", "KEGG", "KEGG_metabolism", "KEGG_genetic",
    "KEGG_environmental", "KEGG_cellular", "KEGG_organismal",
    "KEGG_disease",
    "REACTOME"), STRING.only = c(NA, "neighborhood_score", "fusion_score",
    "cooccurence_score", "coexpression_score", "experimental_score",
    "database_score", "textmining_score")[1], weighted = FALSE,
    network.customised = NULL, seeds.inclusive = TRUE,
    normalise = c("laplacian", "row", "column", "none"), restart = 0.7,
    normalise.affinity.matrix = c("none", "quantile"), parallel = TRUE,
    multicores = NULL, verbose = TRUE,
    RData.location = "http://galahad.well.ox.ac.uk/bigdata")

### Arguments

`data` | a named input vector containing the significance level for genomic regions (GR). For this named vector, the element names are GR, in the format of 'chrN:start-end', where N is either 1-22 or X, start (or end) is genomic positional number; for example, 'chr1:13-20', the element values for the significance level (measured as p-value or fdr). Alternatively, it can be a matrix or data frame with two columns: 1st column for GR, 2nd column for the significance level. Also supported is the input with GR only (without the significance level)
`significance.threshold` | the given significance threshold. By default, it is set to NULL, meaning there is no constraint on the significance level when transforming the significance level of GR into scores. If given, those GR below this are considered significant and thus scored positively. Instead, those above this are considered insignificant and thus receive no score
`score.cap` | the maximum score being capped. By default, it is set to NULL, meaning that no capping is applied
`build.conversion` | the conversion from one genome build to another. The conversions supported are "hg38.to.hg19" and "hg18.to.hg19". By default it is NA (no need to do so)
`crosslink` | the built-in crosslink info with a score quantifying the link of a GR to a gene. See `xGR2xGenes` for details
`crosslink.customised` | the crosslink info with a score quantifying the link of a GR to a gene. A user-input matrix or data frame with 4 columns: 1st column for genomic regions (formatted as "chr:start-end", genome build 19), 2nd column for Genes, 3rd for crosslink score (crosslinking a genomic region to a gene, such as -log10 significance level), and 4th for contexts (optional; if nor provided, it will be added as 'C'). Alternatively, it can be a file containing these 4 columns. Required, otherwise it will return NULL
`cdf.function` | a character specifying how to transform the input crosslink score. It can be one of 'original' (no such transformation), and 'empirical' for looking at empirical Cumulative Distribution Function (cdf; as such it is converted into pvalue-like values [0,1])
`scoring.scheme` | the method used to calculate seed gene scores under a set of GR (also over Contexts if many). It can be one of "sum" for adding up, "max" for the maximum, and "sequential" for the sequential weighting. The sequential weighting is done via: ∑_{i=1}{\frac{R_{i}}{i}}, where R_{i} is the i^{th} rank (in a descreasing order)
`nearby.distance.max` | the maximum distance between genes and GR. Only those genes no far way from this distance will be considered as seed genes. This parameter will influence the distance-component weights calculated for nearby GR per gene
`nearby.decay.kernel` | a character specifying a decay kernel function. It can be one of 'slow' for slow decay, 'linear' for linear decay, and 'rapid' for rapid decay. If no distance weight is used, please select 'constant'
`nearby.decay.exponent` | a numeric specifying a decay exponent. By default, it sets to 2
`network` | the built-in network. Currently two sources of network information are supported: the STRING database (version 10) and the Pathway Commons database (version 7). STRING is a meta-integration of undirect interactions from the functional aspect, while Pathways Commons mainly contains both undirect and direct interactions from the physical/pathway aspect. Both have scores to control the confidence of interactions. Therefore, the user can choose the different quality of the interactions. In STRING, "STRING_highest" indicates interactions with highest confidence (confidence scores>=900), "STRING_high" for interactions with high confidence (confidence scores>=700), "STRING_medium" for interactions with medium confidence (confidence scores>=400), and "STRING_low" for interactions with low confidence (confidence scores>=150). For undirect/physical interactions from Pathways Commons, "PCommonsUN_high" indicates undirect interactions with high confidence (supported with the PubMed references plus at least 2 different sources), "PCommonsUN_medium" for undirect interactions with medium confidence (supported with the PubMed references). For direct (pathway-merged) interactions from Pathways Commons, "PCommonsDN_high" indicates direct interactions with high confidence (supported with the PubMed references plus at least 2 different sources), and "PCommonsUN_medium" for direct interactions with medium confidence (supported with the PubMed references). In addition to pooled version of pathways from all data sources, the user can also choose the pathway-merged network from individual sources, that is, "PCommonsDN_Reactome" for those from Reactome, "PCommonsDN_KEGG" for those from KEGG, "PCommonsDN_HumanCyc" for those from HumanCyc, "PCommonsDN_PID" for those froom PID, "PCommonsDN_PANTHER" for those from PANTHER, "PCommonsDN_ReconX" for those from ReconX, "PCommonsDN_TRANSFAC" for those from TRANSFAC, "PCommonsDN_PhosphoSite" for those from PhosphoSite, and "PCommonsDN_CTD" for those from CTD. For direct (pathway-merged) interactions sourced from KEGG, it can be 'KEGG' for all, 'KEGG_metabolism' for pathways grouped into 'Metabolism', 'KEGG_genetic' for 'Genetic Information Processing' pathways, 'KEGG_environmental' for 'Environmental Information Processing' pathways, 'KEGG_cellular' for 'Cellular Processes' pathways, 'KEGG_organismal' for 'Organismal Systems' pathways, and 'KEGG_disease' for 'Human Diseases' pathways. 'REACTOME' for protein-protein interactions derived from Reactome pathways
`STRING.only` | the further restriction of STRING by interaction type. If NA, no such restriction. Otherwide, it can be one or more of "neighborhood_score","fusion_score","cooccurence_score","coexpression_score","experimental_score","database_score","textmining_score". Useful options are c("experimental_score","database_score"): only experimental data (extracted from BIND, DIP, GRID, HPRD, IntAct, MINT, and PID) and curated data (extracted from Biocarta, BioCyc, GO, KEGG, and Reactome) are used
`weighted` | logical to indicate whether edge weights should be considered. By default, it sets to false. If true, it only works for the network from the STRING database
`network.customised` | an object of class "igraph". By default, it is NULL. It is designed to allow the user analysing their customised network data that are not listed in the above argument 'network'. This customisation (if provided) has the high priority over built-in network. If the user provides the "igraph" object with the "weight" edge attribute, RWR will assume to walk on the weighted network
`seeds.inclusive` | logical to indicate whether non-network seed genes are included for prioritisation. If TRUE (by default), these genes will be added to the netowrk
`normalise` | the way to normalise the adjacency matrix of the input graph. It can be 'laplacian' for laplacian normalisation, 'row' for row-wise normalisation, 'column' for column-wise normalisation, or 'none'
`restart` | the restart probability used for Random Walk with Restart (RWR). The restart probability takes the value from 0 to 1, controlling the range from the starting nodes/seeds that the walker will explore. The higher the value, the more likely the walker is to visit the nodes centered on the starting nodes. At the extreme when the restart probability is zero, the walker moves freely to the neighbors at each step without restarting from seeds, i.e., following a random walk (RW)
`normalise.affinity.matrix` | the way to normalise the output affinity matrix. It can be 'none' for no normalisation, 'quantile' for quantile normalisation to ensure that columns (if multiple) of the output affinity matrix have the same quantiles
`parallel` | logical to indicate whether parallel computation with multicores is used. By default, it sets to true, but not necessarily does so. Partly because parallel backends available will be system-specific (now only Linux or Mac OS). Also, it will depend on whether these two packages "foreach" and "doMC" have been installed
`multicores` | an integer to specify how many cores will be registered as the multicore parallel backend to the 'foreach' package. If NULL, it will use a half of cores available in a user's computer. This option only works when parallel computation is enabled
`verbose` | logical to indicate whether the messages will be displayed in the screen. By default, it sets to true for display
`RData.location` | the characters to tell the location of built-in RData files. See `xRDataLoader` for details

### Value

an object of class "pNode", a list with following components:

- `priority`: a matrix of nNode X 6 containing node priority information, where nNode is the number of nodes in the input graph, and the 6 columns are "name" (node names), "node" (1 for network genes, 0 for non-network seed genes), "seed" (1 for seeds, 0 for non-seeds), "weight" (weight values), "priority" (the priority scores that are rescaled to the range [0,1]), "rank" (ranks of the priority scores), "description" (node description)

- `g`: an input "igraph" object

- `mSeed`: a list with following components 'GR', 'Gene' and 'Link'

### See Also

`xPierGenes`

### Examples

    ## Not run:
    # Load the library
    library(Pi)

    ## End(Not run)

    RData.location <- "http://galahad.well.ox.ac.uk/bigdata"

    ## Not run:
    # a) provide the seed SNPs with the significance info
    data(ImmunoBase)
    ## only AS GWAS SNPs and their significance info (p-values)
    df <- as.data.frame(ImmunoBase$AS$variant, row.names=NULL)
    GR <- paste0(df$seqnames,':',df$start,'-',df$end)
    data <- cbind(GR=GR, Sig=df$Pvalue)

    # b) perform priority analysis
    pNode <- xPierGRs(data=data, crosslink="PCHiC_combined",
    network="STRING_highest", restart=0.7, RData.location=RData.location)

    # c) save to the file called 'GRs_priority.txt'
    write.table(pNode$priority, file="GRs_priority.txt", sep="\t",
    row.names=FALSE)

    # d) manhattan plot
    mp <- xPierManhattan(pNode, top=20, top.label.size=1.5, y.scale="sqrt",
    RData.location=RData.location)
    #pdf(file="Gene_manhattan.pdf", height=6, width=12, compress=TRUE)
    print(mp)
    #dev.off()

    ## End(Not run)