fix: normalize Jensen-Shannon distance to unit range by ranadeepsingh · Pull Request #2631 · microsoft/SynapseML

Rana Singh (ranadeepsingh) · 2026-08-14T20:59:43Z

Related Issues/PRs

Fixes #2006

Related: #2630 independently fixes reference-only category support and custom-reference validation. This PR deliberately does not bundle that work. After #2631 merges, #2630 should rebase and update its two explicit natural-log JS expectations to the normalized scale.

What changes are proposed in this pull request?

Normalize Jensen-Shannon distance to its documented [0, 1] range by converting only its divergence from natural-log units to base-2 units:

JS distance = sqrt((KL(P || M) + KL(Q || M)) / (2 * ln(2)))

The shared relative-entropy helper remains natural-log based, so KL divergence and all other distribution-balance metrics keep their existing semantics and public API. A lower-bound guard clamps negative floating-point cancellation before sqrt.

Coverage now verifies:

identical distributions = 0; disjoint distributions = 1
issue-reproduction near-disjoint value 0.999998765189656
exact intermediate values, argument symmetry, and category-order symmetry
zero-probability/current-only/reference-only support at the metric layer
cancellation near zero and [0, 1] bounds with cross-runtime tolerance
public transformer value, row shape, and transformSchema parity end-to-end
unchanged KL and all other distribution metrics

Docs now state the finite/non-negative/unit-sum domain, midpoint-mixture semantics, no additive smoothing, normalized sample values, and remove the stale static chart that displayed the old scale.

How is this patch tested?

JDK 11 wrapper: core/compile scalastyle test:scalastyle codegen core/testOnly ...DistributionBalanceMeasureSuite — passed
Targeted Scala suite — 15/15 passed, 0 failures/errors/skips
Black 22.3.0 — 189 files unchanged
CI pytest on POSIX filesystem — 78 passed
Notebook JSON validation — 26 cells
Codegen — passed with no tracked generated-file changes
Spark 4.1 replay — patch applied cleanly and test:compile passed on Java 17 / Scala 2.13
Project code-review checklist — no remaining concrete findings

Compatibility

No public class, method, parameter, schema, serialization, dependency, or generated-wrapper change.
KL divergence remains in natural-log units with previous expected values.
Only the documented js_dist numerical scale changes.
Invalid/negative/nonfinite custom references, reference-only categories, and support union are owned by fix(core): include reference-only distribution categories #2630; this PR documents the valid probability domain and composes cleanly with that work.

Final validated revisions

Upstream master: f7a1dc50d09d400d279d08bf69a1fac322896748
PR head: 54e4cead22567f11765f4f51fb85880e8e420dd3

github-actions · 2026-08-14T20:59:53Z

Hey Rana Singh (@ranadeepsingh) 👋!
Thank you so much for contributing to our repository 🙌.
Someone from SynapseML Team will be reviewing this pull request soon.

We use semantic commit messages to streamline the release process.
Before your pull request can be merged, you should make sure your first commit and PR title start with a semantic prefix.
This helps us to create release messages and credit you for your hard work!

Examples of commit messages with semantic prefixes:

fix: Fix LightGBM crashes with empty partitions
feat: Make HTTP on Spark back-offs configurable
docs: Update Spark Serving usage
build: Add codecov support
perf: improve LightGBM memory usage
refactor: make python code generation rely on classes
style: Remove nulls from CNTKModel
test: Add test coverage for CNTKModel

To test your commit locally, please follow our guild on building from source.
Check out the developer guide for additional guidance on testing your change.

azure-pipelines · 2026-08-14T20:59:53Z

Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run.

Rana Singh (ranadeepsingh) · 2026-08-14T20:59:54Z

/azp run

azure-pipelines · 2026-08-14T21:00:07Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Copilot

Pull request overview

This PR corrects the Jensen–Shannon (JS) distance implementation in SynapseML’s core “distribution balance” metrics to match the documented normalized range [0, 1] by converting JS divergence from natural-log units to base-2 units, while keeping KL divergence and other metrics in their existing natural-log semantics.

Changes:

Normalize JS distance by dividing JS divergence by ln(2) (i.e., base-2 relative entropy) and clamp small negative roundoff before sqrt.
Expand and update Scala regression tests to validate normalized endpoints, symmetry, and numerical stability.
Update Responsible AI docs and quickstart notebook expected values/text to reflect the normalized JS distance scale.

Show a summary per file

