medsci-skills 4.1.0

package/skills/meta-analysis/references/checklists/PROBAST.md

@@ -0,0 +1,75 @@
+# PROBAST Assessment Guide
+
+Prediction model Risk Of Bias ASsessment Tool.
+Reference: Wolff RF et al. Ann Intern Med 2019;170(1):51-58. PMID: 30596875.
+AI extension: PROBAST+AI (BMJ 2024).
+
+## Structure
+
+PROBAST assesses 4 domains, each for Risk of Bias AND Applicability.
+- **Signalling questions**: Yes / Probably yes / No / Probably no / No information
+- **Domain judgment**: Low / High / Unclear
+- **Overall judgment**: High if any domain is high; Low only if all domains are low
+
+## Domain 1: Participants
+
+### Signalling Questions (Risk of Bias)
+1. Were appropriate data sources used (e.g., cohort, RCT, nested case-control)?
+2. Were all inclusions and exclusions of participants appropriate?
+
+### Applicability
+- Do the participants and setting match the review question?
+
+## Domain 2: Predictors
+
+### Signalling Questions (Risk of Bias)
+1. Were predictors defined and assessed in a similar way for all participants?
+2. Were predictor assessments made without knowledge of outcome data?
+3. Are all predictors available at the time the model is intended to be used?
+
+### Applicability
+- Do the predictors, their assessment, and timing match the review question?
+
+## Domain 3: Outcome
+
+### Signalling Questions (Risk of Bias)
+1. Was the outcome determined appropriately?
+2. Was a pre-specified or standard outcome definition used?
+3. Were predictors excluded from the outcome definition?
+4. Was the outcome defined and determined in a similar way for all participants?
+5. Was the outcome determined without knowledge of predictor information?
+6. Was the time interval between predictor assessment and outcome appropriate?
+
+### Applicability
+- Does the outcome and its definition/timing match the review question?
+
+## Domain 4: Analysis
+
+### Signalling Questions (Risk of Bias)
+1. Were there a reasonable number of participants with the outcome?
+2. Were continuous and categorical predictors handled appropriately?
+3. Were all enrolled participants included in the analysis?
+4. Were participants with missing data handled appropriately?
+5. Was selection of predictors based on univariable analysis avoided?
+6. Were complexities in the data accounted for appropriately?
+7. Were relevant model performance measures evaluated appropriately?
+8. Were model overfitting and optimism in model performance accounted for?
+9. Do predictors and their assigned weights in the final model correspond to the reported multivariable analysis?
+
+### For Validation Studies (additional)
+- Were the model and its performance evaluated appropriately?
+
+## PROBAST+AI Extensions (2024)
+
+For AI/ML prediction models, additional considerations:
+- **Data**: Training/validation/test split, data leakage check
+- **Model**: Architecture transparency, hyperparameter tuning method
+- **Performance**: Discrimination (AUC), calibration, fairness across subgroups
+- **Reproducibility**: Code/data availability, external validation
+
+## When to Use
+
+- Diagnostic prediction models (e.g., AI classifiers for imaging findings)
+- Prognostic prediction models (e.g., risk scores, survival prediction)
+- Both development AND validation studies
+- Use PROBAST+AI when the model involves machine learning or deep learning

package/skills/meta-analysis/references/checklists/QUADAS2.md

