DispersalModel-class: DispersalModel Class

Description

The class DispersalModel is an S4 Class supplying organism-specific information about dispersal stages (with axial sigmas), FS & HS branch points, and the dispersal stage at which sampling occurs.It is used with the simulate_kindist_custom function to enable the simulation of uniquely defined breeding & dispersal cycles.

Usage

# S4 method for DispersalModel
show(object)
# S4 method for DispersalModel
initialize(
  .Object,
  stages = NULL,
  dispersal_vector = NULL,
  fs = NULL,
  hs = NULL,
  sampling_stage = NULL,
  cycle = NULL,
  breeding_stage = NULL,
  visible_stage = NULL
)

Arguments

object

an object of class DispersalModel

.Object

object to be constructed into DispersalModel class

stages

character. Ordered vector of all dispersal stages across the breeding cycle of the modeled species

dispersal_vector

numeric. Named vector of custom breeding cycle stages and their corresponding axial dispersal values

character. breeding cycle stage at which first substantial FS-phased dispersal occurs

character. breeding cycle stage at which first substantial HS-phased dispersal occurs

sampling_stage

character. stage in the breeding cycle at which samples are to be collected for kin identification.

cycle

non-negative integer. Breeding cycle numbers of dispersed kin to be modeled. Represents the number of complete breeding cycles each simulated individual has undergone before the sampling point, where the time between birth and first reproduction is coded as '0', that between first and second reproduction '1', etc. (default 0)

breeding_stage

(character) - stage in the cycle at which breeding occurs. Must correspond to a previously described cycle stage name. By default, equated with the .HS stage. This stage corresponds to the generation of next-generation individuals; the .FS & .HS stages correspond to their separation. Needed for situations where individuals are sampled before they separate from the parent. Modify if the modeled .HS gamete dispersal event does not correspond to the initial breeding event.

visible_stage

(character) - stage in the cycle at the beginning of which individuals are visible to the study for sampling rather than their parents (i.e. the beginning point of cycle 0). By default, equated with the fs stage. This parameter determines how many dispersal stages individuals have gone through before they are sampled - if .sampling_stage occurs just after .visible_stage, the sampled individuals will have dispersed through only a small amount of the breeding cycle. if .sampling_stage occurs just before .visible_stage, the sampled individuals will have dispersed throughout most of the breeding cycle before being sampled. If .cycle is set to -1, dispersal stages between breeding & visibility can be accessed.

DispersalModel

an object of class DispersalModel

Value

returns object of class DispersalModel

No return value. Called for side effects

returns an object of class DispersalModel

Methods (by generic)

show: print method
initialize: initialization method

Slots

dispersal_vector: numeric. Named vector of custom breeding cycle stages and their corresponding axial dispersal values

stages

character. Ordered vector of all dispersal stages across the breeding cycle of the modeled species

fs

character. breeding cycle stage at which first substantial FS-phased dispersal occurs

hs

character. breeding cycle stage at which first substantial HS-phased dispersal occurs

sampling_stage

character. stage in the breeding cycle at which samples are to be collected for kin identification.

cycle

non-negative integer. Breeding cycle numbers of dispersed kin to be modeled. Represents the number of complete breeding cycles each individual has undergone before the sampling point, where the time between birth and first reproduction is coded as '0', that between first and second reproduction '1', etc. (default 0)

breeding_stage

visible_stage

Details

The original simulation functions in this package (simulate_kindist_simple() & simulate_kindist_composite) were designed for an organism with a specific (& relatively simple) breeding & dispersal cycle. 'simple' corresponded to a single dispersal event across a lifespan, equivalency of all dispersal phases (FS, HS, PO) and no lifetime overlaps. 'composite' corresponded to many insect dispersal situations, where breeding & oviposition are the key 'phase-defining' events (i.e., they lead to the initial gamete dispersal of half siblings & full siblings from each other), where field sampling typically occurs via ovitraps

More general dispersal scenarios (e.g in mammals) require the ability to uniquely specify a variety of distinct breeding ecologies & sampling schemes: the DispersalModel class paired with the simulate_kindist_custom function achieves this by defining a breeding cycle with an arbitrary number of dispersal phases (the dispersal_vector slot, accessed by the dispersal_vector method).

The breeding structure of a species may also impact at which stage FS and HS phase branches occur. In Ae. aegypti, males mate with multiple females in a (single) breeding season, and a female typically carried the egg of only one male. In this context the FS (full-sibling) phase would be set to correspond to the female's oviposition dispersal, while the HS (half-sibling) phase would be set to correspond to the male's breeding dispersal (as its gametes will then be dispersed by multiple females across their gravid & ovipositional phases). However, in e.g. some species of the marsupial Antechinus, the FS branch point would be more appropriately associated with juveniles at the time that they leave the mother's pouch. The fs and hs slots & accessor functions enable the assignment of these phase branches to any defined life phase. Similarly, the sampling_stage slot & method allow the sampling point to be set to correspond to any phase of the defined breeding cycle.

The next parameter stored in this object is the breeding cycle number cycle, accessed by the breeding_cycle method. This parameter enables the treatment of species that undergo multiple breeding cycles in one lifetime. This is defined as a length two vector describing the number of breeding cycles undergone by the final descendant of branch 1 and branch 2 of the dispersal pedigree before their sampling (or after branching in the case of PO). (where branch one is the 'senior' and branch two the 'junior' member of the pedigree) (so uncle is branch one, nephew branch two, grandmother branch one, granddaughter branch two, etc.). For each member of the resulting kin pair, the cycle number represents the number of complete breeding cycles each individual has undergone before the sampling point, where the time between birth and first reproduction is coded as '0', that between first and second reproduction '1', etc. This enables an application of the simulation functions defined here to deal with populations with some amount of overlap between generations.

Note that this 'breeding cycle' approach is only applicable in situations where there is an approximate equivalence between the dispersal which occurs in the first 'juvenile' breeding cycle and that which occurs between later breeding cycles. This parameter is implemented here, but it will often be more productive to implement it instead as a parameter of the simulate_kindist_custom function (the cycle parameter there if set overrides whatever was defined within this object)

The final parameter stored in this object is the breeding stage, breeding_stage. This describes the stage at which the descendant individuals are generated (as opposed to fs & hs, which describe the point at which they are dispersed from the parent)