feat: add stats/strided/dmadfmsorted

[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: na
• task: lint_r
  status: na
• task: lint_c_src
  status: missing_dependencies
• task: lint_c_examples
  status: missing_dependencies
• task: lint_c_benchmarks
  status: missing_dependencies
• 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 #N/A.

Description

What is the purpose of this pull request?

This pull request introduces a new stats/strided package, dmadsorted, which computes the median absolute deviation (MAD) for sorted double-precision floating-point strided arrays.

The median absolute deviation is a robust measure of statistical dispersion that is less sensitive to outliers than variance or standard deviation. Adding dmadsorted extends the existing family of strided statistical functions (e.g., dmediansorted) and provides a commonly used robust statistic in a performance-oriented, strided form.

This PR includes:

• A JavaScript implementation following existing stats/strided/*sorted conventions
• A corresponding C API implementation
• Comprehensive JavaScript tests
• C benchmarks to evaluate performance
• Usage examples and documentation (README and REPL help)

Related Issues

Does this pull request have any related issues?

This pull request has no related issues.

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.

The implementation assumes sorted input, consistent with other *sorted strided APIs.

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

---

@stdlib-js/reviewers

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
stats/strided/dmadfmsorted	$\color{red}366/372$ $\color{green}+98.39%$	$\color{red}24/28$ $\color{green}+85.71%$	$\color{green}4/4$ $\color{green}+100.00%$	$\color{red}366/372$ $\color{green}+98.39%$

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

[Om-A-osc]

Hey @kgryte, I hope this doesn’t already exist (I checked and couldn’t find it). The median absolute deviation (MAD) would be a really valuable addition to stats/strided. Please take a look when you get a chance.

[kgryte]

A few comments:

1. Use of the abbreviation mad should be reserved for "mean absolute deviation", not median absolute deviation from the median. For the latter, the abbreviation should be madfm.
2. Your algorithm below needs work. (a) If the array is already sorted, what does this tell us about the sort order of the deviations from the median? Are they not already sorted? (b) And if they are already sorted, is it actually necessary to compute the deviations across the entire array? (c) If not, how might you compute the median absolute deviation in O(1)?

[kgryte]

Okay. Re: 2. I see that madfm requires that the deviations be sorted based on their absolute differences. Even then, how you are allocating a generic array for handling this is not desirable. Furthermore, you should be using blas/ext/base/dsort for sorting a double-precision floating-point strided array.

[kgryte]

Left initial comments.

[kgryte]

I don't think this is desirable, as it conflates invalid data points with an out-of-memory error.

[kgryte]

You should be using our blas/ext/base/dsort API.

[kgryte]

Instead of dynamic memory allocation, I would suggest pushing this to userland and instead update the signature to

Suggested change

	double API_SUFFIX(stdlib_strided_dmadsorted_ndarray)( const CBLAS_INT N, const double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX ) {
	double API_SUFFIX(stdlib_strided_dmadsorted_ndarray)( const CBLAS_INT N, const double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX, double *Work, const CBLAS_INT strideW, const CBLAS_INT offsetW ) {

where Work is a provided workspace strided array. That also applies to stdlib_strided_dmadsorted above. This is similar to how BLAS/LAPACK APIs can commonly have a workspace array which is provided from user land.

[kgryte]

If you are provided a workspace array, allocation is no longer necessary. However, you will need to copy values to the workspace array.

[kgryte]

A manual for loop is not particularly desirable. If this is a common enough operation, we should create a dedicated strided API for it.

Furthermore, you shouldn't be using fabs. You should be using math/base/special/abs. Meaning, always prefer stdlib APIs if they are available.

[kgryte]

Same thing. Use stdlib APIs.

[kgryte]

This isn't necessary if we support a workspace array.

[Om-A-osc]

Hi @kgryte thank you for the earlier review and feedback.

The previous implementation of the median absolute deviation from the median was intentionally written for simplicity, motivated by an earlier discussion
(#dev-questions > Issue #9361 — feat: add stats/strided/dminabssorted).
However, it indeed had a time complexity of O(N log N) due to explicitly materializing and sorting the deviations.

Based on your comments, I’ve now done a full refactor and updated the implementation to use an O(log N) algorithm, which is the optimal complexity for computing MADFM for already-sorted arrays. Along with this refactor, I’ve also renamed the API to dmadfmsorted to avoid ambiguity with mean absolute deviation, and I’ve tried to reuse existing stdlib APIs wherever possible (e.g., dmediansorted) instead of rolling custom logic.

At a high level, the new algorithm works as follows:

• Since the input array is already sorted, we first compute the median in O(1).
• The absolute deviations from the median naturally form two monotonic sequences:
  • one on the left of the median (when traversed backwards),
  • and one on the right of the median (when traversed forwards).
• Instead of explicitly computing and sorting all deviations, we treat these two monotonic sequences as two virtual sorted arrays and apply a binary-search-based partitioning strategy (similar to the median-of-two-sorted-arrays approach) to directly find the median of the deviations in O(log N) time.

Because this is a complete algorithmic refactor rather than an incremental change, some of the earlier review comments no longer apply in the current version. If you have time, I’d really appreciate another look at the updated implementation when convenient.

Thanks again for the guidance it was very helpful in pushing this toward a more optimal and idiomatic solution.