upoints.point.KeyedPoints

Package upoints :: Module point :: Class KeyedPoints |
[hide private]
[frames] | no frames]

# Class KeyedPoints

    object --+
             |
          dict --+
                 |
                KeyedPoints

Known Subclasses:
  - trigpoints.Trigpoints
  - , cellid.Cells
  - , weather_stations.Stations
  - , kml.Placemarks
  - , xearth.Xearths
  - , baken.Bakens

Class for representing a keyed group of Point objects

Since: 2008-05-02

Instance Methods | [hide private]
    new empty dictionary
__init__(self, points=None, parse=False, units=`'``metric``'`) Initialise a new KeyedPoints object |
`str` |
__repr__(self) Self-documenting string representation |
import_locations(self, locations) Import locations from arguments |
`list` of `float` |
distance(self, order, method=`'``haversine``'`) Calculate distances between locations |
`list` of `float` |
bearing(self, order, format=`'``numeric``'`) Calculate bearing between locations |
`list` of `float` |
final_bearing(self, order, format=`'``numeric``'`) Calculate final bearing between locations |
`list` of 2 `tuple` of `float` |
inverse(self, order) Calculate the inverse geodesic between locations |
`list` of Point instance |
midpoint(self, order) Calculate the midpoint between locations |
`list` of Point objects within specified range |
range(self, location, distance) Test whether locations are within a given range of the first |
destination(self, bearing, distance) Calculate destination locations for given distance and bearings |
forward(self, bearing, distance) Calculate destination locations for given distance and bearings |
`list` of `datetime.datetime` |
sunrise(self, date=None, zenith=None) Calculate sunrise times for locations |
`list` of `datetime.datetime` |
sunset(self, date=None, zenith=None) Calculate sunset times for locations |
`list` of 2 `tuple` of `datetime.datetime` |
sun_events(self, date=None, zenith=None) Calculate sunrise/sunset times for locations |
`list` of `str` |
to_grid_locator(self, precision=`'``square``'`) Calculate Maidenhead locator for locations |
Inherited from `dict`: `__cmp__`, `__contains__`, `__delitem__`, `__eq__`, `__ge__`, `__getattribute__`, `__getitem__`, `__gt__`, `__hash__`, `__iter__`, `__le__`, `__len__`, `__lt__`, `__ne__`, `__new__`, `__setitem__`, `clear`, `copy`, `fromkeys`, `get`, `has_key`, `items`, `iteritems`, `iterkeys`, `itervalues`, `keys`, `pop`, `popitem`, `setdefault`, `update`, `values` Inherited from `object`: `__delattr__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__str__`

Properties | [hide private]
Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, points=None, parse=False, units=`'``metric``'`) (Constructor) |
Initialise a new KeyedPoints object
    >>> KeyedPoints({"a": Point(52.015, -0.221), "b": Point(53.645, -0.284)})
    KeyedPoints({'a': Point(52.015, -0.221, 'metric', 'degrees', 0),
                 'b': Point(53.645, -0.284, 'metric', 'degrees', 0)},
                False, 'metric')
Parameters: `points` (`dict` of Point objects) - Point objects to wrap `parse` (`bool`) - Whether to attempt import of `points` `units` (`str`) - Unit type to be used for distances when parsing string locations Returns:
    new empty dictionary
Overrides: object.__init__

### __repr__(self) (Representation operator) |
Self-documenting string representation
    >>> locations = {"a": Point(0, 0), "b": Point(0,0)}
    >>> KeyedPoints(locations)
    KeyedPoints({'a': Point(0.0, 0.0, 'metric', 'degrees', 0),
                 'b': Point(0.0, 0.0, 'metric', 'degrees', 0)},
                False, 'metric')
Returns: `str` String to recreate KeyedPoints object Overrides: object.__repr__

### import_locations(self, locations) |
Import locations from arguments
    >>> locations = KeyedPoints()
    >>> locations.import_locations([("prime", "0;0"),
    ...                             ("home", "52.015 -0.221")])
    >>> locations
    KeyedPoints({'prime': Point(0.0, 0.0, 'metric', 'degrees', 0),
                 'home': Point(52.015, -0.221, 'metric', 'degrees', 0)},
                 False, 'metric')
Parameters: `locations` (`list` of 2 `tuple` of `str`) - Identifiers and locations

