---

name: classification description: "Guides Attention-Gated Networks ultrasound classification workflows, including Sononet training, evaluation, HDF5 data layout, and attention overlays." disable-model-invocation: true metadata: disco-role: operating license: MIT

Classification

Use this sub-skill for ultrasound scan-plane classification tasks in Attention-Gated Networks. It covers Sononet, Sononet2, Sononet Grid Attention, FeedForwardClassifier, AggregatedClassifier, the HDF5 ultrasound loader, classification training/testing scripts, and attention overlay export.

Read first

• Read api-reference.md when you need exact model names, wrapper behavior, config fields, aggregation modes, or class and function signatures.
• Read data-layout.md before preparing the ultrasound HDF5 file or debugging loader/sampler failures.
• Read workflows.md for training, testing, checkpoint evaluation, model inspection, and safe attention-overlay export.
• Read troubleshooting.md when CUDA, torchsample, Visdom, sampler, HDF5, or overlay failures appear.
• Run run_classifier.py for skill-owned training and testing commands that replace the source repo's root entry points.
• Run export_attention_overlay.py to replace the source repo's hard-coded attention visualization script with a parameterized, skill-owned helper.
• For fast environment validation, run the root helper ../../scripts/check_env.py --repo-root /path/to/Attention-Gated-Networks --mode classification.

When to use this sub-skill

Use this route when the user asks to:

• train or test ultrasound scan-plane classification models;
• choose between sononet, sononet2, and sononet_grid_attention;
• configure aggregated_classifier, deep supervision, or attention aggregation;
• inspect classifier outputs, class counts, losses, or scikit-learn metrics;
• prepare or validate the us HDF5 dataset layout;
• export compatibility-score attention maps or overlay PNGs;
• debug classification-specific CUDA, Visdom, sampler, HDF5, or checkpoint issues.

Route 3D segmentation, NIfTI validation, and multi-attention U-Net feature-map exports to ../segmentation/SKILL.md instead.

Quick workflow

1. Install the repository with CUDA-enabled PyTorch and the legacy torchsample dependency. Then run:

   python ../../scripts/check_env.py --repo-root /path/to/Attention-Gated-Networks --mode classification
   

2. Prepare an ultrasound HDF5 file with x_train, p_train, x_val, p_val, x_test, p_test, and label_names. See data-layout.md.

3. Copy a Sononet config and replace its dataset path. The source configs use model.output_nc=14, input_nc=1, tensor_dim='2D', and gpu_ids=[0].

4. Train with the bundled replacement when real data is available:

Relative config paths are resolved from the explicit --repo-root; relative data_path values are resolved from the config file's parent. The HDF5 data file and any checkpoint/weights must already exist outside this skill. Bundled runners and check_env.py --config ... reject missing or private /vol/... paths before constructing a dataset.

python scripts/run_classifier.py --repo-root /path/to/Attention-Gated-Networks --config path/to/config.json --mode train

5. Evaluate a checkpoint with the bundled replacement:

   python scripts/run_classifier.py --repo-root /path/to/Attention-Gated-Networks --config path/to/config.json --mode test
   

6. For attention models, use model_type='sononet_grid_attention' and read workflows.md before choosing aggregation_mode and aggregation.

7. Export a safe synthetic overlay, or adapt the command for a real 2D input:

   python scripts/export_attention_overlay.py \
     --repo-root /path/to/Attention-Gated-Networks \
     --config configs/config_sononet_grid_att_8.json \
     --output-dir /tmp/ag-net-attention
   

Key decisions

• CUDA is required for the unmodified wrappers because the model and tensor paths call .cuda().
• The stock ultrasound configs assume 14 classes. Do not reuse them unchanged for a different HDF5 label set.
• AggregatedClassifier is for multiple-output attention models. Plain Sononet classifiers use FeedForwardClassifier.
• Synthetic smoke checks prove wiring only; they do not replace training on the real ultrasound HDF5 file or evaluating a real checkpoint.
• The original attention visualization script hard-codes private paths. Use the bundled helper or parameterize your own script rather than running it as-is.

The source train_classifaction.py contains a 10-hour sleep after the final epoch's updates. It is retained in the source checkout for provenance; use the bundled runner when a bounded run without that hold is required.

Expected outputs

Training writes checkpoints and logs below the configured checkpoint directory and experiment name. Testing writes accumulated metrics and a test_result.pkl inside the model save directory. The bundled attention helper writes overlay PNGs and .npy arrays to the requested output directory.