us_geo 1.0.0

data/lib/us_geo/state.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module USGeo
+
+  # U.S. state or territory.
+  class State < BaseRecord
+
+    STATE_TYPE = "state"
+    DISTRICT_TYPE = "district"
+    TERRITORY_TYPE = "territory"
+    
+    self.primary_key = "code"
+    self.inheritance_column = :_type_disabled
+
+    belongs_to :region, optional: -> { territory? }, inverse_of: :states
+    belongs_to :division, optional: -> { territory? }, inverse_of: :states
+    has_many :counties, foreign_key: :state_code, inverse_of: :state
+    has_many :places, foreign_key: :state_code, inverse_of: :state
+
+    validates :code, length: {is: 2}
+    validates :fips, length: {is: 2}
+    validates :name, length: {maximum: 30}
+    validates :type, inclusion: [STATE_TYPE, DISTRICT_TYPE, TERRITORY_TYPE]
+
+    class << self
+      def load!(uri = nil)
+        location = data_uri(uri || "states.csv")
+        
+        import! do
+          load_data_file(location) do |row|
+            load_record!(code: row["Code"]) do |record|
+              record.name = row["Name"]
+              record.type = row["Type"]
+              record.fips = row["FIPS"]
+              record.region_id = row["Region ID"]
+              record.division_id = row["Division ID"]
+            end
+          end
+        end
+      end
+    end
+    
+    def state?
+      type == STATE_TYPE
+    end
+    
+    def territory?
+      type == TERRITORY_TYPE
+    end
+    
+    def district?
+      type == DISTRICT_TYPE
+    end
+
+  end
+end

data/lib/us_geo/urban_area.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module USGeo
+
+  # Urban areas are split into either urbanized areas (population > 50,000) or urban cluster (population < 50,000).
+  class UrbanArea < BaseRecord
+
+    include Demographics
+
+    self.primary_key = "geoid"
+    self.store_full_sti_class = false
+
+    has_many :urban_area_counties, foreign_key: :urban_area_geoid, inverse_of: :urban_area, dependent: :destroy
+    has_many :counties, through: :urban_area_counties
+    belongs_to :primary_county, foreign_key: :primary_county_geoid, class_name: "USGeo::County"
+    
+    has_many :zcta_urban_areas, foreign_key: :urban_area_geoid, inverse_of: :urban_area, dependent: :destroy
+    has_many :zctas, through: :zcta_urban_areas
+
+    validates :geoid, length: {is: 5}
+    validates :primary_county_geoid, length: {is: 5}
+    validates :name, length: {maximum: 90}
+    validates :short_name, length: {maximum: 60}
+    validates :land_area, numericality: true, presence: true
+    validates :water_area, numericality: true, presence: true
+    validates :population, numericality: {only_integer: true}, presence: true
+    validates :housing_units, numericality: {only_integer: true}, presence: true
+
+    delegate :core_based_statistical_area, :designated_market_area, :state, :state_code, :time_zone, to: :primary_county, allow_nil: true
+
+    before_save do
+      self.short_name = name.sub(" Urbanized Area", "").sub(" Urban Cluster", "") if name
+    end
+    
+    class << self
+      def load!(uri = nil)
+        location = data_uri(uri || "urban_areas.csv")
+       
+        import! do
+          load_data_file(location) do |row|
+            load_record!(geoid: row["GEOID"]) do |record|
+              record.type = (row["Population"].to_i >= 50_000 ? "UrbanizedArea" : "UrbanCluster")
+              record.name = row["Name"]
+              record.primary_county_geoid = row["Primary County"]
+              record.population = row["Population"]
+              record.housing_units = row["Housing Units"]
+              record.land_area = area_meters_to_miles(row["Land Area"])
+              record.water_area = area_meters_to_miles(row["Water Area"])
+              record.lat = row["Latitude"]
+              record.lng = row["Longitude"]
+            end
+          end
+        end
+      end
+    end
+
+    def urbanized?
+      raise NotImplementedError
+    end
+    
+    def cluster?
+      raise NotImplementedError
+    end
+
+  end
+end

