HOCOMOCO-derived TFBS and download links

As a default, we use HOCOMOCO-derived TFBS predictions that were predicted with PWMScan. For further method details, see the diffTF paper from our lab.

We provide TFBS predictions for HOCOMOCO-based TF motifs that were used with PWMScan for hg19, hg38, mm10 and soon mm39. As of 2024, we recommend using HOCOMOCO v12 (Website, Paper). Using this database requires only one extra step of downloading the database and preparing it for the use with GRaNIE.

We provide the following downloads that can be directly used with GRaNIE:

hg38:

• PWMScan + HOCOMOCO v12 INVIVO collection (Download here)
• PWMScan + HOCOMOCO v11 (Download here)
• FIMO + HOCOMOCO v11 (Download here)

hg19:

• PWMScan + HOCOMOCO v10 (Download here)

mm10:

• PWMScan + HOCOMOCO v12 INVIVO collection (Download here)
• PWMScan + HOCOMOCO v10 (Download here)

mm39:

• PWMScan + HOCOMOCO v12 INVIVO collection (Download here)

To use them, simply download the file, extract and then reference the folder within the motifFolder argument in the addTFBS() function - see also the Workflow Vignette for examples.

Other TFBS sources

However, you may also use your own TFBS data, and we provide full flexibility in doing so. Only some manual preparation is necessary. Briefly, if you decide to use your own TFBS data, you have to prepare the following:

• a folder that contains one TFBS file per TF in bed or bed.gz format, 6 columns
• file names must be {TF}{suffix}.{fileEnding}, where {TF} specifies the name of the TF, {suffix} an optional and arbitrary string (we use _TFBS, for example), and {fileEnding} the file type (supported are bed and bed.gz).
• the folder must also contain a so-called translation table that must be called translationTable.csv. This file must have the following structure: 3 columns (tab-separated), called SYMBOL, ENSEMBL, and HOCOID. The first column denotes a symbol or shortcut for the TF that is used throughout the pipeline (e.g., AHR), the second the ENSEMBL ID (without the dot suffix; e.g., ENSG00000106546) and the third column the prefix of how the file is called with the TFBS (e.g., AHR.0.B if the file for AHR is called AHR.0.B_TFBS.bed.gz).
• we provide example files for selected genome assemblies (hg19, hg38, mm9, mm10, mm39) that are fully compatible with GRaNIE as separate downloads. For more information, check the links above.

For more methodological details, details on how to construct these files, their exact format etc we refer to diffTF paper and website for details.

Importing TF and TFBS from the JASPAR databases directly in R

As of March 2023, we additionally a more user-friendly way of importing TF and TFBS data from the various JASPAR databases that are available in R/Bioconductor: JASPAR 2022 and 2024. While we so far tested only with the JASPAR2022 database / R package, the other ones should also work - if not, please let us know. Using JASPAR2024 as TF database is much easier and also quicker from a user perspective, and none of the additional complexities that were mentioned above for the custom import apply here. However, we do note that HOCOMOCO v12 produces larger GRNs from our (limited) test experience. For details, see the addTFBS() and overlapPeaksAndTFBS() functions.

Note that we also implemented an option to customize which TFBS collection to use from the JASPAR database via the function argument JASPAR_useSpecificTaxGroup from addTFBS(). For example, this feature can be used to specify the whole TF collection irrespective of the genome assembly the data is in - which is useful for genomes such as rat or mouse, for which JASPAR only finds a few dozen TF at most if the specific genome was specified otherwise.

Be aware, though, that you may want to compare your eGRN across different TF and TFBS data - we are currently investigating the effect of using JASPAR motives and cannot currently comment much on it except what we sumamrized above: HOCOMOCO v12 produces larger GRNs from our (limited) test experience. We will, however, update the vignette here once we have more results to share.

Normalization methods common for peaks and RNA data

