Initial commit

.devcontainer/Dockerfile

@@ -0,0 +1,5 @@
+FROM mcr.microsoft.com/devcontainers/python:3
+# Install the xz-utils package
+COPY requirements.txt requirements.txt
+RUN pip install -r requirements.txt
+

.devcontainer/devcontainer.json

@@ -0,0 +1,13 @@
+{
+    "name": "replication-template",
+    "build": {
+        // Path is relataive to the devcontainer.json file.
+        "dockerfile": "Dockerfile",
+        "context": "."
+    },
+
+    "settings": {
+        "workbench.colorTheme": "Visual Studio Light",
+        "terminal.integrated.shell.linux": "/bin/bash"
+    }
+}

.devcontainer/requirements.txt

@@ -0,0 +1,4 @@
+jupyter-book
+matplotlib
+numpy
+sphinx-design

.github/workflows/main.yml

@@ -0,0 +1,43 @@
+name: deploy-book
+
+# Only run this when the master branch changes
+on:
+  push:
+    branches:
+    - main
+    # If your git repository has the Jupyter Book within some-subfolder next to
+    # unrelated files, you can make this run only if a file within that specific
+    # folder has been modified.
+    #
+    # paths:
+    # - some-subfolder/**
+
+# This job installs dependencies, builds the book, and pushes it to `gh-pages`
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+
+    # Install dependencies
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+        cache: 'pip' # caching pip dependencies
+
+    - name: Install dependencies
+      run: |
+        pip install -r requirements.txt
+
+    # Build the book
+    - name: Build the book
+      run: |
+        jupyter-book build .
+
+    # Push the book's HTML to github-pages
+    - name: GitHub Pages action
+      uses: peaceiris/actions-gh-pages@v3.6.1
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./_build/html

.gitignore

@@ -0,0 +1,10 @@
+venv*
+_build
+.Rproj.user
+.libs
+.Rhistory
+.RData
+_publish.R
+_book
+_bookdown_files
+rsconnect

01_hands_off_running.md

