Skip to content

Commit 9a3a0e7

Browse files
anandkaranubcanandkaranubc
committed
docs: add README
--- 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: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - 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: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na ---
1 parent 45f5de0 commit 9a3a0e7

File tree

1 file changed

+174
-0
lines changed
  • lib/node_modules/@stdlib/stats/incr/wstdev

1 file changed

+174
-0
lines changed

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

+174
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# incrwstdev
22+
23+
> Compute a [weighted standard deviation][weighted-standard-deviation] incrementally.
24+
25+
<section class="intro">
26+
27+
The [weighted standard deviation][weighted-standard-deviation] is defined as
28+
29+
<!-- <equation class="equation" label="eq:weighted_standard_deviation" align="center" raw="s = \sqrt{\frac{\displaystyle\sum_{i=0}^{n-1} w_{i} \left( x_{i} - \bar{x} \right)^2}{\displaystyle\sum_{i=0}^{n-1} w_{i}}}" alt="Equation for the weighted standard deviation."> -->
30+
31+
```math
32+
s = \sqrt{\frac{\displaystyle\sum_{i=0}^{n-1} w_{i} \left( x_{i} - \bar{x} \right)^2}{\displaystyle\sum_{i=0}^{n-1} w_{i}}}
33+
```
34+
35+
<!-- <div class="equation" align="center" data-raw-text="s = \sqrt{\frac{\displaystyle\sum_{i=0}^{n-1} w_{i} \left( x_{i} - \bar{x} \right)^2}{\displaystyle\sum_{i=0}^{n-1} w_{i}}}" data-equation="eq:weighted_arithmetic_mean">
36+
<img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@adbea9806383f70c982e3191475c874efba1296b/lib/node_modules/@stdlib/stats/incr/wmean/docs/img/equation_weighted_standard_deviation.svg" alt="Equation for the weighted arithmetic mean.">
37+
<br>
38+
</div> -->
39+
40+
<!-- </equation> -->
41+
42+
</section>
43+
44+
<!-- /.intro -->
45+
46+
<section class="usage">
47+
48+
## Usage
49+
50+
```javascript
51+
var incrwstdev = require( '@stdlib/stats/incr/wstdev' );
52+
```
53+
54+
#### incrwstdev()
55+
56+
Returns an accumulator `function` which incrementally computes a [weighted standard deviation][weighted-standard-deviation].
57+
58+
```javascript
59+
var accumulator = incrwstdev();
60+
```
61+
62+
#### accumulator( \[x, w] )
63+
64+
If provided an input value `x` and a weight `w`, the accumulator function returns an updated weighted standard deviation. If not provided any input values, the accumulator function returns the current standard deviation.
65+
66+
```javascript
67+
var accumulator = incrwstdev();
68+
69+
var stdev = accumulator( 2.0, 1.0 );
70+
// returns 0.0
71+
72+
stdev = accumulator( 3.0, 2.0 );
73+
// returns ~0.471
74+
75+
stdev = accumulator( 2.0, 0.1 );
76+
// returns ~0.478
77+
78+
stdev = accumulator();
79+
// returns ~0.478
80+
```
81+
82+
</section>
83+
84+
<!-- /.usage -->
85+
86+
<section class="notes">
87+
88+
## Notes
89+
90+
- Input values are **not** type checked. If provided `NaN` or a value which, when used in computations, results in `NaN`, the accumulated value is `NaN` for **all** future invocations. If non-numeric inputs are possible, you are advised to type check and handle accordingly **before** passing the value to the accumulator function.
91+
92+
</section>
93+
94+
<!-- /.notes -->
95+
96+
<section class="examples">
97+
98+
## Examples
99+
100+
<!-- eslint no-undef: "error" -->
101+
102+
```javascript
103+
var uniform = require( '@stdlib/random/base/uniform' );
104+
var incrwstdev = require( '@stdlib/stats/incr/wstdev' );
105+
106+
var accumulator;
107+
var v;
108+
var w;
109+
var i;
110+
111+
// Initialize an accumulator:
112+
accumulator = incrwstdev();
113+
114+
// For each simulated datum, update the weighted standard deviation...
115+
for ( i = 0; i < 100; i++ ) {
116+
v = uniform( 0.0, 100.0 );
117+
w = uniform( 0.0, 100.0 );
118+
accumulator( v, w );
119+
}
120+
console.log( accumulator() );
121+
```
122+
123+
</section>
124+
125+
<!-- /.examples -->
126+
127+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
128+
129+
<section class="related">
130+
131+
* * *
132+
133+
## See Also
134+
135+
- <span class="package-name">[`@stdlib/stats/incr/kurtosis`][@stdlib/stats/incr/kurtosis]</span><span class="delimiter">: </span><span class="description">compute a corrected sample excess kurtosis incrementally.</span>
136+
- <span class="package-name">[`@stdlib/stats/incr/mean`][@stdlib/stats/incr/mean]</span><span class="delimiter">: </span><span class="description">compute an arithmetic mean incrementally.</span>
137+
- <span class="package-name">[`@stdlib/stats/incr/stdev`][@stdlib/stats/incr/stdev]</span><span class="delimiter">: </span><span class="description">compute a corrected sample standard deviation incrementally.</span>
138+
- <span class="package-name">[`@stdlib/stats/incr/mstdev`][@stdlib/stats/incr/mstdev]</span><span class="delimiter">: </span><span class="description">compute a moving corrected sample standard deviation incrementally.</span>
139+
- <span class="package-name">[`@stdlib/stats/incr/skewness`][@stdlib/stats/incr/skewness]</span><span class="delimiter">: </span><span class="description">compute a corrected sample skewness incrementally.</span>
140+
- <span class="package-name">[`@stdlib/stats/incr/summary`][@stdlib/stats/incr/summary]</span><span class="delimiter">: </span><span class="description">compute a statistical summary incrementally.</span>
141+
- <span class="package-name">[`@stdlib/stats/incr/variance`][@stdlib/stats/incr/variance]</span><span class="delimiter">: </span><span class="description">compute an unbiased sample variance incrementally.</span>
142+
143+
</section>
144+
145+
<!-- /.related -->
146+
147+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
148+
149+
<section class="links">
150+
151+
<!-- NOTE: The link below needs to be updated to a more accurate or relevant source. -->
152+
[weighted-standard-deviation]: https://en.wikipedia.org/wiki/Weighted_arithmetic_mean#Weighted_sample_variance
153+
154+
<!-- <related-links> -->
155+
156+
[@stdlib/stats/incr/stdev]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/stdev
157+
158+
[@stdlib/stats/incr/kurtosis]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/kurtosis
159+
160+
[@stdlib/stats/incr/mean]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/mean
161+
162+
[@stdlib/stats/incr/mstdev]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/mstdev
163+
164+
[@stdlib/stats/incr/skewness]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/skewness
165+
166+
[@stdlib/stats/incr/summary]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/summary
167+
168+
[@stdlib/stats/incr/variance]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/variance
169+
170+
<!-- </related-links> -->
171+
172+
</section>
173+
174+
<!-- /.links -->

0 commit comments

Comments
 (0)