docs: record drf author preprocess findings

configs/drf/pretreatment_heatmap_drf_118_aligned.yaml

@@ -0,0 +1,25 @@
+coco18tococo17_args:
+  transfer_to_coco17: False
+
+padkeypoints_args:
+  pad_method: knn
+  use_conf: True
+
+norm_args:
+  pose_format: coco
+  use_conf: ${padkeypoints_args.use_conf}
+  heatmap_image_height: 128
+
+heatmap_generator_args:
+  sigma: 8.0
+  use_score: ${padkeypoints_args.use_conf}
+  img_h: ${norm_args.heatmap_image_height}
+  img_w: ${norm_args.heatmap_image_height}
+  with_limb: null
+  with_kp: null
+
+align_args:
+  align: True
+  final_img_size: 64
+  offset: 0
+  heatmap_image_size: ${norm_args.heatmap_image_height}

docs/drf_author_checkpoint_compat.md

@@ -96,6 +96,79 @@ Result:
 
 This is the strongest recovered path so far.
 
+### Verified provenance of `Scoliosis1K-drf-pkl-118-aligned`
+
+The `118-aligned` root is no longer just an informed guess. It was verified
+directly against the raw pose source:
+- `/mnt/public/data/Scoliosis1K/Scoliosis1K-pose-pkl`
+
+The matching preprocessing path is:
+- `datasets/pretreatment_scoliosis_drf.py`
+- default heatmap config:
+  - `configs/drf/pretreatment_heatmap_drf.yaml`
+- archived equivalent config:
+  - `configs/drf/pretreatment_heatmap_drf_118_aligned.yaml`
+
+That means the aligned root was produced with:
+- shared `sigma: 8.0`
+- `align: True`
+- `final_img_size: 64`
+- default `heatmap_reduction=upstream`
+- no `--stats_partition`, i.e. dataset-level PAV min-max stats
+
+Equivalent command:
+
+```bash
+uv run python datasets/pretreatment_scoliosis_drf.py \
+  --pose_data_path /mnt/public/data/Scoliosis1K/Scoliosis1K-pose-pkl \
+  --output_path /mnt/public/data/Scoliosis1K/Scoliosis1K-drf-pkl-118-aligned
+```
+
+Verification evidence:
+- a regenerated `0_heatmap.pkl` sample from the raw pose input matched the stored
+  `Scoliosis1K-drf-pkl-118-aligned` sample exactly (`array_equal == True`)
+- a full recomputation of `pav_stats.pkl` from the raw pose input matched the
+  stored `pav_min`, `pav_max`, and `stats_partition=None` exactly
+
+So `118-aligned` is the old default OpenGait-style DRF export, not the later:
+- `118-paper` paper-literal summed-heatmap export
+- `118` train-only-stats splitroot export
+- `sigma15` / `sigma15_joint8` exports
+
+### Targeted preprocessing ablations around the recovered path
+
+After verifying the aligned root provenance, a few focused runtime/data ablations
+were tested against the author checkpoint to see which part of the contract still
+mattered most.
+
+Baseline:
+- `118-aligned`
+- `BaseSilCuttingTransform`
+- result:
+  - `80.24 Acc / 76.73 Prec / 76.40 Rec / 76.56 F1`
+
+Hybrid 1:
+- aligned heatmap + splitroot PAV
+- result:
+  - `77.30 Acc / 73.70 Prec / 73.04 Rec / 73.28 F1`
+
+Hybrid 2:
+- splitroot heatmap + aligned PAV
+- result:
+  - `80.37 Acc / 77.16 Prec / 76.48 Rec / 76.80 F1`
+
+Runtime ablation:
+- `118-aligned` + `BaseSilTransform` (`no-cut`)
+- result:
+  - `49.93 Acc / 50.49 Prec / 51.58 Rec / 47.75 F1`
+
+What these ablations suggest:
+- `BaseSilCuttingTransform` is necessary; `no-cut` breaks the checkpoint badly
+- dataset-level PAV stats (`stats_partition=None`) matter more than the exact
+  aligned-vs-splitroot heatmap writer
+- the heatmap export is still part of the contract, but it is no longer the
+  dominant remaining mismatch
+
 ### Other tested paths
 
 `configs/drf/drf_author_eval_118_splitroot_1gpu.yaml`
@@ -123,6 +196,8 @@ What these results mean:
 - the original “very bad” local eval was mostly a compatibility failure
 - the largest single hidden bug was the class-order mismatch
 - the author checkpoint is also sensitive to which local DRF dataset root is used
+- the recovered runtime is now good enough to make the checkpoint believable, but
+  preprocessing alone did not recover the paper DRF headline row
 
 What they do **not** mean:
 
@@ -130,6 +205,13 @@ What they do **not** mean:
 - the provided YAML is trustworthy as-is
 - the paper’s full DRF claim is fully reproduced here
 
+One practical caveat on `1:1:2` vs `1:1:8` comparisons in this repo:
+- local `Scoliosis1K_112.json` and `Scoliosis1K_118.json` are not the same train/test
+  split with only a different class ratio
+- they differ substantially in membership
+- so local `112` vs `118` results should not be overinterpreted as a pure
+  class-balance ablation unless the train/test pool is explicitly held fixed
+
 The strongest recovered result:
 - `80.24 / 76.73 / 76.40 / 76.56`