Chapter 14: The one-click report

Listen in Dr. Leith’s voice

The chat study is, in almost every sense, done. Across the chapters since the prospectus it has acquired everything an empirical study needs. It has a question and a theory: do gaming and non-gaming Twitch channels differ in how their audiences talk, and what would a uses-and-gratifications account predict. It has a codebook, tested for reliability. It has a sample, drawn with a defensible procedure. It has a clean dataset, a set of figures, and a tested finding interpreted with care. Every hard part is finished.

And yet the study is not finished, because all of that lives in pieces. The codebook is one document. The wrangling happened in an R script. The figures are a folder of images. The test result scrolled past in a console. A study scattered across a dozen files is not yet something another person can read, check, or build on. It is raw material for a study, not the study itself.

This last chapter gives the work a form. It assembles every piece into one report, makes that report reproducible, gathers it with the study’s other documents into a single site, and publishes that site where anyone can find it. The chapter’s title names the goal. By the time the study has been built the right way, producing the finished, public report is close to a single action: one click.

Two additional deliverables. Beyond the reproducible portfolio, the graduate study produces two further deliverables: a white paper structured for academic publication and a conference poster formatted for a communication research conference.

A report that rebuilds itself

Begin with the report, and with the ordinary way of writing one. Run the analysis in R. Copy the numbers into a word processor. Take screenshots of the figures and paste them in. Write the prose around them. This works, and it is quietly fragile. The instant the analysis changes, and analyses always change, a coding rule corrected, a few hundred messages added, every pasted number and every pasted figure is silently out of date, and nothing in the document says so. The write-up and the analysis drift apart, and only luck reveals it.

The alternative is to stop copying and put the analysis inside the document. A Quarto document, saved with a .qmd extension, is a plain-text file that interleaves ordinary prose with code chunks, blocks of live R code. When the document is rendered, Quarto runs every chunk, captures what it produces, the tables, the figures, the test statistics, and places that output into the finished document where the chunk sat. Numbers can also be computed inline, mid-sentence:

The analysis dataset held `r nrow(analysis)` coded messages, of which
`r sum(!is.na(analysis$is_gaming))` carried a gaming-status label.

In the rendered report those backtick expressions become the actual counts. Nothing is typed by hand, so nothing can fall out of date. A figure works the same way. The histogram from Chapter 12 is not pasted in; it is produced by a chunk that lives in the report:

````markdown
```{r}
#| label: fig-msglen
#| echo: false
#| fig-cap: "Message length by channel type."

ggplot(msglen, aes(message_length, fill = is_gaming)) +
  geom_histogram(binwidth = 5) +
  v2v::theme_v2v()
```
````

This is reproducible publication, and it has two payoffs that matter. The report cannot drift from the analysis, because the report is the analysis: re-render it and every number updates itself. And the report can be checked, because anyone holding the source and the data can render it and get exactly the same results, which is the standard a scientific claim is supposed to meet (Peng, 2011). The idea is older than Quarto, older than R. Donald Knuth named it literate programming (Knuth, 1984): the conviction that runnable code and the prose explaining it belong together in one document rather than apart in two. Quarto is a modern descendant of that idea, and the “one click” of this chapter’s title is its render button. One action, and the document rebuilds itself from source.

The shape of a report: IMRaD

A document that rebuilds itself still needs a structure, and empirical research has a standard one, settled enough to have an acronym: IMRaD, for Introduction, Methods, Results, and Discussion. Four sections, in that fixed order, and the order is itself a small argument, carrying the reader from why the study was done to what it found to what that means.

The white paper. The white paper follows IMRaD format (Introduction, Methods, Results, Discussion), uses APA 7th edition throughout, reports effect sizes and power statistics, and includes a pre-registration disclosure statement in the methods section. Its discussion situates the findings within the theoretical literature from Chapter 5. For your own study, convert the key results and discussion into IMRaD structure, and ask what is lost in the move and what must be added to meet white paper standards.

The Introduction states the question and why it is worth asking. For the chat study this is the work of the prospectus from Chapter 6: the question of whether gaming and non-gaming Twitch chat differ in message length, and the uses-and-gratifications lens that framed talk on a stream as behavior an audience chooses for its own reasons.

The Methods section says exactly what was done, in enough detail that another researcher could repeat it. This is the home of the codebook from Chapter 8, the sampling procedure and the inter-coder reliability check from Chapter 10, and the wrangling steps from Chapter 11. Methods is the section that earns the reader’s trust, and it is the section a reproducible document supports best, because the code that did the work is right there to be read.

