minsci.geobots package

Submodules

minsci.geobots.containers module

Containers with methods to store/filter data about geographical features

class minsci.geobots.containers.GeoList(*args, **kwargs)

Bases: list

List of GeoNames features with various filtering methods

Each item in the list is a GeoNames JSON object as a dict.

filter_matches(countries=None, state=None, county=None)

Filters matches based on country, state, and county

Parameters:

• countries (mixed) – the name of a country or countries
• state (str) – the name of a state or province
• county (str) – the name of a country or district

Returns:

A GeoList object containing the highest-scoring localities

static get_names(feature, include_alts=True)

Returns variants on the name of a give feature

The complete list of alternative names is only returned if the GeoNames ID is queried directly; other requests return only a subset of all possible names.

Parameters:

• feature (dict) – the GeoName JSON object as a dict
• include_alts (bool) – specifies whether to include alternative names (synonyms, other languages, etc.)

Returns:

List of the various names for this feature

get_site_data()

Returns a summary of site data for each site in this list

match_name(name, kind)

Returns features matching the given name

Parameters:

• name (str) – the name of the feature to match
• kind (str) – the type of feature. Used to trim general terms from feature names to improve matching.

Returns:

A GeoList object containing the features matching the given name

pprint(pause=False)

Pretty prints the contents of the list

Parameters:pause (bool) – specifies whether to pause script after printing

class minsci.geobots.containers.Site(id, source, names, kind, code)

Bases: tuple

code

Alias for field number 4

id

Alias for field number 0

kind

Alias for field number 3

names

Alias for field number 2

source

Alias for field number 1

minsci.geobots.containers.format_name(val)

Standardizes the format of a string to improve comparisons

Parameters:val (str) – the string to be formatted Returns:Formatted string

minsci.geobots.containers.normalize_name(name, kind, for_query=False)

Normalizes the format of a name to improve matching

Parameters:

• name (str) – the name of the feature
• kind (str) – the type of feature. Used to trim general terms from feature names to improve matching.
• for_query (bool) – specifies whether the name is being normalized to create a query for the GeoNames webservice (as opposed to filtering a set of matches).

Returns:

String with the normalized name

minsci.geobots.containers.score_match(name, ref_name, kind=None)

Score the similarity of two place names

Parameters:

• name (str) – a feature name
• ref_name (str) – a feature name to compare against name
• kind (str) – the type of feature. Used to trim general terms from feature names to improve matching.

Returns:

Score corresponding to quality of match

minsci.geobots.geobots module

Defines a requests session customized to interact with GeoNames

class minsci.geobots.geobots.GEOLocateBot(wait, *args, **kwargs)

Bases: minsci.geobots.geobots.GeoBot

A cacheable requests object customized for GEOLocate webservices

FIXME: This whole class needs to be cleaned up and tested

static geolocate_to_emu(result, payload)

Create EMu import based on GeoLocate result

search(loc_string, country, state, county=None, **kwargs)

Use the GeoLocate webservice to geolocate the query string

Parameters:

• loc_string (str) – a query string
• country (str) – name or abbreviation of country
• state (str) – name or abbreviation of state or equivalent
• country – name of county or equivalent

Returns:

Tuple including best match and payload. Best match is a list including lat, lng, radius, precision, and score of match. payload is a dict of search parameters.

class minsci.geobots.geobots.GeoBot(wait, *args, **kwargs)

Bases: requests_cache.core.CachedSession

Methods to handle and retry HTTP requests for georeferencing

class minsci.geobots.geobots.GeoNamesBot(username, user_id=None)

Bases: minsci.geobots.geobots.GeoBot

A cacheable requests object customized for GeoNames webservices

username

str – a valid username for GeoNames

headers

dict – headers data for requests

country_subdivision(lat, lng, dec_places=None)

Returns basic geographical information for a lat-long pair

Parameters:

• lat (float) – latitide
• lng (float) – longitude
• dec_places (int) – decimal places

Returns:

JSON representation of point

find_nearby(lat, lng, dec_places=None)

Returns geographical information for a lat-long pair

Parameters:

• lat (float) – latitide
• lng (float) – longitude
• dec_places (int) – decimal places

Returns:

JSON representation of point

get_by_id(geoname_id)

Returns feature data for a given GeoNames ID

Parameters:geoname_id (str) – the ID of a feature in GeoNames Returns:JSON representation of the matching feature

search(query, countries=None, **params)

Searches all GeoNames fields for a query string

Parameters:

• query (str) – query string
• countries (mixed) – a list or pipe-delimited string of countries
• featureClass (list) –
• featureCode (list) –

Returns:

JSON representation of matching locations

class minsci.geobots.geobots.TownshipGeocoder(wait, *args, **kwargs)

Bases: minsci.geobots.geobots.GeoBot

A cacheable requests object customized for BLM geocoder webservice

geocommunicator(trs, state, meridian=None)

Use the BLM TownshipGeocoder webservice to geolocate TRS

Parameters:

• trs (str) – well-formed section-township-range
• state (str) – name or abbreviation of a U.S. state
• meridian (str) – number of principal meridian. This is required to geolocate a TRS, but rarely recorded, so the function will try out all principal meridians in a state if it is not provided.

Returns:

List of lat-lng pairs

minsci.geobots.geobots.dec2dms(dec, is_lat)

Converts decimal degrees to degrees-minutes-seconds

Parameters:

• dec (float) – a coordinate as a decimal
• is_lat (bool) – specifies if the coordinate is a latitude

Returns:

Coordinate in degrees-minutes-seconds

minsci.geobots.geobots.distance_on_unit_sphere(lat1, long1, lat2, long2)

Calculates the distance in km between two points on a sphere

From http://www.johndcook.com/blog/python_longitude_latitude/

Parameters:

• lat1 (int or float) – latitude of first coordinate pair
• long1 (int or float) – longitude of first coordinate pair
• lat2 (int or float) – latitude of second coordinate pair
• long2 (int or float) – longitdue of second coordinate pair

Returns:

Distance between two points in km

minsci.geobots.plss module

class minsci.geobots.plss.Box(*points)

Bases: object

centroid()

polygon()

Returns a closed polygon describing the section

subsection(direction)

supersection()

class minsci.geobots.plss.PLSS

Bases: object

parse(s)

Parse section-townshup-range from a string

Parameters:s (str) – a string Returns:Tuple containing the derived TRS string, an error string, and a copy of the original string with the longest substring marked in <strong> tags.

class minsci.geobots.plss.PLSSBot

Bases: object

defaults = {'ext': '', 'f': 'json', 'gdbVersion': '', 'geometry': '', 'geometryPrecision': '', 'geometryType': 'esriGeometryEnvelope', 'groupByFieldsForStatistics': '', 'inSR': '', 'maxAllowableOffset': '', 'objectIds': '', 'orderByFields': '', 'outFields': '', 'outSR': '', 'outStatistics': '', 'relationParam': '', 'resultOffset': '', 'resultRecordCount': '', 'returnCountOnly': 'false', 'returnDistinctValues': 'false', 'returnGeometry': 'false', 'returnIdsOnly': 'false', 'returnM': 'false', 'returnTrueCurves': 'false', 'returnZ': 'false', 'spatialRel': 'esriSpatialRelIntersects', 'time': ''}

find_section(plss_id, sec)

find_township(state, twp, rng)

class minsci.geobots.plss.TRS(verbatim, state)

Bases: object

bot = <minsci.geobots.plss.PLSSBot object>

describe(boxes=None)

find()

plss = <minsci.geobots.plss.PLSS object>

Module contents

Provides tools to interact with various georeferencing webservices