gbi_MCMC: Generate Null Distributions for Group-by-Individual Data

In MNWeiss/aninet: Statistical Models for Animal Social Networks

Generate Null Distributions for Group-by-Individual Data

Description

Produce null distributions of target statistics by permuting a group-by-individual matrix using the MCMC routine proposed by Bejder et al. (1998).

Usage

gbi_MCMC(
  data,
  ind_constraint = NULL,
  group_constraint = NULL,
  samples = 1000,
  thin = 100,
  burnin = 1000,
  chains = 2,
  FUN = NULL,
  ...
)

Arguments

data	A group by individual matrix
ind_constraint	A vector of individual characteristics to constrain permutations; defaults to NULL
group_constraint	A vector group characteristics (usually time windows) to constrain permutations; defaults to NULL
samples	The number of samples to draw for each chain. Defaults to 1000.
thin	The number of steps between each draw. Defaults to 100.
burnin	The number of samples before target statistics are calculated. Defaults to 1000.
chains	The number of independent chains to run. Defaults to 2.
FUN	A function taking a GBI as an input and outputting a vector of any length. See Details.
...	Other arguments to be passed to FUN

Details

For some applications, it may be desirable to compare the observed social structure to a null model in which there are no social preferences. This is particularly useful when investigating whether individuals have social preferences, but may also have other uses. In these cases, the canonical method for generating the null model is a Markov Chain Monte Carlo procedure. For each iteration, a change in the matrix is proposed; if the change maintains row an column totals, and falls within the specified constraints, it is accepted, otherwise the matrix stays at its current state. While this method is widely used in social network analysis, and has been implemented in other software, it is often not implemented properly to generate a valid MCMC chain. In addition, none of the current implementations utilize the toolkit that has been developed to check MCMC chain convergence, or provide confidence intervals for p-values. This implementation fills in these gaps.

This function takes an argument FUN, which allows users to define custom test statistics. This argument should be a function taking a single argument (the group by individual matrix) and outputting a vector (the test statistic(s)). By default, this function will calculate the test statistics suggested by Whitehead (2008) for testing for non-random social structure: the mean, SD, CV, and portion non-zero association indices (the SRI by default). Other network statistics can be calculated as well (such as clustering coefficient, modularity, etc.).

Value

An object of class gbi_null

MNWeiss/aninet documentation built on Jan. 31, 2023, 3:55 a.m.