ipg4av

ipg4av applies Intention-aware Policy Graphs (IPGs) [1] to explain Autonomous Vehicle (AV) behaviour. It allows you to:

• generate Policy Graphs (PGs) from real driving data
• infer intentions behind AV behaviour
• produce local and global explanations of AV behaviour

Repository Structure

data/sets/
  ├── nuscenes/       # Preprocessed NuScenes data
  ├── policy_graphs/  # Generated PGs
  └── intentions/     # Generated IPGs + explanatory results

src/
  ├── database/       # NuScenes preprocessing scripts
  ├── discretizer/    # Discretization methods for PGs
  ├── experiments/    # Explanation generation scripts
  ├── metrics/        # PG static metric computation (e.g. entropy)
  └── policy_graph/   # Extensions of pgeon package [2] to build PGs & IPGs for AVs

Getting started

1. Clone the Repository

   git clone https://github.com/HPAI-BSC/ipg4av.git
   cd ipg4av

2. Install Dependencies

   pip install -r requirements.txt

3. Download & Preprocess NuScenes Dataset (optional)

   Preprocessed data is already available at data/sets/nuscenes. To custom the preprocessing or have data available for rendering, see DATASET.md.

Reproducing Results

Start by navigating to the source folder:

   cd src

1. Generate a Policy Graph

Generate a PG of vehicle behaviour considering scene conditions (city, weather, time of day) and a chosen discretisation approach:

python3 -m policy_graph.generate_pg \
    --sensor_file full_v1.0-trainval.csv \
    --camera_file cam_data_v1.0-trainval_18.csv \
    --city_id all \
    --weather all \
    --tod all \
    --discretizer 1b \
    --alpha 18 

sensor_file is the filename of the CSV containing the preprocessed NuScenes sensor data, and camera_file is the filename of the CSV containing the preprocessed NuScenes camera data.

Parameter	Possible Values	Description
--city_id	b,s1, s2, s3, all	City to consider (e.g. Boston)
--weather	all, rain, no_rain	Weather filter on scenes
--tod	all, day, night	Time-of-day filter on scenes
--discretizer	0a, 0b, 1a, 1b, 2a, 2b	PG discretization method
--alpha	number > 0	Detection distance threshold (metres)

The PG generated by this example is already present in data/sets/policy_graphs folder.

2. Hypothesise Desires

• The list of hypothesised desires can be found at experiments/desire_config.py.
• Add/edit to explore different driving intention hypotheses.

3. Compute Intentions and Global Explanations

python3 -m policy_graph.generate_ipg \
    --discretizer 1b \
    --pg_id PG_nuscenes_trainval_Call_D1b_Wall_Tall_18 

pg_id = PG filename without _nodes.csv / _edges.csv.

The IPG generated by this example is already present in data/sets/intentions folder.

4. Explanations

• Global Explanations: once intentions are computed, global intention metrics plots are automatically saved to data/sets/intentions/img. These plots summarise overall behavioural patterns across all scenes.

• Local Explanations: to extract explanations about why the vehicle made a specific decision in a given scene, run src/experiments/scene_analysis.ipynb.

Citation

@InProceedings{10.1007/978-3-032-01399-6_3,
author="Montese, Sara and Gimenez-Abalos, Victor and Cortés, Atia and Cortés, Ulises and Alvarez-Napagao, Sergio",
editor="Calvaresi, Davide and Najjar, Amro and Omicini, Andrea and Aydogan, Reyhan and Carli, Rachele and Ciatto, Giovanni and Tiribelli, Simona and Fr{\"a}mling, Kary",
title="Explaining Autonomous Vehicles with Intention-Aware Policy Graphs",
booktitle="Explainable, Trustworthy, and Responsible AI and Multi-Agent Systems",
year="2026",
publisher="Springer Nature Switzerland",
address="Cham",
pages="40--57"
}

References

[1]: Gimenez-Abalos, V., Alvarez-Napagao, S., Tormos, A., Cortés, U., & Vázquez-Salceda, J. Policy Graphs and Intention: answering ‘why’ and ‘how’ from a telic perspective. In Proceedings of the 24th International Conference on Autonomous Agents and Multiagent Systems (AAMAS '25), International Conference for Autonomous Agents and Multiagent Systems (AAMAS '25).

[2]: Tormos, A., Gimenez-Abalos, V., Vázquez-Salceda, J., & Alvarez-Napagao, S. (2024, May). pgeon applied to Overcooked-AI to explain agents' behaviour. In Proceedings of the 23rd International Conference on Autonomous Agents and Multiagent Systems (pp. 2821-2823).