# walkingpandas

**Massive-scale walk and path analysis on network topologies.**

walkingpandas bridges static graph theory (network topologies) with massive-scale sequential data -- any process that can be modelled as a walk on a graph. DuckDB is the analytical engine, Parquet the storage layer, and the API feels like pandas while safely handling out-of-core computation on datasets of any size.

**Use cases:** pedestrian and vehicle mobility, clickstream / user-journey analysis, supply-chain and logistics flows, trade and transaction routing, biological pathway traversal, communication network traces -- anything where entities move step-by-step through a graph.

## Core concepts

The API is built around two types:

| Concept | Role |
|---------|------|
| **Network** | Static topology: nodes and edges. Load once, reuse. Stored in DuckDB (in-memory or file). |
| **WalkFrame** | Lazy view over walk/path data (Parquet or a DuckDB table), tied to a Network. Build filters and aggregations, then call `.compute()` to run the query. |

## Features

- **Lazy evaluation** -- build up queries without executing until `.compute()` is called
- **Out-of-core processing** -- handle datasets that don't fit in memory using DuckDB and Parquet
- **Integer-native IDs** -- all node/edge IDs stored as BIGINT for fast joins; string IDs auto-translated transparently
- **Map matching** (optional) -- turn raw GPS traces into walk data via Valhalla (`pip install walkingpandas[mapmatch]`)
- **Spatial filtering** -- reverse spatial filtering for fast geographic queries
- **Temporal queries** -- handle time-less, single-timestamp, and dwell-time data
- **Graph validation** -- filter simple paths, cycles, and complex walks
- **Pandas-like API** -- familiar interface for data scientists

## Quick example

```python
import walkingpandas as wp

network = wp.Network(
    nodes="data/network/nodes.parquet",
    edges="data/network/edges.parquet",
)
walks = wp.WalkFrame.from_parquet("data/walks/*.parquet", network=network)

result = (
    walks
    .only_simple_paths()
    .passing_through([42])
    .filter(time_range=("08:00", "09:00"))
    .edge_frequencies()
    .compute()
)
```

## Next steps

- [Getting started](getting-started.md) -- installation, quick start, and creating your first WalkFrame
- [User guide](user-guide/architecture.md) -- architecture, data schema, and performance
- [API reference](api/index.md) -- full auto-generated documentation
- [Examples](examples.md) -- tutorial scripts and cookbook recipes
