All set!

Now that we’ve obtained functional annotation results from the macrophage dataset, we can begin exploring the data using GeDi. You have two options: you can either launch the application and supply the generated data using the GeDi() command, or if you’ve followed this vignette, you can initiate the application directly with the loaded data by executing GeDi(genesets = macrophage_topGO_example).

GeDi()

GeDi(genesets = macrophage_topGO_example)

The above shown code will open the application, directing you to the Welcome page. The Welcome page of GeDi serves as the entry point to the application, providing users with an overview of its features and functionalities. Upon launching the application, users are greeted with a user-friendly interface designed to facilitate the exploration and interpretation of functional annotation and enrichment analysis results. The Welcome page offers guidance on how to navigate the application and highlights key components such as data input options, visualization tools, and interactive features. Whether users are new to GeDi or returning to explore additional datasets, the Welcome page serves as a central hub for accessing resources and getting started with their analysis journey.

Header (navbar)

The dashboard navbar in GeDi, referred to as such in the bs4Dash framework, features a dropdown menu accessible by clicking on the respective “info” icon. The menu offers additional functionality through various buttons:

• The open book icon - This option allows users to explore the GeDi vignette, either the version bundled with the package or the online version, providing detailed documentation and usage guidelines.
• The information i cirle - Selecting this option displays information about the current session, presenting details such as the R environment and loaded packages, helpful for troubleshooting and debugging purposes.
• The heart button - This button offers general information about GeDi, including links to its development version for contribution and guidelines on citing the tool in research publications.

Besides the two dropdown menus, users can also find the Bookmark button in the Navbar. The Bookmark button in the GeDi navbar serves as a convenient tool for users to save and bookmark genes and genesets of interest for later reference. To use this feature, users must first select or click on a gene or geneset that they wish to bookmark. Once the desired gene or geneset is selected, users can then click on the Bookmark button to add it to a list of bookmarked items within the GeDi application. This functionality enables users to organize and revisit specific genes or genesets that they find relevant or intriguing during their exploration of functional annotation and enrichment analysis results. The bookmarked genes and genesets can later be found in the Report panel.

Sidebar

By clicking the menu bar icon on the left side of the app (or simply by moving the mouse over to the left side if viewing the app in full screen mode), users can activate the sidebar menu. This sidebar menu serves as the primary means of accessing the various panels of the GeDi application, providing navigation to different functionalities. More detailed explanations of each panel will be provided in the next section.

Body

The structure of GeDi is designed around different panels, each of which becomes active upon clicking the corresponding icons or text in the sidebar.

While the Welcome panel is relatively self-explanatory, additional information and explanations are provided for the functionality of the remaining panels. For new users seeking guidance, there’s a question circle button available to initiate an interactive tour of GeDi. This tour allows users to learn the basic usage mechanisms by actively engaging with the interface. During the tour, specific elements are highlighted in response to user actions, while the rest of the UI remains shaded to maintain focus. Users can interrupt the tour at any time by clicking outside the highlighted window, and navigation between steps is facilitated by arrow buttons (left, right). The tour functionality is implemented using the rintrojs package.

The Welcome panel

This panel serves as a guide for utilizing GeDi effectively. It offers detailed instructions on generating input data for the application, elucidating the expected input format and outlining the various interactive elements present in the app’s other panels.

The Welcome panel of GeDi

The Data Input panel

This panel serves as a hub for managing data input if it’s not provided within the function call. It’s divided into distinct boxes, each representing a step of the data input process, which sequentially appear as you successfully complete each preceding step.

Step 1: Provide your Genesets as input data

In the initial Step 1 box, you can provide your data by utilizing the Browse button. This action opens a modal window enabling you to select the relevant file from your computer storage. After successfully loading the data, a preview is displayed in the Genesets preview box on the right. During this step, the application checks if your input contains the “Genesets” and “Genes” columns. If these columns are missing, a small error message appears in the lower right corner. Additionally, two drop-down menus allow you to select the correct columns from your data and update the input accordingly.

You also have the option to start using GeDi with preprocessed example data based on the macrophage dataset. Simply click the Load demo data button to load the example data’s enrichment results. You can explore these results in the Genesets preview box.

However, instead of loading demo data and observing the expected data structure through the Genesets preview box, you can also use the Have a look at the data structure button. By clicking this button, a modal window with a visual representation of the expected input data structure will open. This screenshot serves as a helpful guide, providing you with a clear understanding of how your data should be formatted for optimal compatibility with GeDi.

