Merge pull request #16 from solislemuslab/develop

MiNAA v1.2.0

Author: reednel

.github/workflows/draft-pdf.yml

@@ -14,7 +14,7 @@ jobs:
           # This should be the path to the paper within your repo.
           paper-path: paper/paper.md
       - name: Upload
-        uses: actions/upload-artifact@v1
+        uses: actions/upload-artifact@v4
         with:
           name: paper
           # This is the output path where Pandoc will write the compiled

README.md

@@ -1,8 +1,8 @@
 # MiNAA: Microbiome Network Alignment Algorithm
 
-<img src="logo.png" style="width:40%;" align=right>
+<img src="img/logo.png" style="width:40%;" align=right>
 
-[![GitHub Releases](https://img.shields.io/github/v/release/solislemuslab/minaa?display_name=tag)](https://github.com/solislemuslab/minaa/releases) [![GitHub license](https://img.shields.io/github/license/solislemuslab/minaa)](https://github.com/solislemuslab/minaa/blob/main/LICENSE) [![GitHub Issues](https://img.shields.io/github/issues/solislemuslab/minaa)](https://github.com/solislemuslab/minaa/issues) ![ ](https://img.shields.io/github/languages/code-size/solislemuslab/minaa) [![status](https://joss.theoj.org/papers/b4d9f26021065b1759d50413f60aa9c3/status.svg)](https://joss.theoj.org/papers/b4d9f26021065b1759d50413f60aa9c3)
+[![GitHub Releases](https://img.shields.io/github/v/release/solislemuslab/minaa?display_name=tag)](https://github.com/solislemuslab/minaa/releases) [![GitHub license](https://img.shields.io/github/license/solislemuslab/minaa?color=yellow)](https://github.com/solislemuslab/minaa/blob/main/LICENSE) [![GitHub Issues](https://img.shields.io/github/issues/solislemuslab/minaa)](https://github.com/solislemuslab/minaa/issues) ![ ](https://img.shields.io/github/languages/code-size/solislemuslab/minaa?color=white) [![status](https://joss.theoj.org/papers/b4d9f26021065b1759d50413f60aa9c3/status.svg)](https://joss.theoj.org/papers/b4d9f26021065b1759d50413f60aa9c3)
 
 ## Description
 
@@ -64,6 +64,10 @@ This utility has the form `./minaa.exe <G> <H> [-B=bio] [-a=alpha] [-b=beta]`.
 - **-st=**: similarity threshold; The similarity value above which aligned pairs are included in the output.
   - Require: a real number in range [0, 1].
   - Default: 0.
+- **-c**: conserved subgraphs; whether or not to output a list of the conserved subgraphs in the alignment between G and H.
+  - Require: none.
+  - Default: this list is not calculated or returned.
+  - Note: We define a conserved subgraph as a connected subgraph of G whose nodes are aligned to a connected subgraph of H. See the Examples section for a visual.
 
 #### Uncommon
 
@@ -105,6 +109,12 @@ This utility has the form `./minaa.exe <G> <H> [-B=bio] [-a=alpha] [-b=beta]`.
 
 ### Examples
 
+<img src="img/conserved_subgraph.png" style="width:60%;" align=center>
+
+On the left are adjacency matrices for simple networks G and H, and an imagined **alignment matrix** as returned by MiNAA. On the right is a visual depiction of G overlaying H, and the connected purple graph is what we call a **conserved subgraph** in the alignment of G and H. We color a node purple if that node in G is aligned to a node in H, and we color an edge purple if a pair of adjacent nodes in G are also adjacent in the nodes they're aligned to in H. Note that the blue edge, red edge, and red node `e` are not considered part of this conserved subgraph.
+
+#### Example Execution
+
 Examples of MiNAA's usage with real data and in-depth explanations can be found in the `examples/` directory.
 
 ## Simulations in the Manuscript
@@ -117,7 +127,7 @@ Users interested in expanding functionalities in MiNAA are welcome to do so. Iss
 
 ## License
 
-MiNAA is licensed under the [MIT](https://opensource.org/licenses/MIT) license. &copy; SolisLemus lab (2024).
+MiNAA is licensed under the [MIT](https://opensource.org/licenses/MIT) license. &copy; Solis-Lemus Lab (2024).
 
 ## Citation
 

examples/README.md

@@ -10,27 +10,49 @@ Once MiNAA is successfully compiled, the examples below can be run from this pro
 
 ## Example 1
 
-`./minaa.exe examples/g.csv examples/h.csv -a=0.6 -g`
+```bash
+./minaa.exe examples/g.csv examples/h.csv -a=0.6 -g
+```
 
 Output to: `g-h-a0.6/`
 
 Here we align network **g** with network **h** using no biological data. `-a=0.6` sets alpha equal to 0.6, meaning 60% of the topological cost function comes from similarity calculated by GDVs, and 40% from simpler node degree data.
 
 ## Example 2
 
-`./minaa.exe examples/g.csv examples/h.csv -B=examples/bio.csv -b=0.85 -st=0.5 -s`
+```bash
+./minaa.exe examples/g.csv examples/h.csv -B=examples/bio.csv -b=0.85 -st=0.5 -s
+```
 
 Output to: `g-h/`
 
 Here we align network **g** with network **h** using topological information and the given biological similarity matrix, **bio**. Since we've provided a similarity matrix instead of a cost matrix (the default), we have to flag that with `-s`. Since alpha was unspecified, it defaults to 1. Since beta was set to 0.85, 85% of the cost weight is from the calculated topological cost matrix, and 15% is from **bio**. Since the similarity threshold `-st=` was set to 0.5, any aligned pair with similarity score less than or equal to 0.5 is excluded from the alignment results.
 
 ## Example 3
 
-`./minaa.exe examples/g.csv examples/h.csv -Galias=nonsmoker -Halias=smoker -p -t`
+```bash
+./minaa.exe examples/g.csv examples/h.csv -Galias=nonsmoker -Halias=smoker -p -t -c
+```
 
 Output to: `nonsmoker-smoker-2024_01_16-22_05_34/`
 
-Here we align network **g** with network **h**, where **g** is given the alias "nonsmoker", and **h** is given the alias "smoker". The timestamp option `-t` was specified, so the name of the output folder will be nonsmoker-smoker-T, where T is the date and time of execution. Additionally, because the passthrough option `-p` was specified, g.csv and h.csv will be passed through to the output folder as nonsmoker.csv and smoker.csv, respectively.
+Here we align network **g** with network **h**, where **g** is given the alias "nonsmoker", and **h** is given the alias "smoker". The timestamp option `-t` was specified, so the name of the output folder will be nonsmoker-smoker-T, where T is the date and time of execution. Because the passthrough option `-p` was specified, g.csv and h.csv will be passed through to the output folder as nonsmoker.csv and smoker.csv, respectively. Finally, because the `-c` option was specified, the output folder will include the alignment's conserved subgraphs, in a file called `conserved_subgraphs.csv`.
+
+## Example 4
+
+```R
+source("plot_alignment.R")
+plot_alignment(
+    g_filepath = "examples/g.csv",
+    h_filepath = "examples/h.csv",
+    alignment_filepath = "examples/g-h/alignment_matrix.csv",
+    output_filepath = "examples/g-h/plot.png",
+    st = 0.5,
+    hide_singletons = TRUE
+)
+```
+
+This is an example execution in R of the alignment visualization script `plot_alignment.R`. The resulting `plot.png` is in `examples/g-h/`.
 
 ## Attributions
 

examples/g-h/plot.png

@@ -0,0 +1,128 @@
+"g1","h146"
+
+"g6","h5"
+
+"g7","h161"
+
+"g8","h138"
+"g167","h134"
+
+"g12","h124"
+
+"g13","h43"
+"g126","h121"
+
+"g14","h171"
+
+"g16","h96"
+
+"g17","h14"
+"g74","h74"
+"g82","h71"
+"g23","h81"
+"g81","h23"
+"g90","h90"
+"g71","h17"
+"g70","h70"
+"g58","h13"
+
+"g19","h25"
+
+"g20","h128"
+"g28","h87"
+
+"g22","h160"
+
+"g24","h162"
+
+"g30","h130"
+
+"g32","h122"
+"g45","h156"
+"g42","h145"
+
+"g35","h135"
+"g155","h120"
+"g164","h60"
+"g112","h109"
+"g92","h68"
+"g51","h104"
+
+"g37","h110"
+
+"g43","h56"
+
+"g46","h155"
+
+"g52","h127"
+
+"g53","h63"
+"g68","h142"
+
+"g54","h123"
+
+"g56","h118"
+
+"g59","h152"
+
+"g63","h129"
+
+"g65","h7"
+
+"g73","h115"
+
+"g91","h55"
+
+"g95","h153"
+
+"g103","h117"
+
+"g105","h132"
+
+"g106","h107"
+
+"g108","h28"
+
+"g109","h93"
+
+"g115","h72"
+
+"g116","h169"
+
+"g119","h103"
+
+"g120","h101"
+
+"g123","h73"
+
+"g125","h157"
+
+"g128","h173"
+"g157","h6"
+
+"g130","h102"
+
+"g131","h51"
+
+"g133","h32"
+
+"g137","h174"
+
+"g139","h30"
+
+"g142","h31"
+
+"g150","h22"
+
+"g154","h21"
+
+"g166","h18"
+
+"g169","h125"
+
+"g172","h44"
+
+"g173","h106"
+
+"g174","h137"
+

examples/nonsmoker-smoker-2024_01_16-23_10_14/conserved_subgraphs.csv

@@ -21,6 +21,7 @@ namespace FileIO
     void matrix_to_file(std::string, std::vector<std::string>, std::vector<std::string>, std::vector<std::vector<double>>);
     void alignment_to_matrix_file(std::string, std::vector<std::string>, std::vector<std::string>, std::vector<std::vector<double>>, double);
     void alignment_to_list_file(std::string, std::vector<std::string>, std::vector<std::string>, std::vector<std::vector<double>>, double);
+    void subgraphs_to_file(std::string, std::vector<std::string>, std::vector<std::string>, std::vector<std::vector<std::pair<unsigned, unsigned>>>);
 }
 
 #endif

img/conserved_subgraph.png

@@ -10,6 +10,7 @@ namespace Util
     std::vector<std::vector<double>> normalize(std::vector<std::vector<double>>);
     std::vector<std::vector<double>> one_minus(std::vector<std::vector<double>>);
     std::vector<std::vector<double>> combine(std::vector<std::vector<double>>, std::vector<std::vector<double>>, double);
+    std::vector<std::vector<std::pair<unsigned, unsigned>>> conserved_subgraphs(std::vector<std::vector<unsigned>>, std::vector<std::vector<unsigned>>, std::vector<std::vector<double>>, double);
 }
 
 #endif

logo.png img/logo.png

@@ -0,0 +1,145 @@
+plot_alignment <- function(
+    g_filepath,
+    h_filepath,
+    alignment_filepath,
+    output_filepath,
+    st = 0,
+    hide_singletons = FALSE
+) {
+    # # Load necessary libraries
+    # required_packages <- c("igraph", "ggraph", "ggplot2", "readr", "dplyr")
+    # installed_packages <- rownames(installed.packages())
+    # for (pkg in required_packages) {
+    #     if (!pkg %in% installed_packages) {
+    #         install.packages(pkg, dependencies = TRUE)
+    #     }
+    # }
+
+    library(igraph)
+    library(ggraph)
+    library(ggplot2)
+    library(readr)
+    library(dplyr)
+
+    # Helper function to read adjacency matrix
+    read_adjacency <- function(filepath) {
+        df <- read_csv(filepath, show_col_types = FALSE)
+        mat <- as.matrix(df[, -1])
+        rownames(mat) <- df[[1]]
+        return(mat)
+    }
+
+    # Read adjacency matrices
+    g_mat <- read_adjacency(g_filepath)
+    h_mat <- read_adjacency(h_filepath)
+
+    # Create igraph objects (assuming undirected graphs; adjust 'mode' if needed)
+    g_graph <- graph_from_adjacency_matrix(g_mat, mode = "undirected", diag = FALSE)
+    h_graph <- graph_from_adjacency_matrix(h_mat, mode = "undirected", diag = FALSE)
+
+    # Read alignment matrix
+    alignment_df <- read_csv(alignment_filepath, show_col_types = FALSE)
+    alignment_mat <- as.matrix(alignment_df[, -1])
+    rownames(alignment_mat) <- alignment_df[[1]]
+
+    # Extract alignment pairs with similarity > the similarity threshold
+    alignment_pairs <- which(alignment_mat > st, arr.ind = TRUE)
+    align_df <- data.frame(
+        g_node = rownames(alignment_mat)[alignment_pairs[, 1]],
+        h_node = colnames(alignment_mat)[alignment_pairs[, 2]],
+        similarity = alignment_mat[alignment_pairs]
+    )
+
+    if (hide_singletons) {
+        # Remove nodes in G and H with degree 0
+        deg_g <- degree(g_graph)
+        non_single_g <- names(deg_g[deg_g > 0])
+        g_graph <- induced_subgraph(g_graph, vids = non_single_g)
+
+        deg_h <- degree(h_graph)
+        non_single_h <- names(deg_h[deg_h > 0])
+        h_graph <- induced_subgraph(h_graph, vids = non_single_h)
+
+        # Update alignment_df to include only existing nodes after subsetting
+        align_df <- align_df %>%
+            filter(g_node %in% V(g_graph)$name & h_node %in% V(h_graph)$name)
+    }
+
+    # Rename nodes to ensure uniqueness
+    V(g_graph)$name <- paste0("G_", V(g_graph)$name)
+    V(h_graph)$name <- paste0("H_", V(h_graph)$name)
+
+    combined_graph <- disjoint_union(g_graph, h_graph)
+
+    # Prepare alignment edges
+    if (nrow(align_df) > 0) {
+        align_edges <- align_df %>%
+            mutate(
+                from = paste0("G_", g_node),
+                to = paste0("H_", h_node)
+            )
+    } else {
+        align_edges <- data.frame(from = character(0), to = character(0), similarity = numeric(0))
+    }
+
+    # Create a layout with G on the left and H on the right
+    set.seed(123) # For reproducibility
+    layout_g <- layout_with_fr(g_graph)
+    layout_h <- layout_with_fr(h_graph)
+
+    # Shift H layout to the right of G
+    shift_x <- max(layout_g[, 1]) - min(layout_h[, 1]) + 5
+    layout_h[, 1] <- layout_h[, 1] + shift_x
+
+    # Combine layouts
+    combined_layout <- rbind(layout_g, layout_h)
+    V(combined_graph)$x <- combined_layout[, 1]
+    V(combined_graph)$y <- combined_layout[, 2]
+
+    # Prepare data for alignment edges
+    if (nrow(align_edges) > 0) {
+        align_coords <- align_edges %>%
+            mutate(
+                from_x = V(combined_graph)$x[match(from, V(combined_graph)$name)],
+                from_y = V(combined_graph)$y[match(from, V(combined_graph)$name)],
+                to_x = V(combined_graph)$x[match(to, V(combined_graph)$name)],
+                to_y = V(combined_graph)$y[match(to, V(combined_graph)$name)]
+            )
+    }
+
+    # Plot #
+    
+    # Adjust the plot size based on the number of nodes
+    num_nodes <- vcount(combined_graph)
+    plot_width <- max(2000, 100 + 20 * num_nodes)
+    plot_height <- max(1000, 100 + 10 * num_nodes)
+
+    png(filename = output_filepath, width = plot_width, height = plot_height, res = 150)
+
+    p <- ggraph(combined_graph, layout = "manual", x = V(combined_graph)$x, y = V(combined_graph)$y) +
+        # Internal edges within G and H
+        geom_edge_link(aes(alpha = 0.5), color = "grey", linewidth = 0.5) +
+        # G nodes in red, H in blue
+        geom_node_point(aes(color = ifelse(startsWith(name, "G_"), "G", "H")), size = 3) +
+        # Node labels without the prefix
+        geom_node_text(aes(label = gsub("^[GH]_", "", name)), repel = TRUE, size = 3)
+        # Color mapping
+        scale_color_manual(values = c("G" = "red", "H" = "blue")) +
+        theme_void() +
+        theme(legend.position = "none")
+
+    if (nrow(align_edges) > 0) {
+        # Add alignment edges
+        p <- p +
+            geom_segment(
+                data = align_coords,
+                aes(x = from_x, y = from_y, xend = to_x, yend = to_y),
+                color = "purple", linewidth = 0.5, alpha = 0.6
+            )
+    }
+
+    print(p)
+    dev.off()
+
+    message("Plot saved to ", output_filepath)
+}