gtfs_df 0.1.1

data/lib/gtfs_df/feed.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  class Feed
+    GTFS_FILES = %w[
+      agency
+      stops
+      routes
+      trips
+      stop_times
+      calendar
+      calendar_dates
+      pathways
+      levels
+      feed_info
+      shapes
+      frequencies
+      transfers
+      fare_attributes
+      fare_rules
+      attributions
+      translations
+      stop_areas
+      stop_attributes
+      rider_categories
+      fare_media
+      fare_products
+      fare_leg_rules
+      fare_leg_join_rules
+      fare_transfer_rules
+      areas
+      networks
+      route_networks
+      location_groups
+      location_group_stops
+      booking_rules
+    ].freeze
+
+    attr_reader(*GTFS_FILES)
+
+    # Initialize with a hash of DataFrames
+    REQUIRED_GTFS_FILES = %w[agency stops routes trips stop_times].freeze
+
+    def initialize(data = {})
+      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)
+        missing << "calendar.txt or calendar_dates.txt"
+      end
+      unless missing.empty?
+        raise GtfsDf::Error, "Missing required GTFS files: #{missing.map do |f|
+          f.end_with?(".txt") ? f : f + ".txt"
+        end.join(", ")}"
+      end
+
+      GTFS_FILES.each do |file|
+        df = data[file]
+        schema_class_name = file.split("_").map(&:capitalize).join
+        schema_class = begin
+          GtfsDf::Schema.const_get(schema_class_name)
+        rescue
+          nil
+        end
+        if df.is_a?(Polars::DataFrame) && schema_class && schema_class.const_defined?(:SCHEMA)
+          df = schema_class.new(df).df
+        end
+        instance_variable_set("@#{file}", df.is_a?(Polars::DataFrame) ? df : nil)
+      end
+    end
+
+    # Load from a directory of GTFS CSV files
+    def self.load_from_dir(dir)
+      data = {}
+      GTFS_FILES.each do |file|
+        path = File.join(dir, "#{file}.txt")
+        next unless File.exist?(path)
+
+        schema_class_name = file.split("_").map(&:capitalize).join
+
+        data[file] = GtfsDf::Schema.const_get(schema_class_name).new(path)
+      end
+      new(data)
+    end
+
+    # Filter the feed using a view hash
+    # Example view: { 'routes' => { 'route_id' => '123' }, 'trips' => { 'service_id' => 'A' } }
+    def filter(view)
+      filtered = {}
+      graph = GtfsDf::Graph.build
+      # Step 1: Apply view filters
+      GTFS_FILES.each do |file|
+        df = send(file)
+        next unless df
+
+        filters = view[file]
+        if filters && !filters.empty?
+          filters.each do |col, val|
+            df = if val.is_a?(Array)
+              df.filter(Polars.col(col).is_in(val))
+            elsif val.respond_to?(:call)
+              df.filter(val.call(Polars.col(col)))
+            else
+              df.filter(Polars.col(col).eq(val))
+            end
+          end
+        end
+        filtered[file] = df
+      end
+      # Step 2: Cascade filters following the directed edges
+      # An edge from parent->child means: filter child based on valid parent IDs
+      changed = true
+      while changed
+        changed = false
+        GTFS_FILES.each do |parent_file|
+          parent_df = filtered[parent_file]
+          next unless parent_df && parent_df.height > 0
+
+          # For each outgoing edge from parent_file to child_file
+          graph.adj[parent_file]&.each do |child_file, attrs|
+            child_df = filtered[child_file]
+            next unless child_df && child_df.height > 0
+
+            attrs[:dependencies].each do |dep|
+              parent_col = dep[parent_file]
+              child_col = dep[child_file]
+
+              next unless parent_col && child_col &&
+                parent_df.columns.include?(parent_col) && child_df.columns.include?(child_col)
+
+              # Get valid values from parent
+              valid_values = parent_df[parent_col].to_a.uniq.compact
+              next if valid_values.empty?
+
+              # Filter child to only include rows that reference valid parent values
+              before = child_df.height
+              child_df = child_df.filter(Polars.col(child_col).is_in(valid_values))
+
+              if child_df.height < before
+                filtered[child_file] = child_df
+                changed = true
+              end
+            end
+          end
+        end
+      end
+
+      # Remove files that are empty, but keep required files even if empty
+      filtered.delete_if { |file, df| (!df || df.height == 0) && !REQUIRED_GTFS_FILES.include?(file) }
+      self.class.new(filtered)
+    end
+  end
+end

