Read Jensen-Shannon Distance Through Midpoints, Bases and Category Frames

A Jensen-Shannon number is easier to interpret when the report keeps three objects visible: the two category distributions being compared, their midpoint distribution, and the distinction between divergence and distance. Each object answers a different question. Category probabilities describe the supplied composition, the midpoint provides a reference for two comparisons, and the square root converts the combined divergence into the named distance. Losing any of those roles can turn a correct arithmetic result into an unsupported claim about an AI system or a business outcome.

The examples in this guide are original fictional distributions and count frames. No language model, embedding model, retriever or client evaluation was run. The arithmetic checks concern only the supplied finite inputs. They do not establish that a production report used the same formula, aligned categories correctly or supplied valid reference data. Use the examples to read a result with its assumptions intact, then obtain the actual representations and evaluation evidence before deciding what that result means for a real task.

Keep the midpoint and the square root visible

For the examples here, the midpoint distribution is the coordinate-by-coordinate arithmetic mean of two normalized distributions. Compute the Kullback-Leibler divergence from the first distribution to that midpoint and separately from the second distribution to the midpoint. Their equal average is the Jensen-Shannon divergence. Its square root is the Jensen-Shannon distance. These calculations use the same aligned category labels. A coordinate at the first position of one input must correspond to the same category at the first position of the other input.

The official SciPy Jensen-Shannon interface documentation provides this formula, identifies the returned quantity as the distance, and describes its normalization and logarithm-base options. Those are the limited source concepts used here. We did not execute that function or adopt its published example arrays. Our own calculations below use explicitly authored distributions, finite logarithms and a declared zero-term convention. The guide does not certify library conformance, numerical tolerances for an application or behavior on arbitrary invalid inputs.

Case A deliberately places the distributions on separate category supports. Distribution P is [one-half, one-half, zero] across fictional categories Cedar, Maple and Birch. Distribution Q is [zero, zero, one]. Their midpoint is [one-quarter, one-quarter, one-half]. Using base-two logarithms, each positive contribution compares a probability with a midpoint probability half its size. The two directional divergences to the midpoint are each one. Their average is one, and its square root is also one.

This case has the same numeral for divergence and distance, so it cannot by itself reveal whether a report took the square root. Retain a second case with a nontrivial value when checking an explanation. A single easy example may confirm that an expression produces a familiar number while leaving a missing transformation undetected. Matching the result on Case A is a narrow consistency observation about that example, not proof that an implementation computes every Jensen-Shannon quantity correctly.

Use a nontrivial example to distinguish the quantities

Case B uses two categories with P equal to [three-quarters, one-quarter] and Q equal to [one-quarter, three-quarters]. Their midpoint is [one-half, one-half]. With base-two logarithms, each directional divergence to that midpoint is approximately 0.188722. Because they are equal in this particular example, their average has that same value. The distance is its square root, approximately 0.434421. Reporting 0.188722 under a distance label would omit a material mathematical step.

The equality of the two directional terms in Case B comes from its specially authored swapped composition. It is not a general reason to calculate only one term. An explanation should show both source-to-midpoint comparisons or explicitly justify why they coincide in the particular input. If the two distributions are asymmetric in a different way, their individual contributions need not be equal even though the final combined quantity remains symmetric under exchanging the two inputs.

A useful AI-assisted explanation can preserve the computation as a small labeled sequence: normalized P, normalized Q, midpoint M, divergence P to M, divergence Q to M, their equal average, and the final square root. Ask for both the quantity name and its numeric value at the last two steps. Then inspect the arithmetic and the category mapping yourself. Fluency does not demonstrate that the assistant preserved the exact formula, and an attractive chart does not repair a mislabeled final value.

Do not describe the distance as an error percentage. The number does not count incorrect answers, and its complement is not an accuracy score. Case B compares authored category composition, not actual answers against correctness references. A production report might use category distributions constructed from an evaluation process, but that construction needs its own documentation. The distance alone does not identify which category change is desirable, whether an outcome is severe or whether a proposed system should be released.

Symmetry does not erase the directional ingredients

The combined calculation is unchanged when P and Q exchange roles: the midpoint stays the same and the two divergence terms exchange places inside an equal average. This symmetry is useful when comparing compositions without privileging one as the directional reference. It does not make ordinary Kullback-Leibler divergence symmetric. The separate KL guide addresses why exchanging its reference and comparison distributions can change the result and why support conditions matter.

Case C makes the distinction concrete with P equal to [one-half, one-half] and Q equal to [one, zero]. The direct KL divergence from P to Q has a positive P probability facing a zero Q probability. Under the usual extended-real convention, that directional quantity is unbounded. The reverse direction has a finite value. Jensen-Shannon uses neither of those direct comparisons. Its midpoint is [three-quarters, one-quarter], which is positive wherever either supplied distribution is positive.

