Skip to content

About

Interactive bioinformatics tutorials

Topics

Resources

Contributing

Stars

45 stars

Watchers

2 watching

Forks

Repository files navigation

sandbox.bio

Interactive bioinformatics command-line tutorials for bioinformatics at sandbox.bio.

Contributing tutorials

Thank you for your help contributing a tutorial to sandbox.bio!

Overview

Before you start, please reach out through GitHub Discussions or by email to discuss the tutorial you want to add to sandbox.bio. It can be a new tutorial or an existing one you want to port over. Please include the names of the command-line (or Python) tools your tutorial will rely on.

Writing your tutorial

Tutorials are a series of steps, where each step is a separate Markdown file. Here's an example step from the bedtools tutorial: Step7.md (corresponds to https://sandbox.bio/tutorials/bedtools-intro/7)

Custom Components

We use a few custom components:

Data files

Each tutorial includes sample data files that learners use to run the tools on. It's best if you use relatively small files (ideally <500kb each) so they are fast to download, and so the tools run quickly (the tools run inside the browser using WebAssembly, so you can expect a 3-10X slowdown compared to native speed 🙂).

Once you share the Markdown and data files, we'll get the tutorial up and running!


Local development

Setup

Before setting up your local environment, make sure you:

Then, on your terminal, run the following commands:

# Clone your fork
git clone https://github.com/YOUR_USERNAME_GOES_HERE/sandbox.bio.git
cd sandbox.bio
git checkout -b my-new-tutorial

# Set up your environment
./bin/setup.sh

If everything goes well, a browser window will open with sandbox.bio running locally, with a blue "Development Mode" ribbon at the top of the page. You may see a blank page for a few seconds.

New tutorial

Make a copy of the template:

TUTORIAL_ID=awesome-tool-intro
mkdir -p "./src/content/$TUTORIAL_ID"
cp -r "./src/content/_template/" "./src/content/$TUTORIAL_ID"

Then you need to modify src/stores/tutorials.js:

  1. Import your new tutorial at the top of the file: import { config as awesomeToolIntro } from "$content/awesome-tool-intro/config";
  2. Add your tutorial to the tutorials variable on this line

Modify the files as needed--see the next section for information about how files are organized.

Tutorial Structure

Here's how you should structure your tutorial within the sandbox.bio repository:

/src/content/
  some-tool-intro/
    data/               # Data you want to be preloaded in the terminal when the tutorial loads.
      reads.fastq       # Keep these files as small as possible, ideally < 100KB if possible.
      aligned.bam
    steps/              # Tutorial content for each step, defined in Markdown format (see format below).
        Step1.md
        Step2.md
    exercises/          # Exercises (see format below).
      Exercise1.md
    config.js           # Configuration file that defines order of tutorial steps, and other metadata.
    README.md           # Include where you downloaded files from, and how/if they were processed (optional).

See the bedtools tutorial for an example config.js to use as baseline.

About

Interactive bioinformatics tutorials

Topics

Resources

Contributing

Stars

45 stars

Watchers

2 watching

Forks

Used by

Contributors

Languages

⌂