Applied AI-Powered Bioinformatics Tools

Species Detection Heatmap

Last reviewed

Beginner

What you'll learn

~45 min
  • Ask an AI tool, in plan mode, for a page that draws an eDNA project's detection table (one row per taxon per site, made after the lab's control review) as a grid of taxa by site
  • Read its plan for what matters: every site shown, a site with no results marked as such, the rank each taxon was assigned to, the control review's result in its cell, and detections in only one replicate marked
  • Check the grid against values worked out for the practice files
  • Show on the grid how many replicates each detection rests on, and say what an empty cell does and does not mean

The story, and what you will end up with

It is Wednesday 11 November 2026 at an environmental DNA laboratory that extracts and sequences water samples for field researchers. You are the staff scientist who prepares each project’s results. A project’s investigators and field team meet next week, and they have asked for one picture: which taxa were detected at which of their eight sites.

The work that decides what goes in that picture is already done. The field team took three water samples at each site, the replicates of this project’s design, and each was extracted and sequenced on its own, with extraction blanks, field blanks and PCR negatives (reactions with no sample in them) alongside. The lab’s bioinformatics pipeline assigned each sequence to a taxon against a reference database and counted reads per taxon in every replicate. Libraries (each replicate’s DNA prepared for the sequencer) that failed were made again from the stored extracts; the ones that failed twice are written down, and the investigators have been told. Then the lab’s control review compared every taxon’s reads in the samples with its reads in the blanks, and recorded for each taxon at each site whether it is clear, inconclusive (not settled), or removed. (Lesson 15 is about that review; in this lab it comes before this step.) What you have now is the table that came out of it, one row per taxon per site.

The project’s analysis plan, written before any sample was taken, sets what counts: a replicate is positive at 10 reads or more, and a detection in only one replicate is reported as a one-replicate detection, with a caveat. (These are this practice project’s own rules, numbers included. Your project’s own analysis plan is the one that governs.) The practice files hold the first rule; you give your AI tool the second yourself.

Two things should be in your hands before you draw anything: the control review record for this run, signed off by the lab manager, with what every blank and control showed (these practice files say only that the review was completed on 6 November), and, from the investigators, which taxa the project is watching for (these files do not say). Check too that the table’s dates follow the review it came from, and what the analysis plan says about reporting a site with fewer replicates analysed, like S06, or none, like S08. Anything the review left open goes to the lab manager before you draw. In these files invented catfish is such a case: it was also in an extraction blank, it is inconclusive at S01 and S03 but clear at S06, and the files do not say which samples were extracted alongside that blank. With real files you would ask first; here, carry on, and the grid shows it as recorded.

By the end of this lesson you will have a small page on your own computer, the detection grid, that draws that table as taxa down the side and sites across the top, for the team to read at the meeting and on paper. It draws what the table says and decides nothing. You build it by asking your AI tool in plain English, and you check it against numbers this lesson gives you.

🔍Words used in this lessonclick to expand
  • eDNA: environmental DNA; in this project, the DNA in the water samples the field team took at each site.
  • Taxon (plural taxa): a named group the pipeline assigned reads to. Here most are species, one is a genus and two are families.
  • Assigned rank: how far down the assignment reached. Nothing in these files says whether a family row is a different fish from the species rows, so a family row is not counted as an extra species.
  • Replicate: here, one of a site’s three water samples, each extracted and sequenced on its own.
  • Marker: the stretch of DNA the lab amplifies and reads to tell taxa apart.
  • Library: one replicate’s amplified DNA, prepared for the sequencer. In these practice files, a replicate whose library failed has no reads: its cells are blank, not 0.
  • Positive replicate: a replicate with at least the project’s minimum of reads for that taxon, 10 in this practice project.
  • Blanks: controls that carry no sample. A field blank is clean water taken through the field steps, an extraction blank goes through extraction with the samples, and a PCR negative is a reaction with no DNA added.
  • Control review: the lab’s comparison of each taxon’s reads in the samples with its reads in the blanks. In these files its result is clear, inconclusive (also found in an extraction blank, not settled) or removed (reads in the samples at or below the blank’s). Those results, and the rule for removed, are this practice lab’s own and simpler than a real review; how a review decides is set by your lab’s own procedures.
  • Key: the box on the page that says what each kind of cell and mark means.
  • No results: a site where no replicate could be analysed. That is different from an empty cell at a site that was analysed, where the table records no detection.

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:

