fit_geno_cline: Fit a genetic cline model to your data
In tjthurman/BAHZ: Bayesian Analysis of Hybrid Zones

Description Usage Arguments Details Value See Also Examples

Use Rstan to fit Bayesian hybrid zone cline models to genetic data.

1
2
3

fit_geno_cline(data, prior_file, type = c("bi", "multi"),
  tails = c("none", "left", "right", "mirror", "ind"), chains = 4,
  ignore_data = FALSE, init = NULL, ...)

`data`	A dataframe containing your cline data. See `prep_geno_data` for possible formats.
`prior_file`	The path to the `.yaml` file which contains the specifications of the priors.
`type`	The type of model to fit. Either "bi", for a binomial model of allele frequencies, or "multi" for a multinomial model of genotype frequencies.
`tails`	Which type of tails for the model: "none", "left", "right", "mirror", or "ind"?
`chains`	The number of MCMC chains to create. Numeric, coerced to integer. Default is 4.
`ignore_data`	Used for doing prior predictive checks. If FALSE, the default, the model is fit normally. If TRUE, the data are ignored during model fitting. This is useful for double-checking the prior distributions or parameters, and for doing prior predictive checks of the model.
`init`	Optional, default is `NULL`. A user-provided list of initialization values for `stan`, to be used instead of the `bahz` default of random initialization values from the prior. See `stan` for details on how to specify the init list.
`...`	Arguments to be passed to `stan`, e.g., number of iterations, warmup period, etc. See `sampling` and the `control` argument in `stan` for information on these arguments, and the details below for information on how bahz defaults interact with stan defaults.

This is a wrapper function, which calls various data- and model-preparation functions from bahz before passing the results to the sampling function in rstan, which does the MCMC model fitting. Specifically, this function calls:

prep_geno_data to format the provided data.
prep_prior_list, which creates a list containing the specifications of the prior distributions, to be passed to Stan. It creates the priors according to the configuration file prior_file.
prep_init_list, which creates a list of values for initialiing the MCMC chains in stan. Initial values are randomly drawn from the priors specified in prior_file. This step is ignored if the user supplies an initialization list with the init argument.

The results of these functions are then passed to sampling, along with any additional stan arguments supplied by the user. In most cases, these additional stan arguments should be unnecessary. bahz uses the default stan arguments for all sampler parameters expect for one: the default adapt_delta for bahz is 0.95, to better avoid divergent transitions. Note that supplying ANY stan arguments will override ALL bahz defaults. E.g., specifying a different number of total iterations will reset the adapt_delta to the stan default of 0.8.

A stanfit object containing your model results.

prep_geno_data, prep_prior_list, prep_init_list, sampling

## Not run: 
# Fit a multinomial cline
# with mirrored introgression tails.
# Uses default number of chains and stan parameters.
results <- fit_geno_cline(clinedata, "prior_file.yaml",
                     type = "multi", tails = "mirror")

# Fit a binomial cline
# with no introgression tails.
# Use 5 chains with 4000 warmup iterations
# and 8000 total iterations per chain.
# Note that this changes the adapt_delta to
# the stan default of 0.8

results2 <- fit_geno_cline(clinedata, "prior_file.yaml",
                     type = "bi", tails = "none",
                     chains = 5,
                     iter = 8000, warmup = 4000)

## End(Not run)