README.Rmd

---
output: github_document
---

<!-- 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%"
)
```

# netmem: Network Measures using Matrices <img src="man/figures/logo.png" align="right" width="180px"/>

<!-- badges: start --> 
[![CRAN status](https://www.r-pkg.org/badges/version/netmem)](https://CRAN.R-project.org/package=netmem)
[![r-universe status badge](https://anespinosa.r-universe.dev/badges/netmem)](https://anespinosa.r-universe.dev/netmem)
[![](https://img.shields.io/badge/devel%20version-1.0--3-red.svg)](https://github.com/https://github.com/anespinosa/netmem)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
[![Codecov test coverage](https://codecov.io/gh/anespinosa/netmem/branch/master/graph/badge.svg)](https://codecov.io/gh/anespinosa/netmem?branch=master)
[![CodeFactor](https://www.codefactor.io/repository/github/anespinosa/netmem/badge)](https://www.codefactor.io/repository/github/anespinosa/netmem)
[![AppVeyor build status](https://ci.appveyor.com/api/projects/status/github/anespinosa/netmem?branch=master&svg=true)](https://ci.appveyor.com/project/anespinosa/netmem)
[![R-CMD-check](https://github.com/anespinosa/netmem/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/anespinosa/netmem/actions/workflows/R-CMD-check.yaml)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Github All Releases](https://img.shields.io/github/downloads/anespinosa/netmem/total.svg)]()
<!-- badges: end -->

The goal of [`netmem`](https://anespinosa.github.io/netmem/) is to make
available different measures to analyse and manipulate complex networks using
matrices.

`r emo::ji("pen")` Author/mantainer: [Alejandro
Espinosa-Rada](https://github.com/anespinosa)

`r emo::ji("school")` [Social Networks Lab ETH Zürich](https://sn.ethz.ch)

[![Follow me on Twitter](https://img.shields.io/badge/Follow me on
Twitter-9cf.svg)](https://twitter.com/aespinosarada)

The package implements different measures to analyse and manipulate complex
multilayer networks, from an ego-centric perspective, considering one-mode
networks, valued ties (i.e. *weighted* or *multiplex*) or with multiple levels.

## Citation

```{r echo=FALSE, results='asis'}
citation(package = "netmem")
```

## Functions currently available in [`netmem`](https://anespinosa.github.io/netmem/reference/index.html):

Utilities:

1. `matrix_report()`: Matrix report

2. `matrix_adjlist()`: Transform a matrix into an adjacency list

3. `matrix_projection()`: Unipartite projections

4. `matrix_to_edgelist()`: Transform a square matrix into an edge-list

5. `adj_to_matrix()`: Transform an adjacency list into a matrix

6. `cumulativeSumMatrices()`: Cumulative sum of matrices

7. `edgelist_to_matrix()`: Transform an edgelist into a matrix

8. `expand_matrix()`: Expand matrix

9. `extract_component()`: Extract components

10. `hypergraph()`: Hypergraphs

11. `perm_matrix()`: Permutation matrix

12. `perm_label()`: Permute labels of a matrix

13. `power_function()`: Power of a matrix

14. `meta_matrix()`: Meta matrix for multilevel networks

15. `minmax_overlap()`: Minimum/maximum overlap

16. `mix_matrix()`: Mixing matrix

17. `simplicial_complexes()`: Simplicial complexes

18. `structural_na()`: Structural missing data

19. `ego_net()`: Ego network

20. `zone_sample()`: Zone-2 sampling from second-mode

Ego and personal networks:

1. `eb_constraint()`: Constraint

2. `ei_index()`: Krackhardt and Stern's E-I index

3. `heterogeneity()`: Blau's and IQV index

4. `redundancy()`: Redundancy measures

Path distances:

1. `bfs_ugraph()`: Breath-first algorithm

2. `compound_relation()`: Relational composition

3. `count_geodesics()`: Count geodesic distances

4. `short_path()`: Shortest path

5. `wlocal_distances()`: Dijikstra's algorithm (one actor)

6. `wall_distances()`: Dijikstra's algorithm (all actors)

Signed networks:

1. `posneg_index()`: Positive-negative centrality

2. `struc_balance()`: Structural balance

Structural measures:

1. `gen_density()`: Generalized density

2. `gen_degree()`: Generalized degree

3. `multilevel_degree()`: Degree centrality for multilevel networks

4. `recip_coef()`: Reciprocity

5. `trans_coef()`: Transitivity

6. `trans_matrix()`: Transitivity matrix

7. `components_id()`: Components

8. `k_core()`: Generalized k-core

9. `dyadic_census()`: Dyad census

10. `multiplex_census()`: Multiplex triad census

11. `mixed_census()`: Multilevel triad and quadrilateral census

Cohesive subgroups:

1. `clique_table()`: Clique table

2. `dyad_triad_table()`: Forbidden triad table

3. `percolation_clique()`: Clique percolation

4. `q_analysis()`: Q-analysis

5. `shared_partners()`: Shared partners

Similarity measures:

1. `bonacich_norm()`: Bonacich normalization

2. `co_ocurrence()`: Co‐occurrence

3. `dist_sim_matrix()`: Structural similarities

4. `fractional_approach()`: Fractional approach

5. `jaccard()`: Jaccard similarity

Network inference:

1. `kp_reciprocity()`: Reciprocity of Katz and Powell

2. `z_arctest()`: Z test of the number of arcs

3. `triad_uman()`: Triad census analysis assuming U|MAN

4. `ind_rand_matrix()`: Independent random matrix

Geographic information:

1. `dist_geographic()`: Geographical distances

2. `spatial_cor()`: Spatial autocorrelation

Data currently available:

1. `FIFAego`: Ego FIFA

2. `FIFAex`: Outside FIFA

3. `FIFAin`: Inside FIFA

4. `krackhardt_friends`: Krackhardt friends

5. `lazega_lawfirm`: Lazega Law Firm

Additional data in [`classicnets: Classic Data of Social
Networks`](https://github.com/anespinosa/classicnets)

-----

# Quick overview of `netmem: Network Measures using Matrices`

-----

## Installation

You can install the development version from [GitHub](https://github.com/)
with:

```{r inst, eval=FALSE}
### OPTION 1
# install.packages("devtools")
devtools::install_github("anespinosa/netmem")

