Tutorial 2 Adding a New Sequencing Run

Tutorial 2: Adding a New Sequencing Run

Follow along! The sequencing team just finished run IV26Run8. In about 7 minutes you'll add it to the lab's master copy, rebuild the two JHH input files with one command, and put them in source/, ready for a production run.

You'll need access to the lab SharePoint and the Mostafa Lab folder (Step 1: Getting access). This is real patient-sample data: keep it on your computer and SharePoint only.

flowchart LR
    A["Part A (2 min)<br/>Run FASTA + date<br/>→ SharePoint"] --> B["Part B1<br/>Copy SharePoint<br/>→ source_prep/"]
    B --> C["Part B2<br/>prepare_source.py"]
    C --> D{"READY?"}
    D -->|STOPPED| E["Fix what it says"] --> C
    D -->|READY| F["Part B3<br/>Copy 2 files → source/"]

Loading

Part A happens once per sequencing run; Part B each time you want to run the pipeline with new data.

Part A: add the run to SharePoint (once per run, ~2 minutes)

Done by whoever receives the new data.

1. Find the run's folder in the Mostafa Lab shared folder. It is named after the run, e.g. IV26Run8 (IV + 2-digit year + Run + number; a re-run may end in a letter, IV25Run11b).

2. Copy its consensus FASTA into runs/ on the lab SharePoint.

   • Name it Consensus + run name + .fasta: ConsensusIV26Run8.fasta.
   • Copy the file itself, not the whole run folder. Exactly one FASTA per run. Several FASTAs and unsure which is the consensus of all segments? Ask the sequencing team. Don't guess.
   • Never open the FASTA in Word, Excel or TextEdit and save it.

3. Add one row to run_dates.csv on SharePoint, at the bottom:

   sequencing_run,date,notes
   IV26Run7,2026-06-08,
   IV26Run8,2026-10-06,3 samples re-extracted      ← your new row
   

   The date is the one the sequencing team gives you, written YYYY-MM-DD. Notes are optional. Saving from Excel: CSV UTF-8 (Comma delimited) (all rules).

Part B: build the pipeline inputs (~5 minutes)

B1. Copy the latest files from SharePoint into source_prep/

• Copy all FASTA files from SharePoint's runs/ into source_prep/runs/, replacing files already there.
• Copy SharePoint's run_dates.csv into source_prep/, replacing the old one.

Tip

Windows (WSL): in the Ubuntu terminal, inside nextstrain, type explorer.exe source_prep to open the folder in Explorer, then drag the files in. Mac: in Finder press Cmd+Shift+G and paste the path to nextstrain/source_prep. If SharePoint files show a cloud icon, right-click → Always keep on this device first, so you copy the real file and not an empty placeholder.

B2. Run the script

cd ~/nextstrain                      # or wherever your nextstrain folder is
conda activate pekosz-nextstrain
python scripts/prepare_source.py

It takes a few seconds and needs no options. It only reads runs/, run_dates.csv and source/, and writes into source_prep/output/. (python3 works too, even without the conda environment.)

B3. Read the RESULT and copy the files

The last lines say RESULT: READY or RESULT: STOPPED.

• STOPPED: nothing was made. Each problem has a HOW TO FIX line; the full list is in Step 1: Problems. Fix it and run the command again until it says READY.
• READY: read any [WARNING] lines (what they mean). A POSSIBLE CONTAMINATION warning goes to the sequencing team and Dr. Pekosz.

Then copy these two files into source/, replacing the old ones (don't rename them, and leave prep_report.txt where it is):

source_prep/output/JHH_sequences.fasta   →  source/JHH_sequences.fasta
source_prep/output/JHH_metadata.txt      →  source/JHH_metadata.txt

You're done ✅

Your source/ now includes run IV26Run8. Archive the previous build and run the pipeline: Step 2.

Troubleshooting / FAQ

• I edited run_dates.csv locally. Make the same change on SharePoint, or the next person won't have it.
• It says a run has a FASTA but no date. You skipped Part A step 3 (or didn't copy the new run_dates.csv down).
• It says I copied a whole run folder. Move the FASTA itself into runs/ and remove the folder.
• RESULT: UNEXPECTED ERROR. A bug, not your fault: send everything printed (and source_prep/output/prep_report.txt, inside JHU only) to the maintainer.

Next step → Tutorial 3: Updating Vaccine Strains from GISAID