Deep Learning Integration

Traja provides production-ready features for training neural networks on trajectory data, including data augmentation, sequence processing, feature extraction, and PyTorch integration.

Overview 

The deep learning features in traja enable:

Data Augmentation - Create training variations for robust models
Sequence Processing - Standardize trajectory lengths for batching
Feature Extraction - Generate ML-ready features automatically
PyTorch Integration - Seamless tensor conversion
Dataset Utilities - Train/val/test splitting with reproducibility

All features work with both 2D and 3D trajectories.

Data Augmentation 

Data augmentation is essential for training deep learning models that generalize well. Traja provides five augmentation methods:

Rotation 

Rotate trajectories for rotation-invariant models:

import traja

df = traja.generate(n=100)

# Rotate by specific angle
rotated = df.traja.augment_rotate(angle=45)

# Random rotation (0-360 degrees)
rotated = df.traja.augment_rotate()

Gaussian Noise 

Add noise for robustness to measurement errors:

# Add 10% noise relative to coordinate range
noisy = df.traja.augment_noise(sigma=0.1)

Time Reversal 

Reverse trajectory temporally when direction doesn’t matter:

reversed_traj = df.traja.augment_reverse()

Scaling 

Scale coordinates for scale-invariant models:

# Scale by specific factor
scaled = df.traja.augment_scale(factor=1.5)

# Random scaling (0.8-1.2x)
scaled = df.traja.augment_scale()

Subsampling 

Subsample for different temporal resolutions:

# Keep every 3rd point
subsampled = df.traja.augment_subsample(step=3)

# Random step (2-5)
subsampled = df.traja.augment_subsample()

Sequence Processing 

For batching variable-length trajectories, you need consistent sequence lengths.

Padding 

Extend trajectories to target length:

# Pad with edge mode (repeat last value)
padded = df.traja.pad_trajectory(target_length=200, mode='edge')

# Pad with zeros
padded = df.traja.pad_trajectory(target_length=200, mode='constant')

# Pad with linear extrapolation
padded = df.traja.pad_trajectory(target_length=200, mode='linear')

Truncation 

Shorten trajectories to target length:

# Keep first N points
truncated = df.traja.truncate_trajectory(target_length=100, mode='end')

# Keep last N points
truncated = df.traja.truncate_trajectory(target_length=100, mode='start')

# Random starting point
truncated = df.traja.truncate_trajectory(target_length=100, mode='random')

Normalization 

Center and scale coordinates for better convergence:

# Center and scale (mean=0, std=1)
normalized = df.traja.normalize_trajectory(scale=True, center=True)

# Center only
normalized = df.traja.normalize_trajectory(scale=False, center=True)

# Scale only
normalized = df.traja.normalize_trajectory(scale=True, center=False)

Feature Extraction 

Automatically extract ML-ready features:

features = df.traja.extract_features()

# Returns DataFrame with columns:
# - displacement: Step-wise displacement
# - speed: Instantaneous speed (if time available)
# - turn_angle: Turn angle between steps (2D only)
# - heading: Direction of movement (2D only)
# - acceleration: Rate of speed change (if time available)

For 3D trajectories:

df_3d = traja.TrajaDataFrame({'x': [0,1,2], 'y': [0,1,2], 'z': [0,1,2]})
features = df_3d.traja.extract_features()

# Additional columns:
# - displacement_xy: 2D displacement
# - displacement_z: Vertical displacement

PyTorch Integration 

Convert trajectories to PyTorch tensors:

# Requires: pip install torch

tensor = df.traja.to_tensor()
# Returns: torch.Tensor of shape (n_points, 2) for 2D

# For 3D trajectories
tensor = df_3d.traja.to_tensor()
# Returns: torch.Tensor of shape (n_points, 3)

# Specify columns explicitly
tensor = df.traja.to_tensor(columns=['x', 'y'])

If PyTorch is not installed, returns numpy array with a warning.

Dataset Splitting 

Split trajectory lists into train/validation/test sets:

# Create multiple trajectories
trajectories = [traja.generate(n=100) for _ in range(50)]

# Split into train/val/test
train, val, test = traja.trajectory.train_test_split(
    trajectories,
    train_size=0.7,
    val_size=0.15,
    test_size=0.15,
    shuffle=True,
    random_state=42  # For reproducibility
)

print(len(train))  # 35
print(len(val))    # 7
print(len(test))   # 8

Complete Pipeline Example 

Combining all features for a production pipeline:

import traja
import numpy as np

def preprocess_trajectory(traj, target_length=100, augment=True):
    """Complete preprocessing pipeline for deep learning."""

    # 1. Normalize
    traj = traj.traja.normalize_trajectory()

    # 2. Standardize length
    if len(traj) < target_length:
        traj = traj.traja.pad_trajectory(target_length, mode='edge')
    elif len(traj) > target_length:
        traj = traj.traja.truncate_trajectory(target_length, mode='random')

    # 3. Augmentation (training only)
    if augment:
        if np.random.random() < 0.5:
            traj = traj.traja.augment_rotate()
        if np.random.random() < 0.3:
            traj = traj.traja.augment_noise(sigma=0.05)

    # 4. Convert to tensor
    tensor = traj.traja.to_tensor()

    return tensor

# Usage
trajectories = [traja.generate(n=100) for _ in range(100)]
train, val, test = traja.trajectory.train_test_split(trajectories)

# Process training data with augmentation
train_tensors = [preprocess_trajectory(t, augment=True) for t in train]

# Process validation data without augmentation
val_tensors = [preprocess_trajectory(t, augment=False) for t in val]

