Update Croissant files

metadata/CROISSANT_VALIDATION_NOTES.md

@@ -0,0 +1,61 @@
+# Temporal Twins Croissant Validation Notes
+
+## 1. How to Validate
+
+Use the official MLCommons Croissant tooling after the dataset release files are hosted.
+
+1. Confirm the hosted dataset and code repository URLs in `metadata/temporal_twins_croissant.json` are correct for the current release.
+2. Validate the file with the official Croissant validator from the MLCommons Croissant project. If you use the web validator, upload the final JSON-LD file or point it at the hosted Croissant URL.
+3. As a local smoke check, you can also load the JSON-LD with a JSON parser before running the full validator:
+
+```bash
+python3 - <<'PY'
+import json
+from pathlib import Path
+path = Path("metadata/temporal_twins_croissant.json")
+with path.open() as f:
+    json.load(f)
+print("JSON parse OK")
+PY
+```
+
+4. After JSON parsing succeeds, run the official Croissant validation step and confirm the record sets, fields, and distribution references resolve correctly.
+
+## 2. Hosted URLs and Remaining Placeholders
+
+Dataset-side URLs now resolve to:
+
+- Dataset URL: `https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins`
+- Croissant metadata URL: `https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins/raw/main/metadata/temporal_twins_croissant.json`
+- Croissant metadata browser page: `https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins/blob/main/metadata/temporal_twins_croissant.json`
+- Data URL: `https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins/tree/main/data`
+- Results URL: `https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins/tree/main/results`
+- Configs URL: `https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins/tree/main/configs`
+- Metadata URL: `https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins/tree/main/metadata`
+- Release landing URL: `https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins`
+
+Code repository URL:
+
+- `https://huggingface.co/temporal-twins-benchmark/temporal-twins-code`
+
+Paper URL status:
+
+- Not available during double-blind review; to be added after publication.
+
+## 3. Release Checklist
+
+- Dataset URL is accessible to reviewers.
+- Croissant file validates with the official MLCommons Croissant validator.
+- Distribution URLs resolve to the intended hosted artifacts.
+- Record-set columns match the actual hosted files.
+- RAI fields are present.
+- Dataset license is present (`CC-BY-4.0`).
+- Code repository license is present (`Apache-2.0`).
+
+## 4. Packaging Notes
+
+- The Croissant file describes four dataset slices: `oracle_calib`, `easy`, `medium`, and `hard`.
+- It assumes deterministic release seeds `0, 1, 2, 3, 4`.
+- It assumes paper-suite configuration `num_users=350`, `simulation_days=45`, `fast_mode=false`, and `n_checkpoints=8`.
+- The `matched_prefix_examples` record set uses the release-facing column name `matched_local_event_idx`.
+- If the final hosted matched-pairs files keep the internal pipeline column name `eval_local_event_idx` instead, either rename that column in the export or update the Croissant metadata so the record-set field names match the hosted files exactly.

metadata/temporal_twins_croissant.json

