---
title: "Analysis Manifests and Reproducible Bayesian Workflows"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Analysis Manifests and Reproducible Bayesian Workflows}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## A manifest is an analysis contract about the analysis contract

A fitted model is not enough to reconstruct an analysis decision process.
`gp3bayes` 0.2.0 therefore provides an analysis manifest that records the
approved model contract, preparation/transformation record, specification,
prespecified estimands, sensitivity plan, seed, backend metadata, software
versions, and a fingerprint of the analysis data.

The manifest stores a fingerprint rather than duplicating the analysis data.
It is provenance metadata, not a hidden data archive.

## Create a manifest before fitting

```{r}
simulation <- simulate_hierarchical_binary_data(
  n_participants = 10,
  trials_per_participant = 8,
  n_items = 5,
  random_slope_sd = 0,
  seed = 42
)

contract <- create_model_contract(
  "binary", "selected", "participant_id",
  item_col = "item_id",
  trial_col = "trial_id",
  condition_col = "condition"
)

prepared <- prepare_hierarchical_binary_data(
  simulation$data,
  contract,
  condition_levels = c("control", "treatment")
)

specification <- specify_binary_model(prepared, baseline = 0.35)

manifest <- create_analysis_manifest(
  specification = specification,
  estimands = "standardized_probability_contrast",
  seed = 2026,
  label = "Synthetic binary release case"
)

manifest
analysis_manifest_table(manifest)
validate_analysis_manifest(manifest)
```

## Freeze only when the analysis-defining fields are ready

Freezing computes a manifest hash. With `file = NULL`, no file is written.

```{r}
frozen <- freeze_analysis_manifest(manifest)
frozen
```

Writing is always explicit. Temporary files are used here so the vignette does
not write into the package or working directory.

```{r}
manifest_file <- tempfile(fileext = ".rds")
report_file <- tempfile(fileext = ".md")

freeze_analysis_manifest(manifest, file = manifest_file)
restored <- read_analysis_manifest(manifest_file)
write_reproducibility_report(restored, report_file)

file.exists(manifest_file)
file.exists(report_file)

unlink(c(manifest_file, report_file))
```

## Compare analysis provenance

A difference is reported, not judged automatically.

```{r}
alternative <- create_analysis_manifest(
  specification = specification,
  estimands = "standardized_probability_contrast",
  seed = 2027,
  label = "Alternative seed"
)

comparison <- compare_analysis_manifests(manifest, alternative)
comparison
plot(comparison)
```

This comparison is particularly useful during revisions, refits, or a package
upgrade: it makes changes to the data fingerprint, transformations, priors,
estimands, seed, backend settings, or software environment visible without
pretending that every difference is scientifically consequential.