Terminal window
mkdir -p ~/bio-workbench/16-detection-grid && cd ~/bio-workbench/16-detection-grid

Start 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/16/detections.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 (detections.csv, sites.csv and project.csv), 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 detections.zip in your browser, check where it went (the browser’s list of downloads shows the folder), and tell your AI tool, for example: “detections.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 detections.zipclick to expand

Three files, each of which opens in a spreadsheet program:

  • project.csv: the project’s details: project P16, one fish and amphibian marker, three replicates per site, a positive replicate at 10 reads or more, sampled 22 to 24 September 2026, control review completed 6 November, table prepared 9 November.
  • sites.csv: the eight sites, S01 to S08, with how many replicates were collected and analysed, and a note where something failed.
  • detections.csv: 44 rows, each a taxon at a site with at least one positive replicate, with the reads in each replicate, how many replicates were positive, how many were analysed, the assigned rank, the control review’s result and the reads in the blank it was compared with. Every row has at least one replicate at 10 reads or more, so a taxon with only a few reads at a site may have no row there.
SiteReplicates analysedNote
S01 to S05, S073 of 3
S062 of 3replicate 3’s library failed, also after it was made again from the stored extract; its reads are blank, not 0
S080 of 3no results: all three libraries failed, also after they were made again

Twelve taxa: invented dace, shiner, darter, sucker, trout, frog, salamander, newt and catfish (assigned to species), invented sculpin genus (to genus), and invented sunfish family and minnow family (to family).

Control review results: 40 rows clear; invented catfish inconclusive at S01 and S03 (also in the extraction blank, 31 reads there); invented frog at S02 and invented sucker at S06 removed (at or below the blank).

A few replicates have reads under 10, such as invented sucker’s 4 reads in S01 replicate 3. They are in the file but not counted as positive.

Everything in these files is made up for this course: the project, its sites (each described as invented), every taxon (each called “invented” something, such as invented dace) and every number; no real sample or run produced them, and nothing here is a finding about a real species or a real place. Each lesson in this track has its own practice files, with their own people 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 to see:

Our lab sequences eDNA samples for field projects. From the files in data, build a page I can open in my browser: which taxa were detected at each site, with the control review result. Ask me what you need first.

Your AI tool usually reads all three files and comes back with questions, often with a suggested answer for each.

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 asksYou might say
Should the control review’s results be taken as recorded?Yes, show the control review as recorded.
Show the removed records, or leave them off the page?Show them, marked as removed and not counted as detections.
Inconclusive records: with the detections under a warning, or apart?Show inconclusive cells apart from detections, in a style of their own.
Show S08 as no results, and S06’s cells out of its 2 analysed?Yes, S08 as no results; S06’s cells out of 2, with the lab’s note.
Is there a rule for how many positive replicates a detection needs, or just show 1 of 3?Mark the ones in only one replicate: our analysis plan calls them one-replicate detections.
Genus and family rows: listed with the species, and counted per site?Yes, show the rank, and no per-site count.
Reads for each replicate, or a summary?A short summary in each cell, reads per replicate when I point at it.
One section per site, or a single grid?One grid: sites as columns, taxa as rows.
Who reads it?The lab manager first, to check it; then the investigators and field team, on screen and printed.
One file you open directly, without a server (a program that keeps running to show the page)?Yes, one file that works with no internet.

If it asks several questions at once, answer the ones about what a cell means, what counts as a detection and who reads the page from your project’s analysis plan and your lab’s procedures, a sentence each, and accept its suggestions only about how the page 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.

If it did not ask about detections that rest on one replicate, give it the plan’s rule as a message of its own, and wait for its reply:

Our analysis plan calls a detection in only one replicate a one-replicate detection. Mark those cells on the grid.

Then ask for the mark your lab puts on anything not yet signed off:

Mark the page and every printed copy as a draft, not for release until the lab manager approves it.

Wait for its reply, then read the plan.

This page shows the removed and inconclusive cells so you can check them against the table. Whether they appear on the copy that goes to the project is for the lab manager to decide under your lab’s procedures.

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:

  1. Every site in sites.csv has a column, S08 included, marked as having no results rather than left empty like a cell with no detection recorded; S06 shows that it had two replicates analysed.
  2. Every taxon has a row, with its assigned rank, and genus and family rows are not counted as extra species.
  3. Every cell comes from a row of detections.csv and none is coloured by read count; inconclusive and removed cells look different from detections and are not counted as detections.
  4. Detections in only one replicate are marked as one-replicate detections, and the inconclusive and removed cells are not among them.
  5. The project’s details print with the grid, so a printed copy says which project, marker and dates it shows, and the draft mark shows on screen and on every printed page.
  6. Your files are read and left as they are, and the page works on this computer with no internet connection.

