us_geo 1.0.3 → 2.0.0

data/lib/us_geo/county.rb

@@ -1,45 +1,70 @@
 # frozen_string_literal: true
 
 module USGeo
-
   # County or county equivalent. Counties are composed of zero or more ZCTA's and may
   # belong to a CBSA. The county's significance withing the CBSA is indicated by the
   # central flag which indicates if it is a central or outlying county.
   class County < BaseRecord
-
-    include Demographics
+    include Population
+    include Area
 
     self.primary_key = "geoid"
 
-    belongs_to :designated_market_area, foreign_key: :dma_code, optional: true, inverse_of: :counties
     belongs_to :core_based_statistical_area, foreign_key: :cbsa_geoid, optional: true, inverse_of: :counties
     belongs_to :metropolitan_division, foreign_key: :metropolitan_division_geoid, optional: true, inverse_of: :counties
     belongs_to :state, foreign_key: :state_code, inverse_of: :counties
 
-    has_many :subdivisions, foreign_key: :county_geoid, inverse_of: :county, class_name: "USGeo::CountySubdivision"
+    has_many :subdivisions, -> { not_removed }, foreign_key: :county_geoid, inverse_of: :county, class_name: "USGeo::CountySubdivision"
 
-    has_many :zcta_counties, foreign_key: :county_geoid, inverse_of: :county, dependent: :destroy
-    has_many :zctas, through: :zcta_counties
+    has_many :zcta_counties, -> { not_removed }, foreign_key: :county_geoid, inverse_of: :county, dependent: :destroy
+    has_many :zctas, -> { not_removed }, through: :zcta_counties
 
     has_many :urban_area_counties, foreign_key: :county_geoid, inverse_of: :county, dependent: :destroy
     has_many :urban_areas, through: :urban_area_counties
 
-    has_many :place_counties, foreign_key: :county_geoid, inverse_of: :county, dependent: :destroy
-    has_many :places, through: :place_counties
+    has_many :place_counties, -> { not_removed }, foreign_key: :county_geoid, inverse_of: :county, dependent: :destroy
+    has_many :places, -> { not_removed }, through: :place_counties
 
     validates :geoid, length: {is: 5}
-    validates :name, length: {maximum: 60}
-    validates :short_name, length: {maximum: 30}
+    validates :name, presence: true, length: {maximum: 60}, uniqueness: {scope: :state_code}
+    validates :short_name, presence: true, length: {maximum: 30}, uniqueness: {scope: :state_code}
     validates :state_code, length: {is: 2}
     validates :fips_class_code, length: {is: 2}
     validates :metropolitan_division_geoid, length: {is: 5}, allow_nil: true
     validates :cbsa_geoid, length: {is: 5}, allow_nil: true
-    validates :dma_code, length: {is: 3}, allow_nil: true
     validates :land_area, numericality: true, allow_nil: true
     validates :water_area, numericality: true, allow_nil: true
     validates :population, numericality: {only_integer: true}, allow_nil: true
     validates :housing_units, numericality: {only_integer: true}, allow_nil: true
 
+    # @!attribute geoid
+    #   @return [String] 5-digit code for the county.
+
+    # @!attribute name
+    #   @return [String] Name of the county.
+
+    # @!attribute short_name
+    #   @return [String] Short name of the county.
+
+    # @!attribute state_code
+    #   @return [String] 2-letter code for the state.
+
+    # @!attribute fips_class_code
+    #   @return [String] 2-character FIPS class code.
+
+    # @!attribute time_zone_name
+    #   @return [String] Time zone name.
+
+    # @!attribute time_zone_2_name
+    #   @return [String] Time zone name.
+
+    # @!method central?
+    #   @return [Boolean] True if the county is a central county in the CBSA.
+
+    # @!method combined_statistical_area
+    #   @return [USGeo::CombinedStatisticalArea] Combined statistical area that the county belongs to.
+    delegate :combined_statistical_area, to: :core_based_statistical_area, allow_nil: true
+
     class << self
       def load!(uri = nil)
         location = data_uri(uri || "counties.csv")
@@ -53,14 +78,14 @@ module USGeo
               record.state_code = row["State"]
               record.cbsa_geoid = row["CBSA"]
               record.metropolitan_division_geoid = row["Metropolitan Division"]