Under the declared base-two calculation, the Jensen-Shannon divergence for Case C is approximately 0.311278 and its distance is approximately 0.557923. Exchanging P and Q preserves both final values. This finite result does not mean that a missing probability was repaired, that an unseen category was measured or that the direct KL comparison became finite. The formula changed the comparison reference to a midpoint constructed from both inputs. Preserve that construction when explaining why the results differ.

There is a practical writing lesson here. A report can say that a symmetric midpoint comparison remains finite for the particular supplied support pattern. It should not say that Jensen-Shannon solves missing data or guarantees robust behavior in an application. Zero support in an explicitly supplied distribution and an unknown entry in an incomplete source are different states. The mathematics can use a supplied zero; it cannot establish that an unreported value ought to be zero.

Choose and retain the logarithm base

The logarithm base controls the numerical scale of the divergence and therefore the scale of its square root. This guide uses base two for the principal examples and names that choice explicitly. If an implementation uses natural logarithms, its numbers differ even with identical normalized inputs. Comparing values from two reports without their base settings may attribute a numerical difference to the distributions when the difference comes entirely from the unit of the logarithmic calculation.

For Case A, base-two divergence and distance are each one. Using natural logarithms instead gives divergence equal to the natural logarithm of two, approximately 0.693147. The distance is the square root of that value, approximately 0.832555. The relationship applies to these same supplied distributions. It is a change of numerical scale, not an improvement in agreement, a change in category composition or evidence that one implementation is more accurate than the other.

The base adjustment affects divergence and distance differently. Moving from base-two divergence to natural-log divergence multiplies by the natural logarithm of two. Moving between the corresponding distances multiplies by the square root of that factor. If a report applies the divergence conversion factor directly to a distance, it mixes the two quantities. Show the relevant transformation rather than writing that both versions are merely normalized. The word normalized can refer to several unrelated operations.

Keep any acceptance threshold with the quantity, base and construction on which it was defined. This guide proposes no threshold. A cutoff copied from an unrelated report may use divergence instead of distance, a different base, different category aggregation or different weights between the two source distributions. A familiar numeric range is not enough to establish comparability. Obtain the actual method description before interpreting a value as inside or outside a meaningful operational boundary.

Normalization changes counts into composition

Case D starts with positive-total count vectors [three, one] and [six, two]. Their totals are four and eight. Dividing each count vector by its own total gives the same distribution [three-quarters, one-quarter]. Their midpoint equals that shared distribution, so both source-to-midpoint divergences are zero and the Jensen-Shannon distance is zero. The result describes equal composition under the stated normalization. It does not say the original count vectors are equal.

The second vector has twice the total count of the first. A report concerned with volume needs to retain those totals separately. Equal normalized composition does not establish equal workload, equal exposure, equal opportunity for a rare event or equal evidence strength. The authored counts here are not samples from actual populations, so the comparison makes no uncertainty or independence claim. Arithmetic confirms only the normalized proportions and their resulting distance for these supplied count frames.

The official interface documentation says that its routine normalizes inputs that do not sum to one. That description is important when reading a software report, but this guide does not test the routine's full validation behavior. We explicitly normalize our own positive-total examples. An all-zero count vector has no positive total to divide by under this contract, and negative counts do not represent ordinary nonnegative category counts. Treat such cases as unresolved or invalid for the stated example rather than inventing a default probability distribution.

Ask an AI assistant to preserve raw totals beside normalized proportions. A compact comparison might say that the two invented frames have totals four and eight, identical proportions, and zero composition distance. That is more informative than saying the two datasets match perfectly. The shorter phrase would erase the volume difference and imply a broader equivalence than the calculation supports. Identical proportions also do not establish record identity, equal order, identical text or equal task performance.

Category aggregation can hide a meaningful difference

Case E returns to the two-category distributions in Case B. If both categories are merged into one broader category, each distribution becomes [one]. The midpoint also becomes [one], giving zero divergence and zero distance. The original two-category comparison had nonzero distance. The zero after merging reflects the removal of the within-group distinction. It does not demonstrate that the original category difference disappeared in the underlying records.

Category construction is therefore part of the comparison contract. Record the label set, category definitions, exclusions and aggregation rules. If an earlier report distinguishes two outcome types but a later report combines them, a change in distance may reflect a coarser frame. Align the category definitions before treating the values as a time trend. A column label that happens to be the same across exports does not establish that its inclusion criteria remained unchanged.

An AI-generated summary should keep the category-level changes visible when they matter to the task. Ask which probabilities increased or decreased and which distinctions were removed by grouping. A single symmetric scalar cannot explain why the category distribution changed. Nor can it establish the desirability of a shift. A composition change might be important, unimportant, intended or problematic depending on the actual outcomes represented. That judgment requires task context and evidence beyond the distance.

This does not mean that every report should use the finest imaginable categories. Categories can be inappropriate, unstable or too poorly defined to support a useful comparison. The point is to make the chosen frame explicit and keep comparisons within that frame. If a new grouping is selected, report its relationship to the old grouping and explain which questions it can still answer. Do not hide a structural change behind an unchanged metric title.