A first plan often leaves one of these out. Say so in a sentence, in your own words, for example:

Make it print with the project details and the key. Don't colour cells by read count. Give the one-replicate mark to clear cells only.

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 test what it built and tell you how to open it. 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 a few scratch files of its own, ask it what they are for, and to remove them if you do not want them there.

Look at what it built

Ask it to open the page:

Open the grid in my browser.

Your AI tool may open the page for you. If it gives you a file location or an address without opening it, copy that into your browser’s address bar and press Enter, or ask your AI tool to open it for you. If it starts the page at a local address, one ending in a number, and says the address is already in use, say: “Something else is using that address. Don’t stop it. Use a different address for my page.” If your AI tool does not take a message after opening the page, wait a minute. If it still does not, close the terminal window, open a new one, type this lesson’s folder line again, start your tool, and say: “Start the page again so it keeps running while we talk.” The page and your saved work are files in the folder, so nothing is lost. If the page shows no grid, tell your AI tool what the page says. When you have finished with the page, ask: “Stop the grid page if it is still running.” Your page will be laid out in its own way. To see it the way the team will see it on paper, use your browser’s print preview.

Check it for these:

  • There are twelve taxa and eight sites, S01 to S08.
  • Invented sculpin genus shows as a genus, and invented sunfish family and invented minnow family as families.
  • S08 is marked as having no results, not as twelve empty cells.
  • S06 shows two replicates analysed, so its cells read “of 2”, such as 2 of 2 for invented dace.
  • 40 cells show a detection the control review cleared, each with the number of positive replicates, such as 3 of 3.
  • 13 of those 40 are marked as one-replicate detections, and none of the inconclusive or removed cells is marked that way.
  • Invented catfish is inconclusive at S01 and S03 and does not look like a detection there; at S06 it is a clear detection, 1 of 2.
  • Invented frog at S02 and invented sucker at S06 are shown as removed, not as detections.
  • Invented trout has one detection, at S04, 1 of 3.
  • The cells with no row behind them for S01 to S07 are empty, or marked as having no record: seven sites by twelve taxa is 84 cells, less the 44 rows, which leaves 40 empty cells, a different 40 from the cleared detections.
  • The draft mark shows on screen and on every page of the print preview.
  • When you ask “Have my data 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: “Catfish at S01 looks like the other detections. Give inconclusive cells a look of their own.”

In the print preview, look at every page before you print. If a line overlaps another or something is cut off, say what you see, for example: “On the second page the draft line covers the column headings. Move it clear of them.”

Your page may also add up the species detected at each site. Leave that for now; the next section comes back to it.

Your AI tool may point out that invented catfish is clear at S06 but inconclusive at S01 and S03. That is the open question from the start of this lesson: the page shows what the control review recorded, and whether the S06 detection needs the same caution is for the lab manager, who signs the control review, to settle before the grid is shared.

Notice what a detection rests on

Look at the grid as the team will. 40 cells say detected, and the marked ones rest on a single replicate. Before you read on, count the marked cells along each column yourself, and look for the taxa that are never detected in more than one replicate.

13 of the 40 rest on one replicate: invented shiner and salamander at S02, frog and minnow family at S03, trout at S04, sucker, sunfish family and newt at S05, darter, catfish and minnow family at S06 (each 1 of 2), and shiner and newt at S07. S05 and S06 have three each: half of S05’s six detections, and three of S06’s five, where only two replicates were analysed. Three taxa, invented trout, newt and catfish, have no detection in two or more replicates anywhere. Every one of the 13 has 33 reads or fewer in all.

Count the cells on the grid rather than taking the number your AI tool tells you. It may give a total that does not match what its own grid shows; the grid is what the team will read. If it marked any inconclusive or removed cell as a one-replicate detection, tell it so in a sentence: they are not detections, so they are not among the 13.

If your page adds up the species detected at each site, look at S05: its count takes in the one-replicate detections of invented sucker and newt, as if they meant the same as the others, and it leaves out the family row, which may or may not be another species. A sum of cells that do not mean the same thing is not a count of species, so ask for it to go:

