us_geo 1.0.3 → 2.0.0

data/lib/us_geo/urban_area.rb

@@ -1,22 +1,46 @@
 # 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
+    include Area
+    include Population
 
     self.primary_key = "geoid"
     self.store_full_sti_class = false
 
+    # !@method urban_area_counties
+    #   @return [ActiveRecord::Relation<USGeo::UrbanAreaCounty>] County to urban area mapping.
     has_many :urban_area_counties, foreign_key: :urban_area_geoid, inverse_of: :urban_area, dependent: :destroy
+
+    # !@method counties
+    #   @return [ActiveRecord::Relation<USGeo::County>] Counties that overlap with the urban area.
     has_many :counties, through: :urban_area_counties
+
+    # !@method primary_county
+    #   @return [USGeo::County] Primary county that contains most of the urban area.
     belongs_to :primary_county, foreign_key: :primary_county_geoid, class_name: "USGeo::County"
-    
+
+    # !@method urban_area_county_subdivisions
+    #   @return [ActiveRecord::Relation<USGeo::UrbanAreaCountySubdivision>] County subdivision to urban area mapping.
+    has_many :urban_area_county_subdivisions, foreign_key: :urban_area_geoid, inverse_of: :urban_area, dependent: :destroy
+
+    # !@method county_subdivisions
+    #   @return [ActiveRecord::Relation<USGeo::CountySubdivision>] County subdivisions that overlap with the urban area.
+    has_many :county_subdivisions, through: :urban_area_county_subdivisions
+
+    # !@method zcta_urban_areas
+    #   @return [ActiveRecord::Relation<USGeo::ZctaUrbanArea>] Zip code to urban area mapping.
     has_many :zcta_urban_areas, foreign_key: :urban_area_geoid, inverse_of: :urban_area, dependent: :destroy
+
+    # !@method zctas
+    #   @return [ActiveRecord::Relation<USGeo::Zcta>] Zip codes that overlap with the urban area.
     has_many :zctas, through: :zcta_urban_areas
 
+    # !@method places
+    #   @return [ActiveRecord::Relation<USGeo::Place>] Places that overlap with the urban area.
+    has_many :places, foreign_key: :urban_area_geoid, inverse_of: :urban_area
+
     validates :geoid, length: {is: 5}
     validates :primary_county_geoid, length: {is: 5}
     validates :name, length: {maximum: 90}
@@ -26,26 +50,33 @@ module USGeo
     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
+    # !@method combined_statistical_area
+    #   @return [USGeo::CombinedStatisticalArea, nil] Combined statistical area that the urban area is a part of.
+    delegate :combined_statistical_area, to: :primary_county, allow_nil: true
+
+    # !@method core_based_statistical_area
+    #   @return [USGeo::CoreBasedStatisticalArea, nil] Core-based statistical area that the urban area is a part of.
+    delegate :core_based_statistical_area, to: :primary_county, allow_nil: true
+
+    # !@method metropolitan_division
+    #   @return [USGeo::MetropolitanDivision, nil] Metropolitan division that the urban area is a part of.
+    delegate :metropolitan_division, 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.type = ((row["Population"].to_i >= 50_000) ? "UrbanizedArea" : "UrbanCluster")
               record.name = row["Name"]
-              record.primary_county_geoid = row["Primary County"]
+              record.short_name = row["Short Name"]
+              record.primary_county_geoid = row["Primary County GEOID"]
               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.land_area = row["Land Area"]
+              record.water_area = row["Water Area"]
               record.lat = row["Latitude"]
               record.lng = row["Longitude"]
             end
@@ -57,10 +88,9 @@ module USGeo
     def urbanized?
       raise NotImplementedError
     end
-    
+
     def cluster?
       raise NotImplementedError
     end
-
   end
 end

data/lib/us_geo/urban_area_county.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
 module USGeo
-
   # Mapping of urban areas to counties they overlap with.
   class UrbanAreaCounty < BaseRecord
-
-    include Demographics
+    include Area
 
     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
@@ -14,31 +12,22 @@ module USGeo
     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"])
+              record.land_area = row["Land Area"]
+              record.water_area = 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
@@ -49,11 +38,6 @@ module USGeo
       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