We currently support six choices of normalization of either peak or RNA-Seq data: limma_quantile, DESeq2_sizeFactors, limma_cyclicloess, limma_scale, csaw_cyclicLoess_orig, csaw_TMM plus none to skip normalization altogether. The default for RNA-Seq is a quantile normalization, while for the open chromatin peak data, it is DESeq2_sizeFactors (i.e., a “regular” DESeq2 size factor normalization). Importantly, some normalization methods such as DESeq2_sizeFactors strictly require raw data, while others, such as limma_quantile, do not necessarily.

Normalization methods specific for peaks data

For peaks, two additional GC-based normalization schemes are offered: EDASeq_GC_peaks and gcqn_peaks. We refer to the R help for more details (?addData).

Raw vs pre.normalized data

We recommend raw data as input, although it is also possible to provide pre-normalized data as input. Pre-normalizing data beforehand may be useful in case there are known batch effects, for example. Removing the batch effects from the counts before running GRaNIE therefore may be a worthwhile strategy, a procedure that generally produces non-integer counts. In such a case, the user can then either normalize the data with another normalization method (one that is suitable also with non-integer values, see above) or skip additional normalization and use the counts as they are (choosing none therefore for the normalization parameter).

TF-peak connection types

TF-peak connections are found by correlating a suitable measure related to TFs with peak accessibility, and then identifying statistically significant links. By default, TF expression is used as TF measure, but we also implemented an additional measure for establishing these links based on a measure called TF activity (see below).

GC correction

TFs and therefore also TF motifs can have very different GC preferences. Some TFs are known to bind to very GC-rich regions such as SP1. Thus, when calculating the TF-peak link FDRs, comparing a GC-rich or GC-poor foreground set of peaks with the full background (that is, all other peaks with no predicted site), the latter of which may exhibit a very different GC distribution, is potentially biasing the FDR values. We therefore offer an experimental feature to correct for this effect and to use a corresponding GC-matching background. The GC correction is enabled with useGCCorrection = TRUE in the function addConnections_TF_peak(). Note that the GC adjustment will take additional time and is currently much slower as compared to not adjusting the background.

Importantly, we note again that this feature is experimental as of now and we are still exploring its effects and plausibility.

When the GC correction is activated, the following is performed:

1. The pre-calculated GC content of each peak is taken and binned into 10 GC bins (0-10%, 11-20%, …, 91-100%)
2. For both TF-specific foreground and background, the relative frequencies of each of the GC bins is calculated (thus, the sum of all relative frequencies equals 1)
3. We currently offer two different modes of how to create a GC-matched background.
   1. When percBackground_resample is set to a value > 0 (default is 75), the background size is fixed to this value (i.e., 75 translates to a background size of 75% of the original size), and no iterative procedure is run to automatically determine the background size (see b).
   2. When percBackground_resample = 0, an automatic iterative procedure is run that determines the maximum value of percBackground_resample (starting from a value of 100 - the full size of the background - down to 5 maximum in steps of 5 per iteration) so that all GC bins with a relative frequency of at least 5% in the foreground can be matched in sufficient numbers with the corresponding GC bin from the background. GC bins with a relative frequency of less than 5% are ignored due to their low relevance. If the background size as identified by the iterative procedure selects a background that is too small (< 1000 peaks), the selected background percentage is again increased in steps of 5% until at least 1000 peaks can be selected from. This is done for statistical reasons and ensures a minimum no of points in background, even if this sacrifices the mimicking of the distributions as described above.
4. Finally, after a value for the percentage of the background size to sample from, the background can now actually be sampled for each GC bin. If percBackground_resample is set to TRUE, then the background distribution will mimic the foreground distribution perfectly even for GC bins that are very lowly abundant (i.e., those with a relative frequency of < 0.05 in the foreground). In summary, for GC bins for which not enough peaks are available in the background, a resampling scheme is performed that selects the required number of peaks by sampling with replacement from the background. If set to FALSE, however, no resampling is performed and the number of peaks selected from the background is the maximum that can be selected. In this case, the relative frequencies in foreground and background may differ. Note that when percBackground_resample = 0, this is only relevant for GC bins with a relative frequency of < 0.05, while otherwise, resampling may occur for an GC bin depending on the chosen value of percBackground_size

