---
title: "Using `ergm.sign` to analyse the signed Read's Highland Tribes dataset"
author: "Marc Schalberger"
output: rmarkdown::html_vignette
bibliography: ../inst/REFERENCES.bib
vignette: >
  %\VignetteIndexEntry{tribes}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
    %\VignetteIndexEntry{Using ergm.sign to analyse the Read's signed Highland Tribes dataset}

---

```{css, echo=FALSE}
pre {
  font-size: 85%
}
```

```{r, echo=FALSE, cache=FALSE, eval=TRUE}
library(knitr)
library(rmarkdown)
library(ergm)
library(ergm.multi)
options(rmarkdown.html_vignette.check_title = FALSE)
opts_chunk$set(warning= FALSE,message=FALSE, echo=TRUE, cache=TRUE, autodep=TRUE,
concordance=TRUE, error=FALSE, fig.width=7, fig.height=7)
options(width=160)
```

```{r setup}
library(ergm.sign)
```

# Obtaining data

The highland tribes dataset from @read1954cultures is included in the `ergm.sign` package:

```{r}
data("tribes")
```

This gives us a multilayer network construct with a positive and a negative layer encoding the allied and hostile relationships between the tribes.

# Desctiptive statistics

The summary `summary` function returns a matrix with the most important descriptive statistics for the  signed network:

```{r}
summary(tribes)
```

If we would like to get other descriptive statistics using the `summary_formula` function:

```{r}
summary(tribes ~ edges + Pos(~ edges) + Neg(~ edges))
```

# Plotting the network

It is also possible to plot the signed network using the `plot` function. Which requires the `UnLayer` function that turns the multilayer network into a single layer network:

```{r}
plot(tribes, displaylabels = TRUE)
```

# Fitting a model

Just like in the unsigned case, we can call the `ergm.sign` function to fit a model to the signed network. The `ergm.sign` function requires a formula that specifies the model to be fitted. In addition to the normal ergm terms we can also use the `Pos` and the `Neg` function to specify terms that only apply to the positive or negative layer of the network.

```{r}
fit <- ergm.sign(tribes ~ Pos(~ edges) + Neg(~ edges))
summary(fit)
```

Triadic effects are of particular interest in the context of signed networks.

```{r}
triad_fit <- ergm.sign(tribes ~ gwese(0.5, base = "+") + gwesf(0.5, base = "+"))
summary(triad_fit)
```

Here, the `gwese` (geometrically weighted edgewise shared enemies) term models enemy of my enemy is my friend configuration and the `gwesf` (geometrically weighted edgewise shared friends) term models friend of a friend is a friend configuration.

# Goodness of fit

In order to assess the goodness of fit of the model we can use the `gof_sign` function, which compares the observed network statistics to the statistics of simulated networks. The `nsim` argument specifies the number of simulations to be performed. For example, to perform 20 simulations we can use the following code:

```{r}
gof_data <- gof(triad_fit, nsim = 20)
plot(gof_data)
```

# References