### distance(self, order, method=`'``haversine``'`) |
Calculate distances between locations
    >>> locations = KeyedPoints([("home", "52.015;-0.221"),
    ...                          ("Carol", "52.168;0.040"),
    ...                          ("Kenny", "52.855;0.657")],
    ...                         parse=True)
    >>> "%.3f" % sum(locations.distance(("home", "Carol", "Kenny")))
    '111.632'
Parameters: `order` (`list` of identifiers) - Order to process elements in `method` (`str`) - Method used to calculate distance Returns: `list` of `float` Distance between points in `order`

### bearing(self, order, format=`'``numeric``'`) |
Calculate bearing between locations
    >>> locations = KeyedPoints([("home", "52.015;-0.221"),
    ...                          ("Carol", "52.168;0.040"),
    ...                          ("Kenny", "52.855;0.657")],
    ...                         parse=True)
    >>> map(lambda x: "%.3f" % x,
    ...     locations.bearing(("home", "Carol", "Kenny")))
    ['46.242', '28.416']
Parameters: `order` (`list` of identifiers) - Order to process elements in `format` (`str`) - Format of the bearing string to return Returns: `list` of `float` Bearing between points in series

### final_bearing(self, order, format=`'``numeric``'`) |
Calculate final bearing between locations
    >>> locations = KeyedPoints([("home", "52.015;-0.221"),
    ...                          ("Carol", "52.168;0.040"),
    ...                          ("Kenny", "52.855;0.657")],
    ...                         parse=True)
    >>> map(lambda x: "%.3f" % x,
    ...     locations.final_bearing(("home", "Carol", "Kenny")))
    ['46.448', '28.906']
Parameters: `order` (`list` of identifiers) - Order to process elements in `format` (`str`) - Format of the bearing string to return Returns: `list` of `float` Bearing between points in series

### inverse(self, order) |
Calculate the inverse geodesic between locations
    >>> locations = KeyedPoints([("home", "52.015;-0.221"),
    ...                          ("Carol", "52.168;0.040"),
    ...                          ("Kenny", "52.855;0.657")],
    ...                         parse=True)
    >>> locations.inverse(("home", "Carol", "Kenny"))
    [(46.242393198024672, 24.629669163425465),
     (28.416173848453582, 87.002075833085328)]
Parameters: `order` (`list` of identifiers) - Order to process elements in Returns: `list` of 2 `tuple` of `float` Bearing and distance between points in series

### midpoint(self, order) |
Calculate the midpoint between locations
    >>> locations = KeyedPoints([("home", "52.015;-0.221"),
    ...                          ("Carol", "52.168;0.040"),
    ...                          ("Kenny", "52.855;0.657")],
    ...                         parse=True)
    >>> locations.midpoint(("home", "Carol", "Kenny"))
    [Point(52.0915720432, -0.0907237539143, 'metric', 'degrees', 0),
     Point(52.5119010509, 0.346088603087, 'metric', 'degrees', 0)]
Parameters: `order` (`list` of identifiers) - Order to process elements in Returns: `list` of Point instance Midpoint between points in series

### range(self, location, distance) |
Test whether locations are within a given range of the first
    >>> locations = KeyedPoints([("home", "52.015;-0.221"),
    ...                          ("Carol", "52.168;0.040"),
    ...                          ("Kenny", "52.855;0.657")],
    ...                         parse=True)
    >>> list(locations.range(Point(52.015, -0.221), 20))
    [('home', Point(52.015, -0.221, 'metric', 'degrees', 0))]
Parameters: `location` (Point) - Location to test range against `distance` (`float`) - Distance to test location is within Returns: `list` of Point objects within specified range

### destination(self, bearing, distance) |
Calculate destination locations for given distance and bearings
    >>> locations = KeyedPoints([("home", "52.015;-0.221"),
    ...                          ("Carol", "52.168;0.040"),
    ...                          ("Kenny", "52.855;0.657")],
    ...                         parse=True)
    >>> list(locations.destination(42, 240))
    [('home', Point(53.5956078217, 2.2141813684, 'metric', 'degrees', 0)),
     ('Carol', Point(53.7484691495, 2.48403821375, 'metric', 'degrees', 0)),
     ('Kenny', Point(54.4348338045, 3.14183478498, 'metric', 'degrees', 0))]
