timeToSize: Projects how long it takes to get from a starting...
In IPMpack: Builds and analyses Integral Projection Models (IPMs).

Description Usage Arguments Details Value Author(s) References Examples

Provided with a starting vector reflecting starting individual sizes, this function projects forward via the provided IPM until a defined proportion of the population has reach the chosen endSize. Only works for single environment or compound matrices (not time-varying covariates apart from a single discrete one).

1	timeToSize(startingSizes, IPM, endSize, startingEnv = 1, maxT = 100, propReach = 0.01)

`startingSizes`	vector of starting sizes reflecting sizes of individuals in the starting population (in any order).
`IPM`	the IPM Pmatrix.
`endSize`	the end size.
`startingEnv`	vector of starting env, same length as startingSizes, or length = 1 if compound matrices are not being used.
`maxT`	the max number of time steps tested.
`propReach`	the proportion of the starting pop that have to be > than the endSize for it to count.

Plots and returned values of survivorship from preliminary runs will give a notion of how low this has to be.

`ts.dist`	the time-series of size distribution
`time.reach`	the time for n.reach to be at sizes > endSize
`survivorship`	survivorship over the course of the time elapsed for that pop

C. Jessica E. Metcalf, Sean M. McMahon, Roberto Salguero-Gomez, Eelke Jongejans & Cory Merow.

Caswell, 2001. Matrix population models: analysis, construction and interpretation. 2nd ed. Sinauer.

#note that with the "fake data" essentially either takes 
#forever or is immediate...
dff <- generateData()
startSizes <- rnorm(1000, 2.5, 1)
Pmatrix <- makeIPMPmatrix(minSize = 1.2*min(dff$size, na.rm=TRUE),
maxSize = 1.2*max(dff$size, na.rm=TRUE), 
growObj = makeGrowthObj(dff), 
survObj = makeSurvObj(dff))

rc <- timeToSize(startingSizes = startSizes, IPM = Pmatrix, endSize = 6, 
startingEnv = 1, maxT = 1000, propReach = 0.001)

names(rc)

par(mfrow=c(2,2), bty = "l")
## Make picture with lines for distribution of 
## population on different time points
matplot(Pmatrix@meshpoints, rc$ts.dist, type = "l", xlab = "size", 
ylab = "Number of individuals")

## Examine time elapsed for propReach to attain the chosen endSize
rc$time.reach

## Plot out the survivorship
plot(rc$survivorship, type = "l", #log = "y", 
xlab = "time step", ylab = "Probability original population survival", 
ylim = c(0,1), col = "gray")