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

core/database.py

@@ -0,0 +1,62 @@
+"""SQLite database connection and initialization.
+
+Uses stdlib sqlite3 — no ORM.  Every study gets its own .db file under
+data/studies/<study_id>/study.db.
+"""
+
+import os
+import sqlite3
+from pathlib import Path
+
+import sqlite3
+
+from core.models import SCHEMA_SQL, MIGRATIONS_SQL
+
+DATA_ROOT = Path("data/studies")
+
+
+def study_dir(study_id: str) -> Path:
+    return DATA_ROOT / study_id
+
+
+def get_connection(study_id: str) -> sqlite3.Connection:
+    """Return a connection to the study's database, creating dirs if needed."""
+    d = study_dir(study_id)
+    d.mkdir(parents=True, exist_ok=True)
+    db_path = d / "study.db"
+    conn = sqlite3.connect(str(db_path))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+    migrate_db(conn)
+    return conn
+
+
+def init_db(conn: sqlite3.Connection) -> None:
+    """Run CREATE TABLE IF NOT EXISTS for all tables."""
+    conn.executescript(SCHEMA_SQL)
+    conn.commit()
+
+
+def migrate_db(conn: sqlite3.Connection) -> None:
+    """Apply migrations for schema additions (new columns, new tables).
+    
+    Safe to call on any version — catches "duplicate column" errors.
+    Only runs if the target table already exists (skip on fresh DB before init_db).
+    """
+    existing = conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='analysis_results'"
+    ).fetchone()
+    if not existing:
+        return
+    for stmt in MIGRATIONS_SQL.split(";"):
+        stmt = stmt.strip()
+        if not stmt:
+            continue
+        try:
+            conn.execute(stmt)
+        except sqlite3.OperationalError as e:
+            if "duplicate column name" in str(e).lower():
+                continue
+            raise
+    conn.commit()

core/ingestion/csv_loader.py

