# tidyfaf

**tidyfaf** is a Python package that provides a "tidy", statistical data access API for the Freight Analysis Framework (FAF5) dataset. Inspired by `tidycensus`, it allows users to easily retrieve freight flow data and network geometries as pandas DataFrames and GeoDataFrames without dealing with complex file parsing or class instantiation.

## Installation

```bash
pip install tidyfaf
```

## Usage

### 1. Statistical Data Access (The "Flat" API)

Retrieve data directly as DataFrames.

```python
import tidyfaf as faf

# Search for metadata codes
zones = faf.search_zone("Washington")
print(zones)
# Get the ID for DC (e.g., 111)
dc_id = 111

# Get Flow Data (DataFrame)
df = faf.get_flows(destination_zone=dc_id, commodity="Pharmaceuticals")
print(df.head())

# Get Network Data (GeoDataFrame)
net = faf.get_network(state="DC")
net.plot()
```

### 2. Visualization

Visualization is decoupled from data access. You can retrieve geometries and use the built-in `FlowMap` or your own tools.

```python
# Get data with geometry
gdf = faf.get_flows(destination_zone=dc_id, geometry=True)

# Create an interactive map
from tidyfaf.visualization import FlowMap
FlowMap(gdf).generate_map("flows.html")
```

## Features

*   **Data-First Design**: Functions return `pandas.DataFrame` or `geopandas.GeoDataFrame`.
*   **Metadata Helpers**: Easily look up FAF Zones, Commodities, Modes, and States.
*   **Network Support**: Retrieve highway network links filtered by state or route.
*   **Built-in Visualization**: Quickly generate interactive Deck.gl maps for flow data.

## License

MIT License