Methods section requirements. A graduate methods section includes three elements: (1) a data provenance statement (Chapter 9); (2) an intercoder reliability report, including the κ value, training protocol, and threshold applied (Chapter 8); and (3) the pre-registration disclosure with OSF URL (Chapter 5). Each element is a transparency marker that signals to reviewers that the study meets graduate-level evidentiary standards. The pre-registration disclosure in particular protects a distinction that preregistration exists to make legible:

“Preregistration distinguishes analyses and outcomes that result from predictions from those that result from postdictions.”

Nosek et al. (2018, p. 2600)

The Results section reports what was found, plainly and without interpretation. The three figures from Chapter 12 and the t-test from Chapter 13 belong here. Results states the facts: the distributions, the group means, the test statistic with its degrees of freedom, its p-value, and its effect size. It does not yet say what they mean.

The Discussion says what the results mean. This is where the interpretation from Chapter 13 belongs: that the difference between the two kinds of channel is statistically real but negligible in size, that gaming and non-gaming chat are better thought of as alike than as different in message length, and what that answer implies for the uses-and-gratifications question raised in the Introduction. Discussion is also where an honest study states its limits.

A short abstract summarizing all four sections usually sits in front, and references close the document. The V2V Hub ships an imrad-template.qmd with this skeleton already in place. The structure is not bureaucracy. It is a contract with the reader: anyone who has read empirical work knows it holds these parts in this order, and knows exactly where to look for the question, the procedure, the finding, and the meaning.

One site, many pages

The report is not the only document the study produced. There is also the codebook, the record of how the sample was drawn, the log of wrangling decisions. In a finished study these are not crushed into one enormous file. They become separate pages of one site.

Chapter 9 built the scaffold for this with v2v::new_portfolio(), which created a project folder already organized as a Quarto website. The piece that turns a folder of .qmd files into a navigable site is a configuration file named _quarto.yml. It names the site and lists its pages and the navigation that links them:

project:
  type: website

website:
  title: "Twitch Chat Study"
  navbar:
    left:
      - text: "Report"
        href: index.qmd
      - text: "Codebook"
        href: codebook.qmd
      - text: "Figures"
        href: figures.qmd

The IMRaD report is one page, the codebook another, a figure gallery another, each its own .qmd, all rendered together and linked by a shared navigation bar. Running quarto render on the project builds every page at once and writes out a complete website, ready to publish. This is the portfolio synthesis the study has been moving toward since Chapter 9: not a pile of files, but one coherent site that holds the entire study and lets a reader move through it.

Going live

A website sitting in a folder on a laptop is still private. Publishing it means placing it somewhere with a public address, and the standard free option for a Quarto site is GitHub Pages, which serves a website directly from a GitHub repository.

Publishing has a checklist, and the checklist is exactly where studies fail in their final week. v2v::deploy_portfolio() runs the checklist and then publishes:

v2v::deploy_portfolio()

Pre-flight checks
  renv library in sync ......... ok
  no uncommitted changes ....... ok
  _quarto.yml valid ............ ok

Rendering 4 pages ... done
Publishing to GitHub Pages ...

Live at: https://username.github.io/twitch-chat-study/

Before it publishes anything, the function runs three pre-flight checks. It confirms that renv, the tool from Chapter 9 that records the project’s exact package versions, is in sync, so the published site was built with the versions the source declares. It confirms there are no uncommitted Git changes, so the site that goes live matches the source that is actually saved. And it confirms that _quarto.yml is valid, so the render will not fail partway through. Only when all three pass does it run the publish step itself.

The checks are not red tape. Each one heads off a specific and demoralizing failure: a site that renders on its author’s machine and nowhere else, a published page that does not match the work that was actually done, a deployment that collapses at eleven at night the evening a portfolio is due. The function exists so that the last step of a long study is the calm one. What it produces is a URL. The chat study is now a public, reproducible website, one that anyone can read and anyone can rebuild from its source.

The conference poster. A standard academic communication conference poster is 36 × 24 inches, landscape orientation, structured as: title/authors/institution; abstract (~100 words); background and hypotheses; condensed methods; key results with one or two theme_v2v() figures; discussion and implications; QR code linking to the OSF pre-registration and/or Quarto portfolio. The poster is your 90-second pitch. Design the layout of your own 36 × 24 poster, and decide which single figure from your analysis best communicates your main finding in 30 seconds.

The reflection

One short piece remains, and the portfolio is not complete without it: a one-paragraph reflection. It is not part of IMRaD and it is not a result. It is the researcher’s own brief, candid account of what the study taught them and what a second attempt would do differently.