@@ -0,0 +1,191 @@
+"""Load CSV/Excel into a dynamic per-study raw data table."""
+
+import json
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+from core.database import DATA_ROOT, get_connection, init_db
+
+
+def _sanitize_col(name: str) -> str:
+    """Make a column name SQL-safe."""
+    return "".join(c if c.isalnum() or c == "_" else "_" for c in name).strip("_") or "col"
+
+
+def _check_reingest(study_id: str) -> None:
+    """Check if study already has ingested data. Raises SystemExit if so."""
+    conn = get_connection(study_id)
+    init_db(conn)
+
+    # Check if raw_ table exists and has rows
+    raw = f"raw_{study_id}"
+    cur = conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+        (raw,),
+    )
+    if cur.fetchone() is None:
+        conn.close()
+        return  # no raw table → clean
+
+    cur = conn.execute(f"SELECT COUNT(*) AS cnt FROM {raw}")
+    row_count = cur.fetchone()["cnt"]
+
+    cur = conn.execute(
+        "SELECT COUNT(*) AS cnt FROM variables WHERE study_id=?",
+        (study_id,),
+    )
+    var_count = cur.fetchone()["cnt"]
+
+    # Check for locked plan files on disk
+    locked_plans = list(DATA_ROOT.glob(f"{study_id}/study_plan.v*.locked.json"))
+    conn.close()
+
+    if row_count > 0 or var_count > 0 or locked_plans:
+        parts = []
+        if row_count > 0:
+            parts.append(f"{row_count} row(s) in raw table")
+        if var_count > 0:
+            parts.append(f"{var_count} classified variable(s)")
+        if locked_plans:
+            parts.append(f"{len(locked_plans)} locked plan(s)")
+        msg = (
+            f"Study '{study_id}' already has ingested data ({'; '.join(parts)}). "
+            f"Re-ingesting would invalidate existing variables/plan/results. "
+            f"Use 'new-study' to start fresh, or pass --force-reingest if "
+            f"this is intentional (clears all downstream state)."
+        )
+        print(msg, file=sys.stderr)
+        sys.exit(1)
+
+
+def _cascade_clear(study_id: str) -> None:
+    """Drop downstream state so re-ingest can proceed cleanly."""
+    conn = get_connection(study_id)
+    init_db(conn)
+
+    masked = f"raw_masked_{study_id}"
+    conn.execute(f"DROP TABLE IF EXISTS {masked}")
+    # M1 fix: delete child table before parent to avoid FK violation
+    conn.execute(
+        "DELETE FROM analysis_covariate_results WHERE result_id IN "
+        "(SELECT id FROM analysis_results WHERE study_id=?)",
+        (study_id,),
+    )
+    conn.execute("DELETE FROM analysis_results WHERE study_id=?", (study_id,))
+    conn.execute("DELETE FROM variables WHERE study_id=?", (study_id,))
+
+    locked_plans = list(DATA_ROOT.glob(f"{study_id}/study_plan.v*.locked.json"))
+    for p in locked_plans:
+        p.unlink()
+
+    conn.commit()
+    conn.close()
+
+
+def load_file(study_id: str, filepath: str, na_values: list[str] | None = None,
+              force: bool = False) -> list[str]:
+    """Load a CSV (or Excel) file into the study's database.
+
+    Creates a dynamic table named `raw_<study_id>` with one column per CSV column
+    (all TEXT).  Returns the list of column names found.
+
+    Parameters
+    ----------
+    study_id : str
+    filepath : str
+        Path to the CSV or Excel file.
+    na_values : list[str], optional
+        Additional strings to treat as NA/NaN during CSV parsing
+        (e.g. ``["unknown", "missing"]``).  Added on top of pandas' defaults.
+    force : bool
+        If True, clear downstream state before re-ingesting.
+    """
+    if not force:
+        _check_reingest(study_id)
+
+    path = Path(filepath)
+    if path.suffix in (".xls", ".xlsx"):
+        df = pd.read_excel(str(path))
+    else:
+        kwargs = {"keep_default_na": True}
+        if na_values:
+            kwargs["na_values"] = na_values
+        df = pd.read_csv(str(path), **kwargs)
+
+    conn = get_connection(study_id)
+    init_db(conn)
+
+    if force:
+        _cascade_clear(study_id)
+
+    # Strip leading/trailing whitespace from string columns
+    str_cols = df.select_dtypes(include="object").columns
+    for c in str_cols:
+        df[c] = df[c].apply(lambda v: v.strip() if isinstance(v, str) else v)
+    # Also convert whitespace-only strings to None so they register as missing
+    df = df.replace(r"^\s*$", pd.NA, regex=True)
+
+    # ── Duplicate patient_id detection ─────────────────────────────────
+    pid_raw = next((c for c in df.columns if c.lower() in ("patient_id", "patientid", "id", "subject_id")), None)
+    if pid_raw:
+        pid_col = _sanitize_col(pid_raw)
+        dupe_counts = df[pid_raw].value_counts()
+        dupes = dupe_counts[dupe_counts > 1]
+        if not dupes.empty:
+            dupe_list = ", ".join(f"'{pid}' ({n}x)" for pid, n in dupes.items())
+            print(f"Warning: duplicate patient identifiers found — {dupe_list}. "
+                  f"These rows will be included in the analysis; "
+                  f"verify they are genuine repeat records.",
+                  file=__import__("sys").stderr)
+
+    col_names = [_sanitize_col(c) for c in df.columns]
+    col_defs = ", ".join(f'"{c}" TEXT' for c in col_names)
+    table_name = f"raw_{study_id}"
+
+    conn.execute(f"DROP TABLE IF EXISTS {table_name}")
+    conn.execute(f'CREATE TABLE {table_name} ("row_id" INTEGER PRIMARY KEY, {col_defs})')
+
+    placeholders = ", ".join("?" for _ in col_names)
+    col_list = ", ".join(f'"{c}"' for c in col_names)
+
+    for _, row in df.iterrows():
+        vals = tuple(None if pd.isna(v) else str(v) for v in row)
+        conn.execute(f"INSERT INTO {table_name} ({col_list}) VALUES ({placeholders})", vals)
+
+    conn.commit()
+    conn.close()
+    return col_names
+
+
+def find_duplicate_patient_ids(study_id: str) -> list[tuple[str, int]]:
+    """Query the study's raw table for duplicate patient identifiers.
+
+    Returns a list of ``(patient_id, count)`` tuples for every duplicated
+    patient ID, ordered by count descending.  Returns an empty list when
+    there is no patient_id column or no duplicates exist.
+    """
+    from core.database import get_connection
+
+    conn = get_connection(study_id)
+    raw_table = f"raw_{study_id}"
+
+    # Probe column names for a patient-like column
+    cur = conn.execute(f"PRAGMA table_info({raw_table})")
+    col_names = [r["name"] for r in cur.fetchall()]
+    pid_col = next(
+        (c for c in col_names if c.lower() in ("patient_id", "patientid", "id", "subject_id")),
+        None,
+    )
+    if not pid_col:
+        conn.close()
+        return []
+
+    cur = conn.execute(
+        f'SELECT "{pid_col}" AS pid, COUNT(*) AS cnt FROM {raw_table} '
+        f'GROUP BY "{pid_col}" HAVING cnt > 1 ORDER BY cnt DESC'
+    )
+    dupes = [(r["pid"], r["cnt"]) for r in cur.fetchall()]
+    conn.close()
+    return dupes

