gtfs_df 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7fd255d96a4b0990822cfe16cbbbeaa958b6b05f0df9fe149442ace3731034b
-  data.tar.gz: 98d5d680a0c2dd8bcec10168d8cb08639c25b90a830bfb65f597aa229bd2fd5c
+  metadata.gz: 0b218f60e33e005576eb278a74ba89e6164fddccfe99e9f8e5665d105d9fa471
+  data.tar.gz: cb4023192418d5ba89f08b605b2ec8ac79073b28d29f6161f252d97df3291dff
 SHA512:
-  metadata.gz: 72f6480afb171feffe387f02d069ee935e2373068099598b54789c6fe60982021a34d929b53e9509e0a478335f0a76fa2678cd2d71247e96a2c8394587f9f925
-  data.tar.gz: 4153e5271961917a7cff004795c239daea3c9b31069500b3c376295821d250ea5dd85fa848276a06a9881e544d14ffcd798371304eeb576a5c49042d0f615fc3
+  metadata.gz: cefa279582b0579a637e4ebc39fe4c3d90d56582aa1cd0d00ffda041b92f681831334d46aeae95dc1c291c1295758c500a0c7bfe32876f226605f5b150fc0a9c
+  data.tar.gz: e4b5bbe129674304121c61cb732a8261421158f206370289e67d3e6d514bbb089bc0c35f88fde6e46012a18afd3700b86eb4c2a2b457b9880270ef3a4f74cf79

data/.conform.yaml

@@ -23,3 +23,4 @@ policies:
                   - deps
                   - docs
                   - ci
+                  - qol

data/.ruby-version

@@ -0,0 +1 @@
+3.4.7

data/CHANGELOG.md

@@ -1,8 +1,36 @@
+## [0.7.0] - 2025-12-30
+
+### 🚀 Features
+
+- Add GTFS time parsing and formatting utilities
+- Option to parse time fields as seconds since midnight
+- Thread time columns through the input/output cycle
+- Allow modifying the parse_time flag after extraction
+- Provide a method to write to a directory
+
+### 💼 Other
+
+- Silence devenv version warning
+- Update example on release
+- Replace byebug with pry-byebug
+- Enable dependabot updates
+
+### 📚 Documentation
+
+- Update filter examples to use explicit hash syntax
+
+### ⚙️ Miscellaneous Tasks
+
+- Include the util helpers in the console and the test spec
 ## [0.6.2] - 2025-12-15
 
 ### 🐛 Bug Fixes
 
 - Permit non UTF-8 characters
+
+### ⚙️ Miscellaneous Tasks
+
+- Bump version to 0.6.2
 ## [0.6.1] - 2025-12-12
 
 ### 🐛 Bug Fixes

data/README.md

@@ -49,19 +49,19 @@ The library supports filtering feeds by any field in any table. The filter autom
 
 ```ruby
 # Filter by agency
-filtered_feed = feed.filter('agency' => { 'agency_id' => 'MTA' })
+filtered_feed = feed.filter({ 'agency' => { 'agency_id' => 'MTA' } })
 
 # Filter by route
-filtered_feed = feed.filter('routes' => { 'route_id' => ['1', '2', '3'] })
+filtered_feed = feed.filter({ 'routes' => { 'route_id' => ['1', '2', '3'] } })
 
 # Filter by a service
-filtered_feed = feed.filter('calendar' => { 'service_id' => 'WEEKDAY' })
+filtered_feed = feed.filter({ 'calendar' => { 'service_id' => 'WEEKDAY' } })
 
 # Multiple filters
-filtered_feed = feed.filter(
+filtered_feed = feed.filter({
   'agency' => { 'agency_id' => 'MTA' },
   'routes' => { 'route_type' => 1 } # Filter to subway routes
-)
+})
 ```
 
 When you filter by a field, the library automatically:

data/devenv.nix

