upload

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,84 @@
+---
+license: cc-by-nc-nd-4.0
+library_name: pytorch
+tags:
+  - medical-imaging
+  - 3d-cnn
+  - ultrasound
+  - focused-ultrasound
+  - transcranial-ultrasound
+  - reproduction
+  - fine-tuned
+datasets:
+  - vinkle-srivastav/TFUScapes
+base_model: masonwang025/deeptfus-base
+language:
+  - en
+---
+
+# DeepTFUS: variant C (soft-argmax cranked + anchor restored)
+
+*A reproduction attempt of DeepTFUS, proposed by [Srivastav et al. (arXiv:2505.12998)](https://arxiv.org/abs/2505.12998).*
+
+Fine-tune of [`masonwang025/deeptfus-base`](https://huggingface.co/masonwang025/deeptfus-base)
+that's a single-knob counterfactual to variant B: same aggressive
+soft-argmax recipe, but with the paper's `gradient_L1=0.1` anchor
+restored. Tests whether the anchor matters at this aggression level.
+
+⭐ Statistically tied with B on the three paper headline metrics; the
+anchor exists to suppress secondary hot-spots (median secondary-lobe
+volume drops 99% vs B), not to move `focal_mm`.
+
+## Modification (vs base)
+
+```
+loss.focal_weight       0   to 5e-5     (+soft-argmax term)
+loss.focal_temperature  :   to 0.03     (sharper than A's 0.05)
+loss.grad_weight        0.1 to 0.1      (anchor KEPT, single knob diff vs B)
+```
+
+3-epoch warmup ramp on `focal_weight`. Fine-tune ran 10 epochs from base
+ckpt at `lr=3e-5`; shipped ckpt is `ckpt_epoch_008.pt` (best
+val_focal_mm in plateau).
+
+## Test results (n = 597)
+
+| metric | paper | base | C (this model) | Δ vs base | Δ vs B |
+|---|---:|---:|---:|---:|---:|
+| `relative_l2` mean ± std | 0.414 ± 0.086 | 0.384 ± 0.078 | **0.388 ± 0.077** | +0.005 (in budget) | 0.000 (tied) |
+| `relative_l2` median | 0.394 | 0.369 | 0.372 | +0.003 | 0.000 |
+| `focal_position_error_mm` mean ± std | 2.89 ± 2.14 | 6.49 ± 4.58 | 5.11 ± 3.76 | −1.38 mm | +0.05 (≈ tied) |
+| `focal_position_error_mm` median | 2.45 | 5.15 | **4.15** | **−1.00 mm (−19%)** | −0.03 (≈ tied) |
+| `max_pressure_error` mean ± std | 0.199 ± 0.158 | 0.225 ± 0.116 | 0.239 ± 0.106 | +0.014 | 0.000 |
+| `max_pressure_error` median | 0.166 | 0.217 | 0.239 | +0.022 | 0.000 |
+| `focal_pressure_error` median | : | 0.528 | 0.496 | −0.032 | −0.006 |
+| `focal_iou_fwhm` median | : | 0.143 | 0.136 | −0.007 | 0.000 |
+| `inference_latency_s` median | : | 0.233 | 0.232 | unchanged | unchanged |
+
+## Other variants and discussion
+
+See the [Collection](https://huggingface.co/collections/masonwang025/deeptfus-reproduction-6a03e39286a09470b960511f)
+for the other 5 variants, and the [project page](https://masonjwang.com/projects/reproducing-deeptfus)
+for the full reproduction story, interactive viewer, and discussion of
+trade-offs.
+
+## Usage
+
+```python
+from huggingface_hub import hf_hub_download
+import torch
+
+ckpt = torch.load(
+    hf_hub_download("masonwang025/deeptfus-ft-c-softargmax-anchored", "ckpt_best.pt"),
+    map_location="cpu", weights_only=False,
+)
+```
+
+Model code: [github.com/masonwang025/deeptfus](https://github.com/masonwang025/deeptfus).
+
+## Citation & License
+
+Paper: Srivastav et al., [arXiv:2505.12998](https://arxiv.org/abs/2505.12998), 2025.
+
+License: [CC-BY-NC-ND-4.0](https://creativecommons.org/licenses/by-nc-nd/4.0/),
+matching the TFUScapes dataset.

ckpt_best.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:93d1f20501207d9755e78c5f6fdca661625e61ad5e8633cf3fb54ebd2f68c795
+size 20747205

config.snapshot.yaml

@@ -0,0 +1,48 @@
+data:
+  resolution: 256
+  n_transducer_points: 512
+model:
+  base_width: 16
+  cond_dim: 128
+  n_transducer_freqs: 8
+  dynamic_conv_kernel: 3
+  cross_attention_heads: 4
+  cross_attention_levels:
+  - level1
+  - level2
+  - level3
+  - bottleneck
+  cross_attention_bidirectional: false
+  use_film_decoder: false
+loss:
+  alpha: 5.0
+  grad_weight: 0.1
+  focal_weight: 5.0e-05
+  focal_temperature: 0.03
+  focal_warmup_off: 0
+  focal_warmup_epochs: 3
+  box_weight: 0.0
+train:
+  seed: 0
+  epochs: 15
+  batch_size: 4
+  lr: 3.0e-05
+  weight_decay: 0.0001
+  grad_clip: 1.0
+  num_workers: 4
+  val_every: 1
+  precision: pure-bf16
+  grad_checkpoint_encoder: false
+  channels_last: false
+  compile: false
+  save_every_epochs: 1
+  wandb_project: deeptfus-reproduction
+  wandb_entity: mason-wang
+eval:
+  voxel_size_mm: 0.5
+  focal_threshold_db: -6.0
+  off_target_min_dist_mm: 10.0
+  n_warmup_inferences: 3
+  save_predictions: false
+output:
+  run_dir: runs/deeptfus_ft_E_anchored_aggressive