core/ingestion/variable_classifier.py

@@ -0,0 +1,171 @@
+"""Help the user classify variables as baseline/outcome and data types."""
+
+from __future__ import annotations
+
+from core.database import get_connection
+
+
+_OUTCOME_KEYWORDS = frozenset({
+    "outcome", "response", "survival", "pfs", "os", "status", "event",
+    "death", "followup", "lab", "marker", "protein", "score", "level",
+    "change", "fold", "day",
+})
+
+
+def _infer_data_type(study_id: str, column: str) -> str | None:
+    """Infer data type by inspecting actual column values.
+
+    Returns ``"continuous"``, ``"categorical"``, or ``None`` if the raw table
+    cannot be queried (heuristic-only fallback).
+    """
+    conn = get_connection(study_id)
+    try:
+        raw_table = f"raw_{study_id}"
+        cur = conn.execute(
+            f'SELECT DISTINCT "{column}" FROM {raw_table} WHERE "{column}" IS NOT NULL LIMIT 100'
+        )
+        values = [row[0] for row in cur.fetchall()]
+        if not values:
+            return None
+
+        # Attempt numeric parse
+        numeric = []
+        non_numeric = []
+        for v in values:
+            try:
+                float(v)
+                numeric.append(v)
+            except (ValueError, TypeError):
+                non_numeric.append(v)
+
+        # If any values are non-numeric strings, it's categorical
+        if non_numeric:
+            return "categorical"
+
+        # If all values are numeric, check distinct count
+        n_distinct = len(numeric)
+        if n_distinct > 5:
+            return "continuous"
+        return "categorical"
+    except Exception:
+        return None
+    finally:
+        conn.close()
+
+
+def _has_low_cardinality_text_values(study_id: str, column: str) -> bool | None:
+    """Check if a column's values are non-numeric text with few distinct values.
+
+    Returns True for columns like ``high_risk_cytogenetics`` (yes/no),
+    False for columns with >5 distinct non-numeric values,
+    None when the table can't be queried.
+    """
+    conn = get_connection(study_id)
+    try:
+        raw_table = f"raw_{study_id}"
+        cur = conn.execute(
+            f'SELECT DISTINCT "{column}" FROM {raw_table} WHERE "{column}" IS NOT NULL LIMIT 100'
+        )
+        values = [row[0] for row in cur.fetchall()]
+        if not values:
+            return None
+
+        # Check if any value is non-numeric
+        numeric_count = 0
+        for v in values:
+            try:
+                float(v)
+                numeric_count += 1
+            except (ValueError, TypeError):
+                pass
+
+        # If values are numeric, no opinion
+        if numeric_count == len(values):
+            return None
+
+        # Text values with ≤5 distinct options → likely baseline/demographic
+        return len(values) <= 5
+    except Exception:
+        return None
+    finally:
+        conn.close()
+
+
+def classify_variables_interactive(study_id: str, columns: list[str]) -> list[dict]:
+    """CLI-guided variable classification.
+
+    Uses heuristic name patterns AND actual data inspection.
+    Unrecognized column names get role="unclassified" to force explicit
+    resolution before planning.
+    """
+    results = []
+    for col in columns:
+        col_lower = col.lower()
+        tokens = set(col_lower.replace("-", "_").split("_"))
+
+        # ── Role (baseline / outcome / unclassified) ────────────────────
+        if tokens & _OUTCOME_KEYWORDS or any(
+            kw in col_lower for kw in ("outcome", "response", "survival",
+                                       "pfs", "os", "status", "event", "death",
+                                       "followup", "lab", "protein", "marker",
+                                       "score", "level", "change", "fold")
+        ):
+            default_role = "outcome"
+        elif tokens & {"id", "name", "patient", "identifier"}:
+            continue  # skip identifier columns
+        elif tokens & {"age", "bmi", "weight", "height", "creatinine",
+                        "count", "number", "value", "line", "lines", "prior",
+                        "sex", "gender", "stage", "site", "location",
+                        "center", "cohort", "group", "arm", "ecog"}:
+            default_role = "baseline"
+        else:
+            # If the column has low-cardinality text values (yes/no, mild/mod/severe),
+            # it's almost certainly baseline even if the name is unfamiliar.
+            is_low_card_text = _has_low_cardinality_text_values(study_id, col)
+            if is_low_card_text is True:
+                default_role = "baseline"
+            else:
+                # Unknown keyword pattern — flag for explicit user resolution
+                default_role = "unclassified"
+
+        # ── Data type (from actual values if possible) ──────────────────
+        # Start with a name-based guess
+        if any(kw in col_lower for kw in ("time", "days", "months", "duration", "follow_up", "fu")):
+            name_based_dtype = "time_to_event"
+        elif tokens & {"age", "bmi", "weight", "height", "value", "count",
+                       "number", "creatinine", "line", "lines", "prior"}:
+            name_based_dtype = "continuous"
+        else:
+            name_based_dtype = "categorical"
+
+        # Use data inspection to *refine* — only upgrade categorical→continuous,
+        # never override a known name-based type like time_to_event.
+        inferred = _infer_data_type(study_id, col)
+        if name_based_dtype == "categorical" and inferred == "continuous":
+            default_dtype = "continuous"
+        elif name_based_dtype == "categorical" and inferred == "categorical":
+            default_dtype = "categorical"
+        else:
+            default_dtype = name_based_dtype
+
+        results.append({"column": col, "role": default_role, "data_type": default_dtype})
+    return results
+
+
+def _classify_batch(study_id: str, variables: list[dict]) -> None:
+    """Write classified variables to the database.
+
+    Each dict: {column, role, data_type}
+    """
+    conn = get_connection(study_id)
+    for v in variables:
+        is_outcome = 1 if v["role"] == "outcome" else 0
+        conn.execute(
+            """INSERT INTO variables (study_id, column_name, role, data_type, is_masked)
+               VALUES (?, ?, ?, ?, ?)
+               ON CONFLICT(study_id, column_name) DO UPDATE SET
+                 role=excluded.role, data_type=excluded.data_type, is_masked=excluded.is_masked""",
+            (study_id, v["column"], v["role"], v["data_type"], is_outcome),
+        )
+    conn.commit()
+    conn.close()