File	Description
docs/Explore Algorithms/Responsible AI/Quickstart - Data Balance Analysis.ipynb	Updates narrative and expected JS distance values shown in the quickstart.
docs/Explore Algorithms/Responsible AI/Data Balance Analysis.md	Updates JS distance definition/interpretation in documentation.
core/src/test/scala/com/microsoft/azure/synapse/ml/exploratory/DistributionBalanceMeasureSuite.scala	Adds/updates JS distance-focused regression coverage and updates expected values.
core/src/test/scala/com/microsoft/azure/synapse/ml/exploratory/DataBalanceTestBase.scala	Updates the local (test) JS distance calculator to match base-2 normalization and clamp negative roundoff.
core/src/main/scala/com/microsoft/azure/synapse/ml/exploratory/DistributionBalanceMeasure.scala	Implements normalized JS distance in the production metric computation.

Review details

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Files reviewed: 5/5 changed files
Comments generated: 4
Review effort level: Lite

## Summary Normalize only Jensen-Shannon distance to base-2 units so its documented endpoints are exact: identical distributions produce 0 and disjoint distributions produce 1. Preserve natural-log KL divergence and every public API, add cancellation protection near zero, expand numerical regression coverage, and refresh the data-balance documentation and sample values. ## Prompting Intent Own GitHub issue microsoft#2006 end-to-end with an isolated numerical correction. Trace formulas, documentation, and tests; preserve unrelated relative-entropy metrics and API behavior; test endpoints, symmetric intermediate cases, symmetry, bounds, zero handling, and unchanged metrics; validate with JDK 11 guarded SBT commands and project code review; address PR checks and review comments. ## Linked Sources - GitHub issue: microsoft#2006 - Pull request review: microsoft#2631 - Data Balance Analysis docs: docs/Explore Algorithms/Responsible AI/Data Balance Analysis.md - Sample notebook: docs/Explore Algorithms/Responsible AI/Quickstart - Data Balance Analysis.ipynb - Independent code review: no significant findings ## Rationale Divide Jensen-Shannon divergence by ln(2) at the JS call site rather than changing the shared natural-log entropy helper. This is mathematically equivalent to base-2 relative entropy while explicitly preventing changes to KL divergence and other metrics. Clamp only tiny negative JS divergence caused by floating-point cancellation before the square root, preserving valid values and avoiding NaN near the lower bound. Keep endpoint tolerances tight enough to verify the mathematical result without relying on cross-platform bitwise floating-point equality. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Rana Singh (ranadeepsingh) · 2026-08-14T22:28:55Z

/azp run

azure-pipelines · 2026-08-14T22:29:08Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Copilot

Review details

Files reviewed: 5/5 changed files
Comments generated: 0 new
Review effort level: Lite

## Summary Normalize only Jensen-Shannon distance to base-2 units so its documented endpoints are exact: identical distributions produce 0 and disjoint distributions produce 1. Preserve natural-log KL divergence and every public API, add cancellation protection near zero, expand numerical regression coverage, and refresh the data-balance documentation and sample values. ## Prompting Intent Own GitHub issue microsoft#2006 end-to-end with an isolated numerical correction. Trace formulas, documentation, and tests; preserve unrelated relative-entropy metrics and API behavior; test endpoints, symmetric intermediate cases, symmetry, bounds, zero handling, and unchanged metrics; validate with JDK 11 guarded SBT commands and project code review; address PR checks and review comments. ## Linked Sources - GitHub issue: microsoft#2006 - Pull request review: microsoft#2631 - Data Balance Analysis docs: docs/Explore Algorithms/Responsible AI/Data Balance Analysis.md - Sample notebook: docs/Explore Algorithms/Responsible AI/Quickstart - Data Balance Analysis.ipynb - Independent code review: no significant findings ## Rationale Divide Jensen-Shannon divergence by ln(2) at the JS call site rather than changing the shared natural-log entropy helper. This is mathematically equivalent to base-2 relative entropy while explicitly preventing changes to KL divergence and other metrics. Clamp only tiny negative JS divergence caused by floating-point cancellation before the square root, preserving valid values and avoiding NaN near the lower bound. Keep endpoint tolerances tight enough to verify the mathematical result without relying on cross-platform bitwise floating-point equality. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