Once, you have successfully loaded some data, the data input process will proceed and two additional boxes will be displayed in the panel.

The Data input panel - Step 1

Optional Filtering Step: Filter generic genesets

Introducing the first new box, the Optional Filtering Step offers a non-compulsory yet advantageous opportunity to refine your geneset selection. While not obligatory for data exploration, engaging in this step can notably optimize downstream processing runtime. Here, you’re empowered to filter genesets within your dataset, thereby enhancing result interpretation. This step enables the exclusion of large and generic genesets, contributing to clearer insights. Additionally, you have the flexibility to filter genesets based on size criteria.

The box features a histogram illustrating geneset sizes, providing visual context for the filtering process. Within the interface, two input fields are available for customization. The left input field facilitates the selection of individual genesets by their identifiers in the “Genesets” column of your dataset. Meanwhile, the right input field empowers you to establish a threshold “x” for filtering genesets with a size greater than or equal to “x.” This interactive approach ensures tailored filtering suited to your specific analysis requirements.

Once you’ve chosen the genesets you wish to exclude from your dataset, you can initiate the filtering process by clicking the “Remove the selected Genesets” button. This action will remove all selected genesets from the dataset. Additionally, you have the option to save the filtered data using the “Download the filtered data” button. Clicking this button will save the filtered data to your local machine. This feature can be particularly beneficial for users who intend to revisit their data in a new instance of GeDi and want to ensure that previously identified uninsightful genesets have already been filtered out.

Once you’ve chosen the genesets you wish to exclude from your dataset, you can initiate the filtering process by clicking the Remove the selected Genesets button. This action will remove all selected genesets from the dataset.
Additionally, you have the option to save the filtered data using the Download the filtered data button. Clicking this button will save the filtered data to your local machine.This feature can be particularly beneficial for users who intend to revisit their data in a new instance of GeDi and want to ensure that previously identified uninsightful genesets have already been filtered out.

Optional Filtering Step

Step 2: Species Selection

Upon advancing to the second box labeled Step 2, you’ll encounter the crucial task of selecting the species associated with your dataset. This step holds significant importance for the computation of the pMM score within GeDi, which heavily relies on a Protein-Protein Interaction (PPI) matrix. This matrix plays a pivotal role in capturing protein interaction strength, thereby enriching distance scores with valuable biological context. To access and utilize this essential information, specifying the species linked to your dataset is mandatory. By clicking the input field, you’ll prompt a dropdown menu showcasing preselected species options. If your species is included, simply make your selection. Alternatively, if your species is not listed, you have the option to manually input it. In cases of uncertainty, a convenient link provided on the right directs you to the STRING database, enabling verification of species details and PPI availability for informed decision-making.

Species Selection

Step 3: PPI Matrix Download

Following species selection, a third box named Step 3 will emerge. In this phase, you have the opportunity to download the Protein-Protein Interaction (PPI) matrix. This process may necessitate some time, with a progress bar positioned in the lower right corner providing real-time updates on the download status. Once the download is complete, you can conveniently preview the PPI matrix within the PPI Preview box situated on the right-hand side of the interface. This will show that the PPI consists of three columns: Gene1 and Gene2, housing the gene symbols corresponding to the interacting proteins, and a column labeled combined_score, denoting the confidence level of each interaction. The assigned score is derived from the number of known interactions between two proteins, normalized to the (0, 1) interval utilizing the formula:

