Order heatmap columns by how widely each vocabulary is shared

_fleet/mechs_template.md

@@ -100,11 +100,11 @@ Alongside record browsing, the Mechs publish complementary ways to explore their
 
 ## Shared vocabulary
 
-The Mechs are joinable because they ground records in the same public ontologies. The table counts identifier occurrences per vocabulary in each Mech's record corpus; darker cells mean more. Click a Mech name to open it, a cell to list the records behind it, or a column heading to filter the graph to that vocabulary.
+The Mechs are joinable because they ground records in the same public ontologies. The table counts identifier occurrences per vocabulary in each Mech's record corpus; darker cells mean more. Columns run from the most widely shared vocabulary to the least, so the left edge is the fleet's common ground and the right edge is what a single Mech needs alone. Click a Mech name to open it, a cell to list the records behind it, or a column heading to filter the graph to that vocabulary.
 
 <div class="fleet-heat-wrap"><table class="fleet-heat" id="fleet-heat" aria-label="Ontology identifier occurrences per Mech"></table></div>
 <div class="fleet-cell-panel" id="fleet-cell-panel" hidden></div>
-<p class="fleet-heat-note">This earlier September 2026 vocabulary census was not recomputed with the September 15 site refresh and covers nine Mechs; TaxonMech is a fleet member whose vocabulary census has not yet been measured. Counts are prefix occurrences in the canonical record directories (merged recipes for CultureMech, communities for CommunityMech, habitat records for HabitatMech) as of September 2026. ChEBI binds the chemistry arm (media, ingredients, antibiotics, proteins); NCBITaxon and ENVO bind the organism arm (habitat, community, traits); GO and METPO bridge phenotype, structure and protein.</p>
+<p class="fleet-heat-note">This earlier September 2026 vocabulary census was not recomputed with the September 15 site refresh and covers nine Mechs; TaxonMech is a fleet member whose vocabulary census has not yet been measured. Counts are prefix occurrences in the canonical record directories (merged recipes for CultureMech, communities for CommunityMech, habitat records for HabitatMech) as of September 2026. Columns are ordered by how many Mechs ground anything in each vocabulary, then by the total records citing it across the fleet; PMID and DOI sit at the right because every Mech cites literature. ChEBI binds the chemistry arm (media, ingredients, antibiotics, proteins); NCBITaxon and ENVO bind the organism arm (habitat, community, traits); GO and METPO bridge phenotype, structure and protein.</p>
 
 ## How the Mechs reference each other
 

scripts/fleet/build_data.py

@@ -8,10 +8,12 @@
 import os
 REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 DATA = os.path.join(REPO, "_fleet", "data")
-import json, os
+import json, os, sys
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from roots import CITATION, ORDER
+
 S=DATA
 sub=json.load(open(f"{S}/subsets_summary.json")); cen=json.load(open(f"{S}/prefix_census.json"))
-ORDER=["HabitatMech","CommunityMech","TraitMech","CellStructureMech","ProteinTraitsMech","NaturalProductMech","AntibioticMech","MediaIngredientMech","CultureMech"]
 VOC=["CHEBI","NCBITaxon","GO","ENVO","METPO","ARO","UniProt","InterPro","Pfam","RHEA","PDB","PATO","UBERON","FOODON","BTO","GTDB","KEGG","CAS","MIBiG","NPAtlas","PMID","DOI"]
 edges=[]
 for k,v in sub["edges"].items():
@@ -20,6 +22,20 @@
     edges.append({"a":a,"b":b,"n":v["n"],"by":v["by"],"ex":v["ex"]})
 heat={m:{v:cen[m]["prefixes"].get(v,0) for v in VOC} for m in ORDER}
 cells={k.replace("|","--"):n for k,n in sub["cells"].items()}
-json.dump({"order":ORDER,"voc":VOC,"heat":heat,"cells":cells,"vocab_edges":edges},open(f"{S}/fleet_data.json","w"),separators=(",",":"),ensure_ascii=False)
+
+# Heatmap columns run left to right from the most widely shared vocabulary to
+# the least: first by how many Mechs ground anything in it, then, for the many
+# ties at nine and at one, by the total records citing it across the fleet.
+# Name last so the order is stable when a vocabulary appears in no records.
+def reach(v): return sum(1 for m in ORDER if heat[m][v])
+def records(v): return sum(cells.get(f"{m}--{v}",0) for m in ORDER)
+# CITATION comes from roots.py, the same list build_subsets.py uses to decide
+# which prefixes get no record lists. Those two have to agree: a citation
+# prefix would sort to the far left on Mech count with nothing to break the
+# tie, which is what the pin exists to prevent.
+VOC_ORDER=sorted((v for v in VOC if v not in CITATION),key=lambda v:(-reach(v),-records(v),v))+[v for v in CITATION if v in VOC]
+for v in VOC_ORDER: print(f"  {v:<10} {reach(v)} mechs {records(v):>9,} records")
+
+json.dump({"order":ORDER,"voc":VOC_ORDER,"heat":heat,"cells":cells,"vocab_edges":edges},open(f"{S}/fleet_data.json","w"),separators=(",",":"),ensure_ascii=False)
 print(len(edges),"edges;",os.path.getsize(f"{S}/fleet_data.json"),"bytes")
 for e in sorted(edges,key=lambda e:-e["n"])[:6]: print(e["a"],e["b"],e["n"],e["by"],[x["label"] for x in e["ex"]])

scripts/fleet/build_subsets.py

@@ -14,7 +14,7 @@
 import re
 import urllib.parse
 
-from roots import ORDER, mech_root, record_paths
+from roots import CITATION, ORDER, mech_root, record_paths
 
 OUT=os.path.join(REPO,"assets","fleet")
 GH="https://github.com/CultureBotAI/"; SITE="https://culturebotai.github.io/"
@@ -169,7 +169,7 @@ def scan(m, keep=None, cap_cell=300):
     print("edge",a,b,len(shared),os.path.getsize(f"{OUT}/edges/{fn}")//1024,"KB")
 for m in ORDER:
     for p,(n,refs) in idx[m]["cells"].items():
-        if p in ("DOI","PMID"): continue
+        if p in CITATION: continue
         fn=f"{m}--{p}.json"
         json.dump({"mech":m,"prefix":p,"base":MECHS[m]["base"],"total":n,"records":refs},open(f"{OUT}/cells/{fn}","w"),separators=(",",":"),ensure_ascii=False)
         summary["cells"][f"{m}|{p}"]=n

scripts/fleet/roots.py

@@ -38,6 +38,13 @@
 
 ORDER = list(RECORD_GLOBS)
 
+# Prefixes that identify a piece of literature rather than a concept. Every
+# Mech cites papers, so counting them alongside the ontologies would say only
+# that, which is why build_subsets.py writes no record lists for them and
+# build_data.py keeps them out of the heatmap's ordering. Declared once here
+# because those two decisions have to agree (CultureBotAI.github.io#61).
+CITATION = ["PMID", "DOI"]
+
 
 def mech_root(name: str) -> str:
     """The checkout for one Mech, verified to exist."""