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%"
)
library(netrics)
list_functions <- function(string){
  paste0("`", paste(paste0(ls("package:netrics")[grepl(string, ls("package:netrics"))], "()"), collapse = "`, `"), "`")
}
list_data <- function(string){
  paste0("`", paste(paste0(ls("package:netrics")[grepl(string, ls("package:netrics"))]), collapse = "`, `"), "`")
}
```

# netrics 
<img src="man/figures/logo.png" align="right" alt="netrics logo" 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/netrics)
![GitHub release (latest by date)](https://img.shields.io/github/v/release/stocnet/netrics)
![GitHub Release Date](https://img.shields.io/github/release-date/stocnet/netrics)
[![Codecov test coverage](https://codecov.io/gh/stocnet/netrics/branch/main/graph/badge.svg)](https://app.codecov.io/gh/stocnet/netrics?branch=main)
<!-- badges: end -->

## About the package

`{netrics}` is the analytic engine of the [stocnet](https://github.com/stocnet) ecosystem.
It provides _many_ tools for marking, measuring, and identifying nodes' motifs and memberships
in _many_ (if not most) types and kinds of networks.
All functions operate on matrices, `{igraph}`, `{network}`, `{tidygraph}`, and `mnet` class objects,
and recognise directed, weighted, multiplex, multimodal, signed, and other types of networks.

`{netrics}` depends on [`{manynet}`](https://stocnet.github.io/manynet/),
which handles working with different network classes, converting between them, and modifying them.
Network-level logical tests (e.g. `is_directed()`, `is_twomode()`) remain in `{manynet}`,
while node- and tie-level analytic marks (e.g. `node_is_*()`, `tie_is_*()`) are in `{netrics}`.
For graph drawing, see [`{autograph}`](https://stocnet.github.io/autograph/),
and for further testing and modelling capabilities
see [`{migraph}`](https://stocnet.github.io/migraph/).

- [Marking](#marking)
- [Measures](#measures)
- [Memberships](#memberships)
- [Motifs](#motifs)
- [Analysis](#analysis)
- [Installation](#installation)
  - [Stable](#stable)
  - [Development](#development)
- [Relationship to other packages](#relationship-to-other-packages)
- [Funding details](#funding-details)

## Marking

`{netrics}` includes four special groups of functions, 
each with their own pretty `print()` and `plot()` methods:
marks, measures, motifs, and memberships.
Marks are logical scalars or vectors, measures are numeric, 
memberships categorical, and motifs result in tabular outputs.

`{netrics}`'s `node_is_*()` and `tie_is_*()` functions offer fast logical tests
of node- and tie-level properties.
`node_is_*()` returns a logical vector the length of the number of nodes in the network,
and `tie_is_*()` returns a logical vector the length of the number of ties in the network.
Note that network-level tests such as `is_directed()` and `is_twomode()` are in `{manynet}`.

- `r list_functions("^node_is_")`
- `r list_functions("^tie_is_")`

The `*is_max()` and `*is_min()` functions are used to identify
the maximum or minimum, respectively, node or tie according to some measure (see below).

## Measures

`{netrics}`'s `*_by_*()` functions offer numeric measures at the network, node, and tie level.
These include:

- `r list_functions("_by_")`

The measures are organised into several broad categories, including:
_Centrality_, _Cohesion_, _Hierarchy_, _Innovation_ (structural holes),
_Diversity_ (heterogeneity), _Topology_ (features), and _Diffusion_.
Each measure recognises whether the network is directed or undirected,
weighted or unweighted, one-mode or two-mode,
and returns normalized values wherever possible.
We recommend you explore [the list of functions](https://stocnet.github.io/netrics/reference/index.html) to find out more.

## Memberships

`{netrics}`'s `*_in_*()` functions identify nodes' membership in some grouping,
such as a community or component.
These functions always return a character vector, 
indicating e.g. that the first node is a member of group "A", the second in group "B", etc.

- `r list_functions("_in_")`

For example `node_in_brokering()` returns 
the frequency of nodes' participation in 
Gould-Fernandez brokerage roles for a one-mode network,
and the Jasny-Lubell brokerage roles for a two-mode network.

These can be analysed alone, or used as a profile for establishing equivalence.
`{netrics}` offers both HCA and CONCOR algorithms,
as well as elbow, silhouette, and strict methods for _k_-cluster selection.

<img src="https://www.jameshollway.com/post/migraph/dendroPlot.png" alt="Plot of a dendrogram of structural equivalence"/>

`{netrics}` also includes functions for establishing membership on other bases,
such as typical community detection algorithms, 
as well as component and core-periphery partitioning algorithms.

## Motifs

`{netrics}`'s `*_x_*()` functions tabulate nodes' and networks' frequency in various motifs.
These include:

- `r list_functions("_x_")`

## Analysis

The functions in `{netrics}` are designed to answer a wide variety of analytic questions about networks.
For example, you might want to know about:

- _Centrality_: `r list_functions("degree|betweenness|closeness|eigenvector")`
- _Cohesion_: `r list_functions("density|reciprocity|transitivity|equivalency|congruency")`
- _Hierarchy_: `r list_functions("hierarchy|connectedness|upper|efficiency|reciprocity")`
- _Topology_: `r list_functions("core|factions|modularity|smallworld|balance|richclub")`
- _Resilience_: `r list_functions("cutpoint|bridge|hesion|articul")`
- _Brokerage_: `r list_functions("broke|hole|redundancy|constraint|effsize")`
- _Diversity_: `r list_functions("diversity|phily|richness|assort")`
- _Diffusion_: `r list_functions("adopt|infect|expos")`

## Installation

### Stable

The easiest way to install the latest stable version of `{netrics}` is via CRAN.
Simply open the R console and enter:

`install.packages('netrics')`

`library(netrics)` will then load the package and make the functions 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/netrics/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/netrics_winOS.zip", repos = NULL)`
- For Mac: `install.packages("~/Downloads/netrics_macOS.tgz", repos = NULL)`
- For Unix: `install.packages("~/Downloads/netrics_linuxOS.tar.gz", repos = NULL)`