@@ -0,0 +1,77 @@
+# QUADAS-2 Assessment Guide
+
+Quality Assessment of Diagnostic Accuracy Studies, version 2.
+Reference: Whiting PF et al. Ann Intern Med 2011;155(8):529-536.
+
+## Structure
+
+QUADAS-2 assesses 4 domains. Each domain has:
+- **Signalling questions**: answered Yes / No / Unclear
+- **Risk of bias judgment**: Low / High / Unclear
+- **Applicability concern** (domains 1-3 only): Low / High / Unclear
+
+## Domain 1: Patient Selection
+
+### Signalling Questions
+1. Was a consecutive or random sample of patients enrolled?
+2. Was a case-control design avoided?
+3. Did the study avoid inappropriate exclusions?
+
+### Risk of Bias
+- **Low**: Yes to all signalling questions
+- **High**: No to any signalling question
+- **Unclear**: Insufficient information
+
+### Applicability
+- Are there concerns that the included patients and setting do not match the review question?
+
+## Domain 2: Index Test
+
+### Signalling Questions
+1. Were the index test results interpreted without knowledge of the results of the reference standard?
+2. If a threshold was used, was it pre-specified?
+
+### Risk of Bias
+- **Low**: Yes to all signalling questions
+- **High**: No to any signalling question
+- **Unclear**: Insufficient information
+
+### Applicability
+- Are there concerns that the index test, its conduct, or interpretation differ from the review question?
+
+## Domain 3: Reference Standard
+
+### Signalling Questions
+1. Is the reference standard likely to correctly classify the target condition?
+2. Were the reference standard results interpreted without knowledge of the results of the index test?
+
+### Risk of Bias
+- **Low**: Yes to all signalling questions
+- **High**: No to any signalling question
+- **Unclear**: Insufficient information
+
+### Applicability
+- Are there concerns that the target condition as defined by the reference standard does not match the question?
+
+## Domain 4: Flow and Timing
+
+### Signalling Questions
+1. Was there an appropriate interval between index test and reference standard?
+2. Did all patients receive the same reference standard?
+3. Were all patients included in the analysis?
+
+### Risk of Bias
+- **Low**: Yes to all signalling questions
+- **High**: No to any signalling question
+- **Unclear**: Insufficient information
+
+(No applicability concern for this domain)
+
+## Common Issues in DTA Studies
+
+- **Partial verification bias**: Not all patients receive the reference standard (especially when invasive, e.g., biopsy)
+- **Differential verification**: Different reference standards used for different patients
+- **Incorporation bias**: Index test forms part of the reference standard
+- **Review bias**: Knowledge of index test results influences reference standard interpretation
+- **Clinical review bias**: Additional clinical information available during index test interpretation
+- **Uninterpretable results**: Exclusion of technically inadequate or indeterminate results

package/skills/meta-analysis/references/checklists/ROBINS_I.md

@@ -0,0 +1,87 @@
+# ROBINS-I Assessment Guide
+
+Risk Of Bias In Non-randomised Studies - of Interventions.
+Reference: Sterne JAC et al. BMJ 2016;355:i4919.
+
+## Structure
+
+ROBINS-I assesses 7 domains + overall judgment.
+- **Signalling questions**: Yes / Probably yes / Probably no / No / No information
+- **Domain judgment**: Low / Moderate / Serious / Critical / No information
+- **Overall judgment**: Lowest of all domain judgments (most conservative)
+
+## Pre-assessment Requirements
+
+Before applying ROBINS-I, specify:
+1. The target trial (what RCT would ideally answer this question?)
+2. The effect of interest (assignment to intervention vs starting and adhering)
+3. Confounders to be controlled
+
+## Domain 1: Bias Due to Confounding
+
+### Key Questions
+- Is there potential for confounding not accounted for?
+- Did the authors use appropriate methods to control confounding (matching, regression, propensity score)?
+
+### Judgment
+- **Low**: All critical confounders appropriately controlled
+- **Moderate**: Minor concerns about residual confounding
+- **Serious**: Important confounders not adequately controlled
+- **Critical**: Confounding so severe that no useful estimate possible
+
+## Domain 2: Bias in Selection of Participants
+
+### Key Questions
+- Was selection into the study related to both intervention and outcome?
+- Was start of follow-up and intervention aligned?
+- Were adjustments made for different start times?
+
+## Domain 3: Bias in Classification of Interventions
+
+### Key Questions
+- Were intervention groups clearly defined?
+- Was information used to classify interventions recorded at the start of the intervention?
+- Could classification of intervention status have been affected by knowledge of the outcome?
+
+## Domain 4: Bias Due to Deviations from Intended Interventions
+
+### Key Questions
+- Were there deviations from intended intervention beyond what would be expected?
+- Were these deviations unbalanced between groups and likely to affect outcomes?
+- Were important co-interventions balanced across groups?
+
+## Domain 5: Bias Due to Missing Data
+
+### Key Questions
+- Were outcome data available for all or nearly all participants?
+- Were participants excluded due to missing data on intervention or other variables?
+- Was the proportion of missing data similar across groups?
+- Were appropriate methods used to handle missing data?
+
+## Domain 6: Bias in Measurement of Outcomes
+
+### Key Questions
+- Could outcome measurement have been influenced by knowledge of intervention?
+- Were outcome assessors blinded?
+- Were outcome measures comparable across groups?
+
+## Domain 7: Bias in Selection of Reported Result
+
+### Key Questions
+- Were multiple outcome measurements reported?
+- Were multiple analyses performed?
+- Is the reported result likely selected from among multiple measurements or analyses?
+
+## Overall Risk of Bias
+
+The overall judgment is the most conservative across all domains:
+- **Low**: Low risk in all domains
+- **Moderate**: Low or moderate in all domains
+- **Serious**: Serious in at least one domain, but not critical in any
+- **Critical**: Critical in at least one domain
+
+## Recommendation for Synthesis
+
+- Studies at **critical** risk of bias should be excluded from meta-analysis
+- Present critical studies in a separate table for completeness
+- Conduct sensitivity analysis excluding serious risk of bias studies

