squidR: Run SQuID without graphical user interface

Description

The function simulates a world inhabited by individuals whose phenotypes are generated by a user-defined phenotypic equation and then samples from this world according to a user-defined sampling design. If this is your first experience with SQuID, we highly recommend to start with the interactive SQuID application with graphical interface in order to learn and get more familiarized with the SQuID model and its sampling design (use the function squidApp).

Usage

1
2
squidR(input=list(), plot=FALSE, data=NULL, module=NULL, 
       X_previsualization=NULL)

Arguments

input

A list of the model input parameters (see Details).

plot

logical; If FALSE (default), squidR does not include the simulation plots into the output list (see Value).

data

A data.frame of the full data (the "world") returned by squidR (output$full_data).

module

A character string of the module name. This argument is only used by SQuID app.

X_previsualization

A character string of the environment name. This argument is only used by SQuID app.

Details

A detailed description of the SQuID model and its sampling design is provided on the SQuID app (run SQuID app with squidApp). Reading the SQuID documentation on the SQuID app is prerequisite to use properly the SQuID R function.

The argument input is a list that contains the different input parameters to the SQuID model. All the parameters are listed below including their default value and a short description. If a parameter is not declared within the input list, the default value will be used.

When the full data of a previous squid simulation is passed to squidR through the argument data, squidR does not generate a new world and samples directly into the already existing world.

Value

squidR returns a list that includes a data.frame of the full data generated (the "world"), a data.frame of the sampled data and six ggplot2 plots of the results (only if plot is set to TRUE).

The full and the sampled data could be accessed respectively by output$full_data and output$sampled_data. A description of the columns of the full and the sampled data.frame is provided below:

squidR returns a list that also includes a list (plots) of six ggplot2 plots of the results. Note that the plots display only the data of the first trait, the first replicate and the first 20 individuals of the simulation.

References

Allegue, H., Araya-Ajoy, Y.G., Dingemanse, N.J., Dochtermann N.A., Garamszegi, L.Z., Nakagawa, S., Reale, D., Schielzeth, H. and Westneat, D.F. (2016) SQuID - Statistical Quantification of Individual Differences: an educational and statistical tool for understanding multi-level phenotypic data in the mixed modelling framework. Methods in Ecology and Evolution, submitted manuscript.

Note

If this is your first experience with SQuID, we highly recommend to start with the interactive SQuID application with graphical interface in order to learn and get more familiarized with the SQuID model (phenotypic equation) and its sampling design (use the function squidApp).

See Also

squidApp to run the SQuID app which includes detailed documentation on the SQuID model and its sampling design.

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
## create the input list ##
input <- list()

## define the model input parameters ##

input$Tmax <- 100 # 100 time steps
input$NP   <- 10  # 10 replicated populations
input$NI   <- 20  # 20 individuals per replicate population
input$NT   <- 1   # 1 trait per individual

# in this simulation model, only one environmental gradient (x1) is added

# turn on the environmental gradient x1
input$X1_state      <- TRUE  

# add a stochastic environmental effect to the environmental effect x1
input$X1_sto_state  <- TRUE  

# the stochastic environmental effect included 
# into the environmental effect x1 is not shared among individual. 
# Each individual will experience a  different stochastic environmental effect. 
input$X1_sto_shared <- FALSE                  

#  add an autocorrelation effect to the stochastic 
#  environmental effect within the environmental effect x1.
input$X1_sto_autocor_state <- FALSE 

# define the autocorrelation value between two consecutive time steps.
input$X1_sto_corr          <- 0.5 

# add a linear trend to the environmental effect x1. 
# the default parameters for the linear trend will be used 
# (an intercept of 0, a slope of 1 and the linear trend will be shared among individuals)
input$X1_lin_state <- TRUE 

# define the population mean values vector.
# the population mean (fixed intercept) and
# the population mean response to environmental influences x1 (fixed slope) 
# are set to 0.1.
input$B    <- c(0.1, 0.1, 0, 0)
                                                  
# define the individual variance/correlation matrix (squared matrix; 4x4)
# the individual-specific deviation (random intercept; VI) variance is set to 0.7.
# the individual-specific response to an environmental effect x1 (random slope; VS1) is set to 0.5.
# the correlation between the individual-specific deviation (I) 
# and the individual-specific response 
# to an environmental effect x1 
# (S1) is set to -0.7.                                                     
input$Vind <- matrix(c(0.7  , 0   , 0 , 0,
                       -0.7 , 0.5 , 0 , 0,
                       0    , 0   , 0 , 0,
                       0    , 0   , 0 , 0), 
			nrow=4, byrow=TRUE)
                       
input$Ve  <- 0.05 # the measurement error variance

## define the sampling design ##

# the mean number of records per individual
input$NR     <- 10
# the among-individual variance in timing of sampling
input$Vhsi   <- 0.2
# individuals are not sampled the same number of times.
input$NR_ind <- FALSE 
# individuals are not sampled at the time
input$ST_ind <- FALSE 

## run the simulation ##
output <- squidR(input, plot=TRUE)

# plot the individual phenotype values over time
print(output$plot$totPhen) 

# see first records of the simulated data set
head(output$full_data)

## run a second simulation with the identical world but with a different sampling design 
## where individuals are sampled the same number of times and at the same time    

input$NR_ind <- TRUE # individuals are sampled the same number of times.
input$ST_ind <- TRUE # individuals are sampled at the time

output2 <- squidR(input, plot=TRUE, data=output$full_data)

Questions? Problems? Suggestions? or email at ian@mutexlabs.com.

All documentation is copyright its authors; we didn't write any of that.