---
title: "Positional dominance in networks"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{03 positional dominance in networks}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

This vignette describes the concept of positional dominance, the generalization 
of [neighborhood-inclusion](neighborhood_inclusion.html) for arbitrary network and 
attribute data. Additionally, some use cases with the `netrankr` package are given. 
The partial ranking induced by positional dominance can be used to assess 
[partial centrality](partial_centrality.html) or compute
[probabilistic centrality](probabilistic_cent.html).

________________________________________________________________________________

## Theoretical Background

A network can be described as a *dyadic variable* $x\in \mathcal{W}^\mathcal{D}$,
where $\mathcal{W}$ is the value range of the network (in the simple case of unweighted networks $\mathcal{W}=\{0,1\}$)
and $\mathcal{D}=\mathcal{N}\times\mathcal{A}$ describes the dyadic domain of actors $\mathcal{N}$ and
affiliations $\mathcal{A}$. If $\mathcal{A}\neq\mathcal{N}$, we obtain a *two-mode network* and
if $\mathcal{A}=\mathcal{N}$ a *one-mode network* consisting of relations among actors.
\
\
\

**Definition**

Let $x\in \mathcal{W}^\mathcal{D}$ be a network and $i,j \in \mathcal{N}$. We say that
$i$ is dominated by $j$ *under the total homogeneity assumption*, denoted by $i \leq j$ if
$$
x_{it}\leq x_{jt} \quad \forall t \in \mathcal{N}.
$$
If there exists a permutation $\pi: \mathcal{N} \to \mathcal{N}$ such that
$$
x_{it}\leq x_{j\pi(t)} \quad \forall t \in \mathcal{N},
$$
we say that $i$ is dominated by $j$ *under the total heterogeneity assumption*, denoted by $i ⪯ j$.  
It holds that $i\leq j \implies i ⪯ j$ but not vice versa.
\
\
\

More about the positional dominance and the positional approach to network analysis can be found in

> Brandes, Ulrik. (2016). Network Positions.
*Methodological Innovations*, **9**, 2059799116630650.
([link](https://dx.doi.org/10.1177/2059799116630650))

________________________________________________________________________________

## Positional Dominance in the `netrankr` Package

```{r setup, warning=FALSE,message=FALSE}
library(netrankr)
library(igraph)
library(magrittr)
set.seed(1886) #for reproducibility
```

The function `positional_dominance` can be used to check both, dominance under homogeneity and heterogeneity.
In accordance with the analytic pipeline of centrality (consult the tutorial REFREF)
we use the `%>%` operator from the `magrittr` package.

```{r pos_dom}
g <- graph.empty(n=11,directed = FALSE)
g <- add_edges(g,c(1,11,2,4,3,5,3,11,4,8,5,9,5,11,6,7,6,8,
                   6,10,6,11,7,9,7,10,7,11,8,9,8,10,9,10))
V(g)$name <- 1:11

#neighborhood inclusion can be expressed with the analytic pipeline
D <- g %>% indirect_relations(type="identity") %>% positional_dominance()

#without %>% operator:
# rel <- indirect_relations(g,type="identity")
# D <- positional_dominance(rel)

#check if identical to neighborhood-inclusion
identical(D,neighborhood_inclusion(g))
```

More on the `indirect_relations()` function can be found in [this](indirect_relations.html) vignette.

The `map` parameter of `positional_dominance` allows to distinguish between dominance
under *total heterogeneity* (`map=FALSE`) and *total homogeneity* (`map=TRUE`). 
In the later case, all relations can be ordered non-decreasingly (or non-increasingly 
if the relation describes costs, such as distances) and afterwards checked front to back.
Dominance under total homogeneity yields a ranking, if the relation is binary (e.g. adjacent or not).  

```{r homo_and_hetero}
D <- g %>% 
  indirect_relations(type="identity") %>% 
  positional_dominance(map=TRUE)

comparable_pairs(D)
```

For cost variables like shortest path distances, the `benefit` parameter is set to `FALSE`.
```{r dist}
D1 <- g %>% 
  indirect_relations(type="dist_sp") %>% 
  positional_dominance(map=FALSE,benefit=FALSE)
```

From the definition given in the first section, it is clear that there are always 
at least as many comparable pairs under the total homogeneity assumption as under
total heterogeneity.
```{r homo_and_hetero_dist}
D1 <- g %>% 
  indirect_relations(type="dist_sp") %>% 
  positional_dominance(map=FALSE,benefit=FALSE)

D2 <- g %>% 
  indirect_relations(type="dist_sp") %>% 
  positional_dominance(map=TRUE,benefit=FALSE)

c("heterogeneity"=comparable_pairs(D1),
  "homogeneity"=comparable_pairs(D2))

```

Additionally, all dominance relations from the heterogeneity assumption are preserved
under total homogeneity. (Note: $A\implies B$ is equivalent to $\neg A \lor B$)

```{r homo_in_hetero}
all(D1!=1 | D2==1) 
```