@@ -1,9 +1,11 @@
-{ pkgs, lib, config, inputs, ... }:
+{ pkgs, ... }:
 
 {
+  devenv.warnOnNewVersion = false;
+
   languages.ruby = {
     enable = true;
-    version = "3.4.7";
+    versionFile = ./.ruby-version;
     bundler.enable = false;
   };
 

data/examples/split-by-agency/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    gtfs_df (0.1.1)
+    gtfs_df (0.7.0)
       networkx (~> 0.4)
       polars-df (~> 0.22)
       rubyzip (~> 2.3)

data/examples/split-by-agency/split_by_agency.rb

@@ -34,8 +34,12 @@ Whirly.configure spinner: "dots", stop: "✓"
 
 Whirly.start do
   Whirly.status = "Loading"
+
+  start_time = Time.now
   feed = GtfsDf::Reader.load_from_zip(input_path)
-  Whirly.status = "Loaded"
+  elapsed = Time.now - start_time
+
+  Whirly.status = "Loaded (#{elapsed.round(2)}s)"
 end
 
 agency_ids.each do |agency_id|
@@ -45,7 +49,7 @@ agency_ids.each do |agency_id|
     start_time = Time.now
 
     Whirly.status = "-> #{agency_id} filtering..."
-    filtered_feed = feed.filter("agency" => {"agency_id" => agency_id})
+    filtered_feed = feed.filter({"agency" => {"agency_id" => agency_id}})
 
     Whirly.status = "-> #{agency_id} writing..."
     GtfsDf::Writer.write_to_zip(filtered_feed, output_path)

data/lib/gtfs_df/base_gtfs_table.rb

@@ -36,6 +36,10 @@ module GtfsDf
       self.class::SCHEMA.keys
     end
 
+    def self.time_fields
+      const_defined?(:TIME_FIELDS) ? const_get(:TIME_FIELDS) : []
+    end
+
     def valid?
       @validator.valid?
     end

data/lib/gtfs_df/feed.rb

@@ -37,12 +37,17 @@ module GtfsDf
     ].freeze
 
     attr_accessor(*GTFS_FILES)
+    attr_accessor(:parse_times)
     attr_reader(:graph)
 
     # Initialize with a hash of DataFrames
     REQUIRED_GTFS_FILES = %w[agency stops routes trips stop_times].freeze
 
-    def initialize(data = {})
+    # @param data [Hash] Hash of DataFrames for each GTFS file
+    # @param parse_times [Boolean] Whether to parse time fields to seconds since midnight (default: false)
+    def initialize(data = {}, parse_times: false)
+      @parse_times = parse_times
+
       missing = REQUIRED_GTFS_FILES.reject { |file| data[file].is_a?(Polars::DataFrame) }
       # At least one of calendar or calendar_dates must be present
       unless data["calendar"].is_a?(Polars::DataFrame) || data["calendar_dates"].is_a?(Polars::DataFrame)
@@ -66,6 +71,19 @@ module GtfsDf
         end
         if df.is_a?(Polars::DataFrame) && schema_class && schema_class.const_defined?(:SCHEMA)
           df = schema_class.new(df).df
+          # Parse time fields if enabled and they're still strings
+          if @parse_times && schema_class.respond_to?(:time_fields)
+            time_fields = schema_class.time_fields
+            time_fields.each do |field|
+              next unless df.columns.include?(field)
+              # Only parse if the field is still a string (not already parsed)
+              if df[field].dtype == Polars::String
+                df = df.with_columns(
+                  GtfsDf::Utils.as_seconds_since_midnight(field)
+                )
+              end
+            end
+          end
         end
         instance_variable_set("@#{file}", df.is_a?(Polars::DataFrame) ? df : nil)
       end
@@ -127,7 +145,7 @@ module GtfsDf
 
         (!df || df.height == 0) && !is_required_file
       end
-      self.class.new(filtered)
+      self.class.new(filtered, parse_times: @parse_times)
     end
 
     private

data/lib/gtfs_df/reader.rb

@@ -3,7 +3,11 @@
 module GtfsDf
   class Reader
     # Loads a GTFS zip file and returns a Feed
-    def self.load_from_zip(zip_path)
+    #
+    # @param zip_path [String] Path to the GTFS zip file
+    # @param parse_times [Boolean] Whether to parse time fields to seconds since midnight (default: false)
+    # @return [Feed] The loaded GTFS feed
+    def self.load_from_zip(zip_path, parse_times: false)
       data = nil
 
       Dir.mktmpdir do |tmpdir|
@@ -15,14 +19,18 @@ module GtfsDf
           end
         end
 
-        data = load_from_dir(tmpdir)
+        data = load_from_dir(tmpdir, parse_times: parse_times)
       end
 
       data
     end
 
     # Loads a GTFS dir and returns a Feed
