eaternet 0.2.0

data/lib/eaternet/agencies/snhd.rb

@@ -0,0 +1,118 @@
+require 'csv'
+require 'eaternet/framework/prototype'
+require 'eaternet/agencies/snhd_config'
+require 'eaternet/util'
+
+include Eaternet
+include Eaternet::Framework::Prototype
+
+module Eaternet
+  module Agencies
+    # An adapter for the Southern Nevada Health District (Las Vegas).
+    #
+    # @example Print the names of all the Las Vegas businesses
+    #   require 'eaternet'
+    #
+    #   agency = Snhd.new
+    #   agency.businesses
+    #       .select { |biz| biz.city == 'Las Vegas' }
+    #       .each { |biz| puts biz.name }
+    #
+    # The SNHD makes their restaurant inspection data available via a zip file for download.
+    # The file contains several Mysql tables converted to CSV. And so, this is an example
+    # for how to code adapters for other agencies which publish their data in a similar way.
+    #
+    # This code downloads the latest zip file, extracts it, parses the csv, and provides
+    # enumerators of Businesses, Inspections, Violations, and ViolationKinds. (These are
+    # specified in the Eaternet::Framework::Framework module.)
+    #
+    # SNHD's CSV format seems to be non-standard, e.g. using the double-quote character
+    # in fields without escaping it. We need to find out what their quote character actually is.
+    # In the meantime, the files can be parsed by setting the quote character to something else
+    # that doesn't appear in the text, such as a pipe symbol.
+    #
+    # @see http://southernnevadahealthdistrict.org/restaurants/inspect-downloads.php
+    #      The SNHD Developer information page
+    # @see Eaternet::Framework::Prototype Framework module
+    class Snhd
+      include Prototype::AbstractAdapter
+
+      # (see Eaternet::Framework::Framework::AbstractAdapter#businesses)
+      def businesses
+        lazy_csv_map('restaurant_establishments.csv') do |row|
+          BusinessData.new(
+            orig_key: row['permit_number'],
+            name: row['restaurant_name'],
+            address: row['address'],
+            city: row['city_name'],
+            zipcode: row['zip_code']
+          )
+        end
+      end
+
+      # (see Eaternet::Framework::Framework::AbstractAdapter#inspections)
+      def inspections
+        lazy_csv_map('restaurant_inspections.csv') do |row|
+          InspectionData.new(
+            orig_key: row['serial_number'],
+            business_orig_key: row['permit_number'],
+            score: row['inspection_grade'],
+            date: row['inspection_date']
+          )
+        end
+      end
+
+      # (see Eaternet::Framework::Framework::AbstractAdapter#violations)
+      def violations
+        lazy_csv_map('restaurant_inspection_violations.csv') do |row|
+          ViolationData.new(
+            orig_key: row['inspection_violation_id'],
+            inspection_id: row['inspection_id'],
+            violation_kind_id: row['inspection_violation']
+          )
+        end
+      end
+
+      # @return [Enumerable<ViolationKindData>]
+      # @todo Add to AbstractAdapter
+      def violation_kinds
+        lazy_csv_map('restaurant_violations.csv') do |row|
+          ViolationKindData.new(
+            orig_key: row['violation_id'],
+            code: row['violation_code'],
+            demerits: row['violation_demerits'],
+            description: row['violation_description']
+          )
+        end
+      end
+
+      private
+
+      def lazy_csv_map(filename, &block)
+        csv_rows(filename).lazy.map { |row| block.call(row) }
+      end
+
+      def csv_rows(filename)
+        csv_reader(
+          path: File.join(zip_dir, filename),
+          headers: SnhdConfig::CSV_SCHEMA[filename]
+        )
+      end
+
+      def csv_reader(path:, headers:)
+        file = open(path)
+        file.readline  # Skip the non-standard header line
+        CSV.new(
+          file,
+          headers: headers,
+          col_sep: SnhdConfig::COLUMN_SEPARATOR,
+          quote_char: SnhdConfig::QUOTE_CHARACTER
+        )
+      end
+
+      def zip_dir
+        @zip_dir ||= Util.download_and_extract_zipfile(SnhdConfig::DOWNLOAD_URL)
+      end
+    end
+  end
+end

data/lib/eaternet/agencies/snhd_config.rb

@@ -0,0 +1,61 @@
+module Eaternet
+  module Agencies
+    class SnhdConfig
+      DOWNLOAD_URL = 'http://southernnevadahealthdistrict.org/restaurants/download/restaurants.zip'
+      COLUMN_SEPARATOR = ';'
+      QUOTE_CHARACTER = '|'  # TODO: Verify this with SNHD.
+
+      # The SNHD CSV does not have a true header row. And so, this data
+      # structure provides the column names.
+      CSV_SCHEMA = {
+        'restaurant_inspections.csv' => %w(
+          serial_number
+          permit_number
+          inspection_date
+          inspection_time
+          employee_id
+          inspection_type_id
+          inspection_demerits
+          inspection_grade
+          permit_status
+          inspection_result
+          violations
+          record_updated
+        ),
+        'restaurant_establishments.csv' => %w(
+          permit_number
+          facility_id
+          PE
+          restaurant_name
+          location_name
+          address
+          latitude
+          longitude
+          city_id
+          city_name
+          zip_code
+          nciaa
+          plan_review
+          record_status
+          current_grade
+          current_demerits
+          date_current
+          previous_grade
+          date_previous
+        ),
+        'restaurant_inspection_violations.csv' => %w(
+          inspection_violation_id
+          inspection_id
+          inspection_violation
+        ),
+        'restaurant_violations.csv' => %w(
+          violation_id
+          violation_code
+          violation_sort
+          violation_demerits
+          violation_description
+        )
+      }
+    end
+  end
+end

