Skip to content

Commit

Permalink
docs: update README
Browse files Browse the repository at this point in the history
---
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: passed
  - 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
---
  • Loading branch information
aayush0325 committed Jan 24, 2025
1 parent a156db4 commit b4118f2
Show file tree
Hide file tree
Showing 2 changed files with 135 additions and 31 deletions.
164 changes: 134 additions & 30 deletions lib/node_modules/@stdlib/stats/base/sstdevyc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,17 +98,16 @@ The use of the term `n-1` is commonly referred to as Bessel's correction. Note,
var sstdevyc = require( '@stdlib/stats/base/sstdevyc' );
```

#### sstdevyc( N, correction, x, stride )
#### sstdevyc( N, correction, x, strideX )

Computes the [standard deviation][standard-deviation] of a single-precision floating-point strided array `x` using a one-pass algorithm proposed by Youngs and Cramer.

```javascript
var Float32Array = require( '@stdlib/array/float32' );

var x = new Float32Array( [ 1.0, -2.0, 2.0 ] );
var N = x.length;

var v = sstdevyc( N, 1, x, 1 );
var v = sstdevyc( x.length, 1, x, 1 );
// returns ~2.0817
```

Expand All @@ -117,18 +116,16 @@ The function has the following parameters:
- **N**: number of indexed elements.
- **correction**: degrees of freedom adjustment. Setting this parameter to a value other than `0` has the effect of adjusting the divisor during the calculation of the [standard deviation][standard-deviation] according to `N-c` where `c` corresponds to the provided degrees of freedom adjustment. When computing the [standard deviation][standard-deviation] of a population, setting this parameter to `0` is the standard choice (i.e., the provided array contains data constituting an entire population). When computing the corrected sample [standard deviation][standard-deviation], setting this parameter to `1` is the standard choice (i.e., the provided array contains data sampled from a larger population; this is commonly referred to as Bessel's correction).
- **x**: input [`Float32Array`][@stdlib/array/float32].
- **stride**: index increment for `x`.
- **strideX**: stride length for `x`.

The `N` and `stride` parameters determine which elements in `x` are accessed at runtime. For example, to compute the [standard deviation][standard-deviation] of every other element in `x`,
The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to compute the [standard deviation][standard-deviation] of every other element in `x`,

```javascript
var Float32Array = require( '@stdlib/array/float32' );
var floor = require( '@stdlib/math/base/special/floor' );

var x = new Float32Array( [ 1.0, 2.0, 2.0, -7.0, -2.0, 3.0, 4.0, 2.0 ] );
var N = floor( x.length / 2 );

var v = sstdevyc( N, 1, x, 2 );
var v = sstdevyc( 4, 1, x, 2 );
// returns 2.5
```

Expand All @@ -138,45 +135,39 @@ Note that indexing is relative to the first index. To introduce an offset, use [

```javascript
var Float32Array = require( '@stdlib/array/float32' );
var floor = require( '@stdlib/math/base/special/floor' );

var x0 = new Float32Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] );
var x1 = new Float32Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element

var N = floor( x0.length / 2 );

var v = sstdevyc( N, 1, x1, 2 );
var v = sstdevyc( 4, 1, x1, 2 );
// returns 2.5
```

#### sstdevyc.ndarray( N, correction, x, stride, offset )
#### sstdevyc.ndarray( N, correction, x, strideX, offsetX )

Computes the [standard deviation][standard-deviation] of a single-precision floating-point strided array using a one-pass algorithm proposed by Youngs and Cramer and alternative indexing semantics.

```javascript
var Float32Array = require( '@stdlib/array/float32' );

var x = new Float32Array( [ 1.0, -2.0, 2.0 ] );
var N = x.length;

var v = sstdevyc.ndarray( N, 1, x, 1, 0 );
var v = sstdevyc.ndarray( x.length, 1, x, 1, 0 );
// returns ~2.0817
```

The function has the following additional parameters:

- **offset**: starting index for `x`.
- **offsetX**: starting index for `x`.

While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offset` parameter supports indexing semantics based on a starting index. For example, to calculate the [standard deviation][standard-deviation] for every other value in `x` starting from the second value
While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameter supports indexing semantics based on a starting index. For example, to calculate the [standard deviation][standard-deviation] for every other element in `x` starting from the second element

```javascript
var Float32Array = require( '@stdlib/array/float32' );
var floor = require( '@stdlib/math/base/special/floor' );

var x = new Float32Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] );
var N = floor( x.length / 2 );

var v = sstdevyc.ndarray( N, 1, x, 2, 1 );
var v = sstdevyc.ndarray( 4, 1, x, 2, 1 );
// returns 2.5
```

Expand All @@ -202,18 +193,12 @@ var v = sstdevyc.ndarray( N, 1, x, 2, 1 );
<!-- eslint no-undef: "error" -->

