---
title: "Getting Started with ecoGLMM"
author: "André Felipe Carneiro dos Santos, Bruna Martins Bezerra, and Bárbara Lins Caldas de Moraes"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with ecoGLMM}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = TRUE
)

library(ecoGLMM)
```

## Overview

`ecoGLMM` provides a reproducible workflow for fitting and comparing ecological
generalized linear mixed models. For each response and environmental predictor,
the package can fit an additive model and a model containing an interaction with
a temporal factor. Candidate models are compared using AICc, and the selected
models can be summarized, diagnosed, plotted, and exported.

This vignette presents a complete analysis with simulated data. The lightweight
model example is evaluated when the vignette is built, whereas computationally
intensive diagnostics and file exports are displayed without being run. Users
can copy and run every example in an interactive R session.

## Install and load the package

```{r installation, eval=FALSE}
# Install the CRAN version when available:
install.packages("ecoGLMM")

# Install the development version from GitHub:
# install.packages("remotes")
remotes::install_github("andre-fcsantos/ecoGLMM", upgrade = "never")

library(ecoGLMM)
```

## Required data structure

The input must be a data frame with:

- one or more numeric response columns;
- numeric environmental predictors;
- a temporal factor, such as sampling period;
- a grouping variable for the random intercept, such as site.

The final analysis data must contain all these columns in the same data frame.
The generic template can import either one analysis-ready table or separate
acoustic and environmental tables. In separate mode, it validates the join keys
and combines the tables without changing the number of acoustic observations.

Each row of the resulting data set represents one observation. The example below
creates 150 observations from 10 sites and five sampling periods.

```{r simulate-data}
set.seed(123)

sites <- paste0("Site_", seq_len(10))
period_levels <- c("T-0", "T-1", "T-2", "T-3", "T-4")

example_data <- expand.grid(
  site = sites,
  period = period_levels,
  replicate = seq_len(3),
  stringsAsFactors = FALSE
)

n <- nrow(example_data)
example_data$forest <- runif(n, 10, 95)
example_data$urban <- runif(n, 0, 60)

site_effect <- rnorm(length(sites), 0, 0.25)
names(site_effect) <- sites

linear_predictor <-
  -0.5 +
  0.015 * example_data$forest -
  0.012 * example_data$urban +
  site_effect[example_data$site]

example_data$acoustic_index <- plogis(
  linear_predictor + rnorm(n, 0, 0.35)
)

example_data$acoustic_index <- adjust_beta(example_data$acoustic_index)

head(example_data)
```

## Configure the responses

The configuration object requires the columns `response` and `family`. An
optional `label` column provides a readable name for tables and figures.

Supported family names are `"beta"`, `"gamma"`, `"gaussian"`,
`"poisson"`, and `"nbinom2"`.

```{r configuration}
response_config <- data.frame(
  response = "acoustic_index",
  family = "beta",
  label = "Simulated acoustic index"
)
```

For ecoacoustic analyses, `prepare_acoustic_indices()` can transform NDSI from
the interval [-1, 1] to (0, 1) and move boundary values away from zero and one
before beta regression.

```{r acoustic-preparation, eval=FALSE}
# analysis_data <- prepare_acoustic_indices(
#   data = raw_data,
#   ndsi = "NDSI",
#   beta_responses = c("AEI", "ACT"),
#   ndsi_output = "NDSI_beta"
# )
```

## Run the candidate-model analysis

Here, additive and period-interaction models are fitted separately for
`forest` and `urban`. Predictors are standardized by default. All candidate
models use the same complete-case data set, allowing valid AICc comparisons.

```{r run-analysis}
fit <- run_ecoglmm(
  data = example_data,
  config = response_config,
  predictors = c("forest", "urban"),
  period = "period",
  group = "site",
  period_levels = period_levels,
  standardize = TRUE,
  complete_cases = TRUE,
  include_additive = TRUE,
  include_interactions = TRUE,
  competitive_delta = 2
)

fit
summary(fit)
```

## Inspect selection and coefficients

```{r inspect-results}
fit$selection$acoustic_index
fit$interaction_tests$acoustic_index
fit$coefficients
fit$preparation
```

A model with the smallest AICc is ranked first. Models with
`Delta_AICc <= 2` are marked as competitive. Akaike weights express relative
support within the candidate set. The likelihood-ratio tests compare the nested
additive and interaction models for each predictor.

The columns `R2_marginal` and `R2_conditional` are calculated with
`MuMIn::r.squaredGLMM()`. Alternative estimates from
`performance::r2_nakagawa()` are provided in columns ending in
`_performance`.

## Run residual diagnostics

```{r diagnostics, eval=FALSE}
diagnostics <- diagnose_models(
  fit,
  nsim = 1000,
  seed = 123
)

diagnostics$summary

