kernelBetainc incorrect documentation

[jackschmidt]

Checklist

Please ensure the following tasks are completed before filing a bug report.

• Read and understood the Code of Conduct.
• Searched for existing issues and pull requests.

Description

Description of the issue.

The documentation and the source code disagree on the order of the boolean arguments to kernelBetainc.

docs last arguments are: regularized, upper

code last arguments are: invert, normalized
code documentation that invert means upper, and normalized means regularized

Additionally, the code for the case where storage is newly allocated drops the last argument.

The numerical cases code agrees with the main.js code and disagrees with the website documentation.

The non-kernel function is documented as regularized, upper.

The non-kernel function's code correctly reverses the arguments to match kernelBetainc's code. Additionally it statically allocates storage, so the bug in the "allocate new storage" is not seen.

The name "invert" for "upper" may also cause confusion with inverse distribution. "upper" and "regularized" seem like fine names to use consistently in both the documentation and the code.

Related Issues

Does this issue have any related issues?

I did not see any.

Questions

Any questions for reviewers?

No.

Other

Any other information relevant to this issue? This may include screenshots, references, stack traces, sample output, and/or implementation notes.

No

Demo

If relevant, provide a link to a live demo.

No.

Reproduction

What steps are required to reproduce the unexpected output?

out1=[0,0];
out1 = kernelBetainc( out1, 0.2, 1.0, 2.0, true, true );
out2 = kernelBetainc( 0.2, 1.0, 2.0, true, true );

Expected Results

What are the expected results?

out1 and out2 should be (exactly) equal.

Actual Results

What are the actual results?

Not equal (Equal, typo in my code, not yours!)

Environments

What environments are affected (e.g., Node v0.4.x, Chrome, IE 11)? If Node.js, include the npm version, operating system, and any other potentially relevant platform information.

all environments where the code can run

[kgryte]

@jackschmidt Thanks for reporting this bug! We'll work to get a fix shortly.

[kgryte]

@Planeshifter Can you look into this?

[kgryte]

@Planeshifter We should also add additional tests here.

[Planeshifter]

Thank you for filing this issue!

We can confirm the errors in the documentation as well as the inconsistent naming and will fix it shortly.

But would you be able to please elaborate a bit more on the unexpected output you are seeing?

When running your example code

out1=[0,0];
out1 = kernelBetainc( out1, 0.2, 1.0, 2.0, true, true );
out2 = kernelBetainc( 0.2, 1.0, 2.0, true, true );

I see both out1 and out2 having the values [ 0.64, 1.6 ].

From what I can tell, the implementation doesn't drop an argument; it's just that the names do not align when only five arguments are supplied and the output array is omitted:

function kernelBetainc( out, x, a, b, invert, normalized ) {
	if ( arguments.length === 5 ) {
		return compute( new Array( 2 ), out, x, a, b, invert ); // here `out` is `x`, `x` is `a`, `a` is `b` etc.
	}
	return compute( out, x, a, b, invert, normalized );
}

[jackschmidt]

Thank you!

My apologies. Yes, the variables are simply renamed. No code error, just disagreement with docs.

Thanks again! I am looking for a stable version of the upper binomial cdf (my simple 1 - summation has returned negative probabilities) and I think your project will work well.

[Planeshifter]

No worries, thanks for the confirmation!

Will post here once the documentation is updated.

With respect to a binomial CDF, just a pointer that we have statistical distributions including functions like PDF, CDF, and quantiles living at https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dists in case you haven't seen them.

[Planeshifter]

With commit 384f5d0, we have now updated the documentation and changed the parameter order of kernelBetainc to match both @stdlib/math/base/special/betainc and the documentation of @stdlib/math/base/special/kernel-betainc. Closing this issue, but please let us know in case you encounter any further issues. Thanks again!