tidyfaf 0.1.0

A statistical data access tool for the Freight Analysis Framework (FAF5).

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

pip install tidyfaf

Usage

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

Retrieve data directly as DataFrames.

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.

# 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