In spielmanlab/dragon: Deep Time Redox Analysis of the Geobiology Ontology Network

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)

The dragon (Deep-time Redox Analysis of the Geobiology Ontology Network) library provides a Shiny Application [@shiny] for examining mineral-chemistry networks over deep time on Earth, with a specific application of investigating biologically-relevant evolution of element redox states as recorded in the mineral record. These networks are built using open-source data from the Mineral Evolution Database [@med]. dragon uses the igraph [@igraph] and visNetwork [@visnetwork] libraries to construct user-friendly interactive networks that can be manipulated and explored in the browser and exported as publication-ready figures.

Citing dragon

If you use dragon, please cite the following publications:

• The dragon library
• Spielman, Stephanie J. and Moore, Eli K. 2020. "dragon: A New Tool for Exploring Redox Evolution Preserved in the Mineral Record." Frontiers in Earth Science. https://doi.org/10.1130/abs/2019AM-334056.
• The MED database
• Golden, Joshua J., Downs, Robert T., Hazen, Robert M., Pires, Alexander J., Ralph, Jolyon. 2019. Mineral Evolution Database: Data-Driven Age Assignment, How Does a Mineral Get an Age?” In GSA Annual Meeting. Phoenix, Arizona. https://doi.org/10.1130/abs/2019AM-334056.

Or, in LaTeX:

