Metadata-Version: 2.4
Name: tidyfaf
Version: 0.1.0
Summary: A statistical data access tool for the Freight Analysis Framework (FAF5).
Author-email: FreightPulse Team <dmpandit@umd.edu>
License: MIT License
Project-URL: Homepage, https://github.com/freightpulse/tidyfaf
Project-URL: Bug Tracker, https://github.com/freightpulse/tidyfaf/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5.0
Requires-Dist: geopandas>=0.12.0
Requires-Dist: pyarrow>=10.0.0
Requires-Dist: pydeck>=0.8.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: seaborn>=0.12.0
Requires-Dist: pyogrio>=0.4.0
Requires-Dist: openpyxl>=3.0.0
Dynamic: license-file

# 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