Take the count of species per site off the page.

Until any count like that is gone, the grid is not ready to show anyone.

Now the empty cells:

What does an empty cell mean on this page? Make the key say it.

Look for an answer that says an empty cell means the table records no detection of that taxon at that site, in the replicates analysed there, three or, at S06, two, and that it does not show the taxon is absent. Your AI tool may word it as the table having no row for that taxon at that site; that says the same. Every row in the table has at least one replicate at 10 reads or more, so an empty cell may still hide a few reads below that. If it calls an empty cell absent, ask it to change the key. Before an empty cell is read as “not detected”, whoever produced the table confirms that it holds every result the project’s analysis plan counts.

The US Geological Survey’s guide for resource managers on eDNA results (page dated 7 September 2022, read 11 November 2026) defines a false negative as the “failure to detect a species’ DNA at a sample or site despite the species or its DNA being present in the sample or site”, and a false positive at a site as “the detection of a species’ DNA in an environment, despite the species physical absence in the environment” (USGS, eDNA Communication Strategies). The same page says plans should include “definitions of critical terms like what is a negative, positive, or inconclusive eDNA sample and site.” That is why the rule for each kind of cell comes from the project’s analysis plan, and the key on the page says what each kind means.

On a detection grid, a cell marked as a detection means detected in so many replicates, never simply present, and an empty cell means no detection is recorded for the samples analysed, never absent.

What goes to the project as a detection, what goes with a caveat, and anything said about a taxon the project is watching for are decided by the lab manager with the project’s investigators, under the project’s analysis plan. A one-replicate detection of one of those, as invented trout at S04 could be, goes to the lab manager and the investigators before it goes on any shared figure; they may want it confirmed first.

One real run

Here is part of what one AI tool put in its page’s key after the empty-cell question above, with Claude Code on 11 November 2026. Yours will word it differently; check your page against the list above, not against this.

Not reported at this site: the detections table has no row
for this taxon here. Every row in the table has at least one
replicate at 10 reads or more, so the most likely reason is
that no replicate reached that minimum. It does not show that
the taxon is absent.

The files do not say how the table was filtered, so “the most likely reason” is your AI tool’s guess, not something the files show. The person who prepared the table can say why a taxon has no row.

The table and taxa it talks about are made up for this course.

How real projects differ

The practice files are small and tidy; a real detection table may carry more. Check what yours holds.

  • These files give each taxon only an assigned rank. Before a name goes on a page, ask your lab’s bioinformatician what else lies behind each name in your table, such as how closely the sequence matched the reference and whether another taxon matched almost as well.
  • These files give only the reads in the one blank each row was compared with. What each field blank, extraction blank, PCR negative and positive control showed belongs in your lab’s control review record, which is why you check that record before the grid.
  • Check whether your files carry reads per library with each library’s sequencing depth, positive controls, or the filtering your lab applied. Before anything is coloured or compared by reads, ask your lab’s bioinformatician what the reads can and cannot be compared on.
  • This grid does not hold how much water each replicate filtered, whether inhibition (something in the sample that holds the reaction back) was tested, when and in what conditions each site was sampled, or which taxa the marker was chosen to detect. Ask whoever designed the project what an empty cell can and cannot say for your project.
  • S06 had two replicates analysed, where S01 to S05 and S07 had three. Check what your analysis plan says about reporting and comparing a site like that, and ask whoever designed the project if it does not say.
  • A printed grid is read without the screen. The key, the project’s details, the marker and the date the table was prepared belong on the printed page.
  • Your lab’s own procedures say how a failed library is handled and when results are called finished.

Keep going

Small changes do not need plan mode. Say it in a sentence:

  • “Save a checkpoint.” Your AI tool saves a snapshot you can return to.