-    def self.load_from_dir(dir_path)
+    #
+    # @param dir_path [String] Path to the GTFS directory
+    # @param parse_times [Boolean] Whether to parse time fields to seconds since midnight (default: false)
+    # @return [Feed] The loaded GTFS feed
+    def self.load_from_dir(dir_path, parse_times: false)
       data = {}
       GtfsDf::Feed::GTFS_FILES.each do |gtfs_file|
         path = File.join(dir_path, "#{gtfs_file}.txt")
@@ -31,7 +39,7 @@ module GtfsDf
         data[gtfs_file] = data_frame(gtfs_file, path)
       end
 
-      GtfsDf::Feed.new(data)
+      GtfsDf::Feed.new(data, parse_times: parse_times)
     end
 
     private_class_method def self.data_frame(gtfs_file, path)

data/lib/gtfs_df/schema/frequencies.rb

@@ -17,6 +17,11 @@ module GtfsDf
         end_time
         headway_secs
       ].freeze
+
+      TIME_FIELDS = %w[
+        start_time
+        end_time
+      ].freeze
     end
   end
 end

data/lib/gtfs_df/schema/stop_times.rb

@@ -26,6 +26,13 @@ module GtfsDf
 
       REQUIRED_FIELDS = %w[trip_id stop_sequence stop_id]
 