data/lib/gtfs_df/graph.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  class Graph
+    # Returns a directed graph of GTFS file dependencies
+    def self.build
+      g = NetworkX::DiGraph.new
+      # Nodes: GTFS files
+      files = %w[
+        agency routes trips stop_times stops calendar calendar_dates shapes transfers frequencies fare_attributes fare_rules
+        fare_leg_join_rules fare_transfer_rules areas networks route_networks location_groups location_group_stops booking_rules
+      ]
+      files.each { |f| g.add_node(f) }
+
+      # Edges: dependencies
+      edges = [
+        ["agency", "routes", {dependencies: [
+          {"agency" => "agency_id", "routes" => "agency_id"}
+        ]}],
+        ["fare_attributes", "fare_rules", {dependencies: [
+          {"fare_attributes" => "fare_id",
+           "fare_rules" => "fare_id"}
+        ]}],
+        ["fare_rules", "routes", {dependencies: [
+          {"fare_rules" => "route_id", "routes" => "route_id"}
+        ]}],
+        ["routes", "trips", {dependencies: [
+          {"routes" => "route_id", "trips" => "route_id"}
+        ]}],
+        ["trips", "stop_times", {dependencies: [
+          {"trips" => "trip_id", "stop_times" => "trip_id"}
+        ]}],
+        ["stop_times", "stops", {dependencies: [
+          {"stop_times" => "stop_id", "stops" => "stop_id"}
+        ]}],
+        ["stops", "transfers", {dependencies: [
+          {"stops" => "stop_id", "transfers" => "from_stop_id"},
+          {"stops" => "stop_id", "transfers" => "to_stop_id"}
+        ]}],
+        ["trips", "calendar", {dependencies: [
+          {"trips" => "service_id", "calendar" => "service_id"}
+        ]}],
+        ["trips", "calendar_dates", {dependencies: [
+          {"trips" => "service_id", "calendar_dates" => "service_id"}
+        ]}],
+        ["trips", "shapes", {dependencies: [
+          {"trips" => "shape_id", "shapes" => "shape_id"}
+        ]}],
+        ["trips", "frequencies", {dependencies: [
+          {"trips" => "trip_id", "frequencies" => "trip_id"}
+        ]}],
+
+        # --- GTFS Extensions ---
+        ["stops", "fare_leg_join_rules",
+          {dependencies: [
+            {"stops" => "stop_id", "fare_leg_join_rules" => "from_stop_id"},
+            {"stops" => "stop_id", "fare_leg_join_rules" => "to_stop_id"}
+          ]}],
+        ["fare_leg_join_rules", "networks", {dependencies: [
+          {"fare_leg_join_rules" => "from_network_id", "networks" => "network_id"},
+          {"fare_leg_join_rules" => "to_network_id", "networks" => "network_id"}
+        ]}],
+        ["fare_leg_join_rules", "fare_leg_rules",
+          {dependencies: [
+            {"fare_leg_join_rules" => "fare_leg_rule_id", "fare_leg_rules" => "fare_leg_rule_id"}
+          ]}],
+        ["fare_transfer_rules", "fare_leg_rules",
+          {dependencies: [
+            {"fare_transfer_rules" => "from_leg_group_id", "fare_leg_rules" => "leg_group_id"},
+            {"fare_transfer_rules" => "to_leg_group_id", "fare_leg_rules" => "leg_group_id"}
+          ]}],
+        ["fare_transfer_rules", "fare_products",
+          {dependencies: [
+            {"fare_transfer_rules" => "fare_product_id", "fare_products" => "fare_product_id"}
+          ]}],
+        ["areas", "stop_areas", {dependencies: [
+          {"areas" => "area_id", "stop_areas" => "area_id"}
+        ]}],
+        ["stops", "areas", {dependencies: [
+          {"stops" => "area_id", "areas" => "area_id"}
+        ]}],
+        ["areas", "fare_leg_rules", {dependencies: [
+          {"areas" => "area_id", "fare_leg_rules" => "from_area_id"},
+          {"areas" => "area_id", "fare_leg_rules" => "to_area_id"}
+        ]}],
+        ["networks", "route_networks", {dependencies: [
+          {"networks" => "network_id", "route_networks" => "network_id"}
+        ]}],
+        ["networks", "routes", {dependencies: [
+          {"networks" => "network_id", "routes" => "network_id"}
+        ]}],
+        ["networks", "fare_leg_rules", {dependencies: [
+          {"networks" => "network_id", "fare_leg_rules" => "network_id"}
+        ]}],
+        ["route_networks", "routes", {dependencies: [
+          {"route_networks" => "route_id", "routes" => "route_id"}
+        ]}],
+        ["route_networks", "networks", {dependencies: [
+          {"route_networks" => "network_id", "networks" => "network_id"}
+        ]}],
+        ["location_groups", "location_group_stops", {dependencies: [
+          {"location_groups" => "location_group_id", "location_group_stops" => "location_group_id"}
+        ]}],
+        ["location_groups", "stops", {dependencies: [
+          {"location_groups" => "location_group_id", "stops" => "location_group_id"}
+        ]}],
+        ["location_group_stops", "stops", {dependencies: [
+          {"location_group_stops" => "stop_id", "stops" => "stop_id"}
+        ]}],
+        ["stops", "location_group_stops", {dependencies: [
+          {"stops" => "stop_id", "location_group_stops" => "stop_id"}
+        ]}],
+        ["location_group_stops", "location_groups", {dependencies: [
+          {"location_group_stops" => "location_group_id", "location_groups" => "location_group_id"}
+        ]}],
+        ["booking_rules", "stop_times", {dependencies: [
+          {"booking_rules" => "booking_rule_id", "stop_times" => "pickup_booking_rule_id"},
+          {"booking_rules" => "booking_rule_id", "stop_times" => "drop_off_booking_rule_id"}
+        ]}],
+        ["stops", "booking_rules", {dependencies: [
+          {"stops" => "stop_id", "booking_rules" => "stop_id"}
+        ]}]
+      ]
+
+      edges.each do |from, to, attrs|
+        g.add_edge(from, to, **attrs)
+      end
+      g
+    end
+  end
+end

