How nttcslab/dcase2023_task2_baseline_ae works
Project Type and Purpose
• This is an open-source research baseline tool for first-shot unsupervised anomalous sound detection on the DCASE Challenge Task 2 (2023, 2024, 2025).
• It implements two scoring modes: a simple MSE autoencoder and a selective Mahalanobis distance AE, written in PyTorch.
• Orchestration is driven by shell scripts (train/test/summarize), and core logic lives in Python modules under datasets/, networks/, and top-level scripts.
File Structure and Architectural Patterns
• Top-level CLI/Scripts
• 01_train_2025t2.sh, 02a_test_2025t2.sh, 02b_test_2025t2.sh, 03_summarize_results.sh
• train.py (entry point for training)
• common.py (shared utilities)
• baseline.yaml (configuration)
• Data Layer
• data/ contains raw & processed WAV files for dev/eval across multiple years and machine types
• datasets/ holds dataset loaders, path configs (YAML/CSV), ground-truth CSVs
• Model Layer
• networks/ defines base_model, AE architectures, criterion (MSE, Mahalanobis), and top-level models.py
• Persistence
• models/ (checkpoints, saved_model)
• results/ (raw anomaly scores, aggregated metrics)
• logs/ (training logs)
• Utilities
• tools/ for legacy support, data download scripts, plotting, renaming, result export
• dockerfile, requirements.txt for environment reproducibility
Key Components & Interactions
• External Data Sources → data_download_*.sh (or auto-download) → data/dcaseXXXXt2/
• Dataset Loader (datasets/dcase*_loader.py & loader_common.py) reads raw audio, applies preprocessing (feature extraction configured in baseline.yaml), outputs tensors
• Training Orchestrator (train.py invoked by 01_train_2025t2.sh)
• Loads config → instantiates Dataset & DataLoader → builds AE model(s) via networks/ → trains with MSE loss → after final epoch computes covariance matrices for Mahalanobis mode → saves checkpoints (models/)
• Testing Orchestrator (02a_*.sh / 02b_*.sh)
• Loads trained model & covariance (if Mahalanobis) → runs inference on test set → computes anomaly scores (MSE or Mahalanobis) → writes per-file CSV in results/ → for development also computes AUC, pAUC, precision, recall, F1 → writes summary CSV
• Summarization (03_summarize_results.sh)
• Gathers result CSVs → aggregates into a single table under results/.../summarize/
Architectural Patterns & Design Principles
• Layered architecture:
• Presentation/Orchestration layer (shell scripts, CLI)
• Application logic layer (train.py, common.py)
• Domain/model layer (networks/, criterion)
• Data abstraction layer (datasets/, data/)
• Configuration-driven: baseline.yaml centralizes hyperparameters and file paths
• Modular & extensible: networks/ can be extended with new AE variants; datasets/ can support new years/machine types
• Separation of concerns: data downloading, preprocessing, model training, scoring, and result export are decoupled