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}+0.00%$	$\color{red}24/28$ $\color{green}+0.00%$	$\color{green}4/4$ $\color{green}+0.00%$	$\color{red}366/372$ $\color{green}+0.00%$

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]

Left initial comments.

[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.