gtfs_df 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d799dcd02b51045c948123e3b6bc64c41b5505279a583d98350377e6d06b4205
+  data.tar.gz: 57ff89fd953842d68a5d4c7424a91b54484415a0b093bbe0d0b0411b025c6ef4
+SHA512:
+  metadata.gz: 13b027c13cfec0a3493662cb048dd20f1b44aac778eb0e2d124ad873ae3649b1622758550399d9e457065401bfa04dbbb71e5e36da467599f8aac9675b2431ad
+  data.tar.gz: 9d248e0fe06e69af6a5d86114e77e10583dcbf9956858411cc6ed2cc2d03ebf4ce2047d3e8bbc1eb5eb5530a2e544bf8cc21c4d0184fe331558008fce64a055a

data/.conform.yaml

@@ -0,0 +1,25 @@
+policies:
+    - type: commit
+      spec:
+          header:
+              length: 89
+              imperative: true
+              case: lower
+              invalidLastCharacters: .
+          body:
+              required: true
+          dco: false
+          spellcheck:
+              locale: US
+          maximumOfOneCommit: false
+          conventional:
+              scopes:
+                  - master
+                  - deps
+              types:
+                  - feat
+                  - fix
+                  - chore
+                  - deps
+                  - docs
+                  - ci

data/.envrc

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+export DIRENV_WARN_TIMEOUT=20s
+
+eval "$(devenv direnvrc)"
+
+# `use devenv` supports the same options as the `devenv shell` command.
+#
+# To silence all output, use `--quiet`.
+#
+# Example usage: use devenv --quiet --impure --option services.postgres.enable:bool true
+use devenv

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,2 @@
+inherit_gem:
+  standard: config/base.yml

data/.solargraph.yml

