puddy 0.1.0

A toolkit for analyzing spatial trajectories

Puddy

Puddy is a Python toolkit for analyzing spatial trajectories from files in CSV, JSON, JSONL, or Parquet format. It provides easy loading, normalization, feature extraction, anomaly detection, and rich 3D visualization for geospatial or cartesian trajectory data.

---

Installation

Install via pip:

pip install puddy

Or for development (to auto-update as you change source):

pip install -e .

PyPI: https://pypi.org/project/puddy/

---

What does Puddy do?

• Load trajectories from CSV, JSON, JSONL, Parquet/Arrow, or in-memory DataFrames
• Normalize and group trajectory data using customizable column configs
• Extract features automatically (distance, bounding box, linearity, turns, aspect ratio, etc)
• Detect anomalies using Isolation Forest or Local Outlier Factor
• Visualize trajectories in interactive 3D plots colored by "normalcy"

---

Basic Usage

from puddy import TrajectoryCollection, ColumnConfig, TrajectoryAnalyzer, visualize_trajectories_sample

# 1. Configure which columns to use for each axis and group
config = ColumnConfig.create_geo(
    lon_col="lon",
    lat_col="lat",
    alt_col="alt",
    identifier_col="id"
)

# 2. Load your data (CSV, JSONL, Parquet, DataFrame, etc.)
collection = TrajectoryCollection()
collection.load_from_file("trajectories.csv", config=config)

# 3. Visualize a sample
collection.visualize_sample(n=5)

# 4. Analyze features and anomalies
analyzer = TrajectoryAnalyzer(collection)
analyzer.train_anomaly_detector(method="isolation_forest")
scores = analyzer.get_normalcy_scores()
df = analyzer.get_normalcy_df()
print(df.head())

# 5. Visualize by normalcy
visualize_trajectories_sample(
    analyzer.collection.trajectories,
    scores,
    normal_sample=10,
    show_all_anomalies=True
)

---

Features

• Robust file loading: works with large datasets, compressed files, and many formats
• Customizable coordinate systems and grouping
• Automatic feature engineering for trajectory shape/motion
• Built-in anomaly detection and scoring
• Publication-quality 3D plotting

---

Documentation

For advanced usage, custom features, or troubleshooting, see the Wiki.

---

License

MIT © Jason Frazier