feat: add complex dtype support for mean

[kgryte]

This PR

• resolves RFC: add support for complex input to mean #846.
• adds support for complex data types when computing the arithmetic mean.
• includes special cases which deviate from NumPy et al, but are consistent with real-valued floating-point special cases as outlined in the specification. Namely, if the arithmetic mean is computed as a sum followed by scalar division, then NaN components should only propagate relative to the respective component. However, in NumPy, given array([ 1.+0.j, 2.+0.j, nan+0.j]), NumPy will return nan+nanj when invoking np.mean.
• added a note concerning NaN propagation and the recommendation to use isnan, rather than rely on individual components.

[rgommers]

• includes special cases which deviate from NumPy et al, but are consistent with real-valued floating-point special cases as outlined in the specification. Namely, if the arithmetic mean is computed as a sum followed by scalar division, then NaN components should only propagate relative to the respective component. However, in NumPy, given array([ 1.+0.j, 2.+0.j, nan+0.j]), NumPy will return nan+nanj when invoking np.mean.

PyTorch, JAX and CuPy all yield the same nan + nanj result as NumPy. I don't think it's very useful to specify a special case like this, since it'll just be ignored and in practice be wrong. So I'd at least use "should" rather than "must".

It's possible the behavior in NumPy may change (following CPython's change for division): numpy/numpy#26560.

[asmeurer]

I thought we had decided at some point that the distinction between things like 1. + nanj and nan + nanj is generally undefined in the standard (or am I just remembering a similar discussion about infinites?).

I've certainly taken that view in some places when implement things, taking something like "the result should be nan" to mean isnan(x) should give True, which is the case if either or both components are nan.

[ev-br]

Let me add a +1 LGTM to this proposal. Having mean working for complex arrays is a common need and not having it just means piling workarounds downstream.

[rgommers]

I thought we had decided at some point that the distinction between things like 1. + nanj and nan + nanj is generally undefined in the standard

I think so too, and that is what resulted in the current spec for isnan, which says:

For complex floating-point operands, let a = real(x_i), b = imag(x_i), and
- If a or b is NaN, the result is True.

taking something like "the result should be nan" to mean isnan(x) should give True, which is the case if either or both components are nan.

That sounds right to me, isnan should be the canonical function here.

[kgryte]

I thought we had decided at some point that the distinction between things like 1. + nanj and nan + nanj is generally undefined in the standard (or am I just remembering a similar discussion about infinites?).

The discussion concerned infinities and the one-infinity model. It did not extend to NaNs, apart from the behavior of isnan.

[kgryte]

I've updated the proposed changes to include a note explaining that NaN behavior may deviate across array libraries and generally recommends that users use isnan to verify whether a result is NaN. I have also relaxed the language from must to should. I believe that this should allay the concerns raised by @rgommers and hopefully clear the way for getting this merged.

[rgommers]

The last change addresses the concern about special cases. I also quickly checked that all of NumPy, PyTorch, CuPy, JAX and Dask support complex input to mean and behave the same. So this should be good to go - thanks @kgryte, all!