Package: traclus-python
TRACLUSImplemented for Python 3This is an implementation of the TRACLUS algorithm as described in the paper:
"Trajectory Clustering: A Partition-and-Group Framework"
by Lee, Han, & Whang (2007) [http://hanj.cs.illinois.edu/pdf/sigmod07_jglee.pdf]Implementation Author: Adriel Isaiah V. Amoguis (De La Salle University)
Implementation Date: 2023-03-19This implementation was done as part of the algorithms required for the implementation author's
undergraduate thesis. The implementation is not guaranteed to be bug-free and may not be optimized
for certain use-cases. The implementation author is not responsible for any damages caused by the
use of this implementation. Use at your own risk. End-users are encouraged to examine the code
in the case of any issues. If you find any bugs, please report them to the implementation author
via the repository's issues page on GitHub.InstallationThis implementation requires Python 3.6 or higher. It is recommended to use a virtual environment to avoid
dependency conflicts.Optionally, create a Conda Virtual Environment:condacreate-ntracluspython=3.6
condaactivatetraclusInstall the package from pip:pipinstalltraclus-python==1.0.1UsagePreparing Your Trajectory DataThe TRACLUS algorithm requires a Python list of trajectories. Each trajectory is a 2-Dimensional Numpy Array
with the following format:[[x1,y1],[x2,y2],...[xn,yn]]wherexis the x-coordinate, andyis the y-coordinate for each pointn.Running the Algorithm in Your Own Script Filefromtraclusimporttraclusastr# Your Trajectory Datatrajectories=...# Run the TRACLUS Algorithmpartitions,segments,dist_matrix,clusters,cluster_assignments,representative_trajectories=tr.traclus(trajectories)Thepartitionsvariable will contain all the trajectories that are partitioned by the algorithm into their characteristic points (cp).
Thesegmentsvariable will contain all the generated partitions split into segments.
Thedist_matrixvariable will contain the distance matrix generated by the distance function as defined in the paper.
Theclustersvariable will contain the line segment clusters generated by the algorithm.
Thecluster_assignmentsvariable will contain the cluster assignments for each line segment.
Therepresentative_trajectoriesvariable will contain the representative trajectories generated by the algorithm.Distance Weights and Trajectory DirectionThis implementation uses three smaller distance function that computes the overall distance between two points in the trajectory.
These are thePerpendicular Distance,Parallel Distance, andAngular Distance. To compute the overall distance, these three distances
are weighted and added together as shown below:$distance = w_{perpendicular} * d_{perpendicular} + w_{parallel} * d_{parallel} + w_{angular} * d_{angular}$The weights for each distance function can be adjusted by providing aweightslist to thetraclusfunction. The default weights are:weights=[1,1,1]Additionally, thePerpendicular Distanceis computed differently depending on whether or not the trajectories are direction-sensitive.
Trajectories are treated as directional by default, but this can be changed by providing thedirectionalparameter to thetraclusfunction.
Such as:partitions,segments,dist_matrix,clusters,cluster_assignments,representative_trajectories=tr.traclus(trajectories,directional=False)Clustering ParametersThetraclusfunction takes in aclustering_algorithmparameter that can be used to specify the clustering algorithm to use. This is set to
DBSCAN from Scipy by default. Thetraclusfunction also accepts two parameters for DBSCAN:epsandmin_samples. These are set to 1 and 10 by default.Supporting FunctionsThesub_sample_trajectoryfunction can be used to sub-sample a trajectory into a trajectory of the same profile but with lesser points.
It takessample_nas a parameter, which is the number of points to sub-sample the trajectory into.fromtraclus.traclusimportsub_sample_trajectory# Your Trajectory Datatrajectories=...# Sub-Sample the Trajectoriessub_sampled_trajectories=[sub_sample_trajectory(trajectory,sample_n=100)fortrajectoryintrajectories]In the example above, the trajectories will be sub-sampled into 100 points each. This is useful for reducing the number of points processed by the algorithm, decreasing its runtime. However, this may also reduce the accuracy of the results. It is recommended to experiment with different values ofsample_nto find the best value for your use-case.Thesmooth_trajectoryfunction can be used to smooth the representative trajectories generated by the algorithm.fromtraclus.traclusimporttraclus,smooth_trajectory# Your Trajectory Datatrajectories=...# Run the TRACLUS Algorithmpartitions,segments,dist_matrix,clusters,cluster_assignments,representative_trajectories=traclus(trajectories)# Smooth the Representative Trajectoriessmoothed_representative_trajectories=[smooth_trajectory(trajectory,window_size=21)fortrajectoryinrepresentative_trajectories]