-              record.dma_code = row["DMA"]
               record.time_zone_name = row["Time Zone"]
+              record.time_zone_2_name = row["Time Zone 2"]
               record.fips_class_code = row["FIPS Class"]
               record.central = (row["Central"] == "T")
               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
@@ -69,6 +94,13 @@ module USGeo
       end
     end
 
+    # Full name of the county with the state.
+    #
+    # @return [String]
+    def full_name
+      "#{name}, #{state_code}"
+    end
+
     def state_fips
       geoid[0, 2]
     end
@@ -79,12 +111,31 @@ module USGeo
 
     # Return the CBSA only if it is a metropolitan area.
     def metropolitan_area
-      core_based_statistical_area if core_based_statistical_area && core_based_statistical_area.metropolitan?
+      core_based_statistical_area if core_based_statistical_area&.metropolitan?
     end
 
+    # Return a single time zone for the county. If the county has two time zones,
+    # only one is returned.
+    #
+    # @return [ActiveSupport::TimeZone, nil]
     def time_zone
       ActiveSupport::TimeZone[time_zone_name] if time_zone_name
     end
 
+    # Get all time zones for the county.
+    #
+    # @return [Array<ActiveSupport::TimeZone>]
+    def time_zones
+      [time_zone_name, time_zone_2_name].compact.collect do |tz_name|
+        ActiveSupport::TimeZone[tz_name]
+      end.compact
+    end
+
+    # True if the county is an outlying county in the CBSA.
+    #
+    # @return [Boolean]
+    def outlying?
+      !central?
+    end
   end
 end

data/lib/us_geo/county_subdivision.rb

@@ -1,24 +1,58 @@
 # frozen_string_literal: true
 
 module USGeo
-
   # County subdivision.
   class CountySubdivision < BaseRecord
-
-    include Demographics
+    include Population
+    include Area
 
     self.primary_key = "geoid"
 
     belongs_to :county, foreign_key: :county_geoid, inverse_of: :subdivisions
 
+    has_many :zcta_county_subdivisions, -> { not_removed }, foreign_key: :county_subdivision_geoid, inverse_of: :county_subdivision, dependent: :destroy
+    has_many :zctas, -> { not_removed }, through: :zcta_county_subdivisions
+
+    has_many :urban_area_county_subdivisions, foreign_key: :county_subdivision_geoid, inverse_of: :county_subdivision, dependent: :destroy
+    has_many :urban_areas, through: :urban_area_county_subdivisions
+
     validates :geoid, length: {is: 10}
-    validates :name, length: {maximum: 60}
+    validates :name, presence: true, length: {maximum: 60}, uniqueness: {scope: :county_geoid}
     validates :fips_class_code, length: {is: 2}
     validates :land_area, numericality: true, allow_nil: true
     validates :water_area, numericality: true, allow_nil: true
     validates :population, numericality: {only_integer: true}, allow_nil: true
     validates :housing_units, numericality: {only_integer: true}, allow_nil: true
 
+    # @!attribute geoid
+    #   @return [String] 10-digit code for the subdivision.
+
+    # @!attribute name
+    #   @return [String] Name of the subdivision.
+
+    # @!attribute fips_class_code
+    #   @return [String] 2-character FIPS class code.
+
+    # @!method :core_based_statistical_area
+    #   @return [CoreBasedStatisticalArea] Core-based statistical area the subdivision is in.
+    delegate :core_based_statistical_area, to: :county
+
+    # @!method :combined_statistical_area
+    #   @return [CombinedStatisticalArea] Combined statistical area the subdivision is in.
+    delegate :combined_statistical_area, to: :county
+
+    # @!method :metropolitan_division
+    #   @return [MetropolitanDivision] Metropolitan division the subdivision is in.
+    delegate :metropolitan_division, to: :county
+
+    # @!method :state
+    #   @return [State] State the subdivision is in.
+    delegate :state, to: :county
+
+    # @!method :state_code
+    #   @return [String] 2-character state code.
+    delegate :state_code, to: :county
+
     class << self
       def load!(uri = nil)
         location = data_uri(uri || "county_subdivisions.csv")
