tracktable.core module¶

Module contents¶

TrailMix Trajectory Library - Core

Basic types (point, trajectory) live in this module. They are in turn imported from the small C extension libraries.

tracktable.core.data_directory()[source]¶

Return path to Tracktable example data files

We bundle a few example data files inside Tracktable. This function will give you the path to those. Use it as follows:

import os.path from tracktable.core import data_directory

with open(os.path.join(data_directory(), “SampleASDI.csv”)) as asdi_file:: # Do your own stuff with the data

Parameters: arguments. (No) –
Returns: Path to Tracktable example data files.

class tracktable.core.TrajectoryPoint(longitude=0, latitude=0, altitude=0)¶

Bases: object

This is the core geographic point class for Tracktable. NOTE: The ‘Bases’ is not accurate but will do for now.

This is the core geographic point class for Tracktable. You will not instantiate this yourself: instead, use tracktable.domain.<domain>.TrajectoryPoint.

TrajectoryPoint specifies a point on the surface of a sphere that is annotated with an object ID, coordinates, timestamp, and possibly other attributes (commonly altitude, heading and speed). Any or all of these may be left uninitialized depending on the user’s actions although a point without coordinates is not especially useful.

We require that the coordinates be in degrees of longitude and latitude. The units on all numeric properties are user-defined, although altitude will usually be in either feet or meters (depending on your data source) and heading will usually be in degrees clockwise from due north.

The (longitude, latitude) coordinates of a TrajectoryPoint object are accessed as if the object were a Python array, using the [] operator:

from tracktable.domain.terrestrial import TrajectoryPoint

my_point = TrajectoryPoint()
longitude = 30
latitude = 40
my_point[0] = longitude
my_point[1] = latitude

Longitude is always coordinate 0 and latitude is always coordinate 1. We choose this ordering for consistency with the 2D Cartesian domain where the X coordinate is always at position 0 and the Y coordinate is at position 1. Longitude is between -180 and 180 and latitude is between -90 and 90.

Note

TrajectoryPoint is implemented in C++ and exposed to Python via the Boost.Python module. I will include a link to the C++ class definition as soon as I figure out how to do so within Sphinx, Breathe and Napoleon.

object_id¶

string

Object ID of entity referred to by this point

timestamp¶

datetime

Timestamp corresponding to this point

properties¶

dict

User-defined properties. Names are strings, values are numbers, timestamps and strings. All properties other than object ID, coordinates, and timestamp will be stored here.

TrajectoryPoint.has_property(property_name)¶

Check to see whether an entry is present in the property map

Parameters: property_name (string) – Name of property to look for
Returns: True or false depending on whether property was found

class tracktable.core.Trajectory¶

Bases: object

Ordered sequence of timestamped points.

This class is the heart of most of what Tracktable does. It implements an ordered sequence of TrajectoryPoint objects, each of which has an ID, coordinates and a timestamp. Those compose a trajectory. All points in a single Trajectory should have the same object_id.

Note

The Trajectory class is implemented in C++ and exposed to Python via the Boost.Python module. We use the vector indexing suite from Boost to make a trajectory act like a list of points.

object_id¶

string

ID of object described in this trajectory. This will be the string “(empty)” if the trajectory does not contain any points.

start_time¶

datetime

Timestamp of the first point in the trajectory. This will be invalid if the trajectory contains no points.

end_time¶

datetime

Timestamp of the last point in the trajectory. This will be invalid if the trajectory contains no points.

Trajectory.subset_in_window(start_time, end_time)¶

Compute the subset of a trajectory between two timestamps.

We often want to clip a trajectory to just the part that fits within a certain window of time. This method interpolates new start and end positions that fall exactly at start_time and end_time and includes between them all of the points in the trajectory that occur within the specified interval. If the trajectory does not intersect the interval at all then the return value will be an empty Trajectory.

Parameters

start_time (datetime) – Beginning of time window
end_time (datetime) – End of time window

Returns

New Trajectory with endpoints at start_time and end_time

Trajectory.point_at_time(when)¶

Find the position on a trajectory at a specified time.

If the specified time falls between points on the trajectory then we will interpolate as needed. If you ask for a point before the trajectory begins or after the trajectory ends you will get the first or last point of the trajectory respectively.

Parameters: when (datetime) – Time at which to evaluate trajectory
Returns: TrajectoryPoint at specified time

Trajectory.recompute_speed()¶

Compute speeds at each point of a trajectory.