@@ -0,0 +1,26 @@
+---
+include:
+- Rakefile
+- Gemfile
+- "*.gemspec"
+- "**/*.rb"
+exclude:
+- spec/**/*
+- test/**/*
+- vendor/**/*
+- ".bundle/**/*"
+require: []
+domains: []
+reporters:
+- rubocop
+- require_not_found
+formatter:
+  rubocop:
+    cops: safe
+    except: []
+    only: []
+    extra_args: []
+    lint: true
+require_paths: []
+plugins: []
+max_files: 5000

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.1

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [0.1.0] - 2025-11-10
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 David Mejorado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+# ruby-gtfs-df
+
+A ruby gem to manipulate [GTFS] feeds using DataFrames using [Polars] ([ruby-polars])
+
+This project was created to bring the power of [partridge] to ruby.
+
+> **⚠️ Warning:** This gem is not ready for production use. It is currently in active development and the API may change without notice.
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+## Usage
+
+### Loading a GTFS feed
+
+```ruby
+require 'gtfs_df'
+
+# Load from a zip file
+feed = GtfsDf::Reader.load_from_zip('path/to/gtfs.zip')
+
+# Access dataframes for each GTFS file
+puts feed.agency.head
+puts feed.routes.head
+puts feed.trips.head
+puts feed.stop_times.head
+puts feed.stops.head
+```
+
+### Filtering feeds
+
+The library supports filtering feeds by any field in any table. The filter automatically cascades through the dependency graph to ensure referential integrity.
+
+```ruby
+# Filter by agency
+filtered_feed = feed.filter('agency' => { 'agency_id' => 'MTA' })
+
+# Filter by route
+filtered_feed = feed.filter('routes' => { 'route_id' => ['1', '2', '3'] })
+
+# Filter by a service
+filtered_feed = feed.filter('calendar' => { 'service_id' => 'WEEKDAY' })
+
+# Multiple filters
+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:
+1. Filters the specified table
+2. Cascades related tables following foreign key relationships
+3. Keeps only the data that maintains referential integrity
+
+For example, filtering by `agency_id` will automatically filter routes, trips, stop_times, and stops to only include data for that agency.
+
+### Writing filtered feeds
+
+```ruby
+# Write to a new zip file
+GtfsDf::Writer.write_to_zip(filtered_feed, 'output/filtered_gtfs.zip')
+```
+
+### Example: Split feed by agency
+
+See [examples/split-by-agency](examples/split-by-agency) for a complete example that splits a multi-agency GTFS feed into separate files per agency.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## TODO
+
+- [ ] Time parsing
+    Just like partridge, we should parse Time as seconds since midnight. There's a draft in `lib/gtfs_df/utils.rb` but it's not used anywhere.
+    I haven't figured out how to properly implement with Polars.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/davidmh/ruby-gtfs_df.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+[GTFS]: https://gtfs.org/
+[Polars]: https://pola.rs/
+[ruby-polars]: https://github.com/ankane/ruby-polars
+[partridge]: https://github.com/remix/partridge

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/devenv.lock

@@ -0,0 +1,171 @@
+{
+  "nodes": {
+    "devenv": {
+      "locked": {
+        "dir": "src/modules",
+        "lastModified": 1761427990,
+        "owner": "cachix",
+        "repo": "devenv",
+        "rev": "7419c04fc798d5d5918413d4cb6c8629f9d4e8a3",
+        "type": "github"
+      },
+      "original": {
+        "dir": "src/modules",
+        "owner": "cachix",
+        "repo": "devenv",
+        "type": "github"
+      }
+    },
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1747046372,
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "flake-compat_2": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1747046372,
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "git-hooks": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "gitignore": "gitignore",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1760663237,
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "rev": "ca5b894d3e3e151ffc1db040b6ce4dcc75d31c37",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "type": "github"
+      }
+    },
+    "gitignore": {
+      "inputs": {
+        "nixpkgs": [
+          "git-hooks",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1709087332,
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "rev": "637db329424fd7e46cf4185293b9cc8c88c95394",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1758532697,
+        "owner": "cachix",
+        "repo": "devenv-nixpkgs",
+        "rev": "207a4cb0e1253c7658c6736becc6eb9cace1f25f",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "ref": "rolling",
+        "repo": "devenv-nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-ruby": {
+      "inputs": {
+        "flake-compat": "flake-compat_2",
+        "flake-utils": "flake-utils",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1759902829,
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
+        "rev": "5fba6c022a63f1e76dee4da71edddad8959f088a",
+        "type": "github"
+      },
+      "original": {
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "devenv": "devenv",
+        "git-hooks": "git-hooks",
+        "nixpkgs": "nixpkgs",
+        "nixpkgs-ruby": "nixpkgs-ruby",
+        "pre-commit-hooks": [
+          "git-hooks"
+        ]
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

data/devenv.nix

@@ -0,0 +1,13 @@
+{ pkgs, lib, config, inputs, ... }:
+
+{
+  languages.ruby = {
+    enable = true;
+    version = "3.4.7";
+    bundler.enable = false;
+  };
+
+  pre-commit.hooks = {
+    conform.enable = true;
+  };
+}

data/devenv.yaml

@@ -0,0 +1,8 @@
+inputs:
+  nixpkgs:
+    url: github:cachix/devenv-nixpkgs/rolling
+  nixpkgs-ruby:
+    url: github:bobvanderlinden/nixpkgs-ruby
+    inputs:
+      nixpkgs:
+        follows: nixpkgs

data/examples/split-by-agency/.gitignore

@@ -0,0 +1 @@
+output/

data/examples/split-by-agency/Gemfile

@@ -0,0 +1,5 @@
+source "https://gem.coop"
+
+gem "gtfs_df", path: "../.."
+gem "optparse"
+gem "whirly"

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

@@ -0,0 +1,52 @@
+PATH
+  remote: ../..
+  specs:
+    gtfs_df (0.1.0)
+      networkx (~> 0.4)
+      polars-df (~> 0.22)
+      rubyzip (~> 2.3)
+
+GEM
+  remote: https://gem.coop/
+  specs:
+    bigdecimal (3.3.1)
+    matrix (0.4.3)
+    networkx (0.4.0)
+      matrix (~> 0.4)
+      rb_heap (~> 1.0)
+    optparse (0.8.0)
+    polars-df (0.23.0-aarch64-linux)
+      bigdecimal
+    polars-df (0.23.0-aarch64-linux-musl)
+      bigdecimal
+    polars-df (0.23.0-arm64-darwin)
+      bigdecimal
+    polars-df (0.23.0-x86_64-darwin)
+      bigdecimal
+    polars-df (0.23.0-x86_64-linux)
+      bigdecimal
+    polars-df (0.23.0-x86_64-linux-musl)
+      bigdecimal
+    rb_heap (1.1.0)
+    rubyzip (2.4.1)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+    whirly (0.3.0)
+      unicode-display_width (>= 1.1)
+
+PLATFORMS
+  aarch64-linux
+  aarch64-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux
+  x86_64-linux-musl
+
+DEPENDENCIES
+  gtfs_df!
+  optparse
+  whirly
+
+BUNDLED WITH
+   2.6.9

data/examples/split-by-agency/README.md

@@ -0,0 +1,26 @@
+# Split GTFS by Agency Example
+
+This example demonstrates how to split a GTFS zip file into multiple files, one for each specified `agency_id`, using the `gtfs_df` Ruby gem.
+
+## Usage
+
+```
+bundle install
+ruby split_by_agency.rb -i <input-gtfs.zip> --ids agency1,agency2
+```
+
+- The output files will be written to the `output/` directory, named `<agency_id>.zip`.
+
+## Options
+- `-i`, `--input PATH` — Path to the input GTFS zip file
+- `--ids IDS` — Comma-separated list of agency IDs to extract
+
+## Example
+
+```
+ruby split_by_agency.rb -i ../../spec/fixtures/sample_gtfs.zip --ids DTA,OTA
+```
+
+---
+
+This is a port of the [original Python script](https://gist.github.com/davidmh/f51e5d93a9213e0e606a43167ff87403) using Partridge.

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

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "fileutils"
+require "gtfs_df"
+require "whirly"
+
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: split_by_agency.rb -i <input-gtfs.zip> --ids NUMBERS"
+
+  opts.on("-i", "--input PATH", "Path to the input GTFS file") do |v|
+    options[:input] = v
+  end
+  opts.on("--ids IDS", "Comma-separated list of agency_ids") do |v|
+    options[:ids] = v
+  end
+end.parse!
+
+unless options[:input] && options[:ids]
+  warn "Both --input and --ids are required."
+  exit 1
+end
+
+input_path = File.expand_path(options[:input])
+agency_ids = options[:ids].split(",")
+output_dir = File.expand_path("./output", __dir__)
+FileUtils.mkdir_p(output_dir)
+
+feed = nil
+
+Whirly.configure spinner: "dots", stop: "✓"
+
+Whirly.start do
+  Whirly.status = "Loading"
+  feed = GtfsDf::Reader.load_from_zip(input_path)
+  Whirly.status = "Loaded"
+end
+
+agency_ids.each do |agency_id|
+  Whirly.start do
+    Whirly.status = "-> #{agency_id} filtering..."
+    output_path = File.join(output_dir, "#{agency_id}.zip")
+    filtered_feed = feed.filter("agency" => {"agency_id" => agency_id})
+    Whirly.status = "-> #{agency_id} writing..."
+    GtfsDf::Writer.write_to_zip(filtered_feed, output_path)
+    Whirly.status = "-> #{agency_id}"
+  end
+end
+
+puts "✓  Done, all files are stored in the output/ directory"

data/lib/gtfs_df/base_gtfs_table.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module GtfsDf
+  class BaseGtfsTable
+    attr_reader :df, :validator
+
+    # @param input [Polars::DataFrame, String, Array] A dataframe, a csv path or an array-based table
+    def initialize(input)
+      @df =
+        if input.is_a?(Polars::DataFrame)
+          input
+        elsif input.is_a?(String)
+          Polars.read_csv(input, dtypes: self.class::SCHEMA)
+        elsif input.is_a?(Array)
+          head, *body = input
+          df_input = body.each_with_object({}) do |row, acc|
+            head.each_with_index do |column, index|
+              acc[column] ||= []
+              acc[column] << row[index]
+            end
+          end
+          Polars::DataFrame.new(df_input, schema_overrides: self.class::SCHEMA, strict: false)
+        else
+          throw GtfsDf::Error, "Unrecognized input"
+        end
+      @validator = SchemaValidator.new(@df, self.class)
+    end
+
+    def fields
+      self.class::SCHEMA.keys
+    end
+
+    def valid?
+      @validator.valid?
+    end
+
+    def errors
+      @validator.errors
+    end
+
+    def dataframe
+      @df
+    end
+  end
+end