B Adapting the book for your course
The book is meant to be changed. Each chapter is a separate R Markdown file, each example starts from one data chunk, and the book builds with one command, so you can reorder chapters, replace examples with your own data, or add a chapter for a topic you teach.
The files
All sources are in the
book/ folder of
the mirtverse repository:
| File | Contents |
|---|---|
index.Rmd |
Title page and preface |
00-author.Rmd |
About the author |
01-measurement.Rmd to 12-reporting.Rmd |
The twelve chapters, one per course week |
13-ml-lens.Rmd, 14-item-text.Rmd, 15-aig.Rmd, 16-auto-scoring.Rmd, 17-llms.Rmd, 18-ai-validity.Rmd |
The chapters on AI in measurement |
90-datasets.Rmd, 91-adapting.Rmd |
The appendices |
_bookdown.yml |
Chapter order (rmd_files) and output folder |
_output.yml |
Look of the HTML, PDF and EPUB editions |
latex/ |
Title page, preamble and box styles of the PDF edition |
cover/ |
Cover artwork and how to regenerate it |
_common.R |
Code run before every chapter: Loads mirtverse and sets chunk options |
references.bib |
References cited in the book |
The chapter files and their ids ({#measurement}, {#irt-models} and so
on) are kept stable, so links to a chapter keep working across versions.
Every chapter has the same shape
- A Learning goals box.
- Key terms, linked to the glossary.
- The ideas.
- Example 1 and Example 2, each starting with a data chunk labelled
data-<chapter id>-1or-2. - Your turn, with solutions in a folded
<details>block. - In the lab and Further reading.
Keep this shape when you add a chapter, and students will always know where to look.
Swapping in your own data
To use your own data in an example, replace the body of its data chunk and keep the label and the object names listed in Appendix A. For example, to run Example 1 of Chapter 2 on your own dichotomous test:
```{r data-irt-models-1}
# Our midterm: 40 multiple-choice items, scored 0/1.
resp <- read.csv("midterm-scored.csv")[, -1] # drop the ID column
```The rest of the example then runs on your data. Two caveats:
- Examples built on simulated data compare estimates with the true
values used to simulate them (objects such as
true,true_thetaor the planted DIF items). With real data there is no truth, so delete those comparisons or turn them into questions for students. - The prose describes the original results. Re-read the text around each output after you swap the data, and edit the interpretation to match.
The mirtverse instructor toolkit automates these steps, for example copying a chapter into a course folder and replacing a data chunk; see the instructor toolkit guide.
Building the book
Install bookdown once, then build from the book/ folder:
install.packages("bookdown")
bookdown::render_book("index.Rmd") # the whole book, into _book/
bookdown::preview_chapter("05-fit.Rmd") # one chapter, fasterOpen _book/index.html in a browser to read the result. The whole book
builds in a few minutes on a laptop. To publish your own version, put the
_book/ folder on any web server, or use GitHub Pages as the mirtverse
repository does (its book workflow builds the book and publishes it next
to the package website).
Suggesting changes
Every page has a Suggest an edit link at the top, which opens the chapter’s source on GitHub. Corrections and new examples are welcome as issues or pull requests in the mirtverse repository.