Single-Cell Expression Explorer
Last reviewed
BeginnerWhat you'll learn
~45 min- Ask an AI tool, in plan mode, for a page that draws the cells of an analysed single-cell RNA-seq dataset from its map files (a position and a cluster label for each cell), coloured by cluster or by one gene's counts
- Read its plan for what matters: each cell keeps the label its file gives it, cells are matched to their counts by name, the page counts and draws but computes nothing new, and it works with no internet connection
- Check the page's counts against values worked out for the practice files
- See, by switching between two maps of the same cells, why the area a cluster covers and the distance between well-separated clusters are not reliable measures of how many cells there are or how alike they are, and why a cluster label is the analysis's proposal, not a cell type
The story, and what you will end up with
It is Monday 16 November 2026 at a genomics core. You support the labs that send single-cell RNA sequencing projects through the core, from the samples arriving to the data going back. One lab’s project has been sequenced and analysed. The core’s analyst did the analysis with established single-cell analysis software: filtering out poor-quality cells, dealing with doublets (two cells captured as one), normalising, clustering the cells into groups, and drawing the two-dimensional map that shows them. Tomorrow at ten you, the analyst and the lab meet to look at the result together.
Before today you did what comes first. You read the analyst’s report: how the counts were normalised, how the map was made and with what settings, and how the cells were clustered. You looked at the analyst’s per-cluster quality figures and which samples each cluster’s cells came from. You read the project’s data agreement and checked that it lets you keep these per-cell files on your computer for the meeting. And you agreed with the analyst that the analyst speaks for what the analysis shows and presents both maps, and that no cluster is given a cell-type name in the room.
The lab’s postdoc has already seen the map in the report and says three things: clusters 3 and 5 are nearly the same cells, because they sit side by side; cluster 0 is the biggest population, because it covers the most space; and GENE-C is made in clusters 3 and 5, because that is where the map lights up when coloured by it. For the meeting the analyst sent three small files: the report’s map, a second map of the same cells made on purpose with one setting of the map step changed, and a table of counts for the five genes the lab asked about.
By the end of this lesson you will have a page on your own computer that draws those cells as a map, either map, coloured by cluster or by one gene’s counts, with the number of cells in each cluster and, for the gene you pick, how many of each cluster’s cells have at least one count. It computes no map, no clusters, no normalisation and no statistics: it reads what the analysis wrote, draws it and counts. It runs with no internet connection and sends nothing anywhere. 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
- Single-cell RNA sequencing: sequencing that keeps track of which cell each transcript came from, so the result is a count for each gene in each cell.
- Count: here, the whole number in the count table for one gene in one cell, as the analysis recorded it.
- Cluster: a group of cells the analysis put together, given a number.
- Map: two numbers for each cell,
dim_1anddim_2, that place it on a flat picture. A step of the analysis, here called the map step, works out these positions from many genes at once, and it has settings; the map file holds only the result. - Cells per cluster: how many cells in this dataset carry that cluster’s label, after the analysis’s filtering.
- Cells with at least one count: for one gene and one cluster, how many of the cluster’s cells have a count of 1 or more for that gene, out of how many cells the cluster has.
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/17-single-cell-map && cd ~/bio-workbench/17-single-cell-mapStart 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/17/single-cell-files.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 (map-a.csv, map-b.csv and counts.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 single-cell-files.zip in your browser, check where it went (the browser’s list of downloads shows the folder), and tell your AI tool, for example: “single-cell-files.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 single-cell-files.zipclick to expand
Three files, each of which opens in a spreadsheet program:
map-a.csvandmap-b.csv: one row per cell, with the columnscell(a name, CELL-0001 to CELL-0600),dim_1anddim_2(its position on the map) andcluster(0 to 6). The two files hold the same 600 cells with the same cluster labels; only the positions differ. Note the order:map-b.csvstands for the map in the report, andmap-a.csvfor the second map the analyst made with one setting changed. The difference between them is exaggerated, so that it shows plainly.counts.csv: one row per cell, with the columnscelland GENE-A to GENE-E, five invented gene names. Each value is a whole number of counts. The rows are in a different order from the map files, so the cell names are what match a cell’s counts to its place on the map.
| Cluster | 0 | 1 | 2 | 3 | 4 | 5 | 6 |
|---|---|---|---|---|---|---|---|
| Cells | 160 | 120 | 95 | 80 | 70 | 45 | 30 |
The clusters have numbers only. The files name no cell type, tissue or sample.
Everything in these files is made up for this course: every cell, gene, count and position; no real software, dataset, organism or person produced them. 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:
I support single-cell projects at our core. Build an offline page for my browser that draws cells from map files like those in data, switching between maps, coloured by cluster or one gene. Ask me what you need first.Your AI tool usually reads the files and comes back with questions. It may already say that the two maps hold the same cells with the same clusters, or that one gene has very few counts.
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 |
|---|---|
| One page you open by double-clicking, with these files built in, and a way to open others? | Show the files in data at start, with a button to open other files like them. |
| How many cells, usually? | Tens of thousands, sometimes more. |
| Will future files have the same columns? More than two maps? | Same columns, comma-separated, usually two maps. |
| Colour a gene by its raw count, or by a log of it? | The count as written, no transforming. |
| Draw cells with no count in grey, underneath the others? | Yes. Zero-count cells grey, underneath. |
| What if a cell is in one file but not another? | Warn me with the number, and never drop any silently. |
| Hover details, zoom, export, other extras? | Hover to see a cell’s name, cluster and count. Nothing else for now. |
| Which browser will it run in? | A current browser on my computer, with no internet. |
If it asks several questions at once, answer the ones about how cells are matched, counted and coloured, a sentence each, and accept its suggestions only about how the page looks, such as colours and dot size. If you cannot tell which kind a question is, answer it yourself. If it offers to find marker genes, compare clusters, cluster again or transform the counts, say no: the page only draws and counts what the analysis wrote. If it asks something not listed here, answer it the same way, in a sentence.
When it has your answers, say what you want counted for a gene:
For the gene I pick, show how many of each cluster's cells have at least one count, out of how many, and the share.Wait for its reply, then read the plan.
Read the plan
Next it usually shows you a plan: what it will build and how it will check it. Read it for five things:
- Each cell is drawn where its map file puts it, with the cluster label from that file, and switching maps changes no cell’s label or colour.
- Cells are matched to their counts by cell name, not by row, and a cell missing from one file is reported, not dropped.
- Cells per cluster are shown, and for the gene you pick, how many of each cluster’s cells have at least one count, out of how many, and the share.
- It computes nothing new: no map, no clusters, no normalisation, no statistics. It draws and counts what is in the files.
- It works with no internet connection, and your files are read and left as they are.
A first plan may still leave one of these out, item 3 among them. Say so in a sentence, in your own words, for example:
The plan leaves out the counts for the gene I pick. Show them for each cluster, out of how many, and the share.When the plan has all five, 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 page in my browser.A page opened straight from a file cannot read other files by itself, such as the practice files it shows at start. So your AI tool may copy the practice files into a file beside the page, or start a small program on this computer that serves the page at a local address, one ending in a number, such as http://127.0.0.1:8765/ (127.0.0.1 is an address that means this computer). If it gives you a file location or an address without opening it, copy that into your browser’s address bar and press Enter. 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 says it cannot load the files, tell your AI tool what the page says. When you have finished with the page, ask: “Stop the map page if it is still running.” Your page will be laid out in its own way.
Check it for these:
- There are seven clusters, 0 to 6, with 160, 120, 95, 80, 70, 45 and 30 cells, 600 in all, and the cells per cluster are the same on both maps.
- With GENE-A picked, 136 of cluster 0’s 160 cells have at least one count (85.0%), and 66 of cluster 2’s 95 (69.5%). No other cluster has more than 6 such cells. If cluster 0 shows 61 of 160 (38.1%), the counts have been matched to cells by row, not by name; tell your AI tool: “Match each cell’s counts by its name, not by its row.”
- With GENE-C picked: 64 of cluster 3’s 80 cells (80.0%) and 34 of cluster 5’s 45 (75.6%).
- With GENE-E picked: 56 of cluster 4’s 70 cells (80.0%) and 24 of cluster 6’s 30 (80.0%). With GENE-B picked: 11 of cluster 4’s 70, and none of cluster 6’s 30.
- When you ask “Does the page load anything from the internet, or send anything? Show me where.”, it says the page loads nothing from the internet and sends nothing, and shows you where it looked. You can also see it for yourself: turn off your computer’s Wi-Fi (or unplug its network cable), reload the page in your browser, and check that it still draws the cells and shows the counts. Turn the network back on before you send your AI tool another message, because the AI tool itself needs the internet.
- When you ask “Have my files changed since the checkpoint?”, it compares them with the checkpoint and says no.
The shares here are rounded to one decimal place. Where a share ends in exactly a half, such as 1 of 80, pages round it differently (1.2% or 1.3%); the counts before the share are what to compare.
If something on the list is not true, tell your AI tool in a sentence what you see and what you expected, for example: “Cluster 4 shows 80 cells. The map files give it 70; count the cells in each cluster from the map file.”
Notice what the map does not measure
Pick map-b.csv, the report’s map, coloured by cluster. Clusters 3 and 5 sit side by side, and cluster 0 covers more of the picture than any other. That is the picture the postdoc read. Now switch the page to map-a.csv and look again. Then ask your AI tool:
Don't change anything. Does any cell have a different cluster in map-a and map-b? On each map, where do clusters 3 and 5 sit, and which covers more space, cluster 0 or cluster 6?Before you read on: the cells and their clusters are the same in both files. What do you expect to have changed?
Only the picture. No cell has a different cluster in the two files, and the cells per cluster are the same. On map-b.csv clusters 3 and 5 sit side by side, closer than any other two clusters; on map-a.csv they are in opposite corners. On map-b.csv cluster 0, with 160 cells, covers far more of the picture than cluster 6, with 30; on map-a.csv it is the other way round, and cluster 6 spreads across more of the picture than any other cluster. Nothing about the cells moved between the two files. What changed is where the map step put them.
The practice files exaggerate this, but people who make and study such maps say the same of real ones. UMAP and t-SNE are two methods for drawing such a map, and the map they draw is called an embedding. The clustering chapter of a handbook of current practice, Single-cell best practices, says: “We recommend not interpreting distances between clusters visualized on UMAP embeddings.” UMAP’s documentation says that “UMAP has several hyperparameters that can have a significant impact on the resulting embedding” (hyperparameters are the settings chosen before it runs), and that “UMAP, like t-SNE, does not completely preserve density.” An article about t-SNE’s maps in the journal Distill says: “Cluster sizes in a t-SNE plot mean nothing”, where “By size we mean bounding box measurements, not number of points.” (Sources: Single-cell best practices, Clustering, by Anna Schaar, Seo H. Kim and Lukas Heumos; UMAP documentation, Basic UMAP Parameters and Using UMAP for Clustering, version 0.6.0; Martin Wattenberg, Fernanda Viégas and Ian Johnson, How to Use t-SNE Effectively, Distill, 2016; all read 11 November 2026.)
The clusters do not come from the map either. The same chapter advises grouping cells, with a method called Leiden, on a graph that links each cell to the cells most like it in the analysis (a KNN graph, for k nearest neighbours): “Use Leiden community detection on a single-cell KNN graph.” The map is drawn alongside it: “Visualizing the clustering can help us to understand the results, we therefore embed our cells into a UMAP embedding.” How many clusters come out depends on a setting too: “A higher resolution parameter leads to more clusters.” And deciding what a group of cells is, is judgment: the handbook’s annotation chapter says of cell types that “the size of categories and the borders drawn between them are partly subjective” (Single-cell best practices, Annotation, by Lisa Sikkema, Maren Büttner, Seo H. Kim and Lukas Heumos, read 11 November 2026). So the map cannot show that clusters 3 and 5 are nearly the same cells, or that they are different ones.
Now pick GENE-C. Cells with at least one count are mostly in clusters 3 and 5, 64 of 80 and 34 of 45, with a few in other clusters. That tells you which cells the analysis recorded counts for GENE-C in, in this dataset, and no more: the files hold no protein figures, and a cell with no count is one where the analysis recorded none. Whether GENE-C is made there, as the postdoc said, and whether a cell with no count can still make it, are questions for the analyst and the full analysis, not for this count. And cluster 0’s 160 cells are the cells in this dataset that carry its label after filtering; whether that says anything about the tissue the cells came from is a question for the full analysis and how the experiment was designed, not for this count.
On a map like this, the area a cluster covers and the distance between well-separated clusters are not reliable measures of how many cells there are or how alike they are, and a cluster is the analysis’s proposal, not a cell type: what the clusters are, and anything said to the lab about their biology, is for the analyst and the lab to judge from the full analysis, never from the picture.
So at the meeting the page is for looking together, not for deciding. The postdoc’s three points go to the analyst, who answers them from the full analysis: the genes that tell the clusters apart, each cluster’s quality figures, and which samples its cells came from. Agree before the meeting who writes down what was and was not concluded, and that nothing from the picture goes into the lab’s paper or a grant without the analyst.
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 page against the list above, not against this.
So map-a puts clusters 3 and 5 in opposite corners, about 25 apart.Map-b puts them side by side, 2.4 apart, closer than any other twoclusters on that map.
The two maps disagree on both questions with identical cluster labels.The 25 and 2.4 are distances in each map’s own units: positions on a picture, not a measure of how alike the cells are, and the two maps’ units cannot be compared.
The cells, clusters and numbers it talks about are made up for this course.
How real data differs
- Check how many maps your analyst delivers, and that the settings that drew each one are written in the report beside it. Ask for those settings before you show a map to anyone.
- Check which values a table holds. This page’s “at least one count” is read from the original counts only. If your analyst’s table holds normalised, scaled or batch-corrected values, it does not apply to that table: ask your analyst for the counts the analysis started from.
- Ask how deeply each cluster’s cells were sequenced, and whether that, or the cells’ quality, could change how many of a cluster’s cells show at least one count for a gene, or how a colour by count looks. Ask which values any figure you are shown was coloured by.
- A few counts can come from outside the cell. In droplet-based methods, the quality control chapter of the same handbook describes “a background contamination that represents expression not from the cell contained within a droplet, but the solution that contained the cells”, and a doublet carries two cells’ transcripts (Single-cell best practices, Quality Control, by Anna Schaar, Seo H. Kim, Lukas Heumos and Luke Zappia, read 11 November 2026). A few cells with a count in an unexpected cluster are a question for the analyst, not a finding.
- Real files may carry more columns. Check whether yours hold the sample, donor or batch each cell came from, its quality figures and doublet calls. Two clusters side by side can be two samples of the same cells. Ask which samples make up each cluster before reading anything into a pair of clusters.
- Real cell names may repeat across libraries. If two samples’ cells share names, matching by name merges different cells; ask for names that include the sample.
- A real dataset may hold tens of thousands of cells or more, drawn over each other, so whichever are drawn last hide the rest. Ask the page to say what it draws on top.
- Data from human donors may be under a protocol and an agreement that restrict even a per-cell table taken from it. Ask before the export, not after.
Keep going
Small changes do not need plan mode. Say each in a sentence, then look at the page again:
- “Show what each colour stands for, and say on the page which cells are drawn on top.”
- “Print the map file’s name on the picture, so a saved image says which map it is.”
- “Does the page name any cluster, gene or file from these practice files? If it does, make it read them from the files instead.” A page built in a conversation may keep your examples written into it, and on the next project’s files it would get them wrong.
- “Save a checkpoint.” Your AI tool saves a snapshot you can return to.
When you want to look at a real project’s files, use the finished page. It runs in your browser by itself, with your AI tool closed, so your AI tool never sees the 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. Do these steps in order; the first four 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 data is that lab’s to decide on, and data from human donors 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 real projects’ files, outside this course folder, for example
~/single-cell-maps. 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 single-cell-maps in my home folder.” -
Ask your AI tool for blank files to try: “Make me a blank map file and a blank counts file my spreadsheet program can open, in the single-cell-maps folder in my home folder, with one made-up cell, and show the page working on them.” Look for it opening those files in the page and showing one cell in its cluster, with 1 of 1 cells counted for a gene where the made-up count is above zero. Ask your analyst for files in this shape from the analysis: a map file for each map, with each cell’s name, position and cluster, and a counts file for the genes the lab asks about, with each cell named the same way in every file and, where a project has several samples, with the sample in each cell’s name. If the analyst’s files have other column names, tell your AI tool the names, with two rows you make up in the same shape, made-up cell names and numbers, never a real row, and ask it to make the page read files like that.
-
Ask your AI tool for the exact line, for example: “Write me the exact line to start this page myself, and its address, so I can open map and count files from ~/single-cell-maps.” Use your own folder’s name. If it offers to copy your real files into this folder instead, say no. Copy the line and the address it gives you into a note. They will look something like these, though yours may differ:
Terminal window xdg-open /home/dana/bio-workbench/17-single-cell-map/viewer/index.htmland the address
file:///home/dana/bio-workbench/17-single-cell-map/viewer/index.html. Read the line left to right:xdg-openopens a file in the program your computer normally uses for it, here your browser; next comes the page your AI tool wrote, in this lesson’s folder./home/danais the home folder of someone whose user name is dana; your own user name goes wheredanais, and on a Mac the folder begins/Users/instead of/home/and the line may beginopeninstead ofxdg-open. The address does the same from your browser’s address bar. The line depends on the computer: the one above came from a Linux computer, so ask your own AI tool for yours now, while it is open, and use that one. If pasting it later opens nothing, copy the address from your note into your browser’s address bar and press Enter; if that opens nothing either, type this lesson’s folder line again, start your tool, and say: “The line to open my map page opens nothing. Write me one that works on this computer.” If your page is served at a local address instead, you get a line that starts it and an address such ashttp://127.0.0.1:8765/. Note too which button on the page opens files, such as Open files. The line opens the page 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. -
Ask your AI tool to stop anything it started for the page, then leave it the way you did at the start of this lesson.
-
Put a real project’s files in single-cell-maps. At the
$or%prompt, paste the line from your note and press Enter, or open the address in your browser. Choose the files with the page’s button; the page reads them on your computer and saves nothing. 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 show the page to anyone, compare its cells per cluster with the analyst’s report. If they differ, find out why first.
Try another case
Before the quiz, write two or three sentences for yourself. At the meeting the lab sees that 80.0% of cluster 4’s cells and 80.0% of cluster 6’s have at least one count for GENE-E, and asks you to call the two clusters one cell type in their paper. What do you say, and what happens next?
A good answer notices that five genes on a page cannot settle it either way: the analysis grouped the cells on many genes, not on the five the lab asked about, and a share on one gene among 30 cells is a small number to lean on. It hands the question to the analyst, who can look at the genes that tell the clusters apart, each cluster’s quality and doublet figures, and which samples their cells came from, and who would treat merging them as a change to the analysis, not a decision made in the room. And it ends with a written note of what was and was not concluded.
Key takeaways
- Ask briefly, and let your AI tool ask back. Say what you do, which files and what you want to see; its questions fill in how cells are matched, counted and coloured.
- Read the plan for how cells are matched and counted: labels from the file, counts matched by name, nothing computed that the analysis did not write.
- Check a new page against numbers you know before you show it to a lab.
- The same cells can make very different pictures. Area on the map and the gap between well-separated clusters are not reliable measures of how many cells there are or how alike they are; cells per cluster is a count.
- Practice data stays practice data: a real project’s files go to the finished page, with your AI tool closed, after the data check.
On the report's map, clusters 3 and 5 touch. On a second map of the same cells, made by the analyst with one setting changed, they sit in opposite corners. Every cell has the same cluster label in both files. What can you tell the lab?
What’s next
The next lesson is about a finished sequencing run’s per-sample summary, and which samples need a look by a genomics core’s own rules before their data goes to the labs.