data/lib/us_geo/urban_area_county.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module USGeo
+
+  # Mapping of urban areas to counties they overlap with.
+  class UrbanAreaCounty < BaseRecord
+
+    include Demographics
+
+    belongs_to :county, foreign_key: :county_geoid, inverse_of: :urban_area_counties
+    belongs_to :urban_area, foreign_key: :urban_area_geoid, inverse_of: :urban_area_counties
+
+    validates :county_geoid, length: {is: 5}
+    validates :urban_area_geoid, length: {is: 5}
+    validates :land_area, numericality: true, presence: true
+    validates :water_area, numericality: true, presence: true
+    validates :population, numericality: {only_integer: true}, presence: true
+    validates :housing_units, numericality: {only_integer: true}, presence: true
+
+    class << self
+      def load!(uri = nil)
+        location = data_uri(uri || "urban_area_counties.csv")
+        
+        import! do
+          load_data_file(location) do |row|
+            load_record!(urban_area_geoid: row["Urban Area GEOID"], county_geoid: row["County GEOID"]) do |record|
+              record.population = row["Population"]
+              record.housing_units = row["Housing Units"]
+              record.land_area = area_meters_to_miles(row["Land Area"])
+              record.water_area = area_meters_to_miles(row["Water Area"])
+            end
+          end
+        end
+      end
+    end
+
+    # Percentage of the urban area population.
+    def percent_urban_area_population
+      population.to_f / urban_area.population.to_f
+    end
+
+    # Percentage of the urban area land area.
+    def percent_urban_area_land_area
+      land_area / urban_area.land_area
+    end
+
+    # Percentage of the urban area total area.
+    def percent_urban_area_total_area
+      total_area / urban_area.total_area
+    end
+
+    # Percentage of the county population.
+    def percent_county_population
+      population.to_f / county.population.to_f
+    end
+
+    # Percentage of the county land area.
+    def percent_county_land_area
+      land_area / county.land_area
+    end
+
+    # Percentage of the county total area.
+    def percent_county_total_area
+      total_area / county.total_area
+    end
+
+  end
+end

data/lib/us_geo/urban_cluster.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module USGeo
+
+  # Urban area with population < 50,000.
+  class UrbanCluster < UrbanArea
+    
+    def urbanized?
+      false
+    end
+    
+    def cluster?
+      true
+    end
+    
+  end
+
+end

data/lib/us_geo/urbanized_area.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module USGeo
+
+  # Urban area with population >= 50,000.
+  class UrbanizedArea < UrbanArea
+    
+    def urbanized?
+      true
+    end
+    
+    def cluster?
+      false
+    end
+    
+  end
+
+end

data/lib/us_geo/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module USGeo
+  VERSION = "1.0.0"
+end

data/lib/us_geo/zcta.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module USGeo
+
+  # ZIP code tabulation area. These roughly map to U.S. Postal service ZIP codes, but
+  # are designed for geographic and demographic purposes instead of mail routing. In particular
+  # certain optimizations that the Postal Service makes to optimize mail routing are
+  # omitted or smoothed over (i.e. ZIP codes mapping to a single building, one-off enclaves, etc.)
+  #
+  # ZCTA's can span counties, but the one with the majority of the residents is identified
+  # as the primary county for when a single county is required.
+  #
+  # ZCTA's can span urbanized area, but the one with the majority of the residents is identified
+  # as the primary urbanized area for when a single area is required.
+  class Zcta < BaseRecord
+
+    include Demographics
+
+    self.table_name = "us_geo_zctas"
+    self.primary_key = "zipcode"
+
+    has_many :zcta_counties, foreign_key: :zipcode, inverse_of: :zcta, dependent: :destroy
+    has_many :counties, through: :zcta_counties
+    belongs_to :primary_county, foreign_key: :primary_county_geoid, class_name: "USGeo::County"
+
+    has_many :zcta_urban_areas, foreign_key: :zipcode, inverse_of: :zcta, dependent: :destroy
+    has_many :urban_areas, through: :zcta_urban_areas
+    belongs_to :primary_urban_area, foreign_key: :primary_urban_area_geoid, class_name: "USGeo::UrbanArea"
+
+    has_many :zcta_places, foreign_key: :zipcode, inverse_of: :zcta, dependent: :destroy
+    has_many :places, through: :zcta_places
+
+    validates :zipcode, length: {is: 5}
+    validates :land_area, numericality: true, presence: true
+    validates :water_area, numericality: true, presence: true
+    validates :population, numericality: {only_integer: true}, presence: true
+    validates :housing_units, numericality: {only_integer: true}, presence: true
+
+    delegate :core_based_statistical_area, :designated_market_area, :state, :state_code, :time_zone, to: :primary_county, allow_nil: true
+
+    class << self
+      def load!(uri = nil)
+        location = data_uri(uri || "zctas.csv")
+
+        import! do
+          load_data_file(location) do |row|
+            load_record!(zipcode: row["ZCTA5"]) do |record|
+              record.primary_county_geoid = row["Primary County"]
+              record.primary_urban_area_geoid = row["Primary Urban Area"]
+              record.population = row["Population"]
+              record.housing_units = row["Housing Units"]
+              record.land_area = area_meters_to_miles(row["Land Area"])
+              record.water_area = area_meters_to_miles(row["Water Area"])
+              record.lat = row["Latitude"]
+              record.lng = row["Longitude"]
+            end
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/us_geo/zcta_county.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module USGeo
+
+  # Mapping of ZCTA's to counties they overlap with.
+  class ZctaCounty < BaseRecord
+
+    include Demographics
+
+    belongs_to :zcta, foreign_key: :zipcode, inverse_of: :zcta_counties
+    belongs_to :county, foreign_key: :county_geoid, inverse_of: :zcta_counties
+
+    validates :zipcode, length: {is: 5}
+    validates :county_geoid, length: {is: 5}
+    validates :land_area, numericality: true, presence: true
+    validates :water_area, numericality: true, presence: true
+    validates :population, numericality: {only_integer: true}, presence: true
+    validates :housing_units, numericality: {only_integer: true}, presence: true
+
+    class << self
+      def load!(uri = nil)
+        location = data_uri(uri || "zcta_counties.csv")
+        
+        import! do
+          load_data_file(location) do |row|
+            load_record!(zipcode: row["ZCTA5"], county_geoid: row["GEOID"]) do |record|
+              record.population = row["Population"]
+              record.housing_units = row["Housing Units"]
+              record.land_area = area_meters_to_miles(row["Land Area"])
+              record.water_area = area_meters_to_miles(row["Water Area"])
+            end
+          end
+        end
+      end
+    end
+
+    # Percentage of the ZCTA population.
+    def percent_zcta_population
+      population.to_f / zcta.population.to_f
+    end
+
+    # Percentage of the ZCTA land area.
+    def percent_zcta_land_area
+      land_area / zcta.land_area
+    end
+
+    # Percentage of the ZCTA total area.
+    def percent_zcta_total_area
+      total_area / zcta.total_area
+    end
+
+    # Percentage of the county population.
+    def percent_county_population
+      population.to_f / county.population.to_f
+    end
+
+    # Percentage of the county land area.
+    def percent_county_land_area
+      land_area / county.land_area
+    end
+
+    # Percentage of the county total area.
+    def percent_county_total_area
+      total_area / county.total_area
+    end
+
+  end
+end

data/lib/us_geo/zcta_place.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module USGeo
+
+  # Mapping of ZCTA's to urban areas they overlap with.
+  class ZctaPlace < BaseRecord
+
+    include Demographics
+
+    belongs_to :zcta, foreign_key: :zipcode, inverse_of: :zcta_places
+    belongs_to :place, foreign_key: :place_geoid, inverse_of: :zcta_places
+
+    validates :zipcode, length: {is: 5}
+    validates :place_geoid, length: {is: 7}
+    validates :land_area, numericality: true, presence: true
+    validates :water_area, numericality: true, presence: true
+    validates :population, numericality: {only_integer: true}, presence: true
+    validates :housing_units, numericality: {only_integer: true}, presence: true
+
+    class << self
+      def load!(uri = nil)
+        location = data_uri(uri || "zcta_places.csv")
+        
+        import! do
+          load_data_file(location) do |row|
+            load_record!(zipcode: row["ZCTA5"], place_geoid: row["Place GEOID"]) do |record|
+              record.population = row["Population"]
+              record.housing_units = row["Housing Units"]
+              record.land_area = area_meters_to_miles(row["Land Area"])
+              record.water_area = area_meters_to_miles(row["Water Area"])
+            end
+          end
+        end
+      end
+    end
+
+    # Percentage of the ZCTA population.
+    def percent_zcta_population
+      population.to_f / zcta.population.to_f
+    end
+
+    # Percentage of the ZCTA land area.
+    def percent_zcta_land_area
+      land_area / zcta.land_area
+    end
+
+    # Percentage of the ZCTA total area.
+    def percent_zcta_total_area
+      total_area / zcta.total_area
+    end
+
+    # Percentage of the place population.
+    def percent_place_population
+      population.to_f / place.population.to_f
+    end
+
+    # Percentage of the place land area.
+    def percent_place_land_area
+      land_area / place.land_area
+    end
+
+    # Percentage of the place total area..
+    def percent_place_total_area
+      total_area / place.total_area
+    end
+
+  end
+end

data/lib/us_geo/zcta_urban_area.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module USGeo
+
+  # Mapping of ZCTA's to urban areas they overlap with.
+  class ZctaUrbanArea < BaseRecord
+
+    include Demographics
+
+    belongs_to :zcta, foreign_key: :zipcode, inverse_of: :zcta_urban_areas
+    belongs_to :urban_area, foreign_key: :urban_area_geoid, inverse_of: :zcta_urban_areas
+
+    validates :zipcode, length: {is: 5}
+    validates :urban_area_geoid, length: {is: 5}
+    validates :land_area, numericality: true, presence: true
+    validates :water_area, numericality: true, presence: true
+    validates :population, numericality: {only_integer: true}, presence: true
+    validates :housing_units, numericality: {only_integer: true}, presence: true
+
+    class << self
+      def load!(uri = nil)
+        location = data_uri(uri || "zcta_urban_areas.csv")
+
+        import! do
+          load_data_file(location) do |row|
+            load_record!(zipcode: row["ZCTA5"], urban_area_geoid: row["Urban Area GEOID"]) do |record|
+              record.population = row["Population"]
+              record.housing_units = row["Housing Units"]
+              record.land_area = area_meters_to_miles(row["Land Area"])
+              record.water_area = area_meters_to_miles(row["Water Area"])
+            end
+          end
+        end
+      end
+    end
+
+    # Percentage of the ZCTA population.
+    def percent_zcta_population
+      population.to_f / zcta.population.to_f
+    end
+
+    # Percentage of the ZCTA land area.
+    def percent_zcta_land_area
+      land_area / zcta.land_area
+    end
+
+    # Percentage of the ZCTA total area.
+    def percent_zcta_total_area
+      total_area / zcta.total_area
+    end
+
+    # Percentage of the urban area population.
+    def percent_urban_area_population
+      population.to_f / urban_area.population.to_f
+    end
+
+    # Percentage of the urban area land area.
+    def percent_urban_area_land_area
+      land_area / urban_area.land_area
+    end
+
+    # Percentage of the urban area total area.
+    def percent_urban_area_total_area
+      total_area / urban_area.total_area
+    end
+
+  end
+end

data/lib/us_geo.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+require_relative 'us_geo/version'
+require_relative 'us_geo/demographics'
+require_relative 'us_geo/base_record'
+require_relative 'us_geo/region'
+require_relative 'us_geo/division'
+require_relative 'us_geo/state'
+require_relative 'us_geo/designated_market_area'
+require_relative 'us_geo/combined_statistical_area'
+require_relative 'us_geo/core_based_statistical_area'
+require_relative 'us_geo/metropolitan_area'
+require_relative 'us_geo/micropolitan_area'
+require_relative 'us_geo/metropolitan_division'
+require_relative 'us_geo/county'
+require_relative 'us_geo/county_subdivision'
+require_relative 'us_geo/urban_area'
+require_relative 'us_geo/urbanized_area'
+require_relative 'us_geo/urban_cluster'
+require_relative 'us_geo/urban_area_county'
+require_relative 'us_geo/place'
+require_relative 'us_geo/place_county'
+require_relative 'us_geo/zcta'
+require_relative 'us_geo/zcta_urban_area'
+require_relative 'us_geo/zcta_county'
+require_relative 'us_geo/zcta_place'
+
+require_relative 'us_geo/engine' if defined?(::Rails::Engine)
+
+module USGeo
+
+  BASE_DATA_URI = "https://raw.githubusercontent.com/bdurand/us_geo/master/data/dist"
+
+  class << self
+    # The root URI as a string of where to find the data files. This can be a URL
+    # or a file system path. The default is to load the data from files hosted with
+    # the project code on GitHub.
+    def base_data_uri
+      if defined?(@base_data_uri) && @base_data_uri
+        @base_data_uri
+      else
+        BASE_DATA_URI
+      end
+    end
+
+    def base_data_uri=(value)
+      @base_data_uri = (value.nil? ? nil : value.to_s)
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+require "bundler/setup"
+require_relative "../lib/us_geo"
+
+require "active_record"
+require "webmock/rspec"
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end
+
+ActiveRecord::Base.establish_connection("adapter" => "sqlite3", "database" => ":memory:")
+
+Dir.glob(File.expand_path("../db/migrate/*.rb", __dir__)).each do |path|
+  require(path)
+  class_name = File.basename(path).sub(/\.rb/, '').split('_', 2).last.camelcase
+  class_name.constantize.migrate(:up)
+end

data/spec/us_geo/base_record_spec.rb

@@ -0,0 +1,67 @@
+require "spec_helper"
+
+describe USGeo::BaseRecord do
+
+  describe "status" do
+    it "should be marked as imported" do
+      record = USGeo::County.new(status: 1)
+      expect(record.imported?).to eq true
+      expect(record.removed?).to eq false
+      expect(record.manual?).to eq false
+    end
+
+    it "should be marked as removed" do
+      record = USGeo::County.new(status: -1)
+      expect(record.imported?).to eq false
+      expect(record.removed?).to eq true
+      expect(record.manual?).to eq false
+    end
+
+    it "should be marked as manual" do
+      record = USGeo::County.new(status: 0)
+      expect(record.imported?).to eq false
+      expect(record.removed?).to eq false
+      expect(record.manual?).to eq true
+    end
+  end
+
+  describe "load!" do
+    after { USGeo::Region.delete_all }
+
+    it "should mark previously imported records as removed" do
+      data = File.read(File.expand_path("../../data/dist/divisions.csv", __dir__))
+      stub_request(:get, "#{USGeo.base_data_uri}/divisions.csv").to_return(body: data, headers: {"Content-Type": "text/csv; charset=UTF-8"})
+
+      midwest = USGeo::Region.new
+      midwest.id = 2
+      midwest.name = "Northwest Territory"
+      midwest.status = USGeo::Region::STATUS_MANUAL
+      midwest.save!
+
+      other = USGeo::Region.new
+      other.id = 90
+      other.name = "Other"
+      other.status = USGeo::Region::STATUS_IMPORTED
+      other.save!
+
+      manual = USGeo::Region.new
+      manual.id = 80
+      manual.name = "Manual"
+      manual.status = USGeo::Region::STATUS_MANUAL
+      manual.save!
+
+      sleep(1)
+      USGeo::Region.load!
+
+      midwest.reload
+      other.reload
+      manual.reload
+
+      expect(midwest.status).to eq USGeo::Region::STATUS_IMPORTED
+      expect(midwest.name).to eq "Midwest"
+      expect(other.status).to eq USGeo::Region::STATUS_REMOVED
+      expect(manual.status).to eq USGeo::Region::STATUS_MANUAL
+    end
+  end
+
+end

data/spec/us_geo/combined_statistical_area_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+describe USGeo::CombinedStatisticalArea do
+
+  describe "associations" do
+    it "should have core_based_statistical_areas" do
+      csa = USGeo::CombinedStatisticalArea.new
+      csa.geoid = "001"
+      expect{ csa.core_based_statistical_areas }.to_not raise_error
+      expect(csa.core_based_statistical_areas.build).to be_a(USGeo::CoreBasedStatisticalArea)
+    end
+  end
+
+  describe "load" do
+    after { USGeo::CombinedStatisticalArea.delete_all }
+
+    it "should load the fixture data" do
+      data = File.read(File.expand_path("../../data/dist/combined_statistical_areas.csv", __dir__))
+      stub_request(:get, "#{USGeo.base_data_uri}/combined_statistical_areas.csv").to_return(body: data, headers: {"Content-Type": "text/csv; charset=UTF-8"})
+      USGeo::CombinedStatisticalArea.load!
+      expect(USGeo::CombinedStatisticalArea.imported.count).to be > 150
+      expect(USGeo::CombinedStatisticalArea.removed.count).to eq 0
+
+      chicagoland = USGeo::CombinedStatisticalArea.find("176")
+      expect(chicagoland.name).to eq "Chicago-Naperville, IL-IN-WI"
+      expect(chicagoland.population).to be > 8_000_000
+      expect(chicagoland.housing_units).to be > 3_000_000
+      expect(chicagoland.land_area.round).to eq 10636
+      expect(chicagoland.water_area.round).to eq 2431
+    end
+  end
+
+end