+      TIME_FIELDS = %w[
+        arrival_time
+        departure_time
+        start_pickup_drop_off_window
+        end_pickup_drop_off_window
+      ].freeze
+
       ENUM_VALUE_MAP = {
         "pickup_type" => :PICKUP_TYPE,
         "drop_off_type" => :DROP_OFF_TYPE,

data/lib/gtfs_df/utils.rb

@@ -1,6 +1,12 @@
 module GtfsDf
   module Utils
-    # Parses a GTFS time string
+    extend self
+
+    SECONDS_IN_MINUTE = 60
+    SECONDS_IN_HOUR = SECONDS_IN_MINUTE * 60
+    SECONDS_IN_DAY = SECONDS_IN_HOUR * 24
+
+    # Parses a GTFS time string to seconds since midnight
     #
     # The input string is expected to be in the HH:MM:SS format (H:MM:SS is
     # also accepted).
@@ -13,10 +19,9 @@ module GtfsDf
     # @example 14:30:00 for 2:30PM or
     # 25:35:00 for 1:35AM on the next day.
     #
-    # @param str String
-    # Parses a GTFS time string or returns integer seconds if already provided.
-    # Accepts Integer (returns as-is), or HH:MM:SS string (possibly >24h).
-    def self.parse_time(str)
+    # @param str String|Integer
+    # @return Integer|nil seconds since midnight, or nil if invalid
+    def parse_time(str)
       return str if str.is_a?(Integer)
       return nil if str.nil? || (str.respond_to?(:strip) && str.strip.empty?)
 
@@ -29,6 +34,82 @@ module GtfsDf
       nil
     end
 
+    # Formats seconds since midnight as a GTFS time string (HH:MM:SS)
+    #
+    # Handles times greater than 24 hours for times that span past midnight.
+    #
+    # @param seconds Integer seconds since midnight
+    # @return String|nil time in HH:MM:SS format, or nil if invalid
+    def format_time(seconds)
+      return nil if seconds.nil?
+      return seconds if seconds.is_a?(String)
+
+      hours = seconds / SECONDS_IN_HOUR
+      minutes = (seconds % SECONDS_IN_HOUR) / SECONDS_IN_MINUTE
+      secs = seconds % SECONDS_IN_MINUTE
+
+      format("%02d:%02d:%02d", hours, minutes, secs)
+    rescue
+      nil
+    end
+
+    # Converts a GTFS time string column to seconds since midnight
+    #
+    # Use this method with Polars DataFrames to convert time columns.
+    #
+    # @example dataframe.with_columns(GtfsDf::Utils.as_seconds_since_midnight('start_time'))
+    #
+    # @param col_name String The column to convert
+    # @return Polars::Expr
+    def as_seconds_since_midnight(col_name)
+      parts = Polars.col(col_name).str.split(":")
+
+      hours = parts.list.get(0).cast(:i64)
+      minutes = parts.list.get(1).cast(:i64)
+      seconds = parts.list.get(2).cast(:i64)
+
+      (hours * SECONDS_IN_HOUR) +
+        (minutes * SECONDS_IN_MINUTE) +
+        seconds
+    end
+
+    # Converts a seconds since midnight column to GTFS time string (HH:MM:SS)
+    #
+    # Use this method with Polars DataFrames to convert time columns back to strings.
+    #
+    # @example dataframe.with_columns(GtfsDf::Utils.as_time_string('start_time'))
+    #
+    # @param col_name String The column to convert
+    # @return Polars::Expr
+    def as_time_string(col_name)
+      total_seconds = Polars.col(col_name)
+      hours = total_seconds.floordiv(SECONDS_IN_HOUR)
+      minutes = (total_seconds % SECONDS_IN_HOUR).floordiv(SECONDS_IN_MINUTE)
+      seconds = total_seconds % SECONDS_IN_MINUTE
+
+      Polars.format(
+        "{}:{}:{}",
+        hours.cast(:str).str.zfill(2),
+        minutes.cast(:str).str.zfill(2),
+        seconds.cast(:str).str.zfill(2)
+      )
+    end
+
+    # Converts a seconds since midnight Series to GTFS time strings for inspection
+    #
+    # Use this method to get a readable view of time columns during debugging.
+    # It's not meant to be performant.
+    #
+    # @example GtfsDf::Utils.inspect_time(feed.stop_times["arrival_time"])
+    #
+    # @param series Polars::Series The series to convert
+    # @return Polars::Series A series with time strings
+    def inspect_time(series)
+      series.to_frame.with_columns(
+        as_time_string(series.name)
+      )[series.name]
+    end
+
     # Parses a GTFS date string
     #
     # The input string is expected to be a service day in the YYYYMMDD format.
@@ -38,7 +119,7 @@ module GtfsDf
     # @example 20180913 for September 13th, 2018.
     #
     # @param str String
-    def self.parse_date(str)
+    def parse_date(str)
       return nil if str.nil? || str.strip.empty?
       return nil unless str.match?(/^\d{8}$/)
 

data/lib/gtfs_df/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GtfsDf
-  VERSION = "0.6.2"
+  VERSION = "0.7.0"
 end

data/lib/gtfs_df/writer.rb

@@ -3,6 +3,9 @@
 module GtfsDf
   class Writer
     # Exports a Feed to a GTFS zip file
+    #
+    # @param feed [Feed] The GTFS feed to export
+    # @param zip_path [String] The path where the zip file will be created
     def self.write_to_zip(feed, zip_path)
       require "stringio"
       require "zlib"
@@ -12,6 +15,11 @@ module GtfsDf
           df = feed.send(file)
           next unless df.is_a?(Polars::DataFrame)
 
+          # Convert time fields back to strings if parse_times was enabled
+          if feed.parse_times
+            df = format_time_fields(file, df)
+          end
+
           # Write CSV to StringIO
           csv_io = StringIO.new
           df.write_csv(csv_io)
@@ -22,5 +30,47 @@ module GtfsDf
         end
       end
     end
+
+    # Exports a Feed to a directory as individual text files
+    #
+    # @param feed [Feed] The GTFS feed to export
+    # @param dir_path [String] The path where the directory will be created
+    def self.write_to_dir(feed, dir_path)
+      FileUtils.mkdir_p(dir_path)
+      GtfsDf::Feed::GTFS_FILES.each do |file|
+        df = feed.send(file)
+        next unless df.is_a?(Polars::DataFrame)
+
+        # Convert time fields back to strings if parse_times was enabled
+        df = format_time_fields(file, df) if feed.parse_times
+
+        # Write CSV directly to file
+        df.write_csv(File.join(dir_path, "#{file}.txt"))
+      end
+    end
+
+    # Formats time fields back to HH:MM:SS strings for a given GTFS file
+    #
+    # @param file [String] The GTFS file name (e.g., "stop_times")
+    # @param df [Polars::DataFrame] The DataFrame to format
+    # @return [Polars::DataFrame] DataFrame with time fields formatted as strings
+    def self.format_time_fields(file, df)
+      schema_class_name = file.split("_").map(&:capitalize).join
+      schema_class = begin
+        GtfsDf::Schema.const_get(schema_class_name)
+      rescue
+        nil
+      end
+
+      return df unless schema_class&.respond_to?(:time_fields)
+
+      time_fields = schema_class.time_fields
+      time_fields.each do |field|
+        next unless df.columns.include?(field)
+        df = df.with_columns(GtfsDf::Utils.as_time_string(field))
+      end
+
+      df
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gtfs_df
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - David Mejorado
@@ -65,6 +65,7 @@ files:
 - ".envrc"
 - ".rspec"
 - ".rubocop.yml"
+- ".ruby-version"
 - ".solargraph.yml"
 - ".standard.yml"
 - CHANGELOG.md