graph-interpretation

# Scientific Graph Interpreter Interpret and explain scientific graphs, charts, and data visualizations for research publications, clinical presentations, and academic communications with precision and clarity. ## Quick Start ```python from scripts.graph_interpreter import GraphInterpreter interpreter = GraphInterpreter() # Comprehensive graph analysis analysis = interpreter.interpret( image_path="figure_1.png", graph_type="kaplan_meier", context="oncology_phase3_trial", audience="clinicians" ) print(analysis.statistical_summary) print(analysis.clinical_significance) print(analysis.suggested_caption) ``` ## Core Capabilities ### 1. Multi-Type Graph Analysis ```python analysis = interpreter.analyze( graph_type="forest_plot", data={ "studies": ["Study A", "Study B", "Study C"], "effect_sizes": [1.2, 0.8, 1.5], "confidence_intervals": [[1.0, 1.4], [0.6, 1.0], [1.2, 1.8]], "overall_effect": 1.15, "heterogeneity_p": 0.04 } ) ``` **Supported Graph Types:** | Graph Type | Common Use | Key Elements to Extract | |------------|------------|------------------------| | **Kaplan-Meier** | Survival analysis | Median survival, HR, 95% CI, log-rank p | | **Forest Plot** | Meta-analysis | Effect size, CI, heterogeneity (I²), weights | | **ROC Curve** | Diagnostic accuracy | AUC, sensitivity, specificity, optimal cutoff | | **Box Plot** | Distribution comparison | Median, IQR, outliers, whiskers | | **Scatter Plot** | Correlation | R², p-value, trend line, outliers | | **Bar Chart** | Group comparisons | Means, SEM/SD, significance indicators | | **Heatmap** | Expression/omics | Scale, clustering, row/column annotations | | **Volcano Plot** | Differential analysis | Fold change, p-value, FDR threshold | ### 2. Statistical Interpretation ```python stats = interpreter.extract_statistics( graph_data, extract=[ "p_values", "confidence_intervals", "effect_sizes", "sample_sizes", "statistical_tests" ] ) ``` **Statistical Reporting Standards:** ```python # Example output structure { "primary_outcome": { "measure": "Hazard Ratio", "value": 0.72, "ci_95": [0.58, 0.89], "p_value": 0.003, "interpretation": "32% risk reduction" }, "secondary_outcomes": [...], "significance_level": 0.05, "multiple_comparison_adjusted": True } ``` ### 3. Audience-Specific Explanations ```python explanations = interpreter.generate_multi_audience( analysis, audiences=["researchers", "clinicians", "patients", "policy_makers"] ) ``` **Explanation Templates:** **For Researchers:** > "The Kaplan-Meier analysis demonstrates a statistically significant > survival advantage for the experimental arm (HR 0.72, 95% CI 0.58-0.89, > p=0.003). Median survival improved from 14.2 to 19.6 months. > The proportional hazards assumption was verified (p=0.42)." **For Clinicians:** > "This trial shows patients on the new treatment lived about 5 months > longer on average compared to standard care. The 32% reduction in > death risk is significant and clinically meaningful. Consider this > option for eligible patients." **For Patients:** > "The study found that people taking the new treatment lived longer > than those on standard treatment. About 1 in 3 patients benefited > from the new treatment. Side effects were manageable." ### 4. Figure Caption Generation ```python caption = interpreter.generate_caption( analysis, style="journal", # or "presentation", "poster" word_limit=250, include_statistics=True ) ``` **Caption Structure:** ``` Figure X. [Brief title]. [What is shown: X-axis shows..., Y-axis shows..., lines/bars represent...]. [Key finding: Group A showed... compared to Group B...]. [Statistics: HR 0.72 (95% CI 0.58-0.89), p=0.003]. [Conclusion: This demonstrates...]. ``` ### 5. Critical Appraisal ```python appraisal = interpreter.critical_appraisal( graph_data, check=[ "appropriate_graph_type", "axis_scaling", "error_bars_present", "sample_size_adequate", "confounding_controlled", "generalizability" ] ) ``` **Common Graph Pitfalls:** | Issue | Problem | Better Approach | |-------|---------|-----------------| | Truncated y-axis | Exaggerates differences | Start at 0 or clearly indicate break | | No error bars | Hides variability | Include SD, SEM, or 95% CI | | 3D effects | Distorts perception | Use 2D with clear labels | | Dual y-axes | Confusing comparison | Separate graphs or normalized scale | | p-hacking indicators | Multiple comparisons | Adjusted p-values, Bonferroni | ## CLI Usage ```bash # Comprehensive analysis python scripts/graph_interpreter.py \ --image survival_curve.png \ --type kaplan_meier \ --context "phase_3_oncology" \ --audience clinicians \ --output analysis.json # Generate publication caption python scripts/graph_interpreter.py \ --image forest_plot.png \ --type forest_plot \ --generate caption \ --journal-style nature \ --word-limit 200 # Batch process figures python scripts/graph_interpreter.py \ --batch figures/ \ --output report.html \ --template comprehensive ``` ## Common Patterns ### Pattern 1: Clinical Trial Primary Endpoint ```python # Analyze survival curve analysis = interpreter.interpret( graph_type="kaplan_meier", primary_endpoint="overall_survival", treatment_arms=["Experimental", "Control"], key_metrics=["median_os", "hr", "ci", "p_value"] ) # Generate regulatory-ready summary regulatory_summary = interpreter.generate_regulatory_summary( analysis, guideline="ICH_E3" ) ``` ### Pattern 2: Meta-Analysis Forest Plot ```python # Interpret meta-analysis analysis = interpreter.interpret_forest_plot( studies=included_studies, check_heterogeneity=True, assess_publication_bias=True ) # Generate GRADE assessment grade_rating = interpreter.generate_grade_rating(analysis) ``` ### Pattern 3: Diagnostic Accuracy ROC ```python # Analyze diagnostic test analysis = interpreter.interpret_roc( curves=["Test A", "Test B", "Combined"], optimal_cutoffs=True, clinical Utility=True ) # Clinical decision support decision_aid = interpreter.generate_decision_aid(analysis) ``` ## Quality Checklist **Before Interpretation:** - [ ] Graph type appropriate for data - [ ] Axes clearly labeled with units - [ ] Sample sizes indicated - [ ] Statistical tests specified - [ ] Confidence intervals present **During Interpretation:** - [ ] Effect size calculated - [ ] Clinical significance assessed - [ ] Confidence intervals interpreted - [ ] Limitations noted - [ ] Generalizability considered **After Interpretation:** - [ ] Explanation appropriate for audience - [ ] Statistical terms explained - [ ] Uncertainty communicated - [ ] Actionable insights highlighted ## Best Practices **Statistical Communication:** - Always report confidence intervals with point estimates - Distinguish statistical from clinical significance - Note limitations and generalizability - Avoid causal language in observational studies **Visual Analysis:** - Check axis scales for distortion - Note truncated axes or breaks - Identify outliers and their impact - Verify error bar representation (SD vs SEM) ## Common Pitfalls ❌ **Correlation = Causation**: "X causes Y because they're correlated" ✅ **Cautious Interpretation**: "X is associated with Y; other factors may explain this" ❌ **Overstating Significance**: "Highly significant (p<0.001)" as meaning large effect ✅ **Proper Framing**: "Statistically significant but modest effect size (d=0.2)" ❌ **Ignoring Confidence Intervals**: Reporting point estimate only ✅ **Interval Reporting**: "Effect: 1.5 (95% CI: 0.9-2.4), suggesting uncertainty" --- **Skill ID**: 209 | **Version**: 1.0 | **License**: MIT