# dragon
@article{  ,
  author  = {Spielman, Stephanie J. and Moore, Eli K.},   
  title   = {dragon: A New Tool for Exploring Redox Evolution Preserved in the Mineral Record},      
    journal = {Frontiers in Earth Science},      
    volume  = {8},    
    pages   = {414},
    year    = {2020},
    url     = {https://doi.org/10.3389/feart.2020.585087}
}

# MED 
@inproceedings{ ,
    location = {Phoenix, Arizona},
    title = {Mineral Evolution Database: Data-Driven Age Assignment, How Does a Mineral Get an Age?},
    url = {https://doi.org/10.1130/abs/2019AM-334056},
    booktitle = {{GSA} Annual Meeting},
    year = 2019,
    author = {Golden, Joshua J. and Downs, Robert T. and Hazen, Robert M. and Pires, Alexander J. and Ralph, Jolyon}
}

Obtaining dragon

dragon can be used freely online. Please visit the dragon github page at https://github.com/sjspielman/dragon, which will contain the current link to the free online dragon server without any download.

Alternatively, the current release of dragon can be installed from CRAN, or the bleeding edge development version can be installed using the remotes library:

## Install from CRAN:
install.packages("dragon")

## Install from github (current release)
#install.packages("remotes")
remotes::install_github("sjspielman/dragon")


## Install from github for _experimental and unguaranteed_ features:
#install.packages("remotes")
remotes::install_github("sjspielman/dragon", ref = "dev")

To run dragon locally on your computer after installing the package, simply load the library and issue either command, run_dragon() or run_app():

## Launch application
library(dragon)
run_dragon() ## run_app() also works!

Building your network

By default dragon will used a cached and pre-processed version of the MED data. Upon launch, you will be greeted with a prompt indicating the status of the MED data used, with an option to update to the most recent MED data if the cache is out of date. If you elect to update the data, please be patient!! The download will take several minutes or more depending on your internet connection.

Once you acknowledge the prompt, you can proceed to build your network using the sidebar panel. Options and specifications for network construction are described below:

Network construction specifications

These input options are used to specify which elements and minerals will be included in the constructed network. Once you have set these options, click the "Initialize Network" button. When clicked, dragon will build and display your network (unless you turned the display off per settings below). You can change your network settings at any time, including changing the focal elements, without having to click this button again during a given dragon session.

• Select focal element(s).

• Use this dropdown menu to select one or more focal elements for your network. dragon will construct its network from all minerals that contain your selected elements. To build the full mineral network, simply click the "Select All" button in the dropdown - this will automatically selected all elements to be included.

• Select focal elements based on mineral composition. (New in version 1.1.0!)

• You can also select focal elements based on a mineral of interest using this dropdown menu. For example, you might be interested in studying the deep-time networks of all elements in a certain mineral. All constituent elements contained in minerals you select from this list will be applied as focal elements. For example, if you select "Acanthine" (formula Ag₂S), both Ag and S will be considered as the focal elements.

• Age (Ga) range of minerals.

• dragon will include only those minerals whose oldest-known-age is within the specified range, in billion years. For example. The range selection is inclusive. For example, if you select a range of 3-5 Ga, all minerals observed to have first formed 3 billion years ago or more will be included. By contrast, if you select a range of 2-3 Ga, all minerals whose oldest recorded formation is within the 2-3 Ga range will be included. The dates used in these calculations are based on mineral discovery dates as recorded in MED.

• Use maximum or minimum age of minerals

• The MED reports, for each mineral, a maximum and a minimum bound for its estimated age. When determining the oldest-known-age of minerals from MED, dragon will by default use the maximum recorded age bounds. This option can be used to instead specify that dragon uses the minimum age bounds. Changing this option will change your network, so we recommend using the maximum age bound unless you have a specific reason not to.

• Use separate nodes for each element redox

• When this option is turned on, dragon will divide element nodes in the network by redox state, rather than considering a single node for each element. For example, consider the element Fe (Iron), which can take on several redox states (2+ or 3+) depending on the mineral. When this option is turned off, there will be a single node "Fe." When this option is turned on, there will be a separate node for each redox state present in the network, e.g. Fe2+ and Fe3+ will be separate nodes. Note that for many minerals, the precise redox states of its constituent elements cannot be determined with confidence. For these circumstances, there will be a separate element node for unknown redox states.

• Force element intersection in minerals

• When more than one element is selected as focal, dragon will by default include all minerals (at the selected age range) which contain any of ("unity") the focal elements. When turning this option on, dragon will instead include only those minerals which contain all of ("intersection") the focal elements.

• Build network without display

• For extremely large networks (such as the full mineral network), the interactive rendering performed by visNetwork can take a very long time (several minutes) and exhibit overall slower behavior. By turning this option on, dragon will build the network in the background but will not display an interactive network. This option should be used when you wish to explore information about a network, but do not specifically need to visualize it.

Network styling specifications

dragon contains extremely flexibility functionality for styling your network to your liking, as follows. You can change these settings at any time while using dragon, and the updated settings will be automatically applied to your network.

Network layout and clustering options

This menu item allows you to specifiy network layout and clustering algorithms, as follows:

• Network layout: Use this menu to select an initial layout for the network. The "Force-directed" layout algorithms are stochastic, so you can also specify a Seed for reproducibility purposes.
• CAUTION! The "Dynamic physics layout" option can, for larger networks, produce substantial amounts of visual noise which may trigger photosensitive users.
• Network community detection (clustering) algorithm: You can select one of the two approaches "Louvain" [@louvain] or "Leading eigenvector" [@eigen] to perform community clustering on your network.

Node colors

Here you can select color schemes for element and mineral nodes (Color elements/minerals based on:"). Most simply, you can choose a single color for all nodes of a given group, or you can choose a data attribute according to which nodes of a given group will be colored. When an attribute is selected ("Color elements/minerals based on:"), you will have the choice of several colorblind-friendly palettes offered by the RColorBrewer package [@brewer].

When coloring nodes by an attribute, it is possible that some nodes will not have an associated attribute value, i.e. there may be some "NAs." The field Color to use for missing for unknown values can be used to select how nodes with missing information will be colored. Notably, this selected color will also be used for any NAs associated with "Edge Colors" (keep reading!).

Alternatively, you can choose to turn on the option Color all nodes by community cluster, which will override any element- or mineral-specific color scheme specified. All nodes will be colored according to their community cluster, using a colorblind-friendly palette of your choosing. The option to choose a community cluster palette will appear if this option is turned on.

Color individual elements

dragon can also apply specific colors to a set of element nodes of interest, on top of any color scheme specified under "Node Colors." First, you can turn on the option Highlight focal element(s) to specifically color your network's focal element(s) by a chosen color. Second, you can highlight any set of elements you would like to emphasize using the dropdown menu Highlight a set of elements and choosing an associated color.

Node Sizes

Similar to node colors, you can either select a single size for element and mineral nodes each, or you can set the size for each node type according to a given attribute. All size settings can be scaled up or down using the associated slider. Unlike the node colors where some attributes may have missing data, however, it is guaranteed that no attributes used for node sizing have any NAs.

Further, note that one of the sizing options for elements is "Number of known element localities." This quantity is based strictly on the number of localities where the element's associated minerals have been found in the specified network.

Node Shapes

Here, you can change the shape for element and mineral nodes. In particular, you can also disable the shape for element nodes and select the "Text only (no shape)" option. When this is selected, element node color and size will still be based on the specifications under "Node Colors", "Color Individual Elements", and "Node Sizes." Do not use the "Element font color" (keep reading!) to style text-only element nodes.

Node Labels and Font

Here, you can modify element node label color, as well as mineral node label color and font size. Due to specific details of how the visNetwork library handles element nodes, the element node size itself controls the element font size. Therefore, to resize element labels, please resize element nodes. Note further that the "Element font color" should only be used when element nodes have either a circle or square shape; it will have no effect when the element shape is text only.

By default, mineral node names are hidden as they are usually very long and contribute mostly visual noise. However, you can show mineral node names (and select the font color!) using the widgets "Mineral font color" and "Mineral font size". Unlike element nodes, the font color and size for mineral nodes is independent of the shape's size.

Edge attributes

Under thus menu item, you can set the edge color scheme as well as edge thickness. The edge color scheme specification is similar to that for node colors: You can either select a single color for all edges, or color edges according to a given attribute with a colorblind-friendly palette. Again, if an attribute is selected, some edges may have missing information. Please use the "Color to use for missing for unknown values" widget under the "Node Colors" menu item to specify the NA color to use.

Network Interaction Options

The final sidebar menu item controls how you interact with the network by allowing you to change the default visNetwork settings. None of these options will effect the network contents or styling.

• Node selection highlight degree
• This specifies how many connected nodes will be emphasized when you click a node. The default degree of "2" means all nodes within 2 degrees of separation (≤2 edges) will be emphasized.
• Emphasize on hover
• When turned on (default), nodes will be emphasized when the cursor hovers over them.
• Hide edges when dragging nodes
• When turned on (default), edges will visually disappear when re-positioning a node, and they will re-appear after you drag the node to its new location. This option increases the speed of the interactive network rendering, so we recommend keeping it on!
• Drag network in frame
• When turned on (default), you can reposition the entire network by clicking and dragging. When turned off, you can reposition individual nodes but not the network as a whole.
• Scroll in network frame to zoom
• When turned on (default), scrolling on your mouse will zoom in and out of the network.
• Show navigation buttons
• When turned on (not the default), a set of green buttons will appear in the network display frame which can be used to re-position and zoom in/out of the network.

Exporting your network

Below the interactive network are several buttons to export the network and its associated metadata:

• Export the nodes and associated metadata as a CSV file by clicking the button "Export nodes as CSV."
• Export the edges and associated metadata as a CSV file by clicking the button "Export edges as CSV."
• Export the legend image as a PDF by clicking the button "Export legend as PDF."

Finally, you can export the network image itself. On one hand, it is possible to directly right-click on the interactive network and click "Save Image As." This will save the network image exactly as it appears within dragon. Unfortunately, there are known limitations with visNetwork (itself a wrapper for the vis.js Javascript library) that prevent high-resolution image export. We therefore offer a separate approach for exporting the network image: We convert the visNetwork-formatted network display styled in the browser into a fully styled igraph object, which can be exported and visualized at high resolution. To use this approach...

• You must first click the "Click to prepare network for export to PDF" button. You need to click this button every time you change the node positions and want to update the export. (If you do not click this button, your exact network layout will be the inputted sidebar menu layout.)
• Then, click the "Export network as PDF" button, and your network image as a high-resolution PDF will be saved.
• Due to the visNetwork-igraph conversion, some of the exported aspects of the network image may not be precisely to your liking. Therefore, you can use the dropdown menu "PDF options" (above the "Export network as PDF" button) to slightly increase/decrease node sizes, and or remove the node outlines, and change the outputted PDF file's dimensions.

Analyzing the minerals in your network

Under the tab "Analyze Network Minerals," dragon will construct simple linear regressions to analyze the relationships among mineral properties in the network you have built. Note that this tab is also responsive to the inputs in the sidebar panel. If you change the network fundamentals (e.g. focal elements or age range), the analysis will change as well.

To perform a linear regression, specify a predictor (aka "explanatory" or "independent") variable and a response (aka "dependent") variable. The modeling results will be reported on the right side of the screen. If you select "Community cluster" as the predictor variable, a Tukey test will also be performed to perform pairwise comparisons of all clusters considered, so you will see two tables of results. A visualization of your model will appear below the table(s), and you can use style the plot according to various options that appear left of the visualization. You can also export this image using the "Download Plot" button.

There are several caveats to be aware of when conducting analyses in this tab:

• Hiding the sidebar panel can result in a better view. Click the "hamburger" button to the right of the app title will collapse the sidebar.
• Any network with fewer than three minerals cannot be analyzed. dragon will issue a warning if there are too few data points for statistical analysis.
• dragon will not check if the relationship between your numeric variables is indeed linear. You will need to gauge this for yourself in the resulting image.
• dragon will not transform the data in any way. You will need to gauge for yourself whether the data is appropriate for a linear model analysis.
• For analyses which consider Community cluster as the predictor variable, only those clusters that contain at least 3 minerals will be analyzed. dragon will also display a warning if the variance is not equal among clusters being compared, which can result in imprecise modeling results.
• Overall, please interpret these results with caution. We do your models, but not your science!

References

spielmanlab/dragon documentation built on Nov. 15, 2023, 3:04 a.m.