core/masking/gate.py

@@ -0,0 +1,128 @@
+"""The Outcome-Masking Gate.
+
+Enforces outcome masking at the physical storage level.
+
+When variables are classified as outcomes, their values are moved from the
+main raw_{study_id} table into a shadow raw_masked_{study_id} table and
+replaced with NULLs.  This catches EVERY access path — sqlite3 CLI, raw
+Python sqlite3 module, any process that touches the database file.  The only
+way to recover the values is unmask(), which copies them back and transitions
+the study to the unmasked state permanently.
+
+State machine:
+  0 (pre-lock)     → outcome columns are NULL in the main table
+  1 (locked)       → outcome columns still NULL
+  2 (unmasked)     → outcome values restored, irreversible
+"""
+
+from __future__ import annotations
+import sqlite3
+from datetime import datetime, timezone
+from typing import Optional
+from core.database import get_connection, init_db
+
+
+class MaskedDataError(Exception):
+    """Raised when outcome data is accessed while the study is still masked."""
+
+
+def _get_study_state(conn: sqlite3.Connection, study_id: str) -> int:
+    cur = conn.execute("SELECT is_locked FROM studies WHERE id=?", (study_id,))
+    row = cur.fetchone()
+    return row["is_locked"] if row else 0
+
+
+def seal_outcomes(study_id: str) -> None:
+    """Move outcome column values into the masked shadow table, NULL them in main.
+
+    Called AFTER variable classification.  This is the physical enforcement:
+    outcome values simply do not exist in the main table until unmask.
+    """
+    conn = get_connection(study_id)
+    init_db(conn)
+
+    # Get outcome column names
+    cur = conn.execute(
+        "SELECT column_name FROM variables WHERE study_id=? AND role='outcome'",
+        (study_id,),
+    )
+    outcome_cols = [row["column_name"] for row in cur.fetchall()]
+    if not outcome_cols:
+        conn.close()
+        return
+
+    raw = f"raw_{study_id}"
+    masked = f"raw_masked_{study_id}"
+
+    # Create the shadow table with same columns + row_id link
+    col_defs = ", ".join(f'"{c}" TEXT' for c in outcome_cols)
+    conn.execute(f"""
+        CREATE TABLE IF NOT EXISTS {masked} (
+            "row_id" INTEGER PRIMARY KEY REFERENCES {raw}(row_id),
+            {col_defs}
+        )
+    """)
+
+    # Copy outcome values from raw to masked
+    col_list = ", ".join(f'"{c}"' for c in outcome_cols)
+    conn.execute(f"DELETE FROM {masked}")
+    conn.execute(f"""
+        INSERT INTO {masked} (row_id, {col_list})
+        SELECT row_id, {col_list} FROM {raw}
+    """)
+    conn.commit()
+
+    # NULL out outcome columns in the main raw table
+    for col in outcome_cols:
+        conn.execute(f'UPDATE {raw} SET "{col}" = NULL')
+
+    conn.commit()
+    conn.close()
+
+
+def unmask_study(study_id: str) -> None:
+    """Copy outcome values back from shadow table, transition to unmasked.
+
+    Irreversible — once called, outcome columns become permanently visible.
+    """
+    conn = get_connection(study_id)
+    init_db(conn)
+
+    cur = conn.execute(
+        "SELECT column_name FROM variables WHERE study_id=? AND role='outcome'",
+        (study_id,),
+    )
+    outcome_cols = [row["column_name"] for row in cur.fetchall()]
+    if not outcome_cols:
+        conn.close()
+        return
+
+    raw = f"raw_{study_id}"
+    masked = f"raw_masked_{study_id}"
+
+    for col in outcome_cols:
+        conn.execute(f"""
+            UPDATE {raw} SET "{col}" = (
+                SELECT "{col}" FROM {masked} WHERE {masked}.row_id = {raw}.row_id
+            )
+        """)
+
+    conn.execute("UPDATE studies SET is_locked=2, unmasked_at=? WHERE id=?", (datetime.now(timezone.utc).isoformat(), study_id))
+    conn.commit()
+    conn.close()
+
+
+def lock_study(study_id: str) -> None:
+    """Transition to locked state."""
+    conn = get_connection(study_id)
+    init_db(conn)
+    conn.execute("UPDATE studies SET is_locked=1 WHERE id=?", (study_id,))
+    conn.commit()
+    conn.close()
+
+
+def is_masked(study_id: str) -> bool:
+    conn = get_connection(study_id)
+    state = _get_study_state(conn, study_id)
+    conn.close()
+    return state < 2