Sometimes the speed measurements that come with a data set are noisy or outright wrong. Sometimes they’re missing. This method is for those situations. When you call it, it will use the position and timestamp data to compute a speed at each point in the trajectory. This value can be accessed with my_speed = my_trajectory[i].properties['speed'].

Trajectory.recompute_heading()¶

Compute headings at each point of a trajectory.

The heading at each point of a trajectory is the direction to the next point. The heading at the very last point is the same as the heading at the penultimate point. This value can be accessed with my_heading = my_trajectory[i].properties['heading'].

Trajectory.intersects_box(southwest_corner, northeast_corner)¶

Test to see whether a trajectory intersects a rectangle in longitude/latitude space.

A trajectory intersects a box if any of its coordinates falls within the box.

Parameters

southwest_corner (TrajectoryPoint or (longitude, latitude) tuple) – Southwest corner of box of interest
northwest_corner (TrajectoryPoint or (longitude, latitude) tuple) – Northwest corner of box of interest

Returns

True or False

static Trajectory.from_position_list(points)¶

Assemble a Trajectory from a list of TrajectoryPoints.

Parameters: points (list) – List of TrajectoryPoint objects
Returns: New Trajectory instance containing copies of all supplied points

class tracktable.core.Timestamp¶

Convenience methods for working with timestamps.

Recall that a Timestamp is just a timezone-aware datetime.datetime object. That gives us all of the standard Python date/time functions to use for manipulating them. As a result we only need convenience functions to take care of the awkward parts: turning strings into timestamps, timestamps into strings, and imbuing a naive datetime object with a time zone.

static Timestamp.beginning_of_time()¶

Return a timestamp equal to January 1, 1400. No valid timestamp should ever be this old.

Returns: Timestamp object set to the first day of 1400

static Timestamp.from_struct_time(mytime)¶

Construct a datetime from a time.struct_time object.

Parameters: mytime (time.struct_time) – Source time
Returns: An aware datetime object imbued with tracktable.core.timestamp.DEFAULT_TIMEZONE

static Timestamp.from_dict(mydict)¶

Construct a datetime from a dict with named elements.

Parameters: mydict (dict) – Dict with zero or more of ‘hour’, ‘minute’, ‘second’, ‘year’, ‘month’, ‘day’, and ‘utc_offset’ entries. Missing entries will be set to their minimum legal values.
Returns: An aware datetime object imbued with tracktable.core.DEFAULT_TIMEZONE unless a ‘utc_offset’ value is specified, in which case the specified time zone will be used instead.

static Timestamp.from_datetime(mytime)¶

Convert a datetime into an aware timestamp.

Parameters: mytime (datetime.datetime) – datetime object to convert
Returns: datetime that will definitely have a time zone attached. If the input already has a time zone then it will be returned without modification. If not, a new timestamp will be created with the supplied date/time and the default time zone.

static Timestamp.from_any(thing)¶

Try to construct a timestamp from whatever we’re given.

The possible inputs can be:

a Python datetime (in which case we just return a copy of the input)
a string in the format 2013-04-05 11:23:45, in which case we will assume that it resides in timestamp.DEFAULT_TIMEZONE
a string in the format 2013-04-05 11:23:45-05, in which case we will assume that it’s UTC-5 (or other time zone, accordingly)
a string in the format 2013-04-05T11:23:45 or 2013-04-05T11:23:45-05 – just like above but with a T in the middle instead of a space
a string in the format 20130405112345 - these are assumed to reside in the default time zone
a string in the format MM-DD-YYYY HH:MM:SS
a string such as 08-Aug-2013 12:34:45 where ‘Aug’ is the abbreviated name for a month in your local environment
a dict containing at least year, month, day entries and optionally hour, minute, second and utc_offset

Internally this method dispatches to all of the other Timestamp.from_xxx() methods.

Parameters: thing – Thing to try to convert to a timestamp
Returns: Timezone-aware datetime object

static Timestamp.to_string(dt, format_string='%Y-%m-%d %H:%M:%S`, include_tz=False)¶

Create a string from a timestamp.

Format contents as a string, by default formatted as 2013-04-21 14:45:00. You may supply an argument format_string if you want it in a different form. See the documentation for datetime.strftime() for information on what this format string looks like.

Parameters

dt (datetime.datetime) – Timestamp object to stringify
format_string (string) – String to pass to datetime.strftime()
include_tz (Boolean) – Whether or not to append timezone as UTC offset

Returns

String representation of timestamp