A good reflection is specific. It names what turned out harder than expected, where a coding rule proved ambiguous in practice, what the dataset could not answer because of how it was collected, what a future version of the study would change. It resists the two easy failures, the bland report that everything went well and the anxious confession that everything went wrong. A reflection is not an apology. It is evidence of judgment: a researcher who can say precisely where their study is weak is a researcher who genuinely understands it. It is kept to a paragraph on purpose. One honest paragraph is worth more than a page of hedging.

Looking ahead

This is the last chapter, and looking ahead now means looking past the book.

The chat study is finished. A question became a design. A design became data. Data became figures and a test. The whole of it became a reproducible site with a public address, a study another person can read, check, and extend. The dataset along the way happened to be Twitch chat, but nothing in the path depended on that. The sequence is the same for any dataset a reader will ever meet: a question, a theory, a codebook, a sample, a reliability check, a clean dataset, an honest figure, a careful test, and a reproducible report.

That sequence is what the book’s title has been describing all along. Vibes are where a study starts, a hunch, an interesting feeling that some corner of the world works a particular way. Variables are what discipline turns the vibe into, something defined precisely enough to measure, and measured carefully enough to test. The distance between the two is the whole of research methods, and a reader who has now walked it once, from a vague curiosity about Twitch chat to a published finding about it, can walk it again with a dataset of their own. The tools will keep changing. The path from vibes to variables does not.

References

Knuth, D. E. (1984). Literate programming. The Computer Journal, 27(2), 97-111. https://doi.org/10.1093/comjnl/27.2.97

Peng, R. D. (2011). Reproducible research in computational science. Science, 334(6060), 1226-1227. https://doi.org/10.1126/science.1213847

Graduate readings

Nosek, B. A., Ebersole, C. R., DeHaven, A. C., & Mellor, D. T. (2018). The preregistration revolution. Proceedings of the National Academy of Sciences, 115(11), 2600–2606. https://doi.org/10.1073/pnas.1708274114

