meowmotion

Detecting Trips, OD Matrices, and Transport Modes from GPS Data
A Python package for processing geolocation data at scale

📖 Documentation • 🛠 Installation • 🚀 Quick Start

🐾 What is MeowMotion?

MeowMotion is a Python package for processing raw GPS data to detect trips, classify transport modes, and generate Origin-Destination (OD) matrices using scalable and modular methods. Originally developed at the Urban Big Data Centre (UBDC), it supports advanced functionality such as:

• Stay point and trip detection
• Activity-based and demographic-based trip scaling
• Generation of 4 OD matrix types (AM, PM, All-day, and Non-peak)
• Machine learning-based travel mode classification

It’s an ideal tool for urban mobility researchers, transport planners, and geospatial data scientists working with mobile GPS traces or passive location data.

📖 Full Documentation

👉 Read the full docs here: https://urbanbigdatacentre.github.io/meowmotion/

The documentation includes:

• Installation instructions
• Data format requirements
• End-to-end usage examples
• Input file specifications
• Details on OD matrix generation and model predictions

🛠 Installation

📌 Prerequisites

• Python 3.11 is recommended for best compatibility.

• Poetry (optional, for source installs):

  pip install poetry
  

🎉 Install via PyPI (Recommended)

The easiest way to get started is to install directly from PyPI:

poetry new project_name
cd project_name
poetry add meowmotion

🔧 For compatibility tips and alternative setups (e.g., using uv), see the Installation Guide.

🚀 Quick Start

Here’s a minimal pipeline example (see full Quick Start guide):

from meowmotion.meowmob import getStopNodes, processFlowGenration, getActivityStats, generateOD
from meowmotion.process_data import getFilteredData
import pandas as pd

raw_df = readData()  # Load your GPS data
filtered_df = getFilteredData(raw_df, impr_acc=10, cpu_cores=4)
stdf = getStopNodes(filtered_df, time_th=300, radius=150, cpu_cores=4)
trip_df = processFlowGenration(stdf, raw_df, cpu_cores=4)
activity_df = getActivityStats(df=raw_df, output_dir='outputs', cpu_cores=4)

# Load shapefile and support files, then generate OD matrices
generateOD(
    trip_df=trip_df,
    shape=shape,
    active_day_df=activity_df,
    hldf=hldf,
    adult_population=adult_population_df,
    org_loc_cols=["origin_geo"],
    dest_loc_cols=["dest_geo"],
    output_dir="outputs",
    cpu_cores=4,
)

📬 Feedback & Support

For questions, suggestions, or collaborations, feel free to reach out via Issues or contact:

📧 [e-mail]

📄 License This project is licensed under the MIT License.