@@ -1,5 +1,6 @@
 {
   "@context": {
+    "@language": "en",
     "@vocab": "https://schema.org/",
     "sc": "https://schema.org/",
     "cr": "http://mlcommons.org/croissant/",
@@ -51,79 +52,42 @@
     "reproducible benchmark"
   ],
   "distribution": [
-    {
-      "@id": "transactions-archive",
-      "@type": "cr:FileObject",
-      "name": "Transactions archive",
-      "description": "Hosted archive containing synthetic transaction files for oracle_calib, easy, medium, and hard across seeds 0 through 4.",
-      "contentUrl": "https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins/tree/main/data",
-      "encodingFormat": "application/zip"
-    },
-    {
-      "@id": "matched-prefix-archive",
-      "@type": "cr:FileObject",
-      "name": "Matched-prefix examples archive",
-      "description": "Hosted release archive containing matched-prefix fraud/benign evaluation examples under release/data/*/seed_*/matched_pairs.parquet.",
-      "contentUrl": "https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins",
-      "encodingFormat": "application/zip"
-    },
-    {
-      "@id": "configs-archive",
-      "@type": "cr:FileObject",
-      "name": "Configs archive",
-      "description": "Hosted release archive containing benchmark configuration files under release/configs/*.yaml.",
-      "contentUrl": "https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins",
-      "encodingFormat": "application/zip"
-    },
-    {
-      "@id": "results-archive",
-      "@type": "cr:FileObject",
-      "name": "Results archive",
-      "description": "Hosted release archive containing the deterministic 5-seed paper-suite outputs under release/results/.",
-      "contentUrl": "https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins",
-      "encodingFormat": "application/zip"
-    },
     {
       "@id": "metadata-files",
       "@type": "cr:FileSet",
       "name": "Metadata files",
-      "description": "Metadata payload for the public release, including this Croissant file and companion notes.",
-      "containedIn": {
-        "@id": "results-archive"
-      },
-      "includes": "release/metadata/*"
+      "description": "Metadata payload for the hosted release, including this Croissant file and companion notes.",
+      "includes": "metadata/*"
     },
     {
       "@id": "transactions-files",
       "@type": "cr:FileSet",
       "name": "Synthetic transactions parquet files",
       "description": "Expected synthetic transaction files for benchmark modes oracle_calib, easy, medium, and hard across seeds 0 through 4.",
-      "containedIn": {
-        "@id": "transactions-archive"
-      },
-      "includes": "release/data/*/seed_*/transactions.parquet",
+      "includes": "data/*/seed_*/transactions.parquet",
       "encodingFormat": "application/x-parquet"
     },
     {
       "@id": "matched-prefix-files",
       "@type": "cr:FileSet",
       "name": "Matched-prefix example parquet files",
-      "description": "Expected matched-prefix benchmark examples for the release. Each file contains fraud and benign twin examples evaluated at the same local prefix index.",
-      "containedIn": {
-        "@id": "matched-prefix-archive"
-      },
-      "includes": "release/data/*/seed_*/matched_pairs.parquet",
+      "description": "Expected matched-prefix benchmark examples for the hosted release. Each file contains fraud and benign twin examples evaluated at the same local prefix index.",
+      "includes": "data/*/seed_*/matched_pairs.parquet",
       "encodingFormat": "application/x-parquet"
     },
     {
       "@id": "config-files",
       "@type": "cr:FileSet",
       "name": "Benchmark config files",
-      "description": "YAML configuration files for the public release.",
-      "containedIn": {
-        "@id": "configs-archive"
-      },
-      "includes": "release/configs/*.yaml"
+      "description": "YAML configuration files for the hosted release.",
+      "includes": "configs/*.yaml"
+    },
+    {
+      "@id": "results-files",
+      "@type": "cr:FileSet",
+      "name": "Results files",
+      "description": "Hosted result summaries and diagnostics for the deterministic paper suite.",
+      "includes": "results/*"
     },
     {
       "@id": "paper-suite-runs-csv",
@@ -131,9 +95,6 @@
       "name": "Per-run paper-suite results",
       "description": "Per-run deterministic results for the final 5-seed paper-scale suite.",
       "contentUrl": "https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins/raw/main/results/paper_suite_runs.csv",
-      "containedIn": {
-        "@id": "results-archive"
-      },
       "encodingFormat": "text/csv"
     },
     {
@@ -142,9 +103,6 @@
       "name": "Paper-suite summary results",
       "description": "Mean and standard deviation summary of the deterministic 5-seed paper suite.",
       "contentUrl": "https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins/raw/main/results/paper_suite_summary.csv",
-      "containedIn": {
-        "@id": "results-archive"
-      },
       "encodingFormat": "text/csv"
     },
     {
@@ -153,9 +111,6 @@
       "name": "Paper-suite runtime summary",
       "description": "Runtime and StaticGNN evaluation diagnostics for the final paper suite.",
       "contentUrl": "https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins/raw/main/results/paper_suite_runtime.csv",
-      "containedIn": {
-        "@id": "results-archive"
-      },
       "encodingFormat": "text/csv"
     },
     {
@@ -164,9 +119,6 @@
       "name": "Paper-suite failed gate checks",
       "description": "Gate-check and advisory-check outcomes for each run in the final paper suite.",
       "contentUrl": "https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins/raw/main/results/paper_suite_failed_checks.csv",
-      "containedIn": {
-        "@id": "results-archive"
-      },
       "encodingFormat": "text/csv"
     },
     {
@@ -175,9 +127,6 @@
       "name": "Temporal Twins Croissant metadata",
       "description": "MLCommons Croissant 1.1 metadata for the full Temporal Twins benchmark collection.",
       "contentUrl": "https://huggingface.co/datasets/temporal-twins-benchmark/temporal-twins/raw/main/metadata/temporal_twins_croissant.json",
-      "containedIn": {
-        "@id": "metadata-files"
-      },
       "encodingFormat": "application/ld+json"
     }
   ],