/
README.Rmd
211 lines (160 loc) · 9.61 KB
/
README.Rmd
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
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
---
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%"
)
library(migraph)
list_functions <- function(string){
paste0("`", paste(paste0(ls("package:migraph")[grepl(string, ls("package:migraph"))], "()"), collapse = "`, `"), "`")
}
list_data <- function(string){
paste0("`", paste(paste0(ls("package:migraph")[grepl(string, ls("package:migraph"))]), collapse = "`, `"), "`")
}
```
# migraph <img src="man/figures/logo.png" align="right" width="150"/>
<!-- badges: start -->
[![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html#maturing)
![CRAN/METACRAN](https://img.shields.io/cran/v/migraph)
![GitHub release (latest by date)](https://img.shields.io/github/v/release/stocnet/migraph)
![GitHub Release Date](https://img.shields.io/github/release-date/stocnet/migraph)
[![Codecov test coverage](https://codecov.io/gh/stocnet/migraph/branch/main/graph/badge.svg)](https://app.codecov.io/gh/stocnet/migraph?branch=main)
<!-- [![CodeFactor](https://www.codefactor.io/repository/github/stocnet/migraph/badge)](https://www.codefactor.io/repository/github/stocnet/migraph) -->
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4559/badge)](https://bestpractices.coreinfrastructure.org/projects/4559)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7076396.svg)](https://doi.org/10.5281/zenodo.7076396)
<!-- see https://zenodo.org/record/7076396 -->
<!-- ![GitHub All Releases](https://img.shields.io/github/downloads/stocnet/migraph/total) -->
<!-- badges: end -->
## About the package
The most commonly used R packages available for network analysis,
such as `{igraph}` or `{sna}`,
are mainly oriented around directed or undirected one-mode networks.
But researchers are increasingly interested in analysing multimodal (one-, two-, or three-mode), multilevel (connected multimodal networks), or multilayer (multiplex or signed) networks.
Existing procedures typically involve 'projecting' them into one-mode networks so that they can be used with those tools,
but thereby potentially losing important structural information,
or require one or more other specific packages.
Translating between packages various syntaxes and expectations can introduce significant transaction costs though,
driving confusion, inefficiencies, and errors.
`{migraph}` builds upon `{manynet}` to offer smart solutions to these problems.
It includes functions for marking and measuring networks and their nodes and ties,
identifying motifs and memberships in them,
and modelling these networks or simulating processes such as diffusion upon them.
Based on `{manynet}`, every function works for any compatible network format
- from base R matrices or edgelists as data frames,
[`{igraph}`](https://igraph.org/r/),
[`{network}`](https://statnet.org), or
[`{tidygraph}`](https://tidygraph.data-imaginist.com/index.html) objects.
This means it is compatible with your existing workflow,
is extensible by other packages,
and uses the most efficient algorithm available for each task.
<img style="border:10px solid white;" src="https://jameshollway.com/media/9781108833509pvs01.jpg" align="left" width="125"/>
The package is intended as a software companion to the book:
> David Knoke, Mario Diani, James Hollway, and Dimitris Christopoulos (2021) [*Multimodal Political Networks*](https://www.cambridge.org/core/books/multimodal-political-networks/43EE8C192A1B0DCD65B4D9B9A7842128).
Cambridge University Press: Cambridge.
Most datasets used in the book are included in this package,
and the package implements most methods discussed in the book.
Since many of theses datasets and routines are discussed and analysed more there,
if you like the package please check out the book, and vice versa.
## How does migraph help?
`{migraph}` includes five special groups of functions,
each with their own pretty `print()` and `plot()` methods:
marks, measures, memberships, motifs, and models.
`{migraph}` uses a common syntax to help new and experienced network analysts
find the right function and use it correctly.
All `network_*()` functions return a value for the network/graph or for each mode in the network.
All `node_*()` functions return values for each node or vertex in the network.
And all `tie_*()` functions return values for each tie or edge in the network.
Functions are given intuitive and succinct names that avoid conflicts
with existing function names wherever possible.
All results are normalised by default, facilitating comparison.
### Measures
`{migraph}` also offers a large and growing smorgasbord of measures that
can be used at the node, tie, and network level.
Each recognises whether the network is directed or undirected,
weighted or unweighted, one-mode or two-mode.
All return normalized values wherever possible,
though this can be overrided.
Here are some examples:
- _Centrality_: `node_degree()`, `node_closeness()`, `node_betweenness()`, and `node_eigenvector()`
- _Centralization_: `network_degree()`, `network_closeness()`, `network_betweenness()`, and `network_eigenvector()`
- _Cohesion_: `network_density()`, `network_reciprocity()`, `network_transitivity()`, `network_equivalency()`, and `network_congruency()`
- _Connectedness_: `network_components()`, `network_cohesion()`, `network_adhesion()`, `network_diameter()`, `network_length()`
- _Diversity_: `network_diversity()`, `network_homophily()`, `network_assortativity()`,
`node_diversity()`, `node_homophily()`, `node_assortativity()`, `node_richness()`
- _Innovation_: e.g. `node_redundancy()`, `node_effsize()`, `node_efficiency()`, `node_constraint()`, `node_hierarchy()`
- _Topological features_: e.g. `network_core()`, `network_factions()`, `network_modularity()`, `network_smallworld()`, `network_balance()`
Please explore [the list of functions](https://stocnet.github.io/migraph/reference/index.html) to find out more.
### Motifs and Memberships
The package also include functions for returning various censuses
at the network or node level, e.g.:
- `r list_functions("network_.*_census")`
- `r list_functions("node_.*_census")`
These can be analysed alone, or used as a profile for establishing equivalence.
`{migraph}` offers both HCA and CONCOR algorithms,
as well as elbow, silhouette, and strict methods for _k_-cluster selection.
- `r list_functions("node.*_equivalence")`
`{migraph}` also includes functions for establishing membership on other bases,
such as typical community detection algorithms,
as well as component and core-periphery partitioning algorithms.
### Models
All measures can be tested against conditional uniform graph (CUG)
or quadratic assignment procedure (QAP) distributions using:
- `r list_functions("^test_")`
Hypotheses can also be tested within multivariate models
via multiple (linear or logistic) regression QAP:
- `network_reg()`
`{migraph}` is the only package that offers these testing frameworks
for two-mode networks as well as one-mode networks.
## Installation
### Stable
The easiest way to install the latest stable version of `{migraph}` is via CRAN.
Simply open the R console and enter:^[Macs with Macports installed may also install from the command line [using Macports](https://ports.macports.org/port/R-migraph/).]
`install.packages('migraph')`
You can then begin to use `{migraph}` by loading the package:
`library(migraph)`
This will load any required packages and make the data contained within the package available.
### Development
For the latest development version,
for slightly earlier access to new features or for testing,
you may wish to download and install the binaries from Github
or install from source locally.
The latest binary releases for all major OSes -- Windows, Mac, and Linux --
can be found [here](https://github.com/stocnet/migraph/releases/latest).
Download the appropriate binary for your operating system,
and install using an adapted version of the following commands:
- For Windows: `install.packages("~/Downloads/migraph_winOS.zip", repos = NULL)`
- For Mac: `install.packages("~/Downloads/migraph_macOS.tgz", repos = NULL)`
- For Unix: `install.packages("~/Downloads/migraph_linuxOS.tar.gz", repos = NULL)`
To install from source the latest main version of `{migraph}` from Github,
please install the `{remotes}` or `{devtools}` package from CRAN and then:
- For latest stable version:
`remotes::install_github("stocnet/migraph")`
- For latest development version:
`remotes::install_github("stocnet/migraph@develop")`
### Tutorials
Together with `{manynet}`, this package makes available interactive `{learnr}` tutorials.
The easiest way to access the tutorials is via `run_tute()`.
If no tutorial name is provided, the function will return a list of tutorials
currently available in either package:
```{r learnr-tutes}
library(migraph)
run_tute()
# run_tute("tutorial5")
```
For more details on the `{learnr}` package, see [here](https://rstudio.github.io/learnr/).
## Relationship to other packages
`{migraph}` draws together, updates, and builds upon many functions currently available in
other excellent R packages such as
[`{bipartite}`](https://github.com/biometry/bipartite),
[`{multinet}`](https://CRAN.R-project.org/package=multinet),
[`{tnet}`](https://toreopsahl.com/tnet/),
and [`{xUCINET}`](https://sites.google.com/view/asnr-2022/xucinet?authuser=0).
## Funding details
Most work on this package has been funded by the Swiss National Science Foundation (SNSF)
[Grant Number 188976](https://data.snf.ch/grants/grant/188976):
"Power and Networks and the Rate of Change in Institutional Complexes" (PANARCHIC).