[SciPy-Dev] Replacing binom_test with binomtest in stats.

[Warren Weckesser]

On 12/13/20, Warren Weckesser <warren.weckesser at gmail.com> wrote:
> In the pull request
> [gh-12603](https://github.com/scipy/scipy/pull/12603), I am proposing
> that we deprecate `binom_test` and replace it with `binomtest`.
> Here's why...
>
> We are currently updating quite a few of the statistical tests to have
> return values that have additional attributes and methods. To do this
> in a way that is backwards compatible, we usually return an object
> that acts like a tuple (for consistency with the existing behavior),
> but that also has additional attributes.  And when we add the ability
> to compute a confidence interval for the statistic computed by the
> test, we implement it as a method on the new object that is returned
> by the test.
>
> In [gh-12323](https://github.com/scipy/scipy/pull/12323), we created
> the object that allows us to maintain backwards compatibility while
> returning a more general object.  For this to work, the existing
> function must already return a tuple.
>
> `binom_test` is a test of whether an observed number of "successes"
> out of `n` trials is consistent with a given probability. We want to
> add the calculation of the confidence interval for the estimated
> proportion of successes.  To be consistent with what we are doing in
> other functions, this will be implemented as a method on the object
> returned by the function.
>
> However, we can't use the object created in gh-12323, because
> `binom_test` currently returns a single float (the p-value), not a
> tuple.  I mention some alternative APIs in the PR, but maintaining
> consistency with how other statistical test functions will work makes
> creating a new function, `binomtest`, to replace `binom_test`, the
> most appealing approach.  You can read more about the alternatives in
> the PR gh-12603.
>
> The PR already has a couple approvals, but because of the deprecation,
> this deserves being brought up here on the mailing list for more
> feedback.  Let me know what you think, either here or in comments in
> the PR.
>

Of course, it is shortly *after* I send the email that I find in
https://github.com/scipy/scipy/pull/12323 a comment from Ralf (that I
acknowledged!) that we should only "doc-deprecate" `binom_test`.  I'll
update the gh-12603 to do that.

Warren


> Thanks,
>
> Warren
>