fix: added save and read functionality in SSD issue #13328

[Anushreebasics]

issue #13328

Summary
This PR fixes the SSD serialization logic so that objects saved with SSD.save() can be fully restored using SSD.read() without losing internal state.
Previously, some fitted attributes required to reconstruct a trained SSD instance were not persisted, which caused test_ssd_save_load to fail during deserialization.

What was changed?
Refactored the SSD.save() method to persist all fitted attributes required to restore a trained instance.
Updated the corresponding SSD.read() logic to correctly re-initialize these attributes when loading from disk.
Ensured that save/load performs a true round-trip and yields an SSD instance equivalent to the original fitted object.

[Anushreebasics]

@larsoner @mscheltienne Kindly review this PR and let me know if any changes are required

[tsbinns]

I'm happy to look over this @larsoner

[tsbinns]

@Anushreebasics Thanks for opening the PR.

It would be good to set some explicit __get_state__ and __set_state__ methods as per this comment, much like we do for Spectrum and TFR objects (e.g., for TFR objects).

Additionally, we should really also add this save/load behaviour to SPoC, like suggested in the issue/forum post. Actually, the format of generalised eigenvalue decomposition tools was standardised with introduction of the _GEDTransformer class, so now it might make sense to also add the features to the CSP and XdawnTransformer classes (especially now that SPoC inherits from CSP). Though perhaps there might be some caveats making this more complex than I imagined.

Please have a think about adding __get_state__ and __set_state__ methods for the _GEDTransformer class that can be customised for the individual GED classes. For an example, you can have a look at the AverageTFR and EpochsTFR classes to see how their __get_state__ and __set_state__ methods build on those from BaseTFR.

[Anushreebasics]

@tsbinns please review the changes
I’ve added explicit getstate / setstate methods to SSD, building on those in _GEDTransformer, following the same pattern used by BaseTFR. Serialization is now explicit, avoids storing callables, and reconstructs the covariance estimator deterministically on load.
For this PR, I am intentionally limiting the scope to SSD only, to ensure the proposed getstate / setstate approach is correct and aligned with MNE’s design expectations. If this implementation looks good, I will follow up with a separate PR extending the same pattern to SPoC.

[tsbinns]

Thanks for the changes @Anushreebasics. A couple comments and suggestions here.

Also, make sure you add any new functions to the __init__.pyi file, otherwise they can't be imported. This also means that the test which has been added can't run at the moment. Please have a go at running any tests you are adding/changing locally first, that way you'll have a much clearer idea of how the changes are (mis)behaving.

You can find info about running the tests in the contribution guide (here and here). Feel free to ask if you have questions about getting this running.

[Anushreebasics]

@tsbinns please review the changes

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

[Copilot]

The setstate method is not reconstructing the mod_ged_callable attribute, which is required by the base class _GEDTransformer. According to the init method at line 148, this should be set to _ssd_mod. Add 'self.mod_ged_callable = _ssd_mod' after reconstructing the cov_callable.

Suggested change

	)
	)
	# Rebuild modulation GED callable exactly as in __init__
	self.mod_ged_callable = _ssd_mod

[Copilot]

The fitted attribute 'sorter_' is not being explicitly preserved in getstate. This attribute is set by the parent class GEDTransformer.fit() method and may be needed for proper deserialization. Although the parent's getstate copies dict, explicitly including 'sorter' in the fitted attributes list would make the serialization more robust and clear.

Suggested change

	"sfreq_",
	"sfreq_",
	"sorter_",

[Copilot]

The read_ssd function needs to be added to the public API. It should be included in mne/decoding/init.pyi's all list and imported in the stub file so users can import it from mne.decoding. The test imports it directly from mne.decoding, so it must be publicly exported.

[Copilot]

The save method is missing its docstring. It should document the fname and overwrite parameters, describe what the method does, and specify the expected file format (.h5). Follow the docstring pattern used in other MNE save methods like the one in Beamformer.save().

[Copilot]

The save method is incomplete - it creates the state dictionary but never actually writes it to disk. You need to call write_hdf5 to persist the data. The method should import and use write_hdf5 similar to how read_ssd uses read_hdf5. Add the missing write call after line 305.

[Copilot]

Incorrect indentation: the SSD instantiation (lines 446-459) is indented under the if statement on line 443, making it unreachable when the condition is True. This code should be unindented to execute after the validation check. The SSD instantiation should occur regardless of whether the check passes (as long as no exception is raised), so it needs to be at the same indentation level as the if statement.

Suggested change

	ssd = SSD(
	info=state["info"],
	filt_params_signal=state["filt_params_signal"],
	filt_params_noise=state["filt_params_noise"],
	reg=state["reg"],
	n_components=state["n_components"],
	picks=state["picks"],
	sort_by_spectral_ratio=state["sort_by_spectral_ratio"],
	return_filtered=state["return_filtered"],
	n_fft=state["n_fft"],
	cov_method_params=state["cov_method_params"],
	restr_type=state["restr_type"],
	rank=state["rank"],
	)
	ssd = SSD(
	info=state["info"],
	filt_params_signal=state["filt_params_signal"],
	filt_params_noise=state["filt_params_noise"],
	reg=state["reg"],
	n_components=state["n_components"],
	picks=state["picks"],
	sort_by_spectral_ratio=state["sort_by_spectral_ratio"],
	return_filtered=state["return_filtered"],
	n_fft=state["n_fft"],
	cov_method_params=state["cov_method_params"],
	restr_type=state["restr_type"],
	rank=state["rank"],
	)