eventscore-explorer 0.1.0__py3-none-any.whl

eventscore_explorer/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

eventscore_explorer/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

eventscore_explorer/cli.py

@@ -0,0 +1,54 @@
+import argparse
+import json
+from dataclasses import asdict
+from pathlib import Path
+from .core import load_csv, evaluate
+
+def report(truth,predictions,tolerances):
+    payload=json.dumps({'truth':[asdict(x) for x in truth], 'predictions':[asdict(x) for x in predictions],
+                        'results':[evaluate(truth,predictions,x) for x in tolerances]},ensure_ascii=True).replace('<','\\u003c')
+    return TEMPLATE.replace('__DATA__',payload)
+
+def main(argv=None):
+    p=argparse.ArgumentParser(description='Explain one-to-one event matching; CSV times in seconds.')
+    p.add_argument('truth'); p.add_argument('predictions')
+    p.add_argument('--tolerances',default='0,0.5,1,2',help='Comma-separated nonnegative endpoint tolerances (seconds)')
+    p.add_argument('--output',default='eventscore.html'); p.add_argument('--json',dest='json_output')
+    args=p.parse_args(argv)
+    try:
+        truth,predictions=load_csv(args.truth),load_csv(args.predictions)
+        tolerances=sorted(set(float(x) for x in args.tolerances.split(',')))
+        outputs=[Path(args.output)]+([Path(args.json_output)] if args.json_output else [])
+        inputs={Path(args.truth).resolve(),Path(args.predictions).resolve()}
+        if len({x.resolve() for x in outputs}) != len(outputs) or any(x.resolve() in inputs or x.exists() for x in outputs):
+            raise ValueError('Outputs must be distinct new files, separate from inputs')
+        html=report(truth,predictions,tolerances)
+        for x in outputs: x.parent.mkdir(parents=True,exist_ok=True)
+        Path(args.output).write_text(html,encoding='utf-8')
+        if args.json_output:
+            Path(args.json_output).write_text(json.dumps([evaluate(truth,predictions,x) for x in tolerances],indent=2),encoding='utf-8')
+        print(f'Report: {args.output}')
+        return 0
+    except (ValueError,OSError,KeyError) as e:
+        p.exit(2,f'Error: {e}\n')
+
+TEMPLATE=r'''<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>EventScore Explorer</title>
+<style>body{font:16px system-ui;background:#f5f7fb;color:#18273b;margin:0}main{max-width:1100px;margin:auto;padding:40px 24px}h1{font-size:32px;margin:8px 0}header p{max-width:780px;color:#536175}section{background:white;border:1px solid #dce3ed;border-radius:12px;padding:24px;margin:20px 0}select{font:inherit;padding:8px}#metrics{display:flex;flex-wrap:wrap;gap:28px;margin-top:24px}.metric b{display:block;font-size:30px}small,.muted{color:#536175}table{border-collapse:collapse;width:100%}td,th{text-align:left;padding:12px;border-bottom:1px solid #e1e7ef}svg{width:100%;min-width:650px}button{font:inherit;padding:9px 16px;cursor:pointer}.scroll{overflow:auto}.tag{font-size:12px;letter-spacing:2px;color:#285aaa}li{margin:8px 0}</style>
+<main><header><div class="tag">TIME SERIES · EVALUATION LAB</div><h1>EventScore Explorer</h1><p>See which events matched, what was missed, and how an endpoint tolerance changes the result. Synthetic demo or your own CSV — all processing for this report is local.</p></header>
+<section><label for="tolerance">Endpoint tolerance (seconds) </label><select id="tolerance"></select><div id="metrics"></div><p class="muted">One-to-one maximum-cardinality matching. Labels and recordings must agree. At zero tolerance, touching endpoints do not overlap. Signed onset offset = prediction start − truth start; negative means early.</p></section>
+<section><h2>Event timeline</h2><p>Blue: ground truth · Green: matched prediction · Orange: unmatched prediction. Each event has its own row; times are relative to the recording.</p><div class="scroll" id="timeline"></div></section>
+<section><h2>Why these events matched</h2><div class="scroll"><table><thead><tr><th>Truth</th><th>Prediction</th><th>Rule</th><th>Overlap (s)</th><th>Onset offset (s)</th></tr></thead><tbody id="pairs"></tbody></table></div><h3>Unmatched events</h3><ul id="unmatched"></ul><p id="ambiguity"></p><button id="download">Download evaluation JSON</button></section>
+<footer>Prototype 0.1 · No true-negative count, specificity, or false alarms/hour is inferred without recording duration. Matching maximizes count, not temporal quality. This is an explicit evaluation policy, not a clinical standard.</footer></main>
+<script type="application/json" id="data">__DATA__</script><script>
+const data=JSON.parse(document.getElementById('data').textContent), select=document.getElementById('tolerance');
+data.results.forEach((r,i)=>{const o=document.createElement('option');o.value=i;o.textContent=r.tolerance_seconds;select.append(o)});
+function cell(row,value){const td=document.createElement('td');td.textContent=value;row.append(td)}
+function render(){const r=data.results[Number(select.value)],m=document.getElementById('metrics');m.replaceChildren();
+for(const [name,value] of [['Matched',r.tp],['False alarms',r.fp],['Missed',r.fn],['Precision',r.precision],['Recall',r.recall],['F1',r.f1]]){const box=document.createElement('div');box.className='metric';const b=document.createElement('b');b.textContent=value===null?'N/A':(name==='Precision'||name==='Recall'||name==='F1'?value.toFixed(3):value);box.append(b,document.createTextNode(name));m.append(box)}
+const pairs=document.getElementById('pairs');pairs.replaceChildren();r.matches.forEach(p=>{const tr=document.createElement('tr');[p.truth,p.prediction,p.reason,p.overlap_seconds.toFixed(3),p.onset_offset_seconds.toFixed(3)].forEach(x=>cell(tr,x));pairs.append(tr)});
+const ul=document.getElementById('unmatched');ul.replaceChildren();for(const [items,kind] of [[r.missed,'Missed'],[r.false_alarms,'False alarm']])for(const x of items){const li=document.createElement('li');li.textContent=kind+' · '+x.id+' — '+x.reason;ul.append(li)}if(!ul.children.length){const li=document.createElement('li');li.textContent='No unmatched events';ul.append(li)}
+document.getElementById('ambiguity').textContent=r.ambiguous_truth.length?'Multiple eligible predictions: '+r.ambiguous_truth.join(', ')+'. Pair identities and onset offsets can depend on deterministic tie-breaking.':'No truth event has multiple eligible predictions.';
+const host=document.getElementById('timeline');host.replaceChildren(); const ns='http://www.w3.org/2000/svg'; const records=[...new Set([...data.truth,...data.predictions].map(x=>x.recording))];
+for(const record of records){const title=document.createElement('h3');title.textContent=record;host.append(title);const events=[...data.truth.filter(x=>x.recording===record).map(x=>({...x,kind:'truth'})),...data.predictions.filter(x=>x.recording===record).map(x=>({...x,kind:'prediction'}))]; const end=Math.max(1,...events.map(e=>e.end));const svg=document.createElementNS(ns,'svg');svg.setAttribute('viewBox',`0 0 1000 ${events.length*34+45}`);svg.setAttribute('role','img');svg.setAttribute('aria-label','Event intervals for '+record+' in seconds');function text(x,y,s){const n=document.createElementNS(ns,'text');n.setAttribute('x',x);n.setAttribute('y',y);n.setAttribute('font-size','13');n.textContent=s;svg.append(n)}text(260,20,'0 s');text(900,20,end.toFixed(2)+' s');events.forEach((e,i)=>{const y=35+i*34;text(0,y+17,e.kind+' '+e.id+' ['+e.label+']');const rect=document.createElementNS(ns,'rect');rect.setAttribute('x',260+e.start/end*680);rect.setAttribute('y',y);rect.setAttribute('width',Math.max(2,(e.end-e.start)/end*680));rect.setAttribute('height',22);rect.setAttribute('rx',3);rect.setAttribute('fill',e.kind==='truth'?'#386bc0':r.matches.some(p=>p.prediction===e.id)?'#168579':'#c5682a');const tip=document.createElementNS(ns,'title');tip.textContent=e.start+'–'+e.end+' seconds';rect.append(tip);svg.append(rect)});host.append(svg)} }
+select.addEventListener('change',render);document.getElementById('download').onclick=()=>{const url=URL.createObjectURL(new Blob([JSON.stringify(data.results[Number(select.value)],null,2)],{type:'application/json'}));const a=document.createElement('a');a.href=url;a.download='eventscore-evaluation.json';a.click();setTimeout(()=>URL.revokeObjectURL(url),1000)};render();
+</script></html>'''