data/lib/gtfs_df/reader.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  class Reader
+    # Loads a GTFS zip file and returns a Feed
+    def self.load_from_zip(zip_path)
+      data = {}
+      Dir.mktmpdir do |tmpdir|
+        Zip::File.open(zip_path) do |zip_file|
+          zip_file.each do |entry|
+            next unless entry.file?
+
+            GtfsDf::Feed::GTFS_FILES.each do |file|
+              next unless entry.name == "#{file}.txt"
+
+              out_path = File.join(tmpdir, entry.name)
+              entry.extract(out_path)
+              schema_class_name = file.split("_").map(&:capitalize).join
+
+              data[file] = GtfsDf::Schema.const_get(schema_class_name).new(out_path).df
+            end
+          end
+        end
+      end
+      GtfsDf::Feed.new(data)
+    end
+  end
+end

data/lib/gtfs_df/schema/agency.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  module Schema
+    class Agency < BaseGtfsTable
+      SCHEMA = {
+        "agency_id" => Polars::String,
+        "agency_name" => Polars::String,
+        "agency_url" => Polars::String,
+        "agency_timezone" => Polars::String,
+        "agency_lang" => Polars::String,
+        "agency_phone" => Polars::String,
+        "agency_fare_url" => Polars::String,
+        "agency_email" => Polars::String,
+        "ticketing_deep_link_id" => Polars::String, # Google extension, optional
+        "cemv_support" => Polars::Enum.new(EnumValues::CEMV_SUPPORT.map(&:first)) # GTFS extension, optional
+      }
+
+      REQUIRED_FIELDS = %w[agency_name agency_url agency_timezone].freeze
+
+      ENUM_VALUE_MAP = {
+        "cemv_support" => :CEMV_SUPPORT
+      }
+    end
+  end
+end

