@brainpilot/skills 0.0.6

package/skills/02_Cross-Domain_Foundation/cogsci-visualization/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: "cogsci-visualization"
+description: "Domain-specific visualization best practices for cognitive and neuroscience data, encoding plot type selection, color standards, and publication formatting"
+domain: "research-methods"
+version: "1.0.0"
+papers:
+ - "Allen et al., 2019"
+ - "Borland & Taylor, 2007"
+ - "Weissgerber et al., 2015"
+ - "Crameri et al., 2020"
+dependencies:
+ required:
+ - research-literacy
+ recommended:
+ - cogsci-statistics
+review_status: "ai-generated"
+---
+
+# Cognitive Science Visualization
+
+## Purpose
+
+This skill encodes domain-specific visualization knowledge for cognitive science and neuroscience. It covers which plot types to use for different data types, field conventions for brain data visualization, color accessibility standards, and publication formatting requirements. A general-purpose data scientist would produce suboptimal or misleading figures without this knowledge.
+
+## When to Use This Skill
+
+- Creating figures for a cognitive science or neuroscience manuscript
+- Visualizing RT distributions, ERP waveforms, fMRI results, or behavioral data
+- Choosing colors, scales, and formatting for publication
+- Reviewing whether a figure follows field conventions and accessibility standards
+
+## Research Planning Protocol
+
+Before creating visualizations, you MUST:
+
+1. **State the purpose** — What message should this figure communicate? What comparison or pattern should be visible?
+2. **Justify the plot choice** — Why this plot type? What alternatives were considered?
+3. **Declare the target audience** — Journal submission, conference poster, internal review?
+4. **Note potential misrepresentations** — Could this visualization mislead? Are axes, scales, or colors appropriate?
+5. **Present the plan to the user and WAIT for confirmation** before proceeding.
+
+For detailed methodology guidance, see the `research-literacy` skill.
+
+
+## ⚠️ Verification Notice
+
+This skill was generated by AI from academic literature. All parameters, thresholds, and citations require independent verification before use in research. If you find errors, please [open an issue](https://github.com/HaoxuanLiTHUAI/awesome_cognitive_and_neuroscience_skills/issues).
+
+## Plot Type Selection by Data Type
+
+### Behavioral Data: RT Distributions
+
+**Use raincloud plots, NOT bar charts.**
+
+Bar charts with error bars conceal the distribution shape, hide bimodality, and can obscure important effects (Weissgerber et al., 2015). Cognitive science RT data are characteristically right-skewed with potential multimodality.
+
+**Recommended**: Raincloud plots combine a half-violin (density), individual data points (jitter), and a boxplot summary (Allen et al., 2019).
+
+| Plot Type | When to Use | When to Avoid |
+|-----------|------------|---------------|
+| **Raincloud plot** | RT distributions, any continuous DV | Very large N where individual points overlap completely |
+| **Violin plot** | Distribution shape comparison across conditions | When individual data points matter |
+| **Strip/jitter plot** | Small to moderate N (< 100 per condition) | Very large N (overplotting) |
+| **Box plot** | Quick summary; supplements other plots | As the only visualization (hides distribution shape) |
+| **Bar chart with error bars** | **Avoid for continuous data** | Almost always; use for counts/proportions only | Weissgerber et al., 2015 |
+| **Histogram** | Examining RT distribution of a single condition | Comparing across many conditions (hard to overlay) |
+
+### Behavioral Data: Accuracy and Proportions
+
+- **Dot plots with within-subject CI**: Show condition means with dots and individual subject data points connected by lines (for within-subjects designs)
+- **Within-subject confidence intervals**: Use the Morey (2008) correction for repeated-measures CI -- standard CIs are inappropriate for within-subjects designs because they include between-subject variance
+- Calculation: Remove each subject's mean, add back grand mean, then compute standard CI (Cousineau, 2005; Morey, 2008 correction factor: multiply SE by `sqrt(k / (k-1))` where k = number of conditions)
+
+### Interaction Plots
+
+- Use **line plots** (condition x time or condition x group) with individual trajectories shown as thin semi-transparent lines behind the group means
+- For 2x2 designs: plot the continuous variable on x-axis, DV on y-axis, and use color/linetype for the second factor
+- Always show error bars (within-subject CI for repeated measures; Morey, 2008)
+
+## ERP Visualization Conventions
+
+### Waveform Plots
+
+**Polarity convention**: There is a longstanding debate about whether to plot negative up or negative down.
+
+| Convention | Prevalence | Journals |
+|------------|-----------|----------|
+| **Negative up** | Traditional in ERP research | Psychophysiology, most dedicated ERP journals |
+| **Negative down** | Increasingly common; standard mathematical convention | Some cognitive neuroscience journals, Clinical Neurophysiology |
+
+> **Recommendation**: Follow the target journal's convention. If in doubt, negative up is the traditional ERP convention (Luck, 2014, Ch. 3). Always label the y-axis clearly with polarity.
+
+### Waveform Plotting Standards
+
+- **Line width**: **1.0-1.5 pt** for condition waveforms; **0.5 pt** for axis lines (Luck, 2014)
+- **Color**: Use colorblind-safe palette; distinguish conditions by both color AND linetype (solid, dashed)
+- **Time axis**: Mark stimulus onset (**0 ms**) with a vertical dashed line
+- **Amplitude axis**: Label in microvolts (uV); include zero line
+- **Baseline period**: Shade or mark the pre-stimulus baseline period (typically **-200 to 0 ms**)
+- **Component windows**: Shade or bracket the time window of interest (e.g., N400: **300-500 ms**; Kutas & Federmeier, 2011)
+- **Grand average**: Plot grand average waveforms; optionally show individual subject waveforms as thin semi-transparent lines
+
+### Difference Waves
+
+- Plot the difference wave (condition A minus condition B) as a separate panel or overlaid in a distinct color
+- Include the **95% CI** or **standard error** band around the difference wave
+- Difference waves are essential for verifying that an effect is present before interpreting the grand average (Luck, 2014, Ch. 2)
+
+### Topographic Maps
+
+- Plot at specific time points or averaged within the component time window
+- Use a **diverging colormap** (blue-white-red or blue-zero-red) centered on zero (Crameri et al., 2020)
+- Include a **color bar** with labeled range (in uV)
+- Show electrode positions as dots on the map
+- Use consistent scale across conditions for fair comparison
+- Common time windows: N1 (**80-120 ms**), P2 (**150-250 ms**), N400 (**300-500 ms**), P600 (**500-800 ms**) (Luck, 2014)
+
+## fMRI Visualization Standards
+
+### Statistical Map Overlays
+
+- **Never use jet/rainbow colormap** (Borland & Taylor, 2007; Crameri et al., 2020). These colormaps introduce perceptual artifacts: perceived boundaries where none exist, and unequal perceptual steps.
+- **Recommended colormaps**:
+
+| Purpose | Colormap | Source |
+|---------|----------|--------|
+| Sequential (activation) | **hot**, **inferno**, **YlOrRd** | Crameri et al., 2020 |
+| Diverging (activation + deactivation) | **RdBu_r**, **coolwarm**, **vik** | Crameri et al., 2020 |
+| Perceptually uniform | **viridis**, **magma**, **cividis** | Crameri et al., 2020 |
+
+### fMRI Display Types
+
+| Display | When to Use | Tool |
+|---------|------------|------|
+| **Orthogonal slices** | Showing peak activation in a specific region | nilearn `plot_stat_map` |
+| **Glass brain** | Whole-brain overview; showing distributed patterns | nilearn `plot_glass_brain` |
+| **Surface projection** | Publication-quality cortical activation maps | nilearn `plot_surf_stat_map`, FreeSurfer |
+| **Montage (multi-slice)** | Showing extent of activation across brain | nilearn `plot_stat_map` with `display_mode='z'` and `cut_coords` |
+
+### fMRI Visualization Requirements
+
+- Always show a **color bar** with the statistic scale (z-score or t-value)
+- Report the **threshold** used (e.g., "z > 3.1, cluster-level p < 0.05 FWE")
+- Report **coordinate space** (MNI-152 or Talairach) and template
+- Show **both hemispheres** unless the hypothesis is lateralized
+- For ROI analyses, overlay the ROI mask on an anatomical image
+- Use **1 mm** isotropic anatomical underlay (MNI152 T1 template) for sufficient anatomical detail
+
+### What NOT to Do in fMRI Figures
+
+- Do not use 3D rendered brains with inconsistent lighting and angles (obscures data)
+- Do not show only a single slice cherry-picked to show the largest effect
+- Do not use an overly liberal threshold to make results "look better" (threshold must match the reported statistics)
+- Do not use jet/rainbow (Borland & Taylor, 2007)
+
+## Brain Connectivity Visualization
+
+### Matrix Plots (Connectivity Matrices)
+
+- Order regions by network membership (e.g., DMN, FPN, visual, motor) to reveal modular structure
+- Use hierarchical clustering to determine optimal ordering if no a priori network assignment
+- Use a **sequential colormap** for positive-only connectivity (e.g., correlation: viridis)
+- Use a **diverging colormap** for signed connectivity (e.g., partial correlation: RdBu_r centered on zero)
+- Annotate network boundaries with grid lines or color bars along axes
+
+### Chord Diagrams / Connectome Plots
+
+- Use for showing specific significant connections
+- Line width proportional to connection strength
+- Color by network membership of source or target
+- Use mne-connectivity or nilearn `plot_connectome` for 3D brain-space visualization
+
+## Color Accessibility
+
+### Mandatory: Colorblind-Safe Palettes
+
+Approximately **8%** of males and **0.5%** of females have color vision deficiency (Birch, 2012). All figures must be interpretable by colorblind readers.
+
+**Recommended palettes**:
+
+| Palette | Type | Colors | Source |
+|---------|------|--------|--------|
+| **viridis** | Sequential | Yellow-green-blue-purple | Crameri et al., 2020 |
+| **cividis** | Sequential (optimized for CVD) | Yellow-blue | Nuñez et al., 2018 |
+| **Okabe-Ito** | Categorical (8 colors) | `#E69F00, #56B4E9, #009E73, #F0E442, #0072B2, #D55E00, #CC79A7, #000000` | Okabe & Ito, 2002 |
+| **viridis family** (magma, inferno, plasma) | Sequential | Various | Crameri et al., 2020 |
+| **RdBu** | Diverging | Red-white-blue | ColorBrewer; Crameri et al., 2020 |
+
+### Color Usage Guidelines
+
+- **Never** rely on color alone to convey information; use shape, linetype, or labels as redundant cues (WCAG 2.1 guideline 1.4.1)
+- For categorical comparisons, limit to **6-8 colors** maximum (Miller, 1956 -- chunking limit; also practical perceptual limit)
+- Test figures with a CVD simulator (e.g., Coblis, Color Oracle) before submission
+- Avoid red-green contrasts (most common CVD is deuteranopia/protanopia)
+
+## Publication Formatting Standards
+
+### APA 7th Edition Figure Requirements
+
+| Parameter | Specification | Source |
+|-----------|--------------|--------|
+| Resolution | **300 DPI** minimum for print; **600 DPI** for line art | APA 7th, 2020, Section 7.22 |
+| Font | Sans-serif (Arial, Helvetica) **8-14 pt** in the final printed figure | APA 7th, 2020, Section 7.22 |
+| Line weight | **0.5-1.5 pt** minimum for visibility after reduction | APA 7th, 2020 |
+| Figure width | Single column: **3.3 in** (84 mm); double column: **6.9 in** (175 mm) | Typical journal specifications |
+| File format | **TIFF** or **EPS** for print; **PDF** for vector; **PNG** for screen | Journal-specific |
+| Color mode | **CMYK** for print; **RGB** for online-only | Journal-specific |
+| Background | **White** (no gray backgrounds, no gridlines unless essential) | APA 7th, 2020 |
+
+### Axis and Label Standards
+
+- **Axis labels**: Capitalize first word and proper nouns only (sentence case)
+- **Axis values**: Use appropriate precision (RT in ms with 0 decimal places; effect sizes to 2 decimal places)
+- **Error bars**: Always define what they represent in the figure caption (SE, 95% CI, within-subject CI)
+- **Legend**: Place inside the plot area if space permits; avoid obscuring data
+- **Panels**: Label multi-panel figures with **(A)**, **(B)**, **(C)** in bold, upper-left corner, **12 pt** font
+
+### Common Formatting Mistakes
+
+1. **Font too small after scaling**: A figure designed at full-screen size will have illegible text when reduced to column width. Design at the final printed size.
+2. **Axis starting at non-zero**: For RT data, the y-axis should generally start at **0 ms** to avoid exaggerating small differences. Exception: when the effect is small relative to the baseline and breaking the axis is standard in the field.
+3. **Missing error bars or undefined error bars**: Every figure with summary statistics must include error bars, and the caption must state what they are (Cumming & Finch, 2005).
+4. **Inconsistent scales across panels**: When comparing conditions or time points across panels, use the same axis range.
+5. **3D bar charts**: Never use 3D effects on statistical plots; they distort perception of values (Tufte, 2001).
+
+## Common Visualization Mistakes in Cognitive Science
+
+### 1. Bar Charts for Continuous Data
+**Problem**: Bar charts conceal distribution shape, bimodality, outliers, and sample size (Weissgerber et al., 2015).
+**Fix**: Use raincloud plots, violin plots, or strip plots that show individual data points.
+
+### 2. Dynamite Plots (Bar + SE)
+**Problem**: Two very different distributions can produce identical bar + SE plots (Weissgerber et al., 2015).
+**Fix**: Show the data. At minimum, overlay individual data points on any summary plot.
+
+### 3. Rainbow/Jet Colormaps for Brain Images
+**Problem**: Perceptually non-uniform; creates false boundaries; misleads interpretation of gradients (Borland & Taylor, 2007).
+**Fix**: Use perceptually uniform colormaps (viridis, inferno, magma) or scientifically designed colormaps (Crameri et al., 2020).
+
+### 4. Between-Subject Error Bars on Within-Subject Designs
+**Problem**: Standard error bars include between-subject variance, which is irrelevant for within-subject comparisons (Loftus & Masson, 1994).
+**Fix**: Use within-subject CIs (Morey, 2008; Cousineau, 2005).
+
+### 5. Cherry-Picked Brain Slices
+**Problem**: Showing only the single slice with the largest activation cluster misrepresents spatial extent.
+**Fix**: Show a montage of slices or a glass brain projection; share full unthresholded maps on NeuroVault.
+
+### 6. Unlabeled Color Scales on Brain Maps
+**Problem**: Without a labeled color bar showing the statistical range, the reader cannot interpret the image.
+**Fix**: Always include a color bar with the statistic type (z, t, F) and the numerical range.
+
+### 7. Inconsistent ERP Polarity
+**Problem**: Mixing negative-up and negative-down within the same paper or comparing across papers without noting the convention.
+**Fix**: State the polarity convention; label the y-axis clearly; be consistent throughout.
+
+### 8. Not Showing Individual Data
+**Problem**: Group means alone can mask important individual variability (e.g., bimodal response patterns in clinical populations).
+**Fix**: Overlay individual data points (jitter/strip) or show small-multiples of individual subjects.
+
+## Quick Reference Decision Table
+
+| Data Type | Recommended Plot | Tool | Recipe Reference |
+|-----------|-----------------|------|-----------------|
+| RT distribution | Raincloud plot | ggrain (R) / PtitPrince (Python) | `references/plot-recipes.md` Recipe 1 |
+| ERP waveform | Line plot with CI band | MNE-Python / ggplot2 | Recipe 2 |
+| ERP topography | Topographic map | MNE-Python `plot_topomap` | Recipe 3 |
+| fMRI activation | Glass brain or surface | nilearn | Recipe 4 |
+| Accuracy by condition | Dot plot with within-subject CI | ggplot2 / matplotlib | Recipe 5 |
+| Group comparison | Estimation plot (Gardner-Altman) | DABEST / dabestr | Recipe 6 |
+| Time-frequency | TFR heatmap | MNE-Python | Recipe 7 |
+| Correlation matrix | Clustered heatmap | seaborn / corrplot | Recipe 8 |
+
+## References
+
+- Allen, M., Poggiali, D., Whitaker, K., Marshall, T. R., & Kievit, R. A. (2019). Raincloud plots: A multi-platform tool for robust data visualization. *Wellcome Open Research*, 4, 63.
+- American Psychological Association. (2020). *Publication Manual of the APA* (7th ed.).
+- Birch, J. (2012). Worldwide prevalence of red-green color deficiency. *Journal of the Optical Society of America A*, 29(3), 313-320.
+- Borland, D., & Taylor, R. M. (2007). Rainbow color map (still) considered harmful. *IEEE Computer Graphics and Applications*, 27(2), 14-17.
+- Cousineau, D. (2005). Confidence intervals in within-subject designs: A simpler solution to Loftus and Masson's method. *Tutorials in Quantitative Methods for Psychology*, 1(1), 42-45.
+- Crameri, F., Shephard, G. E., & Heron, P. J. (2020). The misuse of colour in science communication. *Nature Communications*, 11, 5444.
+- Cumming, G., & Finch, S. (2005). Inference by eye: Confidence intervals and how to read pictures of data. *American Psychologist*, 60(2), 170-180.
+- Kutas, M., & Federmeier, K. D. (2011). Thirty years and counting: Finding meaning in the N400 component. *Annual Review of Psychology*, 62, 621-647.
+- Loftus, G. R., & Masson, M. E. J. (1994). Using confidence intervals in within-subject designs. *Psychonomic Bulletin & Review*, 1(4), 476-490.
+- Luck, S. J. (2014). *An Introduction to the Event-Related Potential Technique* (2nd ed.). MIT Press.
+- Miller, G. A. (1956). The magical number seven, plus or minus two. *Psychological Review*, 63(2), 81-97.
+- Morey, R. D. (2008). Confidence intervals from normalized data: A correction to Cousineau (2005). *Tutorials in Quantitative Methods for Psychology*, 4(2), 61-64.
+- Nuñez, J. R., Anderton, C. R., & Renslow, R. S. (2018). Optimizing colormaps with consideration for color vision deficiency to enable accurate interpretation of scientific data. *PLoS ONE*, 13(7), e0199239.
+- Okabe, M., & Ito, K. (2002). Color universal design (CUD): How to make figures and presentations that are friendly to colorblind people. J*Fly Data Depository for Drosophila Researchers*.
+- Tufte, E. R. (2001). *The Visual Display of Quantitative Information* (2nd ed.). Graphics Press.
+- Weissgerber, T. L., Milic, N. M., Winham, S. J., & Garovic, V. D. (2015). Beyond bar and line graphs: Time for a new data presentation paradigm. *PLoS Biology*, 13(4), e1002128.
+
+See `references/plot-recipes.md` for concrete code recipes for each visualization type.