Rationale for choosing an appropriate number for percBackground_resample

Ideally, one would want to select as many peaks in the background as possible to maximize the sample size and therefore randomness for better statistical sampling. However, this often fails because particular GC bins may be very dominant in the foreground for GC-rich TFs (e.g., the GC bin 71-80% has a relative frequency of 25%) while the background contains overall only 5% peaks with this GC bin. Thus, one cannot select 25% of all background peaks (as the relative frequency of the GC bins in the foreground is to be kept in the background) of the same GC bin without resampling. The only alternative is to not use the full background size as reference, but only a particular percentage of it so that the required absolute numbers of peaks to sample from decreases and eventually can be selected for all relevant GC bins. When choosing this option, the background size can be much smaller (e.g., 15% only), therefore also choosing only a relative small absolute number of peaks from the background. However, no resampling is done here, therefore not (by chance) giving particular peaks a higher weight.

You may ask which value to choose for percBackground_size and whether to use GC correction at all, however? These are good questions, and while we cannot give any guaranteed reply, we can give recommendations and our experiences from a limited number of datasets:

• for most TFS, those that have no GC preference, whether or not the background is GC corrected should not make a big difference as foreground and background are sufficiently similar for these TFs (in theory, we do not to verify whether this is actually really true)
• for those with extreme GC preferences, in either direction, foreground and background will be very different, and the effects of the GC correction are most visible. Choose some TFs with known GC preferences such as SP1 and check the diagnostic plots to verify and get a feeling for how well the correction worked.
• we generally recommend running GRaNIE once with and once without GC correction to compare the eGRNs. What we sometimes see is that in the eGRN without a GC correction, the most abundant TFs actually have a GC-rich motif, indicating that they may be overrepresented in the eGRN.
• for choosing an appropriate value of percBackground_size, we recommend leaving it at the default value of 75 first and potentially adjusting it after looking at the diagnostic plots. Higher values will result in (1) a higher number of GC bins that need resampling (and therefore potentially overrepresenting some peaks or indirectly causing a bias due to the higher percentage of resampled peaks) while (2) increasing the background size overall, which is better from a statistical sampling point of view. We think
  2. outweighs (1) and therefore set the default to a relatively high value, but we are still checking and experimenting with this feature. This is why the GC correction is still marked as experimental. On the other hand, a lower value will result in the opposite of the two points mentioned above. As often in statistics and science, it is about finding a good compromise.

Judging how well the GC correction worked

We also provide detailed QC plots that summarize both the GC background selection as well as the differences for teh TF-peak connections with and without GC correction. For more details, see here.

Reproducibility of GC correction

Lastly, we need to emphasize that the GC correction, due to the random sampling from the background, is not deterministic and may yield a slightly different number of connections each time it is run. The more bins are resampled (see discussion above), the more differences may arise

TF Activity connections

As explained above, TF-peak connections are found by correlation TF expression with peak accessibility. In addition to expression, we also offer to identify statistically significant TF-peak links based on TF Activity. The concept of TF Activity is described in more detail in our diffTF paper. In short, we define TF motif activity, or TF activity for short, as the effect of a TF on the state of chromatin as measured by chromatin accessibility or active chromatin marks (i.e., ATAC-seq, DNase sequencing [DNase-seq], or histone H3 lysine 27 acetylation [H3K27ac] ChIP-seq). A TF Activity score is therefore needed for each TF and each sample.

TF Activity information can either be calculated within the GRaNIE framework using a simplified and empirical approach) or it can be calculated outside of our framework using designated methods and then imported into our framework. We now describe these two choices in more detail.

Methods

In the GRaNIE framework, in addition to the real connections, we also calculate background connections in each step based on randomized data. Calculating a background eGRN follows exactly the same principles and methods as the real eGRN, without exceptions. It is only the input data that is shuffled in different ways, for both TF-peak links as well as peak-gene links, as follows:

