',
'Use this guide to choose a biological example, see exactly how it was generated, and connect its scientific question to the null being tested. Every record is simulated.
',
'
The quick index links to each method’s CSV, full R script, plot, and saved output. The figures and numerical results come from those module files.
Generating truth and sample evidence are different.
',
'
A nonzero generating effect can yield a large p-value, and a true null can yield a small one. Read the stated model and truth separately from the observed result.
',
'
Rows count CSV records. For paired, repeated, clustered, or aggregated data, the design identifies the actual independent unit.
',
'
Quick index
',
'
Rows and column previews are read directly from the saved CSVs. Result summaries are read from the outputs generated by each module’s R script.
',
'
Method
Biological scenario
',
'
Rows
Seed
Generating truth
Saved result
Data
')
for (i in seq_along(modules)) {
x <- modules[[i]]; m <- x$meta; r <- x$results
search_text <- text_value(c(m$title, m$family, m$biology, m$question, m$null))
mini <- index_result(r$summary)
add('
Each module owns its fixed seed, simulation, CSV, plot, and analysis output. Identifiers are local to a dataset; repeated IDs in different files do not imply shared organisms.
',
'
The model descriptions state any rounding, dependence, censoring, or deliberate unusual observations. The column dictionary and design identify how each record should be interpreted.
',
'
This guide reads saved CSVs and result files; it does not resimulate or refit analyses. Run the course builder or the relevant module scripts first after changing a model, then regenerate this guide.
',
'
Run source("build_instructor_guide.R") followed by build_instructor_guide(".") from the course folder, or knit Instructor-dataset-guide.Rmd in RStudio. Missing module outputs cause a build error rather than an incomplete guide.
',
'
The catalog records the generating model, truth, observed result, file links, and checksums of the CSV and result files used for this build.
',
'')
add('')
writeLines(html, file.path(output_dir, "Instructor-dataset-guide.html"), useBytes = TRUE)
markdown <- c("# Instructor dataset guide", "", "## Generating truth, models, and analysis results", "", subtitle, "",
"All records are simulated. Generating truth is stated from the model, independently of the sample p-value. A true effect can yield a large p-value; a true null can yield a small one.", "",
"CSV rows are not automatically the independent sample size. Use each dataset's design to identify pairing, repeated observations, clustering, or aggregation.", "",
"[Dataset catalog](dataset_catalog.csv)", "", "## Quick index", "",
"| Method | Biological scenario | Rows | Seed | Generating truth | Saved result | CSV |",
"|---|---|---:|---:|---|---|---|")
for (i in seq_along(modules)) {
x <- modules[[i]]; m <- x$meta
markdown <- c(markdown, paste0("| [", md_cell(m$title), "](#dataset-", m$id, ") | ", md_cell(m$biology), " | ",
nrow(x$data), " | ", text_value(m$seed), " | ", md_cell(m$generating_truth), " | ",
md_cell(index_result(x$results$summary)), " | [CSV](", x$csv, ") |"))
}
for (i in seq_along(modules)) {
x <- modules[[i]]; m <- x$meta; r <- x$results
markdown <- c(markdown, "", paste0(''), "",
paste0("## Dataset ", sprintf("%02d", i), ": ", m$title), "", m$biology, "",
paste0("**Family:** ", m$family, " · **Rows:** ", nrow(x$data), " · **Seed:** ", text_value(m$seed)), "",
paste0("[Saved CSV](", x$csv, ") · [Full runnable R script](", x$script, ") · [Full-size plot](", x$plot, ")"), "",
paste0("**Generating truth:** ", m$generating_truth), "", paste0("**Exact generating model:** ", m$generating_model), "",
paste0("**Scientific question:** ", m$question), "", paste0("**Null being tested / estimation target:** ", m$null), "",
paste0("**Design and independent unit:** ", m$design), "", "### Columns", "",
"| Column | Meaning | Unit / type |", "|---|---|---|")
for (column in m$columns) markdown <- c(markdown, paste0("| ", md_cell(column$name), " | ", md_cell(column$meaning), " | ", md_cell(column$unit), " |"))
markdown <- c(markdown, "", "### Analysis from the saved dataset", "",
paste0("![", m$title, " plot. ", m$biology, "](", x$plot, ")"), "",
paste0("- ", unlist(r$summary, use.names = FALSE)), "", text_value(r$report), "",
paste0("**Teaching point:** ", m$teaching_point), "", "### Analysis code excerpt", "", "```r",
paste0('d <- read.csv("modules/', m$id, '/generated/data.csv")'), text_value(m$code_analysis, "\n"), "```", "",
"The full script supplies package loading and any additional preparation.", "", "### Full printed R output", "", "```text",
text_value(r$full_output, "\n"), "```", "", "### Recreate the observations", "", "```r",
recreation_code(m), "```", "", "Run the complete module from the course folder:", "", "```sh",
paste("Rscript", paste0("modules/", m$id, "/analysis.R"), paste0("modules/", m$id, "/generated")), "```", "")
}
markdown <- c(markdown, "## Reproducibility notes", "",
"Each module owns its fixed seed, simulation, saved CSV, plot, and actual analysis output. Identifiers are local to the module. Generating-model descriptions state rounding, dependence, censoring, or deliberate unusual observations.", "",
"The guide reads saved data and result files without rerunning simulations or analyses. Run the course builder or changed module scripts before refreshing the guide. The catalog includes file checksums for this build.", "",
"```r", 'source("build_instructor_guide.R")', 'build_instructor_guide(".")', "```", "",
paste0("Built ", generated_at, " from ", n_modules, " saved module datasets. ",
if (is_subset) "This is a selected subset preview." else "All discovered modules are included."))
writeLines(markdown, file.path(output_dir, "Instructor-dataset-guide.md"), useBytes = TRUE)
answer <- list(modules = vapply(modules, function(x) x$meta$id, character(1)),
count = n_modules, subset_preview = is_subset,
html = file.path(output_dir, "Instructor-dataset-guide.html"),
markdown = file.path(output_dir, "Instructor-dataset-guide.md"),
catalog = file.path(output_dir, "dataset_catalog.csv"))
message("Built instructor guide for ", n_modules, " modules", if (is_subset) " (subset preview)" else "", ".")
invisible(answer)
}
if (sys.nframe() == 0L) {
args <- commandArgs(trailingOnly = TRUE)
if (!length(args)) stop("Usage: Rscript build_instructor_guide.R /absolute/path/to/course [output_dir]")
build_instructor_guide(args[1], if (length(args) >= 2) args[2] else args[1])
}
, ')