DOC: Updated documentation for nan_policy=propagate as per #9947

[Sedosa]

Updated documentation for nan_policy='propagate' as per #9947 and added an example for stats.mode to make behaviour clear.

• Update documentation of nan_policy='propagate' to better describe the behaviour (see DOC: Incorrect documentation for nan_policy='propagate in multiple stats functions #9947)
• Add an example to mode as the results differs from what usually occurs.
• Closes DOC: Incorrect documentation for nan_policy='propagate in multiple stats functions #9947

[Kai-Striega]

@Sedosa thanks for taking the time to make a contribution. There are only a few nitpicks which stand out to me:

1. "'propagate' performs calculations keeping nan values" -> "'propagate' attempts to perform the calculations keeping nan values". The function may encounter error(s) due to nan values, and is therefore not guaranteed to actually perform the calculations.
2. "Defines how to handle when input contains nan" -> "Defines how to handle when the input contains nan". I know this wasn't part of the initial issue, but it would be nice to be grammatically correct.

@rgommers would you mind taking a look at this? The issue occurs that nan_policy='propagate' does not behave as documented in stats.mode() (and maybe some other functions). See #9815. Where the proposed solution was:

I think the behaviour of the function is fine: for me, propagate means to keep NaN values, then perform the calculation and see what happens. Often this results in NaN (e.g. if the calculation involves adding the elements), but in the case of mode, every NaN is simply counted as a single occurence (of course, this needs to be clearly stated).

This PR changes the existing documentation of propagate from "returns nan" to follow the above definition and adds an example for mode when nan_policy='propagate' is used.

[rgommers]

This PR changes the existing documentation of propagate from "returns nan" to follow the above definition and adds an example for mode when nan_policy='propagate' is used.

sounds good to me

[rgommers]

so this seems wrong? given the discussion, should be [1., 1., 2., nan]?

[Sedosa]

I understood the discussion to imply the absence of nan in the returned array was what warranted the example..?

[rgommers]

still ongoing in gh-9815 it seems, let's continue there

[chrisb83]

Maybe an example with a 1d vector is easier to understand to illustrate the behaviour.

[Kai-Striega]

@rgommers should we consider merging this? The other discussions seem to have stalled and this documents the current behaviour better than the existing documentation. The only real improvement I can see would be to change the example to be 1d.

[chrisb83]

this documents the current behaviour better than the existing documentation.

I agree

[rgommers]

@rgommers should we consider merging this? The other discussions seem to have stalled and this documents the current behaviour better than the existing documentation.

I'd rather finish the discussion, because if we merge this and leave it that effectively decides the discussion by explicitly documenting behavior (so we shouldn't change it later without deprecation because it's a bug).

Could both of you indicate on the issue what your preferred behavior is?