JOSS review : Suggestions for the examples

Hi Andrew,

I went through the examples, overall, all of them are very clearly explained and very nicely illustrated. I really enjoyed the step-by-step description of the sift such as for analyzing cycles. I've a few suggestions for the examples.

Suggestions

04 - Mask-sift example

A small section describing how to find frequencies for masking could potentially help new users, may be with something simple like a PSD?

When adding the 30HZ sine, it could be interesting to add a subplot with the sum of the two. Something like :

mask = 0.1*np.sin(2*np.pi*30*time_vect)

plt.figure()
plt.subplot(121)
plt.plot(xy)
plt.plot(mask)
plt.xlim(0, 1000)
plt.subplot(122)
plt.plot(xy + mask, color='k')
plt.xlim(0, 1000)

I also suggest to add one or two sentences to explain why adding this sine to the signal helps masking.

05 - HTML representation of the SiftConfig

One non-important but fancy feature you could add to the SiftConfig is to have a HTML representation when printing inside a notebook. Something like that :

class SiftConfig(...):

    [...]
    
    def _repr_html_(self):
        _str_html = "<h3><b>%s %s</b></h3><hr><ul>" % (self.sift_type, self.__class__)
        lower_level = ['imf_opts', 'envelope_opts', 'extrema_opts']
        for stage in self.store.keys():
            if stage not in lower_level:
                _str_html += '<li><b>{0}</b> : {1}</li>'.format(stage, self.store[stage])
            else:
                outer_list = '<li><b>{0}</b></li>%s'.format(stage)
                inner_list = '<ul>'
                for key in self.store[stage].keys():
                    inner_list += '<li><i>{0}</i> : {1}</li>'.format(key, self.store[stage][key])
                _str_html += outer_list % (inner_list + '</ul>')
        return _str_html + '</ul>'

produces the following output in notebooks : image

PAC example

As we discussed, holospectrum and comodulogram are not exactly the same. Going through the examples, I was pleased to find an illustration of the PAC using emd on simulated signals. In my opinion this is a great feature that deserves a proper example as there are many discussion about methods for quantifying PAC and EMD has been proposed for solving the issue of observing PAC with non-oscillatory components (like sharp waveforms).

Cycles examples

Minor point, but examples about cycles uses the IMF-2 to explain your point but when plotting IMF it corresponds to IMF-3 I guess

Typos

  • [SIFT] 01 - sift intro
    • "solutoin"
    • "iteraitons"
  • [SIFT] 03 - Ensemble sift
    • "amount of white noise to he"
    • "Note that is is"
  • [SPECTRAL] : 01 - Hilbert-Huang
    • "high freqnecy"
    • "our defined frequnecy bins"
  • [SPECTRAL] 02 - Holospectrum
    • "top-left" / "to-right" etc. subplot explanations don't follow the figure's layout
  • [CYCLES] 02 - Statistics on cycles
    • What is "DoN"? I didn't found it
    • "cycle feuquency range"
    • "continuous periods of osillations"