rlefko3: Create Raw Historical Matrix Projection Model

Description Usage Arguments Value Notes Examples

View source: R/matrixcreation.R

Description

rlefko3() returns raw historical MPMs, including the associated component transition and fecundity matrices, data frames describing the ahistorical stages used and the historical paired stages, and a data frame describing the population, patch, and year associated with each matrix.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
rlefko3(
  data,
  stageframe,
  year = "all",
  pop = NA,
  patch = NA,
  censor = FALSE,
  stages = NA,
  alive = c("alive3", "alive2", "alive1"),
  size = c("sizea3", "sizea2", "sizea1"),
  repst = c("repstatus3", "repstatus2", "repstatus1"),
  matst = c("matstatus3", "matstatus2", "matstatus1"),
  fec = c("feca3", "feca2", "feca1"),
  supplement = NA,
  repmatrix = NA,
  overwrite = NA,
  yearcol = NA,
  popcol = NA,
  patchcol = NA,
  indivcol = NA,
  censorcol = NA,
  censorkeep = 0,
  format = "ehrlen",
  reduce = FALSE,
  err_check = FALSE
)

Arguments

data

A vertical demographic data frame, with variables corresponding to the naming conventions in verticalize3().

stageframe

A stageframe object that includes information on the size, observation status, propagule status, immaturity status, and maturity status of each ahistorical stage. Should also incorporate bin widths if size is continuous.

year

A variable corresponding to year or observation time, or a set of such values, given in values associated with the year term used in linear model development. Can also equal all, in which case matrices will be estimated for all years. Defaults to all.

pop

A variable designating which populations will have matrices estimated. Should be set to specific population names, or to all if all populations should have matrices estimated.

patch

A variable designating which patches or subpopulations will have matrices estimated. Should be set to specific patch names, or to all if matrices should be estimated for all patches. Defaults to all.

censor

If TRUE, then data will be removed according to the variable set in censorcol, such that only data with censor values equal to 1 will remain. Defaults to FALSE.

stages

An optional vector denoting the names of the variables within the main vertical dataset coding for the stages of each individual in times t+1, t, and t-1. The names of stages in these variables should match those used in the stageframe exactly. If left blank, then rlefko3() will attempt to infer stages by matching values of alive, size, repst, and matst to characteristics noted in the associated stageframe.

alive

A vector of names of binomial variables corresponding to status as alive (1) or dead (0) in times t+1, t, and t-1, respectively.

size

A vector of names of variables coding size in times t+1, t, and t-1, respectively. Defaults to c("sizea3", "sizea2", "sizea1").

repst

A vector of names of variables coding reproductive status in times t+1, t, and t-1, respectively. Defaults to c("repstatus3", "repstatus2", "repstatus1").

matst

A vector of names of variables coding maturity status in times t+1, t, and t-1, respectively. Defaults to c("matstatus3", "matstatus2", "matstatus1"). Must be supplied if stages is not provided.

fec

A vector of names of variables coding fecundity in times t+1, t, and t-1, respectively. Defaults to c("feca3", "feca2", "feca1").

supplement

An optional data frame of class lefkoSD that provides supplemental data that should be incorporated into the MPM. Three kinds of data may be integrated this way: transitions to be estimated via the use of proxy transitions, transition overwrites from the literature or supplemental studies, and transition multipliers for fecundity. This data frame should be produced using the supplemental() function. Can be used in place of or in addition to an overwrite table (see overwrite below) and a reproduction matrix (see repmatrix below).

repmatrix

A reproduction matrix, which is an optional matrix composed mostly of 0s, with non-zero values for each potentially new individual (row) born to each reproductive stage (column). Entries act as multipliers on fecundity, with 1 equaling full fecundity. Fecundity multipliers provided this way supplement rather than replace those provided in supplement. If left blank, then rlefko3() will assume that all stages marked as reproductive produce offspring at 1x that of fecundity estimated in provided linear models, and that fecundity will be into the first stage noted as propagule or immature. To prevent this behavior, input just 0, which will result in fecundity being estimated only for transitions noted in supplement above. May be the dimensions of either a historical or an ahistorical matrix. If the latter, then all stages will be used in time t-1 for each suggested ahistorical transition.

overwrite

An optional data frame developed with the overwrite() function describing transitions to be overwritten either with given values or with other estimated transitions. Note that this function supplements overwrite data provided in supplement.

yearcol

The variable name or column number corresponding to time in time t in the dataset.

popcol

The variable name or column number corresponding to the identity of the population.

patchcol

