total_protein_count means different things in peptinfo and the functional endpoints

[bmesuere]

🤖 peptinfo and the four functional endpoints (pept2ec, pept2go, pept2interpro, pept2funct) both return a field called total_protein_count, but they compute two different numbers.

peptinfo returns the number of matched proteins:

// api/src/controllers/api/peptinfo.rs
let total_protein_count = item.proteins.len();
// let total_protein_count = *fa.counts.get("all").unwrap_or(&0);

The other four return fa.counts["all"], which calculate_fa defines as the number of distinct proteins carrying at least one EC/GO/IPR annotation — not the number of matches:

// api/src/controllers/api/pept2funct.rs (same in pept2ec, pept2go, pept2interpro)
let total_protein_count = *fa.counts.get("all").unwrap_or(&0);

Live, for MPILGLK:

endpoint	total_protein_count
pept2funct	509
peptinfo	573
pept2prot (number of entries returned)	573

peptinfo was changed to proteins.len() in 1605311 ("Fixed peptinfo total_protein_count was sometimes zero") because counts["all"] drops to 0 when none of the matched proteins are annotated. That fix was never propagated to the other four endpoints, which still have both that zero case and the undercount.

Assuming proteins.len() is the intended meaning everywhere, the fix is to apply the same change to pept2ec, pept2go, pept2interpro and pept2funct (and drop the commented-out line in peptinfo). If instead the annotated-protein count is wanted for the functional endpoints, it should get a distinct field name, since callers currently cannot tell the two apart.

Worth deciding before the API docs describe the field — the docs currently give it peptinfo's definition on all five pages (unipept/unipept#TBD).

[bmesuere]

On second thought, maybe the current behaviour is what is expected.

[bmesuere]

🤖 Reopening, because the "count the proteins that had such an annotation" reading does not survive a check against the live API.

counts["all"] counts proteins carrying any functional annotation, not proteins carrying the type the endpoint reports. All four functional endpoints therefore return the same figure for a given peptide:

MPILGLK   pept2ec 509   pept2go 509   pept2interpro 509   pept2funct 509
          peptinfo 573   (pept2prot returns 573 entries)

If it were per-type, EC, GO and InterPro coverage would have to be identical for every peptide. So pept2go's 509 includes proteins that carry only an EC-number and no GO term at all.

That leaves the field answering neither useful question. It is not the number of matched proteins (573), and it is not the number of proteins carrying the annotation type you asked for. It sits in between, and a caller cannot derive either number from it.

calculate_fa already computes the per-type counts and simply never returns them:

counts.insert("all".to_string(), proteins_with_annotations.len());
counts.insert("EC".to_string(), proteins_with_ec.len());
counts.insert("GO".to_string(), proteins_with_go.len());
counts.insert("IPR".to_string(), proteins_with_ipr.len());

So there are two coherent options:

1. Report the matched protein count, item.proteins.len(), matching peptinfo and the number of entries pept2prot returns for the same peptide. One consistent meaning across every endpoint, and it also removes the zero case that 1605311 fixed for peptinfo.
2. Report the per-type count, counts["EC"] for pept2ec and so on, so the field means what the closing comment assumed.

Option 1 looks right: it makes total_protein_count mean one thing everywhere, and the denominator a caller usually wants next to protein_count on an individual term is the number of proteins that were searched, not the annotated subset. Option 2 is also defensible but keeps a different meaning per endpoint and still leaves peptinfo the odd one out.

Either way it is a response-value change for existing callers. Flagging it here rather than picking one.

The docs side (unipept/unipept#1873) describes today's behaviour, including the any-annotation caveat, so it stays correct until this is decided. It gets simpler once it is.