package/skills/meta-analysis/references/checklists/RoB2.md

@@ -0,0 +1,79 @@
+# RoB 2 Assessment Guide
+
+Revised Cochrane Risk-of-Bias tool for Randomised Trials.
+Reference: Sterne JAC et al. BMJ 2019;366:l4898. PMID: 31462531.
+
+## Structure
+
+RoB 2 assesses 5 domains for each outcome in each study.
+- **Signalling questions**: Yes / Probably yes / Probably no / No / No information
+- **Domain judgment**: Low risk / Some concerns / High risk
+- **Overall judgment**: Most conservative across all domains
+
+## Domain 1: Bias Arising from the Randomisation Process
+
+### Signalling Questions
+1. Was the allocation sequence random?
+2. Was the allocation sequence concealed until participants were enrolled and assigned?
+3. Did baseline differences between groups suggest a problem with the randomisation process?
+
+### Judgment
+- **Low**: Adequate random sequence generation AND allocation concealment, no problematic baseline imbalances
+- **Some concerns**: Information insufficient to permit judgment
+- **High**: Inadequate sequence generation or concealment, or problematic baseline imbalances suggest failure
+
+## Domain 2: Bias Due to Deviations from Intended Interventions
+
+### Effect of Interest: Assignment (intention-to-treat)
+1. Were participants aware of their assigned intervention during the trial?
+2. Were carers and people delivering the interventions aware of assigned intervention?
+3. Were there deviations from the intended intervention that arose because of the trial context?
+4. Were these deviations likely to have affected the outcome?
+5. Was an appropriate analysis used to estimate the effect of assignment to intervention?
+
+### Effect of Interest: Adherence (per-protocol)
+1-2. Same as above
+3. Were important non-protocol interventions balanced across groups?
+4. Could failures in implementing the intervention have affected the outcome?
+5. Did trial participants adhere to the assigned intervention regimen?
+6. Was an appropriate analysis used to estimate the effect of adhering to intervention?
+
+## Domain 3: Bias Due to Missing Outcome Data
+
+### Signalling Questions
+1. Were data for this outcome available for all, or nearly all, participants randomised?
+2. Is there evidence that the result was not biased by missing outcome data?
+3. Could missingness in the outcome depend on its true value?
+4. Is it likely that missingness depended on its true value?
+
+### Judgment
+- **Low**: Data available for all/nearly all (>95%), or evidence result not biased by missing data
+- **Some concerns**: Missingness could depend on true value but unlikely
+- **High**: Missingness likely dependent on true value
+
+## Domain 4: Bias in Measurement of the Outcome
+
+### Signalling Questions
+1. Was the method of measuring the outcome inappropriate?
+2. Could measurement or ascertainment of the outcome have differed between groups?
+3. Were outcome assessors aware of the intervention received by study participants?
+4. Could assessment of the outcome have been influenced by knowledge of intervention?
+5. Is it likely that assessment was influenced by knowledge of intervention?
+
+## Domain 5: Bias in Selection of the Reported Result
+
+### Signalling Questions
+1. Were the data that produced this result analysed in accordance with a pre-specified analysis plan finalised before unblinded outcome data were available?
+2. Is the numerical result likely to have been selected from multiple eligible outcome measurements or analyses of the data?
+
+## Overall Risk of Bias
+
+- **Low risk**: Low risk in all domains
+- **Some concerns**: Some concerns in at least one domain, but not high risk in any
+- **High risk**: High risk in at least one domain, OR some concerns in multiple domains in a way that substantially lowers confidence
+
+## When to Use
+
+- Use for **individually randomised, parallel-group trials** (default)
+- Variants available for: cluster-randomised trials, crossover trials
+- Do NOT use for non-randomised studies (use ROBINS-I instead)