The variable name or column number corresponding to patch in the dataset.

indivcol

The variable name or column number coding individual identity.

censorcol

The variable name or column number denoting the censor status. Only needed if censor = TRUE.

censorkeep

The value of the censor variable denoting data elements to keep. Defaults to 0.

format

A string indicating whether to estimate matrices in ehrlen format or deVries format. The latter adds one extra prior stage to account for the prior state of newborns. Defaults to ehrlen format.

reduce

A logical value denoting whether to remove historical stages associated exclusively with zero transitions. These are removed only if all row and column sums in ALL matrices estimated equal 0. Defaults to FALSE.

err_check

A logical value indicating whether to append extra information used in matrix calculation within the output list. Used for development debugging purposes.

Value

If all inputs are properly formatted, then this function will return either an object of class lefkoMat. Output includes:

A

A list of full projection matrices in order of sorted populations, patches, and years. All matrices output in the matrix class.

U

A list of survival transition matrices sorted as in A. All matrices output in the matrix class.

F

A list of fecundity matrices sorted as in A. All matrices output in the matrix class.

hstages

A data frame matrix showing the pairing of ahistorical stages used to create historical stage pairs.

agestages

Set to NA. Only used in output to function aflefko2().

ahstages

A data frame detailing the characteristics of associated ahistorical stages, in the form of a modified stageframe that includes status as an entry stage through reproduction.

labels

A data frame giving the population, patch, and year of each matrix in order.

matrixqc

A short vector describing the number of non-zero elements in U and F matrices, and the number of annual matrices.

dataqc

A vector showing the numbers of individuals and rows in the vertical dataset used as input.

Notes

The default behavior of this function is to estimate fecundity with regards to transitions specified via associated fecundity multipliers in either supplement or repmatrix. If both of these fields are left empty, then fecundity will be estimated at full for all transitions leading from reproductive stages to immature and propagule stages. However, if a supplement is provided and a repmatrix is not, or if repmatrix is set to 0, then only fecundity transitions noted in the supplement will be set to non-zero values. To use the default behavior of setting all reproductive stages to reproduce at full fecundity into immature and propagule stages but incorporate given or proxy survival transitions, input those given and proxy transitions through the overwrite option.

The reproduction matrix (field repmatrix) may be supplied as either historical or ahistorical. If provided as ahistorical, then flefko3() will assume that all historical transitions involving stages noted for times t and t+1 should be set to the respective fecundity multipliers noted.

Users may at times wish to estimate MPMs using a dataset incorporating multiple patches or subpopulations. Should the aim of analysis be a general MPM that does not distinguish these patches or subpopulations, the patchcol variable should be left to NA, which is the default.

Input options including multiple variable names must be entered in the order of variables in time t+1, t, and t-1. Rearranging the order WILL lead to erroneous calculations, and will probably also lead to fatal errors.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
# Lathyrus example
data(lathyrus)

sizevector <- c(0, 100, 13, 127, 3730, 3800, 0)
stagevector <- c("Sd", "Sdl", "VSm", "Sm", "VLa", "Flo", "Dorm")
repvector <- c(0, 0, 0, 0, 0, 1, 0)
obsvector <- c(0, 1, 1, 1, 1, 1, 0)
matvector <- c(0, 0, 1, 1, 1, 1, 1)
immvector <- c(1, 1, 0, 0, 0, 0, 0)
propvector <- c(1, 0, 0, 0, 0, 0, 0)
indataset <- c(0, 1, 1, 1, 1, 1, 1)
binvec <- c(0, 100, 11, 103, 3500, 3800, 0.5)

lathframe <- sf_create(sizes = sizevector, stagenames = stagevector, 
  repstatus = repvector, obsstatus = obsvector, matstatus = matvector, 
  immstatus = immvector, indataset = indataset, binhalfwidth = binvec, 
  propstatus = propvector)

lathvert <- verticalize3(lathyrus, noyears = 4, firstyear = 1988, 
  patchidcol = "SUBPLOT", individcol = "GENET", blocksize = 9, 
  juvcol = "Seedling1988", sizeacol = "Volume88", repstracol = "FCODE88", 
  fecacol = "Intactseed88", deadacol = "Dead1988", nonobsacol = "Dormant1988", 
  stageassign = lathframe, stagesize = "sizea", censorcol = "Missing1988", 
  censorkeep = NA, censor = TRUE)

