---
title: "Getting Started with rnetcarto"
author: "Guilhem Doulcier"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with rnetcarto}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

``` {r, echo=FALSE, results="hide"}
	library(rnetcarto)
	require("igraph")
```

# Rnetcarto in 60 seconds.

Rnetcarto provides fast network modularity and roles computation by
simulated annealing
([rgraph C library](https://github.com/seeslab/rgraph) wrapper for
R). 

It exposes one main command named `netcarto` that take a graph as an
input (formatted as an **adjacency matrix** or **list**, as described
in more detail below) and returns a partition of the graph optimizing
a given modularity criterion. It also computes the modularity roles of
the nodes.

Here is a small example:

``` {r, echo=TRUE}
 # Generate a simple random network
 a = matrix(as.integer(runif(100)<.3), ncol=10) 
 a[lower.tri(a)] = 0
 rownames(a) = c('a','b','b','c','d','e','f','g','h','i')
 colnames(a) = rownames(a)
 # Find an optimal partition for modularity using netcarto.
 #  The output consists in a table containing node properties,
 #  and the modularity value of the partition.
 netcarto(a)
```

# Input: How should I format my data?

The `netcarto` function can read network in either adjacency matrix or
adjacency list format.

## Matrix format
square symmetric matrix. In this format, the weight $w$ of an between
If you choose the **matrix format**, your network must consist in a
vertices $i$ and $j$ is given by the corresponding value in the matrix
`web[i,j]`. Auto-loop (i.e. diagonal terms are authorised). You may name the rows and/or
columns, those names will be used in the function output.  Example:



### Example 1: Triplet
``` {r, echo=TRUE}
    input = matrix(0,3,3)
    input[1,2] = 1
    input[2,3] = 1
    input[3,1] = 1
	input[2,1] = 1
    input[3,2] = 1
    input[1,3] = 1
    rownames(input) = c("A","B","C")
    colnames(input) = rownames(input)
	print(input)
```

Note that `igraph` package can be used to manipulate and plot graphs:
``` {r, echo=TRUE}
    # import from rnetcarto matrix format to igraph:
    G = igraph::graph.adjacency(input,weighted=TRUE,mode="undirected")
    # Export to a matrix compatible with netcarto:
	input = igraph::get.adjacency(G,sparse=FALSE)
```

``` {r, echo=FALSE}
	plot(G, layout = igraph::layout.circle, ,
       vertex.size = 60,
       vertex.color="red",
       vertex.frame.color= "white",
       vertex.label.color = "white",
       vertex.label.family = "sans",
       edge.width=1,
       edge.color="black")
```

### Example 2: Two triplets
``` {r, echo=TRUE}
    input = matrix(0,7,7)
    input[1,2] = 10
    input[2,3] = 10
    input[3,1] = 10
    input[4,5] = 10
    input[5,6] = 10
    input[6,4] = 10
    rownames(input) = c("A","B","C","D","E","F","G")
    colnames(input) = rownames(input)
```

Note that:

- Empty columns and lines are removed (Here `G`).
- If the matrix is not symmetric, symmetry will be enforced by taking
  `web = web+t(web)-diag(web)`

So the previous matrix is equivalent to:

``` {r, echo=FALSE}
    input = matrix(0,6,6)
    input[1,2] = 10
    input[2,3] = 10
    input[3,1] = 10
    input[4,5] = 10
    input[5,6] = 10
    input[6,4] = 10
	input = input+t(input)-diag(input)
    rownames(input) = c("A","B","C","D","E","F")
    colnames(input) = rownames(input)
	print(input)
```


``` {r, echo=FALSE}
    G = igraph::graph.adjacency(input,weighted=TRUE,mode="undirected")
	plot(G, layout = layout.circle, ,
       vertex.size = 60,
       vertex.color="red",
       vertex.frame.color= "white",
       vertex.label.color = "white",
       vertex.label.family = "sans",
       edge.width=1,
       edge.color="black")
```

### Example 3: Bipartite triplets
Note that the matrix *may* not be square and symmetric *if and only
if* you are considering a bipartite network (using the `bipartite`
flag).


``` {r, echo=TRUE}
    input = matrix(0,6,2)
    input[1,1] = 1
    input[2,1] = 1
    input[3,1] = 1
    input[4,2] = 1
    input[5,2] = 1
    input[6,2] = 1
    rownames(input) = c("A","B","C","D","E","F")
    colnames(input) = c("Team 1", "Team 2")
	print(input)
```


## List format
If you choose the **list format**, your network must be formatted as a
R-list. The first element must be a vector giving the label. The third
element is a vector of the edge weights. The weights are optional and
are all set to one if the list contains only the first two
elements.

### Example 1: Unweighted network:

``` {r, echo=TRUE}
    nd1 = c("A","B","C","D","E","F","C")
    nd2 = c("B","C","A","E","F","D","D")
	web = list(nd1,nd2,weights)
    print(list(nd1,nd2))
```

### Example 2: Weighted network
``` {r, echo=TRUE}
    nd1 = c("A","B","C","D","E","F","C","A")
    nd2 = c("B","C","A","E","F","D","D","D")
	weights = c(10,10,10,10,10,10,10,10,1)
	web = list(nd1,nd2,weights)
    print(web)
```

### Example 3: Bipartite network

``` {r, echo=TRUE}
    nd1 = c("A","B","C","D","E","F","C","A")
    nd2 = c("Team1","Team2","Team1","Team1","Team2","Team1","Team1","Team2")
	bipartite = list(nd1,nd2)
    print(bipartite)
```
	
# Output: How should I read the result?

The `netcarto` command output a list. Its first element is a dataframe
giving the name module, connectivity, and participation coefficient for
each node of the input graph. The second element is the modularity
of this optimal partition.

### Example 1: Weighted network

``` {r, echo=TRUE}
    netcarto(igraph::get.adjacency(G,sparse=FALSE))
```

### Example 2: Bipartite network


``` {r, echo=TRUE}
   netcarto(bipartite, bipartite=TRUE)
```