Add method and operator descriptions with presentation references

README.md

@@ -24,7 +24,7 @@ python3 deploy/huggingface-compressionbenchmark/export_results.py
 python3 deploy/huggingface-compressionbenchmark/build_ui_payload.py
 ```
 
-Publish `README.md`, `index.html`, `style.css`, `app.js`, `ranking.js`, `data.json`, `ui-data.json`, `manifest.json`, `export_results.py`, and `build_ui_payload.py` to the static Space. The manifest records the exact source-file identities and metric boundaries. The compact browser payload retains the full snapshot's measurements and SHA-256 identity.
+Publish `README.md`, `index.html`, `style.css`, `app.js`, `ranking.js`, `reference-catalog.json`, `data.json`, `ui-data.json`, `manifest.json`, `export_results.py`, and `build_ui_payload.py` to the static Space. The manifest records the exact source-file identities and metric boundaries. The compact browser payload retains the full snapshot's measurements and SHA-256 identity. The reference catalog is an independent documentation payload and does not affect leaderboard measurements.
 
 Only measurements in the authoritative current project scope are exported. Missing metrics and missing coverage are displayed explicitly. Existing results do not imply independently verified round trips or uniform hardware environments unless those checks are recorded in the source.
 
@@ -35,6 +35,7 @@ Only measurements in the authoritative current project scope are exported. Missi
 - Compression rate versus encoding/decoding cost plots
 - Dataset-level method details, snapshot provenance, and metric definitions
 - Overall composite score and average dataset Rank, with 36 valid positive one-decimal weight combinations
+- Searchable Methods and Operators documentation with presentation-note references and external source links
 
 The default family view selects the best measured compression-rate configuration independently for each dataset. Switch to **Exact configuration** to hold a configuration fixed. Runtime results stay separate.
 

app.js

@@ -20,6 +20,7 @@ const cols = [
   {key:'original_bytes',label:'Original bytes',digits:0,visible:false},
 ];
 let snapshot, records=[], methods=new Map(), datasets=new Map(), currentRows=[], activeTab='overall';
+let referenceCatalog=null,referenceCatalogError=null;
 let sort={key:'compression_rate',direction:1};
 let selectedMethod=null;
 const state = () => ({runtime:$('runtime').value,dataset:$('dataset').value,dtype:$('dtype').value,precision:$('precision').value,family:$('family').value,mode:$('row-mode').value,search:$('search').value.trim().toLowerCase(),complete:$('complete-only').checked});
@@ -91,9 +92,9 @@ function refresh() {
   if(selectedMethod)showMethod(selectedMethod,false);
 }
 function setTab(tab) {
-  activeTab=['overall','dataset','tradeoffs','methods','about'].includes(tab)?tab:'overall';
+  activeTab=['overall','dataset','tradeoffs','methods','operators','about'].includes(tab)?tab:'overall';
   for(const b of document.querySelectorAll('[data-tab]')){b.classList.toggle('active',b.dataset.tab===activeTab);if(b.dataset.tab===activeTab)b.setAttribute('aria-current','page');else b.removeAttribute('aria-current');}
-  $('results-view').hidden=['methods','about'].includes(activeTab);$('methods-view').hidden=activeTab!=='methods';$('about-view').hidden=activeTab!=='about';$('chart-view').hidden=activeTab!=='tradeoffs';
+  $('results-view').hidden=['methods','operators','about'].includes(activeTab);$('methods-view').hidden=activeTab!=='methods';$('operators-view').hidden=activeTab!=='operators';$('about-view').hidden=activeTab!=='about';$('chart-view').hidden=activeTab!=='tradeoffs';
   $('score-controls').hidden=activeTab!=='overall';
   for(const input of $('column-options').querySelectorAll('input'))input.parentElement.hidden=Boolean(cols.find(c=>c.key===input.dataset.column)?.overallOnly&&activeTab!=='overall');
   if(activeTab!=='overall'&&cols.find(c=>c.key===sort.key)?.overallOnly)sort={key:'compression_rate',direction:1};
@@ -133,6 +134,72 @@ function csv() {
   const body=currentRows.map((r,i)=>[i+1,r.method,r.runtime,scopeKey(),state().mode,state().dataset,sort.key,sort.direction===1?'ascending':'descending',r.compression_rate,r.overall_rate,r.compression_time,r.decompression_time,...weights.map(w=>w.toFixed(1)),r.normalized_compression_time,r.normalized_decompression_time,r.composite_score,r.average_rank,r.rank_coverage,r.normalization_reference_rows,r.encode_min,r.encode_max,r.decode_min,r.decode_max,'min-max over all measured rows in selected runtime/scope/row-mode before search and visibility filters','mean per-dataset composite-score fractional rank; per-dataset min-max times',r.coverage,r.totalDatasets,JSON.stringify(Object.fromEntries(r.source.map(s=>[s.dataset,s.configuration])))].map(quote).join(','));
   const url=URL.createObjectURL(new Blob(['\ufeff'+[columns.join(','),...body].join('\r\n')],{type:'text/csv;charset=utf-8'}));const a=document.createElement('a');a.href=url;a.download=`THULab-compression-${state().runtime}-${scopeKey()}-${state().dataset}.csv`;a.click();setTimeout(()=>URL.revokeObjectURL(url),1000);
 }
+function safeHttpUrl(value) {
+  try { const url=new URL(String(value));return ['http:','https:'].includes(url.protocol)?url.href:null; } catch { return null; }
+}
+function publicNote(value) {
+  const note=typeof value==='string'?value.trim():'';
+  return /(?:\/Users\/|[A-Za-z]:\\|file:\/\/|\.pptx\b)/i.test(note)?'':note;
+}
+function referenceMap() {
+  return new Map((referenceCatalog?.references||[]).map(reference=>[String(reference.id),reference]));
+}
+function resolvedReferences(ids) {
+  const byId=referenceMap();
+  return [...new Set(Array.isArray(ids)?ids.map(String):[])].map(id=>byId.get(id)).filter(Boolean);
+}
+function referenceSearchText(ids) {
+  return resolvedReferences(ids).map(reference=>`${reference.id??''} ${reference.citation??''} ${reference.kind??''}`).join(' ');
+}
+function renderReferences(ids) {
+  const references=resolvedReferences(ids);
+  if(!references.length)return '<p class="reference-empty">No external reference is listed for this entry.</p>';
+  return `<div class="documentation-references"><strong>References</strong><ul>${references.map(reference=>{const url=safeHttpUrl(reference.url),citation=escape(reference.citation||reference.id||'Reference');const meta=[reference.id,reference.source_slide?`Presentation Notes · slide ${reference.source_slide}`:'Additional official source'].filter(Boolean).map(escape).join(' · ');return `<li>${url?`<a href="${escape(url)}" target="_blank" rel="noopener noreferrer">${citation}</a>`:`<span>${citation}</span>`}${meta?`<small>${meta}</small>`:''}</li>`;}).join('')}</ul></div>`;
+}
+function familyConfigurations() {
+  const grouped=new Map();
+  for(const record of records){if(!grouped.has(record.family))grouped.set(record.family,new Set());grouped.get(record.family).add(record.configuration);}
+  return new Map([...grouped].map(([family,names])=>[family,[...names].sort((a,b)=>a.localeCompare(b))]));
+}
+function catalogMethod(family) {
+  const entries=referenceCatalog?.methods||[];
+  return entries.find(entry=>entry.family===family)||entries.find(entry=>String(entry.family).toLowerCase()===family.toLowerCase())||null;
+}
+function renderMethodDocumentation() {
+  const container=$('method-catalog'),status=$('method-doc-status');
+  if(!container||!status)return;
+  if(referenceCatalogError){status.textContent='Method documentation could not be loaded.';container.innerHTML=`<p class="documentation-error">${escape(referenceCatalogError.message)}</p>`;return;}
+  if(!referenceCatalog){status.textContent='Loading method documentation…';container.innerHTML='';return;}
+  const configurations=familyConfigurations(),query=$('method-doc-search').value.trim().toLowerCase();
+  const families=[...configurations.keys()].sort((a,b)=>a.localeCompare(b));
+  const rows=families.map(family=>{const entry=catalogMethod(family)||{},names=configurations.get(family),note=publicNote(entry.notes),search=[family,entry.display_name,entry.description,note,...names,referenceSearchText(entry.reference_ids)].join(' ').toLowerCase();return {family,entry,names,note,search};}).filter(row=>!query||row.search.includes(query));
+  const described=families.filter(family=>catalogMethod(family)?.description).length;
+  status.textContent=`${rows.length} of ${families.length} measured method families shown · ${described} descriptions available`;
+  container.innerHTML=rows.length?rows.map(({family,entry,names,note})=>{const display=entry.display_name||family;return `<article class="documentation-card"><div class="documentation-card-head"><div><h3>${escape(display)}</h3>${display!==family?`<span class="documentation-code">${escape(family)}</span>`:''}</div><span class="documentation-count">${names.length} configuration${names.length===1?'':'s'}</span></div><p class="documentation-description">${escape(entry.description||'A reference description is not available for this measured family.')}</p>${note?`<p class="documentation-note">${escape(note)}</p>`:''}${renderReferences(entry.reference_ids)}<details class="configuration-details"><summary>Published configurations (${names.length})</summary><ul>${names.map(name=>`<li>${escape(name)}</li>`).join('')}</ul></details></article>`;}).join(''):'<p class="documentation-empty">No method documentation matches this search.</p>';
+}
+function renderOperatorDocumentation() {
+  const container=$('operator-catalog'),status=$('operator-doc-status');
+  if(!container||!status)return;
+  if(referenceCatalogError){status.textContent='Operator documentation could not be loaded.';container.innerHTML=`<p class="documentation-error">${escape(referenceCatalogError.message)}</p>`;return;}
+  if(!referenceCatalog){status.textContent='Loading operator documentation…';container.innerHTML='';return;}
+  const query=$('operator-doc-search').value.trim().toLowerCase(),all=referenceCatalog.operators||[];
+  const visible=all.filter(operator=>!query||[operator.id,operator.name,operator.group,operator.description,referenceSearchText(operator.reference_ids)].join(' ').toLowerCase().includes(query));
+  const groups=new Map();
+  for(const operator of visible){const group=operator.group||'Other';if(!groups.has(group))groups.set(group,[]);groups.get(group).push(operator);}
+  status.textContent=`${visible.length} of ${all.length} operators shown`;
+  container.innerHTML=visible.length?[...groups].sort((a,b)=>a[0].localeCompare(b[0])).map(([group,operators])=>`<section class="operator-group"><h3>${escape(group)}</h3><div class="documentation-grid">${operators.sort((a,b)=>String(a.name).localeCompare(String(b.name))).map(operator=>`<article class="documentation-card operator-card"><div class="documentation-card-head"><div><h4>${escape(operator.name||operator.id)}</h4>${operator.id&&operator.id!==operator.name?`<span class="documentation-code">${escape(operator.id)}</span>`:''}</div></div><p class="documentation-description">${escape(operator.description||'Description not available.')}</p>${renderReferences(operator.reference_ids)}</article>`).join('')}</div></section>`).join(''):'<p class="documentation-empty">No operator documentation matches this search.</p>';
+}
+function renderDocumentationViews() { renderMethodDocumentation();renderOperatorDocumentation(); }
+async function loadReferenceCatalog() {
+  try {
+    const response=await fetch('./reference-catalog.json?v=20261008-docs-v1',{cache:'no-cache'});
+    if(!response.ok)throw new Error(`Reference catalog request returned ${response.status}.`);
+    const catalog=await response.json();
+    if(!catalog||!Array.isArray(catalog.methods)||!Array.isArray(catalog.operators)||!Array.isArray(catalog.references))throw new Error('Reference catalog has an invalid schema.');
+    referenceCatalog=catalog;
+  } catch(error) { referenceCatalogError=error instanceof Error?error:new Error('Reference catalog is unavailable.'); }
+  if(snapshot)renderDocumentationViews();
+}
 function renderAbout() {
   const b=snapshot.benchmark||{},s=snapshot.source||{},c=snapshot.coverage||{};
   const notes=[b.scope_note,b.aggregation_note,b.selection_note,...(b.notes||[]),...(b.measurement_boundaries||[])].filter(Boolean);
@@ -142,8 +209,6 @@ function renderAbout() {
   const exclusions=c.exclusions||c.excluded_datasets||snapshot.exclusions||[];
   const info={ 'Snapshot exported':snapshot.exported_at||s.exported_at||'Not reported','Dataset scope generated':s.generated_at||'Not reported', 'Source checkout':s.git_commit||'Not reported','Source files':`${s.source_files?.length??0} metadata inputs and ${s.result_csv_files_used?.length??0} result CSVs (hashes in manifest)`,'Result entries across scopes':`${records.length} (scope slices can reuse a measurement)`,'Worktree source state':s.worktree_dirty_inputs?.length?'Includes current local changes; input file hashes identify the published snapshot.':'See manifest for source file hashes.','Runtime environment':b.hardware||'Hardware details are not recorded in this exported result snapshot.','Lossless evidence':b.roundtrip_evidence||'Lossless-design method filter from the source project; per-run round-trip verification is not recorded here.'};
   $('provenance').innerHTML=`<table class="provenance-table"><tbody>${Object.entries(info).map(([k,v])=>`<tr><th>${escape(k)}</th><td class="source-code">${escape(v)}</td></tr>`).join('')}</tbody></table>${exclusions.length?`<h3>Excluded or unavailable results</h3><p class="source-code">${escape(typeof exclusions==='string'?exclusions:JSON.stringify(exclusions))}</p>`:''}`;
-  const groups=new Map();for(const r of records){if(!groups.has(r.family))groups.set(r.family,[]);groups.get(r.family).push(r.configuration);}
-  $('method-catalog').innerHTML=`<div class="method-groups">${[...groups].sort((a,b)=>a[0].localeCompare(b[0])).map(([family,names])=>`<section class="method-group"><h3>${escape(family)}</h3><ul>${[...new Set(names)].sort().map(n=>`<li>${escape(n)}</li>`).join('')}</ul></section>`).join('')}</div>`;
 }
 function init() {
   if(snapshot.compact_records){const t=snapshot.record_tables;snapshot.dataset_results=snapshot.compact_records.map(r=>({dataset:t.datasets[r[0]],scope:t.scopes[r[1]],runtime:t.runtimes[r[2]],family:t.families[r[3]],method:t.configurations[r[4]],algorithm_variant:t.configurations[r[4]],compression_rate:r[5],compression_time_ns_per_point:r[6],decompression_time_ns_per_point:r[7],original_size_bytes:r[8],compressed_size_bytes:r[9]}));delete snapshot.compact_records;}
@@ -164,7 +229,8 @@ function init() {
   for(const id of ['runtime','dtype','precision','dataset','family','row-mode','complete-only'])$(id).addEventListener('change',refresh);$('search').addEventListener('input',refresh);$('chart-metric').addEventListener('change',renderChart);$('download').addEventListener('click',csv);
   $('reset').addEventListener('click',()=>{$('runtime').value=runtimes.includes('cpp')?'cpp':runtimes[0];$('dtype').value='overall';$('precision').value='all';$('dataset').value='all';$('row-mode').value='family';$('search').value='';$('family').value='all';$('weights').value='4,3,3';$('complete-only').checked=false;selectedMethod=null;$('method-detail').hidden=true;sort={key:'compression_rate',direction:1};setTab(activeTab);});
   for(const tab of document.querySelectorAll('[data-tab]'))tab.addEventListener('click',()=>{history.replaceState(null,'',`#${tab.dataset.tab}`);setTab(tab.dataset.tab);});