data/lib/eaternet/framework/lives_1_0.rb

@@ -0,0 +1,232 @@
+module Eaternet
+  module Framework
+
+    # Framework for creating LIVES 1.0 apps.
+    #
+    # The goal is to make it as easy as possible to create
+    # compliant implementations. And so, the Business, Inspection
+    # and Violation data objects use validations to ensure that they
+    # correctly produce the entities listed in the spec.
+    #
+    # @see http://www.yelp.com/healthscores
+    # @see http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/
+    # @see http://www.rubyinside.com/rails-3-0s-activemodel-how-to-give-ruby-classes-some-activerecord-magic-2937.html
+    module Lives_1_0
+      require 'active_model'
+
+
+      class Adapter
+        # Required.
+        # @return [Enumerable<Business>]
+        def businesses
+          fail 'Override this to return an Enumerable of Business'
+        end
+
+        # Required.
+        # @return [Enumerable<Inspection>]
+        def inspections
+          fail 'Override this to return an Enumerable of Inspection'
+        end
+
+        # Optional.
+        # @return [Enumerable<Violation>]
+        def violations
+          fail 'Optionally override this to return an Enumerable of Violation'
+        end
+
+        # Optional.
+        # @return [FeedInfo]
+        def feed_info
+          fail 'Optionally override this to return a FeedInfo'
+        end
+      end
+
+
+      class DataTransferObject
+        include ActiveModel::Validations
+
+        def initialize(&block)
+          block.call(self)
+          check_validations!
+        end
+
+        def check_validations!
+          fail ArgumentError, errors.messages.inspect if invalid?
+        end
+
+        class TypeValidator < ActiveModel::EachValidator
+          def validate_each(record, attribute, value)
+            record.errors.add attribute, (options[:message] || "is not of class #{options[:with]}") unless
+              value.class == options[:with]
+          end
+        end
+      end
+
+
+      # @see http://www.yelp.com/healthscores#businesses
+      class Business < DataTransferObject
+        attr_accessor :business_id, :name, :address, :city, :state,
+          :postal_code, :latitude, :longitude, :phone_number
+
+        validates :business_id, :name, :address,
+                  type: String,
+                  presence: true
+        validates :city, :state, :postal_code, :phone_number,
+                  type: String,
+                  allow_nil: true
+        validates :latitude,
+                  numericality:
+                    {
+                      greater_than_or_equal_to: -90,
+                      less_than_or_equal_to: 90
+                    },
+                  allow_nil: true
+        validates :longitude,
+                  numericality:
+                    {
+                      greater_than_or_equal_to: -180,
+                      less_than_or_equal_to: 180
+                    },
+                  allow_nil: true
+
+        def ==(other)
+          @business_id == other.business_id
+        end
+
+        def eql?(other)
+          self == other
+        end
+
+        def hash
+          @business_id.hash
+        end
+
+        # @return [String]
+        def to_s
+          "Business #{@business_id}"
+        end
+      end
+
+
+      # @see http://www.yelp.com/healthscores#inspections
+      class Inspection < DataTransferObject
+        attr_accessor :business_id, :score, :date, :description, :type
+
+        ZERO_TO_ONE_HUNDRED_AND_BLANK = (0..100).to_a + ['']
+
+        validates :business_id,
+                  type: String,
+                  presence: true
+        validates :score,
+                  inclusion: { in: ZERO_TO_ONE_HUNDRED_AND_BLANK },
+                  allow_nil: true
+        validates :date,
+                  type: Date,
+                  presence: true
+        validates :type,
+                  inclusion: { in: %w(initial routine followup complaint) },
+                  allow_nil: true
+
+        def score
+          @score.nil? ? '' : @score
+        end
+
+        def to_s
+          "Inspection #{@business_id}/#{@date}/#{@score}"
+        end
+      end
+
+
+      # @see http://www.yelp.com/healthscores#violations
+      class Violation < DataTransferObject
+        attr_accessor :business_id, :date, :code, :description
+
+        validates :business_id,
+                  type: String,
+                  presence: true
+        validates :date,
+                  type: Date,
+                  presence: true
+        validates :code, :description,
+                  type: String,
+                  allow_nil: true
+      end
+
+
+      # @see http://www.yelp.com/healthscores#feed_info
+      class FeedInfo < DataTransferObject
+        attr_accessor :feed_date, :feed_version, :municipality_name,
+                      :municipality_url, :contact_email
+
+        HAS_AN_AT_SOMEWHERE_IN_THE_MIDDLE = /\A[^@]+@[^@]+\z/
+
+        validates :feed_date,
+                  type: Date,
+                  presence: true
+        validates :feed_version,
+                  type: String,
+                  presence: true
+        validates :municipality_name,
+                  type: String,
+                  presence: true
+        validates :municipality_url,
+                  type: String,
+                  format: { with: %r(\Ahttps?:/) },
+                  allow_nil: true
+        validates :contact_email,
+                  type: String,
+                  format: { with: HAS_AN_AT_SOMEWHERE_IN_THE_MIDDLE },
+                  allow_nil: true
+      end
+
+
+      # @see http://www.yelp.com/healthscores#legend
+      class Legend < DataTransferObject
+        attr_accessor :minimum_score, :maximum_score, :description
+
+        validates :minimum_score, :maximum_score,
+                  inclusion: { in: (0..100) }
+        validates :description,
+                  presence: true,
+                  type: String
+      end
+
+
+      # A container for all the Legends in the data set. Performs
+      # validation on the whole set of Legends ensure they cover
+      # the entire range of scores and do not overlap.
+      class LegendGroup < DataTransferObject
+        attr_accessor :legends
+
+        # Check that all the items in this LegendGroup:
+        #
+        #   1. Are of the class, Legend
+        #   2. Cover the range of scores from 0-100 without overlap
+        class ComprehensiveValidator < ActiveModel::EachValidator
+          def validate_each(record, attribute, legends)
+            scores = (0..100).to_a
+            legends.each do |legend|
+              unless legend.class == Legend
+                record.errors.add attribute, 'must be a Legend'
+                return
+              end
+              range = (legend.minimum_score..legend.maximum_score)
+              range.each do |score|
+                if scores.delete(score).nil?
+                  unless score == legend.minimum_score || score == legend.maximum_score
+                    record.errors.add attribute, 'may not overlap'
+                    return
+                  end
+                end
+              end
+            end
+            record.errors.add attribute, 'do not cover entire span from 0–100' unless scores.empty?
+          end
+        end
+
+        validates :legends, comprehensive: true
+      end
+
+    end
+  end
+end

