Handle the limit of p = 0 in p log2 p

[jftsang]

This patch defines a helper function, _xlog2x(x), that calculates
x * log2(x) but handles the case x == 0 by returning 0 rather than nan.
This is needed if the power spectrum has any component that is exactly
zero: in particular, if the f = 0 component is zero.

[raphaelvallat]

Hi @jftsang,

Thanks for the PR! A few questions:

1. Do you have any scientific reference (or any kind of documentation) for why this should be the preferred behavior?

2. Should this modification only affect the spectral entropy function?

3. Could you explain what the @np.vectorize decorator is for?

Thanks,
Raphael

[jftsang]

Hi @raphaelvallat,

1. The limit of x log x as x tends to 0 is 0; it follows from l'Hopital's rule. Try https://math.stackexchange.com/questions/470952/limit-of-x-log-x-as-x-tends-to-0, and see this illustration: https://www.wolframalpha.com/input/?i=limit+of+x*log%28x%29+as+x+-%3E+0. I'll try and find a proper academic reference when I get home.
2. I don't know much about the other entropies but I think this result applies whenever a p log p appears, so that your entropy is zero and not undefined.
3. The @np.vectorize decorator allows you to apply the function to a numpy array rather than a single number. We need this because of the if x == 0. Without the decorator, 'the truth value of an array with more than one element is ambiguous'.

Cheers,
Joanna

[raphaelvallat]

This is all perfect, thanks! One last thing before I merge: can you add your changes to the docs/changelog.rst file (with link to the current PR and if desired your GitHub username)? You'll need to start a new version of antropy, i.e. v0.1.5

Cheers,
Raphael

[jftsang]

Done! I've also added a couple of unit tests.

~JMFT

[raphaelvallat]

Merging now, thanks again for the PR!

[jftsang]

Having tested this on a very large file, I have just realised that this _xlog2x function is significantly slower, I suspect because of the conditional test. I shall experiment with using np.nan_to_num instead, which I suspect will be much faster. Sorry for the inconvenience!