### OPTION 2
options(repos = c(
    netmem = 'https://anespinosa.r-universe.dev',
    CRAN = 'https://cloud.r-project.org'))
install.packages('netmem')
```

```{r inst2}
library(netmem)
```

-----

## Multilevel Networks

Connections between individuals are often embedded in complex structures, which
shape actors’ expectations, behaviours and outcomes over time. These structures
can themselves be interdependent and exist at different levels. Multilevel
networks are a means by which we can represent this complex system by using
nodes and edges of different types. Check [this
book](https://www.springer.com/gp/book/9783319245188) edited by Emmanuel Lazega
and Tom A.B. Snijders or [this
book](https://www.cambridge.org/core/books/multimodal-political-networks/43EE8C192A1B0DCD65B4D9B9A7842128)
edited by David Knoke, Mario Diani, James Hollway and Dimitris Christopoulos.

<img src="man/figures/multilevel.png"/>

For multilevel structures, we tend to collect the data in different matrices
representing the variation of ties within and between levels. Often, we describe
the connection between actors as an adjacency matrix and the relations between
levels through incidence matrices. The comfortable combination of these matrices
into a common structure would represent the multilevel network that could be
highly complex.

### Example

<div class="alert alert-info"> Let's assume that we have a multilevel network
with two adjacency matrices, one valued matrix and two incidence matrices
between them.

- `A1`: Adjacency Matrix of the level 1

- `B1`: incidence Matrix between level 1 and level 2

- `A2`: Adjacency Matrix of the level 2

- `B2`: incidence Matrix between level 2 and level 3

- `A3`: Valued Matrix of the level 3 </div>

Create the data

```{r multilevel_example}
A1 <- matrix(c(
  0, 1, 0, 0, 1,
  1, 0, 0, 1, 1,
  0, 0, 0, 1, 1,
  0, 1, 1, 0, 1,
  1, 1, 1, 1, 0
), byrow = TRUE, ncol = 5)