1. TF-peak links: First, the rows of the binary 0/1 TF-peak overlap table are shuffled separately for each sample (i.e., per column) to produce a truly random overlap matrix. In addition, the sample labels for the RNA counts are shuffled. Thus, subsequently, the counts that are correlated between RNA and peak data are not from the same pair of samples in fact.

2. peak-gene links: After creating the real and true table for the peak-gene pairs that fulfil the user-specified requirements for being tested for correlation (e.g., within the specified distance from one another as defined by the parameter promoterRange), the peaks are shuffled. This consequently means that the peak-gene pairs that are subsequently tested for correlation are (usually) not in the specified proximity anymore, but instead mostly on other chromosomes or at a very different location on the same chromosome. Notably, this preserves the degree distribution for both peaks and genes: that is, if a gene or peak is overrepresented, this is also true for the shuffled version. Second, in analogy to the background TF-peak links, the sample labels for the RNA counts are shuffled before peak-gene correlations are calculated. The latter can be controlled via the parameter shuffleRNACounts in addConnections_peak_gene(). Empirically, we found that only shuffling the peak-gene links is not sufficient to create a truly random background, which is why the default behavior is to do the shuffling in addition. Nevertheless, this can be user-controlled.

3. TF-peak-gene links (eGRN): Combining TF-peak and peak-gene links for the background data then again follows the exact same methods as the real eGRN. However, due to the randomized nature of both the TF-peak and peak-gene links, the background eGRN typically has very few or no statistically significant connections at all.

In summary, we want to emphasize that we currently do not simply permute the real eGRN network. Instead, we re-construct an eGRN using the very same methods but with randomized data, as outlined above. This allows us to judge and compare the connectivity for the real network as compared to a background eGRN.

Object and output details related to the background links

In the GRN object (GRN@connections slot, to be specific), we label the background data with a 1, while the original data is labeled as 0. For example, GRN@connections$TF_peaks[["0"]] stores the original connections, while GRN@connections$TF_peaks[["1"]] stores those arising from the background.

Relevant output files consequently contain the background label to designate that the corresponding background has been used to generate the plot, while the original data is labeled as original.

General comments

We also provide the functions visualizeGRN() to visualize a filtered eGRN network as well as filterConnectionsForPlotting() to filter a eGRN just for visualization purposes. They are both very easy to invoke, but provide many options to customize the output and the way the graph is drawn. We recommend to explore the options in the R help (?visualizeGRN and filterConnectionsForPlotting()). Note that we use the provided network visualization methods from the igraph package for visualizeGRN().

Changing the visualization parameters and layout

Visualizing the whole network usually works well for small to medium-sized networks that contain up to a few hundred edges, but may fail for larger eGRNs. Drawing thousands of nodes and edges at once without losing readability is almost impossible. However, here are a few tips on what you can do if your eGRN cannot be drawn or it looks not nice enough:

• increase the value of the parameter maxEdgesToPlot to say 1000 or even more, and check whether the eGRN can be drawn. It may also help to increase the dimensions of the PDF (if plotAsPDF = TRUE) by increasing pdf_width and pdf_height.
• change the visualization layout by changing the layout parameter. Try all of the supported layouts (see ?visualizeGRN for a list), maybe one looks good enough.

Filtering the network for visualization purposes

If none of the plotting-related parameters improve the visualization or if you want to visually explore the network for particular features of the network (such as specific TFs, peaks, or genes), you can use filterConnectionsForPlotting() to filter a eGRN just for visualization purposes. This reduces the number of nodes and edges to plot and gives the user ultimate flexibility of what to visualize. For example, you can filter the network to just visualize the part of the network that is connected to a specific set of TFs (i.e, their regulons).

