Class: Audumbla::Enrichments::CoarseGeocode

Inherits:
Object
  • Object
show all
Includes:
FieldEnrichment
Defined in:
lib/audumbla/enrichments/coarse_geocode.rb

Overview

Enriches a ‘DPLA::MAP::Place` node by running its data through external geocoders, using heuristics to determine a matching feature from GeoNames, and repopulating the `Place` with related data.

If the existing ‘Place` contains data other than a `providedLabel`, that data will be used as context for evaluating interpretations. For example: a `Place` with an existing latitude and longitude will verify that the point is within the bounding box for a candidate match.

‘skos:exactMatch` are reserved for the GeoNames features returned by the geocoder. Other matching URIs (currently: LC authorities) are included as `skos:closeMatch`

Configuration is handled through a YAML file passed into the initializer (default: ‘geocode.yml’). The options are:

- 'twofishes_host': the hostname for the twofishes server (default: 
    'localhost')
- 'twofishes_port': the port of the twofishes geocode endpoint (default: 
     8080)
- 'twofishes_timeout': request timeout in seconds (default: 3)
- 'twofishes_retries': request retry maximum for twofishes (default: 2)
- 'distance_threshold': the maximum distance between a set of coordinates
     in the  input object and a candidate match before we judge it a 
     false positive, given in kilometers. (default: 5)
- 'max_intepretations': the number of geocoded "interpretations" to 
    request from the server; these are the places that will be considered
    by the internal heuristics (defualt: 5).

Examples:

enriching from a ‘#providedLabel`


place = DPLA::MAP::Place.new.tap { |p| p.providedLabel = 'Georgia' }
CoarseGeocode.new.enrich_value.dump :ttl
# [
#    a <http://www.europeana.eu/schemas/edm/Place>;
#    <http://dp.la/about/map/providedLabel> "Georgia";
#    <http://www.geonames.org/ontology#countryCode> "US";
#    <http://www.w3.org/2003/01/geo/wgs84_pos#lat> 3.275042e1;
#    <http://www.w3.org/2003/01/geo/wgs84_pos#long> -8.350018e1;
#    <http://www.w3.org/2004/02/skos/core#closeMatch> <http://id.loc.gov/authorities/names/n79023113>;
#    <http://www.w3.org/2004/02/skos/core#exactMatch> <http://sws.geonames.org/4197000/>;
#    <http://www.w3.org/2004/02/skos/core#prefLabel> "Georgia, United States"
# ] .

enriching from a ‘#providedLabel` with lat/lng guidance


place = DPLA::MAP::Place.new.tap do |p| 
  p.providedLabel = 'Georgia'
  p.lat = 41.9997
  p.long = 43.4998
end

CoarseGeocode.new.enrich_value.dump :ttl
# [
#    a <http://www.europeana.eu/schemas/edm/Place>;
#    <http://dp.la/about/map/providedLabel> "Georgia";
#    <http://www.geonames.org/ontology#countryCode> "GE";
#    <http://www.w3.org/2003/01/geo/wgs84_pos#lat> 4.199998e1;
#    <http://www.w3.org/2003/01/geo/wgs84_pos#long> 4.34999e1;
#    <http://www.w3.org/2004/02/skos/core#exactMatch> <http://sws.geonames.org/614540/>;
#    <http://www.w3.org/2004/02/skos/core#prefLabel> "Georgia"
# ] .

Constant Summary collapse

DEFAULT_DISTANCE_THRESHOLD_KMS = 
100
DEFAULT_MAX_INTERPRETATIONS = 
5
DEFAULT_TWOFISHES_HOST = 
'localhost'
DEFAULT_TWOFISHES_PORT = 
8080
DEFAULT_TWOFISHES_TIMEOUT = 
10
DEFAULT_TWOFISHES_RETRIES = 
2

Instance Method Summary collapse

Methods included from FieldEnrichment

#enrich, #enrich_all, #enrich_field

Methods included from Audumbla::Enrichment

#enrich, #enrich!, #list_fields

Constructor Details

#initialize(config_file = 'geocode.yml') ⇒ CoarseGeocode

Returns a new instance of CoarseGeocode.

Parameters:

  • config_file (String) (defaults to: 'geocode.yml') —

    a path to a config file for the geocoder; default: ‘geocode.yml’



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/audumbla/enrichments/coarse_geocode.rb', line 82

def initialize(config_file = 'geocode.yml')
  config = YAML.load_file(config_file)

  @distance_threshold = config.fetch('distance_threshold', 
                                     DEFAULT_DISTANCE_THRESHOLD_KMS)
  @max_interpretations = config.fetch('max_interpretations', 
                                      DEFAULT_MAX_INTERPRETATIONS)

  Twofishes.configure do |twofish|
    twofish.host = config.fetch('twofishes_host', DEFAULT_TWOFISHES_HOST)
    twofish.port = config.fetch('twofishes_port', DEFAULT_TWOFISHES_PORT)
    twofish.timeout = config.fetch('twofishes_timeout', 
                                   DEFAULT_TWOFISHES_TIMEOUT)
    twofish.retries = config.fetch('twofishes_retries', 
                                   DEFAULT_TWOFISHES_RETRIES)
  end
end

Instance Method Details

#enrich_value(value) ⇒ DPLA::MAP::Place

Enriches the given value against the TwoFishes coarse geocoder. This process adds a ‘skos:exactMatch` for a matching GeoNames URI, if any, and populates the remaining place data to the degree possible from the matched feature.

Considers a number of matches specified by ‘@max_interpretations` and returned by Twofishes, via `#match?`.

Parameters:

  • value (DPLA::MAP::Place) —

    the place to geocode

Returns:

  • (DPLA::MAP::Place) —

    the inital place, enriched via coarse geocoding



112
113
114
115
116
117
118
119
 
# File 'lib/audumbla/enrichments/coarse_geocode.rb', line 112

def enrich_value(value)
  return value unless value.is_a? DPLA::MAP::Place
  interpretations = geocode(value.providedLabel.first, 
                            [],
                            maxInterpretations: @max_interpretations)
  match = interpretations.find { |interp| match?(interp, value) }
  match.nil? ? value : enrich_place(value, match.feature)
end

#match?(interpretation, place) ⇒ Boolean

Checks that we are satisfied with the geocoder’s best matches prior to acceptance. Most tweaks to the geocoding process should be taken care of at the geocoder itself, but a simple accept/reject of the points offered is possible here. This allows existing data about the place to be used as context.

For example, this method returns false if ‘place` contains latitude and longitude, but the candidate match has a geometry far away from those given. “far away” is defined by `@distance_threshold` from the center of the candidate feature to the point given by `#lat` and `#long` in `place`.

Parameters:

  • interpretation (GeocodeInterpretation) —

    a twofishes interpretation

  • place (#lat#long) —

    a place to verify a match against

Returns:

  • (Boolean) 


137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/audumbla/enrichments/coarse_geocode.rb', line 137

def match?(interpretation, place)
  return true if place.lat.empty? || place.long.empty?

  point = Geokit::LatLng.new(place.lat.first, place.long.first)
  if interpretation.geometry.bounds.nil?
    # measure distance between point centers
    distance = twofishes_point_to_geokit(interpretation.geometry.center)
               .distance_to(point, unit: :kms)
    return distance < @distance_threshold
  end
    
  twofishes_bounds_to_geokit(interpretation.geometry.bounds)
    .contains?(point)
end