eventscore_explorer/core.py

@@ -0,0 +1,94 @@
+"""Explicit, deterministic maximum-cardinality interval matching (not clinical scoring)."""
+import csv
+import math
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class Event:
+    id: str
+    start: float
+    end: float
+    label: str = 'event'
+    recording: str = 'default'
+
+    def __post_init__(self):
+        if not self.id or not self.label or not self.recording:
+            raise ValueError('id, label and recording must not be empty')
+        if not math.isfinite(self.start) or not math.isfinite(self.end) or self.start < 0 or self.end <= self.start:
+            raise ValueError(f'{self.id}: require finite 0 <= start < end (seconds)')
+
+def load_csv(path):
+    with open(path, newline='', encoding='utf-8-sig') as f:
+        reader = csv.DictReader(f)
+        if not {'id', 'start', 'end'} <= set(reader.fieldnames or []):
+            raise ValueError('CSV requires id,start,end; optional label,recording')
+        return validate([Event(r['id'], float(r['start']), float(r['end']), r.get('label', 'event'), r.get('recording', 'default')) for r in reader])
+
+def validate(events):
+    events = list(events)
+    if len({e.id for e in events}) != len(events):
+        raise ValueError('Event IDs must be unique within each input')
+    return events
+
+def evaluate(truth, predictions, tolerance=0.0):
+    """Overlap of half-open intervals OR positive tolerance covering endpoint gap.
+
+    One prediction matches at most one truth. Maximum-cardinality bipartite
+    matching, deterministic sorted traversal; not a minimum-delay assignment.
+    Tolerance never crosses recording or label boundaries.
+    """
+    if not math.isfinite(tolerance) or tolerance < 0:
+        raise ValueError('tolerance must be finite and nonnegative')
+    truth = sorted(validate(truth), key=lambda e: (e.recording,e.label,e.start,e.end,e.id))
+    predictions = sorted(validate(predictions), key=lambda e: (e.recording,e.label,e.start,e.end,e.id))
+    if len(truth) > 2000 or len(predictions) > 2000:
+        raise ValueError('Prototype supports at most 2000 events per input')
+    def eligible(t,p):
+        if (t.recording,t.label) != (p.recording,p.label):
+            return False
+        overlap = min(t.end,p.end)-max(t.start,p.start)
+        gap = max(t.start-p.end,p.start-t.end,0)
+        return overlap > 0 or (tolerance > 0 and gap <= tolerance)
+    edges = [[j for j,p in enumerate(predictions) if eligible(t,p)] for t in truth]
+    # Iterative augmenting paths avoid recursion depth failures on long graphs.
+    owner = {}
+    for start in range(len(truth)):
+        queue = [start]; seen_t = {start}; parent_p = {}; free = None
+        for i in queue:
+            for j in edges[i]:
+                if j in parent_p:
+                    continue
+                parent_p[j] = i
+                if j not in owner:
+                    free = j
+                    break
+                nxt = owner[j]
+                if nxt not in seen_t:
+                    seen_t.add(nxt); queue.append(nxt)
+            if free is not None:
+                break
+        if free is not None:
+            inverse = {i:j for j,i in owner.items()}
+            while True:
+                i = parent_p[free]
+                old = inverse.get(i)
+                owner[free] = i
+                if old is None:
+                    break
+                free = old
+    pairs=[]
+    for j,i in sorted(owner.items(),key=lambda x:x[1]):
+        t,p = truth[i],predictions[j]
+        overlap = max(0,min(t.end,p.end)-max(t.start,p.start))
+        pairs.append({'truth':t.id,'prediction':p.id,'reason':'overlap' if overlap else 'within tolerance',
+                      'overlap_seconds':overlap,'gap_seconds':max(t.start-p.end,p.start-t.end,0),
+                      'onset_offset_seconds':p.start-t.start})
+    tp=len(pairs); fp=len(predictions)-tp; fn=len(truth)-tp
+    return {'tolerance_seconds':tolerance,'tp':tp,'fp':fp,'fn':fn,
+            'precision':tp/len(predictions) if predictions else None,
+            'recall':tp/len(truth) if truth else None,
+            'f1':2*tp/(len(truth)+len(predictions)) if truth or predictions else None,
+            'matches':pairs,
+            'missed':[{'id':t.id,'reason':'candidate assigned to another event' if edges[i] else 'no eligible prediction'} for i,t in enumerate(truth) if i not in owner.values()],
+            'false_alarms':[{'id':p.id,'reason':'candidate assigned to another event' if any(j in e for e in edges) else 'no eligible truth'} for j,p in enumerate(predictions) if j not in owner],
+            'ambiguous_truth':[truth[i].id for i,e in enumerate(edges) if len(e)>1]}

