Extract connections or links from a GRN object as a data frame.

Returns stored connections/links (either TF-peak, peak-genes, TF-genes or the filtered set of connections as produced by filterGRNAndConnectGenes). Additional meta columns (TF, peak and gene metadata) can be added optionally. Note: This function, as all get functions from this package, does NOT return a GRN object.

getGRNConnections(
  GRN,
  type = "all.filtered",
  background = FALSE,
  include_TF_gene_correlations = FALSE,
  include_TFMetadata = FALSE,
  include_peakMetadata = FALSE,
  include_geneMetadata = FALSE,
  include_variancePartitionResults = FALSE
)

Arguments

GRN

Object of class GRN

type

Character. One of TF_peaks, peak_genes, TF_genes or all.filtered. Default all.filtered. The type of connections to retrieve.

background

Integer (0 or 1). Default 0. Either 0 or 1). Here, 0 refers to the real (foreground) while 1 to the background.

include_TF_gene_correlations

Logical. TRUE or FALSE. Default FALSE. Should TFs and gene correlations be returned as well? If set to TRUE, they must have been computed beforehand with add_TF_gene_correlation.

include_TFMetadata

Logical. TRUE or FALSE. Default FALSE. Should TF metadata be returned as well?

include_peakMetadata

Logical. TRUE or FALSE. Default FALSE. Should peak metadata be returned as well?

include_geneMetadata

Logical. TRUE or FALSE. Default FALSE. Should gene metadata be returned as well?

include_variancePartitionResults

Logical. TRUE or FALSE. Default FALSE. Should the results from the function add_featureVariation be included? If set to TRUE, they must have been computed beforehand with add_featureVariation; otherwise, an error is thrown.

Value

A data frame with the requested connections. This function does **NOT** return a GRN object. Depending on the arguments, the data frame that is returned has different columns, which however can be divided into the following classes according to their name:

  • TF-related: Starting with TF.:

    • TF.name and TF.ID: Name / ID of the TF

    • TF.ENSEMBL: Ensembl ID (unique)

  • peak-related: Starting with peak.:

    • peak.ID: ID (coordinates)

    • peak.mean, peak.median, peak.CV: peak mean, median and its coefficient of variation (CV) across all samples

    • peak.annotation: Peak annotation as determined by ChIPseeker such as Promoter, 5’ UTR, 3’ UTR, Exon, Intron, Downstream, Intergenic

    • peak.nearestGene*: Additional metadata for the nearest gene such as position (chr, start, end, strand), name (name, symbol and ENSEMBL), and distance to the TSS (distanceToTSS)

    • peak.GC.perc: GC percentage

  • gene-related: Starting with gene.:

    • gene.name and gene.ENSEMBL: gene name and Ensembl ID

    • gene.type: gene type (such as protein_coding, lincRNA) as retrieved by biomaRt

    • gene.mean, gene.median, gene.CV: gene mean, median and its coefficient of variation (CV) across all samples

  • TF-peak-related: Starting with TF_peak.:

    • TF_peak.r and TF_peak.r_bin: Correlation coefficient of the TF-peak pair and its correlation bin (in bins of width 0.05, such as (-0.55,-0.5] for r = -0.53)

    • TF_peak.fdr and TF_peak.fdr_direction: TF-peak FDR and the directionality from which it was derived (see Methods in the paper, pos or neg)

    • TF_peak.connectionType: TF-peak connection type. This is by default expression, meaning that expression was used to construct the TF and peak

  • peak-gene-related: Starting with peak_gene.:

    • peak_gene.distance: Peak-gene distance (usually taken the TSS of the gene as reference unless specified otherwise, see the parameter overlapTypeGene for more information from addConnections_peak_gene)

    • peak_gene.r: Correlation coefficient of the peak-gene pair

    • peak_gene.p_raw and peak_gene.p_adj: Raw and adjusted p-value of the peak-gene pair

  • TF-gene-related: Starting with TF_gene.:

    • TF_gene.r: Correlation coefficient of the TF-gene pair

    • TF_gene.p_raw: Raw p-value of the TF-gene pair

Examples

# See the Workflow vignette on the GRaNIE website for examples
GRN = loadExampleObject()
#> Downloading GRaNIE example object from https://git.embl.de/grp-zaugg/GRaNIE/-/raw/master/data/GRN.rds
#> INFO [2023-08-16 17:28:36] Storing GRN@data$RNA$counts matrix as sparse matrix because fraction of 0s is > 0.1 (0.44)
#> Finished successfully. You may explore the example object. Start by typing the object name to the console to see a summaty. Happy GRaNIE'ing!
GRN_con.all.df = getGRNConnections(GRN)