core/models.py

@@ -0,0 +1,138 @@
+"""Data model dataclasses and SQL schema for the research tool."""
+
+from __future__ import annotations
+import json
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from typing import Optional
+
+# ── SQL schema ──────────────────────────────────────────────────────────────
+
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS studies (
+    id          TEXT PRIMARY KEY,
+    name        TEXT NOT NULL,
+    created_at  TEXT NOT NULL,       -- ISO-8601
+    study_type  TEXT,                -- cohort | case_control | cross_sectional
+    is_locked   INTEGER NOT NULL DEFAULT 0,  -- 0 = pre-lock, 1 = locked, 2 = unmasked
+    unmasked_at TEXT,                -- ISO-8601 timestamp of unmask event
+    data_dir    TEXT NOT NULL,
+    unmask_audit_json TEXT           -- JSON array of override events
+);
+
+CREATE TABLE IF NOT EXISTS variables (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    study_id    TEXT NOT NULL REFERENCES studies(id),
+    column_name TEXT NOT NULL,
+    role        TEXT NOT NULL,       -- baseline | outcome
+    data_type   TEXT NOT NULL,       -- categorical | continuous | time_to_event
+    is_masked   INTEGER NOT NULL DEFAULT 0,
+    UNIQUE(study_id, column_name)
+);
+
+CREATE TABLE IF NOT EXISTS raw_data (
+    row_id    INTEGER PRIMARY KEY AUTOINCREMENT,
+    study_id  TEXT NOT NULL REFERENCES studies(id),
+    json_row  TEXT NOT NULL          -- full row as JSON for flexibility
+);
+
+CREATE TABLE IF NOT EXISTS analysis_results (
+    id                INTEGER PRIMARY KEY AUTOINCREMENT,
+    study_id          TEXT NOT NULL REFERENCES studies(id),
+    study_plan_version INTEGER,
+    variable_ids_used TEXT,          -- JSON list
+    test_name         TEXT,
+    statistic         REAL,
+    p_value           REAL,
+    adjusted_p_value  REAL,
+    ci_lower          REAL,
+    ci_upper          REAL,
+    effect_size_json  TEXT,          -- JSON: {"metric": "Cramér's V", "value": 0.32}
+    sample_counts_json TEXT,         -- JSON: {"n_total": 21, "n_analyzed": 21, "n_excluded": 0}
+    status_json       TEXT,          -- JSON: {"status": "completed", "reason": "..."}
+    is_pre_registered INTEGER NOT NULL DEFAULT 1,
+    provenance_json   TEXT,          -- JSON blob
+    computed_at       TEXT NOT NULL,
+    superseded_previous_result_id INTEGER DEFAULT NULL,
+    lr_test_p         REAL,
+    concordance_index REAL,
+    ph_diagnostics_json TEXT
+);
+
+CREATE TABLE IF NOT EXISTS analysis_covariate_results (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    result_id   INTEGER NOT NULL REFERENCES analysis_results(id),
+    covariate   TEXT NOT NULL,
+    hr          REAL,
+    ci_lower    REAL,
+    ci_upper    REAL,
+    wald_p      REAL,
+    coef        REAL,
+    se          REAL,
+    z           REAL,
+    reference_level TEXT,
+    tested_level TEXT
+);
+"""
+
+MIGRATIONS_SQL = """
+ALTER TABLE analysis_results ADD COLUMN lr_test_p REAL;
+ALTER TABLE analysis_results ADD COLUMN concordance_index REAL;
+ALTER TABLE analysis_results ADD COLUMN ph_diagnostics_json TEXT;
+
+CREATE TABLE IF NOT EXISTS analysis_covariate_results (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    result_id   INTEGER NOT NULL REFERENCES analysis_results(id),
+    covariate   TEXT NOT NULL,
+    hr          REAL,
+    ci_lower    REAL,
+    ci_upper    REAL,
+    wald_p      REAL,
+    coef        REAL,
+    se          REAL,
+    z           REAL,
+    reference_level TEXT,
+    tested_level TEXT
+);
+ALTER TABLE analysis_covariate_results ADD COLUMN reference_level TEXT;
+ALTER TABLE analysis_covariate_results ADD COLUMN tested_level TEXT;
+ALTER TABLE studies ADD COLUMN unmask_audit_json TEXT;
+"""
+
+# ── Dataclasses ─────────────────────────────────────────────────────────────
+
+
+@dataclass
+class Study:
+    id: str
+    name: str
+    created_at: str  # ISO-8601
+    study_type: Optional[str] = None
+    is_locked: int = 0
+    data_dir: str = ""
+
+
+@dataclass
+class Variable:
+    id: int
+    study_id: str
+    column_name: str
+    role: str  # "baseline" | "outcome"
+    data_type: str  # "categorical" | "continuous" | "time_to_event"
+    is_masked: bool = True
+
+
+@dataclass
+class AnalysisResult:
+    id: int
+    study_id: str
+    study_plan_version: int
+    variable_ids_used: list[int]
+    test_name: str
+    statistic: Optional[float] = None
+    p_value: Optional[float] = None
+    adjusted_p_value: Optional[float] = None
+    confidence_interval: tuple[Optional[float], Optional[float]] = (None, None)
+    is_pre_registered: bool = True
+    provenance: Optional[dict] = None
+    computed_at: Optional[str] = None