# Modularity

The analysis of network modularity is done in three steps:

- generate a starting point, using one of the starter functions
- optimize modularity
- analyse the output

All starter functions take a network as input, and return a tuple of this network and a dictionary where every species maps onto its module. This forms the input of all other modularity related functions.

## Measures

`EcologicalNetworks.Q`

— Function`Q(N::T, L::Dict{E,Int64}) where {T<:AbstractEcologicalNetwork,E}`

Modularity of a network and its partition. The second argument is a dictionary where every species of `N`

is associated to an `Int64`

value representing the identity of the module. This function returns the same value of bipartite networks and their unipartite projection.

**References**

Barber, M.J., 2007. Modularity and community detection in bipartite networks. Phys. Rev. E 76, 066102. https://doi.org/10.1103/PhysRevE.76.066102

Newman, M.E., 2006. Modularity and community structure in networks. Proceedings of the national academy of sciences 103, 8577–8582.

`EcologicalNetworks.Qr`

— Function`Qr(N::T, L::Dict{E,Int64}) where {T<:AbstractEcologicalNetwork,E}`

Realized modularity – this function returns a value giving the proportion of all links that are within the same module. Higher values reflect a more strongly modular partition (whereas `Q`

represents the deviation of modularity from the random expectation).

**References**

- Poisot, T., 2013. An a posteriori measure of network modularity. F1000Research
- https://doi.org/10.12688/f1000research.2-130.v3

## Starters

`EcologicalNetworks.n_random_modules`

— Function`n_random_modules(n::Int64)`

This returns *a function* which, when applied to a network, will randomly assign every species to one of `n`

modules. The correct way to apply this function to a network `N`

is, therefore `n_random_modules(4)(N)`

(with four modules).

**References**

Thébault, E., 2013. Identifying compartments in presence–absence matrices and bipartite networks: insights into modularity measures. Journal of Biogeography 40, 759–768. https://doi.org/10.1111/jbi.12015

`EcologicalNetworks.each_species_its_module`

— Function`each_species_its_module(N::T) where {T<:AbstractEcologicalNetwork}`

Returns a dictionary in which each species is its own module. This is used as a starting point for `lp`

and `salp`

internally. This is often a very poor starting point for `brim`

, and should probably not be used on its own.

**References**

Thébault, E., 2013. Identifying compartments in presence–absence matrices and bipartite networks: insights into modularity measures. Journal of Biogeography 40, 759–768. https://doi.org/10.1111/jbi.12015

`EcologicalNetworks.lp`

— Function`lp(N::T) where {T<:AbstractEcologicalNetwork}`

Uses label propagation to generate a first approximation of the modular structure of a network. This is usually followed by the BRIM (`brim`

) method. This method supposedly performs better for large graphs, but we rarely observed any differences between it and variations of BRIM alone on smaller graphs.

**References**

Liu, X., Murata, T., 2009. Community Detection in Large-Scale Bipartite Networks, in: 2009 IEEE/WIC/ACM International Joint Conference on Web Intelligence and Intelligent Agent Technology. Institute of Electrical & Electronics Engineers (IEEE). https://doi.org/10.1109/wi-iat.2009.15

## Optimizers

`EcologicalNetworks.brim`

— Function`brim(N::NT, L::Dict{E,Int64}) where {NT<:AbstractEcologicalNetwork,E}`

Uses BRIM to optimize the modularity of an ecological network. The `L`

argument is a dictionary mapping every species in the network to its module. This function returns a tuple of the network and its module assignment.

**References**

Barber, M.J., 2007. Modularity and community detection in bipartite networks. Phys. Rev. E 76, 066102. https://doi.org/10.1103/PhysRevE.76.066102

Newman, M.E., 2006. Modularity and community structure in networks. Proceedings of the national academy of sciences 103, 8577–8582.

Thébault, E., 2013. Identifying compartments in presence–absence matrices and bipartite networks: insights into modularity measures. Journal of Biogeography 40, 759–768. https://doi.org/10.1111/jbi.12015

`EcologicalNetworks.salp`

— Function`salp(N::T; θ::Float64=1.0, steps::Int64=10_000, λ::Float64=0.999, progress::Bool=false) where {T <: BipartiteNetwork}`

Label-propagation using simulated annealing. This function uses simulated annealing to propagate labels from neighboring nodes. It accepts a network as input. The schedule of the simulated annealing is linear: at step k+1, the temperature is θλᵏ. The initial temperature has been picked so that after 100 timesteps, using the default λ, a move decreasing modularity by 0.05 (20% of the theoretical maximum) is picked with a probability of 0.1.

Optional arguments regulating the behavior of the simulated annealing routine are:

`λ=0.999`

, the rate of temperature decay`θ=0.002`

, the initial temperature`steps=10_000`

, the number of annealing steps to perform`progress=false`

, whether to display an info message every 100 timesteps

The θ parameter can be picked using the following method: if we want to allow a maximal loss of modularity of δ, after timestep k, with a decay parameter λ, with a probability P, then θ = -δ/[λᵏ×ln(P)]⁻¹. By beibg more or less restrictive on these parameters, the user can pick a value of θ for every problem.

This function can work as a first step (like `lp`

), but in explorations during the development of the package, we found that `brim`

was rarely (if ever) able to optmize the output further. It can therefore be used on its own.

## Functional roles

`EcologicalNetworks.functional_cartography`

— Function`functional_cartography(N::T, L::Dict{E,Int64}) where {T<:BinaryNetwork, E}`

This function will take the output of a modularity analysis (*i.e.* a network and a partition), and return a dictionary where every species is associated to its functional role, as defined in Olesen et al (2005). The first element is the within-module degree z-score, and the second is the participation coefficient.

**References**

Guimerà, R., Amaral, L.A.N., 2005. Cartography of complex networks: modules and universal roles. Journal of Statistical Mechanics: Theory and Experiment 2005, P02001. https://doi.org/10.1088/1742-5468/2005/02/P02001

Guimerà, R., Nunes Amaral, L.A., 2005. Functional cartography of complex metabolic networks. Nature 433, 895–900. https://doi.org/10.1038/nature03288

Olesen, J.M., Bascompte, J., Dupont, Y.L., Jordano, P., 2007. The modularity of pollination networks. Proceedings of the National Academy of Sciences 104, 19891–19896. https://doi.org/10.1073/pnas.0706375104