Alternatively, you can also re-filter the network again more stringently using filterGRNAndConnectGenes(), but then all subsequent analyses have to be rerun as well (e.g., build_eGRN_graph() and all enrichment functions). This may reduce the multiple testing burden for peak-gene p-values and recover connections that may not have passed the filter beforehand.

Object details

Our pipeline works and output a so-called GRN object. The goal is simple: All information is stored in it, and by keeping everything within one object and sharing it with others, they have all the necessary data and information to run the GRaNIE workflow. A consistent and simple workflow logic makes it easy and intuitive to work with it, similar to other packages such as DESeq2.

Technically speaking, it is an S4 object of class GRN. As you can see from the workflow vignette, almost all GRaNIE functions return a GRN object (with the notable exception of get functions - i.e., all functions that start with get). Except initializeGRN(), which creates an empty GRN object, they also all require a GRN object as first argument, which makes is easy and intuitive to work with.

GRN objects contain all data and results necessary for the various functions the package provides, and various extractor functions allow to extract information out of an GRN object such as the various get functions. In addition, printing a GRN object results in an object summary that is printed (try it out and just type GRN in the console if your GRN object is called like this!). In the future, we aim to add more convenience functions. If you have specific ideas, please let us know.

The slots of a GRN object are described in the R help, see ?GRN-class for details. While we work on general extractor functions for the various slots for optimal user experience, we currently suggest to also access and explore the data directly with the @ operator until we finalized it. For example, for a GRN object called GRN, GRN@config accesses the configuration slot that contains all parameters and object metadata, and slotNames(GRN) prints all available slots of the object.

Results in the object

During a typical GRaNIE analysis, almost all results are automatically stored in GRN object that is used as input (exceptions are indicated in the corresponding sections) and therefore, almost all functions return also the very same GRN object, containing in addition the results of the function.

The only exception is the function getGRNConnections() that can be used to extract the resulting eGRN network from a GRN object and returns a separate data frame and NOT a GRN object. For more information and an explanation about the various columns that are returned from the function, see the corresponding R help ( ?getGRNConnections).

Object summary

A summary of a GRN object can be retrieved with the function getGRNSummary(). This returns a named list that summarizes all relevant aspects for a GRN object. For more details, see the R help.

Object data

All user data is stored in GRN@data. This slot contains the following elements:

• peaks: Here, peaks data are stored, and the list contains the following elements:
  • counts stores the data after the user-selected normalization scheme has been performed (even if set to none)
  • counts_metadata stores the peak metadata (peak location, ID, and whether or not it is marked as filtered with the current object settings)
  • counts_raw is only present when the user used keepOriginalReadCounts = TRUE when running the addData() function. It stores the original, user-provided data before any normalization scheme. For memory reasons and because the raw counts are never directly used in the GRaNIE workflow, they are not stored by default (anymore).
• RNA: Here, RNA data are stored, and the list contains the same elements as the peaks data, with one additional element:
  • GRN@data$RNA$counts_permuted_index: A memory-saving representation of how to perform sample shuffling when permuting the data, which is the basis for constructing the background links for both TF-peak and peak-gene connections.
• metadata: Data frame with the user-provided sample-specific metadata and a few additional metadata that were added when running addData().
• TFs: Here, TF-specific data are stored, and the list contains the following elements:
  • TF_peak_overlap stores the binary 0/1 TF-peak overlap matrix that denotes whether a particular TF has a putative/predicted TF binding site in a particular peak. This information comes from the provided TF and TFBS data from the functions addTFBS() and overlapPeaksAndTFBS() in particular
  • classification stores the TF classification results and is only present when the function AR_classification_wrapper() has been run successfully. For more information, see here

Plots

No plots are specifically available for the count data, but the PCA plots can be used to visualize the variability in the normalized count data for both paks and RNA (see here for more details).

For the TF classification, output plots are available, see here for more details.

Object data

Currently, the actual PCA result data are not stored in the GRN object, but we may change this. We will update the Vignette once this is done and mention it in the News/Changelog.

Plots

