SizheZ03/DRIVES_Markovian

DRIVES Markovian

This repository contains the train-only Markov/table baseline artifacts for the DRIVES strict next-location prediction benchmark.

The model is not a neural network and it is not a Hugging Face transformers model. It is a serialized set of transition-count/probability tables plus optional SGD candidate-ranker artifacts used by the DRIVES next-location pipeline.

current trip context
+ participant/start/hour/gap/previous-location lookup tables
-> candidate destination probabilities/ranks
-> ranked candidate list

Repository contents

Expected repository layout:

artifacts_fulltrain_trainonly/
  tables.pkl
  place_feature_map.pkl
  artifact_metadata.json

markov_origin_to_destination/
  markov_model.json
  val_predictions.parquet
  test_predictions.parquet

sgd_candidate_ranker/
  sgd_model.json
  sgd_classifier.joblib
  val_predictions.parquet
  test_predictions.parquet

manifest.json
metrics.json
report.md

The screenshot version of this repository already shows the three important artifact directories:

artifacts_fulltrain_trainonly
markov_origin_to_destination
sgd_candidate_ranker

What the model does

The primary Markovian model predicts the next destination cell from train-derived transition tables. The most important table is the participant-specific origin-to-destination table:

P(destination | participant, current_start_cell)

The broader artifact set also contains auxiliary train-only tables used by the stricter candidate-ranker pipeline:

participant_start:       P(destination | participant, current_start_cell)
global_start:            P(destination | current_start_cell)
participant_destination: P(destination | participant)
global_destination:      P(destination)
participant_hour:        P(destination | participant, start_hour)
global_hour:             P(destination | start_hour)
participant_gap:         P(destination | participant, previous_gap_bucket)
global_gap:              P(destination | previous_gap_bucket)
participant_prev_end:    P(destination | participant, previous_end_cell)
global_prev_end:         P(destination | previous_end_cell)

These tables are built from the training split only.

Strict evaluation rule

This artifact is designed for strict evaluation. Strict means:

do not append the true held-out destination to the candidate set when retrieval misses it

If the true destination is absent from the candidate list, that row receives:

MRR contribution = 0
Hit@k = false

This makes candidate coverage an upper bound on Hit@k.

Reported strict results

Dataset:

data/next_location/processed/next_location_supervised_250m_test10pct.parquet

Rows:

train: 223,018
val:     4,788
test:    4,788

Markov origin-to-destination baseline

Split	Candidate coverage	MRR	Hit@1	Hit@5	Hit@10	Mean candidates
Validation	0.5081	0.4092	0.3467	0.5040	0.5081	5.79
Test	0.4532	0.3489	0.2857	0.4513	0.4532	5.31

SGD candidate-ranker baseline

Split	Candidate coverage	MRR	Hit@1	Hit@5	Hit@10	Mean candidates
Validation	0.6652	0.4101	0.3193	0.5340	0.6424	23.45
Test	0.6412	0.3489	0.2571	0.4756	0.6061	23.17

How to download

from pathlib import Path
from huggingface_hub import snapshot_download

repo_dir = Path(snapshot_download("SizheZ03/DRIVES_Markovian", repo_type="model"))
print(repo_dir)

Minimal loading example

import pickle
from pathlib import Path
from huggingface_hub import snapshot_download

repo_dir = Path(snapshot_download("SizheZ03/DRIVES_Markovian", repo_type="model"))

with open(repo_dir / "artifacts_fulltrain_trainonly" / "tables.pkl", "rb") as f:
    tables = pickle.load(f)

with open(repo_dir / "artifacts_fulltrain_trainonly" / "place_feature_map.pkl", "rb") as f:
    place_feature_map = pickle.load(f)

print(tables.keys())
print(len(place_feature_map))

Using the tables directly

The exact nested structure depends on the DRIVES table builder, so the safest way is to use the DRIVES helper functions. Conceptually, a table entry contains a candidate-count distribution and normalized probabilities.

Example pattern:

participant_id = "100010"
start_place_id = "some_origin_cell"

entry = tables["participant_start"].get((participant_id, start_place_id))

if entry is not None:
    # Usually contains candidate counts/probabilities used by DRIVES helpers.
    print(entry.keys())

