On 12/13/20, Warren Weckesser <warren.weckesser@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