The pipeline outputs PCA plots for both peaks and RNA as well as original (i..e, the counts the user provided as input) and normalized (i.e., the counts after normalizing them if any normalization method has been provided) data. Thus, in total, 4 different PCA plots are produced, 2 per data modality (peaks and RNA) and 2 per data type (original and normalized counts).

Each PDF consists of three parts: PCA results based on the top 500, top 1000 and top 5000 features (see page headers, depending on the parameter topn in plotPCA_all()). For each part, different plot types are available and briefly explained in the following:

1. Multi-density plot across all samples (1 page)

2. Screeplot (1 page)

3. Metadata correlation plot

4. PCA plots with different metadata being colored (5 or more pages, depending on available metadata)

Object data

The TF-peak connections are stored in GRN@connections$TF_peaks. This list is structured as follows:

• the first level constitutes, in analogy to many other places within the object, whether the real or background links are stored. For more details, see here.

• inside both real and background links (i.e., within GRN@connections$TF_peaks[["0"]] and GRN@connections$TF_peaks[["1"]]), a list with two elements is stored:

  • main, containing a data frame with the actual TF-peak connections along with additional properties
  • connectionStats, containing a summary of the empirical FDR procedure, stratified by TF, correlation bin, FDR direction and TF connection type. This slots also contains details on GC-specific information if activated (see parameter useGCCorrection = TRUE in addConnections_TF_peak)

The slot GRN@stats$GC is also populated:

• Irrespective of whether or not a GC correction has been done, overall statistics for the user-provided peaks with respect to GC properties and relative frequencies are stored in GRN@stats$GC$peaks.
• If the GC adjustment of the background has been performed, additional elements within GRN@stats$GC are stored:
  • TFs_GC_correction: A data frame that summarized the GC correction on the TF and GC bin level
  • TFs_GC_correction_plots: For each TF, the GC plots for each TF are stored, namely the same two plots that were part of the output plots (see below). For example, to plot the first plot of the TF AIRE.0.C, simply type GRN@stats$GC$TFs_GC_correction_plots$AIRE.0.C[[1]].

Plots

We provide multiple QC plots for the TF-peak connections as part of the output, as explained in the following.

Extra plots for the GC correction

When GC background adjustment was activated (useGCCorrection = TRUE in the function addConnections_TF_peak()), additional QC plots can optionally be generated with the function plotDiagnosticPlots_TFPeaks_GC(). They summarize all relevant data and adjustments related to the GC adjustment. Note that this function is not run automatically as part of the regular TF-peak diagnostic plots at the moment when plotDiagnosticPlots_TFPeaks() is executed.

Object data

It is also possible to extract the results from the AR classification out of a GRN object. Currently, this can only be done manually, extractor functions are in the works that will further enhance the user experience. The results are stored in the slot GRN@data$TFs$classification[[permIndex]] [[connectionType]]$TF.classification. Here, permIndex refers to the original, non-permuted (0) or permuted (1) data, while connectionType here is either expression or TFActivity, depending on whether the pipeline has also be run for TF Activity in addition to expression (see function addConnections_TF_peak()). Thus, typically, the results for the original data are stored in GRN@data$TFs$classification[["0"]] [["expression"]]$TF.classification. If intermediate results from the classification have not been deleted (the default is to delete them as they can occupy a large amount of memory in the object, see the parameters of AR_classification_wrapper for details), they can be accessed similarly within GRN@data$TFs$classification[[permIndex]] [[connectionType]]: TF_cor_median_foreground, TF_cor_median_background, TF_peak_cor_foreground, TF_peak_cor_background, and act.rep.thres.l.

Plots

The pipeline produces 3 different plot types related to the activator-repressor (AR) classification that can optionally be run as part of the GRaNIE workflow. For each of the 3 types, plots are produced for both the original (labeled as original) as well as the permuted (labeled as permuted) data.

The AR classification is run for the RNA expression data (labeled as expression) and can additionally also be run for TF activity data (labeled as TFActivity, see the function addConnections_TF_peak() and its parameter options).

