or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

data-analysis.mddata-processing.mdfeed-operations.mdgeospatial.mdindex.mdutilities.md
tile.json

geospatial.mddocs/

Geospatial Operations

Geometric processing, spatial analysis, and interactive mapping capabilities. This module supports conversion between DataFrame and GeoDataFrame formats, spatial operations, and creation of interactive maps using Folium.

Data Access with Geometry

Routes with Geometry

def get_routes(feed, date=None, time=None, *, as_gdf=False, use_utm=False, split_directions=False):
    """
    Get routes DataFrame or GeoDataFrame with optional geometry.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - date (str, optional): Filter by service date (YYYYMMDD)
    - time (str, optional): Filter by active time (HH:MM:SS)
    - as_gdf (bool): Return as GeoDataFrame with geometry
    - use_utm (bool): Use UTM projection for geometry
    - split_directions (bool): Split routes by direction
    
    Returns:
    - DataFrame or GeoDataFrame: Routes data with optional geometry
    """

Stops with Geometry

def get_stops(feed, date=None, trip_ids=None, route_ids=None, *, in_stations=False, as_gdf=False, use_utm=False):
    """
    Get stops DataFrame or GeoDataFrame with optional geometry.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - date (str, optional): Filter by service date (YYYYMMDD)
    - trip_ids (list, optional): Filter by trip IDs
    - route_ids (list, optional): Filter by route IDs
    - in_stations (bool): Include stops within stations
    - as_gdf (bool): Return as GeoDataFrame with geometry
    - use_utm (bool): Use UTM projection for geometry
    
    Returns:
    - DataFrame or GeoDataFrame: Stops data with optional geometry
    """

def geometrize_stops(stops, *, use_utm=False):
    """
    Convert stops DataFrame to GeoDataFrame.
    
    Parameters:
    - stops (DataFrame): Stops DataFrame
    - use_utm (bool): Use UTM projection
    
    Returns:
    - GeoDataFrame: Stops with Point geometry
    """

def ungeometrize_stops(stops_g):
    """
    Convert stops GeoDataFrame back to DataFrame.
    
    Parameters:
    - stops_g (GeoDataFrame): Stops GeoDataFrame
    
    Returns:
    - DataFrame: Stops DataFrame without geometry
    """

Shapes with Geometry

def get_shapes(feed, *, as_gdf=False, use_utm=False):
    """
    Get shapes DataFrame or GeoDataFrame with optional geometry.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - as_gdf (bool): Return as GeoDataFrame with geometry
    - use_utm (bool): Use UTM projection for geometry
    
    Returns:
    - DataFrame or GeoDataFrame: Shapes data with optional geometry
    """

def geometrize_shapes(shapes, *, use_utm=False):
    """
    Convert shapes DataFrame to GeoDataFrame with LineString geometry.
    
    Parameters:
    - shapes (DataFrame): Shapes DataFrame
    - use_utm (bool): Use UTM projection
    
    Returns:
    - GeoDataFrame: Shapes with LineString geometry
    """

def ungeometrize_shapes(shapes_g):
    """
    Convert shapes GeoDataFrame back to DataFrame.
    
    Parameters:
    - shapes_g (GeoDataFrame): Shapes GeoDataFrame
    
    Returns:
    - DataFrame: Shapes DataFrame without geometry
    """

def append_dist_to_shapes(feed):
    """
    Calculate and append shape_dist_traveled field to shapes.
    
    Parameters:
    - feed (Feed): GTFS feed object (modified in-place)
    
    Returns:
    - Feed: Feed with updated shapes
    """

Trips with Geometry

def get_trips(feed, date=None, time=None, *, as_gdf=False, use_utm=False):
    """
    Get trips DataFrame or GeoDataFrame with optional geometry.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - date (str, optional): Filter by service date (YYYYMMDD)
    - time (str, optional): Filter by active time (HH:MM:SS)
    - as_gdf (bool): Return as GeoDataFrame with geometry
    - use_utm (bool): Use UTM projection for geometry
    
    Returns:
    - DataFrame or GeoDataFrame: Trips data with optional geometry
    """

Stop Times with Geometry

def get_stop_times(feed, date=None):
    """
    Get stop times DataFrame, optionally filtered by date.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - date (str, optional): Filter by service date (YYYYMMDD)
    
    Returns:
    - DataFrame: Stop times data
    """

