---
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