This section details on the original issue you should resolve

<issue_title>rankList uq</issue_title>
<issue_description>
Goal

Implement SelectionUQ in py3plex to quantify uncertainty over discrete query outputs like:

top_k(...)

where(...) filters that yield a node/edge set

any query that returns a selected subset of items (nodes/edges)

SelectionUQ must answer:

“What is the probability item u appears in the result set?”

“How stable is the top-k ranking?”

“Which items are borderline/unstable?”

“How sensitive is the selection size / threshold?”

This must integrate with:

DSL v2 .uq(...)

QueryResult columns + meta

provenance

existing resampling strategies / noise models

Scope (strict)

Focus only on SelectionUQ (sets and rankings)

Do not rework existing numeric StatSeries UQ beyond minimal reuse

Do not add new markdown docs files

Update AGENTS.md + relevant .rst only if strictly needed

Must support both nodes and edges, including grouped results (per_layer, per_layer_pair) if present

Core Concept

Selection outputs are decisions, not scalar values. UQ must quantify:

1. Inclusion probability: Pr(item ∈ result)

2. Rank uncertainty (when order_by / top_k used):

E[rank], rank CI, Pr(rank ≤ k)

1. Set stability:

Jaccard similarity distribution vs reference (consensus)

expected overlap of top-k across runs

1. Borderline detection:

items with inclusion prob near 0.5

items with wide rank intervals

Architecture

1. UQPlan (reuse/extend existing)

SelectionUQ must compile down to the same UQPlan abstraction:

base_callable(net, params) -> SelectionOutput

strategy: SEED | PERTURBATION | BOOTSTRAP | JACKKNIFE

noise_model (optional)

n_samples, seed

reducers: SelectionReducers

storage_mode: "none" | "samples" | "sketch"

backend: "python" | "jax" (jax optional, not required)

1. NoiseModel (formalize selection perturbations)

Implement/reuse a NoiseModel interface (same as PartitionUQ prompt), but ensure SelectionUQ supports:

Required NoiseModels

None (seed-only)

EdgeDrop(p)

WeightNoise(dist="lognormal", sigma)

NodeDrop(p)

LayerDrop(p | mask)

TemporalWindowBootstrap(...) (if temporal)

NoiseModel must be:

serializable

recorded in provenance

applied before executing the query

1. Canonical SelectionUQ Result Type

Create a SelectionUQ class (distinct from StatSeries).

Must store (canonical)

n_samples

items_universe (IDs actually seen across samples; keep bounded)

samples_seen (effective)

inclusion probabilities:

present_prob[item]

size distribution summary:

mean/var/quantiles of |result|

stability metrics:

Jaccard distribution vs consensus selection

top-k overlap distribution (if ranking available)

ranking summaries (if ranking exists):

rank_mean[item], rank_std[item], rank_ci[item]

p_in_topk[item] = Pr(rank ≤ k)

Optional (storage dependent)

store raw selections per sample (only if store="samples")

store raw ranks per sample (only if store="samples")

Must implement

.summary() → small human-readable dict/table

.to_pandas(expand=True) → tidy table with probs/ranks

.to_dict() → serializable form for QueryResult export

1. SelectionOutput (internal unified output representation)

Define a small internal structure returned by base_callable so reducers are generic:

SelectionOutput(
items: list[ItemID], # selected items
scores: dict[ItemID, float]|None, # optional score if ranked
ranks: dict[ItemID, int]|None, # optional exact ranks if available
k: int|None, # top_k parameter if relevant
target: "nodes"|"edges",
group_key: tuple|None # for per_layer/per_layer_pair grouping
)

Rules:

If .top_k(k, ...) exists, ranks must be defined for at least returned items.

If only filtering (no ordering), then scores/ranks may be None.

1. Reducers (online; memory-safe)

Implement reducers that update per sample without storing everything.

Mandatory reducers

1. InclusionReducer

maintains count occurrences of each item across samples

output: present_prob

1. SizeReducer

online mean/var + quantiles of set size

output: size stats

1. StabilityReducer

compute Jaccard similarity vs a running reference selection

needs an evolving “consensus selection” (see below)

output: distribution summary (mean/std/quantiles)

Conditional reducers (only when ranking exists)

1. RankReducer

maintain online mean/var of rank per item

maintain p_in_topk for configured k

note: ranks for items not present in a sample should be treated carefully:

option A (default): ranks only defined when present; compute conditional rank stats

option B (also store): treat missing as rank > K_max (requires convention)

implement A first, but also compute p_in_topk directly from presence within top-k

1. TopKOverlapReducer

track overlap between top-k sets across samples

output: expected overlap, distribution summary

Reducer interface

All reducers implement:

...