@@ -63,6 +47,5 @@ module USGeo
     def percent_county_total_area
       total_area / county.total_area
     end
-
   end
 end

data/lib/us_geo/urban_area_county_subdivision.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module USGeo
+  # Mapping of urban areas to counties they overlap with.
+  class UrbanAreaCountySubdivision < BaseRecord
+    include Area
+
+    belongs_to :county_subdivision, foreign_key: :county_subdivision_geoid, inverse_of: :urban_area_county_subdivisions
+    belongs_to :urban_area, foreign_key: :urban_area_geoid, inverse_of: :urban_area_county_subdivisions
+
+    validates :county_subdivision_geoid, length: {is: 10}
+    validates :urban_area_geoid, length: {is: 5}
+    validates :land_area, numericality: true, presence: true
+    validates :water_area, numericality: true, presence: true
+
+    class << self
+      def load!(uri = nil)
+        location = data_uri(uri || "urban_area_county_subdivisions.csv")
+
+        import! do
+          load_data_file(location) do |row|
+            load_record!(urban_area_geoid: row["Urban Area GEOID"], county_subdivision_geoid: row["County Subdivision GEOID"]) do |record|
+              record.land_area = row["Land Area"]
+              record.water_area = row["Water Area"]
+            end
+          end
+        end
+      end
+    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 land area.
+    def percent_county_subdivision_land_area
+      land_area / county_subdivision.land_area
+    end
+
+    # Percentage of the county total area.
+    def percent_county_subdivision_total_area
+      total_area / county_subdivision.total_area
+    end
+  end
+end

data/lib/us_geo/urban_cluster.rb

@@ -1,18 +1,14 @@
 # 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

@@ -1,18 +1,14 @@
 # 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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module USGeo
-  VERSION = "1.0.3"
+  VERSION = File.read(File.expand_path("../../VERSION", __dir__)).chomp.freeze
 end

data/lib/us_geo/zcta.rb

@@ -1,7 +1,6 @@
 # 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
@@ -10,25 +9,74 @@ module USGeo
   # 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.
+  # ZCTA's can span places, but the one with the majority of the residents is identified
+  # as the primary place for when a single area is required.
   class Zcta < BaseRecord
-
-    include Demographics
+    include Population
+    include Area
 
     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
+    # @!method self.for_zipcode
+    #   This scope will search for ZCTA's via the ZCTAMappings table. This is useful
+    #   when you have a retired ZIP code and want to find the current ZCTA for that ZIP code.
+    #
+    #   @param zipcode [String] ZIP code to search for.
+    #   @return [ActiveRecord::Relation] ZCTA's matching the given ZIP code.
+    scope :for_zipcode, ->(zipcode) { left_outer_joins(:zcta_mappings).where(ZctaMapping.table_name => {zipcode: zipcode}).or(left_outer_joins(:zcta_mappings).where(zipcode: zipcode)).distinct }
+
+    # @!method zcta_counties
+    #   @return [ActiveRecord::Relation] ZCTA to county mappings.
+    has_many :zcta_counties, -> { not_removed }, foreign_key: :zipcode, inverse_of: :zcta, dependent: :destroy
+
+    # @!method counties
+    #   @return [ActiveRecord::Relation] Counties that this ZCTA is a part of.
+    has_many :counties, -> { not_removed }, through: :zcta_counties
+
+    # @!method primary_county
+    #   @return [USGeo::County] County that contains most of the ZCTA's land area.
     belongs_to :primary_county, foreign_key: :primary_county_geoid, class_name: "USGeo::County"
 
+    # @!method zcta_urban_areas
+    #   @return [ActiveRecord::Relation] ZCTA to urban area mappings.
     has_many :zcta_urban_areas, foreign_key: :zipcode, inverse_of: :zcta, dependent: :destroy
+
+    # @!method urban_areas
+    #   @return [ActiveRecord::Relation] Urban areas that this ZCTA is a part of.
     has_many :urban_areas, through: :zcta_urban_areas
+
+    # @!method primary_urban_area
+    #   @return [USGeo::UrbanArea] Urban area that contains most of the ZCTA's land area.
     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
