Analysis was performed using CTD public data available (revision 17,266; March 2024). CTD is updated with new content on a monthly basis (https://ctdbase.org/about/dataStatus.go); consequently, query results described in this text may vary over time.

The freely available version 4.4.0 of R (https://www.r-project.org) was used (R Core Team, 2018). The R package data.table version 1.15.2 (https://CRAN.R-project.org/package=data.table) was used in preparing the data and the R package circlize version 0.4.16 (https://CRAN.R-project.org/package=circlize) was used to generate the chord diagrams (Gu et al., 2014). To format CGPD-tetramers and plot a basic chord diagram, download the CTD-vizscript.R, from GitHub (https://github.com/CTD-NCSU/Chord_Diagrams) or use the version included with a dataset of test tetramers (“test.csv”) for practice (Supplemental File S1). For CTD users unfamiliar with R, it is not necessary to download local versions of the software to generate the chord diagrams. Instead, a free, web-based version of R and RStudio environment from Posit Cloud (https://posit.cloud) may be used to generate the diagrams; users will need to first create a free account at Posit Cloud, and the steps required using the latter method are provided below.

Step 1: Download CTD Tetramers query results in CSV format (and rename the file to something more intuitive); start with a dataset of no more than 1,500 tetramers (discussed below); alternatively, use the test sample CSV file provided as “test.csv” (Supplemental File S1), which contains 309 CGPD-tetramers composed of two chemicals (copper and iron), 61 genes, 87 phenotypes, and 1 disease (liver neoplasms).

Step 2: Download CTD-vizscript.R locally from GitHub (https://github.com/CTD-NCSU/Chord_Diagrams) or use the provided file (Supplemental File S1)

Step 3: Create a free account at Posit Cloud (https://posit.cloud) and log in to the “Your Workspace” web page.

Step 4: On the right-hand side of the workspace web page, click on the “New Project” button and select “New RStudio Project” from the drop-down menu. The browser will reload showing three panes: “Console” in the upper left, “Environment” in the upper right, and “Files” in the bottom right; browser screenshots for the subsequent steps are provided (Supplemental File S2). In the bottom right pane (“Files”), click on the “Upload” button to browse for and select the downloaded copy of CTD-vizscript.R file (panel A, Supplemental File S2); then upload the CSV formatted file of the CTD Tetramer query results that are to be visualized, or use the provided sample file “test.csv.” Both files will now be listed in the “Files” pane.

Step 5: Click on the CTD-vizscript.R file and the script will appear in a new upper left-hand pane (and “Console” will displace to the bottom left). An alert will pop up and ask to install circlize and data.table. Choose install (panel C, Supplemental File S2). In the “Console” window, you’ll see the program run until it is finished.

Step 6: Load data.table and circlize using the library() command to make them available for future steps. To do this, go to code lines 2–3 and execute the two lines of the script by using the cursor to physically highlight the two lines for library(data.table) and library(circlize) in the window pane, and then click “Run” button (panel D, Supplemental File S2).

Step 7: Under “#Import data,” at code line 6 assign the name of the CTD Tetramer query result file to the variable “tetramers” (panel E, Supplemental File S2). To do this, type in the exact name of the file, which is case-sensitive, surrounded by quotation marks, and suffixed with “.csv,” all enclosed with the parentheses. For example, if using the provided test file (test.csv), then set the line to read: tetramers < - read.csv(“test.csv”). The case-sensitive file name must be spelled exactly, contain the CSV suffix, be flanked by quotation marks, and enclosed in the parentheses.

Step 8: Using the cursor, highlight the line from step 7 (where the tetramer file name is entered on code line 6) along with the rest of the script to code line 60 (panel F, Supplemental File S2). Click the “Run” button.

Step 9: If everything runs successfully, the tool will generate a colored chord diagram in the lower right pane under “Plots” (panel I, Supplemental File S2). This process can take a few minutes, depending upon the total number of CGPD-tetramers that are being graphed. See below for common errors that might arise. To adjust the font size of the labels, go to code line 59 and find “cex = ” near the end of the script under “## Add labels to diagram” (panel H, Supplemental File S2). “cex” stands for “character expansion” and is the parameter that changes the font size of the node labels. It has a default value of 1; to make the font size smaller, the parameter can be changed to a value between 0 and 1; for example, cex = 0.5 will result in text that is 50% smaller than the default value. Changing the parameter to a value greater than 1 will result in larger text; for example, cex = 1.5 will result in text that is 50% larger than the default value. The greater the number of tetramers being plotted, the smaller the value of cex should be in order for the labels to be clearly separated and not overlapping. Additionally, or alternatively, for very large sets of tetramers where the node labels are difficult to resolve, a user might instead prefer to display only the node accession identifiers, as discussed below. After changing the value of cex, go to code line 45 and highlight the text beginning with circos.clear along with the remaining script, and click “Run”. This is necessary to clear out the old data and rerun the program using the newly entered values.

Step 10: The chord diagram can be saved as either a PDF or an image by clicking the “Export” button under the “Plots” tab of the lower right-hand pane (panel I, Supplemental File S2).

Common error 1: An error that states Error in setDT(cgpd): could not find function “setDT” indicates the data.table package is not loaded. Highlight the line that says library(data.table) near the top of the script (code line 2) and click “Run.” This will make the function “setDT” available.

Common error 2: An error that states any of the following are not found, “circos.clear,” “circos.par,” “chordDiagram,” or “circos.track, indicates the circlize package is not loaded. Highlight code line 3 that says library(circlize) and click “Run.” This will make those functions available.

Common error 3: An error that states “Maybe your “gap.degree” is too large so that there is no space to allocate sectors” indicates that there is a very large number of tetramers. First, highlight the code line 45 that says circos.clear() and click “Run.” Next, go to code line 47 that says circos.par(gap.degree = 1) and change gap.degree to a number less than 1 (panel G, Supplemental File S2). This is a setting for the gaps between neighboring nodes. Larger values for gap.degree will create larger spacing between nodes and smaller values for gap.degree will create smaller spacing between nodes. Once gap.degree is changed to a smaller value, highlight the line along with the rest of the script and click “Run.” If the error occurs again, repeat the process of running circos.clear, changing gap.degree to an even smaller number and rerunning the script.

To enhance the readability of large chord diagrams, it is sometimes preferable to shorten the node term label to an accession identifier (ID), as this further compacts the diagram by reducing the text. A label can be switched from “node term” to “node ID” easily by adding “.ID” as a suffix the end of the Chemical, Gene, Phenotype, or Disease variables (code lines 10–13) in the section under “# Prep data” (panel J, Supplemental File S2). Highlight the script beginning with this line along with the remaining script and click “Run”. Additional customization options can be found in the circlize documentation at https://jokergoo.github.io/circlize_book/book/index.html.

The default selection of color palettes for CTD tetramer chord diagrams are blue (chemical), green (gene), purple (phenotype), and red (disease). If necessary, users can change these colors using code lines 37–40 (panel K, Supplemental File S2). Each line of script for each of the four variables contains two colors. The script will create a palette from the first color listed to the second color. To change the color, simply edit the name in the code line, making sure the new color name is in quotation marks and the two colors are separated by a comma. There are many R color cheat sheets that can be found with an internet search to aid in choosing colors, including those that are specifically designed for users with color-vision deficiencies (Dahl et al., 2022).

A summary of the entire CTD-vizscript code is provided with information boxes showing the exact code lines that users can edit to customize the chord diagram output (panel L, Supplemental File S2).

To demonstrate how to transform a large dataset of CGPD-tetramers into a single chord diagram, we queried the CTD Tetramers tool (https://ctdbase.org/query.go?type=tetramer) using “metals” as the chemical input, selecting the hierarchy filter to include any descendant terms, and “liver neoplasms” as the disease outcome. This yields 309 CGPD-tetramers, composed of two chemicals (copper and iron), 61 genes, and 87 phenotypes connected to liver neoplasms (Figure 3). The web-based table result displays only the first 50 of the 309 CGPD-tetramers (but it can be set to display 500). The tabular output is downloaded from the webpage as a CSV file, and then following the step-by-step directions (see Methods), the CTD Tetramer results are processed to generate a chord diagram that depicts all 309 CGPD-tetramers in a single image (Figure 3). Each chemical, gene, phenotype, and disease is represented as a colored node on the circumference of the circle, with chemicals shown in a blue palette, genes in a green palette, phenotypes in a purple palette, and diseases in a red palette. The arcs in the center of the circle connect the four nodes of each CGPD-tetramer, and are read in a clockwise manner: chemical (blue arc) to gene, gene (green arc) to phenotype, and phenotype (purple arc) to disease. The length of the node reflects the frequency that the specific data term occurs in the CGPD-tetramers and the width of the arc is proportional to the frequency that a dimer interaction occurs (Figure 2). Larger nodes/arcs readily highlight the more commonly used data types, and visually indicate potentially important molecular players, such as the genes HMOX1, TP53, and TNF, and the phenotypes cell proliferation and cell cycle for metal-associated liver neoplasms (Figure 3).

Environmental health is a complex, multifactorial system wherein outcomes can be the result of chemical mixtures and of multiple, independent chemical exposures from different sources (Davis et al., 2023b). Thus, CTD users often query for and analyze different sets of CGPD-tetramers for different chemicals and then combine the data to look for overlaps between shared molecular mechanisms and diseases. To aid in such analysis, multiple tetramer query results can be combined into a single chord diagram. To merge query results, it is most straightforward to download the individual CSV files for each independent query, combine the files into a single CSV document (using Excel copy-and-paste), and then upload that single file as the data source for generating a chord diagram as described above.

For example, numerous environmental factors have been associated with male infertility, including phthalates, pesticides, and arsenic (Rodprasert et al., 2023). Three independent queries for CTD tetramers that relate the chemicals dibutyl phthalate, atrazine, and arsenic to male infertility can be combined into a single chord diagram to help identify potentially key genetic and phenotypic molecular mechanisms associated with these environmental stressors (Figure 4). In total, these three independent queries yield 381 CGPD-tetramers composed of 37 genes and 124 phenotypes connecting the three chemicals to male infertility. Visualization of this complex environmental health dataset illuminates candidate genes (BAX, BCL2, and SOD2) and phenotypes (male gonad development, apoptosis, and spermatogenesis) connecting the chemicals to male infertility, and thus may represent critical intermediate molecular mechanisms (Figure 4).

An impediment for visualizing CGPD-tetramers as a chord diagram is spacing constraints that limit the comprehensibility of these diagrams. We have found that about 1,500 tetramers tend to represent a practical upper limit for figure clarity. For larger datasets, there are a few options. As described above, customizing the node displays either using the “cex” parameter (for font size) or changing the label from “term” to “node ID” will significantly reduce the text (panel J, Supplemental File S2), resulting in a more compact diagram, but still enabling nodes to be readily identified. As well, the starting number of CGPD-tetramers to be graphed can be reduced preemptively by adding additional search parameters in the query to narrow the dataset to focus on a more specific question. For example, a query for “liver neoplasms” results in over 16,700 CGPD-tetramers, and represents a very broad open-ended question with respect to environmental health. However, when “metals” is included as the chemical parameter in the search, the number reduces to 309 (Figure 3), and focuses on a more specific, addressable environmental health question. Alternatively, including phenotypes (e.g., “nervous system process,” “inflammatory response”, or “metabolic process,” with the filter option actively changed to include any descendant term) can also help focus questions and provide a more manageable number of CGPD-tetramers for analysis. Finally, CTD is also exploring ways to rank tetramers with a metric score as a means to prioritize the query results with the CGPD-tetramers that have the most supporting lines of evidence from the literature. Currently, the default display is alphabetical on the web-page results. Ranking would allow users to select tetramer subsets (instead of using the entire output) to include in their chord diagram.

Another limitation is the use of colors to represent information, as this may be an issue for those with color-vision deficiencies. Users can customize the plot colors to provide accessibility for specific color-vision deficiencies (Dahl et al., 2022) or for aesthetic purposes (panel K, Supplemental File S2).

Finally, the obvious complicating factor to this approach is the manual effort required to download and transfer data files from CTD to an R environment in order to generate a chord diagram. Consequently, we plan to integrate similar functionality directly into CTD Tetramer query results pages in a future release.