Data Format¶

The public data contract is JSONL split files. Each line is one event sequence. The same format is used by the Python API and the CLI.

Minimal Record¶

{"times": [0.1, 0.4, 1.2], "locations": [[0.2, 0.4], [0.3, 0.8], [0.7, 0.1]]}

times[i] and locations[i] describe the same event. locations is a list of coordinate pairs. Optional per-event arrays (marks, event_covariates, field_covariates) must have the same length as times.

Local Data For One Run¶

Use this layout for Python API experiments, fit, tune, or one-dataset bench runs:

dataset_root/
  train.jsonl
  val.jsonl
  test.jsonl

train.jsonl and val.jsonl are required for fitting. test.jsonl is normally needed for evaluation.

Show Python example

from seahorse import load_jsonl

train = load_jsonl("dataset_root/train.jsonl")
val   = load_jsonl("dataset_root/val.jsonl")
test  = load_jsonl("dataset_root/test.jsonl")

Show CLI command

python -m seahorse fit \
  --preset poisson_gmm \
  --train dataset_root/train.jsonl \
  --val dataset_root/val.jsonl \
  --test dataset_root/test.jsonl \
  --out runs/local_fit

Local Data For Benchmarks¶

Use a split collection when benchmarking multiple datasets:

Show benchmark layout

splits_root/
  dataset_a/
    train.jsonl
    val.jsonl
    test.jsonl
  dataset_b/
    train.jsonl
    val.jsonl
    test.jsonl

Run all datasets found under the root:

python -m seahorse bench \
  --presets poisson_gmm hawkes_gmm \
  --splits_dir splits_root \
  --seeds 1 2 3 \
  --out runs/bench

Show CLI command — filter to specific datasets

python -m seahorse bench \
  --presets poisson_gmm hawkes_gmm \
  --splits_dir splits_root \
  --datasets dataset_a dataset_b \
  --seeds 1 \
  --out runs/bench_subset

Hugging Face Data¶

python -m seahorse fit \
  --preset poisson_gmm \
  --dataset owner/repo[/subdir] \
  --dataset-revision main \
  --out runs/hf_fit

Use --dataset-revision to pin the source for reproducible runs. The resolved dataset must expose train.jsonl and val.jsonl; test.jsonl is used when present.

Show CLI command — HuggingFace benchmark source

python -m seahorse bench \
  --preset poisson_gmm \
  --dataset owner/repo[/subdir] \
  --dataset-revision main \
  --seeds 1 \
  --out runs/bench_hf

Command Support Matrix¶

Command	Local split paths	Local dataset directory	Split collection	Hugging Face source
Python API	yes, via `load_jsonl`	yes, by reading files	manual loop	not directly
`fit`	`--train --val --test`	`--dataset`	no	`--dataset`
`tune`	`--train --val`	`--dataset`	no	`--dataset`
`bench`	no	`--dataset`	`--splits_dir`	`--dataset`
`evaluate metrics`	`--data`	no	no	no

Practical Checks¶

Keep train, validation, and test splits separate.
Use the same coordinate system across all splits for a dataset.
Use one JSON object per line, not a single JSON array file.
Keep optional per-event arrays aligned with times.
Pin Hugging Face revisions for benchmark or paper results.