+    # @!method zcta_county_subdivisions
+    #   @return [ActiveRecord::Relation] ZCTA to county subdivision mappings.
+    has_many :zcta_county_subdivisions, -> { not_removed }, foreign_key: :zipcode, inverse_of: :zcta, dependent: :destroy
+
+    # @!method county_subdivisions
+    #   @return [ActiveRecord::Relation] County subdivisions that this ZCTA is a part of.
+    has_many :county_subdivisions, -> { not_removed }, through: :zcta_county_subdivisions
+
+    # @!method primary_county_subdivision
+    #   @return [USGeo::CountySubdivision] County subdivision that contains most of the ZCTA's land area.
+    belongs_to :primary_county_subdivision, foreign_key: :primary_county_subdivision_geoid, class_name: "USGeo::CountySubdivision"
+
+    # @!method zcta_places
+    #   @return [ActiveRecord::Relation] ZCTA to place mappings.
+    has_many :zcta_places, -> { not_removed }, foreign_key: :zipcode, inverse_of: :zcta, dependent: :destroy
+
+    # @!method places
+    #   @return [ActiveRecord::Relation] Places that this ZCTA is a part of.
+    has_many :places, -> { not_removed }, through: :zcta_places
+
+    # @!method primary_place
+    #   @return [USGeo::Place] Place that contains most of the ZCTA's land area.
+    belongs_to :primary_place, foreign_key: :primary_place_geoid, class_name: "USGeo::Place"
+
+    # @!method zcta_mappings
+    #   @return [ActiveRecord::Relation] 2010 ZCTA to current ZCTA mappings.
+    has_many :zcta_mappings, -> { not_removed }, foreign_key: :zcta_zipcode, inverse_of: :zcta, dependent: :destroy
 
     validates :zipcode, length: {is: 5}
     validates :land_area, numericality: true, presence: true
@@ -36,7 +84,35 @@ module USGeo
     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
+    # @!attribute zipcode
+    #   @return [String] 5-digit ZIP code.
+
+    # @!method combined_statistical_area
+    #   @return [USGeo::CombinedStatisticalArea, nil] Combined statistical area that contains the ZCTA.
+    delegate :combined_statistical_area, to: :primary_county, allow_nil: true
+
+    # @!method core_based_statistical_area
+    #   @return [USGeo::CoreBasedStatisticalArea, nil] Core-based statistical area that contains the ZCTA.
+    delegate :core_based_statistical_area, to: :primary_county, allow_nil: true
+
+    # @!method metropolitan_division
+    #   @return [USGeo::MetropolitanDivision, nil] Metropolitan division that contains the ZCTA.
+    delegate :metropolitan_division, to: :primary_county, allow_nil: true
+
+    # @!method state
+    #   @return [USGeo::State] State that contains the ZCTA.
+    delegate :state, to: :primary_county, allow_nil: true
+
+    # @!method state_code
+    #   @return [String] State code that contains the ZCTA.
+    delegate :state_code, to: :primary_county, allow_nil: true
+
+    # @!method time_zone
+    #   Get the time zone for the primary county containing the ZCTA. Note that this is not
+    #   necessarily the time zone for the ZCTA itself since a handful of counties span multiple
+    #   time zones.
+    #   @return [ActiveSupport::TimeZone, nil] Time zone for the ZCTA.
+    delegate :time_zone, to: :primary_county, allow_nil: true
 
     class << self
       def load!(uri = nil)
@@ -47,10 +123,12 @@ module USGeo
             load_record!(zipcode: row["ZCTA5"]) do |record|
               record.primary_county_geoid = row["Primary County"]
               record.primary_urban_area_geoid = row["Primary Urban Area"]
+              record.primary_county_subdivision_geoid = row["Primary County Subdivision"]
+              record.primary_place_geoid = row["Primary Place"]
               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.land_area = row["Land Area"]
+              record.water_area = row["Water Area"]
               record.lat = row["Latitude"]
               record.lng = row["Longitude"]
             end
@@ -58,6 +136,5 @@ module USGeo
         end
       end
     end
-
   end
 end

data/lib/us_geo/zcta_county.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
 module USGeo
