epp: Building data-set for realized and unrealized EPP-pairs
In expp: Spatial Analysis of Extra-Pair Paternity

Description Usage Arguments Details Value See Also Examples

epp combines a SpatialPointsBreeding, a SpatialPolygons* as obtained from DirichletPolygons and a eppMatrix to create the spatial context for every potential and realized extra-pair male-female combination.

epp(breedingDat, polygonsDat, eppDat, maxlag = 3)

## S4 method for signature 'epp,missing'
plot(x, zoom, maxlag = 3, zoom.col = "grey", ...)

## S4 method for signature 'epp'
barplot(height, relativeValues = FALSE, ...)

## S4 method for signature 'epp'
as.data.frame(x)

`breedingDat`	A SpatialPointsBreeding object, created by the `SpatialPointsBreeding` function
`polygonsDat`	A SpatialPolygons* object as obtained by calling `DirichletPolygons` function
`eppDat`	An object of class `eppMatrix`
`maxlag`	A numeric value indicating the maximum breeding distance for which male-female combinations should be calculated. When plotting it defines the outermost row of neighbors plotted around a focal id set by zoom
`x, height`	an `epp` object
`zoom`	a `SpatialPointsBreeding` id which is used for subsetting prior to plot
`zoom.col`	background color of the id (and hence the polygon) set by `zoom`
`...`	further arguments to pass to `plot.SpatialPointsBreeding` and `plot.SpatialPolygons*`
`relativeValues`	Defines the unit of the y-axis. TRUE plots proportions, FALSE absolute numbers.

'plot' plots the territories, the identity of males ('m...') and females ('f...') at breeding sites (numbers), and the extra-pair events (dashed red arrows). Individuals that had extra-pair offspring are marked red. The parameter 'zoom' can be used to make a detailed visual check of a specific location (nestbox) and its surroundings.

'barplot' displays the distribution of extra-pair events over different breeding distances between the partners (in the number of territories) as vertical bars. Note that the distribution of all potential extra-pair partners is displayed as a dashed line only if the argument 'relativeValues' is TRUE.

Returns an S4-class epp-object with 5 slots:

`breedingDat`	Input breeding data-set.
`polygonsDat`	Either polygons are estimated automatically using Thiessen Polygons, or input breeding polygons.
`eppDat`	Input data.frame with all male-female combinations that had EPP together.
`maxlag`	Input rank. Defaults to 3.
`EPP`	`data.frame` containing columns for the focal male and female ("male", "female"), their breeding distance ("rank"), and the parameters associated either with the male (column with prefix "_MALE") or the female (column with prefix "_FEMALE") territory.

vignette(expp)

  ### Simple example with three breeding pairs
  require(expp)
  # create raw data
  set.seed(1310)
  b = data.frame(id = as.integer(10:12), x = rnorm(3), y = rnorm(3), 
  male = paste0("m",1:3), female =  paste0("f",1:3), xx = rnorm(3), stringsAsFactors=FALSE  )  
  eppPairs = data.frame(male = c("m1", "m2", "m1"), female=c("f3", "f1", "f2") )
  
  # prepare data
  breedingDat = SpatialPointsBreeding(b, id = 'id', coords = ~ x + y, breeding = ~ male + female)
  polygonsDat = DirichletPolygons(breedingDat)
  eppDat   = eppMatrix(eppPairs, pairs = ~ male + female)

  plot(breedingDat, eppDat)
  
  # convert to epp class     
  x = epp(breedingDat, polygonsDat, eppDat, maxlag = 3)
  as.data.frame(x)
  
  
  #plot 
  plot(x) 
  
  ### Example on a random data set with n breeding pairs and  n/2 extra-pair paternity rate
  # create raw data
  set.seed(123)
  n = 20
  b = data.frame(id = 1:n, x = rnorm(n), y = rnorm(n), 
  male = paste0("m",1:n), female =  paste0("f",1:n), xx = rnorm(n), stringsAsFactors=FALSE  )  
  eppPairs = data.frame(male = sample(b$male, round(n/2) ), female = sample(b$female, round(n/2) ) )
  
  # prepare data
  breedingDat = SpatialPointsBreeding(b, id = 'id', coords = ~ x + y, breeding = ~ male + female)
  polygonsDat = DirichletPolygons(breedingDat)
  eppDat   = eppMatrix(eppPairs, pairs = ~ male + female)
  
  # convert to epp class
  x = epp(breedingDat, polygonsDat, eppDat, maxlag = 10)
  
  # plot 
  plot(x)
  barplot(x) 
  barplot(x, relativeValues = TRUE) 
  

   
  ### Real data example
  # Raw datasets 
  data(bluetit_breeding)
  data(bluetit_epp)
  # select one year 
  year = 2010
  b = bluetit_breeding[bluetit_breeding$year_ == year, ]
  eppPairs = bluetit_epp[bluetit_epp$year_ == year, ]
  
  # prepare data
  breedingDat  = SpatialPointsBreeding(b, id = 'id', coords = ~ x + y, breeding = ~ male + female)
  polygonsDat = DirichletPolygons(breedingDat)
  eppDat = eppMatrix(eppPairs, pairs = ~ male + female)
  
  # convert to epp class
  x = epp(breedingDat, polygonsDat, eppDat, maxlag = 2)
  
  # plot
  plot(x)
  barplot(x) 
  # plot zoom
  plot(x, zoom = 120, maxlag = 3) 
  
  # run model on epp probability     
  dat = as.data.frame(x)
  nrow(dat[dat$epp == 1, c('male', 'female')] )
  nrow(unique(eppPairs))
  
  if(require(lme4))
   (summary(glmer(epp ~ rank + male_age_MALE + (1|male) + (1|female), 
    data = dat, family = binomial)))