Reproducible RNA-Seq Workflow Orchestrator
Last reviewed
BeginnerWhat you'll learn
~45 min- Ask an AI tool, in plan mode, for a program that reads the record a finished RNA sequencing run left behind (the lab's sample sheet, the log of every step and attempt, and the settings the run was started with) and lists what needs a look
- Give it your facility's rules, and read its plan for what matters: samples matched both ways, each step judged by its last attempt, every rerun listed, versions and reference compared with the settings, blanks flagged, and no word that sounds like a delivery
- Check its list against findings worked out for the practice files
- Say what can honestly be written about what was run, why it comes from the run log, and who decides what happens to results whose record shows a difference
The story, and what you will end up with
It is Tuesday 10 November 2026, 2 in the afternoon, in the bioinformatics group of a core facility. You are the staff scientist who runs the facility’s RNA sequencing workflow for client labs. On Monday evening you started it on LAB-52’s twelve samples, from the sample sheet LAB-52 submitted. The steps themselves (checking the reads, trimming them, aligning them to a reference, counting them per gene) are done by established workflow software that its community maintains. This lesson is not about that software, and not about whether the analysis choices were right. It is about the record a run leaves behind, and being able to say exactly what was run.
Before you started it, you did what comes first. You checked the read files the sequencing core delivered against the sample sheet, with the core’s checksums and read counts: all twelve samples arrived, with reads. You started the run from the facility’s pinned settings, the program versions and options the facility fixes for this workflow. Monday’s run stopped with errors, and at 8:41 this morning a colleague resumed it through the workflow’s own resume, from the group’s other server. The workflow’s end message says it completed with one error. You have copied the run’s record files to a folder of their own, so checking them changes nothing in the run itself.
Before anything goes back to LAB-52 (the count table, the read-check report and a paragraph saying what was run, for their methods section), you want to know: is every sample on the sheet in the run, and is anything in the run that is not on the sheet; did every step finish for every sample; was anything run again, and with the same program version and reference as the rest; and is anything the “what was run” paragraph needs missing from the record. Today that means reading a log of 53 rows by eye.
By the end of this lesson you will have a small program on your own computer that reads a run’s record files and makes that list, on screen and as a file your spreadsheet program opens. It runs no analysis step, judges no analysis choice and says nothing about the quality of the reads: it reads what the workflow wrote, compares it with the sample sheet and the settings, and says, with a reason, what needs a look. You build it by asking your AI tool in plain English, and you check it against findings this lesson gives you.
🔍Words used in this lessonclick to expand
- Sample sheet: the table a lab submits that names its samples, here with each sample’s condition and replicate number.
- Run log: the workflow’s own record of a run, one row for every time a step was tried on a sample, with when it started and finished, whether it finished or failed, which computer ran it, and the program and version the workflow recorded for it.
- Attempt: one try at one step for one sample. A step that failed and was tried again has two or more attempts; the last attempt is the one with the highest number.
- Resume: starting a stopped run again so that it carries on from the steps that had not finished, instead of starting over.
- Reference: the genome sequence the reads are aligned to. Annotation: the file that says where the genes are in it. Both come in releases, and this practice facility’s “what was run” paragraph names the release used.
- Settings file: the settings the run was started with: the reference, the annotation, the program and version the workflow pins for each step, and the main options.
- Strandedness: a line in the settings file that the counting step is given about how the library was made. Whether it matches LAB-52’s library is a question for whoever made the library; this lesson does not check it.
Before you start
First, if your AI tool is still open, leave it: type /exit and press Enter (if you use Antigravity, press Ctrl+D with nothing typed instead), and wait until you see the $ or % prompt. The next line goes there, in the terminal, not in the AI tool. It makes a folder for this lesson beside your practice folder and goes into it:
mkdir -p ~/bio-workbench/06-run-record-check && cd ~/bio-workbench/06-run-record-checkStart your AI tool with the start line you kept from the setup lesson, the one with approval prompts off. Then ask it to set the folder up:
Set this folder up so we can undo any change you make, download https://learn.intellimetrics.net/starters/biotech/06/run-record.zip and unpack it into a data folder, and save a checkpoint.Look for it saying three things: the folder is set up with Git (the program that saves snapshots, from setup), three files are in the data folder (sample-sheet.csv, run-log.csv and settings.txt), and a first snapshot, your checkpoint, is saved. Later you can ask whether the files have changed since then. If it does not mention one of them, ask: “Did you save a checkpoint with the files in it?” It may also keep the zip file in the data folder, which is fine; if it says it kept one somewhere outside this folder, ask it to delete that copy. If the download does not work, download run-record.zip in your browser, check where it went (the browser’s list of downloads shows the folder), and tell your AI tool, for example: “run-record.zip is in my Downloads folder. Unpack that one file into a data folder here, and save a checkpoint.” In Windows PowerShell or a desktop app, “my Downloads folder” works as is; only say “my Windows Downloads folder” if you use Ubuntu (WSL) on Windows, which keeps its own Downloads folder apart from Windows.
The box below says what is in the practice files; later steps refer to them.
ℹWhat is in run-record.zipclick to expand
Three files from one run of the practice facility’s workflow on LAB-52’s samples:
sample-sheet.csv: what LAB-52 submitted. Columns: Sample_ID, Lab, Condition, Replicate. Twelve samples, R-01 to R-12: R-01 to R-06 untreated, R-07 to R-12 treated.run-log.csv: 53 rows, one for each attempt at each step for each sample, in the order the attempts started. Columns: Sample_ID, Step (read_check, trimming, alignment, counting), Attempt, Status (finished or failed), Started, Finished, Host (the computer that ran it), Program, Version, Reference (alignment rows only). The version is the one the workflow recorded for that attempt.settings.txt: what the run was started with, one setting a line: the workflow’s version, the reference (PR-7), the annotation (PA) and its release, the program and version pinned for each step, the named option sets for trimming, alignment and counting (profiles T2, A1 and C3), the strandedness and how many times the workflow retries a failed step by itself (once).
| Program in the settings | Step | Pinned version |
|---|---|---|
| pracqc | read_check | 2.4.1 |
| practrim | trimming | 1.9.0 |
| pracalign | alignment | 3.2.0 |
| praccount | counting | 1.6.2 |
Monday’s steps ran on the host bio-a, from 18:00; this morning’s resumed steps ran on bio-b, from 08:41.
Everything in these files is made up for this course: every sample, lab, program name, version number, reference, host and time; no real workflow, program or reference produced them. Each lesson in this track has its own practice files, with their own samples and dates.
Switch to plan mode
Your AI tool is already open. Switch to plan mode now: Shift+Tab until it says plan, or /plan (the keys for each tool). In plan mode it usually reads your files, asks its questions and shows you a plan before it builds anything; the order can vary.
The conversation
Each message below is an example. Say it your own way.
Say what you want
Say what you do, which files to use, and what you want from them:
I run RNA-seq workflows at our core. Build a program that checks a finished run's records, like those in data, before results go back to the lab, by rules I'll give you. Ask me what you need first.Your AI tool usually reads the files and comes back with questions, starting with your rules. It may already point out some of what it sees.
Give it your rules
These are this practice facility’s own rules. Your facility’s are in its own written procedures; use those.
Our rules: every sample on the sheet needs read check, trimming, alignment and counting finished, each step judged by its last attempt and started after the one before finished. Nothing may be in the run that isn't on the sheet.Wait for its reply, then send the rule about timing:
The log shows only minutes, so a step that starts in the same minute as the one before it finished needs a look.Wait for its reply, then send the third message:
Every step's program version and reference must match settings.txt. List every rerun. Flag any blank in the settings. Say "needs a look" or "nothing found", never fine, release, approved or ready to deliver.The settings file holds what this practice facility’s “what was run” paragraph needs (the workflow’s version, each program and its version, the reference and annotation with their releases, and the main options), so a blank there is a gap in that paragraph. The list says “nothing found” rather than “fine” because it has checked the record and nothing else.
Answer its questions
Answer each in a sentence. These are questions the tools often ask, with one way to answer each. Yours may ask them in a different order or show a list of choices:
| If it asks | You might say |
|---|---|
| Does a rule block release, or only warn? | Neither. Each needs a look, with its reason, and I decide. |
| Does retries = 1 mean two attempts in all? | Yes, here two per run; a resumed run can add more. |
| Does “last attempt” mean the highest attempt number? | Yes, the highest attempt number. |
| Must a step start strictly after the one before, or is the same minute fine? | The log shows only minutes, so a same-minute start needs a look. |
| Should other steps’ blank reference fields need a look? | No. The reference check is for alignment only. |
| Should every rerun need a look, even one that finished and breaks no rule? | No. A rerun is listed; it needs a look only if it breaks a rule. |
| Missing or unclear records? | They need a look too. |
| Only this workflow’s four steps, or others too? | Just this workflow’s four steps. |
| On screen, a spreadsheet file, or something else? | A list on screen and a file I can open in a spreadsheet. |
If it asks several questions at once, answer the ones about your rules and how samples and steps are judged from your facility’s own procedures, a sentence each, and accept its suggestions only about how the list looks. If you cannot tell which kind a question is, treat it as a rule. If it asks something not listed here, answer it the same way, in a sentence.
Read the plan
Next it usually shows you a plan: what it will build and how it will check it. Read it for six things:
- Samples are matched both ways between the sheet and the run log, by their names as written, and a sample on one and not the other needs a look.
- Each step is judged by its last attempt: a step whose last attempt failed needs a look, and so does a step that started before, or in the same minute as, the same sample’s step before it finished.
- Every rerun is listed, apart from what needs a look. Every step’s program version and every alignment’s reference are compared with the settings file.
- Every blank in the settings is flagged, never filled in.
- Everything that needs a look gives its reason, and the list uses only the words you gave it.
- It is a program you can run again on the next run’s folder, and your files are read and left as they are.
A first plan often leaves one of these out, most often item 3. Say so in a sentence, in your own words, for example:
List reruns apart from what needs a look; a rerun needs a look only if it breaks a rule.If it does not say the program runs again on the next run’s folder, say: “Make it a program I can run again on each new run’s folder.”
When the plan has all six, approve it: if your AI tool offers a choice to go ahead, pick it; otherwise say “Yes, go ahead and build it.” In Codex, press Shift+Tab first to leave plan mode. In Copilot, saying it brings up a choice to go ahead; pick that. Let it build. It may run what it built and tell you how to run it yourself; either way, the next step asks it to. When it has finished, ask it: “Did you install anything, and where?” Nothing, or something inside this lesson’s folder, is fine for these lessons. If it names anywhere else on your computer, such as the zip file it downloaded, ask it what that is for, and to remove it if you do not want it there.
Look at what it built
Ask it to run what it built:
Run it on the files in data and show me the list.Your list will be worded and laid out in its own way, and some details may be only in the spreadsheet file, not on screen. Check it for these:
- R-21 needs a look: it is in the run log and not on LAB-52’s sheet.
- R-11 needs a look: it is on the sheet and has no row in the run log. Some lists show this as four missing steps.
- R-09 needs a look: its counting failed at its last attempt, attempt 3, run this morning on bio-b.
- R-04 needs a look: its alignment finished at attempt 3, this morning on bio-b, with pracalign 3.2.1, where the settings pin 3.2.0.
- R-10 needs a look: its alignment used the reference PR-6, where the settings say PR-7.
- The settings have a blank: the annotation release.
- Nothing is found against R-01, R-02, R-03, R-05, R-06, R-07, R-08 or R-12. Some lists name these eight; others list only what needs a look.
- Three reruns are listed, apart from what needs a look: R-04’s alignment (three attempts), R-07’s trimming (two) and R-09’s counting (three). Some lists give a line for each attempt after the first. R-07’s second attempt used the same program and version as the rest, so it is listed and nothing is found against it.
- No step is reported as starting before, or in the same minute as, the step before it finished; there is none in these files. R-04’s counting started at 09:33, after its third alignment attempt finished at 09:31.
- No line calls a sample fine, released, approved or ready to deliver. The setting’s own name, annotation_release, may appear.
- When you ask “Have my run files changed since the checkpoint?”, it compares them with the checkpoint and says no.
If something on the list is not true, tell your AI tool in a sentence what you see and what you expected, for example: “R-04 shows nothing found. Judge its alignment by attempt 3, its last, and compare that version with the settings.”
Notice where a methods paragraph comes from
Look at R-04 and R-10 on your list. Both finished every step. Neither would show in a check that only asked whether every step finished. Now ask your AI tool:
Write the alignment sentence of a methods paragraph twice: first from settings.txt alone, then from the run log. Show both, and don't change anything.Before you read on: which of the two would you send to LAB-52?
The sentence from the settings alone says reads were aligned to PR-7 with pracalign 3.2.0. It reads cleanly, and it is wrong for two of LAB-52’s samples. The sentence from the run log has to say that R-04 was aligned with 3.2.1 and that R-10’s alignment is recorded against PR-6; if yours does not, tell your AI tool so. Check too that it leaves R-21 out and says R-11 has no alignment at all; a sentence that says “all samples” may quietly include the one and skip the other. Neither sentence can give the annotation release: it is blank in the settings and nowhere in the log, so it is found in the facility’s own records, never guessed, and the facility’s pinned settings need it filled in before the next run. And the log records no options, so it cannot confirm that profile A1 was used either.
Only the log shows that this run finished across two versions of one program and two references. R-04’s 3.2.1 came with this morning’s resume on bio-b; R-10’s PR-6 alignment ran on Monday on bio-a, with the others, so the resume does not explain it. Whether either changes any of LAB-52’s counts is in neither file.
Before anyone decides anything, ask the colleague who resumed the run what they resumed it with: which sample sheet, and which server’s programs and reference. The run was started from LAB-52’s sheet, yet R-21 is in it and R-11 is not, and the files do not show which sheet each part of the run read. Settle R-21 first: a sample in the run that is not on the sheet may be another lab’s, and nothing goes back to LAB-52 until someone knows whose it is. Then R-11, whose reads arrived and were not processed; R-09, with no counts; and R-04 and R-10. Whether those samples are run again before anything goes out, or go out with the differences stated in the paragraph, and what LAB-52 is told about R-11, are decisions for you as the staff scientist responsible and whoever your facility names to sign off, under its procedures, not for the list or a sentence your AI tool drafted. A rerun that changed nothing, such as R-07’s trimming, still has a cause worth finding: its first attempt failed for a reason the log does not give.
The settings say what a run was meant to do and the run log records what each attempt did: write what was run from the log, and leave whether the results go back to the lab, and how, to the staff scientist responsible and whoever your facility names to sign off.
One real run
Here is part of what one AI tool said after the question above, with Claude Code on 11 November 2026. Yours will word it differently; check your two sentences against the checks above, not against this.
- **Profile:** the run log doesn't record alignment options, so profile A1 comes only from the settings. The log can't confirm it was used.The samples, profile and files it talks about are made up for this course.
How real records differ
- A label is not proof. The run log says PR-7 for eleven samples’ alignments and PR-6 for R-10’s. That shows a label differs; it does not show which genome file was used for any of them. Check whether your workflow records checksums of the reference, the annotation and the index the aligner used (a prepared copy of the reference that it searches); comparing those is one way to settle it, and R-10’s label is a reason to check the others’ too.
- A step run by hand may not be in the log. The practice log records every attempt neatly. A step someone runs outside the workflow, to fix one sample, may leave no row at all.
- Finished is not the same as usable. Real logs may also hold steps reused from an earlier run, steps retried with more memory, steps stopped by the scheduler, errors the workflow was told to ignore, and steps that finished but wrote an empty or cut-short file. An end message can say a run completed while one of these sits in the log. Check, too, that the count table going to the lab has a column for each sample on the sheet, and what it holds for a sample whose counting failed.
- The names may not line up so neatly. Read files may be named differently from the sheet, a sample may have several files, and a workflow’s task names may be codes with the sample buried inside them. R-1 and R-01, a space at the end or a capital letter can stop two names matching. Check how your workflow names samples before you trust a match.
- The settings may be spread over several files. A real run’s record may keep the reference in a parameters file, each program’s version in a file of its own, and the exact build of each program as a container identifier (a code that names one exact packaged copy of a program), beside the workflow’s own code revision. A version number alone may not say which build ran.
- The list checks the record, not the analysis. It does not check whether the strandedness setting matches the library, whether profile A1 suits these samples, or whether a change from 3.2.0 to 3.2.1 changes any count. The record cannot tell you that last one either.
- Sample names can identify people or animals. Check whether your facility’s names carry an identifier.
Keep going
Small changes do not need plan mode. Say each in a sentence, then run it again:
- “Have the program also write a ‘what was run’ paragraph for the lab from the run log, with a blank wherever the files don’t say.” Check that it names R-04’s version and R-10’s reference, and leaves the annotation release blank. It is a draft for you to check and edit; nothing goes to the lab until the people who decide have decided.
- “Does the program name any sample from these practice files? If it does, make it work those out from the files instead.” A program built in a conversation may keep your examples written into it, and on the next run’s files it would get them wrong.
- “Save a checkpoint.” Your AI tool saves a snapshot you can return to.
When you want to check a real run’s record, use the finished program. It runs on your real files by itself, with your AI tool closed, so your AI tool never sees them. Nothing confidential or unpublished, and nothing about people or about animals under a protocol, goes to your AI tool or into this course folder. Your workflow software’s record will not be shaped like the practice files: the steps and attempts may be in a trace or report file it writes, the versions in files of their own, and the settings in a parameters file. Do these steps in order; the first five happen now, while your AI tool is open and this folder still holds only the practice files:
-
Go through the data check, the questions in setup about what the data is, who decides how it is used, and which AI tool would see it. A lab’s samples and results are that lab’s to decide on, and human-sample data may need your facility director or compliance office as well. Go on only if they allow this use.
-
Decide on a folder of its own for your real files, outside this course folder, for example
~/run-records. Nothing has to be in it yet. If the folder is not there, ask your AI tool to make it: “Make an empty folder called run-records in my home folder.” -
Ask your AI tool for blank files and a made-up run to try: “Make me a blank sample sheet my spreadsheet program can open, in the run-records folder in my home folder, and a made-up run folder here with one sample, and show the program working on it.” Look for it running the program on the made-up run and showing what it found for that one sample. The blank sample sheet has the practice columns; if your facility’s sheet has others, tell your AI tool their names. Then look at your own workflow’s record and tell your AI tool the names of its columns or settings, file by file, with two rows you make up in the same shape, made-up sample names, versions and times, never a real row. For example: “My workflow’s trace file has the columns task, sample, status, attempt, submitted, completed, host and container. Its versions are in a file of their own. Here are two made-up rows of each. Change the program to read files like that.” Then paste the two rows you made up. Give column names only where your facility is content for them to go to your AI tool; if it treats them as confidential, ask whoever is responsible first, or make up equivalents. Real sample names never go to it.
-
Give the program your facility’s own rules in place of the practice rules, from its written procedures. For example: “Replace the practice rules with ours, which I’ll send next. Then make up one sample for each rule that only that rule flags, and show me the list.” Wait for its reply, then send your rules. Check that each made-up sample needs a look for the rule it was made for, with that rule’s reason.
-
Ask your AI tool for the exact line, for example: “Give me the exact one line to run this myself on a run folder inside a folder called run-records in my home folder, with full paths, saving the list there too.” Use your own folder’s name. If it offers to copy your real files into this folder instead, say no. Copy the line it gives you into a note. It will look something like this one, though yours may differ:
Terminal window python3 /home/dana/bio-workbench/06-run-record-check/check_run.py /home/dana/run-records/RUN_FOLDER --out /home/dana/run-records/RUN_FOLDER-check.csvRead it left to right.
python3runs a Python program. Next comes the checking program, in this lesson’s folder; then the run’s folder inside run-records;--outand the name after it say where the spreadsheet file goes.RUN_FOLDERstands for your run folder’s name, in two places; each run, you change it to that run’s./home/danais the home folder of someone whose user name is dana; your own user name goes wheredanais, and on a Mac the folders begin/Users/instead of/home/. The line runs the program where it is, so leave this lesson’s folder in place. If you are unsure about any part, ask your AI tool now, while it is still open. -
Leave your AI tool the way you did at the start of this lesson.
-
Copy a real run’s record files, the way you normally copy files on your computer, into a folder of their own inside run-records, named as your line names it. Paste the line from your note at the
$or%prompt and press Enter. The list appears beside your real files, not in the course folder. To come back to the lesson folder later, type this lesson’s folder line again, the line near the top of this page that begins withmkdir. -
Before you use the list on a new run, run it on a past run whose record you have already checked yourself, and compare every finding with what you found. If they differ, find out why first.
Try another case
Before the quiz, write two or three sentences for yourself. Next month a lab writes: “Your methods paragraph says every sample was aligned with version 3.2.0. Our reviewer reran sample 7 and got slightly different counts.” What do you look at first, and what do you tell the lab?
A good answer goes to that run’s log before anything else: sample 7’s last alignment attempt, its version, its reference and its host, and whether the paragraph was written from the log or from the settings. It tells the lab only what the record shows, and leaves whether anything is run again, and what is said, to the people your facility names.
Key takeaways
- A short ask, then your rules. Say what you do and which files; give your facility’s rules in its own words.
- Read the plan for how steps are judged: the last attempt, every rerun listed, versions and reference against the settings, blanks flagged.
- Check a new list against findings you know before you trust it on a run you do not.
- The settings say what was meant; the log says what ran. A “what was run” paragraph comes from the log.
- Practice data stays practice data: real records go to the finished program, with your AI tool closed, after the data check.
By this practice facility's rules, a sample's alignment has three attempts in the run log. Attempts 1 and 2 failed with version 3.2.0; attempt 3 finished with version 3.2.1. The settings pin 3.2.0. What does the list say about that sample's alignment?
The settings file says every alignment used reference PR-7. The run log shows one sample aligned to PR-6. Which should the 'what was run' paragraph for the lab follow?
What’s next
The next lesson checks a core facility’s service requests as they come in, before any work starts.