Improve H2EPR Explorer event navigation and timeline UX

README.md

@@ -9,7 +9,7 @@ license: cc-by-nc-4.0
 
 # H²EPR-Bench Explorer
 
-H²EPR-Bench Explorer is the planned interactive browsing layer for `AgenticFinLab/H2EPR-Bench`. It is separate from the canonical dataset repository: the dataset repo remains the release package, while this Docker Space runs a Streamlit app for search, event detail, stage inspection, public FinalCascade JSON browsing, and Gantt-style timelines.
+H²EPR-Bench Explorer is the interactive browsing layer for `AgenticFinLab/H2EPR-Bench`. It is separate from the canonical dataset repository: the dataset repo remains the release package, while this Docker Space runs a Streamlit app for search, event detail, stage inspection, public FinalCascade JSON browsing, and Gantt-style timelines.
 
 **Release boundary:** public records are intended for browsing, reuse, and presentation. Official scoring uses the [manual-gated Gold companion](https://huggingface.co/datasets/AgenticFinLab/H2EPR-Bench-Gold). Public FinalCascade and Gantt views are supplementary inspection assets, not official scoring references.
 

app.py

@@ -17,6 +17,12 @@ from h2epr_explorer.constants import (
 )
 from h2epr_explorer.data_loader import load_catalog, load_event_graph, load_finalcascade_summary, load_stages
 from h2epr_explorer.filters import event_description, event_display_label, event_name, filter_catalog
+from h2epr_explorer.navigation import (
+    build_event_links,
+    filter_summary_text,
+    query_param_event_id,
+    resolve_selected_event_index,
+)
 from h2epr_explorer.render_gantt import build_timeline_figure
 
 
@@ -29,10 +35,57 @@ def _select_columns(frame, columns):
     return frame[present] if present else frame
 
 
+def _sort_stage_frame(frame):
+    sort_columns = [column for column in ("stage_index", "stage_order", "stage_id") if column in frame.columns]
+    return frame.sort_values(sort_columns) if sort_columns else frame
+
+
+def _safe_int(value, default=0):
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
 st.set_page_config(page_title="H2EPR-Bench Explorer", layout="wide")
 
-st.title("H²EPR-Bench Explorer")
-st.caption("Interactive browser for public event metadata, stage rows, FinalCascade summaries, and Gantt-style views.")
+st.markdown(
+    """
+<style>
+div[data-testid="stMetric"] {
+    border: 1px solid #e5e7eb;
+    border-radius: 8px;
+    padding: 0.35rem 0.6rem;
+    background: #fbfbf8;
+}
+.h2epr-kicker {
+    color: #4b5563;
+    font-size: 0.92rem;
+    letter-spacing: 0;
+    margin-bottom: 0.25rem;
+}
+.h2epr-title {
+    font-size: 2.15rem;
+    font-weight: 760;
+    line-height: 1.12;
+    margin-bottom: 0.25rem;
+}
+.h2epr-subtitle {
+    color: #374151;
+    max-width: 920px;
+    margin-bottom: 0.75rem;
+}
+</style>
+""",
+    unsafe_allow_html=True,
+)
+
+st.markdown('<div class="h2epr-kicker">H²EPR-Bench · public release explorer</div>', unsafe_allow_html=True)
+st.markdown('<div class="h2epr-title">Event-process graph browser</div>', unsafe_allow_html=True)
+st.markdown(
+    '<div class="h2epr-subtitle">Browse public event metadata, stage rows, FinalCascade summaries, and Gantt-style timelines for the H²EPR-Bench release.</div>',
+    unsafe_allow_html=True,
+)
 st.info(RELEASE_BOUNDARY_NOTICE)
 
 catalog = load_catalog()
@@ -48,6 +101,9 @@ with st.sidebar:
     categories = st.multiselect("Category", sorted(catalog["event_category"].dropna().unique().tolist()))
     min_source_count = st.slider("Minimum sources", 0, int(catalog["source_count"].max()), 0)
     min_stage_count = st.slider("Minimum stages", 0, int(catalog["stage_count"].max()), 0)
+    st.divider()
+    st.link_button("Dataset repository", f"https://huggingface.co/datasets/{PUBLIC_DATASET_REPO}", use_container_width=True)
+    st.link_button("Request Gold access", f"https://huggingface.co/datasets/{GOLD_COMPANION_REPO}", use_container_width=True)
 
 filtered_rows = filter_catalog(
     catalog_rows,
@@ -63,35 +119,80 @@ if not filtered_rows:
     st.stop()
 
 event_labels = {row["event_id"]: event_display_label(row) for row in catalog_rows}
+requested_event_id = query_param_event_id(st.query_params)
+selected_index = resolve_selected_event_index(filtered_rows, requested_event_id)
 
 selected_event = st.selectbox(
     "Selected event",
     [row["event_id"] for row in filtered_rows],
+    index=selected_index,
     format_func=lambda event_id: event_labels.get(event_id, event_id),
 )
+try:
+    st.query_params["event_id"] = selected_event
+except Exception:
+    pass
 
 event_row = catalog[catalog["event_id"] == selected_event].iloc[0]
 event_record = event_row.to_dict()
-event_stages = stages[stages["event_id"] == selected_event].sort_values("stage_order")
+event_stages = _sort_stage_frame(stages[stages["event_id"] == selected_event])
 summary_row = summary[summary["event_id"] == selected_event]
+event_links = build_event_links(selected_event, str(event_record.get("gantt_html_path") or ""))
 
-tabs = st.tabs(["Catalog", "Event detail", "Timeline", "Stages", "FinalCascade JSON", "Release boundary"])
+st.caption(filter_summary_text(len(filtered_rows), len(catalog_rows)))
+
+tabs = st.tabs(["Catalog", "Event detail", "Timeline", "Stages", "FinalCascade JSON", "Access and boundary"])
 
 with tabs[0]:
-    st.subheader(f"Event catalog: {len(filtered_rows)} of {len(catalog_rows)} events")
+    st.subheader("Event catalog")
     st.dataframe(_select_columns(catalog[catalog["event_id"].isin([row["event_id"] for row in filtered_rows])], CATALOG_COLUMNS), use_container_width=True, height=520)
 
 with tabs[1]:
     st.subheader(event_name(event_record))
     st.write(event_description(event_record))
-    c1, c2, c3, c4 = st.columns(4)
-    c1.metric("Domain", str(event_row.get("domain", "")))
-    c2.metric("Category", str(event_row.get("event_category", "")))
-    c3.metric("Sources", int(event_row.get("source_count", 0)))
-    c4.metric("Stages", int(event_row.get("stage_count", 0)))
+    c1, c2, c3, c4, c5 = st.columns(5)
+    c1.metric("Sources", _safe_int(event_row.get("source_count", 0)))
+    c2.metric("Stages", _safe_int(event_row.get("stage_count", 0)))
+    c3.metric("Episodes", _safe_int(event_row.get("episode_count", 0)))
+    c4.metric("Participants", _safe_int(event_row.get("participant_count", 0)))
+    c5.metric("Relations", _safe_int(event_row.get("relation_count", 0)))
+
+    st.markdown("#### Event profile")
+    profile_columns = [
+        "event_id",
+        "display_name",
+        "domain",
+        "event_category",
+        "event_scope_label",
+        "keywords",
+        "event_boundary_time_status",
+        "temporal_anchor_summary",
+        "gold_reference_access_level",
+        "finalcascade_access_level",
+    ]
+    st.dataframe(_select_columns(catalog[catalog["event_id"] == selected_event], profile_columns), use_container_width=True)
+
+    link_cols = st.columns(4)
+    link_cols[0].link_button("Open dataset", event_links["public_dataset"], use_container_width=True)
+    link_cols[1].link_button("Gold access", event_links["gold_request"], use_container_width=True)
+    link_cols[2].link_button("FinalCascade file", event_links["finalcascade_jsonl"], use_container_width=True)
+    if "gantt_html" in event_links:
+        link_cols[3].link_button("Gantt artifact", event_links["gantt_html"], use_container_width=True)
+
     if not summary_row.empty:
         st.markdown("#### Public FinalCascade summary")
-        st.dataframe(summary_row, use_container_width=True)
+        summary_columns = [
+            "event_id",
+            "stage_count",
+            "episode_count",
+            "participant_count",
+            "transaction_count",
+            "relation_count",
+            "event_boundary_time_status",
+            "known_action_time_anchor_count",
+            "not_gold_warning",
+        ]
+        st.dataframe(_select_columns(summary_row, summary_columns), use_container_width=True)
 
 with tabs[2]:
     figure = build_timeline_figure(_as_records(event_stages), selected_event)

src/h2epr_explorer/constants.py

@@ -17,13 +17,14 @@ RELEASE_BOUNDARY_NOTICE = (
 
 CATALOG_COLUMNS = [
     "event_id",
-    "event_name",
+    "display_name",
     "domain",
     "event_category",
-    "short_description",
+    "event_descriptor_en",
     "keywords",
     "source_count",
     "stage_count",
+    "event_boundary_time_status",
+    "known_action_time_anchor_count",
     "gantt_html_path",
 ]
-

src/h2epr_explorer/navigation.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .constants import GOLD_COMPANION_REPO, PUBLIC_DATASET_REPO
+
+
+SPACE_URL = "https://huggingface.co/spaces/AgenticFinLab/H2EPR-Bench-Explorer"
+PUBLIC_DATASET_URL = f"https://huggingface.co/datasets/{PUBLIC_DATASET_REPO}"
+GOLD_COMPANION_URL = f"https://huggingface.co/datasets/{GOLD_COMPANION_REPO}"
+
+
+def _first_value(value: Any) -> str:
+    if isinstance(value, (list, tuple)):
+        return str(value[0]).strip() if value else ""
+    return str(value or "").strip()
+
+
+def query_param_event_id(query_params: Mapping[str, Any]) -> str:
+    return _first_value(query_params.get("event_id"))
+
+
+def resolve_selected_event_index(rows: list[dict[str, Any]], requested_event_id: str = "") -> int:
+    if not rows:
+        return 0
+    if requested_event_id:
+        for index, row in enumerate(rows):
+            if str(row.get("event_id", "")).strip() == requested_event_id:
+                return index
+    return 0
+
+
+def build_event_links(event_id: str, gantt_html_path: str = "") -> dict[str, str]:
+    event_id = event_id.strip()
+    links = {
+        "explorer": f"{SPACE_URL}?event_id={event_id}",
+        "public_dataset": PUBLIC_DATASET_URL,
+        "gold_request": GOLD_COMPANION_URL,
+        "finalcascade_jsonl": f"{PUBLIC_DATASET_URL}/blob/main/data/finmycelium_finalcascade_public.jsonl",
+    }
+    if gantt_html_path:
+        links["gantt_html"] = f"{PUBLIC_DATASET_URL}/blob/main/{gantt_html_path.lstrip('/')}"
+    return links
+
+
+def filter_summary_text(filtered_count: int, total_count: int) -> str:
+    return f"Showing {filtered_count:,} of {total_count:,} events"

src/h2epr_explorer/render_gantt.py

@@ -7,18 +7,42 @@ def _is_known_time(value: Any) -> bool:
     return bool(value) and str(value).strip().lower() not in {"unknown", "none", "nan", "nat"}
 
 
+def _stage_order(row: dict[str, Any], fallback_index: int = 0) -> int:
+    value = row.get("stage_index", row.get("stage_order", fallback_index))
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return fallback_index
+
+
+def _stage_label(row: dict[str, Any]) -> str:
+    for field in ("stage_title", "stage_label_public", "stage_label", "stage_id"):
+        value = str(row.get(field) or "").strip()
+        if value:
+            return value
+    return "Unnamed stage"
+
+
 def prepare_gantt_rows(stage_rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    ordered = sorted(stage_rows, key=lambda row: (int(row.get("stage_order") or 0), str(row.get("stage_id", ""))))
+    ordered = sorted(
+        stage_rows,
+        key=lambda row: (_stage_order(row), str(row.get("stage_id", ""))),
+    )
+    calendar_axis = all(
+        _is_known_time(row.get("stage_start_time")) and _is_known_time(row.get("stage_end_time"))
+        for row in ordered
+    )
     prepared: list[dict[str, Any]] = []
     for fallback_index, row in enumerate(ordered, start=1):
         start = row.get("stage_start_time")
         end = row.get("stage_end_time")
-        if _is_known_time(start) and _is_known_time(end):
+        stage_order = _stage_order(row, fallback_index)
+        if calendar_axis:
             display_start = start
             display_end = end
             axis_mode = "calendar"
         else:
-            display_start = int(row.get("stage_order") or fallback_index)
+            display_start = stage_order
             display_end = display_start + 0.85
             axis_mode = "relative_order"
 
@@ -29,6 +53,8 @@ def prepare_gantt_rows(stage_rows: list[dict[str, Any]]) -> list[dict[str, Any]]
         prepared.append(
             {
                 **row,
+                "stage_label": _stage_label(row),
+                "stage_order": stage_order,
                 "display_start": display_start,
                 "display_end": display_end,
                 "axis_mode": axis_mode,
@@ -52,8 +78,8 @@ def build_timeline_figure(stage_rows: list[dict[str, Any]], event_id: str):
             frame,
             x_start="display_start",
             x_end="display_end",
-            y="stage_label_public",
-            color="stage_label_public",
+            y="stage_label",
+            color="stage_label",
             hover_data=["stage_id", "stage_order", "time_note"],
             title=f"{event_id}: public stage timeline",
         )
@@ -63,14 +89,13 @@ def build_timeline_figure(stage_rows: list[dict[str, Any]], event_id: str):
     fig = px.bar(
         frame,
         x=[row["display_end"] - row["display_start"] for row in prepared],
-        y="stage_label_public",
+        y="stage_label",
         base="display_start",
         orientation="h",
-        color="stage_label_public",
+        color="stage_label",
         hover_data=["stage_id", "stage_order", "time_note"],
         title=f"{event_id}: relative stage order",
     )
     fig.update_yaxes(autorange="reversed")
     fig.update_layout(xaxis_title="Relative stage order")
     return fig
-