Setup

This document details how to create a local copy of this pub’s codebase and setup your compute environment. This is a prerequisite for reproducing this publication, experimenting with the analysis, or contributing a revision.

Obtain local copy

The codebase is hosted on GitHub and can be found here.

To obtain a local copy, you have the option of either cloning or forking the repository. If you aren’t sure what’s best, our suggestion is to clone unless you both (1) want to propose a revision for the publication and (2) are not an employee of Arcadia Science.

To clone:

git clone https://github.com/Arcadia-Science/2024-paired-token-masking.git

Installation

Important

The publication is rendered with Quarto. If you don’t have it installed (check with quarto --version), you can install it here.

This repository uses conda to manage the computational and build environment. If you don’t have it installed (check with conda --version), you can find operating system-specific instructions for installing miniconda here. After installing, run the following commands to create and activate the environment.

conda env create -n 2024-paired-token-masking --file env.yml
conda activate 2024-paired-token-masking

Now, install any internal packages in the repository:

pip install -e .

And finally, if you plan to submit a pull request, install the pre-commit hooks:

pre-commit install

What’s next?

With a copy of the code and compute environment set up on your local machine, you can now reproduce or modify a local copy of the publication however you see fit. Read on to get started.

Reproduce

The best way to ensure you’ve correctly set up your code and compute environment is to reproduce this work. Fortunately, the analysis, and therefore the publication itself, can be reproduced with the following command:

make execute

This will execute and render the notebook index.ipynb, then build the publication site HTML, generating the directory _site/. Open _site/index.html to view your local copy of the publication.

Modify

To modify or extend any analyses, open up index.ipynb with Jupyter or your favorite IDE:

jupyter-lab index.ipynb

Preview

To create a live preview of your pub, run the following:

make preview

This will open a local copy of the publication in your default browser. The command watches for changes such that whenever index.ipynb is saved, the publication is re-rendered.

Publish

If you’ve improved the publication, consider contributing so we can update the hosted publication with your edits (big or small!). To get started, see our contributing guide.