In the following, the 3 plot types are briefly explained:

1. Summary heatmaps (files starting with TF_classification_summaryHeatmap): This is described in detail in the diffTF documentation.

   We explain and summarize this type of plot in the Workflow Vignette. Please check there for details.

2. Classification stringency summary plots (files starting with TF_classification_stringencyThresholds): This is described in detail in the diffTF documentation.

3. Density plots per TF (files starting with TF_classification_densityPlotsForegroundBackground): Density plots for each TF, with one TF per page. The plot shows the foreground (red, labeled as Motif) and background (gray, labeled as Non-motif) densities of the correlation coefficient (either Pearson or Spearman, see x-axis label) from peaks with (foreground) or without (background) a (predicted) TFBS in the peak for the particular TF. The numbers in the parenthesis summarize the underlying total number of peaks.

Object data

The peak-gene connections are stored in GRN@connections$peak_genes. This list is structured as follows:

• the first level constitutes, in analogy to many other places within the object, whether the real or background links are stored. For more details, see here.
• inside both real and background links (i.e., within GRN@connections$peak_genes[["0"]] and GRN@connections$peak_genes[["1"]]), a data frame with the peak-gene connections along with additional metadata (e.g., peak.ID, gene.ENSEMBL, peak_gene.distance), their connection origin (e.g TADs, knownLinks or neighborhood), and statistical properties are stored (peak_gene.r, peak_gene.p_raw).

Plots

The function plotDiagnosticPlots_peakGene() or indirectly the function addConnections_peak_gene() (when plotDiagnosticPlots = TRUE) plots various diagnostic plots for the peak-gene links that are imperative for understanding the biological system and resulting eGRN. In what follows, we describe them briefly, along with some notes on expected patterns, implications etc. Note that this section is subject to regular change.

The main QC summary figure on page 1 is divided into two rows: the upper row focuses on the peak-gene raw p-value from the correlation tests, while the lower row focuses on the peak-gene correlation coefficient. The left side visualizes the data of the corresponding metrics via density plots, while the right side bins the metrics and visualizes them with barplots for highlighting differences between real and background data as well as negatively and positively correlated peak-gene links (denoted as r+ and r-, respectively).

We will now discuss and explain both of them in more detail.

Object data

The peak-gene connections are stored in GRN@connections$all.filtered. This list is structured as follows:

• the first level constitutes, in analogy to many other places within the object, whether the real or background links are stored. For more details, see here.
• inside both real and background links (i.e., within GRN@connections$all.filtered[["0"]] and GRN@connections$all.filtered[["1"]]), a data frame with the TF-peak-gene connections along with additional metadata and statistical properties are stored. This table is not to be used directly, however; instead, the function getGRNConnections() has to be used to retrieve them and add additional information as needed along with it.

Plots

No plots are available here, but the eGRN can be visualized with visualizeGRN().

Object data

The peak-gene connections are stored in GRN@connections$$TF_genes.filtered. This list is structured as follows:

• the first level constitutes, in analogy to many other places within the object, whether the real or background links are stored. For more details, see here.
• inside both real and background links (i.e., within GRN@connections$$TF_genes.filtered[["0"]] and GRN@connections$$TF_genes.filtered[["1"]]), a data frame with the TF-gene connections along with additional metadata and statistical properties are stored. This table is not to be used directly, however; instead, the function getGRNConnections() with include_TF_gene_correlations has to be used to retrieve them.

Plots

For a particular (set of) TF-gene pair(s), the underlying TF-gene data and the correlation can be visualized with plotCorrelations(). For more information, see the R help for the function.

In addition, the eGRN can be visualized with visualizeGRN().

Object data

The results of the function generateStatsSummary() is stored in GRN@stats$connections. This table contains a lot of information, including but not limited to the various parameters the function iterated over to generate multiple eGRNs for different parameter thresholds and combinations such as the number of distinct TFs, peaks, genes, their connectivity, etc.