eventscore_explorer-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: eventscore-explorer
+Version: 0.1.0
+Summary: Explain event-level time-series evaluation
+Author: Ryu Koda
+License-Expression: MIT
+Project-URL: Repository, https://github.com/R-Koda/eventscore-explorer
+Project-URL: Issues, https://github.com/R-Koda/eventscore-explorer/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# EventScore Explorer
+
+[![Tests](https://github.com/R-Koda/eventscore-explorer/actions/workflows/tests.yml/badge.svg)](https://github.com/R-Koda/eventscore-explorer/actions/workflows/tests.yml)
+**Explain why time-series events match — and why the score changes.**
+
+A small, dependency-free Python toolkit that turns truth and prediction intervals into an interactive HTML report. Inspect one-to-one matches, misses, false alarms, and signed onset offsets. Switch endpoint tolerances without a server.
+
+実際にどのイベントが対応したかを説明する、時系列評価ツールです。許容時間を切り替えてスコアの変化を確認できます。
+
+## Install from PyPI / pipでインストール
+
+Python 3.10 or later. Create and activate a virtual environment first:
+
+```sh
+python3 -m venv .venv
+```
+
+macOS / Linux: `source .venv/bin/activate`
+
+Windows PowerShell: `.venv\Scripts\Activate.ps1`
+
+```sh
+python -m pip install eventscore-explorer
+eventscore --help
+```
+
+The help screen confirms that the command is available. Install only the tools you need.
+[PyPI package](https://pypi.org/project/eventscore-explorer/) · [Source and examples](https://github.com/R-Koda/eventscore-explorer)
+
+サンプルCSV・Notebookなどはpipでは配置されません。公開デモはブラウザで開けます。自分でサンプルを実行する場合はGitHubの「Code → Download ZIP」で取得・展開し、READMEの相対パスをそのフォルダー内から指定してください。
+
+## Article & live demo / 紹介記事と公開デモ
+
+- [個別ガイド / EventScore Explorer：時系列の見逃し・誤検出を確かめる](https://ryu-koda.com/blog/eventscore-explorer-event-evaluation/)
+- [紹介記事：データを分ける・評価する・公開する。Pythonの小さな確認ツールを3つ作りました](https://ryu-koda.com/blog/python-tools-splittrace-eventscore-notebook/) — Japanese overview of SplitTrace, EventScore Explorer, and Notebook Publish Check.
+- [公開デモをブラウザで開く / Open the live demo](https://ryu-koda.com/articles/python-tools/eventscore-demo.html) — Synthetic data only; no installation required.
+
+公開デモは合成データの出力例です。自分のファイルをアップロードする画面ではありません。
+The hosted demo is a sample report, not a file-upload service.
+
+## Try the demo
+
+Open [`examples/demo.html`](https://github.com/R-Koda/eventscore-explorer/blob/main/examples/demo.html) in a browser after downloading the repository. All data is synthetic. At 0 seconds the demo has 2 matches, 3 false alarms and 2 misses. At 0.5 seconds it has 3 matches, 2 false alarms and 1 miss.
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install .
+eventscore examples/truth.csv examples/predictions.csv --tolerances 0,0.5,1,2 --output reports/events.html --json reports/events.json
+```
+
+Without installing: prefix the same arguments with `PYTHONPATH=src python3 -m eventscore_explorer` instead of `eventscore`.
+
+Python 3.10+. Runtime has no third-party dependencies.
+
+## Input
+
+Each CSV requires `id,start,end`; optional `label,recording` default to `event,default`. IDs must be unique within each input. Times are finite seconds with `0 <= start < end`. The two files must use the same time origin within each recording. Multiple recordings and labels are never matched across boundaries.
+
+```csv
+id,start,end,label,recording
+T1,10,15,event,recording-1
+```
+
+## Exact scoring policy
+
+- Intervals are half-open. At tolerance 0, only positive-duration overlap qualifies.
+- At positive tolerance, disjoint or touching intervals qualify when their endpoint gap is at most that tolerance. This is **not** an onset-only collar.
+- One truth and one prediction per match; maximum-cardinality bipartite matching maximizes matched count. Sorted traversal is deterministic; it does not optimize overlap or latency. Ambiguous matches are flagged.
+- Precision = matches / predictions; recall = matches / truth; F1 = 2 × matches / (truth + predictions). Undefined denominators are reported as `null` / N/A.
+- Onset offset = prediction start − truth start. Negative means early; it is not clipped into a positive detection delay.
+- No prediction merging, point adjustment, label weighting, true-negative metrics or clinical scoring is applied. Recording duration is not supplied, so false alarms/hour is not computed.
+
+Use the Python API: `from eventscore_explorer.core import Event, evaluate`.
+
+## Scope and limits
+
+Experimental 0.1. Input is capped at 2,000 events per file; matching can be expensive on dense graphs. Every requested tolerance is precomputed. Reports contain event IDs and times: review before publishing. Report files are never overwritten, and input CSVs cannot be output targets.
+
+This tool complements [TimeEval](https://github.com/TimeEval/timeeval) and [affiliation metrics](https://github.com/ahstat/affiliation-metrics-py). It does not implement those metrics or claim equivalence. Its focus is explaining a simple, explicit matching policy.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+Tests cover non-greedy matching, endpoint rules, duplicate alarms, recording/label isolation, empty inputs, determinism, validation and safe HTML data embedding.
+
+MIT licensed. Synthetic examples only; not a validated clinical evaluation standard.

eventscore_explorer-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+eventscore_explorer/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+eventscore_explorer/__main__.py,sha256=ee5vE0xcUZM3fPmxicvcw-IJXkm6nOwxARREHBWpF8Q,47
+eventscore_explorer/cli.py,sha256=cQvDJZovgrDwFcXoDcGQz2Cb8XmatT8DIaeNMvtWX4I,8114
+eventscore_explorer/core.py,sha256=0Qc4mr3lbgVL5zu3aBy-4bK374Vgw_5eFll67vloiHM,4618
+eventscore_explorer-0.1.0.dist-info/licenses/LICENSE,sha256=g92amfOtr0v2qgLJkCaw1xM9vtUm6PuYqjNM5rUYReE,1065
+eventscore_explorer-0.1.0.dist-info/METADATA,sha256=pK4Awq7bs4slJxVhhCLYG7IDTTA3vf5W5VLn19kbaW8,5832
+eventscore_explorer-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+eventscore_explorer-0.1.0.dist-info/entry_points.txt,sha256=YEVJkLtZ1VgzJtY3zYmcNA6eNjT4kOFYVIbWOCTqHVk,60
+eventscore_explorer-0.1.0.dist-info/top_level.txt,sha256=CsFPLHOVNygQ_uLlR0UEV8Rig76Z0aDBwPl-vm8iyi0,20
+eventscore_explorer-0.1.0.dist-info/RECORD,,

eventscore_explorer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

eventscore_explorer-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+eventscore = eventscore_explorer.cli:main

eventscore_explorer-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryu Koda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eventscore_explorer-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+eventscore_explorer