---
title: "GREMLINS. Quick Mathematical Background"
author: "Sophie Donnet, Pierre Barbillon"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 4
bibliography: biblio.bib
link-citations: yes
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{GREMLINS. Quick Mathematical Background}
  %\VignetteEncoding{UTF-8}
---


<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```


<!-- badges: start -->
<!-- badges: end -->

The goal of GREMLINS is to perform statistical analysis of multipartite networks through a block model approach. 

Multipartite networks  consist in the joint observation of several networks implying some common individuals. The individuals (or entities represented by nodes)  at stake are partitioned into groups defined by their nature.
In what follows, these groups will be referred to as  **functional groups**.




```{r packages, echo = TRUE, eval=TRUE}
library(GREMLINS)
```


## Mathematical Background

The model is introduced and described in @Donnet. 

###  A collection of networks

Assume that $Q$ functional groups of individuals are at stake.  **A multipartite network is a collection of networks**,  each of them implying one or two functional group. Thus, each network may be 

         - *simple* if it represents the relations inside  a   functional   group  
         - *bipartite* if it represent the relations between individuals of two  functional groups. 
         
We index the collection of networks by pairs of functional groups $(q,q')$. The set $E$ denotes  the  list of pairs of  functional groups  for   which we observe an interaction network.

For any pair $(q,q') \in E$, **the interaction network is encoded in a matrix  $X^{qq'}$ **  such that  $X^{qq'}_{ii'} \neq 0$ if there is an edge from unit $i$ of functional group
$q$ to unit $i'$ of functional group $q'$, $X^{qq'}_{ii'} = 0$ otherwise.

For any $(q,q')$, $X^{qq'}_{ii'}$ may be in $\{0,1\}$ or a numeric for weigthed networks. 

Note that,  if $q \neq q'$,   $X^{qq'}$ is  said to be  an **incidence matrix** (corresponding to a bipartite network). If $q = q'$, $X^{qq}$ is  an  **adjacency matrix**. Moreover, if the relation inside the functional group $q$  is non-oriented, $X^{qq}$ is symmetric. 

### A probabilistic latent variables model

Let $n_q$ be  the number of individuals  in the $q$-th functional group.
Assume that,   each functional group $q$  is  divided into $K_q$  **blocks  or equivalently clusters**.  $\forall q$ and  $\forall i$, let $Z^{q}_i$ be
the latent random variable  such that $Z^ q_i =k$  if individual $i$ of functional group $q$ belongs to cluster $k$.
The random variables $Z^{q}_i$'s are assumed to be independent and  such that: $\forall (i,k,q) \in   \{1,\dots,n_q\} \times \{1,\dots,K_q\} \times  \{1,\dots,Q\}$:

\begin{equation}\label{eq:mod2}
\mathbb{P}(Z^{q}_i=k) = \pi^{q}_k,
\end{equation}
with $\sum_{k=1}^{K_q}\pi^{q}_k=1$,  $\forall q=1,\dots, Q$.



Conditionally on the clustering,  the entries of the matrices   $\left(X^{qq'}_{ii'}\right)$ are assumed to be independent and distributed as follows:
$\forall (i,i')  \in \{1,\dots,n_q\} \times  \{1,\dots,n_{q'}\}$,
\begin{equation}\label{eq:mod1}
X^{qq'}_{ii'}\;  |  \; Z^{q}_i=k, Z^{q'}_{i'}=k'   \sim_{i.i.d} \mathcal{F}_{qq'}(\theta^{qq'}_{kk'})\,
\end{equation}
meaning that the probability of connection from $i$  of functional group $q$ to  $i'$ of functional group $q'$ only  depends on the clusters to which they belong to.

For any pair $(q,q')$, $\mathcal{F}_{qq'}(\cdot)$ is either: 

    - Bernoulli, resulting into binary interactions
    
    - Poisson for weighted networks of counts
    
    - Gaussian or Laplace for continuous weighted networks. 
As a consequence, the collection of networks may contain weighted and/or binary networks.  

### Statistical inference


The inference of the model consists in the selection of the numbers of clusters $(K_q)_{q=1,\dots,Q}$ and the estimation of the parameters $(\theta_{qq'})$. The model selection is performed with the ICL, a penalized likelihood criterion. The parameters are estimated with a varitional version of the EM algorithm. The estimation procedure also provides a clustering of the entities at stake. 




## References

.
