Species Detection Heatmap

What you’re building

Imagine uploading a species detection CSV and instantly seeing a color-coded heatmap showing exactly which species were found at which sites — sortable, filterable, and click-to-highlight. No R, no ggplot, no Python seaborn. Just one HTML file you can open on any lab computer or project in a conference talk.

That is what you will build in the next 20 minutes.

By the end of this lesson you will have a standalone species detection heatmap that runs entirely in the browser. It accepts a CSV of species detections by site, renders an interactive heatmap with CSS-styled cells, provides summary bar charts for species richness and detection frequency (Chart.js), and lets you click any species to highlight its distribution across all sites.

Who this is for

• eDNA survey researchers who need a fast, shareable visualization of detection results across sites.
• Natural resource managers who want to see species distributions across monitoring sites without learning R.
• Graduate students presenting eDNA survey results at lab meetings or conferences who want an interactive figure they can click through.

The showcase

Here is what the finished tool looks like once you open the HTML file in a browser:

• Header with a file upload area for your detection matrix CSV (or a textarea for pasting).
• Heatmap grid — rows are species, columns are sites, cells are colored (green = detected, gray = not detected, with opacity scaling if read counts are provided instead of binary values).
• Sorting controls — sort rows by species name (alphabetical), total detections (most to fewest), or detection frequency. Sort columns by site name or species richness.
• Species richness bar chart (Chart.js) — one bar per site showing how many species were detected there.
• Detection frequency bar chart (Chart.js) — one bar per species showing at how many sites it was found.
• Click-to-highlight — click any species name to highlight all sites where it was found. Click a site header to highlight all species found there.
• Summary stats — total species, total sites, average richness, rarest species, most common species.

Everything runs client-side. Your detection data never leaves your browser.

The prompt

Open your terminal Terminal The app where you type commands. Mac: Cmd+Space, type "Terminal". Windows: open WSL (Ubuntu) from the Start menu. Full lesson → , navigate to a project folder project folder A directory on your computer where the tool lives. Create one with "mkdir my-project && cd my-project". Full lesson → , start your AI CLI tool AI CLI tool Claude Code, Gemini CLI, or Codex CLI — a command-line AI that reads files, writes code, and runs commands. Full lesson → (e.g., by typing claude), and paste this prompt:

Build a single self-contained HTML file called species-heatmap.html that serves
as an interactive species detection heatmap for eDNA survey data. Requirements:

1. DATA INPUT
   - File upload button accepting .csv files plus a textarea for pasting CSV data
   - CSV format: first column is species name, remaining columns are site names,
     cell values are either 0/1 (presence/absence) or integer read counts
   - If read counts are provided (values > 1), treat any value > 0 as "detected"
     for the heatmap but use the count for opacity scaling
   - Include a "Load Example" button with this embedded dataset:

     Species,Devils_Lake,Mirror_Lake,Lake_Mendota,Trout_Creek,Spring_Creek,Yahara_River,Pheasant_Branch,Lake_Wingra
     Salvelinus_fontinalis,1,0,0,1,1,0,0,0
     Micropterus_salmoides,1,1,1,0,1,1,1,1
     Oncorhynchus_mykiss,0,0,0,1,1,0,0,0
     Lithobates_catesbeianus,1,1,1,1,1,1,1,1
     Chelydra_serpentina,0,0,1,0,0,1,0,1
     Esox_lucius,1,1,0,0,0,1,0,0
     Salmo_trutta,0,0,0,1,1,0,0,0
     Ambloplites_rupestris,1,0,1,0,0,1,1,0
     Cyprinus_carpio,0,0,1,0,0,1,0,1
     Notemigonus_crysoleucas,1,0,0,0,1,0,0,0
     Ictalurus_punctatus,0,0,1,1,0,0,0,1
     Notropis_hudsonius,1,0,1,0,0,1,0,0
     Catostomus_commersonii,0,1,0,0,1,0,1,0
     Perca_flavescens,1,0,1,1,0,0,0,1
     Lepomis_macrochirus,1,1,1,0,1,1,1,1

2. HEATMAP GRID
   - Render as an HTML table with CSS-styled cells
   - Detected cells: background #10b981 (green), not detected: #374151 (dark gray)
   - When input has read counts > 1, scale the green opacity from 0.3 (low reads)
     to 1.0 (highest reads) so abundance differences are visible
   - Species names in the first column, site names as column headers rotated 45
     degrees for readability
   - Hover tooltip on each cell showing: species name, site name, and value
     (detected/not detected, or read count if provided)
   - Cell size uniform, roughly 36x36 pixels

3. SORTING AND FILTERING
   - Row sort buttons: Alphabetical (A-Z), By Total Detections (descending),
     By Detection Frequency (descending, same as total for binary data)
   - Column sort buttons: Alphabetical (A-Z), By Species Richness (descending)
   - Text filter: type a species name to filter rows (partial match, case-insensitive)
   - Detection filter slider: show only species detected at >= N sites

