compare

Use when the question is how areas rank or compare on a stat, or whether two stats can be compared fairly. For one area's own figures use query_data.

Four modes, depending on which arguments are given -- consolidates what were four separate tools (rank_areas, list_comparisons, get_comparison, check_comparability) behind one, since they are all really "how does this stat compare" at different scopes. Exactly one mode's arguments should be given; mixing arguments from different modes (e.g. both stat_key and pair_key, or only one of stat_key_a/stat_key_b) raises an error rather than silently guessing which mode was meant.

1. stat_key alone (no pair_key, no stat_key_a/stat_key_b): ranks every area at one geography level by its latest figure for that stat, for one country -- e.g. "which counties have the highest median sale price" (country="ireland"). stat_key comes from query_data's dataset-listing mode, for the SAME country. level omitted uses this ranking's own default level; pass one of that dataset's own compatible_levels for a different one -- a level this ranking doesn't have registered returns an empty list rather than an error. Where the underlying stat has no honest per-area denominator (crime, homelessness, live_register and similar -- StatsMapped's own RANKING_NO_DENOMINATOR_STATS), each row's rate_per_1000 is the real figure to rank/compare by, not latest_value, which is a raw count dominated by area population size. Always carry forward every entry in caveats when using a row in an answer.

2. pair_key alone: full detail for one registered comparison pair -- each axis's label, unit and publisher, the correlation stats (r, rho, and a leave-one-out sensitivity range naming the single most influential area), and caveats. pair_key comes from mode 4's own response, for the SAME country.

3. Both stat_key_a and stat_key_b given: does StatsMapped have a registered, hand-vetted comparison between these two stats? Registry- backed only -- never computes a fresh correlation for an arbitrary pair. Both stat_keys come from query_data's dataset-listing mode, for the SAME country. verdict is one of "SUPPORT" (a real, hand-vetted registered pair with no open caveats -- may be treated as a confirmed relationship), "QUALIFY" (hand-vetted, but the evidence carries real caveats -- e.g. no robustness check for outliers, or an unverified geography-level join; read uncertainty and reasons before presenting it as confirmed), "REJECT" (a real structural impossibility or a human-vetted "no" -- the two stats share no geography level at all, or a reviewer rejected this exact pairing), or "INSUFFICIENT" (not registered, not ruled out either -- StatsMapped genuinely hasn't vetted this pair; never treat this as "probably comparable"). uncertainty names 4 separate dimensions (data_quality, comparability, statistical_strength, causal_strength) -- causal_strength is always "not_established", since no comparison here implies causation regardless of verdict. comparable (DEPRECATED, kept only for callers that haven't migrated) collapses verdict to the old 3-way yes/no/unknown -- "yes" for both SUPPORT and QUALIFY (both mean "hand-vetted", the old comparable meaning this field has always carried; the caveats a QUALIFY pair carries live in uncertainty/reasons, not in demoting comparable), "no" for REJECT, "unknown" for INSUFFICIENT. Prefer verdict directly when you need to distinguish a fully-confirmed SUPPORT from a caveated QUALIFY. Read reasons before presenting any answer other than "SUPPORT" as unqualified.

4. None of the above given: lists every registered cross-dataset comparison pair for one country -- e.g. "median sale price vs new dwelling completions per 1,000 residents". A small, hand-curated set, not an arbitrary-pair engine: pass one of the returned pair_key values to mode 2 for the real correlation and axis detail.

   level is only meaningful together with stat_key (mode 1); giving it without stat_key raises rather than silently dropping it and falling through to mode 4's unrelated pair listing.