In jsocolar/flocker: Flexible Occupancy Estimation with Stan

This document provides a guide to how families are treated in flocker through the lens of everything that needs to happen in order to add a new family.

Data formatting and model fitting

1. Add the custom family to occupancy_families.R
2. Add a function to output the relevant Stan code in make_occupancy_lpmf.R
3. If the Stan code requires any data that is not already available in one of the formats output by make_flocker_data(), modify make_flocker_data() to enable this output. Check with flocker package maintainers before doing this, as complicated new options might be better suited to getting their own, separate formatting functions rather than adding more arguments and complexity to make_flocker_data().
4. If modifiying make_flocker_data(), name the new output type and add to flocker_data_output_types() in utils.R. Update flocker_data_type_lookup(). If appropriate, add to rep_constant_types(), threading_types(), or multi_types().
   • If introducing new column names in the output of make_flocker_data(), add them to flocker_col_names() in utils.R.
   • If requiring any new data input format in make_flocker_data(), name the input format and add to flocker_data_input_types() in utils.R.
5. In utils.R, add the new model type to flocker_model_types() and to params_by_type(). There should be a separate entry for every family.
6. In flock.R, modify flock_() to handle the new family.
   • Make sure that flock_() assigns good distinguishing attributes to the outputted flocker_fit object, identifying the important aspects of the family.
   • If any new arguments to flock_() are required, modify all functions in flock.R to pass the new arguments properly.
7. In utils.R, update validate_flock_params() and any relevant helper functions beginning with validate_ to handle new arguments in flock() or new options in the arguments to flock().
8. Look over all other functions in flock.R and make sure that no changes are required.

Model processing

1. Update fitted_flocker() in fitted_flocker.R:
   • If there are any new distributional parameters, add those options.
   • Make sure that the return from fitted_flocker conforms to the shape of the data passed to make_flocker_data(obs = ...). That is, fitted_flocker() should always return linear predictors shaped like obs, with posterior iterations and/or summaries stacked along the $n+1$th dimension.
2. Update get_Z() in get_Z.R
3. Log_lik
4. Loo
5. Predict_flocker

Documentation

1. Update simulate_flocker_data() in simulate_flocker_data.R to enable accurate simulation from the new model.
2. Make sure that the new family is treated in one of the vignettes. In some cases, this can be very lightweight (for example, if we add false positive autologistic models, then we probably just need to change a single sentence in the fp models vignette).
3. Optionally, if the vignette uses data that are not readily simulated via simulate_flocker_data() (e.g. if illustrating the family's capabilities requires more/different covariates than simulate_flocker_data() provides), create an example dataset in the data folder, put the script to generate the dataset in data.R, and document appropriately.

jsocolar/flocker documentation built on Jan. 29, 2025, 11:18 p.m.