lathsupp3 <- supplemental(stage3 = c("Sd", "Sd", "Sdl", "Sdl", "Sd", "Sdl", "mat"),
  stage2 = c("Sd", "Sd", "Sd", "Sd", "rep", "rep", "Sdl"),
  stage1 = c("Sd", "rep", "Sd", "rep", "npr", "npr", "Sd"),
  eststage3 = c(NA, NA, NA, NA, NA, NA, "mat"),
  eststage2 = c(NA, NA, NA, NA, NA, NA, "Sdl"),
  eststage1 = c(NA, NA, NA, NA, NA, NA, "NotAlive"),
  givenrate = c(0.345, 0.345, 0.054, 0.054, NA, NA, NA),
  multiplier = c(NA, NA, NA, NA, 0.345, 0.054, NA),
  type = c(1, 1, 1, 1, 3, 3, 1), type_t12 = c(1, 2, 1, 2, 1, 1, 1),
  stageframe = lathframe, historical = TRUE)

ehrlen3 <- rlefko3(data = lathvert, stageframe = lathframe, year = "all", 
  stages = c("stage3", "stage2", "stage1"), supplement = lathsupp3,
  yearcol = "year2", indivcol = "individ")

summary(ehrlen3)

# Cypripedium example
rm(list=ls(all=TRUE))
data(cypdata)

sizevector <- c(0, 0, 0, 0, 0, 0, 1, 2.5, 4.5, 8, 17.5)
stagevector <- c("SD", "P1", "P2", "P3", "SL", "D", "XSm", "Sm", "Md", "Lg",
  "XLg")
repvector <- c(0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1)
obsvector <- c(0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1)
matvector <- c(0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1)
immvector <- c(0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0)
propvector <- c(1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
indataset <- c(0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1)
binvec <- c(0, 0, 0, 0, 0, 0.5, 0.5, 1, 1, 2.5, 7)

cypframe_raw <- sf_create(sizes = sizevector, stagenames = stagevector,
  repstatus = repvector, obsstatus = obsvector, matstatus = matvector,
  propstatus = propvector, immstatus = immvector, indataset = indataset,
  binhalfwidth = binvec)

cypraw_v1 <- verticalize3(data = cypdata, noyears = 6, firstyear = 2004,
  patchidcol = "patch", individcol = "plantid", blocksize = 4,
  sizeacol = "Inf2.04", sizebcol = "Inf.04", sizeccol = "Veg.04",
  repstracol = "Inf.04", repstrbcol = "Inf2.04", fecacol = "Pod.04",
  stageassign = cypframe_raw, stagesize = "sizeadded", NAas0 = TRUE,
  NRasRep = TRUE)

cypsupp3r <- supplemental(stage3 = c("SD", "SD", "P1", "P1", "P2", "P3",
    "SL", "SL", "SL", "D", "XSm", "Sm", "D", "XSm", "Sm", "SD", "P1"),
  stage2 = c("SD", "SD", "SD", "SD", "P1", "P2", "P3", "SL", "SL", "SL",
    "SL", "SL", "SL", "SL", "SL", "rep", "rep"),
  stage1 = c("SD", "rep", "SD", "rep", "SD", "P1", "P2", "P3", "SL", "P3",
    "P3", "P3", "SL", "SL", "SL", "all", "all"),
  eststage3 = c(NA, NA, NA, NA, NA, NA, NA, NA, NA, "D", "XSm", "Sm", "D",
    "XSm", "Sm", NA, NA),
  eststage2 = c(NA, NA, NA, NA, NA, NA, NA, NA, NA, "XSm", "XSm", "XSm",
    "XSm", "XSm", "XSm", NA, NA),
  eststage1 = c(NA, NA, NA, NA, NA, NA, NA, NA, NA, "XSm", "XSm", "XSm",
    "XSm", "XSm", "XSm", NA, NA),
  givenrate = c(0.1, 0.1, 0.2, 0.2, 0.2, 0.2, 0.25, 0.4, 0.4, NA, NA, NA, NA,
    NA, NA, NA, NA),
  multiplier = c(NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,
    0.5, 0.5),
  type = c(1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 3, 3),
  type_t12 = c(1, 2, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1),
  stageframe = cypframe_raw, historical = TRUE)

cypmatrix3r <- rlefko3(data = cypraw_v1, stageframe = cypframe_raw,
  year = "all", patch = "all", stages = c("stage3", "stage2", "stage1"),
  size = c("size3added", "size2added", "size1added"),
  supplement = cypsupp3r, yearcol = "year2", patchcol = "patchid",
  indivcol = "individ")

summary(cypmatrix3r)

lefko3 documentation built on July 22, 2021, 9:10 a.m.