Add per-effect focal-effect flag (is_focal / focal_role) for original–replication pairs

[LukasWallrich]

TL;DR

I wanted a version to select focal effects - i.e. pick one row per original-replication pair in a principled way - a few times now. I would suggest we add this to the store - but @LukasRoeseler let's discuss whether we add this to the database directly, or just provide it as an extra resource. Maybe keeping it separate is better as it is not double-coded and thus not up to FReD quality standards.

What this adds

Two files under cache/:

• focal_effect_flags.csv — one row per FReD effect (2164 rows, keyed to output/FReD.xlsx by effect_id), flagging whether each effect is the focal effect of its replication pair: the single effect the replication study actually targeted as its primary replication object.
• focal_effect_flags.md — documentation of the columns, the derivation rule, and the caveats.

Why

FReD's row unit is the effect (effect_id), but the scientific unit of a replication is the original↔replication pair (fred_id), which can carry many correlated within-study effects. Any per-pair analysis (replication-rate summaries, z-curves, one-observation-per-claim comparisons) needs to reduce each pair to the one effect the replication was actually about. This flag provides that, chosen on principle.

How the focal effect was determined

Per pair, cheapest evidence first (focal_source records which tier resolved each pair):

1. single_effect (702 pairs) — the pair has one effect; trivially focal.
2. abstract match (134) — semantic match of the coder's abstract-level replication finding to one candidate effect's original claim (LLM, gemini-flash-lite-latest, two-pass, spot-checked).
3. outcome_quote match (17) — same, using the finding-level quote when the abstract was too coarse.
4. replication-report reading (134) — where the abstract/quote could not disambiguate (bundle/project-level abstracts, whole-model aggregate verdicts, or a finding matching no candidate), the actual replication report was read to identify the targeted effect, with the report section/table/statistic cited as evidence.

When no single focal claim could be identified, the focal effect was **left empty ** — and the pair was routed to an explicit non-focal class.

Coverage

987 coded pairs → 957 resolved to a single focal effect. The rest are classified, not dropped:

class	pairs	meaning
focal (resolved)	957	one identified focal effect
constituent_set	23	aggregate replication of co-equal effects; no single focal (members flagged focal_role = constituent)
focal_in_sibling	3	FReD split one pair across fred_ids; the targeted effect lives in a sibling fred_id
target_absent	3	the targeted effect is not among FReD's candidate rows for the pair
not_applicable	1	association-matrix bundle (Soto/LOOPR) — focal concept doesn't apply

No pair remains needs_review. Effect-level coverage: is_focal = TRUE on exactly 957 rows (one per resolved pair); resolved 1781 / constituent_set 169 / target_absent 13 / focal_in_sibling 7 / not_applicable 60 / uncoded 134 effects.

Method notes

• Focal determination is finding-level: it uses the abstract-coded replication outcomes from the "Validating FReD replication success" sheet, which is double-coded — only validation == "validated - chosen" rows are authoritative.
• Verdicts were attached to pairs by replication identity, keyed on coalesce(DOI, URL) on both the original and replication sides, with preprint↔version-of-record equivalences (cache/confirmed_preprint_duplicates.csv) and RPP umbrella-vs-component DOIs, not on raw DOI alone.

FReD data-quality findings surfaced by this work

• fred_id fragmentation — one original↔replication pair is sometimes split across a base fred_id and _1-style siblings sharing identical doi_o + doi_r. Documented (focal_in_sibling); analyses must dedup on doi_o + doi_r, not fred_id.
• additional_studies94 claim_text mis-paste (fixed in source) — effects 323/324 carried the Study-1 manipulation-check text although their statistics are the focal reliance DV; corrected in the validation sheet on 2026-07-23 (see focal_effect_flags.md).
• Four missing effect rows added to the validation sheet (status "awaiting validation"): the curatescience15 depletion DV and three resciencex_01 teacher-credential effects — effects the replications targeted that FReD did not hold.

Provenance / reproducibility

Derived from the "Validating FReD replication success" abstract-coding sheet and the FReD effect table; full method, per-tier counts, spot-checks, and the complete list of non-focal pairs are in the accompanying validation report (available on request).