When you want a grid of a real project, use the finished page. It runs by itself, with your AI tool closed, so your AI tool never sees the project’s files. Nothing confidential or unpublished, and nothing about people or about animals under a protocol, goes to your AI tool or into this course folder; nor do the locations of sites that are kept private, or results covered by an agreement with the people who collected the samples. Your lab’s files will not be shaped like the practice ones: your lab may keep a table of reads per taxon per sample, and the per-site table may come from your lab’s own summary of it after the control review. 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:

  1. 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 project’s results are its investigators’ to decide on, and your lab may have agreements that cover them. Go on only if they allow this use.

  2. Decide on a folder of its own for your real project’s files, outside this course folder, for example ~/edna-results. 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 edna-results in my home folder.”

  3. Ask your AI tool for fill-in copies of the three files in that folder, with the same columns and one made-up row each, and to build the page from them:

    Make fill-in copies of the three data files in ~/edna-results, same columns, one made-up row each, that my spreadsheet opens. Build the page from them and show me.

    Look at the page it makes: one made-up taxon at one made-up site. Your AI tool may point out that one row of project.csv leaves out the other project details, such as the reads a positive replicate needs; if it asks whether the fill-in project.csv should list every field with made-up values, say yes. You can open the fill-in files in your spreadsheet program to see the shape the page reads. The sites file and the project file are yours to fill in there: one row per site with its replicates collected and analysed, and the project’s details from its analysis plan. If your lab’s per-site summary has other column names, tell your AI tool those names, with two rows you make up in the same shape, never real rows, and ask it to read files like that.

  4. Give the page your own project’s analysis plan in place of this practice project’s: how many replicates a site has, the reads a replicate needs to count as positive, what the plan calls a detection that rests on too few replicates, and what your control review’s results are called. Put your own numbers and names where this example has its made-up ones:

    Use our plan instead of the practice one: four replicates per site, each positive at 20 reads, provisional below two positive replicates, review results pass, query, fail. Update the fill-in files in ~/edna-results to match.

    Wait for its reply, then:

    Make up a site with a detection under each rule and show me.

    Check that each made-up detection is marked the way your plan says, and that a cell your review did not clear is not shown as a detection. Your AI tool may ask how a result such as query should be shown, or whether a result like it counts as a detection; answer from your plan.

  5. Ask your AI tool for the exact line:

    Write me the exact line to build the page myself from my three files in a folder called edna-results in my home folder, with full paths, saving the page 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/16-detection-grid/scripts/build_report.py /home/dana/edna-results /home/dana/edna-results/report.html

    Read it left to right. python3 runs a Python program. Next comes the program your AI tool wrote to build the page, in this lesson’s folder; then the folder that will hold your three files; last, the page it writes there. /home/dana is the home folder of someone whose user name is dana; your own user name goes where dana is, 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. Ask your AI tool, too, what the three files must be called and which column names they must keep, and note that too. If your page instead opens files with a button, note too which button. If you are unsure about any part, ask your AI tool now, while it is still open.

  6. Leave your AI tool the way you did at the start of this lesson.

  7. Put your three files in that folder in place of the fill-in copies, named as your AI tool said. Paste the line from your note at the $ or % prompt and press Enter. The page appears beside your real files, not in the course folder. Open it in your browser. 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 with mkdir. Before anyone else sees it, check it cell by cell against the per-site table as the lab manager signed it off, and take any taxon that was also found in a blank to the lab manager.

Try another case

Before the quiz, write two or three sentences for yourself. At the meeting, an investigator points at the grid and says: “So the trout is at S04, and there are no newts at S02.” What would you say?

A good answer separates the two halves. The S04 cell is one replicate of three, 12 reads, a one-replicate detection under the project’s analysis plan, so it is a detection to report with its caveat, not a finding that trout live there; what is done about it is for the lab manager and the investigators. The empty S02 cell means the table records no newt detection in the three replicates analysed there, which is not the same as no newts.

Key takeaways

  • Ask briefly, and let your AI tool ask back. Say what the lab does, which files to use and what you want to see.
  • Read the plan for what a cell means: every site shown, no results marked, rank shown, the control review’s result in the cell, one-replicate detections marked.
  • A cell marked as a detection rests on so many replicates, and the grid should show how many; an empty cell means only that no detection is recorded.
  • The project’s analysis plan says what each kind of cell means, and people decide what is reported.
  • Practice data stays practice data: real projects go to the finished page, with your AI tool closed, after the data check.
KNOWLEDGE CHECK

On a grid like this one, invented newt's cell at S02 is empty: the detection table has no row for invented newt at S02, and S02 had three replicates analysed. What does the empty cell tell the project team?

What’s next

The next lesson is about a single-cell RNA sequencing project that has already been analysed: drawing its cells as a map, and what such a map can and cannot show.

intellimetrics · Arlington, VA
© 2026 intellimetrics.net
Search lessons