## Summary Strengthen Jensen-Shannon distance verification with exact-value, symmetry, normalization, cancellation, zero-support, bounds, schema, and end-to-end assertions. Clarify the mathematical domain and smoothing semantics in the docs, and remove a stale chart whose embedded values used the old natural-log scale. ## Prompting Intent Independently make GitHub PR microsoft#2631 merge-ready by auditing its full mathematical and runtime behavior, API compatibility, edge cases, related PR microsoft#2630 interactions, review feedback, checks, generated bindings, Spark compatibility, and downstream documentation. Fix every valid issue without bundling the separate reference-support implementation. ## Linked Sources - GitHub issue microsoft#2006: microsoft#2006 - Pull request microsoft#2631: microsoft#2631 - Related reference-support pull request microsoft#2630: microsoft#2630 - Copilot review feedback: microsoft#2631 (review) - Jensen-Shannon definition: https://en.wikipedia.org/wiki/Jensen%E2%80%93Shannon_divergence ## Rationale Keep the production correction narrowly scoped to dividing Jensen-Shannon divergence by ln(2), preserving natural-log KL divergence and all public APIs. Use independently calculated constants and tolerant assertions to validate semantics across Spark/JVM versions. Document that the unit bound assumes valid probability distributions and that midpoint mixing, not additive smoothing, handles zero support. Leave reference-only category materialization and custom-distribution validation to microsoft#2630 to avoid duplicating unrelated work. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Rana Singh (ranadeepsingh) · 2026-08-16T08:40:42Z

/azp run

azure-pipelines · 2026-08-16T08:40:54Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Copilot

Review details

Files reviewed: 5/5 changed files
Comments generated: 2
Review effort level: Lite

## Summary Address the latest automated review by using explicit unused count values in the JS-distance expression fixture and rewriting the sample interpretation relative to the uniform reference distribution with corrected wording. ## Prompting Intent Resolve every valid active review comment on GitHub PR microsoft#2631, preserve the strong normalized-distance coverage, and keep the documentation mathematically consistent before rerunning required checks. ## Linked Sources - Pull request microsoft#2631: microsoft#2631 - Count-fixture review comment: microsoft#2631 (comment) - Notebook wording review comment: microsoft#2631 (comment) ## Rationale Counts are not read by the private JS-distance expression, so explicit zero placeholders communicate that fact without pretending probabilities are counts. The notebook now compares observed data directly with the configured uniform reference rather than using ambiguous balance terminology. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Rana Singh (ranadeepsingh) · 2026-08-16T08:49:06Z

/azp run

azure-pipelines · 2026-08-16T08:49:20Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Copilot

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

docs/Explore Algorithms/Responsible AI/Data Balance Analysis.md:166

This JS Distance table row contains a large run of whitespace padding inside the table cell (between the sentence ending and the next |). It doesn’t affect rendering, but it makes the markdown noisier to edit and can create unnecessary diffs.

