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

[Warren Weckesser]

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.

Thanks,

Warren