package/skills/meta-analysis/references/data_integrity_checklist.md

@@ -0,0 +1,57 @@
+# Data Integrity Checklist
+
+**Applies to**: the full span of Phase 3 (Extraction) ~ Phase 6 (Statistical synthesis) ~ Phase 9 (Circulation). Blocks the numerical-consistency risks specific to meta-analysis.
+
+## 1. Extraction stage
+
+### DI-1. Formalize the extraction consensus log
+- **Problem pattern**: Comparative extraction results kept only as inline comments inside the R analysis script — no standalone consensus log → arm-specific numbers become irretraceable once the script is edited.
+- **Rule**: At the start of every MA project, create `2_Data/extraction_consensus_log.md` or `3_Extraction/extraction_consensus_log.md`. Columns: study_id, arm, numerator, denominator, source_page, source_type (text/table/figure/KM-reconstruction), extractor_initials, second_reviewer_initials, timestamp, notes. Comparative extractions must live only as formal rows, never as script comments.
+
+### DI-2. Mandatory double-check of 2x2 cell counts
+- **Problem pattern**: Hand-typed 2x2 cells with arm order swapped against the source paper, or with numerator/denominator misread from a KM-derived subgroup rather than the raw table. Both fail silently until a third reviewer back-calculates the proportion.
+- **Rule**: Every 2x2 / comparative extraction requires (a) a first extraction + (b) an independent second re-extraction + (c) source re-check on any mismatch + a consensus-log row. Perform the Phase 6b "numerical safety gate".
+
+### DI-3. Complete the KM-reconstruction audit trail
+- **Problem pattern**: Subgroup cell counts reconstructed from a published KM curve without preserving the WebPlotDigitizer trace or the IPDfromKM reconstruction log → numbers cannot be re-derived if a reviewer challenges them.
+- **Rule**: KM-reconstruction outputs must be kept as a set in `3_Extraction/km_reconstruction/{study_id}/`: (a) the WebPlotDigitizer JSON, (b) the IPDfromKM CSV, and (c) metadata for tool version + coordinate values + parameters + date. Link them in the consensus log as type "km-reconstruction".
+
+### DI-4. Denominator change = source page citation + consensus-log row
+- **Problem pattern**: Denominator correction (e.g., treatment-naive subset) entered only as an R-script comment without citing the source paper's page/table → the correction's rationale is lost at revision.
+- **Rule**: Every denominator change requires (a) a source page/table citation, (b) a sentence stating the rationale, and (c) one consensus-log row. Reject the change if any of the three is missing.
+
+### DI-5. Methodology mismatch random spot-check
+- **Problem pattern**: A source paper reports per-protocol analysis while the SR framework is ITT/ITD (or vice versa). Without a methodology spot-check, the study's effect estimate is silently re-used under a different analysis framework.
+- **Rule**: Include a "methodology flag" in the extraction spot-check scope — whether each study's source analysis unit (per-protocol / ITT / ITD) matches our SR framework. Re-extract on mismatch.
+
+## 2. 3~5-way consistency
+
+### DI-6. PRISMA flow 5-way consistency
+- **Problem pattern**: PRISMA flow numbers drift across the search CSV, the screening log, the Methods prose, the Results prose, and the Figure 1 caption — five surfaces reach submission in three mutually inconsistent states (reversed database order, divergent full-text-assessed counts, stale caption numbers).
+- **Rule**: Verify the PRISMA flow numbers as consistent across five places simultaneously:
+  1. `1_Search/*.csv` original (source of truth, no edits)
+  2. `2_Screening/prisma_flow_final.md`
+  3. Manuscript Methods prose
+  4. Manuscript Results prose (where mentioned again)
+  5. Figure 1 caption (both `5_Figures/_captions.md` and the short DOCX caption)
+- **ID-Set Gate Rule 5**: fix the prose first → then render the diagram. If the diagram is built first, editing the prose causes drift.
+- **Automation candidate**: manage `k`, `n`, and the search numbers in a single YAML source and substitute them into the prose/diagram templates.
+
+### DI-7. Single source for k = `4_Analysis/*.csv`
+- **Problem pattern**: Included-study count `k` quoted as two different values across consecutive manuscript versions because it was hand-typed into prose rather than derived from the analysis CSV.
+- **Rule**: Derive k only from the `4_Analysis/*.csv` row count. When entering k into the manuscript / MANIFEST / PROSPERO, also state the CSV path + row count.
+
+## 3. Pre-submission cleanup
+
+### DI-8. Remove every tag / TODO
+- **Problem pattern**: `TODO`, `[VERIFY-CSV]`, "to be regenerated" strings survive into the submission package — found in R scripts, figure captions, and supplementary material banners.
+- **Rule**: 0 hits for the following grep before submission day:
+  ```bash
+  rg -n "VERIFY-CSV|TODO|FIXME|XXX|to be regenerated|PH TODO|to-do" \
+     7_Manuscript/ supplement/ 5_Figures/ 6_Tables/ 1_Code/
+  ```
+- **`[VERIFY-CSV]` lifecycle**: attach (v6) → verify (v7) → mark (v8+) → remove (submission). Record each stage in the MANIFEST.
+
+### DI-9. State bias-driven homogeneity interpretation
+- **Problem pattern**: In a DTA pool where every included study is retrospective with differential verification, Sp I²=0% reflects universalized bias compression rather than true between-study homogeneity — easy to over-interpret as robust agreement.
+- **Rule**: When I²=0% and QUADAS-2 Domain 4 risk are both high/unclear → state "universalized bias compression" explicitly and frame as an "upper-bound estimate". Bias context is mandatory in the Discussion.