@@ -0,0 +1,190 @@
+# Hands-off running
+
+The very first test is that your code must run, beginning to end, top to bottom, without error, and ideally without any user intervention. This should in principle (re)create all figures, tables, and numbers you include in your paper. 
+
+Many users may not be set up to run in one single top-to-bottom run. It helps to have a `main file` that runs all the other files, or all code, in the correct order, but is not a pre-requisite. 
+
+```{warning}
+We have seen users who appear to highlight code and to run it interactively, in pieces, using the program file as a kind of notepad. This is not reproducible, and should be avoided. It is fine for debugging.
+```
+
+## Some simple examples of main files
+
+
+
+::::{tab-set}
+
+
+:::{tab-item} Stata
+
+```stata
+* main.do
+* This is a simple example of a main file in Stata
+* It runs all the other files in the correct order
+
+* Set the root directory
+
+global rootdir : pwd
+
+* Run the data preparation file
+do $rootdir/01_data_prep.do
+
+* Run the analysis file
+do $rootdir/02_analysis.do
+
+* Run the table file
+do $rootdir/03_tables.do
+
+* Run the figure file
+do $rootdir/04_figures.do
+
+* Run the appendix file
+do $rootdir/05_appendix.do
+```
+The use of `do` (instead of `run` or even `capture run`) is best, as it will show the code that is being run, and is thus more transparent to you and the future replicator.
+
+
+Run this using the [right-click method](https://labordynamicsinstitute.github.io/ldilab-manual/96-02-running-stata-code.html#step-6-run-the-code) (Windows) or from the terminal (macOS, Linux): 
+
+```bash
+cd /where/my/code/is
+stata-mp -b do main.do
+```
+where `stata-mp` should be replaced with `stata` or `stata-se` depending on your licensed version.
+
+:::
+
+:::{tab-item} R
+
+```r
+# main.R
+# This is a simple example of a main file in R
+# It runs all the other files in the correct order
+
+# Set the root directory
+# rootdir <- getwd()
+# or if you are using Rproj files or git
+rootdir <- here::here()
+
+# Run the data preparation file
+source(file.path(rootdir, "01_data_prep.R"), echo = TRUE)
+
+# Run the analysis file
+source(file.path(rootdir, "02_analysis.R"), echo = TRUE)
+
+# Run the table file
+source(file.path(rootdir, "03_tables.R"), echo = TRUE)
+
+# Run the figure file
+source(file.path(rootdir, "04_figures.R"), echo = TRUE)
+
+# Run the appendix file
+source(file.path(rootdir, "05_appendix.R"), echo = TRUE)
+```
+The use of `echo=TRUE` is best, as it will show the code that is being run, and is thus more transparent to you and the future replicator.
+
+
+Run this using the [terminal method](https://labordynamicsinstitute.github.io/ldilab-manual/96-12-running-r-code.html) in Rstudio for any platform, or from the terminal (macOS, Linux): 
+
+```bash
+cd /where/my/code/is
+R CMD BATCH main.R
+```
+
+Do not use `Rscript`, as it will not generate enough output! On Windows, under `cmd.exe` or Powershell, you may need to adjust `R` to be `R.exe` if it is in your `%PATH%` or the full path to `R.exe` if it is not (this is automatically set for you in Rstudio).
+
+:::
+
+:::{tab-item} Python
+
+```python
+# main.py
+# This is a simple example of a main file in Python
+# It runs all the other files in the correct order
+
+# Set the root directory
+# rootdir = os.getcwd()
+# or better
+rootdir = os.path.dirname(os.path.realpath(__file__))
+
+# Run the data preparation file
+exec(open(os.path.join(rootdir, "01_data_prep.py")).read())
+
+# Run the analysis file
+exec(open(os.path.join(rootdir, "02_analysis.py")).read())
+
+# Run the table file
+exec(open(os.path.join(rootdir, "03_tables.py")).read())
+
+# Run the figure file
+exec(open(os.path.join(rootdir, "04_figures.py")).read())
+
+# Run the appendix file
+exec(open(os.path.join(rootdir, "05_appendix.py")).read())
+```
+
+Run this from your favorite IDE or from a terminal:
+
+```bash
+cd /where/my/code/is
+python main.py
+```
+
+:::
+
+:::{tab-item} MATLAB
+
+```matlab
+% main.m
+% This is a simple example of a main file in MATLAB
+% It runs all the other files in the correct order
+
+% Set the root directory
+rootdir = pwd;
+
+% Run the data preparation file
+run(fullfile(rootdir, '01_data_prep.m'))
+
+% Run the analysis file
+run(fullfile(rootdir, '02_analysis.m'))
+
+% Run the table file
+run(fullfile(rootdir, '03_tables.m'))
+
+% Run the figure file
+run(fullfile(rootdir, '04_figures.m'))
+
+% Run the appendix file
+run(fullfile(rootdir, '05_appendix.m'))
+```
+
+Follow instructions here to run MATLAB without a GUI, in hands-off mode, creating a log file.
+
+:::
+
+
+::::
+
+## What this does
+
+This ensures
+
+- that your code runs without problem, after all the debugging.
+- that your code runs without manual intervention.
+- that your code generates a log file that you can inspect, and that you could share with others.
+
+## What this does not do
+
+This does not ensure
+
+- that it will run on somebody else's computer
+  - because it does not guarantee that all the software is there
+  - because it does not guarantee that all the directories for input or output are there
+  - because many intermediate files might be present that are not in the replication package
+  - because it does not guarantee that all the directory names are correctly adjusted everywhere in your code
+- that it actually produces all the outputs
+  - because some outputs might be present from test runs
+
+## What to do next
+
+To solve some of these problems, let's go to the next step.

02_environments.md

@@ -0,0 +1 @@
+# Using environments

29-new-computer.md

@@ -0,0 +1,3 @@
+# Use a new computer
+
+Some authors may have a fresh, or extra, computer lying around. Use that to download the replication package, and see if it runs.

30-docker.md

@@ -0,0 +1,11 @@
+# Use of containers
+
+Coming soon.
+
+```bash
+docker run -it --rm \
+   -v "$(pwd)":/project \
+    -w /project \
+    dataeditors/stata17:2023-08-29 \
+    -b do main.do
+```

_config.yml

@@ -0,0 +1,79 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: Self-checking replication packages
+author: Lars Vilhuber
+logo: assets/ssde-logo.jpeg
+copyright: 2023
+exclude_patterns          : ["*venv*",".git*",".devcontainer"]
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+#  - packages.bib
+  - paper.bib
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/larsvilhuber/self-checking-reproducibility  # Online location of your book
+  #path_to_book:   # Optional path to your book, relative to the repository root
+  branch: main  # Which branch of the repository should be used when creating links (optional)
+
+#######################################################################################
+# Parse and render settings
+parse:
+  myst_enable_extensions:  # default extensions to enable in the myst parser. See https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html
+    # - amsmath
+    - colon_fence
+    # - deflist
+    - dollarmath
+    # - html_admonition
+    # - html_image
+    - linkify
+    # - replacements
+    # - smartquotes
+    - substitution
+    - tasklist
+  myst_url_schemes: [mailto, http, https] # URI schemes that will be recognised as external URLs in Markdown links
+  myst_dmath_double_inline: true  # Allow display math ($$) within an inline context
+
+
+#######################################################################################
+# HTML-specific settings
+html:
+  favicon                   : ""  # A path to a favicon image
+  use_edit_page_button      : true  # Whether to add an "edit this page" button to pages. If `true`, repository information in repository: must be filled in
+  use_repository_button     : true  # Whether to add a link to your repository button
+  use_issues_button         : true  # Whether to add an "open an issue" button
+  use_multitoc_numbering    : true   # Continuous numbering across parts/chapters
+  #extra_navbar              : <a href="https://labordynamicsinstitute.github.io/replicability-training-curriculum/">Link to old documentation</a>  # Will be displayed underneath the left navbar.
+  extra_footer              : ""  # Will be displayed underneath the footer.
+  google_analytics_id       : ""  # A GA id that can be used to track book views.
+  home_page_in_navbar       : true  # Whether to include your home page in the left Navigation Bar
+  baseurl                   : "https://larsvilhuber.github.io/self-checking-reproducibility/"  # The base URL where your book will be hosted. Used for creating image previews and social links. e.g.: https://mypage.com/mybook/
+  comments:
+    hypothesis              : false
+    utterances              : false
+  announcement              : "This is not yet fully debugged - report any issues!" # A banner announcement at the top of the site.
+
+
+# Advanced and power-user settings
+sphinx:
+  extra_extensions          :   # A list of extra extensions to load by Sphinx.
+  config                    :   # key-value pairs to directly over-ride the Sphinx configuration
+    bibtex_reference_style: author_year
+
+# Custom data in JSON notation
+
+# This will need to be integrated using GLUE, see https://jupyterbook.org/en/stable/content/executable/output-insert.html
+# - at setup, read in _config.yml, make glue variables
+# - able to reference anywhere in the document.

_setup.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+# This will initialize the Python environment needed for testing.
+[[ -z $1 ]] && VERSION=3.10 || VERSION=$1
+python$VERSION -m venv venv-$VERSION
+source venv-$VERSION/bin/activate
+pip$VERSION install -r requirements.txt
+

_test.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+[[ -z $1 ]] && VERSION=3.10 || VERSION=$1
+
+source venv-$VERSION/bin/activate
+jupyter-book build .