First commit on github -- NetBunch 1.0

1 files changed, 156 insertions, 0 deletions

diff --git a/doc/f3m.1 b/doc/f3m.1
new file mode 100644
index 0000000..fb1a919
--- /dev/null
+++ b/doc/f3m.1
@@ -0,0 +1,156 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "F3M" "1" "September 2017" "www.complex-networks.net" "www.complex-networks.net"
+.
+.SH "NAME"
+\fBf3m\fR \- Count all the 3\-node subgraphs of a directed graph
+.
+.SH "SYNOPSIS"
+\fBf3m\fR \fIgraph_in\fR [\fInum_random\fR]
+.
+.SH "DESCRIPTION"
+\fBf3m\fR performs a motif analysis on \fIgraph_in\fR, i\.e\., it counts all the 3\-node subgraphs and computes the z\-score of that count with respect to the corresponding configuration model ensemble\.
+.
+.SH "PARAMETERS"
+.
+.TP
+\fIgraph_in\fR
+input graph (edge list)\. It must be an existing file\.
+.
+.TP
+\fInum_random\fR
+The number of random graphs to sample from the configuration model for the computation of the z\-score of the motifs\.
+.
+.SH "OUTPUT"
+\fBf3m\fR prints on the standard output a table with 13 rows, one for each of the 13 possible 3\-node motifs\. Each line is in the format:
+.
+.IP "" 4
+.
+.nf
+
+    motif_number  count  mean_rnd  std_rnd  z\-score
+.
+.fi
+.
+.IP "" 0
+.
+.P
+where \fBmotif_number\fR is a number between 1 and 13 that identifies the motif (see \fIMOTIF NUMBERS\fR below), \fBcount\fR is the number of subgraphs ot type \fBmotif_number\fR found in \fIgraph_in\fR, \fBmean_rnd\fR is the average number of subgraphs of type \fBmotif_number\fR in the corresponding configuration model ensemble, and \fBstd_rnd\fR is the associated standard deviation\. Finally, \fBz\-score\fR is the quantity:
+.
+.IP "" 4
+.
+.nf
+
+   (count \- mean_rnd) / std_rnd
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The program also prints a progress bar on STDERR\.
+.
+.SH "MOTIF NUMBERS"
+We report below the correspondence between the 13 possible 3\-node subgraphs and the corresponding \fBmotif_number\fR\. In the diagrams, \'O\-\-\->O\' indicates a single edge form the left node to the right node, while \'O\fI==\fRO\' indicates a double (bi\-directional) edge between the two nodes:
+.
+.IP "" 4
+.
+.nf
+
+   (1)  O<\-\-\-O\-\-\->O
+
+   (2)  O\-\-\->O\-\-\->O
+
+   (3)  O<==>O\-\-\->O
+
+   (4)  O\-\-\->O<\-\-\-O
+
+   (5)  O\-\-\->O\-\-\->O
+         \e        ^
+          \e_______|
+
+   (6)  O<==>O\-\-\->O
+         \e        ^
+          \e_______|
+
+   (7)  O<==>O<\-\-\-O
+
+   (8)  O<==>O<==>O
+
+   (9)  O<\-\-\-O<\-\-\-O
+         \e        ^
+          \e_______|
+
+  (10)  O<==>O<\-\-\-O
+         \e        ^
+          \e_______|
+
+  (11)  O\-\-\->O<==>O
+         \e        ^
+          \e_______|
+
+  (12)  O<==>O<==>O
+         \e        ^
+          \e_______|
+
+  (13)  O<==>O<==>O
+        ^\e       ^/
+         \e\e_____//
+          \e_____/
+.
+.fi
+.
+.IP "" 0
+.
+.SH "EXAMPLES"
+To perform a motif analysis on the E\.coli transcription regulation graph, using 1000 randomised networks, we run the command:
+.
+.IP "" 4
+.
+.nf
+
+    $ f3m e_coli\.net 1000
+    1          4760         4400\.11    137\.679     +2\.614
+    2           162          188\.78      8\.022     \-3\.338
+    3             0            0\.89      3\.903     \-0\.228
+    4           226          238\.32      7\.657     \-1\.609
+    5            40            6\.54      2\.836    +11\.800
+    6             0            0\.01      0\.077     \-0\.078
+    7             0            0\.12      0\.642     \-0\.192
+    8             0            0\.00      0\.032     \-0\.032
+    9             0            0\.01      0\.109     \-0\.110
+    10            0            0\.00      0\.000     +0\.000
+    11            0            0\.00      0\.032     \-0\.032
+    12            0            0\.00      0\.000     +0\.000
+    13            0            0\.00      0\.000     +0\.000
+    $
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Notice that the motif \fB5\fR (the so\-called "feed\-forward loop") has a z\-score equal to 11\.8, meaning that it is highly overrepresented in the E\.coli graph with respect to the corresponding configuration model ensemble\. Conversely, the motif \fB2\fR (three\-node chain) is underrepresented, as made evident by value of the z\-score (\-3\.338)\.
+.
+.SH "SEE ALSO"
+johnson_cycles(1)
+.
+.SH "REFERENCES"
+.
+.IP "\(bu" 4
+R\. Milo et al\. "Network Motifs: Simple Building Blocks of Complex Networks"\. Science 298 (2002), 824\-827\.
+.
+.IP "\(bu" 4
+R\. Milo et al\. "Superfamilies of evolved and designed networks\." Science 303 (2004), 1538\-1542
+.
+.IP "\(bu" 4
+V\. Latora, V\. Nicosia, G\. Russo, "Complex Networks: Principles, Methods and Applications", Chapter 8, Cambridge University Press (2017)
+.
+.IP "\(bu" 4
+V\. Latora, V\. Nicosia, G\. Russo, "Complex Networks: Principles, Methods and Applications", Appendix 16, Cambridge University Press (2017)
+.
+.IP "" 0
+.
+.SH "AUTHORS"
+(c) Vincenzo \'KatolaZ\' Nicosia 2009\-2017 \fB<v\.nicosia@qmul\.ac\.uk>\fR\.