forrtproject / forrtproject/flora-extractor

Empirical validation agenda for the technical report (tracking)

Open
#52 1 comment 0 reactions 0 assignees View on GitHub
documentation enhancement
Dominant language
Python
Stars
2
Forks
1
Avg merge
1d 6h
Merged PRs (30d)
4

Description

## What / Where

Tracking issue for the empirical validation the FLoRA **technical report** needs. Many thresholds and coverage assumptions across the pipeline are currently unvalidated (several are self-described as such in code comments and in `CLAUDE.md`). This issue collects the measurements to run.

## Why it matters

The report will make quantitative claims about recall, precision, and outcome balance. Right now those rest on hand-tuned thresholds and untested assumptions. Each item below is a place a number could be materially wrong.

## Agenda

**Stage 1 — recall**
- Run `search/sensitivity_check.py` to estimate keyword recall, **split by success vs. failure phrasing**.
- Test whether OpenAlex `.search` actually honors **quoted phrases** (if not, phrase precision assumptions are wrong).

**Stage 2 — false-rejection rate**
- Hand-label a sample of the never-reviewed **no-phrase bucket** (~2.17M rows) to estimate the false-rejection (recall-loss) rate. (Related: the Stage-2 second-pass issue.)

**Stage 3 — linking precision & thresholds**
- Per-`link_method` precision on a **gold sample**, plus threshold sensitivity sweeps for the values currently hard-coded and self-described as unvalidated:
- citation scoring cutoffs (4.0 / 2.0)
- same-author Jaccard floor (0.05)
- `doi_verify` Jaccards (`VERIFY_TITLE_JACCARD 0.5`, `RESOLVE_TITLE_JACCARD 0.7`, `TITLE_ONLY_JACCARD 0.6`, `TITLE_ONLY_GAP 1.5`)
- `find_all_candidates()` **empty-rate**: `shared/openalex_client.py:284–299` returns `[]` whenever there is no `openalex_id_r` or no indexed references — this bounds how many rows the rule-based linker can even attempt. Measure the empty-rate to bound rule-based linking coverage.

**Stage 3 — outcome**
- Outcome **gold sample** (~150–300 rows), stratified by decision path, including the bare-`"replicated"` → `success` keyword bucket (which is a low-signal shortcut worth auditing).
- **Abstract-only vs. full-text** outcome comparison — how often does full text change the coded outcome vs. abstract alone?

Found in the 2026-07-16 end-to-end pipeline review.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with CLAUDE.md and search/sensitivity_check.py, then inspect shared/openalex_client.py:284–299 and the listed threshold assumptions. Run the sensitivity check and design the gold-sample measurements across recall, linking, and outcome stages; done means the agenda has recorded measurements for the stated coverage, precision, threshold, and outcome questions.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
data, testing-qa
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.