Contents

Classes for Trajectory Data

Trajectory Point Table Class

class mtldp.mtltrajs.OverallPoints(df=None)

class object for storing and manipulating a data frame of trajectory points from any number of trajectories Attributes

  • .df: data frame of trajectory points across all trajectories

__add__(other)

specifies the __add__ method to run self.append(other) and create a new mtldp.mtltrajs.OverallPoints class object tc = tc1 + tc2 :param other: data frame of trajectory points :return: a new mtldp.mtltrajs.OverallPoints class object

__init__(df=None)

initiate a trajectory data frame from an existing data frame of trajectory points :param df: data frame of trajectory points from any number of trajectories

Return type

None

__len__()

specifies the __len__ method to return number of trajectories :return: number of trajectories

add_basic_mapinfo(network)

add other basic map attributes (link and intersection ids) after fast map matching :param network: map network class (mtldp.mtlmap.Network)

Return type

None

add_complete_mapinfo(network)

run both self.add_basic_mapinfo(network) and self.add_movement(network) :param network: map network class (mtldp.mtlmap.Network)

Return type

None

add_date_time_info(tz=None)

add another two columns for date and date_time :param tz: see mtlutil.TimeZone :return:

add_movement(network)

add movement information :param network: map network class (mtldp.mtlmap.Network)

Return type

None

append(tc)

add more trajectory points from another data frame :param tc: data frame of trajectory points

Return type

None

get_temporal_range()

get the first and last timestamp in self.df :return: the first and last timestamp in self.df

get_timezone()

get timezone :return: timezone for trajectory points

get_trajs_dict(traj_attributes=None)

split self.df based on trip id and initiate a mtldp.mtltrajs.Trajectory class object for each trip and store them in a mtldp.mtltrajs.TrajectoryDict class object :return: a mtldp.mtltrajs.TrajectoryDict class object containing all of the trips in self.df

get_truncate_df(start_time, end_time)

get the truncated data frame according to a certain time period :param start_time: the beginning of the time period of interest :param end_time: the end of the time period of interest :return: the truncated data frame according to the time period

get_truncate_tc(start_time, end_time)

get the truncated data frame according to a certain time period and return a new mtldp.mtltrajs.OverallPoints class object

Parameters

  • start_time – the beginning of the time period of interest

  • end_time – the end of the time period of interest

Returns

mtldp.mtltrajs.OverallPoints class object with the truncated data frame

load_data(df, sort_trajs=False)

load an existing data frame of trajectory points as self.df and sort trajectory points by trip id and timestamp :param df: data frame of trajectory points from any number of trajectories :param sort_trajs: indicates if the trajectory points should be sorted by trip id and timestamp

Return type

None

load_file(filename)

read a csv file containing trajectory point information in a data frame and run self.load_data :param filename: csv file path

Return type

None

load_files(file_list)

read a list of csv files containing trajectory point information in one single data frame and run self.load_data :param file_list: list of csv file paths

Return type

None

load_fmm_results(fmm_file)

match the fast map matching output file with self.df

Parameters

fmm_file – path name of fast map matching output file

Return type

None

output_fmm_file(fmm_input_file, network_bound)

create input file for the fast map matching from self.df

Parameters

  • fmm_input_file – path name for the fmm input file

  • network_bound – geographic bounding box for the area of interest

Return type

None

split self.df by link and store the resulting mtldp.mtltrajs.OverallPoints class objects in a dictionary :return: a dictionary of :class:`mtldp.mtltrajs.OverallPoints’ class objects for each link

split_by_movement()

split self.df by movement and store the resulting mtldp.mtltrajs.OverallPoints class objects in a dictionary :return: a dictionary of :class:`mtldp.mtltrajs.OverallPoints’ class objects for each movement

truncate_by_period(start_time, end_time)

truncate the trajectory collection by start/end time stamp

Parameters

  • start_time – the beginning of the time period of interest

  • end_time – the end of the time period of interest

Return type

None

truncate_df(start_time, end_time)

truncate the trajectory collection by start/end time stamp

Parameters

  • start_time – the beginning of the time period of interest

  • end_time – the end of the time period of interest

Return type

None

Trajectory Dictionary Class

class mtldp.mtltrajs.TrajectoryDict(trajs_dict=None)

class object for storing and manipulating a dictionary of individual trajectory objects (mtldp.mtltrajs.Trajectory)

Attributes

  • .dict: dictionary of individual trajectory objects (mtldp.mtltrajs.Trajectory)

  • .timezone: timezone of trajectories in self.dict

__add__(other)

specifies the __add__ method to run self.append(other)

Parameters

other – a mtldp.mtltrajs.TrajectoryDict class object

Returns

self

__init__(trajs_dict=None)

initiate the class object from an existing dictionary of trajectory objects (mtldp.mtltrajs.Trajectory)

Parameters

trajs_dict – dictionary of trajectory objects (mtldp.mtltrajs.Trajectory) where the keys are the trip ids

__len__()

specifies the __len__ method to return the number of mtldp.mtltrajs.Trajectory class objects in self.dict

:return:the number of mtldp.mtltrajs.Trajectory class objects in self.dict

add_local_seconds(overall_timezone=None, in_same_timezone=True)

add ‘seconds_in_day’ attribute to each mtldp.mtltrajs.Trajectory class objects in self.dict

Parameters

  • overall_timezone – mtldp.utils.Timezone

  • in_same_timezone – True if all trajectories in self.dict are in the same timezone

