Applied AI-Powered Bioinformatics Tools

Proteomics Search Results Triage

Last reviewed

Beginner

What you'll learn

~45 min
  • Ask an AI tool, in plan mode, for a program that reads the protein-group table a database search writes (one row per protein group: the proteins its peptides cannot tell apart) and sorts the groups by rules you give it
  • Give it your core's rules, and read its plan for what matters: decoy groups listed apart, contaminants looked at whatever their score, every accession in a group shown, a reason beside every group that needs a look
  • Check its list against values worked out for the practice files
  • Say what the files show about a protein supported by one peptide, and what you check before anything about it goes to a lab

The story, and what you will end up with

It is Thursday 12 November 2026, 8 in the morning, at a proteomics core. You manage the core, and you decide what goes back to the labs it serves. LAB-42 sent a cell pellet with a submission form that names their organism and a protein they hope to see, PX-0009, untagged. The core lysed the cells, digested the proteins with trypsin and ran the digest on the instrument once.

Before this morning you did what comes first. The instrument’s quality-control standard ran before the sample and was in range by your core’s checks, and a blank ran between the previous sample and this one; you looked at it the way your core does. The search used your core’s usual settings for this kind of sample: the enzyme and how many missed cleavages it allows, the modifications it looks for, the mass tolerances, and its limits on false discoveries among the peptide-spectrum matches and peptides. It searched the protein database for LAB-42’s organism, together with your core’s list of common contaminants and a decoy version of every entry, each sequence reversed, so the software can estimate how many of its matches are false. You read the search’s own summary: it names the database and contaminant list versions, it reached the false discovery limits it was set to, and PX-0009’s sequence is in the database it searched. Your core’s settings write every protein group up to an estimated q-value (explained in the box below) of 0.05 into the table, so a near miss can be seen; your core reports at 0.01. Both numbers are this practice core’s own.

Now the search has written its protein table, 905 protein groups long, and its peptide list. Before anything goes to LAB-42 you want every group sorted into two piles, the ones that meet your core’s written rules and the ones someone needs to look at first, with the reason for each, and the decoy groups set apart. Today that means sorting a spreadsheet four ways.

