How zakaria76al/usc works
Project type and purpose
• This is an open-source deep learning pipeline for underwater acoustic signal classification.
• It defines two neural network architectures (MFCC-based hybrid and end-to-end convolutional) and provides scripts for feature extraction, training, and inference.
File structure
Top-level files and folders:
• features.py – dataset loading & feature extraction module
• model.py – Keras model definitions (two architectures)
• params.py – hyperparameter and configuration container
• inference.py – script to run inference on a saved model
• requirements.txt – dependencies (e.g., TensorFlow/Keras, librosa)
• saved_models/ – zipped trained model archives
• weights/ – raw HDF5 model weights
• file.wav – sample input audio
• readme.md – project overview and results
Architectural hints
• A clear separation of concerns: data prep (features.py), model definition (model.py), configuration (params.py), and runtime inference (inference.py).
• Model artifacts are persisted in two forms: zipped archives (saved_models/) and HDF5 weights (weights/).
README for additional insights
• Confirms two architectures: “Hybrid” (MFCC + conv blocks) and “End-to-end” (raw signal input).
• Describes pipeline stages: feature extraction → model training → inference → performance evaluation.
a. Main components
1. Data Input
• Raw .wav files (e.g., file.wav) or dataset directories (DeepShip, ShipsEar).
2. Feature Extraction Module (features.py)
• Static MFCC extraction (hybrid model).
• Optional spectrogram generator for end-to-end.
3. Model Definition (model.py)
• Hybrid network architecture.
• End-to-end network architecture.
4. Configuration (params.py)
• Hyperparameters (learning rate, batch size, number of epochs, model type selector).
5. Training & Serialization
• Training process (Keras.fit).
• Save weights (.hdf5) and zipped models (.zip).
6. Model Storage
• weights/ directory
• saved_models/ directory
7. Inference Module (inference.py)
• Loads model architecture + weights.
• Takes file.wav or batch of files.
• Outputs classification results (labels, confidences).
8. Reporting & Results
• Console or file log of accuracy, precision, recall, F1.
b. Relationships and data flow
• Two parallel flows from Feature Extraction → Model Definition → Training.
• Outputs from Training → Model Storage.
• Inference Module loads from Model Storage and uses Model Definition.
• Inference Module → Reporting & Results.
c. Architectural patterns & principles
• Modular pipeline: each stage encapsulated in its own script.
• Separation of concerns between data prep, model logic, and inference.
• Reproducibility: parameters externalized in params.py, models versioned in storage directories.
d. Key technologies & libraries
• Python 3.x
• TensorFlow/Keras for DL
• librosa (or similar) for audio feature extraction
• HDF5 for weight serialization
• Zip archive for model packaging