4. SUMMARY CHARTS (Chart.js from CDN)
   - Vertical bar chart: Species Richness per Site (one bar per site column,
     y-axis = number of species detected, bar color #10b981)
   - Horizontal bar chart: Detection Frequency per Species (one bar per species
     row, x-axis = number of sites, bar color #38bdf8)
   - Both charts update when filtering or sorting changes the visible data

5. CLICK-TO-HIGHLIGHT
   - Click a species name (row header) to highlight that entire row plus all
     column headers where it was detected. Second click deselects.
   - Click a site name (column header) to highlight that entire column plus all
     row headers for species detected there. Second click deselects.
   - Highlight color: border #facc15 (yellow), 2px solid

6. SUMMARY STATS (top panel, updates with filters)
   - Total species shown / total in dataset
   - Total sites
   - Average species richness (mean across sites)
   - Rarest species: name and detection count (fewest sites, >0)
   - Most common species: name and detection count
   - Most species-rich site: name and richness count

7. DESIGN
   - Dark theme: background #0f172a, cards #1e293b, text #e2e8f0, accent #38bdf8
   - Clean sans-serif font (Inter from Google Fonts CDN)
   - Responsive layout: heatmap scrolls horizontally on narrow screens
   - Include a Clear button to reset everything
   - Add an "Export PNG" button that uses html2canvas (CDN) to capture the
     heatmap as a downloadable image

8. TECHNICAL
   - Pure HTML/CSS/JS in one file, no build step
   - Chart.js loaded from CDN (https://cdn.jsdelivr.net/npm/chart.js)
   - html2canvas loaded from CDN (https://cdn.jsdelivr.net/npm/html2canvas)
   - CSV parsing handles quoted fields
   - All processing client-side, no data uploaded anywhere

What you get

After the LLM finishes (typically 60-90 seconds), you will have a single file: species-heatmap.html. Open it in any browser.

Expected output structure

species-heatmap.html    (~500-700 lines)

Click Load Example and you should see:

1. A 15 × 8 heatmap grid with green cells (detected) and gray cells (not detected).
2. Two ubiquitous species with green cells across most or all columns: Lithobates catesbeianus (8/8 sites) and Micropterus salmoides (7/8 sites).
3. Two rare species with green cells in only 2 columns: Oncorhynchus mykiss (Trout_Creek and Spring_Creek) and Salmo trutta (same two sites — both are cold-water species restricted to trout streams).
4. The species richness chart showing Devils_Lake and Lake_Mendota with the highest richness (8-9 species each).
5. The detection frequency chart showing Lithobates catesbeianus at the top with 8 sites and Oncorhynchus mykiss / Salmo trutta at the bottom with 2 sites each.
6. Click highlighting — clicking Esox lucius should highlight Devils_Lake, Mirror_Lake, and Yahara_River.

If something is off

How it works (the 2-minute explanation)

You do not need to understand every line of the generated code, but here is the mental model:

1. CSV parsing reads the first row as site headers and the first column of each subsequent row as a species name. Every other cell becomes a detection value (0 or a read count).
2. The heatmap is an HTML <table> with CSS styling. Each cell gets a background color based on its value. For binary data, it is green or gray. For read counts, the green opacity scales linearly with the count.
3. Sorting rearranges the table rows or columns by rebuilding the <table> from the sorted data array. JavaScript sorts the underlying data, then re-renders.
4. Click-to-highlight attaches an event listener to each row header and column header. When clicked, it adds a CSS class to the relevant cells. A second click removes it.
5. Chart.js renders the two bar charts. When filters change, the chart data is updated and the charts re-render.

Customize it

The base heatmap is useful as-is, but here are extensions that make it more powerful for publication and analysis:

Add read-count gradient mode

Add a toggle between "Presence/Absence" mode (binary green/gray) and
"Abundance" mode (green gradient scaled by read count). In abundance mode,
show the read count number inside each cell in small white text. Add a
color scale legend showing the gradient range from the minimum to maximum
read count.

Add site metadata row

Add a row at the top of the heatmap for site metadata. Let me upload a second
CSV with columns: Site, Latitude, Longitude, Habitat_Type, Date_Sampled.
Display Habitat_Type as a colored bar above each site column (e.g., lake=blue,
river=cyan, pond=teal, stream=green). Show the other metadata in the hover
tooltip.

Add similarity clustering

Add a "Cluster" button that reorders both rows and columns by similarity
using Jaccard distance. For rows: species with similar site distributions
should be adjacent. For columns: sites with similar species compositions
should be adjacent. Use a simple hierarchical clustering approach
(nearest-neighbor linkage). Add dendrograms on the left side (species)
and top (sites) showing the clustering tree.

Try it yourself

1. Open your CLI tool in an empty folder.
2. Paste the main prompt from above.
3. Open the generated species-heatmap.html in your browser.
4. Click Load Example and verify the heatmap renders correctly.
5. Try sorting by detection frequency — the trout species should drop to the bottom.
6. Click Lithobates catesbeianus to see it highlighted across all 8 sites.
7. If you have real eDNA detection data (or output from the contamination checker in the previous lesson), paste it in and see your own heatmap.

Key takeaways

• Presence/absence heatmaps are the standard visualization for eDNA survey data — and building your own gives you full control over formatting and interactivity.
• Sorting reveals ecological patterns: sorting by detection frequency separates ubiquitous species from rare ones; sorting sites by richness highlights biodiversity hotspots.
• Click-to-highlight makes the heatmap interactive in a way that static R or Python plots cannot match — ideal for presentations and exploratory analysis.
• The heatmap connects directly to the contamination QC checker from the previous lesson: clean your data first, then visualize the results.
• Export to PNG makes the heatmap immediately usable in papers, reports, and slide decks without screenshots.

What’s next

In the next lesson, you will build a Single-Cell Expression Explorer — a UMAP/t-SNE viewer for pre-computed coordinate CSVs with cluster coloring. Same single-file HTML pattern, but applied to single-cell genomics data. If eDNA tells you which species are where, single-cell tells you which genes are active in which cells — a different scale of biodiversity.