By the end of this lesson you will have a small program on your own computer, the triage list, that reads a search’s protein table and makes that list on screen and as a file your spreadsheet program opens. It works out no score, probability or false discovery rate of its own: the search software did that, and the list reads its numbers as written and compares them with your rules. It never sends anything. 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
  • Peptide-spectrum match (PSM): one spectrum the search software matched to one peptide. The PSMs column counts them.
  • Protein group: the proteins the search could not tell apart because they share the same peptides. A group with two accessions (database identifiers) is one row with both, written PX-0011;PX-0012.
  • Unique peptide: here, a peptide found in one protein group only, among the entries in the database searched. A peptide in two groups is shared.
  • Decoy: an artificial sequence the search software adds for comparison; here its accession begins REV-. A group that matched a decoy is not evidence of a protein in the sample.
  • q-value: an estimate the search software makes from the decoys. If the list, ranked by score, were cut just low enough to take this group in, the decoy groups above the cut divided by the real ones would be about this number: an estimate of how many of the groups kept are false. Smaller is stricter. These practice files work it out from one search program’s one-line definition, quoted further down, taken down the list ranked by score.
  • Contaminant: a protein on your core’s list of ones that turn up in samples by accident or from handling.
  • Coverage: the share of the protein’s length that its peptides cover.

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/20-protein-triage && cd ~/bio-workbench/20-protein-triage

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/20/protein-results.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), two files are in the data folder (protein-groups.csv and peptides.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 protein-results.zip in your browser, check where it went (the browser’s list of downloads shows the folder), and tell your AI tool, for example: “protein-results.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 protein-results.zipclick to expand

Two files, each of which opens in a spreadsheet program, from one made-up search:

  • protein-groups.csv: one row per protein group, 905 rows. Columns: Protein_Group (the group’s number), Protein_IDs, Descriptions, Length_AA (the protein’s length in amino acids), Peptides, Unique_Peptides, PSMs, Coverage_Pct, Score (the software’s protein score, higher is better), Q_Value, Contaminant and Decoy (each + when marked).
  • peptides.csv: one row per peptide per group, 6,694 rows. Columns: Protein_Group, Peptide, Length, Missed_Cleavages, Modifications, PSMs, Best_Score, Unique (+ when the peptide is in that group only).

The groups this lesson names:

GroupProtein_IDsPeptidesUniquePSMsScoreQ_ValueMarked
1PX-000138381022,195.50
253CON-00012623662,180.20Contaminant
222CON-0002;CON-000314832935.30Contaminant
166PX-00079722604.70
610PX-0011;PX-00126615451.60
400PX-0013325154.20
549PX-0016315144.40
646PX-0009113120.00
162REV-PX-0031222113.80.0013Decoy
190PX-001522891.10.0101
44PX-001711290.40.0113

CON- accessions are on the contaminant list, REV- accessions are decoys, PX- accessions are the organism’s. Two more contaminant groups, CON-0004 and CON-0005 (a stand-in for the digestion enzyme), are in the file too. PX-0016 shares two of its three peptides with PX-0007, and PX-0013 one of its three with another group.

Everything in these files is made up for this course: every accession, description, peptide and number; the peptides are random letters, so any likeness to a real sequence is chance, and no instrument, database or real sample 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 from them:

I report protein identifications at a proteomics core. Build a program that sorts the protein groups in search results like those in the data folder into meets my rules or needs a look. 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: the decoy and contaminant groups, groups with more than one accession, or how many groups rest on one unique peptide.

Give it your rules

These are this practice core’s own rules, numbers included. Your core’s are in its own written reporting procedure; use those.

Our rules: a protein group needs a look if its q-value is over 0.01, it has fewer than 2 unique peptides, or it is on the contaminant list, whatever its score.

Wait for its reply, then send a second message:

List decoy groups apart, never as proteins. Show every accession in a group, counted once. Give reasons, using the file's numbers as written. Never call a protein confirmed or present.

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
Does exactly 0.01, or exactly 2 unique peptides, count as fine?Yes. Exactly at a limit is fine.
Minimums for PSMs, coverage or score as well?No. Only the three rules I gave.
Should groups with several accessions always need a look?No. A group with several accessions is fine if it meets the other rules.
Should peptide checks count, such as shared or modified peptides only?No peptide-level checks.
The Contaminant column, or a separate list?Use the file’s Contaminant column.
One reason for each group, or every reason?List every reason.
What about a missing or unreadable value?A missing value needs a look.
On screen, a spreadsheet file, or a page?A list on screen and a file I can open in a spreadsheet.
Keep the cutoffs in a settings file?A settings file for the rules is fine.
Should you be able to override a result and note why?No overrides; I decide outside the program.

If it asks several questions at once, answer the ones about your rules and how groups are counted from your core’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:

  1. Your rules as you gave them, each reason with the file’s numbers as written, and exactly at a limit counted as fine.
  2. Decoy groups listed apart and counted, never among the proteins.
  3. A contaminant group needs a look whatever its score.
  4. Every accession in a group is shown, and the group is counted once. Several accessions are not a reason on their own.
  5. The numbers come from the file: the program works out no score, q-value or false discovery rate again.
  6. It is a program you can run again on the next search’s files, and your files are read and left as they are.

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

Make it a program I can run again on the next search's files, and leave my files as they are.

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.

It may show the list in the terminal, or build a page and give you an address to open. If it builds a page, ask: “Open the list in my browser.” 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. When you have finished with the page, ask: “Stop the list page if it is still running.”

Your list will be worded and laid out in its own way. Check it for these:

  • 905 groups: 721 meet the rules, 141 need a look, and 43 decoy groups listed apart.
  • Of the 141: 4 are on the contaminant list (CON-0001; CON-0002 with CON-0003; CON-0004; CON-0005), 69 have a q-value over 0.01, and 125 have fewer than 2 unique peptides. 57 groups have both of those last two reasons, so 12 need a look for their q-value alone and 68 for their unique peptides alone.
  • CON-0001 needs a look as a contaminant, though its score, 2,180.2, is the second highest in the table.
  • PX-0015 needs a look: its q-value, 0.0101, is over 0.01. PX-0017 has two reasons: q-value 0.0113 and 1 unique peptide.
  • PX-0013 meets the rules with exactly 2 unique peptides. PX-0016 needs a look with 1; its other two peptides are shared with PX-0007.
  • PX-0009 needs a look: 1 unique peptide.
  • Group 610 shows PX-0011 and PX-0012 together and meets the rules, counted once among the 721. If your list counts accessions as well, the 721 groups hold 743, because 22 of them have two.
  • REV-PX-0031 is listed apart as a decoy, although its q-value, 0.0013, is under 0.01. Six other decoy groups are under 0.01 as well.
  • No line calls a protein confirmed or present.
  • When you ask “Have my search files changed since the checkpoint?”, it compares them with the checkpoint and says no.

The list compares the numbers as the file writes them, so 0.0101 is over 0.01 even though it would round to 0.01.

If something on the list is not true, tell your AI tool in a sentence what you see and what you expected, for example: “CON-0001 meets the rules. A group on the contaminant list needs a look whatever its score.”

Notice what one peptide does not say

Find PX-0009 on your list: needs a look, 1 unique peptide. It is the protein LAB-42 asked about. Ask your AI tool:

The lab asked whether PX-0009 is in their sample. What do these files show about it, and what don't they? Don't change anything.

Before you read on: what would you tell LAB-42 this morning?

The files show one peptide, EMEYPGTFSDK, 11 amino acids long, matched in 3 spectra with a best score of 120.0. It is unique in the database searched, and it covers 2.7% of the 412 amino acids PX-0009 has. The group’s q-value is 0, which by the definition these files follow means only that no decoy group scored higher: the highest decoy, REV-PX-0031, scores 113.8. It is not a probability that this one match is right, and it says nothing about the peptide beyond its rank.

What the files do not show is the part that decides it. Whether the 3 spectra really support that sequence is not in this table: the spectra are in the search software’s results, and how they are judged is set by your core’s procedures. Whether the peptide was in the blank run before this sample, or in the sample before that, is in those runs, not in this table. Whether a protein the database searched leaves out could give the same peptide is a question these files cannot answer; ask whoever keeps your core’s databases. Your AI tool may offer wording for the lab. Nothing goes to LAB-42 until you have done those checks, and nothing you send says the protein is absent: a protein not found in one search may simply not have been seen.

Then the decision is yours. You might report PX-0009 with a caveat that it rests on one peptide, leave it out of the report and tell the lab why, or suggest a measurement aimed at that peptide. Which, and in what words, depends on what you saw in the spectra and on your core’s reporting procedure.

The same holds for groups that meet the rules. Group 610 holds two accessions the search could not tell apart; how you name them to the lab is your wording, not the list’s. PX-0013 meets the rules on exactly 2 unique peptides, and its third peptide is shared with another group; what a shared peptide is taken to support is yours to judge.

The list sorts protein groups by your core’s written rules; what is reported to a lab, reported with a caveat, or left out is the core manager’s decision under the core’s reporting procedure.

A group listed as meeting the rules has passed those numbers, and nothing more.

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 list against the checks above, not against this.

- PX-0009's score of 120.0 is higher than every decoy in the file.
The highest decoy scores 113.8.
That's mildly reassuring, but it's not a validation. It's a comparison
against just 43 decoys.

The groups, peptide and scores it talks about are made up for this course.

The same answer ended with a sentence for the lab that said PX-0009 “was identified in this search”. That is wording to decide after you have looked at the spectra, not before.

How real results differ

  • Decoys and contaminants are marked, and set aside. One search program’s documentation says of a group marked as a decoy that it “contains no protein, made up of at least 50% of the peptides of the leading protein, with a peptide derived from the reversed part of the decoy database. These should be removed for further data analysis.”, and of one marked as a contaminant: “When marked with ‘+’, this particular protein group was found to be a commonly occurring contaminant. These should be removed for further data analysis.” It defines its protein q-value as “This is the ratio of reverse to forward protein groups.” (MaxQuant documentation, Output Tables, Protein Groups, read 11 November 2026). Other programs may mark these differently and estimate q-values in other ways; read your own program’s documentation for what its columns mean.
  • A contaminant list is a list of usual suspects, not a verdict. One widely shared list describes itself as “an attempt to create a list of proteins commonly found in proteomics experiments that are present either by accident or through unavoidable contamination of protein samples” (The GPM, cRAP, read 11 November 2026). A protein on it can also be a real part of the sample, and a lab’s own protein of interest can be on it. That is why this practice core looks at contaminant groups rather than dropping them. A stand-in for the digestion enzyme, like CON-0005 here, will need a look whenever the search finds it, which in samples digested with that enzyme may be every run.
  • Single-peptide identifications are held to more in some places. In 2015 one journal’s editors described their guidelines’ “requirement that authors provide “annotated” spectra for all MS/MS protein identifications based on only a single unique peptide”, and that the journal later waived sending them with the article, “allowing deposition in an acceptable public repository in lieu of inclusion in the manuscript” (Burlingame and others, Molecular & Cellular Proteomics, 2015, read 11 November 2026). That was for papers sent to that journal, and a journal’s rules change; if a lab means to publish, check the journal’s current instructions before you report.
  • Two peptides is a rule for one purpose, not for every report. The Human Proteome Project’s guidelines say “two uniquely-mapping, non-nested peptides of nine or more amino acids should be the minimum required for such a claim”, where the claim is mass spectrometry evidence for a human protein in that project’s catalogue, and they say those guidelines “apply only to manuscripts presenting evidence that could qualify the newly-identified proteins for consideration as PE1 in neXtProt or to provide MS evidence for PE1 proteins lacking MS data, so classified based on other types of data” (Deutsch and others, Journal of Proteome Research, 2019, read 11 November 2026). PE1 is that catalogue’s level for proteins with, in the same paper’s words, “compelling mass spectrometry (MS) or non-MS protein-level evidence”. This practice core’s 2 unique peptides is its own rule for its own reports.
  • Unique means unique in the database searched. The Unique column compares a peptide with the entries in that database and nothing else. Whether a protein it leaves out could give the same peptide is a question for whoever keeps your core’s databases.
  • A short list rests on few decoys. By the definition quoted above, a protein q-value is a ratio of decoy groups to real ones, so on a short list, such as a single band from a gel, a handful of decoys decides it; read the q-values with that in mind.
  • Real tables may hold more. Check what yours holds, for example: gene names, intensities for working out amounts, peptide-level q-values, charge states, mass errors, razor peptides (shared peptides assigned to one group), leading-protein columns and one column per sample in a multi-sample search. A program built for one export needs telling what each column of yours means.
  • Score, PSMs and coverage describe the evidence in one run. The list reads them as that and nothing more; whether and how your core reports amounts is in its own procedures.
  • Your export may already be cut. A search may write its protein table only up to its own protein-level limit, so groups just over it may not be in your table at all. This practice table goes to 0.05 so near misses show.

Keep going

Small changes do not need plan mode. Say each in a sentence, then run it again:

  1. “For each group that needs a look, also list its peptides from peptides.csv, with their spectra and best score. If no peptides file is given, still run and say so.” The list then shows, beside PX-0009, the one peptide you will look at.
  2. “Does the program name any group 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 search’s files it would get them wrong.
  3. “Save a checkpoint.” Your AI tool saves a snapshot you can return to.

When you want a list for a real search, 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 search software’s export will not be shaped like the practice files: its columns have their own names, and it may mark decoys and contaminants in its own way. 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 lab’s 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.

  2. Decide on a folder of its own for your real searches, outside this course folder, for example ~/search-triage. 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 search-triage in my home folder.”

  3. Ask your AI tool for a blank file and a made-up one to try: “Make me a blank protein-groups file my spreadsheet program can open, in ~/search-triage, and a made-up one here with one group, and show the program working on it.” Look for it running the program on the made-up file and showing that group as meeting the rules or needing a look, and if it needs a look, why. Then open your own search software’s protein export in a spreadsheet and tell your AI tool the names of its columns, and how it marks decoys and contaminants, with two rows you make up in the same shape, made-up accessions and numbers, never a real row. For example: “My export has the columns Accessions, Peptide count, Unique count, Spectra, Protein score, q, Decoy flag and Contaminant flag. Here are two made-up rows in the same shape. Change the program to read files like that.” Then paste the two rows you made up. Give column names only where your core 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 accessions and results from a lab’s sample never go to it. If you made the peptides change in Keep going, your own peptide export is one more file: describe it to your AI tool the same way, its column names with two rows made up in the same shape, never real rows, and the exact line you ask for in step 5 then names both files, so save both into search-triage in step 7.

  4. Give the program your core’s own rules in place of the three practice rules, from its written reporting procedure, numbers included. For example: “Replace the three practice rules with ours, which I’ll send next. Then make up one group 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 group needs a look for the rule it was made for, with that rule’s reason.

  5. Ask your AI tool for the exact line, for example: “Give me the exact one line to run this myself on a protein-groups file inside a folder called search-triage 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/20-protein-triage/sort_proteins.py /home/dana/search-triage/protein-groups.csv --out /home/dana/search-triage | tee /home/dana/search-triage/triage-list.txt

    Read it left to right. python3 runs a Python program. Next comes the triage program, in this lesson’s folder; then the search’s protein file, in search-triage; --out and the folder after it say where the list files go. | tee and the last name keep a copy of the on-screen list in a text file there too. /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. Each run writes over the last run’s list files, so rename those first if you want to keep them. The line on this page names only the protein file. If you made the peptides change and the line you were given names only one file, ask your AI tool for the line again, naming both. 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. Save a search’s protein export into search-triage, 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 file, 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 with mkdir.

  8. Before you act on the list, compare a few of its counts with your search software’s own summary for the same search. If they differ, find out why first.

Try another case

Before the quiz, write two or three sentences for yourself. Next month a lab that studies skin cells sends a sample, and the list puts the group with the highest score under needs a look, on the contaminant list. The lab’s student says it is the protein their whole project is about and asks why your core “flagged” it. What do you check, and what do you tell them?

A good answer treats the flag as the core’s own rule doing its job, not as a verdict: a protein on the contaminant list can also be a real part of a sample, and for this lab it is expected. It checks what can tell the two apart (the blank, how the sample was handled, whether the amount fits the sample), says in the report how contaminant-list proteins were treated, and leaves the rule as written.

Key takeaways

  • A short ask, then your rules. Say what you do and which files; give your core’s rules in its own words.
  • Read the plan for how groups are counted: decoys apart, contaminants looked at, every accession shown, a reason beside every flag.
  • Check a new list against numbers you know before you trust it on a search you do not.
  • One peptide is a reason to look: at the spectra, the blank and the database. What the lab is told is yours to decide.
  • Practice data stays practice data: real search results go to the finished program, with your AI tool closed, after the data check.
KNOWLEDGE CHECK

A protein group has a q-value of 0.004, 1 unique peptide seen in 4 spectra, and is not on the contaminant list. By this practice core's rules, what does the list say, and what happens next?

KNOWLEDGE CHECK

A decoy group in the table has a q-value of 0.004, under the core's 0.01. What should the list do with it?

What’s next

The next lesson is about checking the typed inventory from a field school’s mock recovery, made with replica material, before anyone relies on it.

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