---
title: "Get started with lagdynamics"
author:
  - "Mohammed Saqr"
  - "Sonsoles López-Pernas"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started with lagdynamics}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", message = FALSE,
                      warning = FALSE, dpi = 150, fig.width = 7,
                      fig.height = 5.6, out.width = "100%",
                      fig.align = "center")
set.seed(1)
library(lagdynamics)
old_options <- options(digits = 3)
has_cograph <- requireNamespace("cograph", quietly = TRUE)
has_ggplot2 <- requireNamespace("ggplot2", quietly = TRUE)
```

This quick start takes one bundled sequence data set from raw rows to a
fitted lag-sequential analysis (LSA) model, tidy transition tables, two
plots, and one uncertainty check.

For the method background, see `vignette("intro", package =
"lagdynamics")`. For a complete applied analysis, see
`vignette("workflow", package = "lagdynamics")`. For all plotting
variants, see `vignette("plotting", package = "lagdynamics")`.

# Fit a model

`engagement` contains weekly engagement states for students. It is a
wide sequence table: each row is one sequence, each column is an ordered
time point, and each cell is a state.

```{r data}
head(engagement)
```

`lsa()` fits the model in one call. It counts state-to-state transitions,
computes expected counts under independence, and reports adjusted
residuals for every `from -> to` transition.

```{r fit}
fit <- lsa(engagement)
fit
```

# Read the result

`transitions()` is the main table. It returns one row per transition with
observed counts, expected counts, transition probabilities, adjusted
residuals, p-values, and significance flags.

```{r transitions}
transitions(fit)
```

Most first reads start with the transitions that depart from chance.

```{r significant}
transitions(fit, significant = TRUE)
```

The companion verbs read the other parts of the same fitted model.

```{r companion-verbs}
nodes(fit)
tests(fit)
initial(fit)
summary(fit)
```

# Plot the model

The default plot is a residual heatmap. Rows are current states, columns
are next states, and colour is the adjusted residual.

```{r heatmap, eval = has_ggplot2}
plot(fit)
```

The network view uses the same residual model: edges show transitions
that are over- or under-represented relative to independence.

```{r residual-network, eval = has_cograph}
plot(fit, type = "network")
```

Use `weights = "tna"` or `weights = "relative"` when the question is the
usual transition-network question: where does the process tend to go
next?

```{r tna-network, eval = has_cograph}
plot(fit, type = "network", weights = "tna")
```

# Check uncertainty

Adjusted residuals test departures from independence in the fitted
table. Edge-level claims should also report uncertainty. The analytic
certainty estimator gives credible intervals for transition
probabilities without resampling.

```{r certainty}
cert <- certainty_lsa(fit)
cert
transitions(cert) |> head(4)
```

For resampling-based edge uncertainty, use `bootstrap_lsa()`. For
whole-network reproducibility, use `reliability_lsa()` and
`stability_lsa()`. For empirical null comparisons, use `permute_lsa()`
or `compare_lsa()`. These are covered in
`vignette("confirmatory", package = "lagdynamics")`.

# Where next

Use the focused vignettes according to the claim you need to support:

- `vignette("intro", package = "lagdynamics")` for concepts and package
  map.
- `vignette("workflow", package = "lagdynamics")` for a full
  claim-to-evidence analysis.
- `vignette("interop", package = "lagdynamics")` for wide data, long
  logs, `tna`, `Nestimate`, `cograph`, and `lsa_to_tna()`.
- `vignette("plotting", package = "lagdynamics")` for heatmaps,
  networks, chords, sunbursts, and comparison plots.
- `vignette("confirmatory", package = "lagdynamics")` for certainty,
  bootstrap, reliability, stability, permutation, and group comparison.
- `vignette("lag-transition-networks", package = "lagdynamics")` for
  TNA-style transition networks.

```{r cleanup, include = FALSE}
options(old_options)
```