Parameters: `bearing` (`float` or coercible to `float`) - Bearing to move on in degrees `distance` (`float` or coercible to `float`) - Distance in kilometres

### forward(self, bearing, distance) |
Calculate destination locations for given distance and bearings
    >>> locations = KeyedPoints([("home", "52.015;-0.221"),
    ...                          ("Carol", "52.168;0.040"),
    ...                          ("Kenny", "52.855;0.657")],
    ...                         parse=True)
    >>> list(locations.destination(42, 240))
    [('home', Point(53.5956078217, 2.2141813684, 'metric', 'degrees', 0)),
     ('Carol', Point(53.7484691495, 2.48403821375, 'metric', 'degrees', 0)),
     ('Kenny', Point(54.4348338045, 3.14183478498, 'metric', 'degrees', 0))]
Parameters: `bearing` (`float` or coercible to `float`) - Bearing to move on in degrees `distance` (`float` or coercible to `float`) - Distance in kilometres

### sunrise(self, date=None, zenith=None) |
Calculate sunrise times for locations
    >>> locations = KeyedPoints([("home", "52.015;-0.221"),
    ...                          ("Carol", "52.168;0.040"),
    ...                          ("Kenny", "52.855;0.657")],
    ...                         parse=True)
    >>> import datetime
    >>> list(locations.sunrise(datetime.date(2008, 5, 2)))
    [('home', datetime.time(4, 28)), ('Carol', datetime.time(4, 26)),
     ('Kenny', datetime.time(4, 21))]
Parameters: `date` (`datetime.date`) - Calculate rise or set for given date `zenith` (`None` or `str`) - Calculate rise/set events, or twilight times Returns: `list` of `datetime.datetime` The time for the sunrise for each point

### sunset(self, date=None, zenith=None) |
Calculate sunset times for locations
    >>> locations = KeyedPoints([("home", "52.015;-0.221"),
    ...                          ("Carol", "52.168;0.040"),
    ...                          ("Kenny", "52.855;0.657")],
    ...                         parse=True)
    >>> import datetime
    >>> list(locations.sunset(datetime.date(2008, 5, 2)))
    [('home', datetime.time(19, 29)), ('Carol', datetime.time(19, 28)),
     ('Kenny', datetime.time(19, 28))]
Parameters: `date` (`datetime.date`) - Calculate rise or set for given date `zenith` (`None` or `str`) - Calculate rise/set events, or twilight times Returns: `list` of `datetime.datetime` The time for the sunset for each point

### sun_events(self, date=None, zenith=None) |
Calculate sunrise/sunset times for locations
    >>> locations = KeyedPoints([("home", "52.015;-0.221"),
    ...                          ("Carol", "52.168;0.040"),
    ...                          ("Kenny", "52.855;0.657")],
    ...                         parse=True)
    >>> import datetime
    >>> list(locations.sun_events(datetime.date(2008, 5, 2)))
    [('home', (datetime.time(4, 28), datetime.time(19, 29))),
     ('Carol', (datetime.time(4, 26), datetime.time(19, 28))),
     ('Kenny', (datetime.time(4, 21), datetime.time(19, 28)))]
Parameters: `date` (`datetime.date`) - Calculate rise or set for given date `zenith` (`None` or `str`) - Calculate rise/set events, or twilight times Returns: `list` of 2 `tuple` of `datetime.datetime` The time for the sunrise and sunset events for each point

### to_grid_locator(self, precision=`'``square``'`) |
Calculate Maidenhead locator for locations
    >>> locations = KeyedPoints([("home", "52.015;-0.221"),
    ...                          ("Carol", "52.168;0.040"),
    ...                          ("Kenny", "52.855;0.657")],
    ...                         parse=True)
    >>> list(locations.to_grid_locator("extsquare"))
    [('home', 'IO92va33'), ('Carol', 'JO02ae40'), ('Kenny', 'JO02hu85')]
    >>> list(locations.to_grid_locator("subsquare"))
    [('home', 'IO92va'), ('Carol', 'JO02ae'), ('Kenny', 'JO02hu')]
Parameters: `precision` (`str`) - Precision with which generate locator string Returns: `list` of `str` Maidenhead locator for each point