Return type

None

add_trajectory(trajectory)

add a mtldp.mtltrajs.Trajectory class object to self.dict where the key is the trajectory id

Parameters

trajectory – a mtldp.mtltrajs.Trajectory class object

Return type

None

append(other)

append the trajectories from another mtldp.mtltrajs.TrajectoryDict object to self.dict

Parameters

other – a mtldp.mtltrajs.TrajectoryDict class object

Return type

None

del_trajectories(trajs_id)

remove mtldp.mtltrajs.Trajectory class objects from self.dict

Parameters

trajs_id – a list of trajectory ids

eliminate_outliers(length_threshold=5)

eliminate outlier mtldp.mtltrajs.Trajectory class objects that have a small number of trajectory points and update self.dict

Parameters

length_threshold – the minimum number of trajectory points required in a mtldp.mtltrajs.Trajectory class object

Return type

None

get_points_df(attributes='all', resort=True)

get a single data frame of all the trajectory points in self.dict that includes specific point attributes

Parameters

  • attributes – a list of point attributes to be included in data frame

  • resort – a mode that determines if the data frame will be resorted by ‘trip_id’ and ‘timestamp’

Returns

a single data frame of all the trajectory points in self.dict

get_trajs_df(attributes)

get a single data frame of all the trajectories in self.dict that includes specific trajectory attributes

Parameters

attributes – list of trajectory attributes

Returns

a single data frame of trajectories and their attributes

pop_traversed_trajectory(timestamp=None, debug=False)
Parameters

  • timestamp –

  • debug –

Returns

split_trip_by_gap(time_threshold=60, distance_threshold=500)

split all of the mtldp.mtltrajs.Trajectory class objects in self.dict into shorter mtldp.mtltrajs.Trajectory class objects and update self.dict

Parameters

  • time_threshold – the minimum time between two consecutive trajectory point timestamps required to split an existing trajectory

  • distance_threshold – the minimum distance traveled between two consecutive trajectory points required to split an existing trajectory

Return type

None

truncate_by_tod(start_tod, end_tod)

trim self.dict to only contain mtldp.mtltrajs.Trajectory class objects in a certain time range

Parameters

  • start_tod (str) – beginning of time range in format “HH:MM”

  • end_tod (str) – end of time range in format “HH:MM”

Return type

None

Trajectory Class

class mtldp.mtltrajs.Trajectory(traj_id, trip_id, trip_attributes=None, df=None)

class object for storing and manipulating data from an individual vehicle trajectory

Attributes

  • .traj_id: trajectory id

  • .trip_id: parent trajectory id after trajectory splitting, will be the same as .traj_id if the trajectory has not been split

  • .df: data frame of trajectory points

  • .trip_attributes: a list of trajectory attributes provided in the raw data

  • .date: trajectory date

  • .timestamp: timestamp of the last point in the trajectory

  • .date_time: trajectory hour and minute

  • .movement_id: includes the intersection id and phase movement id

  • .text: basic text of pertinent trajectory information (to be plotted)

__add__(other)

specifies the __add__ method to add more trajectory points to self from another mtldp.mtltrajs.Trajectory class object

Parameters

other – a mtldp.mtltrajs.Trajectory class object

Returns

updated self with added trajectory points

__init__(traj_id, trip_id, trip_attributes=None, df=None)

Initiate trajectory class

Parameters

  • traj_id (str) – trajectory id

  • trip_id (str) – if self is initiated from splitting a previous mtldp.mtltrajs.Trajectory class object, than the trip_id is the parent trajectory id, otherwise it is the same as the traj_id

  • trip_attributes – a list of uniform trajectory attributes provided in the raw data

  • df – data frame of trajectory points

Return type

None

__len__()

Specifies the __len__ method to return the number trajectory points in self

Returns

the number of trajectory points in self

__setattr__(name, value, /)

Implement setattr(self, name, value).

add_local_seconds(overall_timezone=None)

Add attribute “seconds_in_day”

Parameters

overall_timezone – if None, a timezone will be calculated for current trajectory, default None

Return type

None

generate_tod(tz=None)

Generate the tod info of trajectory data

Parameters

tz – time zone of the trajectory

Returns

self.date and self.date_time

get_point_attributes(*args)

Get point attributes as a list

example: >> lats, lons, times = trajectory.get_point_attributes(“latitude”, “longitude”, “timestamp”)

Parameters

args – point attributes of interest

Returns

a list for each point attribute in args

Return type

list

init_timezone()

Get the timezone of current trajectory

if a timezone cannot be inferred from position of current trajectory, the timezone will be set to GMT

Returns

mtldp.utils.Timezone

set_point_attributes(**kwargs)

set the point attributes from a list

example: >> trajectory.set_point_attributes(relative_dis=list())

Parameters

kwargs – new attribute name and attribute values

split_by_gap(time_threshold=60, distance_threshold=500)

Split self by a certain gap (time interval and distance) into shorter mtldp.mtltrajs.Trajectory class objects

Parameters

  • time_threshold – the minimum time between two consecutive trajectory point timestamps required to split an existing trajectory

  • distance_threshold – the minimum distance traveled between two consecutive trajectory points required to split an existing trajectory

Returns

a mtldp.mtltrajs.TrajectoryDict class object with all of the resulting mtldp.mtltrajs.Trajectory class objects from the split

Trajectory data Map Matching