@@ -32,15 +66,17 @@ module USGeo
               record.fips_class_code = row["FIPS Class"]
               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"]
+
+              duplicate = where.not(geoid: record.geoid).find_by(name: record.name, county_geoid: record.county_geoid)
+              duplicate&.update!(name: "#{record.name} (deleted)", status: BaseRecord::STATUS_REMOVED)
             end
           end
         end
       end
     end
-
   end
 end

data/lib/us_geo/division.rb

@@ -1,29 +1,39 @@
 # frozen_string_literal: true
 
 module USGeo
-
   # U.S. regional division composed of states.
   class Division < BaseRecord
+    include Population
+    include Area
 
     belongs_to :region, inverse_of: :divisions
-    has_many :states, inverse_of: :division
+    has_many :states, -> { not_removed }, inverse_of: :division
+
+    validates :name, presence: true, length: {maximum: 30}, uniqueness: true
+
+    # @!attribute id
+    #   @return [Integer] ID of the division.
 
-    validates :name, length: {maximum: 30}
+    # @!attribute name
+    #   @return [String] Name of the division.
 
     class << self
       def load!(uri = nil)
         location = data_uri(uri || "divisions.csv")
-        
+
         import! do
           load_data_file(location) do |row|
-            load_record!(id: row["Division ID"]) do |record|
-              record.name = row["Division Name"]
+            load_record!(id: row["ID"]) do |record|
+              record.name = row["Name"]
               record.region_id = row["Region ID"]
+              record.population = row["Population"]
+              record.housing_units = row["Housing Units"]
+              record.land_area = row["Land Area"]
+              record.water_area = row["Water Area"]
             end
           end
         end
       end
     end
-
   end
 end

data/lib/us_geo/metropolitan_area.rb

@@ -1,18 +1,14 @@
 # frozen_string_literal: true
 
 module USGeo
-
   # Core based statistical area with a population greater then 50,000.
   class MetropolitanArea < CoreBasedStatisticalArea
-    
     def metropolitan?
       true
     end
-    
+
     def micropolitan?
       false
     end
-    
   end
-  
 end

data/lib/us_geo/metropolitan_division.rb

@@ -1,23 +1,32 @@
 # frozen_string_literal: true
 
 module USGeo
-
   # Division of very large metropolitian areas into groups of approximately 2.5 million people.
   class MetropolitanDivision < BaseRecord
-
-    include Demographics
+    include Population
+    include Area
 
     self.primary_key = "geoid"
 
-    has_many :counties, foreign_key: :metropolitan_division_geoid, inverse_of: :metropolitan_division
+    has_many :counties, -> { not_removed }, foreign_key: :metropolitan_division_geoid, inverse_of: :metropolitan_division
     belongs_to :core_based_statistical_area, foreign_key: :cbsa_geoid, optional: true, inverse_of: :metropolitan_divisions
 
     validates :geoid, length: {is: 5}
-    validates :name, length: {maximum: 60}
+    validates :name, presence: true, length: {maximum: 60}, uniqueness: true
     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
+    validates :housing_units, numericality: {only_integer: true}, presence: true
+
+    # @!attribute geoid
+    #   @return [String] 5-digit code for the metropolitan division.
+
+    # @!attribute name
+    #   @return [String] Name of the metropolitan division.
+
+    # @!method combined_statistical_area
+    #   @return [CombinedStatisticalArea, nil] Combined statistical area that the metropolitan division is a part of.
+    delegate :combined_statistical_area, to: :core_based_statistical_area, allow_nil: true
 
     class << self
       def load!(uri = nil)
@@ -30,13 +39,12 @@ module USGeo
               record.cbsa_geoid = row["CBSA"]
               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
-
   end
 end

data/lib/us_geo/micropolitan_area.rb

@@ -1,18 +1,14 @@
 # frozen_string_literal: true
 
 module USGeo
-
   # Core based statistical area with a population greater then 10,000 but less than 50,000.
   class MicropolitanArea < CoreBasedStatisticalArea
-    
     def metropolitan?
       false
     end
-    
+
     def micropolitan?
       true
     end
-    
   end
-  
 end

data/lib/us_geo/place.rb