data/lib/gtfs_df/schema/areas.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  module Schema
+    class Areas < BaseGtfsTable
+      SCHEMA = {
+        "area_id" => Polars::String,
+        "area_name" => Polars::String,
+        "area_type" => Polars::String
+      }.freeze
+
+      REQUIRED_FIELDS = %w[
+        area_id
+        area_name
+      ].freeze
+    end
+  end
+end

data/lib/gtfs_df/schema/attributions.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  module Schema
+    class Attributions < BaseGtfsTable
+      SCHEMA = {
+        "attribution_id" => Polars::String,
+        "agency_id" => Polars::String,
+        "route_id" => Polars::String,
+        "trip_id" => Polars::String,
+        "organization_name" => Polars::String,
+        "is_producer" => Polars::Int64,
+        "is_operator" => Polars::Int64,
+        "is_authority" => Polars::Int64,
+        "attribution_url" => Polars::String,
+        "attribution_email" => Polars::String,
+        "attribution_phone" => Polars::String
+      }.freeze
+
+      REQUIRED_FIELDS = %w[
+        organization_name
+        is_producer
+        is_operator
+        is_authority
+      ].freeze
+    end
+  end
+end

data/lib/gtfs_df/schema/booking_rules.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  module Schema
+    class BookingRules < BaseGtfsTable
+      SCHEMA = {
+        "booking_rule_id" => Polars::String,
+        "booking_type" => Polars::String,
+        "min_advance_book_time" => Polars::Int64,
+        "max_advance_book_time" => Polars::Int64
+      }.freeze
+
+      REQUIRED_FIELDS = %w[
+        booking_rule_id
+        booking_type
+      ].freeze
+    end
+  end
+end

data/lib/gtfs_df/schema/calendar.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  module Schema
+    class Calendar < BaseGtfsTable
+      SCHEMA = {
+        "service_id" => Polars::String,
+        "monday" => Polars::Enum.new(EnumValues::SERVICE_DAY.map(&:first)),
+        "tuesday" => Polars::Enum.new(%w[0 1]),
+        "wednesday" => Polars::Enum.new(%w[0 1]),
+        "thursday" => Polars::Enum.new(EnumValues::SERVICE_DAY.map(&:first)),
+        "friday" => Polars::Enum.new(%w[0 1]),
+        "saturday" => Polars::Enum.new(%w[0 1]),
+        "sunday" => Polars::Enum.new(%w[0 1]),
+        "start_date" => Polars::String,
+        "end_date" => Polars::String
+      }
+
+      REQUIRED_FIELDS = %w[service_id monday tuesday wednesday thursday friday saturday sunday start_date end_date]
+
+      ENUM_VALUE_MAP = {
+        "monday" => :SERVICE_DAY,
+        "tuesday" => :SERVICE_DAY,
+        "wednesday" => :SERVICE_DAY,
+        "thursday" => :SERVICE_DAY,
+        "friday" => :SERVICE_DAY,
+        "saturday" => :SERVICE_DAY,
+        "sunday" => :SERVICE_DAY
+      }
+    end
+  end
+end

