deepRetinotopy_TheToolbox

Abstract

Registration-consistent models (breaking change in predictions): The training targets (HCP 7T retinotopy maps) and the myelin input were re-expressed from the HCP MSMAll registration into the FreeSurfer sphere.reg frame of the curvature inputs. The two registrations place the same fs_LR 32k vertex ~5 mm apart in early visual cortex, so inputs and targets were previously misaligned. All models were retrained on the frame-consistent data (same recipe as v1.0.19: whole-brain ROI, SWA, 5 seeds). Do not mix predicted maps from this version with earlier versions in one analysis: predictions are now in the sphere.reg frame, consistent with the curvature route. Compare against empirical maps resampled through sphere.reg, not MSMAll. Template sphere verification: deepRetinotopy and signMaps now verify the fs_LR-deformed_to-fsaverage template spheres by checksum and refuse to run with any other version. Two versions exist in HCPpipelines: the original 2016 release (commit ab8895fb), which the deepRetinotopy models were trained with, and the 2017 "dedrifted" update (commit eee524bc, current master). Predictions are only valid when inference uses the identical spheres as training, so the pipeline stops if the 2017 version is detected. Download the pinned 2016 release linked in the README; DEEPRETINOTOPY_SKIP_TEMPLATE_CHECK=1 bypasses the check (not recommended). Predicted-map filenames now carry a -spherereg token (e.g. [sub].predicted_polarAngle_visualCoord-spherereg-model.lh.native.func.gii) marking the registration frame of the new models, so outputs from this release never collide with pre-1.1.0 (MSMAll-frame) maps in the same subjects directory. Downstream scripts that glob the old *visualCoord-model* pattern need updating; signMaps -m visualCoord-model still processes legacy maps. Step 1 also verifies previously generated curvature files (the template's provenance is embedded in each file) and refuses to reuse 2017-derived ones. Robustness of multi-subject runs: A subject that fails in a parallel step no longer vanishes silently: the pipeline reports which subjects failed, continues with the subjects that succeeded, and finishes with a warning summary and nonzero exit code. Re-running the same command only redoes the missing work. Environment problems (missing FreeSurfer/Workbench tools) and runs where no subject succeeds abort immediately with a clear message. signMaps writes timestamped logs to /logs/, matching deepRetinotopy (no more ~/signMap_*.log). Field-sign maps are now computed with ROI-restricted resampling and re-thresholded to strict {−1, 0, +1}, removing edge-of-ROI contamination present in earlier versions. Training & internals: New HCP_spherereg dataset option and read_HCP_gifti reader train directly from per-subject GIFTI files in the re-expressed frame; the full re-expression pipeline, its validation checkpoints, and the run report ship in scripts/spherereg_targets/. 2_inference.py: --tag now also names single-map (pRF size) outputs; the redundant --model_path argument was removed (use --model_dir). Model weights for this release are fetched from a new OSF directory (models/v3). Issue to be fixed in the next release: -o is silently ignored if the output directory doesn't exist yet — run mkdir -p first. Long-standing bug (since 1.0.19); it will be fixed in v1.1.1. (Sorry!!)