@@ -1,29 +1,46 @@
 # frozen_string_literal: true
 
 module USGeo
-
   # Division of very large metropolitian areas into groups of approximately 2.5 million people.
   class Place < BaseRecord
-
-    include Demographics
+    include Population
+    include Area
 
     self.primary_key = "geoid"
 
-    has_many :zcta_places, foreign_key: :place_geoid, inverse_of: :place, dependent: :destroy
-    has_many :zctas, through: :zcta_places
+    # !@method zcta_places
+    #   @return [ActiveRecord::Relation<ZctaPlace>] ZCTA to place mapping.
+    has_many :zcta_places, -> { not_removed }, foreign_key: :place_geoid, inverse_of: :place, dependent: :destroy
+
+    # !@method zctas
+    #   @return [ActiveRecord::Relation<Zcta>] ZCTA's that overlap with this place.
+    has_many :zctas, -> { not_removed }, through: :zcta_places
 
-    has_many :place_counties, foreign_key: :place_geoid, inverse_of: :place, dependent: :destroy
-    has_many :counties, through: :place_counties
+    # !@method place_counties
+    #   @return [ActiveRecord::Relation<PlaceCounty>] Place to county mapping.
+    has_many :place_counties, -> { not_removed }, foreign_key: :place_geoid, inverse_of: :place, dependent: :destroy
 
+    # !@method counties
+    #   @return [ActiveRecord::Relation<County>] Counties that this place is a part of.
+    has_many :counties, -> { not_removed }, through: :place_counties
+
+    # !@method primary_county
+    #   @return [County] County that contains most of the place.
     belongs_to :primary_county, foreign_key: :primary_county_geoid, class_name: "USGeo::County"
+
+    # !@method urban_area
+    #   @return [UrbanArea] Urban area that the place is a part of.
     belongs_to :urban_area, foreign_key: :urban_area_geoid, optional: true, class_name: "USGeo::UrbanArea"
+
+    # !@method state
+    #   @return [State] State that the place is in.
     belongs_to :state, foreign_key: :state_code, inverse_of: :places
 
     validates :geoid, length: {is: 7}
     validates :state_code, length: {is: 2}
     validates :primary_county_geoid, length: {is: 5}
     validates :urban_area_geoid, length: {is: 5}, allow_nil: true
-    validates :name, length: {maximum: 60}
+    validates :name, presence: true, length: {maximum: 60}
     validates :short_name, length: {maximum: 30}
     validates :fips_class_code, length: {is: 2}
     validates :land_area, numericality: true, allow_nil: true
@@ -31,6 +48,40 @@ module USGeo
     validates :population, numericality: {only_integer: true}, allow_nil: true
     validates :housing_units, numericality: {only_integer: true}, allow_nil: true
 
+    # @!attribute geoid
+    #   @return [String] 7-digit code for the place.
+
+    # @!attribute name
+    #   @return [String] Name of the place.
+
+    # @!attribute short_name
+    #   @return [String] Short name of the place.
+
+    # @!attribute state_code
+    #   @return [String] 2-letter code for the state.
+
+    # @!attribute fips_class_code
+    #   @return [String] 2-character FIPS class code.
+
+    # @!method combined_statistical_area
+    #   @return [CombinedStatisticalArea, nil] Combined statistical area that the place is a part of.
+    delegate :combined_statistical_area, to: :primary_county, allow_nil: true
+
+    # @!method core_based_statistical_area
+    #   @return [CoreBasedStatisticalArea, nil] Core-based statistical area that the place is a part of.
+    delegate :core_based_statistical_area, to: :primary_county, allow_nil: true
+
+    # @!method metropolitan_division
+    #   @return [MetropolitanDivision, nil] Metropolitan division that the place is a part of.
+    delegate :metropolitan_division, to: :primary_county, allow_nil: true
+
+    # Full name of the place as short name plus the state.
+    #
+    # @return [String]
+    def full_name
+      "#{short_name}, #{state_code}"
+    end
+
     class << self
       def load!(uri = nil)
         location = data_uri(uri || "places.csv")
@@ -47,8 +98,8 @@ module USGeo
               record.fips_class_code = row["FIPS Class"]
               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
