Describe the issue:
In Kilosort 2.5 (utils/rezToPhy.m, line 70 at v2.5.2) and Kilosort 3 (utils/rezToPhy.m / rezToPhy2.m, line 77 at v3.0.2) the exported whitening matrix is a scaled identity, with the real export commented out:
% whiteningMatrix = rez.Wrot/rez.ops.scaleproc;
whiteningMatrix = eye(size(rez.Wrot)) / rez.ops.scaleproc;
Kilosort 2.0 (utils/rezToPhy.m, line 69 at v2.0.2) exported the real rez.Wrot. Kilosort 4 exports the real matrix again (kilosort/io.py, where the identity variant survives as a comment: "this was different in KS 2.5 because the binary file was already whitened").
I understand the rationale — params.py points Phy at the already-whitened temp_wh.dat, so an identity is self-consistent inside Phy. But whitening_mat.npy / whitening_mat_inv.npy follow a de-facto contract that downstream tools rely on to unwhiten templates.npy (waveform amplitude estimates, µV conversion, template shape analyses). For every KS2.5/KS3 output:
- "unwhitened" templates remain in whitened space; absolute amplitudes and the cross-channel energy distribution are not what those tools assume;
- amplitude-derived metrics are silently not comparable between KS2.0 outputs and KS2.5/KS3 outputs of the same data.
Ask:
Since the 2.5/3 branches are frozen, a short note in the README of those branches (and/or the KS4 docs section describing the Phy export files) stating that KS2.5/KS3 whitening_mat.npy is an identity placeholder — and that the true transform is recoverable from rez.Wrot in rez2.mat — would let downstream tool authors and re-analysis efforts handle old outputs correctly. Happy to draft that note as a PR if useful.
Context: found while auditing the Kilosort versions used by 60 papers in six high-impact journals (2021–2026); 22 of them pin KS2.5 or KS3.
Generated by Claude Code
Describe the issue:
In Kilosort 2.5 (
utils/rezToPhy.m, line 70 at v2.5.2) and Kilosort 3 (utils/rezToPhy.m/rezToPhy2.m, line 77 at v3.0.2) the exported whitening matrix is a scaled identity, with the real export commented out:Kilosort 2.0 (
utils/rezToPhy.m, line 69 at v2.0.2) exported the realrez.Wrot. Kilosort 4 exports the real matrix again (kilosort/io.py, where the identity variant survives as a comment: "this was different in KS 2.5 because the binary file was already whitened").I understand the rationale —
params.pypoints Phy at the already-whitenedtemp_wh.dat, so an identity is self-consistent inside Phy. Butwhitening_mat.npy/whitening_mat_inv.npyfollow a de-facto contract that downstream tools rely on to unwhitentemplates.npy(waveform amplitude estimates, µV conversion, template shape analyses). For every KS2.5/KS3 output:Ask:
Since the 2.5/3 branches are frozen, a short note in the README of those branches (and/or the KS4 docs section describing the Phy export files) stating that KS2.5/KS3
whitening_mat.npyis an identity placeholder — and that the true transform is recoverable fromrez.Wrotinrez2.mat— would let downstream tool authors and re-analysis efforts handle old outputs correctly. Happy to draft that note as a PR if useful.Context: found while auditing the Kilosort versions used by 60 papers in six high-impact journals (2021–2026); 22 of them pin KS2.5 or KS3.
Generated by Claude Code