| JS Distance              | Square root of the average base-2 KL divergence from each distribution to their midpoint mixture. The mixture handles zero-probability support without additive smoothing.                                                                                                                                                                          | For finite, non-negative distributions with unit sum, the range is [0, 1]. 0 means identical distributions; 1 means disjoint support. | [Link](https://en.wikipedia.org/wiki/Jensen%E2%80%93Shannon_divergence)                |

Files reviewed: 5/5 changed files
Comments generated: 0 new
Review effort level: Lite

## Summary Compact the JS Distance markdown row so the corrected mathematical description remains easy to review and edit without large whitespace-only spans. ## Prompting Intent Audit and address suppressed as well as active review feedback on GitHub PR microsoft#2631 before declaring the change ready. ## Linked Sources - Pull request microsoft#2631: microsoft#2631 - Final Copilot review with suppressed feedback: microsoft#2631 (review) ## Rationale Markdown tables do not require visual source alignment. Removing cell padding preserves rendered output while preventing noisy future diffs and directly addresses the suppressed review finding. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Rana Singh (ranadeepsingh) · 2026-08-16T08:55:46Z

/azp run

Rana Singh (ranadeepsingh) · 2026-08-16T08:55:47Z

Addressed the final suppressed review feedback in 54e4cea by compacting the JS Distance markdown row without changing rendered content.

azure-pipelines · 2026-08-16T08:55:57Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Copilot

Review details

Files reviewed: 5/5 changed files
Comments generated: 0 new
Review effort level: Lite

Rana Singh (ranadeepsingh) · 2026-08-16T10:09:51Z

Brendan Walsh (@BrendanWalsh) final review requested: head 54e4cead22567f11765f4f51fb85880e8e420dd3 is rebased on master f7a1dc50d09d400d279d08bf69a1fac322896748; all 80 checks pass, all review threads (including suppressed feedback) are resolved, and Copilot final review reports 0 new comments. Repository rules still require one non-author approval/last-push approval.

Rana Singh (ranadeepsingh) · 2026-08-16T10:15:15Z

Final verification for 54e4cead22567f11765f4f51fb85880e8e420dd3 on master f7a1dc50d09d400d279d08bf69a1fac322896748:

all 80 reported checks completed with 79 successes + 1 expected skipped deploy, 0 pending/failures
required microsoft.SynapseML, WIP, and license/cla checks pass
targeted Scala suite: 15/15 passed; JDK 11 compile/style/codegen passed
Black 22.3: 189 files unchanged; CI pytest: 78 passed
Spark 4.1 replay applied cleanly; Java 17 / Scala 2.13 test:compile passed
all active and suppressed review feedback addressed; 0 unresolved threads; final Copilot review generated 0 new comments
no public signature/schema/serialization/dependency/generated-wrapper changes

The only remaining repository-rule gate is the requested non-author/last-push approval from Brendan Walsh (@BrendanWalsh).

Copilot AI lite review requested due to automatic review settings August 14, 2026 20:59

Rana Singh (ranadeepsingh) requested a review from Brendan Walsh (BrendanWalsh) as a code owner August 14, 2026 20:59

Copilot started reviewing on behalf of Rana Singh (ranadeepsingh) August 14, 2026 21:00 View session

Copilot AI reviewed Aug 14, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings August 14, 2026 22:28

Rana Singh (ranadeepsingh) force-pushed the copilot/issue-2006-js-distance branch from 186ed8a to fb81306 Compare August 14, 2026 22:28

Copilot started reviewing on behalf of Rana Singh (ranadeepsingh) August 14, 2026 22:28 View session

Copilot AI reviewed Aug 14, 2026

View reviewed changes

SynapseML CI and others added 2 commits August 16, 2026 01:10

Rana Singh (ranadeepsingh) force-pushed the copilot/issue-2006-js-distance branch from fb81306 to 5d91a61 Compare August 16, 2026 08:40

Copilot AI review requested due to automatic review settings August 16, 2026 08:40

Rana Singh (ranadeepsingh) mentioned this pull request Aug 16, 2026

fix(core): include reference-only distribution categories #2630

Open

Copilot started reviewing on behalf of Rana Singh (ranadeepsingh) August 16, 2026 08:40 View session

Copilot AI reviewed Aug 16, 2026

View reviewed changes

Comment thread .../test/scala/com/microsoft/azure/synapse/ml/exploratory/DistributionBalanceMeasureSuite.scala Outdated

Comment thread docs/Explore Algorithms/Responsible AI/Quickstart - Data Balance Analysis.ipynb Outdated

Copilot AI review requested due to automatic review settings August 16, 2026 08:48

Copilot started reviewing on behalf of Rana Singh (ranadeepsingh) August 16, 2026 08:49 View session

Copilot AI reviewed Aug 16, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings August 16, 2026 08:55

Copilot started reviewing on behalf of Rana Singh (ranadeepsingh) August 16, 2026 08:56 View session

Copilot AI reviewed Aug 16, 2026

View reviewed changes

Uh oh!

Conversation

Rana Singh (ranadeepsingh) commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related Issues/PRs

What changes are proposed in this pull request?

How is this patch tested?

Compatibility

Final validated revisions

Uh oh!

github-actions Bot commented Aug 14, 2026

Uh oh!

azure-pipelines Bot commented Aug 14, 2026

Uh oh!

Rana Singh (ranadeepsingh) commented Aug 14, 2026

Uh oh!

azure-pipelines Bot commented Aug 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Rana Singh (ranadeepsingh) commented Aug 14, 2026

Uh oh!

azure-pipelines Bot commented Aug 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Rana Singh (ranadeepsingh) commented Aug 16, 2026

Uh oh!

azure-pipelines Bot commented Aug 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Uh oh!

Rana Singh (ranadeepsingh) commented Aug 16, 2026

Uh oh!

azure-pipelines Bot commented Aug 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Rana Singh (ranadeepsingh) commented Aug 16, 2026

Uh oh!

Rana Singh (ranadeepsingh) commented Aug 16, 2026

Uh oh!

azure-pipelines Bot commented Aug 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Rana Singh (ranadeepsingh) commented Aug 16, 2026

Uh oh!

Rana Singh (ranadeepsingh) commented Aug 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Rana Singh (ranadeepsingh) commented Aug 14, 2026 •

edited

Loading