The main notebook on Binder, in JupyterLab.
The dashboard on Binder, with its code hidden.
A REMARK (R[eplications/eproductions] and Explorations Made using ARK) is a self-contained project whose computational results anyone can reproduce, on any platform, now and years from now. REMARKs are listed in the REMARK catalog and shown on econ-ark.org.
This repository is a small but complete REMARK, meant to be copied when you start your own. It meets Tier 2 (Reproducible REMARK) of the REMARK Standard. For a REMARK that is a whole paper, see BufferStockTheory.
code/python/REMARK-starter-example.ipynbsolves a consumption-saving model with HARK'sKinkyPrefConsumerType: a consumer with shocks to their preferences, who pays a higher interest rate when borrowing than they earn when saving. It draws the consumption function at each value of the shock (figures/cFunc.pdf).- The same notebook calls a function in
code/python/custom_code.pythat draws a histogram of random numbers (figures/dist.pdf). The function takes a seed, so every run draws the same numbers. REMARK-starter-example.texis a short LaTeX document that includes both figures.dashboard/REMARK-starter-example-dashboard.ipynbredraws the consumption functions as a slider changes the consumer's risk aversion.
reproduce.sh regenerates every figure. It installs the exact package versions recorded in
uv.lock, then executes the notebook: the figures are written to figures/, and an executed
copy of the notebook, with all its output, to results/. Once the packages are installed it
takes about a minute. (The dashboard computes no results, so it is left for you to open.)
Use whichever of these suits you.
docker build -t remark-starter-example .
docker run --rm --user "$(id -u):$(id -g)" \
-v "$PWD/results:/app/results" -v "$PWD/figures:/app/figures" remark-starter-exampleThe image holds Python and every package; running it runs reproduce.sh. The two -v
options put the results in this folder, and --user makes the files yours rather than
root's. The base image is pinned by its digest, so the image is the same wherever it is built.
Install uv, then:
./reproduce.shuv installs the Python version named in .python-version (if you do not already have it)
and the packages in uv.lock into .venv. To work with the notebooks yourself, start
JupyterLab with uv run jupyter lab, or the dashboard with
uv run voila dashboard/REMARK-starter-example-dashboard.ipynb.
The REMARK catalog's cli.py builds the environment from binder/environment.yml with
repo2docker and runs reproduce.sh in it, which is how
the Econ-ARK team tests a submitted REMARK. In a clone of
econ-ark/REMARK, add a catalog entry
REMARKs/REMARK-starter-example.yml:
name: REMARK-starter-example
remote: https://github.com/econ-ark/REMARK-starter-example
title: REMARK Starter Example
tag: v1.0.1and run:
python cli.py pull REMARKs/REMARK-starter-example.yml
python cli.py lint --tier 2 REMARKs/REMARK-starter-example.yml
python cli.py build docker REMARKs/REMARK-starter-example.yml
python cli.py execute docker REMARKs/REMARK-starter-example.ymlThe CLI guide explains each command.
The badges at the top open the notebook, or the dashboard, in your browser, with nothing to
install. Binder builds its environment from binder/: environment.yml installs Python and
uv, and postBuild installs the packages in uv.lock and makes them the notebooks' kernel.
reproduce_textetc.sh compiles REMARK-starter-example.tex into
latex/REMARK-starter-example.pdf from the figures. It needs a LaTeX installation
(pdflatex and bibtex), which the Docker image does not include.
| File | What it is for | Required |
|---|---|---|
reproduce.sh |
Regenerates every result | All tiers |
Dockerfile |
Builds an image that runs reproduce.sh |
All tiers |
binder/environment.yml |
The environment the REMARK tool and Binder build | All tiers |
pyproject.toml |
The packages the code uses, edited by hand | With uv |
uv.lock |
The exact version of every package, written by uv lock |
All tiers (a lock file) |
.python-version |
The exact Python version | With uv |
LICENSE |
The terms of use (Apache 2.0) | All tiers |
README.md |
This file: at least 50 non-empty lines for Tier 1, 100 for Tier 2 | All tiers |
CITATION.cff |
How to cite the REMARK | Tiers 2 and 3 |
REMARK.md |
The REMARK's tier, its notebooks and its abstract, for the website | Tiers 2 and 3 |
binder/postBuild |
Installs uv.lock's packages on Binder |
With uv, for Binder |
code/python/ |
The notebook, and the module it imports | Yours to organize |
dashboard/ |
The interactive dashboard | Optional |
figures/ |
The figures reproduce.sh makes |
Optional |
REMARK-starter-example.tex, latex/ |
The LaTeX document, its bibliography and the compiled PDF | Optional |
reproduce_textetc.sh |
Compiles the LaTeX document | Optional |
Every tier also requires a tagged release; this one is tagged v1.0.1. A REMARK whose
reproduce.sh takes five minutes or more should also have a reproduce_min.sh that
reproduces some of the results quickly. This one is fast enough not to need it.
- Copy the repository. Clone it, delete its
.gitfolder, and push the files to a new repository of your own; or use GitHub's "Import repository". Your REMARK stays under your account. - Replace the code. Put your notebooks and code in
code/, and changereproduce.shso that it runs them. Keep it non-interactive: it must run from start to finish with nobody at the keyboard, and fail (exit with a nonzero code) if anything goes wrong. - Declare your packages. Add each one with
uv add <package>(or editpyproject.tomland runuv lock), and commit bothpyproject.tomlanduv.lock. Change.python-version, the Dockerfile's base image andbinder/environment.ymltogether if you need another Python version. - Rename the project in
pyproject.toml,binder/environment.yml, the Dockerfile's comments andREMARK.md. - Write your README with what the REMARK computes and how to reproduce it. The REMARK catalog's templates give an outline for each tier.
- Fill in
CITATION.cffandREMARK.mdwith your title, authors, abstract and tier. The CFF initializer helps write a validCITATION.cff. - Choose a license and replace
LICENSEif Apache 2.0 is not the one you want. - Check it. Run
./reproduce.shfrom a fresh clone, then the REMARK tool'slint,buildandexecutecommands above with your own catalog entry. - Tag a release, for example
git tag -a v1.0.0 -m "First release"andgit push origin v1.0.0, and release a new tag for each later version. - Submit it by opening a pull request on the REMARK catalog that adds your entry, as STANDARD.md describes. For Tier 3, get a Zenodo DOI first; the catalog's Zenodo guide shows how.
- Pin everything.
uv.lockpins every package, including the ones your packages depend on;.python-versionpins Python; the Dockerfile pins its base image by digest. Theexclude-newerdate inpyproject.tomlmakesuv lockchoose the same versions whenever it runs; move it forward when you want newer packages. - Fix the seed of every random number generator, as
custom_code.pydoes. - Leave dates out of output files. The figures are saved without a creation date, so a run that gives the same results writes byte-for-byte the same files.
- Never edit results by hand. Everything in
figures/should come fromreproduce.sh.
The code and text are released under the Apache License 2.0; see LICENSE. To cite this
repository, use CITATION.cff (GitHub's "Cite this repository" button reads it).