0
# MovingPandas
1

2
MovingPandas is a comprehensive Python library for trajectory and movement data analysis that builds upon pandas, GeoPandas, and the broader geospatial ecosystem. It provides specialized data structures for working with spatio-temporal trajectory data, including Trajectory and TrajectoryCollection classes with rich functionality for data exploration, visualization, and analysis.
3

4
## Package Information
5

6
- **Package Name**: movingpandas
7
- **Language**: Python
8
- **Installation**: `pip install movingpandas`
9
- **Documentation**: https://movingpandas.readthedocs.io
10

11
## Core Imports
12

13
```python
14
import movingpandas as mpd
15
```
16

17
Common imports for specific functionality:
18

19
```python
20
from movingpandas import Trajectory, TrajectoryCollection
21
from movingpandas import read_mf_json, gdf_to_mf_json
22
```
23

24
## Basic Usage
25

26
```python
27
import movingpandas as mpd
28
import pandas as pd
29
import geopandas as gpd
30
from shapely.geometry import Point
31
from datetime import datetime, timedelta
32

33
# Create sample trajectory data
34
data = []
35
base_time = datetime(2023, 1, 1, 12, 0, 0)
36
for i in range(10):
37
    data.append({
38
        'geometry': Point(i * 0.1, i * 0.1),
39
        't': base_time + timedelta(minutes=i * 5),
40
        'obj_id': 'A'
41
    })
42

43
# Create GeoDataFrame
44
gdf = gpd.GeoDataFrame(data, crs='EPSG:4326')
45

46
# Create a Trajectory
47
traj = mpd.Trajectory(gdf, traj_id='traj_1')
48

49
# Basic trajectory operations
50
print(f"Start time: {traj.get_start_time()}")
51
print(f"End time: {traj.get_end_time()}")
52
print(f"Duration: {traj.get_duration()}")
53
print(f"Length: {traj.get_length()}")
54

55
# Add computed columns
56
traj = traj.add_speed()
57
traj = traj.add_direction()
58

59
# Create TrajectoryCollection from multiple trajectories
60
collection = mpd.TrajectoryCollection(gdf, traj_id_col='obj_id')
61
```
62

63
## Architecture
64

65
MovingPandas builds on the foundation of pandas and GeoPandas, extending them with specialized trajectory data structures:
66

67
- **Trajectory**: Individual movement path with temporal geometry data
68
- **TrajectoryCollection**: Container for managing multiple trajectories
69
- **Processing Classes**: Specialized algorithms for trajectory analysis
70
- **Integration**: Seamless compatibility with pandas, GeoPandas, and geospatial libraries
71

72
The library provides extensive trajectory processing capabilities through modular components that can be combined for complex analysis workflows.
73

74
## Capabilities
75

76
### Core Data Structures
77

78
The fundamental classes for representing and managing trajectory data, providing rich functionality for spatio-temporal analysis and visualization.
79

80
```python { .api }
81
class Trajectory:
82
    def __init__(self, df, traj_id, traj_id_col=None, obj_id=None, t=None, x=None, y=None, crs="epsg:4326", parent=None): ...
83
    def get_start_time(self): ...
84
    def get_end_time(self): ...
85
    def get_duration(self): ...
86
    def get_length(self, units=UNITS()): ...
87
    def add_speed(self, overwrite=False, name="speed", units=UNITS()): ...
88
    def add_direction(self, overwrite=False, name="direction"): ...
89

90
class TrajectoryCollection:
91
    def __init__(self, data, traj_id_col=None, obj_id_col=None, t=None, x=None, y=None, crs="epsg:4326", min_length=0, min_duration=None): ...
92
    def get_trajectory(self, traj_id): ...
93
    def filter(self, property_name, property_values): ...
94
    def get_intersecting(self, polygon): ...
95
```
96

97
[Core Data Structures](./core-data-structures.md)
98

99
### Trajectory Processing
100

101
Advanced algorithms for trajectory generalization, splitting, cleaning, and analysis. These classes provide specialized methods for preparing and analyzing movement data.
102

103
```python { .api }
104
class DouglasPeuckerGeneralizer:
105
    def __init__(self, traj): ...
106
    def generalize(self, tolerance=1.0): ...
107

108
class TemporalSplitter:
109
    def __init__(self, traj): ...
110
    def split(self, mode="day", min_length=0): ...
111

112
class OutlierCleaner:
113
    def __init__(self, traj): ...
114
    def clean(self, v_max=None, units=UNITS(), alpha=3): ...
115

116
class TrajectoryStopDetector:
117
    def __init__(self, traj, n_processes=1): ...
118
    def get_stop_segments(self, max_diameter, min_duration): ...
119
```
120

121
[Trajectory Processing](./trajectory-processing.md)
122

123
### Aggregation and Analysis
124

125
Tools for extracting insights from trajectory collections, including significant point detection, clustering, and flow analysis.
126

127
```python { .api }
128
class TrajectoryCollectionAggregator:
129
    def __init__(self, traj_collection, max_distance, min_distance, min_stop_duration, min_angle=45): ...
130
    def get_significant_points_gdf(self): ...
131
    def get_clusters_gdf(self): ...
132
    def get_flows_gdf(self): ...
133

134
class PointClusterer:
135
    def __init__(self, points, max_distance, is_latlon): ...
136
    def get_clusters(self): ...
137
```
138

139
[Aggregation and Analysis](./aggregation-analysis.md)
140

141
### IO and Data Exchange
142

143
Functions for importing and exporting trajectory data in various formats, with special support for OGC Moving Features JSON.
144

145
```python { .api }
146
def read_mf_json(json_file_path, traj_id_property=None, traj_id=0): ...
147
def read_mf_dict(data, traj_id=0, traj_id_property=None): ...
148
def gdf_to_mf_json(gdf, traj_id_column, datetime_column, temporal_columns=None, **kwargs): ...
149
def show_versions(): ...
150
```
151

152
[IO and Utilities](./io-utilities.md)
153

154
## Types
155

156
```python { .api }
157
from collections import namedtuple
158

159
UNITS = namedtuple("UNITS", "distance time time2 crs", defaults=(None, None, None, None))
160

161
class TimeZoneWarning(UserWarning, ValueError):
162
    """Warning for timezone-related issues in trajectory data."""
163
```
164

165
## Constants
166

167
```python { .api }
168
# Standard column names used throughout MovingPandas
169
ACCELERATION_COL_NAME = "acceleration"
170
ANGULAR_DIFFERENCE_COL_NAME = "angular_difference"
171
DIRECTION_COL_NAME = "direction"
172
DISTANCE_COL_NAME = "distance"
173
SPEED_COL_NAME = "speed"
174
TIMEDELTA_COL_NAME = "timedelta"
175
TRAJ_ID_COL_NAME = "traj_id"
176
```