#### Getting Started with Single-Species Occupancy Models

This dashboard supports two workflows for fitting occupancy models: Basic and Advanced. Both use the same underlying statistical methods but offer different levels of control over model specification.

#### Choosing Your Workflow

- Basic Workflow: Best for standard analyses and newcomers to occupancy modeling
  - Simple linear effects of covariates
  - Streamlined model specification
  - Quick model comparison
- Advanced Workflow: For complex analyses requiring:
  - Quadratic effects
  - Interaction terms
  - Random effects
  - Fine control over model structure

#### Basic Workflow Guide

1. Model Setup
   - Choose between 'unmarked' (faster) and 'ubms' (Bayesian) packages
   - Select model type: Occupancy or Royle-Nichols
   - Optionally scale covariates (recommended)
   - Select detection covariates (including effort if desired)
   - Select occupancy covariates
2. Model Selection
   - Run multiple models with different covariate combinations
   - Add models to model selection table
   - Compare using AIC (unmarked) or elpd (expected log pointwise predictive density, in ubms)
3. Response Plots
   - Visualize relationships between covariates and detection/occupancy
   - Adjust confidence levels
   - Compare detection vs. occupancy effects
4. Spatial Predictions
   - Generate prediction maps using extracted covariates or custom rasters
   - View uncertainty in predictions
   - Export results for further analysis or visualization in GIS software

#### Advanced Workflow Guide

1. Model Setup
   - Same package and model type options as Basic workflow
   - Add effects one at a time with more options:
     - Linear effects (standard relationship)
     - Quadratic effects (unimodal relationships)
     - Interactions (combined effects of two covariates)
     - Random effects (for grouped or nested data)
   - Preview formula before fitting
2. Results & Diagnostics
   - Detailed model summaries
   - MCMC diagnostics for ubms models
   - Trace plots for convergence checking
3. Effect Visualization
   - Response curves for each effect type
   - Separate plots for detection and occupancy

#### Tips and Best Practices

- General Tips
  - Start with the Basic workflow unless you need Advanced features
  - Scale covariates to improve model convergence (especially with large absolute covariate values)
  - Include effort as a detection covariate
  - Check for correlations between covariates before modeling (section "Data Processing" > "Covariate Correlation")
- Model Selection
  - Start with simple models and gradually add complexity
  - Use AIC/elpd to compare models formally
  - Consider biological significance alongside statistical significance
- MCMC Settings (ubms)
  - Increase iterations if chains haven't converged
  - Use multiple chains to assess convergence
  - Check trace plots for mixing
  - Adjust thinning if autocorrelation is high (recommended value for thinning is 1 though, see ?stan_occu)

#### Common Issues

- Model Convergence
  - Non-convergence often indicates insufficient data for complex models
  - Ensure adequate detections for reliable parameter estimation
- Prediction Issues
  - Ensure prediction rasters match the scale of model covariates (if not using extracted rasters created by dashboard - dashboard handles scaling of prediction rasters automatically)
  - Check for missing values in prediction surfaces
  - Be cautious about predicting beyond the range of observed covariates

#### Relevant functions

- `ubms::stan_occu`
- `unmarked::occu`