-  renderAbout();setTab(location.hash.slice(1)||'overall');
+  $('method-doc-search').addEventListener('input',renderMethodDocumentation);$('operator-doc-search').addEventListener('input',renderOperatorDocumentation);
+  renderAbout();renderDocumentationViews();setTab(location.hash.slice(1)||'overall');
   document.documentElement.dataset.ready='true';
 }
 function setupTheme() {
@@ -175,5 +241,6 @@ function setupTheme() {
   $('theme').addEventListener('click',()=>{const next=document.documentElement.dataset.theme==='dark'?'light':'dark';document.documentElement.dataset.theme=next;$('theme').textContent=next==='dark'?'Light mode':'Dark mode';try{localStorage.setItem('thulab-theme',next);}catch{}});
 }
 setupTheme();
+void loadReferenceCatalog();
 try { const response=await fetch('./ui-data.json?v=20261008-rank-v1',{cache:'no-cache'});if(!response.ok)throw new Error(`Snapshot request returned ${response.status}`);snapshot=await response.json();init(); }
 catch(e){$('load-error').hidden=false;$('load-error').textContent=`The result snapshot could not be loaded. Please reload the page or download the JSON from the repository. ${e.message}`;$('snapshot').textContent='Snapshot unavailable';$('leaderboard').querySelector('tbody').innerHTML='<tr><td class="empty-cell">Results unavailable.</td></tr>';}

index.html

@@ -6,8 +6,8 @@
   <meta name="description" content="THULab time-series compression benchmark: measured compression rates, encoding and decoding costs, and dataset coverage.">
   <meta name="color-scheme" content="light dark">
   <title>THULab | Time Series Compression Benchmark</title>
-  <link rel="stylesheet" href="style.css?v=20261008-rank-v1">
-  <script src="app.js?v=20261008-ui-v2" type="module"></script>
+  <link rel="stylesheet" href="style.css?v=20261008-docs-v1">
+  <script src="app.js?v=20261008-docs-v1" type="module"></script>
 </head>
 <body>
   <a class="skip-link" href="#content">Skip to results</a>
@@ -33,6 +33,7 @@
       <button id="tab-dataset" class="tab" data-tab="dataset">By dataset</button>
       <button id="tab-tradeoffs" class="tab" data-tab="tradeoffs">Trade-offs</button>
       <button id="tab-methods" class="tab" data-tab="methods">Methods</button>
+      <button id="tab-operators" class="tab" data-tab="operators">Operators</button>
       <button id="tab-about" class="tab" data-tab="about">About</button>
     </nav>
     <div id="load-error" class="error-message" role="alert" hidden></div>
@@ -70,7 +71,24 @@
       <div class="table-footer"><span id="row-count" aria-live="polite"></span><span>Select a method to inspect dataset-level results.</span></div>
       <section id="method-detail" class="method-detail" hidden tabindex="-1" aria-labelledby="detail-title"></section>
     </section>
-    <section id="methods-view" class="text-view" hidden><h2>Method configurations</h2><p class="muted">Names and parameters are retained from the project's result files. Availability can differ by runtime and data type.</p><div id="method-catalog"></div></section>
+    <section id="methods-view" class="text-view documentation-view" hidden>
+      <div class="documentation-head">
+        <div><h2>Methods</h2><p class="muted">Descriptions and references for the method families measured in this benchmark. Expand a family to inspect its published configurations.</p></div>
+        <label class="documentation-search">Search methods<input id="method-doc-search" type="search" placeholder="Family, description, configuration, or reference" autocomplete="off"></label>
+      </div>
+      <p class="reference-source">References follow the presentation Notes (slides 2–3), with official sources for additional variants. External links open in a new tab.</p>
+      <p id="method-doc-status" class="documentation-status" aria-live="polite">Loading method documentation…</p>
+      <div id="method-catalog" class="documentation-grid"></div>
+    </section>
+    <section id="operators-view" class="text-view documentation-view" hidden>
+      <div class="documentation-head">
+        <div><h2>Operators</h2><p class="muted">Reusable transforms and coding primitives that appear across time-series compression methods.</p></div>
+        <label class="documentation-search">Search operators<input id="operator-doc-search" type="search" placeholder="Name, group, description, or reference" autocomplete="off"></label>
+      </div>
+      <p class="reference-source">References from the presentation Notes (slides 2–3). External links open in a new tab.</p>
+      <p id="operator-doc-status" class="documentation-status" aria-live="polite">Loading operator documentation…</p>
+      <div id="operator-catalog" class="operator-groups"></div>
+    </section>
     <section id="about-view" class="text-view" hidden>
       <h2>About this benchmark</h2>
       <p>This Space publishes a snapshot of the existing <a href="https://github.com/xjz17/web_compression" target="_blank" rel="noopener">web_compression</a> project results. The layout follows the grouped leaderboard approach of <a href="https://huggingface.co/spaces/Salesforce/GIFT-Eval" target="_blank" rel="noopener">GIFT-Eval</a>.</p>

style.css

@@ -9,3 +9,4 @@
 .intro{padding:16px 0 10px}.eyebrow{display:none}h1{font-size:clamp(24px,2.8vw,30px);margin-bottom:8px}.intro-text{font-size:13px}.snapshot{font-size:11px;margin-top:6px}.summary-strip{padding:10px 0}.summary-strip strong{font-size:20px}.filters{padding:12px;gap:8px}.toolbar{margin-top:12px;margin-bottom:4px}
 .score-controls{display:flex;align-items:start;gap:20px;padding:12px 14px;margin:6px 0 12px;border:1px solid var(--line);border-radius:var(--radius);background:var(--soft)}.score-controls label{min-width:320px}.score-controls p{font-size:11px;line-height:1.7;margin:0;max-width:90ch}.score-controls select{height:35px}@media(max-width:768px){.score-controls{flex-direction:column;gap:10px}.score-controls label{min-width:0;width:100%}}
 .audit-badge{display:block;color:var(--muted);font-size:10px;margin-top:4px}.audit-notice{font-size:12px;padding:10px 14px;margin:8px 0;border-left:3px solid var(--accent);background:var(--accent-soft);color:var(--text)}
+.documentation-view{max-width:1180px}.documentation-head{display:flex;justify-content:space-between;align-items:end;gap:28px;margin-bottom:10px}.documentation-head>div{min-width:0}.documentation-search{width:min(390px,42%);flex:0 0 auto}.reference-source{margin:8px 0 4px;color:var(--muted);font-size:12px}.documentation-status{margin:14px 0;color:var(--muted);font-size:12px}.documentation-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:14px}.documentation-card{min-width:0;padding:18px;background:var(--surface);border:1px solid var(--line);border-radius:var(--radius)}.documentation-card h3,.documentation-card h4{margin:0;color:var(--text);line-height:1.35}.documentation-card h4{font-size:16px}.documentation-card-head{display:flex;justify-content:space-between;align-items:start;gap:16px}.documentation-code{display:block;margin-top:3px;color:var(--muted);font:11px "SFMono-Regular",Consolas,monospace;overflow-wrap:anywhere}.documentation-count{flex:0 0 auto;padding:3px 7px;border-radius:4px;background:var(--soft);color:var(--muted);font-size:10px}.documentation-description{margin:12px 0;color:var(--text);font-size:13px;line-height:1.65}.documentation-note{margin:10px 0;padding:9px 11px;border-left:2px solid var(--line);color:var(--muted);font-size:12px}.documentation-references{margin-top:12px;font-size:12px}.documentation-references>strong{font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted)}.documentation-references ul{list-style:none;padding:0;margin:6px 0 0}.documentation-references li{padding:5px 0;border-top:1px solid var(--line);overflow-wrap:anywhere}.documentation-references small{display:block;margin-top:1px;color:var(--muted);font-size:10px}.reference-empty{margin:12px 0 0;color:var(--muted);font-size:11px}.configuration-details{margin-top:13px;border-top:1px solid var(--line);padding-top:10px}.configuration-details summary{cursor:pointer;color:var(--accent);font-size:12px;font-weight:600}.configuration-details ul{display:flex;flex-wrap:wrap;gap:6px;list-style:none;padding:10px 0 0;margin:0}.configuration-details li{max-width:100%;padding:4px 7px;border-radius:4px;background:var(--soft);font:10px "SFMono-Regular",Consolas,monospace;overflow-wrap:anywhere}.operator-group{margin-top:24px}.operator-group>h3{margin:0 0 10px;padding-bottom:8px;border-bottom:1px solid var(--line)}.operator-card{padding:16px}.documentation-error,.documentation-empty{grid-column:1/-1;margin:0;padding:22px;border:1px solid var(--line);border-radius:var(--radius);color:var(--muted);background:var(--surface)}.documentation-error{border-left:3px solid #b34938;color:var(--text)}@media(max-width:768px){.documentation-head{align-items:stretch;flex-direction:column;gap:14px}.documentation-search{width:100%}.documentation-grid{grid-template-columns:1fr}.documentation-card{padding:15px}.documentation-card-head{gap:10px}}