feat: add stats/incr/wvariance incremental weighted variance

[Om-A-osc]

---

type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes. report:

• task: lint_filenames status: passed
• task: lint_editorconfig status: passed
• task: lint_markdown status: passed
• task: lint_package_json status: passed
• task: lint_repl_help status: passed
• task: lint_javascript_src status: passed
• task: lint_javascript_cli status: na
• task: lint_javascript_examples status: passed
• task: lint_javascript_tests status: passed
• task: lint_javascript_benchmarks status: passed
• task: lint_python status: passed
• task: lint_r status: na
• task: lint_c_src status: na
• task: lint_c_examples status: na
• task: lint_c_benchmarks status: na
• task: lint_c_tests_fixtures status: na
• task: lint_shell status: na
• task: lint_typescript_declarations status: passed
• task: lint_typescript_tests status: passed
• task: lint_license_headers status: passed ---

Resolves #46.

Description

What is the purpose of this pull request?

This pull request:

• Adds an incremental accumulator for computing the weighted variance.
• Implements a numerically stable, one-pass algorithm based on the weighted Welford method.
• Computes the unnormalized second central moment incrementally and normalizes by the total weight.
• Adds tests validating correctness against batch-computed weighted variance.
• Adds documentation describing the underlying mathematics and usage.

The incremental update follows the weighted Welford formulation:

Related Issues

Does this pull request have any related issues?

This pull request has the following related issues:

• [RFC]: add stats/incr/wvariance #46

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.

• Test fixtures were generated using Python with NumPy to compute batch weighted variance for prefix sequences.
• Tests, benchmarks, and README documentation have been added or updated as appropriate.
• Contributing guidelines were read and followed.

Checklist

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

• Read, understood, and followed the contributing guidelines.

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of AI assistance?

• Yes
• No

Disclosure

No AI assistance was used in the implementation, tests, or documentation.

---

@stdlib-js/reviewers

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
stats/incr/wvariance	$\color{green}207/207$ $\color{green}+0.00%$	$\color{green}16/16$ $\color{green}+0.00%$	$\color{green}2/2$ $\color{green}+0.00%$	$\color{green}207/207$ $\color{green}+0.00%$

The above coverage report was generated for the changes in this PR.

[Om-A-osc]

@kgryte Issue #46 has officially reached legendary status (≈10 years 😄).
I’ve implemented the requested feature would love your review whenever you have time!

[Om-A-osc]

@Planeshifter Please review this.

[Om-A-osc]

@kgryte Hey I did the requested changes.

[Planeshifter]

Missing tests for invalid input types. All incr/* packages test that non-numeric inputs (strings, booleans, null, arrays, objects, functions) are handled. See incr/mpe or incr/wmean test files for the expected pattern.

[Om-A-osc]

Hi @Planeshifter,

I looked into this before implementing and double-checked again now. The two-argument accumulator packages you mentioned incr/wmean and incr/mpe do not perform any type checks on their accumulator inputs beyond NaN handling.

incr/wmean (lib/main.js) has no isNumber, no typeof checks, and no non-numeric input tests in its test file. The accumulator directly computes:

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

without any input validation.

incr/mpe follows the same pattern: no type validation on accumulator arguments and no non-numeric input tests.

incr/rss also follows the same pattern with no type checks on accumulator inputs.

The isNumber + throw TypeError pattern that exists in packages like incr/variance and incr/stdev is used to validate the factory function’s configuration arguments (e.g., incrvariance(mean) validates the optional known-mean parameter), not the data values passed to the accumulator on each call.

Since incrwvariance() takes no factory arguments, there's nothing to validate at construction time. The current implementation already includes isnan checks on the accumulator inputs (x, w) and an arguments.length !== 2 guard, which is consistent with and slightly more defensive than the existing two-argument accumulator packages.

Happy to add non-numeric type checks if that's something we want to introduce as a new convention, but wanted to flag that existing packages don't currently follow that pattern.