STAN Models for bbsBayes

[steffilazerte]

This pull request contains extensive development to include (among other things) models built with STAN rather than JAGS.

Current framework to ensure that functionality is maintained and we (hopefully) do not introduce bugs!

• Tidying existing functions to ensure consistency (XXX_tidy())
• Modifying tidied functions to use Stan model outputs (get the original function name XXX())
• Once finished, original and tidied functions will be omitted (but right now are XXX_orig())

Stage: Cleaning and Scrubbing
Working to clean up existing code, solidify checks and tests and add documentation

Progress

• New core functionality
  • Update functions to handle Stan models via cmdstanr
    • generate_trends(), generate_indices(), plot_map() (was generate_map()), plot_geofacet() (was geofacet_plot()), plot_indices()
    • model_to_file()
  • Add functionality for spatial modelling (i.e. prepare_spatial())
  • Add convergence checks (i.e., convergence())
  • Add option to provide custom stratification
• Best Practices
  • Function tests and code coverage indicators
  • Tidying
  • Deprecate/defunct functions and arguments gracefully
  • Best practices (goodpractices)
  • Passing checks
• Last to-dos
  • n_route and n_routes_total should update if strata excluded
  • obs_mean should be zero in indices if obs were missing in prior years
• Documentation
  • Update function references
  • Vignettes
    • Stratification / Data prep
    • Model Choice
    • Results and summaries (annual indices, trend-estimates and maps)
• Ready for Release
  • Update sample data to 2020 (update tests accordingly)
  • Checks (notes etc. )
  • Deal with location of BBS data (use CRAN best practices)
  • Deal with location of compiled model files
  • Deal with any potentially fragile or long running tests
  • Deal with any potentially fragile or long running examples
  • Host on R-Universe

[steffilazerte]

@AdamCSmithCWS I'm working on getting the STAN models all working with their options (then I'll tackle the spatial models). The jags models seem to include four (slope, firstdiff, gam, gamye), but the original stan models only two (non-spatial: slope and gamye).

Will there be four regular STAN models eventually? Or are the firstdiff and gam models either not relevant or incorporated into the existing models?

[AdamCSmithCWS]

@AdamCSmithCWS I'm working on getting the STAN models all working with their options (then I'll tackle the spatial models). The jags models seem to include four (slope, firstdiff, gam, gamye), but the original stan models only two (non-spatial: slope and gamye).

Will there be four regular STAN models eventually? Or are the firstdiff and gam models either not relevant or incorporated into the existing models?

Yes. Sorry. I will push versions of the firstdiff and gam two models within the next two days.

[AdamCSmithCWS]

@AdamCSmithCWS I'm working on getting the STAN models all working with their options (then I'll tackle the spatial models). The jags models seem to include four (slope, firstdiff, gam, gamye), but the original stan models only two (non-spatial: slope and gamye).
Will there be four regular STAN models eventually? Or are the firstdiff and gam models either not relevant or incorporated into the existing models?

Yes. Sorry. I will push versions of the firstdiff and gam two models within the next two days.

@steffilazerte:
My bbsStanBayes repo now includes the first difference models (spatial and non). Note: they won't generate estimates that directly match the JAGS version of the firstdifference models. These versions are hierarchical versions that share information among strata, the JAGS versions were not. This represents an elaboration (improvement) on the earlier models and I'm not sure it's worth adding the original version. The one benefit of having the non-hierarchical version (to match the JAGS version) is that this non-hierarchical version is what the USGS still uses. Perhaps we should discuss this. If we were to add the original non-hierarchical version, there would have to be 3 first-difference models...

EDITED: gam models are now in the bbsStanBayes repo

[AdamCSmithCWS]

All of the bbsBayes models are now translated to Stan in the bbsStanBayes repo.
In addition, I added a version of the first difference model that matches the USGS implementation. I've called it a NonHierarchical version of the model. The code to run it is now in the same R script as for the other first difference models. It includes a boolean object Non_hierarchical <- TRUE object defined in the script that sets everything up correctly.

Having this 3rd option for the first difference model is a bit of a departure from the original plan. I wonder if it's worth the extra effort so that users can replicate the USGS analysis.
Thoughts?