data/lib/gtfs_df/schema/calendar_dates.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  module Schema
+    class CalendarDates < BaseGtfsTable
+      SCHEMA = {
+        "service_id" => Polars::String,
+        "date" => Polars::String,
+        "exception_type" => Polars::Enum.new(EnumValues::EXCEPTION_TYPE.map(&:first))
+      }.freeze
+
+      REQUIRED_FIELDS = %w[service_id date exception_type].freeze
+
+      ENUM_VALUE_MAP = {
+        "exception_type" => :EXCEPTION_TYPE
+      }
+    end
+  end
+end

data/lib/gtfs_df/schema/enum_values.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  module Schema
+    module EnumValues
+      # trips.txt
+      # direction_id: Indicates the direction of travel for a trip.
+      DIRECTION_ID = [
+        ["0", "Outbound travel"],
+        ["1", "Inbound travel"]
+      ]
+
+      # wheelchair_accessible: Indicates wheelchair accessibility.
+      WHEELCHAIR_ACCESSIBLE = [
+        ["0", "No accessibility information"],
+        ["1", "Vehicle can accommodate at least one rider in a wheelchair"],
+        ["2", "No riders in wheelchairs can be accommodated"]
+      ]
+
+      # bikes_allowed: Indicates whether bikes are allowed.
+      BIKES_ALLOWED = [
+        ["0", "No bike information"],
+        ["1", "Vehicle can accommodate at least one bicycle"],
+        ["2", "No bicycles allowed"]
+      ]
+
+      # cars_allowed: Indicates whether cars are allowed.
+      CARS_ALLOWED = [
+        ["0", "No car information"],
+        ["1", "Vehicle can accommodate at least one car"],
+        ["2", "No cars allowed"]
+      ]
+
+      # stop_times.txt
+      # pickup_type/drop_off_type: Pickup/drop off method.
+      PICKUP_TYPE = [
+        ["0", "Regularly scheduled pickup"],
+        ["1", "No pickup available"],
+        ["2", "Must phone agency to arrange pickup"],
+        ["3", "Must coordinate with driver to arrange pickup"]
+      ]
+      DROP_OFF_TYPE = [
+        ["0", "Regularly scheduled drop off"],
+        ["1", "No drop off available"],
+        ["2", "Must phone agency to arrange drop off"],
+        ["3", "Must coordinate with driver to arrange drop off"]
+      ]
+
+      # continuous_pickup/continuous_drop_off: Continuous stopping behavior.
+      CONTINUOUS_PICKUP = [
+        ["0", "Continuous stopping pickup"],
+        ["1", "No continuous stopping pickup"],
+        ["2", "Must phone agency to arrange continuous stopping pickup"],
+        ["3", "Must coordinate with driver to arrange continuous stopping pickup"]
+      ]
+      CONTINUOUS_DROP_OFF = [
+        ["0", "Continuous stopping drop off"],
+        ["1", "No continuous stopping drop off"],
+        ["2", "Must phone agency to arrange continuous stopping drop off"],
+        ["3", "Must coordinate with driver to arrange continuous stopping drop off"]
+      ]
+
+      # timepoint: Indicates if times are exact or approximate.
+      TIMEPOINT = [
+        ["0", "Times are approximate"],
+        ["1", "Times are exact"]
+      ]
+
+      # calendar.txt
+      # Service days: 1 = service available, 0 = not available
+      SERVICE_DAY = [
+        ["0", "Service not available"],
+        ["1", "Service available"]
+      ]
+
+      # calendar_dates.txt
+      # exception_type: Indicates whether service is added or removed for a date.
+      EXCEPTION_TYPE = [
+        ["1", "Service added for the date"],
+        ["2", "Service removed for the date"]
+      ]
+
+      # stops.txt
+      # location_type: Type of location
+      LOCATION_TYPE = [
+        ["0", "Stop or platform"],
+        ["1", "Station"],
+        ["2", "Entrance/Exit"],
+        ["3", "Generic Node"],
+        ["4", "Boarding Area"]
+      ]
+
+      # wheelchair_boarding: Indicates wheelchair boarding possibility
+      WHEELCHAIR_BOARDING = [
+        ["0", "No accessibility information"],
+        ["1", "Some vehicles can be boarded by a rider in a wheelchair"],
+        ["2", "Wheelchair boarding not possible"]
+      ]
+
+      # stop_access: How the stop is accessed
+      STOP_ACCESS = [
+        ["0", "Cannot be directly accessed from street network"],
+        ["1", "Direct access from street network"]
+      ]
+
+      # routes.txt
+      # route_type: Type of transportation
+      ROUTE_TYPE = [
+        ["0", "Tram, Streetcar, Light rail"],
+        ["1", "Subway, Metro"],
+        ["2", "Rail"],
+        ["3", "Bus"],
+        ["4", "Ferry"],
+        ["5", "Cable tram"],
+        ["6", "Aerial lift, suspended cable car"],
+        ["7", "Funicular"],
+        ["11", "Trolleybus"],
+        ["12", "Monorail"]
+      ]
+
+      # cemv_support: Contactless EMV support
+      CEMV_SUPPORT = [
+        ["0", "No cEMV information"],
+        ["1", "Riders may use cEMVs as fare media"],
+        ["2", "cEMVs are not supported"]
+      ]
+
+      # pathways.txt
+      # pathway_mode: Type of pathway
+      PATHWAY_MODE = [
+        ["1", "Walkway"],
+        ["2", "Stairs"],
+        ["3", "Moving sidewalk/travelator"],
+        ["4", "Escalator"],
+        ["5", "Elevator"],
+        ["6", "Fare gate"],
+        ["7", "Exit gate"]
+      ]
+
+      # is_bidirectional: Directionality of pathway
+      IS_BIDIRECTIONAL = [
+        %w[0 Unidirectional],
+        %w[1 Bidirectional]
+      ]
+    end
+  end
+end

