## ----include = FALSE----------------------------------------------------------
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(magentabook)

## -----------------------------------------------------------------------------
toc <- mb_theory_of_change(
  inputs     = c("GBP 50m grant", "12 FTE programme team",
                 "Partnership with Jobcentre Plus"),
  activities = c("Design training curriculum",
                 "Deliver workshops in 50 sites",
                 "Provide ongoing mentoring"),
  outputs    = c("500 workshops delivered",
                 "8000 attendees",
                 "5000 completed mentoring blocks"),
  outcomes   = c("Improved employability skills",
                 "Increased job-search confidence",
                 "Higher application rates"),
  impact     = "Higher 12-month employment among long-term unemployed",
  assumptions = c(
    "Workshops cause skills uplift (not just selection of motivated attendees)",
    "Skills uplift translates into application behaviour",
    "Local labour markets absorb the additional applicants"
  ),
  external_factors = c(
    "Macro labour market remains broadly stable",
    "No competing employability programme launches in same areas"
  ),
  name = "Skills uplift programme"
)
toc

## -----------------------------------------------------------------------------
mb_logframe(
  toc,
  indicators = list(
    outputs  = c("Workshops delivered", "Attendees per workshop"),
    outcomes = c("Skills score (post)", "Application count"),
    impact   = "Employment rate at 12 months"
  ),
  mov = list(
    outputs  = "Programme delivery log",
    outcomes = c("Pre/post survey", "DWP admin data"),
    impact   = "Linked HMRC PAYE records"
  ),
  risks = list(
    outputs  = "Attendance below planned levels",
    outcomes = "Self-report bias in skills score",
    impact   = "Macro shock confounds the estimate"
  )
)

## -----------------------------------------------------------------------------
mb_assumptions(
  level = c("activities", "outcomes", "impact"),
  description = c(
    "Workshops are well-attended",
    "Skills uplift translates into job entry",
    "Employment rise persists at 12 months"
  ),
  evidence = c(
    "Pilot attendance was 80%",
    "Indirect: similar programmes show 0.3 SD effect",
    "Limited evidence on longer-run persistence"
  ),
  criticality = c("medium", "high", "high")
)

## -----------------------------------------------------------------------------
qs <- mb_questions(
  text = c(
    "Did the programme cause higher 12-month employment",
    "How large is the effect, and for whom",
    "Was delivery faithful to the design",
    "What was the cost per additional job"
  ),
  type     = c("impact", "impact", "process", "economic"),
  priority = c("primary", "secondary", "secondary", "primary")
)
qs

## -----------------------------------------------------------------------------
cf <- mb_counterfactual(
  definition  = "Eligible non-applicants matched on age, prior unemployment duration, and region",
  source      = "quasi-experimental",
  credibility = "Moderate; selection on observables only, but rich admin covariates available"
)
cf

## -----------------------------------------------------------------------------
mb_stakeholders(
  name = c("HM Treasury", "DWP", "Local authorities", "What Works Centre"),
  role = c("Funder", "Policy lead", "Delivery", "Synthesis"),
  raci = c("A", "R", "C", "I"),
  interest  = c(5, 5, 4, 3),
  influence = c(5, 5, 3, 2)
)

## -----------------------------------------------------------------------------
plan <- mb_evaluation_plan(
  scope = "GBP 50m programme, 50 sites, 2026-2029",
  questions = qs,
  methods = c(
    impact   = "Difference-in-differences with matched comparison group",
    process  = "Mixed-methods implementation review",
    economic = "Cost per job, with QALY-adjusted variant"
  ),
  timing = c(baseline = "2026-Q1", midline = "2027-Q4", endline = "2029-Q2"),
  governance = "Joint HMT / DWP steering group; peer review by What Works Centre",
  budget = 1.5e6
)
plan

## -----------------------------------------------------------------------------
mb_sample_size(
  type = "proportion", p1 = 0.30, p2 = 0.35,
  power = 0.8, alpha = 0.05
)

## -----------------------------------------------------------------------------
mb_icc_reference("employment")
mb_cluster_design(individuals_per_cluster = 50, icc = 0.04, n_clusters = 25)

## -----------------------------------------------------------------------------
mb_stepped_wedge(
  steps = 5, clusters_per_step = 5,
  individuals_per_cluster = 50, icc = 0.04
)

## -----------------------------------------------------------------------------
mb_mde(
  n_per_group = 600, type = "proportion",
  baseline = 0.30, power = 0.8
)

## -----------------------------------------------------------------------------
sms <- mb_sms_rate(
  level  = 4,
  study  = "Smith et al. (2029) Skills uplift evaluation",
  design = "Difference-in-differences with matched comparison",
  notes  = "Parallel trends supported by 4 pre-period observations; cluster-robust SEs"
)
sms

## -----------------------------------------------------------------------------
conf_main <- mb_confidence(
  rating                 = "medium",
  question               = "Did the programme raise 12-month employment",
  evidence_strength      = "One Level 4 DiD (n = 12000); supportive Level 3 cohort study",
  methodological_quality = "Adequate; parallel trends plausible; some attrition concerns",
  generalisability       = "Established across 50 sites in two regions",
  rationale              = "Effect direction consistent across two studies but limited replication outside the programme footprint"
)
conf_main

conf_process <- mb_confidence(
  rating                 = "high",
  question               = "Was the programme implemented faithfully",
  evidence_strength      = "Mixed-methods process evaluation; 50-site fidelity audit",
  methodological_quality = "Strong; documented fidelity protocol with inter-rater reliability",
  generalisability       = "All sites covered",
  rationale              = "Comprehensive coverage; consistent fidelity scores"
)

mb_confidence_summary(conf_main, conf_process)

## -----------------------------------------------------------------------------
report <- mb_evaluation_report(
  plan       = plan,
  toc        = toc,
  sms        = sms,
  confidence = list(conf_main, conf_process),
  name       = "Skills uplift evaluation"
)
report

## -----------------------------------------------------------------------------
cat(mb_to_latex(report, caption = "Skills uplift evaluation summary"))

## -----------------------------------------------------------------------------
mb_data_versions()