To install from source the latest main version of `{netrics}` from Github, 
please install the `{remotes}` package from CRAN and then:

- For latest stable version: 
`remotes::install_github("stocnet/netrics")`
- For latest development version: 
`remotes::install_github("stocnet/netrics@develop")`

### Other sources

Those using Mac computers may also install using Macports:

`sudo port install R-netrics`

## Relationship to other packages

`{netrics}` is part of the [stocnet](https://github.com/stocnet) ecosystem of R packages
for network analysis.
The packages are designed to be modular, with clear roles and dependencies:

- [`{manynet}`](https://stocnet.github.io/manynet/): 
  The foundation package for working with network data.
  It handles network classes (matrices, `{igraph}`, `{network}`, `{tidygraph}`, `mnet`), 
  coercion between them, modification, and network-level logical tests (`is_*()` functions).
- **`{netrics}`**: 
  The analytic package containing all measures (`*_by_*()` functions),
  memberships (`*_in_*()` functions), motifs (`*_x_*()` functions), 
  and node- and tie-level marks (`node_is_*()`, `tie_is_*()` functions).
  `{netrics}` depends on `{manynet}`.
- [`{autograph}`](https://stocnet.github.io/autograph/): 
  The graph drawing package.
  `{autograph}` depends on both `{manynet}` (for network classes)
  and `{netrics}` (for analytic results to visualise),
  since it would typically be used with both.
- [`{migraph}`](https://stocnet.github.io/migraph/): 
  The modelling and testing package, 
  building on both `{manynet}` and `{netrics}`.

Node- and tie-level marks such as `node_is_cutpoint()` and `tie_is_bridge()` are kept
in `{netrics}` rather than `{manynet}` because they are analytic functions that identify
structural positions in the network.
Network-level property tests like `is_directed()` remain in `{manynet}`
because they describe the type of data rather than an analytic result.

## Funding details

Development 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).