B1 <- matrix(c(
  1, 0, 0,
  1, 1, 0,
  0, 1, 0,
  0, 1, 0,
  0, 1, 1
), byrow = TRUE, ncol = 3)

A2 <- matrix(c(
  0, 1, 1,
  1, 0, 0,
  1, 0, 0
), byrow = TRUE, nrow = 3)

B2 <- matrix(c(
  1, 1, 0, 0,
  0, 0, 1, 0,
  0, 0, 1, 1
), byrow = TRUE, ncol = 4)

A3 <- matrix(c(
  0, 1, 3, 1,
  1, 0, 0, 0,
  3, 0, 0, 5,
  1, 0, 5, 0
), byrow = TRUE, ncol = 4)
```

We will start with a report of the matrices:

```{r matrix_report}
matrix_report(A1)
matrix_report(B1)
matrix_report(A2)
matrix_report(B2)
matrix_report(A3)
```

What is the density of some of the matrices?

```{r multilevel_example2}
matrices <- list(A1, B1, A2, B2)
gen_density(matrices, multilayer = TRUE)
```

How about the degree centrality of the entire structure?

```{r multil, warning=FALSE}
multilevel_degree(A1, B1, A2, B2, complete = TRUE)
```

Besides, we can perform a *k*-core analysis of one of the levels using the
information of an incidence matrix

```{r multil2, warning=FALSE}
k_core(A1, B1, multilevel = TRUE)
```

This package also allows performing complex census for multilevel networks.

```{r multil3}
mixed_census(A2, t(B1), B2, quad = TRUE)
```

-----

### Ego measures

When we are interested in one particular actor, we could perform different
network measures. For example, actor `e` has connections with all the other
actors in the network. Therefore, we could estimate some of Ronald Burt's
measures.

```{r ego}
# First we will assign names to the matrix
rownames(A1) <- letters[1:nrow(A1)]
colnames(A1) <- letters[1:ncol(A1)]

eb_constraint(A1, ego = "e")
redundancy(A1, ego = "e")
```

Also, sometimes we might want to subset a group of actors surrounding an ego.

```{r ego2}
ego_net(A1, ego = "e")
```

-----

### One-mode network

This package expand some measures for one-mode networks, such as the generalized
degree centrality. Suppose we consider a valued matrix `A3`. If `alpha=0` then
it would only count the direct connections. But, adding the tuning parameter
`alpha=0.5` would determine the relative importance of the number of ties
compared to tie weights.

```{r onem}
gen_degree(A3, digraph = FALSE, weighted = TRUE)
```

Also, we could conduct some exploratory analysis using the normalized degree of
an incidence matrix.

```{r onem2}
gen_degree(B1, bipartite = TRUE, normalized = TRUE)
```
 
This package also implements some analysis of dyads.

```{r onem3}
# dyad census
dyadic_census(A1)

# Katz and Powell reciprocity
kp_reciprocity(A1)

# Z test of the number of arcs
z_arctest(A1)
```

We can also check the triad census assuming conditional uniform distribution
considering different types of dyads **(U|MAN)**

```{r onem4}
triad_uman(A1)
```
 
-----

### Code of conduct

Please note that this project is released with a [Contributor Code of
Conduct](https://anespinosa.github.io/netmem/CODE_OF_CONDUCT.html). By
participating in this project you agree to abide by its terms.

-----

### To-do list

```{r todo1}
# library(todor)
# todor::todor_package(c("TODO", "FIXME"))
```

-----

### Other related R packages

- [`{bipartite}`](https://github.com/biometry/bipartite)

- [`{migraph}`](https://github.com/snlab-ch/migraph)

- [`{multinet}`](https://CRAN.R-project.org/package=multinet)

- [`{muxViz}`](https://github.com/manlius/muxViz)

- [`{tnet}`](https://toreopsahl.com/tnet/)

- [`{xUCINET}`](https://www.analyzingsocialnetworksusingr.com/xucinet)