0
# Feed Operations
1

2
Core functionality for loading, manipulating, and exporting GTFS feeds. This module provides the primary interface for working with GTFS data through the `Feed` class and related functions.
3

4
## Core Functions
5

6
### Reading GTFS Feeds
7

8
```python { .api }
9
def read_feed(path_or_url, dist_units='km'):
10
    """
11
    Read a GTFS feed from a file path or URL.
12
    
13
    Parameters:
14
    - path_or_url (str or Path): Path to GTFS zip file, directory, or URL
15
    - dist_units (str): Distance units for the feed ('ft', 'mi', 'm', 'km')
16
    
17
    Returns:
18
    - Feed: GTFS Feed object
19
    """
20
```
21

22
```python
23
import gtfs_kit as gk
24

25
# Read from local file
26
feed = gk.read_feed('gtfs.zip', dist_units='km')
27

28
# Read from URL
29
feed = gk.read_feed('https://example.com/gtfs.zip', dist_units='mi')
30

31
# Read from directory
32
feed = gk.read_feed('/path/to/gtfs/directory', dist_units='m')
33
```
34

35
### Feed Inspection
36

37
```python { .api }
38
def list_feed(path):
39
    """
40
    List the contents of a GTFS feed file or directory.
41
    
42
    Parameters:
43
    - path (str or Path): Path to GTFS zip file or directory
44
    
45
    Returns:
46
    - DataFrame: DataFrame with columns 'file_name' and 'file_size'
47
    """
48
```
49

50
```python
51
# Check what files are in a GTFS feed before loading
52
file_info = gk.list_feed('gtfs.zip')
53
print(file_info)  # DataFrame with file_name and file_size columns
54
```
55

56
## Feed Class
57

58
The `Feed` class is the primary interface for all GTFS operations. It contains all GTFS tables as DataFrame attributes and provides methods for feed manipulation.
59

60
```python { .api }
61
class Feed:
62
    """
63
    Main GTFS feed class for loading and manipulating transit data.
64
    
65
    Attributes (all pandas.DataFrame):
66
    - agency: Transit agency information
67
    - stops: Stop/station information  
68
    - routes: Route information
69
    - trips: Individual trip information
70
    - stop_times: Stop time schedules for trips
71
    - calendar: Service calendar information
72
    - calendar_dates: Service calendar date exceptions
73
    - fare_attributes: Fare information (optional)
74
    - fare_rules: Fare rules (optional)
75
    - shapes: Shape/path information (optional)
76
    - frequencies: Trip frequency information (optional)
77
    - transfers: Transfer information (optional)
78
    - feed_info: Feed metadata (optional)
79
    - attributions: Data attributions (optional)
80
    - dist_units (str): Distance units for the feed
81
    """
82
    
83
    def __init__(self, dist_units, agency=None, stops=None, routes=None, 
84
                 trips=None, stop_times=None, calendar=None, calendar_dates=None, 
85
                 fare_attributes=None, fare_rules=None, shapes=None, frequencies=None, 
86
                 transfers=None, feed_info=None, attributions=None):
87
        """
88
        Initialize a GTFS Feed object.
89
        
90
        Parameters:
91
        - dist_units (str): Distance units for the feed ('ft', 'mi', 'm', 'km')
92
        - agency (DataFrame, optional): Transit agency information
93
        - stops (DataFrame, optional): Stop/station information
94
        - routes (DataFrame, optional): Route information
95
        - trips (DataFrame, optional): Individual trip information
96
        - stop_times (DataFrame, optional): Stop time schedules
97
        - calendar (DataFrame, optional): Service calendar information
98
        - calendar_dates (DataFrame, optional): Calendar date exceptions
99
        - fare_attributes (DataFrame, optional): Fare information
100
        - fare_rules (DataFrame, optional): Fare rules
101
        - shapes (DataFrame, optional): Shape/path information
102
        - frequencies (DataFrame, optional): Trip frequency information
103
        - transfers (DataFrame, optional): Transfer information
104
        - feed_info (DataFrame, optional): Feed metadata
105
        - attributions (DataFrame, optional): Data attributions
106
        """
107
    
108
    @property
109
    def dist_units(self):
110
        """Distance units property getter."""
111
    
112
    @dist_units.setter
113
    def dist_units(self, value):
114
        """Distance units property setter."""
115
        
116
    def __str__(self):
117
        """String representation of the Feed object."""
118
        
119
    def __eq__(self, other):
120
        """Equality comparison between Feed objects."""
121
```
122

123
### Feed Instance Methods
124

125
```python { .api }
126
def copy(self):
127
    """
128
    Create a deep copy of the feed.
129
    
130
    Returns:
131
    - Feed: Deep copy of the feed object
132
    """
133

134
def to_file(self, path, ndigits=None):
135
    """
136
    Write the feed to a file or ZIP archive.
137
    
138
    Parameters:
139
    - path (str or Path): Output file path (zip extension creates ZIP archive)
140
    - ndigits (int, optional): Number of decimal places for coordinate precision
141
    """
142
```
143

144
### Working with Feed Objects
145

146
```python
147
import gtfs_kit as gk
148

149
# Load a feed
150
feed = gk.read_feed('gtfs.zip', dist_units='km')
151

152
# Access GTFS tables as DataFrames
153
print(feed.agency)
154
print(feed.routes.head())
155
print(feed.stops.head())
156

157
# Check feed attributes
158
print(f"Distance units: {feed.dist_units}")
159
print(f"Number of routes: {len(feed.routes)}")
160
print(f"Number of stops: {len(feed.stops)}")
161

162
# Copy the feed
163
feed_copy = feed.copy()
164

165
# Save feed to file
166
feed.to_file('output.zip')  # Save as ZIP
167
feed.to_file('output_dir')  # Save as directory
168
feed.to_file('output.zip', ndigits=6)  # Control coordinate precision
169
```
170

171
## Feed Data Access
172

173
All functions from other modules are available as methods on `Feed` instances, providing two equivalent ways to work with the data:
174

175
```python
176
# As standalone functions
177
routes = gk.get_routes(feed, date='20230101')
178
stops = gk.get_stops(feed, as_gdf=True)
179

180
# As feed methods  
181
routes = feed.get_routes(date='20230101')
182
stops = feed.get_stops(as_gdf=True)
183
```
184

185
## Integration with Other Capabilities
186

187
The `Feed` class serves as the foundation for all other GTFS Kit capabilities:
188

189
- **Data Analysis**: All statistical and time series functions operate on `Feed` objects
190
- **Geospatial Operations**: Geometric and mapping functions work with feed data
191
- **Data Processing**: Cleaning and transformation functions modify feed data in-place
192
- **Utilities**: Helper functions support feed data manipulation and analysis
193

194
This design provides a consistent interface while allowing both functional and object-oriented programming styles depending on your preferences.