An unknown count can affect every normalized coordinate

Case F supplies a complete fictional count vector [one, one] for P and an incomplete vector [one, unknown] for Q. The first Q count is known, but its normalized probability is not yet determined because the total is unknown. This differs from receiving a complete, explicitly normalized probability vector with a declared total. Do not infer the second count from a sum-to-one rule when the inputs are counts and the unknown total has not been supplied.

Two hypothetical completions show the effect. If the second Q count were one, both normalized vectors would be [one-half, one-half] and the distance would be zero. If it were three, Q would normalize to [one-quarter, three-quarters], while P would remain [one-half, one-half]. The base-two divergence would then be approximately 0.048795 and the distance approximately 0.220896. These alternatives are authored scenarios, not recovered values or forecasts of the missing count.

One of the two declared Q count entries is known, giving an entry-availability fraction of one-half. That fraction is not semantic coverage, category-probability mass or confidence in the final metric. The full comparison remains unresolved. Computing only the known coordinate and normalizing that smaller frame would answer a different question. Replacing the unknown with zero would introduce an unsupported completion and produce another composition. Keep these operations under separate labels if they are deliberately explored.

A bounded explanation can identify the missing input, show the two hypothetical completions and list what is needed to finish the actual calculation. It should not silently select the completion that yields the most reassuring result. If a production method uses imputation or exclusion, obtain its documented rule and evaluate that method as such. The mathematical formula does not supply an evidential basis for a missing value simply because a final numeric result would be convenient.

Write a comparison that can survive a shorter summary

Begin with the actual objects being compared and the category frame. State whether the inputs are normalized probabilities or raw counts that will be normalized. Preserve each positive total, the shared category mapping, the logarithm base and the distinction between divergence and distance. Then show the midpoint and enough contribution detail to make the calculation reproducible. For an application report, also identify how the input distributions were constructed and which reference information supports their category labels.

Next, describe the mathematical finding at the right scope. Case B establishes a nonzero distance between two authored compositions. Case D establishes equal normalized composition despite different totals. Case E shows that merging categories can remove the represented distinction. Case F leaves the full result unresolved. These conclusions are specific enough to check. A generic statement that the distributions are similar can hide which frame, quantity and missing-data assumptions produced that impression.

Finally, name the task evidence needed before acting. A distribution comparison can support investigation, but it does not independently establish accuracy, cause, fairness, drift severity or a release decision. Review relevant records and references, inspect the category definitions and compare any proposed method change on suitable actual cases. AI can help draft the explanation and organize open questions when the supplied evidence is explicit. It should not turn an authored arithmetic example into an observed evaluation result.

For a reproducibility check, retain more precision in the calculation than in the published display. The rounded values in this guide use six decimal places, with a small declared tolerance for checking the displayed logarithmic results. Exact fractions are used for the authored counts, normalized proportions and midpoint coordinates wherever possible. A display-level match confirms that narrow numerical comparison; it does not establish that the underlying data, category definitions or library behavior were validated. Keep those separate review questions visible when a calculation moves from a teaching example to an actual report.

Questions about Jensen-Shannon reports

Is Jensen-Shannon distance the same number as divergence?

The distance is the square root of the divergence under the stated construction. They coincide in some special cases, including zero and the base-two value one in Case A, but Case B separates them: approximately 0.188722 divergence and 0.434421 distance. Preserve both the quantity name and the base when comparing report values or thresholds.

Why is this comparison symmetric when KL divergence is directional?

The midpoint is unchanged when the two distributions exchange roles, and the two directional comparisons to that midpoint exchange places in an equal average. This does not make direct KL divergence symmetric. Case C distinguishes its unbounded direct comparison from the finite midpoint-based calculation without claiming that missing data or category support was repaired.

Can zero distance prove that two datasets are identical?

It establishes equal normalized composition for the stated complete examples. Case D has different count totals and zero distance after normalization. Case E has zero after categories are merged, despite a difference in the original finer frame. Neither result establishes identical records, texts, chronology, sample strength or task outcomes.

Does the logarithm base matter for a distance report?

Yes. Case A has distance one with base two and approximately 0.832555 with natural logarithms. The divergence and distance conversion factors differ because of the square root. Keep any comparison value or threshold with its formula, base and category construction. This guide supplies no operating cutoff or recommendation for selecting one.

Can an unknown count be treated as zero?

That would be an added assumption. In Case F the missing count affects the total and therefore both normalized Q probabilities. Two explicit hypothetical completions give distances zero and approximately 0.220896. Leave the actual full result unresolved until the missing input or an applicable documented handling policy is available.

What can AI usefully add to this review?

It can draft a labeled calculation explanation, preserve raw totals and category definitions, separate distance from divergence, and identify unresolved inputs. Check that draft against the supplied frame and actual method. This guide reports no model test, production evaluation, reference validation or client result, and a fluent explanation does not provide those missing forms of evidence.