EMD's max_imf doesn't return the expected number of IMFs

[kritchie]

Describe the bug From the documentation, the `EMD.emd() method is supposed to return max_imf number of IMFs

The decomposition is limited to *max_imf* imfs.

However, it returns that number + 1.

To Reproduce

from PyEMD import EMD
import numpy as np
s = np.random.random(100)

emd = EMD()
IMFs = emd(s, max_imf=3)

assert len(IMFs) == 3

Expected behavior Either return the appropriate number of IMFs or adjust the documentation.

[kritchie]

@laszukdawid I could submit a PR depending on your call. Happy to help if I can, let me know!

[laszukdawid]

Hey @kritchie, I think the confusion is from distinguishing what is an IMF (Intrinsic Mode Function). I had a long chat initially with folks who were using this package (and also for own research). The conclusion was to extract IMFs and then any remaining is added as the residue. In such a case, if you set max_imf=3 you'll get at least 3 signals and sometimes 4 - the last being residue. If you prefer, you can also use emd.get_imfs_and_residue method which returns tuple of (imfs, residue).

Hope this helps, Dawid

[kritchie]

Hi @laszukdawid , thanks for your comment. I understand your point.

I still believe the documentation could be made a bit more explicit, for example the documentation of the method states: Returns IMF functions in numpy array format., there's no mention of the residue here.

Additionally, the return type is documented as:

Returns
-------
IMF : numpy array
    Set of IMFs produced from input signal.

Maybe simply adding a [...] and residue to those documentation strings could make it clearer. That being said, it's not a big deal for me and I'll update my code as per your instructions.

I'm new to using EMD and I love the library, it's very useful! Thank you for your work!

[laszukdawid]

Sorry for closing too early. You're right :) At the very least I could update the documentation to make this more clear.

[laszukdawid]

Added info with commit 7ebc39eb449b234e401d006266430a62de2db0c5