data/lib/gtfs_df/schema/fare_attributes.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  module Schema
+    class FareAttributes < BaseGtfsTable
+      SCHEMA = {
+        "fare_id" => Polars::String,
+        "price" => Polars::Float64,
+        "currency_type" => Polars::String,
+        "payment_method" => Polars::Int64,
+        "transfers" => Polars::Int64,
+        "agency_id" => Polars::String,
+        "transfer_duration" => Polars::Int64
+      }.freeze
+
+      REQUIRED_FIELDS = %w[
+        fare_id
+        price
+        currency_type
+        payment_method
+        transfers
+      ].freeze
+    end
+  end
+end

data/lib/gtfs_df/schema/fare_leg_join_rules.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  module Schema
+    class FareLegJoinRules < BaseGtfsTable
+      SCHEMA = {
+        "fare_leg_join_rule_id" => Polars::String,
+        "from_leg_group_id" => Polars::String,
+        "to_leg_group_id" => Polars::String,
+        "network_id" => Polars::String
+      }.freeze
+
+      REQUIRED_FIELDS = %w[
+        fare_leg_join_rule_id
+        from_leg_group_id
+        to_leg_group_id
+      ].freeze
+    end
+  end
+end

data/lib/gtfs_df/schema/fare_leg_rules.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  module Schema
+    class FareLegRules < BaseGtfsTable
+      SCHEMA = {
+        "fare_leg_rule_id" => Polars::String,
+        "fare_product_id" => Polars::String,
+        "from_area_id" => Polars::String,
+        "to_area_id" => Polars::String,
+        "leg_group_id" => Polars::String,
+        "network_id" => Polars::String
+      }.freeze
+
+      REQUIRED_FIELDS = %w[
+        fare_leg_rule_id
+        fare_product_id
+      ].freeze
+    end
+  end
+end