# TRACLUS
Implemented for Python 3
This 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-19
This 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.
---
## Installation
This 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:
```bash
conda create -n traclus python=3.6
conda activate traclus
```
Install the package from pip:
```bash
pip install traclus-python==1.0.1
```
---
## Usage
### Preparing Your Trajectory Data
The TRACLUS algorithm requires a Python list of trajectories. Each trajectory is a 2-Dimensional Numpy Array
with the following format:
```python
[[x1, y1],
[x2, y2],
...
[xn, yn]]
```
where `x` is the x-coordinate, and `y` is the y-coordinate for each point `n`.
### Running the Algorithm in Your Own Script File
```python
from traclus import traclus as tr
# Your Trajectory Data
trajectories = ...
# Run the TRACLUS Algorithm
partitions, segments, dist_matrix, clusters, cluster_assignments, representative_trajectories = tr.traclus(trajectories)
```
The `partitions` variable will contain all the trajectories that are partitioned by the algorithm into their characteristic points (cp).
The `segments` variable will contain all the generated partitions split into segments.
The `dist_matrix` variable will contain the distance matrix generated by the distance function as defined in the paper.
The `clusters` variable will contain the line segment clusters generated by the algorithm.
The `cluster_assignments` variable will contain the cluster assignments for each line segment.
The `representative_trajectories` variable will contain the representative trajectories generated by the algorithm.
### Distance Weights and Trajectory Direction
This implementation uses three smaller distance function that computes the overall distance between two points in the trajectory.
These are the _Perpendicular Distance_, _Parallel Distance_, and _Angular 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 a `weights` list to the `traclus` function. The default weights are:
```python
weights = [1, 1, 1]
```
Additionally, the _Perpendicular Distance_ is 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 the `directional` parameter to the `traclus` function.
Such as:
```python
partitions, segments, dist_matrix, clusters, cluster_assignments, representative_trajectories = tr.traclus(trajectories, directional=False)
```
### Clustering Parameters
The `traclus` function takes in a `clustering_algorithm` parameter that can be used to specify the clustering algorithm to use. This is set to
DBSCAN from Scipy by default. The `traclus` function also accepts two parameters for DBSCAN: `eps` and `min_samples`. These are set to 1 and 10 by default.
### Supporting Functions
The `sub_sample_trajectory` function can be used to sub-sample a trajectory into a trajectory of the same profile but with lesser points.
It takes `sample_n` as a parameter, which is the number of points to sub-sample the trajectory into.
```python
from traclus.traclus import sub_sample_trajectory
# Your Trajectory Data
trajectories = ...
# Sub-Sample the Trajectories
sub_sampled_trajectories = [sub_sample_trajectory(trajectory, sample_n=100) for trajectory in trajectories]
```
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 of `sample_n` to find the best value for your use-case.
The `smooth_trajectory` function can be used to smooth the representative trajectories generated by the algorithm.
```python
from traclus.traclus import traclus, smooth_trajectory
# Your Trajectory Data
trajectories = ...
# Run the TRACLUS Algorithm
partitions, segments, dist_matrix, clusters, cluster_assignments, representative_trajectories = traclus(trajectories)
# Smooth the Representative Trajectories
smoothed_representative_trajectories = [smooth_trajectory(trajectory, window_size=21) for trajectory in representative_trajectories]
```
Raw data
{
"_id": null,
"home_page": "https://github.com/AdrielAmoguis/TRACLUS",
"name": "traclus-python",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Trajectory Clustering",
"author": "Adriel Isaiah Amoguis",
"author_email": "adriel.isaiah.amoguis@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/51/eb/d1c4c260d44ddf602b061994dd70014624c78ff93d15ed966349affb2354/traclus-python-1.0.2.tar.gz",
"platform": null,
"description": "# TRACLUS\n\nImplemented for Python 3\n\nThis is an implementation of the TRACLUS algorithm as described in the paper:\n\"Trajectory Clustering: A Partition-and-Group Framework\"\nby Lee, Han, & Whang (2007) [http://hanj.cs.illinois.edu/pdf/sigmod07_jglee.pdf]\n\nImplementation Author: Adriel Isaiah V. Amoguis (De La Salle University)\nImplementation Date: 2023-03-19\n\nThis implementation was done as part of the algorithms required for the implementation author's\nundergraduate thesis. The implementation is not guaranteed to be bug-free and may not be optimized\nfor certain use-cases. The implementation author is not responsible for any damages caused by the\nuse of this implementation. Use at your own risk. End-users are encouraged to examine the code\nin the case of any issues. If you find any bugs, please report them to the implementation author\nvia the repository's issues page on GitHub.\n\n---\n\n## Installation\n\nThis implementation requires Python 3.6 or higher. It is recommended to use a virtual environment to avoid\ndependency conflicts.\n\nOptionally, create a Conda Virtual Environment:\n\n```bash\nconda create -n traclus python=3.6\nconda activate traclus\n```\n\nInstall the package from pip:\n\n```bash\npip install traclus-python==1.0.1\n```\n\n---\n\n## Usage\n\n### Preparing Your Trajectory Data\n\nThe TRACLUS algorithm requires a Python list of trajectories. Each trajectory is a 2-Dimensional Numpy Array\nwith the following format:\n\n```python\n[[x1, y1],\n [x2, y2],\n ...\n [xn, yn]]\n```\n\nwhere `x` is the x-coordinate, and `y` is the y-coordinate for each point `n`.\n\n### Running the Algorithm in Your Own Script File\n\n```python\nfrom traclus import traclus as tr\n\n# Your Trajectory Data\ntrajectories = ...\n\n# Run the TRACLUS Algorithm\npartitions, segments, dist_matrix, clusters, cluster_assignments, representative_trajectories = tr.traclus(trajectories)\n```\n\nThe `partitions` variable will contain all the trajectories that are partitioned by the algorithm into their characteristic points (cp).\nThe `segments` variable will contain all the generated partitions split into segments.\nThe `dist_matrix` variable will contain the distance matrix generated by the distance function as defined in the paper.\nThe `clusters` variable will contain the line segment clusters generated by the algorithm.\nThe `cluster_assignments` variable will contain the cluster assignments for each line segment.\nThe `representative_trajectories` variable will contain the representative trajectories generated by the algorithm.\n\n### Distance Weights and Trajectory Direction\n\nThis implementation uses three smaller distance function that computes the overall distance between two points in the trajectory.\nThese are the _Perpendicular Distance_, _Parallel Distance_, and _Angular Distance_. To compute the overall distance, these three distances\nare weighted and added together as shown below:\n\n$distance = w_{perpendicular} * d_{perpendicular} + w_{parallel} * d_{parallel} + w_{angular} * d_{angular}$\n\nThe weights for each distance function can be adjusted by providing a `weights` list to the `traclus` function. The default weights are:\n\n```python\nweights = [1, 1, 1]\n```\n\nAdditionally, the _Perpendicular Distance_ is computed differently depending on whether or not the trajectories are direction-sensitive.\nTrajectories are treated as directional by default, but this can be changed by providing the `directional` parameter to the `traclus` function.\nSuch as:\n\n```python\npartitions, segments, dist_matrix, clusters, cluster_assignments, representative_trajectories = tr.traclus(trajectories, directional=False)\n```\n\n### Clustering Parameters\n\nThe `traclus` function takes in a `clustering_algorithm` parameter that can be used to specify the clustering algorithm to use. This is set to\nDBSCAN from Scipy by default. The `traclus` function also accepts two parameters for DBSCAN: `eps` and `min_samples`. These are set to 1 and 10 by default.\n\n### Supporting Functions\n\nThe `sub_sample_trajectory` function can be used to sub-sample a trajectory into a trajectory of the same profile but with lesser points.\nIt takes `sample_n` as a parameter, which is the number of points to sub-sample the trajectory into.\n\n```python\n\nfrom traclus.traclus import sub_sample_trajectory\n\n# Your Trajectory Data\ntrajectories = ...\n\n# Sub-Sample the Trajectories\nsub_sampled_trajectories = [sub_sample_trajectory(trajectory, sample_n=100) for trajectory in trajectories]\n```\n\nIn 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 of `sample_n` to find the best value for your use-case.\n\nThe `smooth_trajectory` function can be used to smooth the representative trajectories generated by the algorithm.\n\n```python\nfrom traclus.traclus import traclus, smooth_trajectory\n\n# Your Trajectory Data\ntrajectories = ...\n\n# Run the TRACLUS Algorithm\npartitions, segments, dist_matrix, clusters, cluster_assignments, representative_trajectories = traclus(trajectories)\n\n# Smooth the Representative Trajectories\nsmoothed_representative_trajectories = [smooth_trajectory(trajectory, window_size=21) for trajectory in representative_trajectories]\n```\n",
"bugtrack_url": null,
"license": "apache-2.0",
"summary": "",
"version": "1.0.2",
"split_keywords": [
"trajectory",
"clustering"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "51ebd1c4c260d44ddf602b061994dd70014624c78ff93d15ed966349affb2354",
"md5": "28ad363c7557694e0378f05cadf2d47f",
"sha256": "92868dee845c7f28c28755f4d2c7af51238597cde812b4898cb54570a71bd172"
},
"downloads": -1,
"filename": "traclus-python-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "28ad363c7557694e0378f05cadf2d47f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13538,
"upload_time": "2023-04-17T04:04:42",
"upload_time_iso_8601": "2023-04-17T04:04:42.069714Z",
"url": "https://files.pythonhosted.org/packages/51/eb/d1c4c260d44ddf602b061994dd70014624c78ff93d15ed966349affb2354/traclus-python-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-17 04:04:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "AdrielAmoguis",
"github_project": "TRACLUS",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "traclus-python"
}
JSON