For direct reproduction of the benchmark, use the DRIVES scripts rather than manually reading table internals.

Proper DRIVES usage

Clone the DRIVES repository:

git clone https://github.com/novaz03/DRIVES.git
cd DRIVES

Install the usual Python stack:

pip install pandas numpy scikit-learn joblib pyarrow

Then place or symlink the downloaded Hugging Face artifact directory into the expected DRIVES baseline path, for example:

mkdir -p data/next_location/baselines
ln -s /path/to/DRIVES_Markovian \
  data/next_location/baselines/markov_sgd_strict_retrain_20260706_093316

The key train-only artifact path expected by later scripts is:

data/next_location/baselines/markov_sgd_strict_retrain_20260706_093316/artifacts_fulltrain_trainonly/tables.pkl

Model A and Model B rerankers use this artifact directory via:

--artifact-dir data/next_location/baselines/markov_sgd_strict_retrain_20260706_093316/artifacts_fulltrain_trainonly

Reusing the SGD candidate ranker

The repository also includes:

sgd_candidate_ranker/sgd_classifier.joblib
sgd_candidate_ranker/sgd_model.json

Load with:

from pathlib import Path
from huggingface_hub import snapshot_download
import joblib
import json

repo_dir = Path(snapshot_download("SizheZ03/DRIVES_Markovian", repo_type="model"))

clf = joblib.load(repo_dir / "sgd_candidate_ranker" / "sgd_classifier.joblib")
metadata = json.loads((repo_dir / "sgd_candidate_ranker" / "sgd_model.json").read_text())

print(type(clf))
print(metadata.keys())

The SGD ranker is a lightweight learned candidate ranker over static Markov/table and POI/parking features. It is not the same as the LLM rescorer.

Relationship to other DRIVES models

This repository is the structured non-LLM baseline artifact.

It is used downstream by:

Model A: LLM rank + structured LambdaMART fusion ranker
Model B: LLM semantic embedding + MLP scorer
LLM linear-head rescorer evaluation scripts

The Markovian model provides train-only transition priors and candidate-generation support. The neural and tree-based rerankers can then rescore candidates produced or supported by these tables.

Common mistakes

Mistake 1: treating this as a Transformers model

This is not a transformers checkpoint. Do not call:

AutoModel.from_pretrained("SizheZ03/DRIVES_Markovian")

Use pickle, joblib, and the DRIVES helper scripts.

Mistake 2: changing strict evaluation

Do not append the true destination during validation/test evaluation if you want comparable metrics.

Mistake 3: mixing candidate coverage with ranking quality

MRR and Hit@k are all-row strict metrics. Low candidate coverage directly limits maximum possible Hit@k.

Mistake 4: assuming the tables are universal

The transition tables are specific to the DRIVES processed dataset, split definition, cell resolution, and train/test split used to build them.

Files that are required for downstream DRIVES rerankers

Minimum required for downstream scripts:

artifacts_fulltrain_trainonly/tables.pkl
artifacts_fulltrain_trainonly/place_feature_map.pkl

Useful for reproducibility/reporting:

manifest.json
metrics.json
report.md
artifacts_fulltrain_trainonly/artifact_metadata.json
markov_origin_to_destination/val_predictions.parquet
markov_origin_to_destination/test_predictions.parquet
sgd_candidate_ranker/val_predictions.parquet
sgd_candidate_ranker/test_predictions.parquet

Required only if using the SGD ranker:

sgd_candidate_ranker/sgd_classifier.joblib
sgd_candidate_ranker/sgd_model.json

Project reference

https://github.com/novaz03/DRIVES

Relevant project files:

scripts/next_location/baseline_candidate_ranker.py
scripts/next_location/llm_structured_lambdamart_meta_ranker.py
scripts/next_location/llm_embedding_mlp_ranker.py
docs/nonllm_audit_summary.md

Limitations

• Dataset-specific and split-specific.
• Uses historical transition regularities; it does not use semantic LLM reasoning.
• Candidate coverage is limited for rare/unseen transitions.
• The SGD component requires the same feature construction used in DRIVES.
• Intended for research and reproducibility, not general-purpose geolocation prediction.

License

Set the Hugging Face license field to match the DRIVES repository license and any dataset constraints that apply to the released artifacts.