data/lib/eaternet/framework/prototype.rb

@@ -0,0 +1,109 @@
+module Eaternet
+  module Framework
+    # A first pass at a health scores mini-framework which
+    # is denormalized and provides some more information than
+    # LIVES.
+    module Prototype
+
+      module AbstractAdapter
+        # @return [Enumerable<BusinessData>]
+        def businesses
+          fail 'Override this to return an Enumerable of BusinessData objects'
+        end
+
+        # @return [Enumerable<InspectionData>]
+        def inspections
+          fail 'Override this to return an Enumerable of InspectionData objects'
+        end
+
+        # @return [Enumerable<ViolationData>]
+        def violations
+          fail 'Override this to return an Enumerable of ViolationData objects'
+        end
+
+        # @return [Enumerable<ViolationData>]
+        def violation_kinds
+          fail 'Override this to return an Enumerable of ViolationKindData objects'
+        end
+      end
+
+      class BusinessData
+        # @return [String]
+        attr_reader :name, :address, :city, :zipcode, :orig_key
+
+        def initialize(name:, address:, city:, zipcode:, orig_key:)
+          @name = name
+          @address = address
+          @city = city
+          @zipcode = zipcode
+          @orig_key = orig_key
+        end
+
+        def ==(other)
+          @orig_key == other.orig_key
+        end
+
+        def eql?(other)
+          self == other
+        end
+
+        def hash
+          @orig_key.hash
+        end
+
+        # @return [String]
+        def to_s
+          "Business #{@orig_key}"
+        end
+      end
+
+      class InspectionData
+        # @return [String]
+        attr_reader :orig_key, :business_orig_key, :score, :date
+
+        def initialize(orig_key:, business_orig_key:, score:, date:)
+          @orig_key = orig_key
+          @business_orig_key = business_orig_key
+          @score = score
+          @date = date
+        end
+
+        def to_s
+          "Inspection #{@orig_key}"
+        end
+      end
+
+      class ViolationData
+        # @return [String]
+        attr_reader :orig_key, :inspection_id, :violation_kind_id
+
+        def initialize(orig_key:, inspection_id:, violation_kind_id:)
+          @orig_key = orig_key
+          @inspection_id = inspection_id
+          @violation_kind_id = violation_kind_id
+        end
+
+        def to_s
+          "Violation #{@orig_key}"
+        end
+      end
+
+      class ViolationKindData
+        # @return [String]
+        attr_reader :orig_key, :code, :demerits, :description
+
+        def initialize(orig_key:, code:, demerits:, description:)
+          @orig_key = orig_key
+          @code = code
+          @demerits = demerits
+          @description = description
+        end
+
+        def to_s
+          "ViolationKind #{@orig_key}"
+        end
+      end
+
+    end
+  end
+end