[ENH] Add support for AAHC clustering

[rkobler]

Hi pycrostates team @vferat @mscheltienne ! 👋

Thank you for working on a python repository that integrates microstate analysis with MNE python.

I recently started using the repository and felt like adding support for the atomize and agglomerate hierarchical clustering (AAHC) algorithm. The implementation is inspired by the matlab code provided in the eeglab plugin Microstates v 1.2 [1].

Please, let me know if you see merit in adding this method to the package.

Best,
Reinmar

[1] https://www.thomaskoenig.ch/Download/EEGLAB_Microstates/Microstates1.2.zip

[codecov]

Codecov Report

Merging #92 (aa4ef4d) into main (c8bcc0a) will increase coverage by 0.58%.
The diff coverage is 99.77%.

@@            Coverage Diff             @@
##             main      #92      +/-   ##
==========================================
+ Coverage   96.33%   96.92%   +0.58%     
==========================================
  Files          54       56       +2     
  Lines        4120     5005     +885     
==========================================
+ Hits         3969     4851     +882     
- Misses        151      154       +3     

Impacted Files	Coverage Δ
pycrostates/cluster/aahc.py	98.84% <98.84%> (ø)
pycrostates/cluster/__init__.py	100.00% <100.00%> (ø)
pycrostates/cluster/_base.py	93.43% <100.00%> (+0.01%)	⬆️
pycrostates/cluster/kmeans.py	97.76% <100.00%> (-0.02%)	⬇️
pycrostates/cluster/tests/test_aahc.py	100.00% <100.00%> (ø)
pycrostates/io/fiff.py	87.03% <100.00%> (+0.84%)	⬆️
pycrostates/utils/_docs.py	85.50% <0.00%> (-1.45%)	⬇️
pycrostates/utils/_checks.py	99.13% <0.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[mscheltienne]

Thank you very much for adding this algo! I just went once through the code quickly, it looks very good. I will try to test it quickly :)

For the style, you can run black at the root of the repository with the command black . or black pycrostates and it will auto-format the files, fixing most of the style issues.

Also, could you add an entry in the changelog: https://github.com/vferat/pycrostates/tree/main/docs/source/dev/changes
You can add your name and a link to your website/github in names.inc and an entry for this PR in latest.rst 🙏

[vferat]

Hey @rkobler,

Thanks a lot for this contribution, we really appreciate it. As @mscheltienne said, the code is very clean. This a a great addition to the library.
I checked your code with some data, and only find one/two small issues. Please have a look at my review for more details.

[mscheltienne]

I have one question about the argument ignore_polarity. The ModKMeans always ignore polarities, right?
Why is this an option with AAHC and what is a use case of ignore_polarity=False?

[rkobler]

@mscheltienne

I have one question about the argument ignore_polarity. The ModKMeans always ignore polarities, right?
Why is this an option with AAHC and what is a use case of ignore_polarity=False?

This is a valid question. I think the best motivation for including the case ignore_polarity=False are scenarios where one would like to apply clustering to event-related potential (ERP) datasets. In this case, the polarity is informative.

[vferat]

@mscheltienne

I have one question about the argument ignore_polarity. The ModKMeans always ignore polarities, right?
Why is this an option with AAHC and what is a use case of ignore_polarity=False?

This is a valid question. I think the best motivation for including the case ignore_polarity=False are scenarios where one would like to apply clustering to event-related potential (ERP) datasets. In this case, the polarity is informative.

@rkobler is right. For ERP analysis we take into account polarities whereas we ignore it for spontaneous activities ( raw / epochs).

I did not intend to include ERP microstates analysis in pycrostates at first. But it may be interesting. For now, I think we should keep the ignore_polarity hidden from the public API and always use the default value True.

Metrics, .predict() are only implemented to work with ignored polarities. I may lead to wrong results if people try to use them with a cluster that do not ignore polarities.

In the meantime, I'll have a look at how much work is needed to implement changes to take into account polarities in the library.

[mscheltienne]

Ok, then yes +1 to include ignore_polarity in ModKMeans as well in a different PR. And indeed, if for now predict does not work when polarities are not ignored, then let's hard-code self._ignore_polarity = True in AAHC.__init__() with a TODO item to move it back as an argument when we add support for ignore_polartity=False in the base-class, in ModKMeans, and in the metrics.

[mscheltienne]

Only minor comments remain, LGTM.
I especially like the tests on simulated data you added!

[mscheltienne]

LGTM, thanks a lot for this amazing addition, and don't worry about the codacy workflow ;)

[mscheltienne]

Good catch for n_jobs, @vferat I pushed an additional commit to fix the docstring, since the order of the arguments would have been wrong.

[vferat]

Thx @mscheltienne for the fix !

LGTM ! @rkobler thanks a lot for the contribution! Everything went super smooth thanks to your code quality and fast responses 🥇

@all-contributors please add @rkobler for code, doc, ideas and test !

[allcontributors]

@vferat

I couldn't determine any contributions to add, did you specify any contributions?
Please make sure to use valid contribution names.

I couldn't determine any contributions to add, did you specify any contributions?
Please make sure to use valid contribution names.

I've put up a pull request to add @rkobler! 🎉