--- title: "Chapter 14: The one-click report" --- ::: {.chapter-audio} [Listen in Dr. Leith's voice]{.audio-label} ```{=html} <audio class="v2v-audio v2v-audio-ug" controls preload="none"><source src="../audio/ch14-ug.mp3" type="audio/mpeg">Your browser does not support audio.</audio> <audio class="v2v-audio v2v-audio-grad" controls preload="none"><source src="../audio/ch14-grad.mp3" type="audio/mpeg">Your browser does not support audio.</audio> ``` ::: The chat study is, in almost every sense, done. Across the chapters since the prospectus it has acquired everything an empirical study needs. It has a question and a theory: do gaming and non-gaming Twitch channels differ in how their audiences talk, and what would a uses-and-gratifications account predict. It has a codebook, tested for reliability. It has a sample, drawn with a defensible procedure. It has a clean dataset, a set of figures, and a tested finding interpreted with care. Every hard part is finished. And yet the study is not finished, because all of that lives in pieces. The codebook is one document. The wrangling happened in an R script. The figures are a folder of images. The test result scrolled past in a console. A study scattered across a dozen files is not yet something another person can read, check, or build on. It is raw material for a study, not the study itself. This last chapter gives the work a form. It assembles every piece into one report, makes that report reproducible, gathers it with the study's other documents into a single site, and publishes that site where anyone can find it. The chapter's title names the goal. By the time the study has been built the right way, producing the finished, public report is close to a single action: one click. ::: {.graduate-extension} **Two additional deliverables.** Beyond the reproducible portfolio, the graduate study produces two further deliverables: a *white paper* structured for academic publication and a *conference poster* formatted for a communication research conference. ::: ## A report that rebuilds itself Begin with the report, and with the ordinary way of writing one. Run the analysis in R. Copy the numbers into a word processor. Take screenshots of the figures and paste them in. Write the prose around them. This works, and it is quietly fragile. The instant the analysis changes, and analyses always change, a coding rule corrected, a few hundred messages added, every pasted number and every pasted figure is silently out of date, and nothing in the document says so. The write-up and the analysis drift apart, and only luck reveals it. The alternative is to stop copying and put the analysis inside the document. A **Quarto document**, saved with a `.qmd` extension, is a plain-text file that interleaves ordinary prose with **code chunks**, blocks of live R code. When the document is rendered, Quarto runs every chunk, captures what it produces, the tables, the figures, the test statistics, and places that output into the finished document where the chunk sat. Numbers can also be computed inline, mid-sentence: ```{verbatim lang="markdown"} The analysis dataset held `r nrow(analysis)` coded messages, of which `r sum(!is.na(analysis$is_gaming))` carried a gaming-status label. ``` In the rendered report those backtick expressions become the actual counts. Nothing is typed by hand, so nothing can fall out of date. A figure works the same way. The histogram from Chapter 12 is not pasted in; it is produced by a chunk that lives in the report: `````{verbatim lang="markdown"} ````markdown ```{r} #| label: fig-msglen #| echo: false #| fig-cap: "Message length by channel type." ggplot(msglen, aes(message_length, fill = is_gaming)) + geom_histogram(binwidth = 5) + v2v::theme_v2v() ``` ```` ````` This is **reproducible publication**, and it has two payoffs that matter. The report cannot drift from the analysis, because the report is the analysis: re-render it and every number updates itself. And the report can be checked, because anyone holding the source and the data can render it and get exactly the same results, which is the standard a scientific claim is supposed to meet (Peng, 2011). The idea is older than Quarto, older than R. Donald Knuth named it **literate programming** (Knuth, 1984): the conviction that runnable code and the prose explaining it belong together in one document rather than apart in two. Quarto is a modern descendant of that idea, and the "one click" of this chapter's title is its render button. One action, and the document rebuilds itself from source. ## The shape of a report: IMRaD A document that rebuilds itself still needs a structure, and empirical research has a standard one, settled enough to have an acronym: **IMRaD**, for Introduction, Methods, Results, and Discussion. Four sections, in that fixed order, and the order is itself a small argument, carrying the reader from why the study was done to what it found to what that means. ::: {.graduate-extension} **The white paper.** The white paper follows IMRaD format (Introduction, Methods, Results, Discussion), uses APA 7th edition throughout, reports effect sizes and power statistics, and includes a pre-registration disclosure statement in the methods section. Its discussion situates the findings within the theoretical literature from Chapter 5. For your own study, convert the key results and discussion into IMRaD structure, and ask what is lost in the move and what must be added to meet white paper standards. ::: The **Introduction** states the question and why it is worth asking. For the chat study this is the work of the prospectus from Chapter 6: the question of whether gaming and non-gaming Twitch chat differ in message length, and the uses-and-gratifications lens that framed talk on a stream as behavior an audience chooses for its own reasons. The **Methods** section says exactly what was done, in enough detail that another researcher could repeat it. This is the home of the codebook from Chapter 8, the sampling procedure and the inter-coder reliability check from Chapter 10, and the wrangling steps from Chapter 11. Methods is the section that earns the reader's trust, and it is the section a reproducible document supports best, because the code that did the work is right there to be read. ::: {.graduate-extension} **Methods section requirements.** A graduate methods section includes three elements: (1) a data provenance statement (Chapter 9); (2) an intercoder reliability report, including the κ value, training protocol, and threshold applied (Chapter 8); and (3) the pre-registration disclosure with OSF URL (Chapter 5). Each element is a transparency marker that signals to reviewers that the study meets graduate-level evidentiary standards. The pre-registration disclosure in particular protects a distinction that preregistration exists to make legible: > "Preregistration distinguishes analyses and outcomes that result from predictions from those that result from postdictions." > > Nosek et al. (2018, p. 2600) ::: The **Results** section reports what was found, plainly and without interpretation. The three figures from Chapter 12 and the t-test from Chapter 13 belong here. Results states the facts: the distributions, the group means, the test statistic with its degrees of freedom, its p-value, and its effect size. It does not yet say what they mean. The **Discussion** says what the results mean. This is where the interpretation from Chapter 13 belongs: that the difference between the two kinds of channel is statistically real but negligible in size, that gaming and non-gaming chat are better thought of as alike than as different in message length, and what that answer implies for the uses-and-gratifications question raised in the Introduction. Discussion is also where an honest study states its limits. A short **abstract** summarizing all four sections usually sits in front, and references close the document. The V2V Hub ships an `imrad-template.qmd` with this skeleton already in place. The structure is not bureaucracy. It is a contract with the reader: anyone who has read empirical work knows it holds these parts in this order, and knows exactly where to look for the question, the procedure, the finding, and the meaning. ## One site, many pages The report is not the only document the study produced. There is also the codebook, the record of how the sample was drawn, the log of wrangling decisions. In a finished study these are not crushed into one enormous file. They become separate pages of one **site**. Chapter 9 built the scaffold for this with `v2v::new_portfolio()`, which created a project folder already organized as a Quarto website. The piece that turns a folder of `.qmd` files into a navigable site is a configuration file named `_quarto.yml`. It names the site and lists its pages and the navigation that links them: ```yaml project: type: website website: title: "Twitch Chat Study" navbar: left: - text: "Report" href: index.qmd - text: "Codebook" href: codebook.qmd - text: "Figures" href: figures.qmd ``` The IMRaD report is one page, the codebook another, a figure gallery another, each its own `.qmd`, all rendered together and linked by a shared navigation bar. Running `quarto render` on the project builds every page at once and writes out a complete website, ready to publish. This is the portfolio synthesis the study has been moving toward since Chapter 9: not a pile of files, but one coherent site that holds the entire study and lets a reader move through it. ## Going live A website sitting in a folder on a laptop is still private. Publishing it means placing it somewhere with a public address, and the standard free option for a Quarto site is **GitHub Pages**, which serves a website directly from a GitHub repository. Publishing has a checklist, and the checklist is exactly where studies fail in their final week. `v2v::deploy_portfolio()` runs the checklist and then publishes: ```r v2v::deploy_portfolio() ``` ``` Pre-flight checks renv library in sync ......... ok no uncommitted changes ....... ok _quarto.yml valid ............ ok Rendering 4 pages ... done Publishing to GitHub Pages ... Live at: https://username.github.io/twitch-chat-study/ ``` Before it publishes anything, the function runs three **pre-flight checks**. It confirms that renv, the tool from Chapter 9 that records the project's exact package versions, is in sync, so the published site was built with the versions the source declares. It confirms there are no uncommitted Git changes, so the site that goes live matches the source that is actually saved. And it confirms that `_quarto.yml` is valid, so the render will not fail partway through. Only when all three pass does it run the publish step itself. The checks are not red tape. Each one heads off a specific and demoralizing failure: a site that renders on its author's machine and nowhere else, a published page that does not match the work that was actually done, a deployment that collapses at eleven at night the evening a portfolio is due. The function exists so that the last step of a long study is the calm one. What it produces is a URL. The chat study is now a public, reproducible website, one that anyone can read and anyone can rebuild from its source. ::: {.graduate-extension} **The conference poster.** A standard academic communication conference poster is 36 × 24 inches, landscape orientation, structured as: title/authors/institution; abstract (~100 words); background and hypotheses; condensed methods; key results with one or two `theme_v2v()` figures; discussion and implications; QR code linking to the OSF pre-registration and/or Quarto portfolio. The poster is your 90-second pitch. Design the layout of your own 36 × 24 poster, and decide which single figure from your analysis best communicates your main finding in 30 seconds. ::: ## The reflection One short piece remains, and the portfolio is not complete without it: a one-paragraph **reflection**. It is not part of IMRaD and it is not a result. It is the researcher's own brief, candid account of what the study taught them and what a second attempt would do differently. A good reflection is specific. It names what turned out harder than expected, where a coding rule proved ambiguous in practice, what the dataset could not answer because of how it was collected, what a future version of the study would change. It resists the two easy failures, the bland report that everything went well and the anxious confession that everything went wrong. A reflection is not an apology. It is evidence of judgment: a researcher who can say precisely where their study is weak is a researcher who genuinely understands it. It is kept to a paragraph on purpose. One honest paragraph is worth more than a page of hedging. ## Looking ahead This is the last chapter, and looking ahead now means looking past the book. The chat study is finished. A question became a design. A design became data. Data became figures and a test. The whole of it became a reproducible site with a public address, a study another person can read, check, and extend. The dataset along the way happened to be Twitch chat, but nothing in the path depended on that. The sequence is the same for any dataset a reader will ever meet: a question, a theory, a codebook, a sample, a reliability check, a clean dataset, an honest figure, a careful test, and a reproducible report. That sequence is what the book's title has been describing all along. **Vibes** are where a study starts, a hunch, an interesting feeling that some corner of the world works a particular way. **Variables** are what discipline turns the vibe into, something defined precisely enough to measure, and measured carefully enough to test. The distance between the two is the whole of research methods, and a reader who has now walked it once, from a vague curiosity about Twitch chat to a published finding about it, can walk it again with a dataset of their own. The tools will keep changing. The path from vibes to variables does not. ## References Knuth, D. E. (1984). Literate programming. _The Computer Journal_, _27_(2), 97-111. https://doi.org/10.1093/comjnl/27.2.97 Peng, R. D. (2011). Reproducible research in computational science. _Science_, _334_(6060), 1226-1227. https://doi.org/10.1126/science.1213847 ::: {.graduate-extension} ### Graduate readings Nosek, B. A., Ebersole, C. R., DeHaven, A. C., & Mellor, D. T. (2018). The preregistration revolution. *Proceedings of the National Academy of Sciences*, *115*(11), 2600–2606. https://doi.org/10.1073/pnas.1708274114 :::