samplesim: Effect of sample size in stable isotope mixing models

In ahasverus/SampleSim: Sample Size Effects in Stable Isotope Mixing Solutions

Description

This function allows investigating the effect of sample size on estimates and precision of stable isotope mixing solutions. User can modify the sample size for one chosen source, for all sources or for the consumer. See details section for further information.

Usage

samplesim(
  package = "siar",
  mix,
  source,
  discr,
  type = NULL,
  nsamples = NULL,
  modify = NULL,
  nrep = 100,
  interval = 90,
  name = NULL,
  resid_err = TRUE,
  process_err = FALSE,
  run = "test",
  alpha.prior = 1,
  path = "."
)

Arguments

package	a character of length 1. The package name to be used to estimate mixing proportions. Must be one of 'siar' (default) or 'mixsiar'.
mix	a named list. The output returned by the MixSIAR::load_mix_data() function and containing consumer isotope values.
source	a named list. The output returned by the MixSIAR::load_source_data() function and containing mean and standard deviation isotope values of sources (and in some case raw values).
discr	a named list. The output returned by the MixSIAR::load_discr_data() function and containing discrimination values.
type	a character of length 1 indicating the type of analysis to run. Must be one of 'one source', 'all sources' or 'consumer'.
nsamples	a numeric vector with the sample sizes to simulate.
modify	a character of length 1. The source name to modify (case sensitive). This argument has to be specified when type = 'one source'. Otherwise it will be ignored.
nrep	an integer of length 1 specifying the number of replicates for each sample sizes. Default is 100.
interval	an integer of length 1 indicating the width of credible interval to use for precision estimation. Default is 90.
name	a character of length 1 giving the name of the simulation. If NULL (default) the simulation will be named by the time of the simulation. This name will serve to create a directory in which results will be stored.
resid_err	a logical value indicating if residual error is included in the model. See MixSIAR::run_model() for further information. Only necessary if package = 'mixsiar'.
process_err	a logical value indicating if process error is included in the model. See MixSIAR::run_model() for further information. Only necessary if package = 'mixsiar'.
run	a character string or a list specifying MCMC parameters. See MixSIAR::run_model() for further information. Only necessary if package = 'mixsiar'.
alpha.prior	a numeric of length 1 specifying the Dirichlet prior on p.global. See MixSIAR::run_model() for further information. Only necessary if package = 'mixsiar'.
path	a character string of length 1. The directory to save results. This directory must exist and can be an absolute or a relative path. Default is the current working directory.

Details

This function assesses the sensitivity of isotopes mixing models to variation in numbers of samples from source tissues. This tool can be used prior to full-blown studies in a similar manner than power analyses. It used the function siar::siarmcmcdirichletv4(). Alternatively, it can be used with the function MixSIAR::run_model(). User can choose to sample one particular source (argument type sets to 'one source') or all the sources in the same type (argument type sets to 'all sources'). User can also choose to modify consumer data (argument type sets to 'consumer'). Sample sizes are modified assuming a normal distribution with a user defined mean and standard deviation. Samples of different sizes are created from this distribution, and mixing proportions are estimated for several replicates of each sample size with the function siar::siarmcmcdirichletv4() or MixSIAR::run_model().

Value

This function does not return any object in the R console. Results are stored in a directory (argument name) and contain four R objects:

• intervals: a four dimensions array with the upper and lower bounds of the credible interval for each sample size, replicate and source. First dimension represents lower and upper bounds; second dimension corresponds to the number of sources; third dimension is the number of replicates; and fourth dimension is the number of sample size.

• widths: a three dimensions array with the width (precision) of credible intervals for each source, each replicate and each sample size. First dimension corresponds to the number of replicates; second dimension is the number of sources; and third dimension represents the number of sample size.

• medians: a three dimensions array with the median (estimate) of credible intervals for each source, each replicate and each sample size. Dimensions are the same as for widths object.

• datasets: a four dimensions array with all re-sampled datasets.

A log file is also written and contains all parameters of the simulation.

References

Lecomte N., Ehrich D., Casajus N., Berteaux D., Cameron C., and Yoccoz N.G. How many is enough? An R package for evaluating the effect of sample size on estimates and precision of stable isotope mixing solutions. Submitted to Methods in Ecology and Evolution.

See Also

get_output(), plot_samplesim(), plot_isospace()

Examples

## Not run: 
## Please visit the vignette available at: 
## https://ahasverus.github.io/samplesim/articles/samplesim.html

## End(Not run)

ahasverus/SampleSim documentation built on July 7, 2021, 1:17 a.m.