@@ -56,6 +107,5 @@ module USGeo
         end
       end
     end
-
   end
 end

data/lib/us_geo/place_county.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 
 module USGeo
-
-  # Mapping of urban areas to counties they overlap with.
+  # Mapping of places to counties they overlap with.
   class PlaceCounty < BaseRecord
-
     belongs_to :county, foreign_key: :county_geoid, inverse_of: :place_counties
     belongs_to :place, foreign_key: :place_geoid, inverse_of: :place_counties
 
@@ -23,6 +21,5 @@ module USGeo
         end
       end
     end
-
   end
 end

data/lib/us_geo/population.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module USGeo
+  # This module is mixed into all models with a population and land area.
+  module Population
+    # @!attribute population
+    #   @return [Integer, nil] Total population of the area.
+
+    # @!attribute housing_units
+    #   @return [Integer, nil] Total housing units in the area.
+
+    # Population per square mile.
+    #
+    # @return [Float, nil]
+    def population_density
+      population.to_f / land_area if population && land_area.to_f > 0
+    end
+
+    # Population per square kilometer.
+    #
+    # @return [Float, nil]
+    def population_density_km
+      population.to_f / land_area_km if population && land_area.to_f > 0
+    end
+  end
+end

data/lib/us_geo/region.rb

@@ -1,28 +1,38 @@
 # frozen_string_literal: true
 
 module USGeo
-
   # U.S. region.
   class Region < BaseRecord
+    include Population
+    include Area
+
+    has_many :divisions, -> { not_removed }, inverse_of: :region
+    has_many :states, -> { not_removed }, inverse_of: :region
 
-    has_many :divisions, inverse_of: :region
-    has_many :states, inverse_of: :region
+    validates :name, presence: true, length: {maximum: 30}, uniqueness: true
 
-    validates :name, length: {maximum: 30}
+    # @!attribute id
+    #   @return [Integer] ID of the region.
+
+    # @!attribute name
+    #   @return [String] Name of the region.
 
     class << self
       def load!(uri = nil)
-        location = data_uri(uri || "divisions.csv")
+        location = data_uri(uri || "regions.csv")
 
         import! do
           load_data_file(location) do |row|
-            load_record!(id: row["Region ID"]) do |record|
-              record.name = row["Region Name"]
+            load_record!(id: row["ID"]) do |record|
+              record.name = row["Name"]
+              record.population = row["Population"]
+              record.housing_units = row["Housing Units"]
+              record.land_area = row["Land Area"]
+              record.water_area = row["Water Area"]
             end
           end
         end
       end
     end
-
   end
 end

data/lib/us_geo/state.rb

@@ -1,31 +1,49 @@
 # frozen_string_literal: true
 
 module USGeo
-
   # U.S. state or territory.
   class State < BaseRecord
+    include Population
+    include Area
 
     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}
+    has_many :counties, -> { not_removed }, foreign_key: :state_code, inverse_of: :state
+    has_many :places, -> { not_removed }, foreign_key: :state_code, inverse_of: :state
+
+    validates :code, length: {is: 2}, uniqueness: true
     validates :fips, length: {is: 2}
-    validates :name, length: {maximum: 30}
+    validates :name, presence: true, length: {maximum: 30}, uniqueness: true
     validates :type, inclusion: [STATE_TYPE, DISTRICT_TYPE, TERRITORY_TYPE]
 
+    # @!attribute code
+    #   @return [String] 2-letter postal code of the state.
+
+    # @!attribute name
+    #   @return [String] Name of the state.
+
+    # @!attribute fips
+    #   @return [String] 2-digit FIPS code of the state.
+
+    # @!attribute type
+    #   @return [String] Type of the state or territory.
+
+    # @!method :region
+    #   @return [Region] Region the state is in.
+    delegate :region, to: :division, allow_nil: true
+
     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|
@@ -34,23 +52,26 @@ module USGeo
               record.fips = row["FIPS"]
               record.region_id = row["Region ID"]
               record.division_id = row["Division ID"]
+              record.population = row["Population"]
+              record.housing_units = row["Housing Units"]
+              record.land_area = row["Land Area"]
+              record.water_area = row["Water Area"]
             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