# Examples

Self-contained tutorial scripts that demonstrate all library functionality. Each example uses small generated data (no external files) and can be run from the project root.

## How to run

```bash
uv run python examples/01_getting_started.py
```

Or with a regular Python environment where walkingpandas is installed:

```bash
python examples/01_getting_started.py
```

## Tutorial scripts

| Script | Description | Main concepts |
|--------|-------------|---------------|
| `01_getting_started.py` | Minimal Network + WalkFrame + `compute()` | Lazy evaluation, `.compute()`, `nodes=`/`edges=`, `.network` |
| `02_network_creation.py` | Build networks from different sources | Parquet, GeoDataFrames, `from_gdfs`, `from_networkx`, `from_walks` |
| `03_walkframe_basics.py` | Filter, limit, export | `.filter()`, `.limit()`, `.to_pandas()`, `.to_geopandas()` |
| `04_graph_validation.py` | Simple paths, cycles, complex walks | `only_simple_paths()`, `only_cycles()`, `only_complex_walks()` |
| `05_spatial_filtering.py` | Spatial filters on walks | `passing_through`, `within_bounds`, `intersecting`, `near_point` |
| `06_temporal_queries.py` | Time-based filtering and traffic | `filter(time_range=...)`, `edge_traffic_at(time)` |
| `07_aggregations.py` | Counts and lengths | `edge_frequencies()`, `node_frequencies()`, `walk_lengths()` |
| `08_ingestion_io.py` | Schema validation and writing | `validate_schema`, `convert_to_superset_format`, `write_walks` |
| `09_persistence.py` | Save/load Network, single-file DuckDB | `Network.save/load`, `connect()`, `write_duckdb` |
| `10_data_quality.py` | Orphan detection | `get_orphaned_records()` |
| `11_full_workflow.py` | End-to-end pipeline | Create data, write Parquet, load, chain queries, save .duckdb |

## Cookbook recipes

### Find the busiest edges

```python
import walkingpandas as wp

walks = wp.read_dataset(nodes, edges, walks)
busy_edges = (
    walks
    .filter(time_range=("08:00", "09:00"))
    .edge_frequencies()
    .compute()
)
top_edges = busy_edges.nlargest(10, "traffic_count")
```

### Analyze cycles

```python
cycles = (
    walks
    .only_cycles()
    .walk_lengths()
    .compute()
)
avg_cycle_length = cycles["length"].mean()
```

### Most popular nodes

```python
popular = walks.node_frequencies().compute()
popular.nlargest(5, "traffic_count")
```

### Spatial analysis (when nodes have geometry)

```python
from shapely.geometry import Polygon

area = Polygon([(0, 0), (1, 0), (1, 1), (0, 1)])
intersecting_walks = (
    walks
    .intersecting(area)
    .node_frequencies()
    .compute()
)
```