package/skills/meta-analysis/references/icmje_coi_guide.md

@@ -0,0 +1,181 @@
+# ICMJE COI Form Generation Guide
+
+## Overview
+
+Most journals (Springer/CVIR, Lancet, npj, etc.) require ICMJE Conflict of Interest
+disclosure forms from all authors. This guide documents how to batch-generate pre-filled
+forms using `python-docx`.
+
+## Template Location
+
+Use any existing blank ICMJE form as template. Suggested locations:
+- A previously-used filled form from one of your manuscripts (under `<project>/submission/{journal}/icmje_forms/`).
+- Download a blank from https://www.icmje.org/disclosure-of-interest/.
+
+## ICMJE Form Structure (docx)
+
+```
+Table 0 (Header): 6 rows × 2 cols
+  Row 0: Title ("ICMJE DISCLOSURE FORM")
+  Row 1: Date
+  Row 2: Author name        ← PRE-FILL THIS
+  Row 3: Manuscript title    ← PRE-FILL THIS
+  Row 4: Manuscript number   ← Leave blank or fill if known
+  Row 5: Instructions text
+
+Table 1 (Disclosures): 19 rows × 5 cols
+  Row 0: Column headers
+  Row 1: Time frame header (since initial planning)
+  Row 2: Item 1 — Support for present manuscript
+  Row 3: Time frame header (past 36 months)
+  Rows 4-15: Items 2-13 (grants, royalties, consulting, etc.)
+    → Col 3: Entity name (leave blank if no conflict)
+    → Col 4: Specifications (leave blank if no conflict)
+  Row 16: Empty
+  Row 17: Certification header
+  Row 18: Certification text  ← ADD "X" to certify
+```
+
+## Python Script: Batch Generate
+
+```python
+#!/usr/bin/env python3
+"""Batch-generate ICMJE COI forms from a template."""
+import shutil
+from pathlib import Path
+from docx import Document
+
+def generate_coi_forms(
+    template_path: str,
+    output_dir: str,
+    manuscript_title: str,
+    authors: list[tuple[str, str]],  # [(name, email), ...]
+    manuscript_number: str = "",
+    date_str: str = "",
+):
+    """
+    Generate one ICMJE COI form per author.
+    
+    KNOWN ISSUES (python-docx + ICMJE form):
+    1. Merged cells: Table 0 Row 0 and Table 1 headers use merged cells.
+       Writing to cell.text replaces ALL merged cell content.
+       → Use cell.paragraphs[0].runs approach instead.
+    2. Formatting loss: Direct cell.text assignment strips bold/italic.
+       → Preserve runs and only modify run.text.
+    3. XML namespace errors: Some ICMJE forms have custom XML.
+       python-docx may warn about "lxml.etree.XMLSyntaxError".
+       → These warnings are usually harmless; the output is still valid.
+    """
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    
+    for i, (name, email) in enumerate(authors, 1):
+        # Copy template to preserve all formatting
+        fname = f"ICMJE_COI_{i:02d}_{name.replace(' ', '_')}.docx"
+        dst = out / fname
+        shutil.copy2(template_path, dst)
+        
+        doc = Document(str(dst))
+        t0 = doc.tables[0]
+        
+        # Pre-fill header fields
+        # IMPORTANT: Access the cell, find existing text, append to it
+        # Don't replace — some cells have label + value in same cell
+        
+        # Row 1: Date
+        if date_str:
+            _safe_append(t0.rows[1].cells[0], f" {date_str}")
+        
+        # Row 2: Author name
+        _safe_append(t0.rows[2].cells[0], f" {name}")
+        
+        # Row 3: Manuscript title
+        _safe_append(t0.rows[3].cells[0], f" {manuscript_title}")
+        
+        # Row 4: Manuscript number
+        if manuscript_number:
+            _safe_append(t0.rows[4].cells[0], f" {manuscript_number}")
+        
+        doc.save(str(dst))
+        print(f"  Created: {fname}")
+    
+    print(f"\nGenerated {len(authors)} COI forms in {output_dir}")
+
+
+def _safe_append(cell, text):
+    """Append text to a cell without destroying existing formatting.
+    
+    This avoids the common python-docx pitfall where cell.text = "new"
+    destroys all runs and formatting in merged cells.
+    """
+    if cell.paragraphs:
+        p = cell.paragraphs[0]
+        if p.runs:
+            # Append to last run to preserve formatting
+            p.runs[-1].text += text
+        else:
+            # No runs — add one
+            run = p.add_run(text)
+    else:
+        cell.text = text
+
+
+# === Example usage ===
+if __name__ == "__main__":
+    # Replace with the actual author roster for your manuscript.
+    authors = [
+        ("Author One", "author1@example.com"),
+        ("Author Two", "author2@example.com"),
+        ("Author Three", "author3@example.com"),
+        # ...
+    ]
+
+    generate_coi_forms(
+        template_path="path/to/blank_ICMJE_template.docx",
+        output_dir="submission/{journal}/icmje_coi_forms/",
+        manuscript_title="Your Manuscript Title Here",
+        authors=authors,
+        date_str="YYYY-MM-DD",
+    )
+```
+
+## Common Pitfalls
+
+### 1. Merged Cell Destruction
+**Problem**: `cell.text = "new value"` on a merged cell deletes content in ALL merged cells.
+**Fix**: Use `_safe_append()` or access `cell.paragraphs[0].runs[-1].text`.
+
+### 2. XML/SQL-like Errors
+**Problem**: `lxml.etree.XMLSyntaxError` when opening some ICMJE forms.
+This happens because ICMJE's official template contains custom XML namespaces
+that python-docx doesn't fully support.
+**Fix**: These warnings are cosmetic. The output file is still valid Word doc.
+If errors persist, use `shutil.copy2()` first, then open the copy.
+
+### 3. Formatting Loss on Save
+**Problem**: Bold/italic disappears after saving.
+**Fix**: Never assign to `cell.text` directly. Always work through
+`cell.paragraphs[0].runs` to preserve formatting.
+
+### 4. Empty Cells for "No Conflict"
+**Problem**: Some journals want explicit "None" vs empty cell.
+**Fix**: Check journal-specific requirements. CVIR (Springer) accepts empty cells.
+
+## Workflow for New Projects
+
+1. Copy any existing ICMJE form as template (or download blank from icmje.org)
+2. Update `authors` list with names and emails
+3. Update `manuscript_title`
+4. Run script → generates N individual docx files
+5. Send to co-authors for review/signature
+6. Collect signed forms before submission
+
+## Author Email List (JSON format)
+
+Store alongside COI forms for reference:
+```json
+[
+  ["Author Name", "email@example.com"],
+  ...
+]
+```