$$ \begin{aligned} combinedScore = \frac{(\#interaction - min)}{(max - min)} \end{aligned} $$

where min and max represent the minimum and maximum number of interactions, respectively.

In addition to downloading a PPI matrix during the current session, users can also upload a previously saved matrix for analysis using the Browse button. This functionality allows users to work with their own customized datasets or previously analyzed PPI matrices. Furthermore, saving the downloaded PPI matrix locally enables users to store the data on their machine for future use. By saving the matrix locally via the Save PPI matrix button, users can access the data quickly in subsequent sessions without having to wait for the download process again. This capability significantly enhances workflow efficiency and allows for seamless continuation of analysis across different sessions.

Downloading the PPI

While the final two steps are optional, note that the PPI matrix is only required for a singular score. Therefore, you can commence data exploration without necessarily completing these additional steps.

Upon concluding the essential tasks outlined in this panel, you are ready to progress to the Distance Scores panel.

The Distance Scores panel

This panel focuses mainly on computing distance scores for the provided input data. Like the preceding panel, it is segmented into two distinct sections, each serving a specific function.

The Distance Score panel

Calculating Distance Scores

In the upper box, titled Calculate distance scores for your Genesets, you have the flexibility to select from various distance scores for computation. This feature provides users with a range of options to tailor the analysis according to their specific requirements and preferences. The available scores are:

• pMM Score: This score integrates protein-protein interaction (PPI) data into the Meet-Min distance. The PPI-weighted Meet-Min (pMM) score is defined as

$$ \begin{aligned} pMM = min(pMM(A -> B), pMM(B -> A)) \end{aligned} $$ where

$$ \begin{aligned} pMM(A -> B) = 1 - \frac{|A \cap B|}{min(|A|, |B|)} - \frac{\alpha}{min(|A|, |B|)} * \sum_{a \in A - B} \frac{w * \sum_{b \in A \cap B} P(a, b) + \sum_{b \in B - A} P(a, b)}{max(P) * (w * |A \cup B| + |B - A|)} \end{aligned} $$ and

$$ \begin{aligned} w = \frac{min(|A|, |B|)}{|A| + |B|} \end{aligned} $$ α is a scaling factor between 0 and 1. The PPI matrix can be downloaded from the Data Input panel. More details can be found in the paper by Yoon et al (Yoon et al. 2019).

• Kappa Score: The Kappa distance is a set-based metric based on observed and expected agreement rates between two genesets. It is defined as

$$ \begin{aligned} Kappa = 1 - \frac{O - E}{1 - E} \end{aligned} $$

where

$$ \begin{aligned} O = \frac{|A \cap B| + |A \cup B|^c}{U} \\ E = \frac{|A| |B| + |A^c| |B^c|}{|U|^2} \end{aligned} $$

U is the set of all unique genes in the data. In this application the Kappa distance is additionally normalized to the (0, 1) interval to make it comparable to the remaining distance metrics.

• Jaccard Score: The Jaccard distance uses the Jaccard coefficient, which is transformed into a distance metric by subtracting it from 1. It is defined as

$$ \begin{aligned} Jaccard = 1 - \frac{|A \cap B|}{|A \cup B|} \end{aligned} $$

• Meet-Min Score: The Meet-Min (MM) distance transforms the overlap coefficient into a distance measure by subtracting it from 1.The overlap coefficient is a similarity measure which is defined as

$$ \begin{aligned} OC = \frac{|A \cap B|}{min(|A|, |B|)} \end{aligned} $$

In order to transform this measure of similarity into a measure of distance, the overlap coefficient is subtracted from 1, resulting in the calculation of the Meet-Min (MM) distance as

$$ \begin{aligned} MM = 1 - \frac{|A \cap B|}{min(|A|, |B|)} \end{aligned} $$

As a solely set based measurement, the Meet-Min distance only takes the composition of the genesets into account but not the underlying biological information inherent in the genesets.

• Sorensen-Dice: The Sorensen-Dice distance uses the Sorensen-Dice coefficient, which is transformed into a distance metric by subtracting it from 1. It is defined as

$$ \begin{aligned} Sorensen-Dice(A, B) = 1 - \frac{2 * |A \cap B|}{|A| + |B|} \end{aligned} $$ As a solely set based measurement, the Sorensen-Dice distance only takes the composition of the genesets into account but not the underlying biological information inherent in the genesets.

• GO distance: The GO distance score measures the relationship between gene sets that are represented by GO terms. Implemented in the GOSemSim Rpackage, there are two main types: information content (IC)-based methods(e.g., Resnik, Lin, Schlicker, and Jiang) and graph-based methods (e.g., Wang). These methods compute similarity scores based on shared characteristics, such as the most informative common ancestor in IC-based methods or the hierarchical structure of the GO database in graph-based methods. To integrate these scores into distance-based analyses, the similarity scores are converted into distance scores by subtracting the similarity score from 1. This transformation ensures compatibility with other distance metrics used in GeDi. While applicable only to GO terms, this approach is particularly useful in gene function analyses.

Each scoring method possesses its own set of advantages and drawbacks, underscoring the importance of selecting one that suits your dataset characteristics and analysis goals. Upon choosing a score, the Compute the distances between genesets button appears on the on the right side. Clicking this button initiates the scoring procedure, which may require some time to execute, particularly for larger datasets. To monitor the progress of this operation, refer to the progress bar located in the lower right corner of the panel. Once the scoring process concludes, you can delve into the Geneset Distance Scores box to explore a variety of visual representations of your data.

Distance Scores Visualizations

• Distance Scores Heatmap: The initial visualization offered is a heatmap illustrating the distribution of distance scores. Activation of the heatmap generation is triggered by clicking the Calculate Distance Score Heatmap button. Following computation, users can interact with the heatmap by hovering over it, revealing the involved genesets and their corresponding scores. Additionally, users can zoom in on specific areas of interest. To reset the zoomed view, a simple click outside the heatmap area suffices.

• Distance Scores Dendrogram: The second visualization provided is a dendrogram showcasing individual distance scores. Hierarchical clustering is employed to generate the dendrogram, which effectively groups genesets exhibiting the highest similarity. To enhance the dendrogram’s presentation, users can select different combination methods using the drop-down menu located on the left side.

• Distance Scores Graph: The final visualization available is the network representation of distance scores. In this representation, nodes/genesets with scores below a predefined threshold are connected by edges. By default, the threshold is set to 0.3, but users can adjust it via the slider located on the left. This interactive graph allows users to hover over or click on nodes to highlight connected nodes and obtain additional information about genesets upon selection. Furthermore, users can search for specific genesets using the input field on the left, with the selected geneset being subsequently highlighted in the graph. The Graph metrics table at the bottom of this box contains various metrics pertaining to the graph, such as degree, betweenness, harmonic centrality, clustering coefficient, and input data. This tabulated information serves to provide users with valuable insights into the underlying data and distance scores.

Bookmarking from the this panel:

As users navigate through the distance scores of genesets in this section, they may encounter genesets and interactions that capture their interest and merit further investigation. To aid in preserving these noteworthy genesets for later exploration, you can utilize the Bookmark button situated in the Navbar. Upon clicking this button, the selected geneset will be added to the list of bookmarked genesets within the Report panel. Additionally, informative messages displayed in the lower right corner will guide users through the bookmarking process.

Once you’ve finished exploring the distance scores, you can proceed to the Clustering graph panel.

The Clustering Graph panel

This panel is dedicated to the computation of clusters among genesets based on their similarity, which is derived from the previously calculated distance scores. Similar to the preceding panel, it comprises two distinct boxes. Within these boxes, users can access functionalities to determine and visualize clusters of genesets that exhibit comparable characteristics or functions.

The computation of clusters involves grouping genesets that display similar patterns of distance scores, thereby indicating shared biological characteristics or functional relationships. This clustering process enables users to identify cohesive groups of genesets with related functionalities or involvement in similar biological processes.

The Clustering Graph panel

Choosing a Clustering algorithm

The upper box, labeled Select the clustering method, provides a selection of distinct clustering algorithms. Users can explore various options to find the most suitable algorithm for their analysis:

• Louvain: The Louvain algorithm, a prevalent tool in biological network analysis, seeks to divide graph nodes into clusters to optimize the modularity metric. This metric gauges the strength of connections within clusters relative to those between clusters. Consequently, nodes within the same cluster exhibit greater similarity to one another than to nodes outside the cluster. This clustering approach aims to enhance data interpretation by grouping similar genesets together. Users can adjust a slider in the bottom left corner of the box to set a similarity threshold, determining when genesets are considered similar based on distance scores.

• Markov: The Markov algorithm, commonly employed in biological network analysis, is designed to pinpoint densely interconnected regions within graphs. These regions frequently align with communities or clusters in the graph structure. Users can utilize a slider located in the bottom left corner of the box to specify a similarity threshold, determining when genesets are deemed similar based on distance scores.

• Fuzzy clustering: The Fuzzy Clustering algorithm is a computational technique used to partition data points into clusters based on their similarity, while allowing for data points to belong to multiple clusters with varying degrees of membership. It operates through distinct steps and requires the specification of different thresholds. Firstly, the Similarity threshold is set to determine if two genesets exhibit sufficient similarity to be potentially clustered together. Secondly, the Membership threshold dictates how many members of a potential cluster must possess a close relationship, defined by a distance score less than or equal to the similarity threshold, for the cluster to persist. Lastly, the Clustering threshold determines whether two clusters will be merged. Clusters are merged if their percentage of overlap meets or exceeds the clustering threshold. Users can adjust all thresholds using sliders provided in the interface.

• PAM: The PAM (Partitioning around Mendoids) clustering algorithm partitions nodes into k distinct clusters, where k is a user-defined parameter. The algorithm iteratively assigns each node to the nearest cluster center based on calculated distance scores, and then updates the cluster centers to minimize the overall variance within each cluster. Users can specify the number of clusters, k, using a slider in the interface, allowing them to tailor the clustering process to the needs of their analysis. Adjusting the value of k enables the exploration of different clustering granularities, providing flexibility in interpreting the data and identifying meaningful patterns.

Once you choose a method, you can start the cluster calculation via the Cluster the Genesets button on the right. Keep in mind that this step might take some time, especially for larger datasets. Look for the progress bar in the lower right corner for updates on the scoring status.

Once the clusters are calculated, you can explore various visualizations of your data in the Geneset Cluster Graphs box.

Cluster Visualizations

• Geneset Graph: In the Geneset Graph, clusters are visualized as a graph, with individual genesets serving as nodes and edges connecting genesets within the same cluster. To highlight specific nodes, utilize the Select by id feature on the left, or choose to highlight entire clusters by selecting the respective option under Select by cluster. Please note that only genesets belonging to at least one cluster will be displayed in this graph. For additional insights, nodes can be colored based on specific parameters from your input data, accessible through the Color the graph by dropdown menu. Depending on the information provided with your data, various options will be available. While interacting with the network, nodes can be moved by clicking and dragging them to desired locations, offering flexibility in managing node placement which is particularly useful in complex or densely populated graphs.

• Cluster-Geneset Bipartite Graph: The Cluster-Geneset Bipartite Graph presents a bipartite representation of the clusters. In this visualization, nodes represent both clusters and genesets, with edges connecting cluster nodes to their corresponding geneset members. Hovering over nodes provides additional data insights. Cluster nodes display the members within each cluster, while geneset nodes showcase the genes associated with each geneset.

• Cluster Enrichment Terms Word Cloud: The Cluster Enrichment Terms Word Cloud displays the most frequently occurring terms for each cluster. This visualization proves particularly useful when your data includes brief descriptions of the genesets, in addition to the mandatory input data. By utilizing the Select a cluster drop-down menu, you can designate the cluster of interest. Furthermore, hovering over the word cloud enables you to select individual terms and view the frequency with which each term appears in the descriptions of the genesets within that cluster.

• Clustering graph summaries: The cluster information is also summarized in a table-like format in the Clustering graph summaries box. This table displays each geneset alongside the cluster to which it belongs. Additionally, the table features a search function, facilitating the quick retrieval of a geneset of interest.

Bookmarking from this panel:

While exploring the Clustering Graph panel, users may encounter genesets and clusters that intrigue them and warrant further investigation. To facilitate the preservation of these notable genesets and clusters for future exploration, users can utilize the Bookmark button located in the Navbar. Clicking this button will add the selected geneset or cluster to the list of bookmarked items within the Report panel. Helpful messages displayed in the lower right corner will assist users throughout the bookmarking process.

In order to bookmark interesting genes and clusters, users simply select a geneset or cluster from the Geneset Graph or Cluster-Geneset Bipartite Graph and use the Bookmark button to add the respective information to the set of bookmarked features. After exploring the results in the Clustering Graph panel, users can proceed to the Report panel to have a look at the bookmarked genesets and clusters or iterate through the individual panels of the app for a more in depth exploration of the data.

The Report panel

In this panel of the application, users can obtain a comprehensive overview of the items they have bookmarked for further exploration. On the left side of the interface, bookmarked genesets are listed, while bookmarked clusters are displayed on the right side.

During an interactive exploration session, recalling specific details about each bookmarked item can sometimes be challenging. Therefore, users are provided with convenient options to manage their bookmarked data.

Below the interactive tables displaying bookmarked genesets and clusters, users can find buttons allowing them to download the content of each table individually. Additionally, the Start the generation of the report button is provided to generate a detailed report encompassing all selected elements of interest.

The report generation process utilizes a predefined template report included within the GeDi package. This template leverages the input elements and reactive values associated with the bookmarks, ensuring that the generated report contains comprehensive and relevant information.

The resulting report serves as a valuable tool for creating a permanent and reproducible analysis output. Users can easily store or share this report for future reference or collaboration purposes.

The Report panel