def append_dist_to_stop_times(feed):
    """
    Calculate and append shape_dist_traveled to stop_times.
    
    Parameters:
    - feed (Feed): GTFS feed object (modified in-place)
    
    Returns:
    - Feed: Feed with updated stop_times
    """

def get_start_and_end_times(feed, date=None):
    """
    Get earliest and latest times in stop_times.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - date (str, optional): Filter by service date
    
    Returns:
    - list: [start_time, end_time] in HH:MM:SS format
    """

Spatial Analysis

Geometric Utilities

def build_geometry_by_shape(feed, shape_ids=None, *, use_utm=False):
    """
    Build dictionary mapping shape IDs to geometry objects.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - shape_ids (list, optional): Specific shape IDs to process
    - use_utm (bool): Use UTM projection
    
    Returns:
    - dict: Shape ID to geometry mapping
    """

def build_geometry_by_stop(feed, stop_ids=None, *, use_utm=False):
    """
    Build dictionary mapping stop IDs to geometry objects.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - stop_ids (list, optional): Specific stop IDs to process
    - use_utm (bool): Use UTM projection
    
    Returns:
    - dict: Stop ID to geometry mapping
    """

def split_simple(shapes_g, segmentize_m=5):
    """
    Split non-simple LineStrings into simple sub-LineStrings.
    
    Parameters:
    - shapes_g (GeoDataFrame): Shapes GeoDataFrame
    - segmentize_m (float): Segmentization distance in meters
    
    Returns:
    - GeoDataFrame: Shapes with simple LineStrings
    """

Spatial Queries

def get_shapes_intersecting_geometry(feed, geometry, shapes_g=None, *, as_gdf=False):
    """
    Get shapes that intersect with a given geometry.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - geometry: Shapely geometry object
    - shapes_g (GeoDataFrame, optional): Pre-computed shapes GeoDataFrame
    - as_gdf (bool): Return as GeoDataFrame
    
    Returns:
    - DataFrame or GeoDataFrame: Intersecting shapes
    """

def get_stops_in_area(feed, area):
    """
    Get stops within a given area (GeoDataFrame).
    
    Parameters:
    - feed (Feed): GTFS feed object
    - area (GeoDataFrame): Area geometry to query within
    
    Returns:
    - DataFrame: Stops within the specified area
    """

def compute_bounds(feed, stop_ids=None):
    """
    Compute bounding box of stops.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - stop_ids (list, optional): Specific stop IDs to bound
    
    Returns:
    - ndarray: Bounding box coordinates [min_lon, min_lat, max_lon, max_lat]
    """

def compute_convex_hull(feed, stop_ids=None):
    """
    Compute convex hull of stops.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - stop_ids (list, optional): Specific stop IDs to hull
    
    Returns:
    - Polygon: Shapely Polygon representing convex hull
    """

def compute_centroid(feed, stop_ids=None):
    """
    Compute centroid of stops.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - stop_ids (list, optional): Specific stop IDs to center
    
    Returns:
    - Point: Shapely Point representing centroid
    """

def compute_screen_line_counts(feed, screen_lines, dates, segmentize_m=5, *, include_testing_cols=False):
    """
    Count transit trips crossing screen lines.
    
    Parameters:
    - feed (Feed): GTFS feed object  
    - screen_lines: Screen line geometries
    - dates (list): List of dates to analyze
    - segmentize_m (float): Segmentization distance in meters
    - include_testing_cols (bool): Include debugging columns
    
    Returns:
    - DataFrame: Screen line crossing counts
    """

def get_stops_in_area(feed, area): """ Get stops within a polygon area.

Parameters:
- feed (Feed): GTFS feed object
- area: Shapely Polygon or MultiPolygon

Returns:
- DataFrame: Stops within the area
"""
### Geometric Calculations

