compare
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | ||
| country | No | ireland | |
| pair_key | No | ||
| stat_key | No | ||
| stat_key_a | No | ||
| stat_key_b | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |