README.md

metadata

title: HiCoTraj
emoji: 🗺️
colorFrom: red
colorTo: indigo
sdk: gradio
app_file: app.py
pinned: false

HiCoTraj Demo

Zero-Shot Demographic Reasoning via Hierarchical Chain-of-Thought Prompting from Trajectory ACM SIGSPATIAL GeoGenAgent Workshop 2025

---

Overview

HiCoTraj is a demo that shows how a large language model can infer demographic attributes, specifically household income, from raw human mobility trajectories through a three-stage hierarchical chain-of-thought prompting strategy. It does not require training data or fine-tuning.

---

Interface Layout

Component	Description
Agent Cards	Top panel — 6 showcase agents from the NUMOSIM dataset. Click any card to load that agent's data throughout the interface.
Trajectory Map	Interactive map of stay points, ordered chronologically (yellow → dark red). Click any dot for location, time, and activity details.
Summary Tab	Rule-based processed data: top locations, temporal distribution, activity breakdown, and observation period.
Raw Data Tab	Full daily activity log. Use Show All Days to expand beyond the preview.
CoT Panel	Right column — step-by-step LLM reasoning. Advance with the ▶ button; each click runs one stage.

---

How to Run the Demo

1. Select an agent by clicking one of the six cards at the top of the page.
2. Explore the Trajectory Map — hover and click stay-point markers to inspect visit details.
3. Switch to the Raw Data tab and click Show All Days to view the complete daily log.
4. Click ▶ Stage 1: Feature Extraction to begin the reasoning chain.
5. Click ▶ Stage 2: Behavioral Analysis — Stage 1 results are now visible.
6. Click ▶ Stage 3: Demographic Inference — all three stages shown simultaneously.
7. Click ↺ Reset to clear results and try a different agent.

💡 Tip: Click ▼ prompt under each stage header to expand the full prompt specification used for that step.

---

Hierarchical Chain-of-Thought Stages

🔵 Stage 01 — Feature Extraction

The LLM receives raw trajectory data and extracts objective features without interpretation: location inventory (POI names, visit counts, price tier), temporal patterns (time-of-day and weekday/weekend split), spatial activity radius, and daily activity sequences.

Displayed as: location table with visit bars · time-of-day color segment bar · weekday/weekend split

🟠 Stage 02 — Behavioral Analysis

Using Stage 1 features, the model performs behavioral abstraction across four dimensions: Routine & Schedule (work pattern type), Economic Behavior (spending tier from venue choices), Social & Lifestyle (leisure and community engagement), and Routine Stability (consistency of movement patterns).

Displayed as: 2×2 card grid — one card per behavioral dimension

🔴 Stage 03 — Demographic Inference

The model synthesizes Stages 1 and 2 to infer the agent's household income bracket, citing specific mobility evidence. The structured output (INCOME_PREDICTION / INCOME_REASONING) enables reliable extraction and display.

Displayed as: income prediction badge · evidence-grounded reasoning text

---

Dataset

NUMOSIM — NUMoSim: A Synthetic Mobility Dataset with Anomaly Detection Benchmarks. Stanford C., Adari S., Liao X., et al. ACM SIGSPATIAL Workshop on Geospatial Anomaly Detection, 2024.

Synthetic trajectories preserving real population demographics and mobility patterns.

• Demo subset: 6 agents
• Attribute inferred: household income bracket
• Method: zero-shot LLM, no fine-tuning