TraffixGen

TraffixGen is a Python package for handling and analyzing flight datasets, generating distributions, and providing utilities for Origin-Destination (OD) analysis. It is designed to be flexible and extensible, suitable for research, simulations, and data-driven applications in aviation and transportation.

Features

• Load and manage flight datasets in CSV or DataFrame format.
• Generate Origin-Destination distributions.
• Categorize and analyze flights by type or other criteria.
• NumPy-style docstring documentation for all classes and functions.

Installation

It is recommended to use a virtual environment:

# Create and activate virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

# Install TraffixGen in editable mode
pip install -e .

# Optional dependencies
pip install .[pyarrow].  # For parquet support
pip install .[docs]      # For building documentation
pip install .[plotting]  # For visualization examples

Documentation

Full documentation is generated using Sphinx. After building the docs, you can open them in your browser:

1. Navigate to the docs folder:

   cd docs

2. Build the HTML documentation:

   make html

3. Open the generated index.html in your web browser:
   • macOS

   open _build/html/index.html

   • Linux

   xdg-open _build/html/index.html

   • Windows

   start _build/html/index.html

Examples

TraffixGen includes multiple example scripts to illustrate key functionality:

1. distributions_fit_example.py

Demonstrates generating synthetic data (Gaussian mixtures) and fitting multiple probability distributions.

Key steps:

• Generates 2–4 Gaussian components, optionally discrete.
• Fits and ranks distributions by log_likelihood, AIC, or BIC.
• Plots histogram with top 3 fitted PDFs/PMFs.

Usage:

python examples/distributions_fit_example.py

Output:

• Console table of fit scores.
• Histogram with top 3 fitted distributions.

---

2. FIR_example.py

Visualizes FIR polygons and flight levels using TraffixGen datasets.

Key steps:

• Loads FIR, flight points, and flight datasets.
• Plots airspace boundaries and flight levels vs lat/lon.
• Filters by bounding box, flight level, and excluded airspaces.

Usage:

python examples/FIR_example.py

Output:

• Interactive plots of airspace geometries and flight levels.

---

3. flights_data_example.py

Extracts, analyzes, and generates synthetic flight route data.

Key steps:

• Loads flight and route datasets.
• Filters by bounding box, flight level, and airspace.
• Samples synthetic routes and plots route distributions.
• Exports data to Excel.

Usage:

python examples/flights_data_example.py

Output:

• Console route samples.
• Bar plots of route probabilities.
• Excel file example_data.xlsx.

---

4. flights_example.py

Visualizes flight routes and aircraft types.

Key steps:

• Loads flight data from CSV.
• Counts route and route+aircraft combinations.
• Plots horizontal bar charts.

Usage:

python examples/flights_example.py

Output:

• Bar charts of route and route-type counts.

---

5. route_generation_example.py

Generates flight state spaces and samples trajectories using KDE models.

Key steps:

• Loads flight and route datasets.
• Defines 3 models:
  1. Multidimensional KDE
  2. Derivative KDE
  3. Practical State Space
• Samples OD, aircraft types, and trajectories.
• Visualizes flight metrics.

Usage:

python examples/route_generation_example.py

Output:

• Console samples.
• Plots of trajectories, flight level, ground speed, lat/lon.

---

6. tree_route_generation_example.py

Samples flight trajectories using tree-based state space model (XGBoost).

Key steps:

• Loads datasets.
• Initializes FlightTrajectorySampler and FlightStateSpaceTreesPhased.
• Samples multiple trajectories per OD/type.
• Plots maps and flight profiles.
• Computes R², RMSE, MAE, MAPE.

Usage:

python examples/tree_route_generation_example.py

Output:

• Maps of sampled vs real trajectories.
• Subplots of flight metrics.
• Console performance metrics.

Integrating TraffixGen with ATM Simulators

TraffixGen is designed to be modular and simulator-friendly. If you're building a plugin for an ATM simulator, here’s how you can connect with TraffixGen and leverage its filtering and trajectory generation capabilities.

What TraffixGen Provides

• Flight and route datasets: Load from CSV or generate synthetic routes.
• Filtering utilities: Apply bounding boxes, flight level constraints, and airspace exclusions.
• Trajectory sampling: Use KDE or tree-based models to generate realistic flight paths.

How to Connect

1. Load and Filter Data
   Use examples like flights_data_example.py and FIR_example.py to:

   • Load FIRs and flight datasets
   • Filter by bounding box, flight level, and excluded airspaces
   • Extract OD pairs and aircraft types

2. Generate Trajectories
   Use route_generation_example.py or tree_route_generation_example.py to:

   • Sample trajectories based on OD and aircraft type
   • Choose between KDE-based or tree-based models
   • Output lat/lon, flight level, ground speed, and heading over time

3. Export or Stream to Simulator
   Once you have sampled trajectories:

   • Export them as structured arrays or DataFrames
   • Stream them into your simulator’s state update loop
   • Use timestamps or normalized time to synchronize with your simulation clock

Filtering Example

from traffixgen.filters import filter_by_bbox, filter_by_flight_level

# Example: filter flights within a bounding box and flight level range
filtered_flights = filter_by_bbox(flights_df, bbox=(-10, 40, 10, 60))
filtered_flights = filter_by_flight_level(filtered_flights, min_fl=300, max_fl=400)

Output Format

Trajectory samples typically include:

• latitude, longitude
• flight_level, ground_speed, heading
• elapsed_time or normalized time steps

These can be directly mapped to your simulator’s aircraft state model.

---

For a quick start, try adapting tree_route_generation_example.py to sample trajectories and feed them into your plugin. You can also use the filtering logic from FIR_example.py to restrict traffic to your simulated region.