Traffic Project

Tools and benchmarks for acoustic traffic monitoring.

Setup

Create and activate a Python environment, then install the dependencies:

python -m pip install -r requirements.txt

MELAUDIS is distributed as RAR archives. Install one supported extractor and make sure it is available on PATH:

• 7-Zip
• unrar
• unar
• bsdtar

MELAUDIS workflow

run_melaudis_pipeline.py is the main entry point for the MELAUDIS workflow.

It can:

• download and extract the dataset;
• parse filename labels;
• create recording-level data splits;
• audit duplicate and conflicting audio;
• build a conservative deduplicated index;
• run data-quality checks;
• run the test suite;
• train and evaluate the available model families;
• write benchmark summaries.

Quick end-to-end check

Run the smoke profile first:

python run_melaudis_pipeline.py --stage all --profile smoke

The smoke profile uses small subsets and one training epoch. It checks that the data preparation, tests, model loading, training loops, and output writing all work correctly.

It does not produce final benchmark results.

To install the Python dependencies as part of the same command:

python run_melaudis_pipeline.py --install --stage all --profile smoke

Standard benchmark

Run the standard benchmark configurations:

python run_melaudis_pipeline.py --stage all --profile core

When the dataset and metadata have already been prepared, run only the model stage:

python run_melaudis_pipeline.py --stage models --profile core

Extended benchmark

Run the extended regression configurations and multi-seed classification experiments:

python run_melaudis_pipeline.py --stage all --profile full

The full profile can take many hours and requires more disk space than the smoke and core profiles.

When preparation is already complete:

python run_melaudis_pipeline.py --stage models --profile full

Optional IDMT Traffic evaluation

Add --include-idmt to download, prepare, audit, and evaluate IDMT Traffic:

python run_melaudis_pipeline.py \
    --stage all \
    --profile smoke \
    --include-idmt

The smoke profile evaluates a limited IDMT subset. The core and full profiles use the complete generated IDMT index.

CPU execution

CUDA is used when available. Add --cpu to run the supported model workflows on the CPU:

python run_melaudis_pipeline.py \
    --stage models \
    --profile smoke \
    --cpu

Preview commands

Use --dry-run to print the commands without executing them:

python run_melaudis_pipeline.py \
    --stage all \
    --profile smoke \
    --dry-run

Pipeline stages

Individual stages can be run separately:

python run_melaudis_pipeline.py --stage download
python run_melaudis_pipeline.py --stage prepare
python run_melaudis_pipeline.py --stage verify
python run_melaudis_pipeline.py --stage models --profile smoke

The downloader and extractor reuse existing valid files. Completed model runs are also skipped when their expected output files already exist. Use --force to repeat extraction or model execution.

Manual verification

Run the tests:

python -m pytest -q

Compile the Python source files:

python -m compileall scripts models tests run_melaudis_pipeline.py

Display the available benchmark options:

python run_melaudis_pipeline.py --help
python models/run_melaudis_classification_benchmark.py --help
python models/run_melaudis_regression_benchmark.py --help

Outputs

Generated files are not committed to Git.

Main output locations:

• downloaded and extracted data: data/
• generated metadata: data/metadata/
• data audits: artifacts/audit/
• smoke-run outputs: artifacts/verification/melaudis/
• full benchmark outputs: artifacts/benchmarks/
• checkpoints and predictions: inside each model output directory

The main metadata file used by the benchmark runners is:

data/metadata/melaudis_recording_splits_deduplicated_original_assignment.csv

Evaluation behavior

The workflow follows these rules:

• recording groups remain separated across train, validation, and test;
• duplicate groups with conflicting labels are excluded;
• consistent duplicate copies are collapsed;
• model checkpoints are selected using validation metrics;
• benchmark configurations are ranked using validation metrics;
• test metrics are computed after validation-based selection;
• missing class support is reported rather than filled in or inferred.

Some tasks do not have every class represented in every split. The audit reports these cases, and the classification runner skips a task when a required class is absent from the training split.

Detailed documentation

See docs/melaudis_benchmarks.md for the data flow, model profiles, generated files, and individual commands.

Other repository workflows

run_pipeline.py is the entry point for the existing unified traffic catalog, embedding, and foundation-model benchmark workflow.

A short check can be run with:

python run_pipeline.py --smoke

Legacy Colab file

colab_for_the_acoustic_traffic_monitoring_project.py is a historical Colab export. It contains notebook-specific shell commands and is not used by either pipeline entry point.