feat: add stats/incr/wstdev

[anandkaranubc]

Resolves #47

Description

What is the purpose of this pull request?

This pull request:

• Adds the JS implementation of the incremental weighted standard deviation.

Related Issues

Does this pull request have any related issues?

This pull request:

• resolves #47

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

• This PR will also serve as a reference implementation for [RFC]: add stats/incr/wvariance #46

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

---

@stdlib-js/reviewers

[anandkaranubc]

The README link for the weighted standard deviation needs to be updated with a more appropriate reference. Currently, there does not seem to be a specific Wikipedia link for the weighted standard deviation.

Current README link:

stdlib/lib/node_modules/@stdlib/stats/incr/wstdev/README.md

Lines 151 to 153 in 9a3a0e7

	<!-- NOTE: The link below needs to be updated to a more accurate or relevant source. -->
	[weighted-standard-deviation]: https://en.wikipedia.org/wiki/Weighted_arithmetic_mean#Weighted_sample_variance

Additionally, considering the reference implementation stats/incr/wmean, it assumes that weights are always positive. However, this assumption is not explicitly documented anywhere. Should this be clarified? If necessary, I can update the documentation and implementations for both wmean and wstdev to explicitly mention that weights must be positive. Or, the implementation can be modified to include guards before using wsum.

Code snippet:

stdlib/lib/node_modules/@stdlib/stats/incr/wmean/lib/main.js

Line 112 in b0b66d2

mu += ( w/wsum ) * ( x-mu );

As seen above, if wsum is 0, then mu is undefined.

[kgryte]

Currently, there does not seem to be a specific Wikipedia link for the weighted standard deviation.

Given the close relationship between the variance and standard deviation, there won't be a specific link for the standard deviation. The closest reference will be the variance. There aren't any standard deviation-specific algorithms, which don't arise first from computing the variance.

it assumes that weights are always positive.

You're right. In wmean, we should allow for nonnegative weights (i.e., w_i = 0) and only start updating mu once we encounter a non-zero weight.

[anandkaranubc]

@kgryte Open to your feedback on this complete PR.

SVG has been updated. Thanks for the help in OH.

This is the part where I would need your attention the most.

stdlib/lib/node_modules/@stdlib/stats/incr/wstdev/lib/main.js

Line 34 in c790ae8

* ## Method

Also, I changed every occurrence of "weighted standard deviation" to "weighted sample standard deviation" to be consistent with the other standard deviation related implementations in stats/incr/*. I hope this change was essential.