Plots

We currently offer two different connection summary PDFs, both of which are produced from the function plot_stats_connectionSummary(). Both PDFs shows the number of connections for each node type (TF, peak, and gene), while in the boxplots, peaks are further differentiated into TF-peak and peak-gene entities. They also iterate over various parameters and plot one plot per page and parameter combination, as indicated in the title:

1. allowMissingTFs: TRUE or FALSE (i.e., allow TFs to be missing when summarizing the eGRN network. If set to TRUE, a valid connection may consist of just peak to gene, with no TF being connected to the peak. For more details, see the R help for plot_stats_connectionSummary())
2. allowMissingGenes: TRUE or FALSE (i.e., allow genes to be missing when summarizing the eGRN network. If set to TRUE, a valid connection may consist of just TF to peak, with no gene being connected to the peak. For more details, see the R help for plot_stats_connectionSummary())
3. TF_peak.connectionType. Either expression or TFActivity to denote which connection type the summary is based on.

Both plot types compare the connectivity for the real and background data (denoted as Network type in the boxplot PDF), which allows a better judgment of the connectivity from the real data.

An example page for the summary heatmap looks like this:

Here, two heatmaps are shown, one for real (top) and one for background (bottom) network. Each of them shows for different combinations of TF-peak and peak-gene FDRs (0.01 to 0.2) the number of unique node types for the given FDR combination (here: TFs).

Second, a multi-page summary PDF for the connections in form of a boxplot, as exemplified with the following Figure:

Object data

The actual graph structure is stored in GRN@graph after successful execution of the function build_eGRN_graph().It contains two different kind of graphs, namely the TF-peak-gene and the TF-gene graph. Each of them is associated with a list element with the same name, which stores also the table that was used to create the graph along with the graph itself and the used parameters for creating it.

Plots

The function visualizeGRN() can be used for visualization of the eGRN graph.

Object data

The identified communities for each node are stored within igraph objects in GRN@graph$TF_gene$clusterGraph (retrievable via GRN@graph$TF_gene$clusterGraph$membership, for example) and as vertex attributes in GRN@graph$TF_gene$graph (retrievable via igraph::vertex.attributes(GRN@graph$TF_gene$graph)$community, for example).

Plots

The function visualizeGRN() can be used for visualization of the identified communities in the eGRN graph. The functions plotCommunitiesStats() and plotCommunitiesEnrichment() can be used for plotting and summarizing community properties and enrichments, respectively.

Object data

All enrichment results are stored inside GRN@stats$Enrichment . This contains a nested list with the named elements general, byCommunity, and byTF for general, community-specific and TF-specific enrichments, respectively.

Inside each of these elements, there is further nesting by the chosen ontology (e.g, `GO_BP), and whether results or the parameters of the enrichment function should be retrieved.

Plots

Object data

The results are added to GRN@stats$variancePartition as well as within the various feature-related elements of GRN@annotation. The former slot and results can be used for the various diagnostic and plotting functions from the variancePartition package.

The easiest way to retrieve and include the results into the final eGRN is to rerun the function getGRNConnections() and set include_variancePartitionResults = TRUE, as the results are NOT added automatically to GRN@connections$all.filtered either.

Plots

QC plots for the feature variation results are available via the function plotDiagnosticPlots_featureVariation().

We are currently working on updating details for this section. Stay tuned, coming soon!

Object data

SNP data is added via the function addSNPData(). When add_SNPs_LD = TRUE, additional information for SNPs in LD with any of the user-provided input SNPs are stored within GRN@annotation$SNPs and GRN@annotation$SNPs_filtered for the unfiltered and filtered SNP table, respectively, and the list of peak-associated SNPs is extended to SNPs in LD with overlapping SNPs from the user input.

Final peak-SNP overlaps are stored in GRN@data$peaks$counts_metadata. For more details, see ?addSNPData.

Plots

No plots are specifically available for the SNp data at the moment.