{"id":13701645,"url":"https://github.com/a-paxton/living-documents","last_synced_at":"2026-03-02T22:53:46.747Z","repository":{"id":87390891,"uuid":"128236995","full_name":"a-paxton/living-documents","owner":"a-paxton","description":"How to use Jupyter notebooks and R markdown to create living documents and reproducible reports.","archived":false,"fork":false,"pushed_at":"2022-11-03T17:12:45.000Z","size":3459,"stargazers_count":49,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-13T07:36:20.638Z","etag":null,"topics":["jupyter","jupyter-notebook","living-documents","r","r-markdown","reproducible-workflows","tutorial","workshop-materials"],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/a-paxton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-04-05T16:57:21.000Z","updated_at":"2023-07-25T09:39:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"7b6708ec-074e-4457-9473-dc0d3667517b","html_url":"https://github.com/a-paxton/living-documents","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-paxton%2Fliving-documents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-paxton%2Fliving-documents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-paxton%2Fliving-documents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-paxton%2Fliving-documents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/a-paxton","download_url":"https://codeload.github.com/a-paxton/living-documents/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252403960,"owners_count":21742470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jupyter","jupyter-notebook","living-documents","r","r-markdown","reproducible-workflows","tutorial","workshop-materials"],"created_at":"2024-08-02T20:01:53.310Z","updated_at":"2026-03-02T22:53:46.654Z","avatar_url":"https://github.com/a-paxton.png","language":"Jupyter Notebook","funding_links":[],"categories":["Jupyter Notebook"],"sub_categories":[],"readme":"# Creating living documents and reproducible reports with\u2028 R markdown and Jupyter notebooks\n\n[![Binder](http://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/a-paxton/living-documents/master)\n\nCurious about how living documents and reproducible reports could help your\nresearch? This repo contains a workshop walkthrough about how\n[R markdown](https://rmarkdown.rstudio.com/) and\n[Jupyter notebooks](http://jupyter.org/) can enrich your research workflow.\n\n## What are \"living documents\" and \"reproducible reports\"?\n\nWhile everyone seems to have their own take on what these two terms mean and how\nthey differ from one another, \"living documents\" and \"reproducible reports\" are\nways for researchers to share code, images, and text in a single document.\n\nFor my part, I view \"living documents\" as work-in-progress documents. They're\ngreat for keeping notes on your data cleaning, data processing, and data\nanalysis by allowing you to add plain text, plots, and live code in a single\nplace. As researchers, we might spend months away from a project (while we're\nbusy with something else or while we're waiting for reviewers to get back to\nus). When it comes time to start up the project again, living documents can help\nus jump back into the project quickly: Taking good notes about what our code\ndoes -- right next to real code -- can help us remember exactly what we were\nthinking and why we made the choices we did.\n\n\"Reproducible reports,\" on the other hand, I see as documents that are meant to\npublicly accompany your research outputs (e.g., talks, posters, journal\narticles). These are ways for other researchers (and maybe even your reviewers)\nto see all of the work that you did when handling your data and creating your\nanalyses. Given ongoing concerns about transparency and reproducibility in a\nvariety of fields (including psychology and cognitive science), using\nreproducible reports can provide vital information about the data cleaning,\nprocessing, and analysis that supported your conclusions.\n\n\"Reproducible manuscripts\" are a specific type of reproducible report---one that\nhas as its output a submission-ready manuscript. For a reproducible manuscript,\nyou include code \"chunks\" or \"blocks\" that run your data analysis behind the\nscenes, along with the actual manuscript text (including figures, tables, and\neven references). Mastering the reproducible manuscript means no more tedious\n(and error-prone) copying and pasting of your statistics---they'll all recompile\nand render perfectly each time you compile your manuscript.\n\n## Why should I care?\n\n### For science\n\nResearchers -- especially within cognitive science and psychology -- are\nincreasingly interested in promoting transparency and reproducibility. There are\n[badges that researchers can earn for sharing their data and\nmaterials](https://cos.io/our-services/open-science-badges/) that promote the\nprominence of open science, and some journals even require data and code sharing\nnow.\n\nProviding an explicit accounting of your data and code practices can help\ndemonstrate the value of your work. If you share your data and your code, you're\npromoting immediate computational reproducibility by anyone (especially if you\nuse open-source programming languages and packages). As an added bonus, if\nthere's future interest in directly or conceptually replicating your work in new\nexperiments, providing your code openly can help those future replication\nefforts use methods as close to your original work as possible.\n\nBy using reproducible manuscripts, you'll take the added step of helping\nminimize transcription errors in your manuscript's statistics. Given the\nsurprisingly high rate of statistical errors in scientific articles generally\nand psychology articles specifically (see Bakker \u0026 Wicherts, 2011, *Behavior\nResearch Methods*), using reproducible manuscripts can help prevent simple\nerrors in transcription from entering the scientific field---especially ones\nthat (as noted by Bakker \u0026 Wicherts) could lead to qualitatively different\nresults.\n\n### For yourself\n\nThink of this as your present self doing something nice for your future self. If\nyour present self takes a few minutes to add some explanatory text, code\ncomments, or a useful plot, you'll be saving your future self headaches and\ntime. Present-you knows what you're doing because present-you is ankle-deep in\nthings. Future-you, on the other hand, will probably have spent weeks or months\naway from the problem and will have to spend valuable time puzzling through the\ntraces that then-past-you created. Do future-you a favor!\n\nUsing reproducible manuscripts takes that one step further. When reviewers come\nback with requests for an update to your data pipeline or a new study to add\nyour manuscript, you don't have to worry about recalculating and painstakingly\ncopying-and-pasting all of your descriptive statistics and results back into\nyour manuscript. You can get right to addressing those reviewer concerns and get\nthat revision out faster.\n\n### For yourself *and* science\n\nA transformative way to think about this is to see that the effort you put in\nfor helping your future self can be equally valuable for helping the broader\nresearch community engage with and make sense of your research.\n\nWith just a little bit of additional effort, you can tweak your living documents\ninto reproducible reports. If you're taking good notes and adding comments to\nyour code in your living document *while* you're doing the research, all you\nneed to do is publish the document after you're done!\n\n## Workshop materials: A guide\n\nTo run the workshop materials, just click on the \"launch binder\" button at the\ntop of the README file. [Binder](https://mybinder.org/) is a way of converting a\nGitHub repository into a cloud-based executable instance, complete with all of\nthe files and data in the repository. Just click the button, and you'll be able\nto start working on, executing, and editing the code  immediately---no\ninstallation required! Be patient the first time you launch it; it may take\na few minutes to be ready for you to start.\n\nOnce your Binder instance is started, you can navigate the directory in the\nbrowser window much in the same way that you can navigate files on your local\ncomputer. You can click file or folder names to open them. More on opening\nspecific files types are included below in the instructions for each of them.\n\nYou're able to come back and launch a new Binder instance of the code any time\nyou'd like. Keep in mind that none of your changes will be saved after the\nBinder instance is closed; each new Binder instance will only load with the\nfiles and specifications exactly as they are in the repository.\n\nHowever, if you'd like something more permanent, feel free to fork the\nrepository or download the files. The beauty of R markdown and Jupyter notebooks\nlies in their flexibility -- so experiment until you find what works best for\nyou!\n\n### R markdown (directory: `rmarkdown`)\n\nTo run the R markdown files, you'll need to start RStudio in the environment. If\nyou're not familiar with [RStudio](https://rstudio.com/products/rstudio/), it's\nan *integrated development environment* or IDE that facilitates programming in a\nmore user-friendly setup. (If you're familiar with MATLAB, RStudio will give you\na very similar programming experience in R to the one that you're used to seeing\nin MATLAB.)\n\nTo start RStudio, click the \"New\" button in the upper righthand corner. Select\n\"RStudio\" from the drop-down menu that appears. A new tab will open within your\nbrowser that includes RStudio. You can open files by selecting the \"File\" menu\nin the top-left corner, selecting \"Open\", and navigating to the appropriate\nfile. When you have this file open, it will open a new pane in the top-left\nsection of the RStudio window. This new pane is called the *source* pane, and it\nwill be where you can write and save your code. Below the source pane is the\n*console* pane, where you can run code. The top-right pane is the *environment*\npane, which shows the variables and custom functions specified in your\ndirectory. The lower-right pane is the *files*/*plot*/*help* pane, which serves\na variety of functions: showing files in the current directory, displaying\nplots, and rendering help text (depending on which tab you've selected). For\nmore on RStudio, check out the \"Further reading and more examples\" section (or\njust play around---remember, no matter what you do, you can't permanently ruin a\nBinder instance, since you can just get a new one).\n\nIn the `rmarkdown` directory, you'll find three files:\n\n* `rmarkdown-basic.Rmd`: Start here. Playing around with this file will give you\n  a very basic introduction to the R markdown format and its components.\n\n* `rmarkdown-fake_experiment_data_analysis.Rmd`: Once you're done with the basic\n  introduction, try this more realistic (but still toy) R markdown. It will\n  demonstrate how you might structure a reproducible report.\n\n* `r_library_installation.r`: This file is called by the toy reproducible report\n  to install required libraries.\n\n### Reproducible manuscripts (directory: `reproducible_manuscript`)\n\nWe'll be using RStudio again for our reproducible manuscripts, so follow the\ninstructions above to open the files through RStudio. I would strongly\nrecommend working on the basic R markdown before starting this section, unless\nyou are already familiar with R markdown.\n\nIn this directory, you'll find a number of files, including:\n\n* `prep_for_reproducible_manuscript.R`: **Open and run this script in its\n  entirety before beginning the rest of the reproducible manuscripts tutorial.**\n  You will not be able to proceed with this tutorial without running this script\n  first. This script will download `papaja` and set up the TeX distribution with\n  `tinytex`. You can open it in RStudio, highlight everything in the file, and\n  click \"Run\" (or press command+enter [Mac] or ctrl+enter [PC/Linux]).\n  **Remember**: You must run this *each time* you open a new Binder instance,\n  since it *does not permanently store* the changes that you make to the\n  instance.\n\n* `reproducible_manuscript.Rmd`: *After* you've run the\n  `prep_for_reproducible_manuscript.R` file for the first time since opening\n  your latest Binder instance, this R markdown will provide an example of a\n  reproducible manuscript written in R with `papaja`. When you compile it, you\n  will see a few new files with the same name (`reproducible_manuscript`) but\n  with new extensions. These files will include LaTeX log files, intermediary\n  manuscript files, and (given the specifications provided in our example) a\n  final PDF of the manuscript and figures (already included in this repository).\n\n* `references.bib`: This is a BibTeX-formatted file of references for the\n  reproducible manuscript. As with LaTeX, you may include more references in the\n  `.bib` file than you cite in your manuscript, and only those that you cite\n  will be rendered in the reference list. (If you're not used to using BibTeX\n  for reference management, Google Scholar offers it as an option when you click\n  the \"Cite\" button for a Google Scholar entry; just look for the \"BibTex\" link\n  at the bottom of the pop-up.)\n\n### Jupyter notebooks (directory: `jupyter-notebooks`)\n\nRunning the Jupyter notebooks is much more straightforward than opening the R\nmarkdown files. To open, simply click on the name of the file, and it will\nopen the Jupyter notebook in a new tab.\n\nIn this directory, you'll find three files:\n\n* `jupyter_notebook-basic.ipynb`: Start here. Playing around with this file will\n  give you a very basic introduction to the Jupyter notebook format and its\n  components.\n\n* `jupyter_notebook-fake_experiment_data_generator.ipynb`: Once you're done with\n  introduction, try this more realistic (but still toy) R markdown. The\n  demonstration will walk you through using the notebook by generating toy data\n  (provided also by default in the `data/` directory) used by various R markdown\n  files.\n\n* `test-external-script.py`: A standalone Python script that is used in the\n  basic Jupyter notebook.\n\n## Further reading and more examples\n\n* About RStudio and R markdown:\n  * R markdown cheat sheet: https://rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf\n  * RStudio's webinar on reproducible reporting: https://rstudio.com/resources/webinars/reproducible-reporting/\n  * More on knitr (a foundation for R markdown): http://kbroman.org/knitr_knutshell/\n  * Getting started with RStudio: https://www.oreilly.com/library/view/getting-started-with/9781449314798/ch01.html\n* About Jupyter:\n  * Jupyter's introductory documentation to the notebook: https://jupyter-notebook.readthedocs.io/en/stable/notebook.html\n  * Jupyter notebook cheat sheet: https://s3.amazonaws.com/assets.datacamp.com/blog_assets/Jupyter_Notebook_Cheat_Sheet.pdf\n  * A gallery of interesting Jupyter notebooks: https://github.com/jupyter/jupyter/wiki/A-gallery-of-interesting-Jupyter-Notebooks\n* A few living documents and reproducible reports that I've done (with varying\n  levels of sophistication):\n  * An early one for a research paper: https://github.com/a-paxton/emotion-dynamics\n  * One from a poster in 2016: https://github.com/a-paxton/explaining-mechanisms-of-global-warming\n  * A few for testing and trying out a Python package: https://github.com/nickduran/align-linguistic-alignment\n  * One for a 2017 paper: https://github.com/a-paxton/dual-conversation-constraints\n  * A reproducible manuscript for a CogSci 2018 proceedings paper: https://github.com/a-paxton/perception-memory-coordination/tree/master/study_1-cogsci2018\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa-paxton%2Fliving-documents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fa-paxton%2Fliving-documents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa-paxton%2Fliving-documents/lists"}