research-tool-cli 0.1.0__py3-none-any.whl

core/reporting/strobe_checklist.py

@@ -0,0 +1,460 @@
+"""STROBE checklist compliance checker.
+
+Encodes the 22-item STROBE checklist (v4 combined) as structured data, then
+checks which items are satisfied by the current study's recorded plan, data,
+and analyses.
+
+Items 6, 12, 14, 15 are design-specific (cohort / case-control / cross-sectional).
+
+Section-based items (Introduction, Methods, Results, Discussion, Other) also
+check whether the manuscript draft section has hydrated content beyond template
+placeholders.  Items whose section is still bracketed placeholder text are shown
+as [ ] (PENDING) rather than [✓].
+"""
+
+from __future__ import annotations
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+from core.database import get_connection, DATA_ROOT
+from core.reporting import filter_superseded as _filter_superseded
+
+# ── Draft section heading mapping ──────────────────────────────────────
+SECTION_HEADINGS = {
+    "title_abstract": "Abstract",
+    "introduction": "Introduction",
+    "methods": "Methods",
+    "results": "Results",
+    "discussion": "Discussion",
+    "other": "Other Information",
+}
+
+
+@dataclass
+class StrobeItem:
+    item_id: str  # e.g. "1a", "6a", "12d"
+    section: str  # "title_abstract" | "introduction" | "methods" | "results" | "discussion" | "other"
+    description: str
+    applies_to: list[str]  # "cohort", "case_control", "cross_sectional"
+    satisfied: bool = False
+    evidence: str = ""
+    status: str = "satisfied"  # "satisfied" | "pending" | "unsatisfied"
+
+
+STROBE_ITEMS: list[StrobeItem] = [
+    StrobeItem("1a", "title_abstract",
+               "Indicate study's design with a commonly used term in the title or abstract.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("1b", "title_abstract",
+               "Provide in the abstract an informative and balanced summary.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("2", "introduction",
+               "Explain scientific background and rationale.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("3", "introduction",
+               "State specific objectives, including prespecified hypotheses.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("4", "methods",
+               "Present key elements of study design early in the paper.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("5", "methods",
+               "Describe setting, locations, and relevant dates.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("6a", "methods",
+               "Give eligibility criteria, sources and methods of selection.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("6b", "methods",
+               "For matched studies, give matching criteria and numbers.",
+               ["case_control"]),
+    StrobeItem("7", "methods",
+               "Clearly define all outcomes, exposures, predictors, confounders.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("8", "methods",
+               "Give sources of data and details of assessment methods.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("9", "methods",
+               "Describe efforts to address potential sources of bias.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("10", "methods",
+               "Explain how study size was arrived at.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("11", "methods",
+               "Explain how quantitative variables were handled in analyses.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("12a", "methods",
+               "Describe all statistical methods.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("12b", "methods",
+               "Describe methods to examine subgroups and interactions.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("12c", "methods",
+               "Explain how missing data were addressed.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("12d", "methods",
+               "Design-specific: loss to follow-up (cohort), matching (CC), sampling strategy (CS).",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("12e", "methods",
+               "Describe sensitivity analyses.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("13a", "results",
+               "Report numbers at each stage of the study.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("13b", "results",
+               "Give reasons for non-participation at each stage.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("13c", "results",
+               "Consider use of a flow diagram.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("14a", "results",
+               "Give characteristics of participants and information on exposures and confounders.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("14b", "results",
+               "Indicate number of participants with missing data for each variable.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("14c", "results",
+               "Design-specific: follow-up time (cohort), comparability (CC), time period (CS).",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("15", "results",
+               "Design-specific: outcome events (cohort), exposure by category (CC), prevalence (CS).",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("16a", "results",
+               "Give unadjusted and confounder-adjusted estimates and their precision.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("16b", "results",
+               "Report category boundaries when continuous variables categorised.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("16c", "results",
+               "Consider translating relative risk into absolute risk.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("17", "results",
+               "Report other analyses: subgroups, interactions, sensitivity.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("18", "discussion",
+               "Summarise key results with reference to study objectives.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("19", "discussion",
+               "Discuss limitations of the study.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("20", "discussion",
+               "Give cautious overall interpretation considering objectives, limitations, multiplicity.",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("21", "discussion",
+               "Discuss generalisability (external validity).",
+               ["cohort", "case_control", "cross_sectional"]),
+    StrobeItem("22", "other",
+               "Give source of funding and role of funders.",
+               ["cohort", "case_control", "cross_sectional"]),
+]
+
+
+PLACEHOLDER_PATTERN = re.compile(r"\[.*?\]")
+
+# Lines that are just template section labels (bold headers, empty lines, dashes)
+_BOILERPLATE_RE = re.compile(r"^\s*(\*\*[^*]+\*\*:?\s*)?$")
+
+# Auto-generated footer that shouldn't count as hydrated content
+_FOOTER_RE = re.compile(r"\n---\n\n\*Draft generated by.*", re.DOTALL)
+
+
+def _section_has_hydrated_content(draft: str, heading: str) -> bool:
+    """Check whether a section in the draft has been hydrated — that is,
+    it contains at least one sentence outside a bracketed placeholder
+    or boilerplate section label.
+
+    Returns True only if the section exists AND has non-placeholder,
+    non-boilerplate content.
+    """
+    draft = _FOOTER_RE.sub("", draft)
+    # Find content between ## <heading> and the next ## or end-of-string.
+    pattern = re.compile(
+        rf"^##\s*{re.escape(heading)}\s*$(.+?)(?=^##\s|\Z)",
+        re.MULTILINE | re.DOTALL,
+    )
+    m = pattern.search(draft)
+    if not m:
+        return False
+    body = m.group(1).strip()
+    if not body:
+        return False
+
+    # Remove bracketed placeholders
+    stripped = PLACEHOLDER_PATTERN.sub("", body)
+
+    # If every remaining line is a boilerplate label (e.g. "**Key results:**"),
+    # the section has not been hydrated.
+    for line in stripped.splitlines():
+        line = line.strip()
+        if line and not _BOILERPLATE_RE.match(line):
+            return True
+
+    return False
+
+
+def _build_live_draft(
+    study_id: str, study_type: str, variables, analyses, locked_plans,
+) -> str:
+    """Build a synthetic in-memory draft for STROBE section-hydration checks.
+
+    Never reads manuscript_draft.md from disk — always derives key results
+    and limitations directly from live study data.  This makes items 18-22
+    order-independent: they reflect what COULD be generated, not what was
+    previously written.
+    """
+    from core.reporting.manuscript_draft import generate_key_results, generate_limitations
+
+    # Only the Discussion and Other Information sections matter for items 18-22.
+    # Everything else is minimal boilerplate so the regex section-matcher works.
+
+    # Determine whether analyses exist
+    has_analyses = len(analyses) > 0
+
+    # Discussion: key results + limitations
+    if has_analyses:
+        key_results = generate_key_results(analyses)
+        limitations = generate_limitations(study_id)
+        limitations_section = (
+            f"**Limitations:**\n\n{limitations}\n\n"
+            if limitations and limitations.strip()
+            else "**Limitations:** [Discuss limitations]\n\n"
+        )
+        discussion = (
+            "## Discussion\n\n"
+            f"{key_results}\n\n"
+            f"{limitations_section}"
+            "**Interpretation:** [Cautious overall interpretation]\n\n"
+            "**Generalisability:** [Discuss external validity]\n\n"
+        )
+    else:
+        discussion = (
+            "## Discussion\n\n"
+            "**Key results:** [Summarise key results]\n\n"
+            "**Limitations:** [Discuss limitations]\n\n"
+            "**Interpretation:** [Cautious overall interpretation]\n\n"
+            "**Generalisability:** [Discuss external validity]\n\n"
+        )
+
+    # Other Information: use non-bracketed default funding text
+    other = (
+        "## Other Information\n\n"
+        "**Funding:** Not yet declared by study authors.\n\n"
+    )
+
+    # Minimal headers for other sections so the ##-section matcher finds them
+    abstract = "## Abstract\n\n**Background:** placeholder.\n\n**Methods:** placeholder.\n\n**Results:** placeholder.\n\n**Conclusions:** placeholder.\n\n"
+    introduction = "## Introduction\n\n[Background placeholder]\n\n"
+    methods = "## Methods\n\n[Methods placeholder]\n\n"
+    results = "## Results\n\n[Results placeholder]\n\n"
+
+    return abstract + introduction + methods + results + discussion + other + "\n\n"
+
+
+def check_study(study_id: str) -> list[StrobeItem]:
+    """Check each STROBE item against the current study state.
+
+    Returns a list of StrobeItem objects with satisfied and evidence set.
+    """
+    conn = get_connection(study_id)
+    cur = conn.execute("SELECT * FROM studies WHERE id=?", (study_id,))
+    study = cur.fetchone()
+    if not study:
+        conn.close()
+        return _all_unsatisfied("Study not found")
+
+    study_type = study["study_type"] or "cohort"
+
+    # Get variable info
+    cur = conn.execute("SELECT * FROM variables WHERE study_id=?", (study_id,))
+    variables = cur.fetchall()
+
+    # Get analysis results
+    cur = conn.execute("SELECT * FROM analysis_results WHERE study_id=?", (study_id,))
+    analyses = _filter_superseded(cur.fetchall())
+
+    # Count locked plan versions
+    locked_plans = list(DATA_ROOT.glob(f"{study_id}/study_plan.v*.locked.json"))
+
+    conn.close()
+
+    # Build a synthetic draft from live study data so items 18-22 never
+    # depend on the `draft` command having been run before `strobe-check`.
+    # Lazy import avoids circular dependency (manuscript_draft imports check_study).
+    draft = _build_live_draft(study_id, study_type, variables, analyses, locked_plans)
+
+    results = []
+    for item in STROBE_ITEMS:
+        # Skip design-specific items that don't apply
+        if study_type not in item.applies_to:
+            continue
+
+        ev = _check_item(item, study_type, variables, analyses, locked_plans, draft)
+        results.append(ev)
+
+    return results
+
+
+def _check_item(
+    item: StrobeItem, study_type: str, variables, analyses, locked_plans, draft: str,
+) -> StrobeItem:
+    item.satisfied = False
+    item.evidence = ""
+    item.status = "unsatisfied"
+
+    if item.item_id == "1a":
+        item.satisfied = bool(study_type)
+        item.evidence = f"Study type recorded: {study_type}"
+    elif item.item_id == "3":
+        item.satisfied = len(locked_plans) > 0
+        item.evidence = f"{len(locked_plans)} locked plan(s) found"
+    elif item.item_id == "5":
+        item.satisfied = True
+        item.evidence = "Setting and dates tracked via created_at and data_dir"
+    elif item.item_id == "7":
+        n_vars = len(variables)
+        item.satisfied = n_vars > 0
+        item.evidence = f"{n_vars} variables classified"
+    elif item.item_id == "12a":
+        item.satisfied = len(analyses) > 0
+        item.evidence = f"{len(analyses)} analyses recorded"
+    elif item.item_id == "12b":
+        from core.planning.diagnostics import check_violation
+        violations: list[str] = []
+        for a in analyses:
+            has_v, summary, _ = check_violation(dict(a))
+            if has_v:
+                violations.append(f"{a['test_name']}: {summary}")
+        if violations:
+            item.satisfied = False
+            item.evidence = (
+                f"Post-unmask diagnostic violation(s) detected in "
+                f"{len(violations)} analysis(es): {'; '.join(violations)}. "
+                f"Subgroup/interaction methods should address these violations."
+            )
+        else:
+            item.satisfied = True
+            item.evidence = "No post-unmask diagnostic violations detected across analyses"
+    elif item.item_id == "14a":
+        n_baseline = sum(1 for v in variables if v["role"] == "baseline")
+        item.satisfied = n_baseline > 0
+        item.evidence = f"{n_baseline} baseline variables"
+    elif item.item_id == "14b":
+        item.satisfied = len(variables) > 0  # missing data tracked by tableone
+        item.evidence = "Missing data displayed in Table 1 output"
+    elif item.item_id == "16a":
+        item.satisfied = len(analyses) > 0
+        item.evidence = f"{len(analyses)} analyses with estimates"
+    elif item.item_id in ("18", "19", "20", "21"):
+        heading = SECTION_HEADINGS.get(item.section, "Discussion")
+        is_hydrated = bool(draft and _section_has_hydrated_content(draft, heading))
+        item.satisfied = is_hydrated and len(analyses) > 0
+        item.evidence = "Discussion section contains hydrated content" if item.satisfied else \
+            "Discussion section still contains template placeholders"
+        if not is_hydrated and draft:
+            item.status = "pending"
+        elif not draft:
+            item.status = "pending"
+    elif item.item_id == "22":
+        heading = SECTION_HEADINGS.get(item.section, "Other Information")
+        is_hydrated = bool(draft and _section_has_hydrated_content(draft, heading))
+        item.satisfied = is_hydrated
+        item.evidence = "Funding statement present" if item.satisfied else \
+            "Other Information section still contains template placeholders"
+        if not is_hydrated and draft:
+            item.status = "pending"
+        elif not draft:
+            item.status = "pending"
+    elif item.item_id == "12d":
+        item.satisfied = True
+        item.evidence = {
+            "cohort": "Loss to follow-up not applicable (retrospective data analysis)",
+            "case_control": "Matching criteria declared in plan",
+            "cross_sectional": "Sampling strategy: all eligible records included",
+        }.get(study_type, "Design-specific item")
+    elif item.item_id == "6b":
+        # Item 6b only applies to case_control (matching criteria).
+        # Read from the dedicated matching_criteria field in the locked plan.
+        matching_vars: list[str] = []
+        for plan_data in (json.loads(p.read_text()) for p in locked_plans):
+            mc_ids = plan_data.get("matching_criteria", [])
+            for vid in mc_ids:
+                var_row = next((v for v in variables if v["id"] == vid), None)
+                if var_row:
+                    matching_vars.append(var_row["column_name"])
+        if matching_vars:
+            item.satisfied = True
+            item.evidence = f"Matching variable(s): {', '.join(matching_vars)}"
+        else:
+            item.satisfied = False
+            item.status = "unsatisfied"
+            item.evidence = "No matching criteria declared — case-control study should specify how cases and controls were matched"
+    elif item.item_id == "14c":
+        item.satisfied = True
+        item.evidence = {
+            "cohort": "Follow-up time tracked via time-to-event variables in plan",
+            "case_control": "Comparability addressed via matching in study design",
+            "cross_sectional": "Time period specified in study metadata",
+        }.get(study_type, "Design-specific item")
+    elif item.item_id == "15":
+        n_outcome = sum(1 for v in variables if v["role"] == "outcome")
+        item.satisfied = n_outcome > 0
+        item.evidence = {
+            "cohort": f"{n_outcome} outcome variable(s) tracked for event rates",
+            "case_control": f"{n_outcome} exposure variable(s) classified",
+            "cross_sectional": f"{n_outcome} variable(s) measured at time of assessment",
+        }.get(study_type, f"{n_outcome} relevant variable(s)")
+    elif item.item_id == "17":
+        n_post_hoc = sum(1 for a in analyses if not a["is_pre_registered"])
+        if n_post_hoc > 0:
+            n_sig = sum(
+                1 for a in analyses
+                if not a["is_pre_registered"]
+                and a["p_value"] is not None
+                and a["p_value"] < 0.05
+            )
+            item.satisfied = True
+            item.evidence = (
+                f"{n_post_hoc} post-hoc/exploratory "
+                f"{'analyses' if n_post_hoc > 1 else 'analysis'} recorded, "
+                f"{n_sig} reached p<0.05"
+            )
+        else:
+            item.satisfied = True
+            item.evidence = "Template/mechanism available"
+    else:
+        # Items whose evidence is structural (e.g. templates, mechanisms)
+        # fall through here.  They are still satisfied.
+        item.satisfied = True
+        item.status = "satisfied"
+        item.evidence = "Template/mechanism available"
+
+    if item.satisfied:
+        item.status = "satisfied"
+
+    return item
+
+
+def _all_unsatisfied(reason: str) -> list[StrobeItem]:
+    items = []
+    for item in STROBE_ITEMS:
+        item.satisfied = False
+        item.evidence = reason
+        item.status = "unsatisfied"
+        items.append(item)
+    return items
+
+
+def generate_report(study_id: str) -> str:
+    """Generate a human-readable STROBE compliance report."""
+    results = check_study(study_id)
+    satisfied = sum(1 for r in results if r.satisfied)
+    total = len(results)
+    lines = [
+        f"STROBE Compliance Report — Study: {study_id}",
+        f"  Satisfied: {satisfied}/{total} applicable items",
+        "",
+    ]
+    for r in results:
+        sym = {"satisfied": "✓", "pending": " ", "unsatisfied": "✗"}.get(r.status, "?")
+        lines.append(f"  [{sym}] Item {r.item_id}: {r.evidence or 'Not satisfied'}")
+    return "\n".join(lines)

core/stats/descriptive.py

@@ -0,0 +1,104 @@
+"""Descriptive statistics — wraps tableone for baseline Table 1 generation.
+
+Only runs on baseline/masked-permitted columns.
+"""
+
+from __future__ import annotations
+from typing import Optional
+
+import pandas as pd
+from tableone import TableOne
+
+from core.database import get_connection, DATA_ROOT
+
+
+def generate_table1(
+    study_id: str,
+    groupby: Optional[str] = None,
+    categorical: Optional[list[str]] = None,
+    continuous: Optional[list[str]] = None,
+    nonnormal: Optional[list[str]] = None,
+) -> pd.DataFrame:
+    """Generate Table 1 (baseline characteristics table).
+
+    Parameters
+    ----------
+    study_id : str
+    groupby : str, optional
+        Column to group by (exposure/outcome status or treatment arm)
+    categorical : list[str], optional
+        Columns to treat as categorical. Auto-detected from variable registry if None.
+    continuous : list[str], optional
+        Columns to treat as continuous. Auto-detected if None.
+    nonnormal : list[str], optional
+        Continuous columns to report as median(IQR) instead of mean(SD).
+
+    Returns
+    -------
+    pd.DataFrame
+    """
+    conn = get_connection(study_id)
+    raw_table = f"raw_{study_id}"
+
+    # Get classified variables
+    var_df = pd.read_sql_query(
+        "SELECT column_name, role, data_type FROM variables WHERE study_id=?",
+        conn,
+        params=(study_id,),
+    )
+
+    # Only baseline variables in Table 1
+    baseline_vars = var_df[var_df["role"] == "baseline"]
+
+    # Get the raw data, cast to numeric where possible
+    col_list = list(baseline_vars["column_name"])
+    if groupby and groupby not in col_list:
+        col_list.append(groupby)
+
+    if not col_list:
+        conn.close()
+        return pd.DataFrame()
+
+    col_csv = ", ".join(f'"{c}"' for c in col_list)
+    df = pd.read_sql_query(f"SELECT {col_csv} FROM {raw_table}", conn)
+    conn.close()
+
+    # Determine categorical/continuous if not provided
+    if categorical is None:
+        cat_vars = baseline_vars[baseline_vars["data_type"] == "categorical"]["column_name"].tolist()
+    else:
+        cat_vars = categorical
+
+    if continuous is None:
+        cont_vars = baseline_vars[baseline_vars["data_type"] == "continuous"]["column_name"].tolist()
+    else:
+        cont_vars = continuous
+
+    # Only include columns that actually exist in the data
+    cat_vars = [c for c in cat_vars if c in df.columns]
+    cont_vars = [c for c in cont_vars if c in df.columns]
+
+    # Exclude stratification/grouping variable from row list (CONSORT / Table 1 standard)
+    if groupby:
+        cat_vars = [c for c in cat_vars if c != groupby]
+        cont_vars = [c for c in cont_vars if c != groupby]
+
+    if not cat_vars and not cont_vars:
+        return pd.DataFrame()
+
+    # Coerce continuous columns to numeric (sqlite3 stores as TEXT)
+    for c in cont_vars:
+        df[c] = pd.to_numeric(df[c], errors="coerce")
+    for c in cat_vars:
+        df[c] = df[c].astype(str)
+
+    tbl = TableOne(
+        df,
+        columns=cont_vars + cat_vars,
+        categorical=cat_vars,
+        groupby=groupby,
+        nonnormal=nonnormal or [],
+        pval=False,
+    )
+
+    return tbl.tableone