# Inspect the DHARMa residual plot:
plot(diagnostics$residuals$acoustic_index)
```

The summary reports uniformity, dispersion, and outlier tests. A `"Passed"`
status means that all three p-values exceed 0.05; it does not replace graphical
inspection or ecological judgment.

## Create figures

```{r figures}
plot_effect(fit, "acoustic_index")
plot_selection(fit, "acoustic_index", metric = "delta")
plot_selection(fit, "acoustic_index", metric = "weight")
plot_coefficients(fit)
```

## Export the analysis

```{r export, eval=FALSE}
exported_files <- export_ecoglmm(
  object = fit,
  path = file.path(tempdir(), "ecoGLMM_results"),
  diagnostics = diagnostics,
  figures = TRUE
)

exported_files
```

The output directory contains an Excel workbook with the overview,
coefficients, model-selection results, interaction tests, and diagnostics. When
`figures = TRUE`, publication-quality PNG files are also created. When a
diagnostics object is supplied, `DHARMa_diagnostics.pdf` is generated with the
residual panels and a formal-test summary for every selected response model.

## Use the complete generic analysis template

The installed package includes a complete generic template that accepts either
one analysis-ready table or separate acoustic and environmental tables in CSV
or Excel format. When separate files are used, the template joins them by a
user-defined site key and checks for duplicated or unmatched values. The example
uses fictional column names and does not contain data or settings from any
unpublished study.

Locate, copy, and open an editable version of the template with:

```{r locate-template, eval=FALSE}
template_path <- system.file(
  "examples",
  "ecoGLMM_template.R",
  package = "ecoGLMM"
)

if (!nzchar(template_path) || !file.exists(template_path)) {
  stop("The generic analysis template was not found in the installed package.")
}

template_copy <- file.path(tempdir(), "ecoGLMM_template.R")

copied <- file.copy(
  from = template_path,
  to = template_copy,
  overwrite = TRUE
)

if (!copied || !file.exists(template_copy) || file.size(template_copy) == 0) {
  stop("The generic analysis template could not be copied correctly.")
}

if (interactive()) {
  file.edit(template_copy)
}

template_copy
```

For a persistent copy, choose your own writable destination instead of `tempdir()`.
Edit only Section 01 of the copied file before running the complete script.
The full template is reproduced below directly from the file distributed with
the package, ensuring that the vignette and script remain synchronized.

```{r display-generic-template, echo=FALSE, results="asis"}
template_path <- system.file(
  "examples",
  "ecoGLMM_template.R",
  package = "ecoGLMM"
)

if (!nzchar(template_path)) {
  stop("The generic analysis template was not found in the installed package.")
}

template_code <- readLines(template_path, warn = FALSE)

cat(
  "```r\n",
  paste(template_code, collapse = "\n"),
  "\n```\n",
  sep = ""
)
```

Users should adapt file paths, column mappings, responses, distributions,
predictors, temporal levels, output folders, and analysis options only in their
own copy. After changing any setting, run the script again from Section 01.

For two input tables, set `INPUT_MODE <- "separate"` and provide the exact
join-column name used by each table. The template verifies uniqueness in the
environmental table, reports unmatched keys, preserves the original acoustic-row
order, removes configured non-analytical columns, and confirms the final column
names.

For ecoacoustic data requiring NDSI and beta-response preparation, set
`PREPARE_ACOUSTIC_INDICES <- TRUE` in Section 01. The corresponding column
names and boundary adjustment can be configured without editing the processing
code. If the option is left disabled while the configured NDSI output is
requested, the template returns a targeted instruction instead of a generic
missing-column error.

## Preflight checks and predictor redundancy

Before fitting any model, the generic template checks that configured response
and predictor columns are numeric and finite, that predictors are not constant,
and that group and period variables contain at least two observed levels. It
also verifies that response values satisfy the selected distribution: beta
responses must lie strictly between zero and one, Gamma responses must be
positive, and Poisson or negative-binomial responses must be non-negative
integers.

When `CHECK_PREDICTOR_CORRELATIONS <- TRUE`, the template calculates all
pairwise correlations among the environmental predictors. The method and
warning threshold are controlled in Section 01:

```{r correlation-settings, eval=FALSE}
CHECK_PREDICTOR_CORRELATIONS <- TRUE
CORRELATION_METHOD <- "spearman"
CORRELATION_THRESHOLD <- 0.70
```

This screen is descriptive. It warns when two predictors may represent
redundant ecological hypotheses, but it never removes variables or changes the
candidate set. Classical variance inflation factors (VIF) are not calculated
because ecoGLMM currently fits one environmental predictor per candidate model;
VIF diagnoses collinearity among multiple predictors included in the same
model. If multivariable candidate models are added in a future release, VIF or
a comparable conditional-collinearity diagnostic should be assessed for those
models.

The template saves `data_quality.csv`, `predictor_correlations.csv`, and
`preflight_checks.rds` beside the regular model outputs so the checks can be
reported and reproduced.

## Reproducibility recommendations

- Preserve the original data and analyse a separate working copy.
- Record the response distribution selected for each ecological index.
- Keep `complete_cases = TRUE` when comparing models by AICc.
- Inspect convergence messages and DHARMa plots, not only p-values.
- Report the candidate set, AICc, delta AICc, Akaike weights, coefficients,
  confidence intervals, and marginal and conditional R-squared.
- Save `sessionInfo()` with the exported results.