---
title: "Reproducibility workflow"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Reproducibility workflow}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

This vignette shows how to make power analyses reproducible: capture a manifest (scenario fingerprint, seed, session info), bundle results with metadata and labels, export to CSV/JSON, and use the manifest to regenerate the same outputs.

```{r}
library(mixpower)
```

## Run analysis and capture manifest

Run your analysis as usual and create a manifest from the same scenario and seed you used. The manifest records a scenario digest (so you can verify the same design/assumptions later), seed strategy, R and mixpower versions, optional session info, and git SHA when in a repo.

```{r}
d <- mp_design(clusters = list(subject = 30), trials_per_cell = 4)
a <- mp_assumptions(
  fixed_effects = list(`(Intercept)` = 0, condition = 0.3),
  residual_sd = 1,
  icc = list(subject = 0.1)
)
scn <- mp_scenario_lme4(
  y ~ condition + (1 | subject),
  design = d,
  assumptions = a,
  test_method = "wald"
)

seed <- 123
res <- mp_power(scn, nsim = 20, seed = seed)
manifest <- mp_manifest(scn, seed = seed, session = FALSE)
manifest
```

## Bundle results and export

Combine the result, manifest, and optional labels into a single bundle. Then write a publication-ready table (and, for JSON, manifest and labels) to disk.

```{r}
bundle <- mp_bundle_results(
  res,
  manifest,
  study_id = "power_2024_01",
  analyst = "analyst",
  notes = "Initial power run for condition effect"
)
bundle
```

```{r}
tab <- mp_report_table(bundle)
tab
```

```{r eval = FALSE}
mp_write_results(bundle, "power_results.csv", format = "csv", row.names = FALSE)
mp_write_results(bundle, "power_results.json", format = "json")
```

(Export is skipped in the vignette to avoid writing to the user's working directory.)

## Regenerating from manifest and seed

To reproduce the same run later:

1. Restore the same scenario (design, assumptions, formula, test). The manifest's `scenario_digest` is a fingerprint of formula, design, assumptions, and test; you can recompute it with `mp_manifest(scn, session = FALSE)$scenario_digest` and compare to the stored value.
2. Use the same seed from the manifest: `mp_power(scn, nsim = 20, seed = manifest$seed)`.
3. Use the same `nsim`, `alpha`, and `failure_policy` as in the original run (store these in your notes or in the bundle labels if needed).

Example: re-run with the stored seed and confirm the power estimate matches.

```{r}
res2 <- mp_power(scn, nsim = 20, seed = manifest$seed)
all.equal(res$power, res2$power)
```

## One-row manifest for saving

You can flatten the manifest to a one-row data frame (e.g. to append to a log) by building it from the list, omitting the long `session_info` if desired:

```{r}
m <- mp_manifest(scn, seed = 123, session = FALSE)
df_row <- data.frame(
  scenario_digest = m$scenario_digest,
  seed = m$seed,
  seed_strategy = m$seed_strategy,
  timestamp = m$timestamp,
  r_version = m$r_version,
  mixpower_version = m$mixpower_version,
  git_sha = m$git_sha,
  stringsAsFactors = FALSE
)
df_row
```