oxygraphis 0.1.6

Algorithms and structures on ecological graphs command line interface.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

# `oxygraphis`

## Introduction

A small crate and command line tool to interact with bipartite ecological graphs.

<img src="./euphrasia_hp.svg">

## CLI details

### Install

Currently you will need to clone this repository and build from source. Never fear, just download the rust toolchain. Then:

```bash
git clone https://github.com/Euphrasiologist/oxygraphis
cd oxygraphis
# install to path.
cargo install --path=.
```

### Interface

Bipartite graphs are the graph of interest. Analyse these graphs directly, or simulate them.

```bash
Usage: oxygraphis [COMMAND]

Commands:
  bipartite  Generate and analyse bipartite graphs.
  simulate   Simulate a number of graphs, and return calculations over the samples.
  help       Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help information
  -V, --version  Print version information
```

#### Bipartite graphs

The `bipartite` subcommand.

```bash
Generate and analyse bipartite graphs.

Usage: oxygraphis bipartite [OPTIONS] <INPUT_DSV> [DELIMITER] [COMMAND]

Commands:
  interaction-matrix  Coerce a bipartite graph into an interaction matrix.
  derived-graphs      Coerce a bipartite graph into two derived graphs.
  modularity          Derive the modularity of a bipartite graph.
  help                Print this message or the help of the given subcommand(s)

Arguments:
  <INPUT_DSV>  An input DSV with three headers only: from, to, and weight.
  [DELIMITER]  Specify the delimiter of the DSV; we assume tabs.

Options:
  -p, --plotbp                 Render an SVG bipartite graph plot.
  -d, --degreedistribution     Return the degree distribution of a bipartite graph.
  -b, --bivariatedistribution  Return the bivariate degree distribution of a bipartite graph.
  -h, --help                   Print help information
```

The input must be a delimited file with three columns only:

```txt
from    to    weight
Sp1    Sp2    1.0
Sp2    Sp3    1.0
Sp1    Sp3    1.0
```

And I guess should be bipartite in structure (i.e. edges only from stratum 1 -> stratum 2). A warning is issued if it isn't, but does not halt the program.

#### Derived graphs

Derived graphs are graphs which show the relationships between species in a stratum.

```bash
Coerce a bipartite graph into two derived graphs.

Usage: oxygraphis bipartite <INPUT_DSV> derived-graphs [OPTIONS]

Options:
  -p, --plotdg               Render an SVG derived graph of a stratum.
  -s, --stratum [<STRATUM>]  The stratum to display. [default: host] [possible values: host, parasite]
  -r, --remove [<REMOVE>]    Edges with fewer than this number of connections are removed from the graph. [default: 2.0]
  -h, --help                 Print help information
```

#### Interaction matrix

These form the core of some interesting bipartite analyses. Essentially an `n x m` matrix of all possible species-species interactions in the network.

```bash
Coerce a bipartite graph into an interaction matrix.

Usage: oxygraphis bipartite <INPUT_DSV> interaction-matrix [OPTIONS]

Options:
      --print   Print the inner matrix as a TSV. Mainly for debugging.
  -p, --plotim  Render an SVG interaction matrix plot.
  -n, --nodf    Compute the NODF number of a *sorted* interaction matrix.
  -h, --help    Print help information
```

#### Modularity 

An algorithm operating on the interaction matrix made from a bipartite graph. It attempts to find modules of species-host interactions in a matrix.

```bash
Derive the modularity of a bipartite graph.

Usage: oxygraphis bipartite <INPUT_DSV> modularity [OPTIONS]

Options:
  -l, --lpawbplus      Compute the modularity of a bipartite network using LPAwb+ algorithm.
  -d, --dirtlpawbplus  Compute the modularity of a bipartite network using DIRTLPAwb+ algorithm.
  -p, --plotmod        Plot the interaction matrix of a bipartite network, sorted to maximise modularity.
  -h, --help           Print help information
```

#### Simulations

A subcommand to simulate a number of random graphs (Erdös-Rényi) and execute a calculation on each.

```bash
Simulate a number of graphs, and return calculations over the samples.

Usage: oxygraphis simulate [OPTIONS] --parasitenumber <PARASITENUMBER> --hostnumber <HOSTNUMBER> --edgecount <EDGECOUNT>

Options:
      --parasitenumber <PARASITENUMBER>
          Number of parasite nodes in the graph.
      --hostnumber <HOSTNUMBER>
          Number of host nodes in the graph.
  -e, --edgecount <EDGECOUNT>
          Number of edges in the graph.
  -n, --nsims [<NSIMS>]
          Number of random samples to make. [default: 1000]
  -c, --calculation [<CALCULATION>]
          The calculation to make. [default: nodf] [possible values: nodf, lpawbplus, dirtlpawbplus, degree-distribution, bivariate-distribution]
  -h, --help
          Print help information
```

## Oxygraphis..?

*Oxygraphis* is one of only 5-6 genera in the flowering plants which have *graph* included fully in the name. It's in the Ranunculaceae.