3D Support 

All deep learning features support 3D trajectories:

# Create 3D trajectory
df_3d = traja.TrajaDataFrame({
    'x': np.random.randn(100),
    'y': np.random.randn(100),
    'z': np.random.randn(100)
})

# All operations work the same
rotated_3d = df_3d.traja.augment_rotate()  # Rotates x,y; z unchanged
normalized_3d = df_3d.traja.normalize_trajectory()
tensor_3d = df_3d.traja.to_tensor()  # Shape: (100, 3)

GPS/Lat-Long Support 

Work with GPS coordinates:

# Create trajectory from GPS coordinates
lat = np.array([40.7128, 40.7228, 40.7328])
lon = np.array([-74.0060, -74.0000, -73.9940])

traj = traja.from_latlon(lat, lon)

# Original GPS coordinates preserved
print(traj[['lat', 'lon', 'x', 'y']])

# Now use any DL features
normalized = traj.traja.normalize_trajectory()
tensor = traj.traja.to_tensor()

Demo Notebook 

See the complete demo with visualizations in:

examples/deep_learning_demo.ipynb

The demo uses the public jaguar tracking dataset and shows:

All augmentation methods with visualizations
Sequence processing examples
Feature extraction and plotting
Complete preprocessing pipeline
Train/val/test splitting
GPS coordinate conversion

Use Cases 

These features enable:

Trajectory Prediction - Train LSTM/GRU models to predict future positions
Trajectory Classification - Classify movement patterns (foraging, migrating, etc.)
Anomaly Detection - Detect unusual movement patterns
Generative Models - Generate realistic synthetic trajectories with VAE/GAN
Transfer Learning - Pre-train on one species, fine-tune on another

Visualization 

Traja provides several enhanced visualization methods for trajectory analysis.

Interactive Plots 

Create interactive plots with zoom, pan, and rotation (requires plotly):

# Interactive 2D plot
fig = df.traja.plot_interactive()
fig.show()

# Interactive 3D plot
df_3d = traja.TrajaDataFrame({'x': x, 'y': y, 'z': z})
fig = df_3d.traja.plot_interactive()
fig.show()

Heatmap 

Visualize time spent in each location:

ax = df.traja.plot_heatmap(bins=50, cmap='hot')
plt.show()

Speed and Acceleration 

Plot speed and acceleration profiles:

# Speed over time
ax = df.traja.plot_speed()
plt.show()

# Acceleration over time (requires time column)
ax = df.traja.plot_acceleration()
plt.show()

Comprehensive Analysis 

4-panel visualization showing path, components, speed, and displacement:

fig = df.traja.plot_trajectory_components(figsize=(12, 8))
plt.show()

Performance Optimization 

For processing large trajectory datasets, use parallel batch processing.

Parallel Processing 

Process multiple trajectories in parallel (requires joblib):

import traja

# Create many trajectories
trajectories = [traja.generate(n=1000) for _ in range(100)]

# Process in parallel using all CPUs
normalized = traja.trajectory.batch_process(
    trajectories,
    lambda t: t.traja.normalize_trajectory(),
    n_jobs=-1  # Use all CPUs
)

# With custom function and arguments
def preprocess(traj, target_length=500):
    traj = traj.traja.normalize_trajectory()
    if len(traj) > target_length:
        traj = traj.traja.truncate_trajectory(target_length)
    return traj

processed = traja.trajectory.batch_process(
    trajectories,
    preprocess,
    n_jobs=4,  # Use 4 CPUs
    target_length=500
)

This can provide significant speedup for large datasets (10-100x faster on multi-core machines).

API Reference 

Data Augmentation 

`TrajaAccessor.augment_rotate`([angle])	Rotate trajectory by angle (in degrees) for data augmentation.
`TrajaAccessor.augment_noise`([sigma])	Add Gaussian noise to trajectory coordinates for data augmentation.
`TrajaAccessor.augment_reverse`()	Reverse trajectory temporally for data augmentation.
`TrajaAccessor.augment_scale`([factor])	Scale trajectory coordinates for data augmentation.
`TrajaAccessor.augment_subsample`([step])	Subsample trajectory by taking every nth point for data augmentation.

Sequence Processing 

`TrajaAccessor.pad_trajectory`(target_length)	Pad trajectory to target length for deep learning batching.
`TrajaAccessor.truncate_trajectory`(target_length)	Truncate trajectory to target length for deep learning batching.
`TrajaAccessor.normalize_trajectory`([scale, ...])	Normalize trajectory coordinates for deep learning.

Feature Extraction 

`TrajaAccessor.extract_features`()	Extract common features for machine learning.
`TrajaAccessor.to_tensor`([columns])	Convert trajectory to PyTorch tensor (if torch is available).

Dataset Utilities 

`train_test_split`(trajectories[, train_size, ...])	Split trajectories into train, validation, and test sets for deep learning.
`batch_process`(trajectories, func[, n_jobs])	Apply function to trajectories in parallel for performance.

Visualization Methods 

`TrajaAccessor.plot_interactive`(**kwargs)	Create interactive 2D or 3D trajectory plot using plotly.
`TrajaAccessor.plot_heatmap`([bins, cmap])	Plot 2D heatmap showing time spent in each location.
`TrajaAccessor.plot_speed`(**kwargs)	Plot speed over time.
`TrajaAccessor.plot_acceleration`(**kwargs)	Plot acceleration over time.
`TrajaAccessor.plot_trajectory_components`([...])	Plot comprehensive trajectory analysis with multiple subplots.