fit_pheno_cline: Fit a phenotypic 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 phenotypic data. The phenotypic cline models in BAHZ assume that phenotypes are normally distributed.

1 2	fit_pheno_cline(data, prior_file, pheno_variance = "constant", chains = 4, init = NULL, ignore_data = F, ...)

`data`	A dataframe containing your cline data. See `prep_pheno_data` for possible formats.
`prior_file`	The path to the `.yaml` file which contains the specifications of the priors.
`pheno_variance`	The method used to estimate phenotypic variance. Either "constant" (the default), "pooled", or "independent". If "constant", bahz estimates a single, constant phenotypic variance across all sites (global_sigma). If "independent", bahz estimates phenotypic variance independently at each site (site_sigma). If "pooled", bahz uses a hierarchical model which shares information across sites to estimate both the average phenotypic variance (global_sigma) and site-specific variances (site_sigma). The site-specific variances are assumed to be normally distributed around the global_sigma with their own variance, which is estimated (sigma_sigma).
`chains`	The number of MCMC chains to create. Numeric, coerced to integer. Default is 4.
`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.
`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.
`...`	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_pheno_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_pheno_data, prep_prior_list, prep_init_list, sampling

## Not run: 
# Fit a phenotypic cline
# Uses default number of chains and stan parameters.
results <- fit_pheno_cline(clinedata, "prior_file.yaml")

# Fit a phenotypic cline
# 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_pheno_cline(clinedata, "prior_file.yaml",
                     chains = 5,
                     iter = 8000, warmup = 4000)

## End(Not run)