-
   # Mapping of ZCTA's to counties they overlap with.
   class ZctaCounty < BaseRecord
-
-    include Demographics
+    include Area
 
     belongs_to :zcta, foreign_key: :zipcode, inverse_of: :zcta_counties
     belongs_to :county, foreign_key: :county_geoid, inverse_of: :zcta_counties
@@ -14,31 +12,22 @@ module USGeo
     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"])
+            load_record!(zipcode: row["ZCTA5"], county_geoid: row["County GEOID"]) do |record|
+              record.land_area = row["Land Area"]
+              record.water_area = 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
@@ -49,11 +38,6 @@ module USGeo
       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
@@ -63,6 +47,5 @@ module USGeo
     def percent_county_total_area
       total_area / county.total_area
     end
-
   end
 end

data/lib/us_geo/zcta_county_subdivision.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module USGeo
+  # Mapping of ZCTA's to counties they overlap with.
+  class ZctaCountySubdivision < BaseRecord
+    include Area
+
+    belongs_to :zcta, foreign_key: :zipcode, inverse_of: :zcta_county_subdivisions
+    belongs_to :county_subdivision, foreign_key: :county_subdivision_geoid, inverse_of: :zcta_county_subdivisions
+
+    validates :zipcode, length: {is: 5}
+    validates :county_subdivision_geoid, length: {is: 10}
+    validates :land_area, numericality: true, presence: true
+    validates :water_area, numericality: true, presence: true
+
+    class << self
+      def load!(uri = nil)
+        location = data_uri(uri || "zcta_county_subdivisions.csv")
+
+        import! do
+          load_data_file(location) do |row|
+            load_record!(zipcode: row["ZCTA5"], county_subdivision_geoid: row["County Subdivision GEOID"]) do |record|
+              record.land_area = row["Land Area"]
+              record.water_area = row["Water Area"]
+            end
+          end
+        end
+      end
+    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 subdivision land area.
+    def percent_county_subdivision_land_area
+      land_area / county_subdivision.land_area
+    end
+
+    # Percentage of the county subdivision total area.
+    def percent_county_subdivision_total_area
+      total_area / county_subdivision.total_area
+    end
+  end
+end

data/lib/us_geo/zcta_mapping.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module USGeo
+  # Mapping of ZIP codes to currently active ZCTA's. The U.S. Postal Service
+  # maintains the list of active ZIP codes which can change as population moves
+  # around. New ZIP codes are created when a new area is developed and old ZIP
+  # are retired when an area is losing population. The Census Bureau updates
+  # the list of ZCTA's every 10 years.
+  #
+  # This mapping table allows looking up the current ZCTA for a ZIP code even
+  # if that ZIP code was retired and is no longer in the ZCTA table.
+  class ZctaMapping < BaseRecord
+    self.table_name = "us_geo_zcta_mappings"
+    self.primary_key = "zipcode"
+
+    belongs_to :zcta, foreign_key: :zcta_zipcode, inverse_of: :zcta_mappings
+
+    validates :zipcode, length: {is: 5}
+    validates :zcta_zipcode, length: {is: 5}
+
+    class << self
+      def load!(uri = nil)
+        location = data_uri(uri || "zcta_mappings.csv")
+
+        import! do
+          load_data_file(location) do |row|
+            load_record!(zipcode: row["ZIP Code"]) do |record|
+              record.zcta_zipcode = row["Active ZCTA5"]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/us_geo/zcta_place.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
 module USGeo
-
-  # Mapping of ZCTA's to urban areas they overlap with.
+  # Mapping of ZCTA's to places they overlap with.
   class ZctaPlace < BaseRecord
-
-    include Demographics
+    include Area
 
     belongs_to :zcta, foreign_key: :zipcode, inverse_of: :zcta_places
     belongs_to :place, foreign_key: :place_geoid, inverse_of: :zcta_places
@@ -14,20 +12,16 @@ module USGeo
     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"])
+              record.land_area = row["Land Area"]
+              record.water_area = row["Water Area"]
             end
           end
         end
@@ -63,6 +57,5 @@ module USGeo
     def percent_place_total_area
       total_area / place.total_area
     end
-
   end
 end