```python { .api }
def compute_bounds(feed, stop_ids=None):
    """
    Compute bounding box of stops.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - stop_ids (list, optional): Specific stop IDs
    
    Returns:
    - tuple: (min_lon, min_lat, max_lon, max_lat)
    """

def compute_convex_hull(feed, stop_ids=None):
    """
    Compute convex hull of stops.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - stop_ids (list, optional): Specific stop IDs
    
    Returns:
    - Polygon: Convex hull geometry
    """

def compute_centroid(feed, stop_ids=None):
    """
    Compute centroid of stops.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - stop_ids (list, optional): Specific stop IDs
    
    Returns:
    - Point: Centroid geometry
    """

Data Export

GeoJSON Export

def routes_to_geojson(feed, route_ids=None, *, split_directions=False, include_stops=False):
    """
    Convert routes to GeoJSON format.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - route_ids (list, optional): Specific route IDs to export
    - split_directions (bool): Split routes by direction
    - include_stops (bool): Include stop points in output
    
    Returns:
    - dict: GeoJSON FeatureCollection
    """

def stops_to_geojson(feed, stop_ids=None):
    """
    Convert stops to GeoJSON format.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - stop_ids (list, optional): Specific stop IDs to export
    
    Returns:
    - dict: GeoJSON FeatureCollection
    """

def shapes_to_geojson(feed, shape_ids=None):
    """
    Convert shapes to GeoJSON format.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - shape_ids (list, optional): Specific shape IDs to export
    
    Returns:
    - dict: GeoJSON FeatureCollection
    """

def trips_to_geojson(feed, trip_ids=None, *, include_stops=False):
    """
    Convert trips to GeoJSON format.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - trip_ids (list, optional): Specific trip IDs to export
    - include_stops (bool): Include stop points in output
    
    Returns:
    - dict: GeoJSON FeatureCollection
    """

def stop_times_to_geojson(feed, trip_ids=None):
    """
    Convert stop times to GeoJSON points.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - trip_ids (list, optional): Specific trip IDs to export
    
    Returns:
    - dict: GeoJSON FeatureCollection
    """

Interactive Mapping

Route Mapping

def map_routes(feed, route_ids=None, route_short_names=None, color_palette=COLORS_SET2, *, show_stops=False):
    """
    Create Folium map displaying routes.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - route_ids (list, optional): Specific route IDs to display
    - route_short_names (list, optional): Route short names to display
    - color_palette (list): Colors for route visualization
    - show_stops (bool): Include stops on the map
    
    Returns:
    - folium.Map: Interactive map with routes
    """

Stop Mapping

def map_stops(feed, stop_ids, stop_style=STOP_STYLE):
    """
    Create Folium map displaying stops.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - stop_ids (list): Stop IDs to display
    - stop_style (dict): Leaflet circleMarker style parameters
    
    Returns:
    - folium.Map: Interactive map with stops
    """

def map_trips(feed, trip_ids, color_palette=COLORS_SET2, *, show_stops=False, show_direction=False):
    """
    Create Folium map displaying trips.
    
    Parameters:
    - feed (Feed): GTFS feed object
    - trip_ids (list): Trip IDs to display  
    - color_palette (list): Colors for trip visualization
    - show_stops (bool): Include stops on the map
    - show_direction (bool): Show trip direction arrows
    
    Returns:
    - folium.Map: Interactive map with trips
    """

These mapping functions create interactive Folium maps for visualizing GTFS data with customizable styling and display options.

Usage Examples

Basic Geospatial Operations

import gtfs_kit as gk

# Load feed
feed = gk.read_feed('gtfs.zip', dist_units='km')

# Get routes as GeoDataFrame
routes_gdf = gk.get_routes(feed, as_gdf=True)

# Get stops with UTM projection
stops_gdf = gk.get_stops(feed, as_gdf=True, use_utm=True)

# Get shapes with geometry
shapes_gdf = gk.get_shapes(feed, as_gdf=True)

Spatial Analysis

# Compute feed boundaries
bounds = gk.compute_bounds(feed)
hull = gk.compute_convex_hull(feed)
center = gk.compute_centroid(feed)

# Find shapes intersecting an area
from shapely.geometry import Polygon
area = Polygon([(lon1, lat1), (lon2, lat2), (lon3, lat3), (lon4, lat4)])
intersecting_shapes = gk.get_shapes_intersecting_geometry(feed, area, as_gdf=True)

# Get stops in area
stops_in_area = gk.get_stops_in_area(feed, area)

Export and Visualization

# Export to GeoJSON
routes_geojson = gk.routes_to_geojson(feed, split_directions=True)
stops_geojson = gk.stops_to_geojson(feed)

# Create interactive maps
route_map = gk.map_routes(feed, route_ids=['route_1', 'route_2'], show_stops=True)
stop_map = gk.map_stops(feed, stop_ids=['stop_1', 'stop_2'])

# Save maps to HTML
route_map.save('routes.html')
stop_map.save('stops.html')

The geospatial capabilities enable comprehensive spatial analysis and visualization of transit networks, supporting both analytical workflows and interactive exploration of GTFS data.