```javascript
var randu = require( '@stdlib/random/base/randu' );
var round = require( '@stdlib/math/base/special/round' );
var Float32Array = require( '@stdlib/array/float32' );
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
var sstdevyc = require( '@stdlib/stats/base/sstdevyc' );

var x;
var i;

x = new Float32Array( 10 );
for ( i = 0; i < x.length; i++ ) {
x[ i ] = round( (randu()*100.0) - 50.0 );
}
var x = discreteUniform( 10, -50, 50, {
'dtype': 'float32'
});
console.log( x );

var v = sstdevyc( x.length, 1, x, 1 );
Expand All @@ -224,6 +209,125 @@ console.log( v );

<!-- /.examples -->

<!-- C interface documentation. -->

* * *

<section class="c">

## C APIs

<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->

<section class="intro">

</section>

<!-- /.intro -->

<!-- C usage documentation. -->

<section class="usage">

### Usage

```c
#include "stdlib/stats/base/sstdevyc.h"
```

#### stdlib_strided_sstdevyc( N, correction, \*X, strideX )

Computes the [standard deviation][standard-deviation] of a single-precision floating-point strided array using a one-pass algorithm proposed by Youngs and Cramer.

```c
const float x[] = { 1.0f, -2.0f, 2.0f };

float v = stdlib_strided_sstdevyc( 3, 1.0f, x, 1 );
// returns ~2.0817f
```
The function accepts the following arguments:
- **N**: `[in] CBLAS_INT` number of indexed elements.
- **correction**: `[in] float` degrees of freedom adjustment. Setting this parameter to a value other than `0` has the effect of adjusting the divisor during the calculation of the [standard deviation][standard-deviation] according to `N-c` where `c` corresponds to the provided degrees of freedom adjustment. When computing the [standard deviation][standard-deviation] of a population, setting this parameter to `0` is the standard choice (i.e., the provided array contains data constituting an entire population). When computing the corrected sample [standard deviation][standard-deviation], setting this parameter to `1` is the standard choice (i.e., the provided array contains data sampled from a larger population; this is commonly referred to as Bessel's correction).
- **X**: `[in] float*` input array.
- **strideX**: `[in] CBLAS_INT` stride length for `X`.
```c
float stdlib_strided_sstdevyc( const CBLAS_INT N, const float correction, const float *X, const CBLAS_INT strideX );
```

#### stdlib_strided_sstdevyc_ndarray( N, correction, \*X, strideX, offsetX )

Computes the [standard deviation][standard-deviation] of a single-precision floating-point strided array using a one-pass algorithm proposed by Youngs and Cramer and alternative indexing semantics.

```c
const float x[] = { 1.0f, -2.0f, 2.0f };

float v = stdlib_strided_sstdevyc_ndarray( 3, 1.0f, x, 1, 0 );
// returns ~2.0817f
```
The function accepts the following arguments:
- **N**: `[in] CBLAS_INT` number of indexed elements.
- **correction**: `[in] float` degrees of freedom adjustment. Setting this parameter to a value other than `0` has the effect of adjusting the divisor during the calculation of the [standard deviation][standard-deviation] according to `N-c` where `c` corresponds to the provided degrees of freedom adjustment. When computing the [standard deviation][standard-deviation] of a population, setting this parameter to `0` is the standard choice (i.e., the provided array contains data constituting an entire population). When computing the corrected sample [standard deviation][standard-deviation], setting this parameter to `1` is the standard choice (i.e., the provided array contains data sampled from a larger population; this is commonly referred to as Bessel's correction).
- **X**: `[in] float*` input array.
- **strideX**: `[in] CBLAS_INT` stride length for `X`.
- **offsetX**: `[in] CBLAS_INT` starting index for `X`.
```c
float stdlib_strided_sstdevyc_ndarray( const CBLAS_INT N, const float correction, const float *X, const CBLAS_INT strideX, const CBLAS_INT offsetX );
```

</section>

<!-- /.usage -->

<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->

<section class="notes">

</section>

<!-- /.notes -->

<!-- C API usage examples. -->

<section class="examples">

### Examples

```c
#include "stdlib/stats/base/sstdevyc.h"
#include <stdio.h>

int main( void ) {
// Create a strided array:
const float x[] = { 1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f };

// Specify the number of elements:
const int N = 4;

// Specify the stride length:
const int strideX = 2;

// Compute the standard deviation:
float v = stdlib_strided_sstdevyc( N, 1.0f, x, strideX );

// Print the result:
printf( "sample standard deviation: %f\n", v );
}
```
</section>
<!-- /.examples -->
</section>
<!-- /.c -->
* * *
<section class="references">
Expand Down
2 changes: 1 addition & 1 deletion lib/node_modules/@stdlib/stats/base/sstdevyc/src/main.c
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/**
* @license Apache-2.0
*
* Copyright (c) 2020 The Stdlib Authors.
* Copyright (c) 2025 The Stdlib Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
Expand Down

0 comments on commit b4118f2

Please sign in to comment.