@litfamily/litcodex 1.0.0

package/node_modules/@litcodex/lit-loop/vendor/scientific-visualization/references/publication_guidelines.md

@@ -0,0 +1,217 @@
+# Publication-Ready Figure Guidelines
+
+## Core Principles
+
+Scientific figures must be clear, accurate, and accessible. Publication-ready figures follow these fundamental principles:
+
+1. **Clarity**: Information should be immediately understandable
+2. **Accuracy**: Data representation must be truthful and unmanipulated
+3. **Accessibility**: Figures should be interpretable by all readers, including those with visual impairments
+4. **Professional**: Clean, polished appearance suitable for peer-reviewed journals
+
+## Resolution and File Format
+
+### Resolution Requirements
+- **Raster images (photos, microscopy)**: 300-600 DPI at final print size
+- **Line art and graphs**: 600-1200 DPI (or vector format)
+- **Combined figures**: 300-600 DPI
+
+### File Formats
+- **Vector formats (preferred for graphs/plots)**: PDF, EPS, SVG
+  - Infinitely scalable without quality loss
+  - Smaller file sizes for line art
+  - Best for: plots, diagrams, schematics
+
+- **Raster formats**: TIFF, PNG (never JPEG for scientific data)
+  - Use for: photographs, microscopy, images with continuous tone
+  - TIFF: Lossless, widely accepted
+  - PNG: Lossless, good for web and supplementary materials
+  - **Never use JPEG**: Lossy compression introduces artifacts
+
+### Size Specifications
+- **Single column**: 85-90 mm (3.35-3.54 inches) width
+- **1.5 column**: 114-120 mm (4.49-4.72 inches) width
+- **Double column**: 174-180 mm (6.85-7.08 inches) width
+- **Maximum height**: Usually 230-240 mm (9-9.5 inches)
+
+## Typography
+
+### Font Guidelines
+- **Font family**: Sans-serif fonts (Arial, Helvetica, Calibri) for most journals
+  - Some journals prefer specific fonts (check guidelines)
+  - Consistency across all figures in manuscript
+
+- **Font sizes at final print size**:
+  - Axis labels: 7-9 pt minimum
+  - Tick labels: 6-8 pt minimum
+  - Legends: 6-8 pt
+  - Panel labels (A, B, C): 8-12 pt, bold
+  - Title: Generally avoided in multi-panel figures
+
+- **Font weight**: Regular weight for most text; bold for panel labels only
+
+### Text Best Practices
+- Use sentence case for axis labels ("Time (hours)" not "TIME (HOURS)")
+- Include units in parentheses
+- Avoid abbreviations unless space-constrained (define in caption)
+- No text smaller than 5-6 pt at final size
+
+## Color Usage
+
+### Color Selection Principles
+1. **Colorblind-friendly**: ~8% of males have color vision deficiency
+   - Avoid red/green combinations
+   - Use blue/orange, blue/yellow, or add texture/pattern
+   - Test with colorblindness simulators
+
+2. **Purposeful color**: Color should convey meaning, not just aesthetics
+   - Use color to distinguish categories or highlight key data
+   - Maintain consistency across figures (same treatment = same color)
+
+3. **Print considerations**:
+   - Colors may appear different in print vs. screen
+   - Use CMYK color space for print, RGB for digital
+   - Ensure sufficient contrast (especially for grayscale conversion)
+
+### Recommended Color Palettes
+- **Qualitative (categories)**: ColorBrewer, Okabe-Ito palette
+- **Sequential (low to high)**: Viridis, Cividis, Blues, Oranges
+- **Diverging (negative to positive)**: RdBu, PuOr, BrBG (ensure colorblind-safe)
+
+### Grayscale Compatibility
+- All figures should be interpretable in grayscale
+- Use different line styles (solid, dashed, dotted) and markers
+- Add patterns/hatching to bars and areas
+
+## Layout and Composition
+
+### Multi-Panel Figures
+- **Panel labels**: Use bold uppercase letters (A, B, C) in top-left corner
+- **Spacing**: Adequate white space between panels
+- **Alignment**: Align panels along edges or axes where possible
+- **Sizing**: Related panels should have consistent sizes
+- **Arrangement**: Logical flow (left-to-right, top-to-bottom)
+
+### Plot Elements
+
+#### Axes
+- **Axis lines**: 0.5-1 pt thickness
+- **Tick marks**: Point inward or outward consistently
+- **Tick frequency**: Enough to read values, not cluttered (typically 4-7 major ticks)
+- **Axis labels**: Required on all plots; state units
+- **Axis ranges**: Start from zero for bar charts (unless scientifically inappropriate)
+
+#### Lines and Markers
+- **Line width**: 1-2 pt for data lines; 0.5-1 pt for reference lines
+- **Marker size**: 3-6 pt, larger than line width
+- **Marker types**: Differentiate when multiple series (circles, squares, triangles)
+- **Error bars**: 0.5-1 pt width; include caps if appropriate
+
+#### Legends
+- **Position**: Inside plot area if space permits, outside otherwise
+- **Frame**: Optional; if used, thin line (0.5 pt)
+- **Order**: Match order of data appearance (top to bottom or left to right)
+- **Content**: Concise descriptions; full details in caption
+
+### White Space and Margins
+- Remove unnecessary white space around plots
+- Maintain consistent margins
+- `tight_layout()` or `constrained_layout=True` in matplotlib
+
+## Data Representation Best Practices
+
+### Statistical Rigor
+- **Error bars**: Always show uncertainty (SD, SEM, CI) and state which in caption
+- **Sample size**: Indicate n in figure or caption
+- **Significance**: Mark statistical significance clearly (*, **, ***)
+- **Replicates**: Show individual data points when possible, not just summary statistics
+
+### Appropriate Chart Types
+- **Bar plots**: Comparing discrete categories; always start y-axis at zero
+- **Line plots**: Time series or continuous relationships
+- **Scatter plots**: Correlation, independent observations, replicate clouds, and embeddings. Use points only unless a fitted model/regression line is scientifically justified. Do not connect unordered scatter observations with line segments.
+- **Box plots**: Distribution comparisons; show outliers
+- **Heatmaps**: Matrix data, correlations, expression patterns
+- **Violin plots**: Distribution shape comparison (better than box plots for bimodal data)
+
+### Avoiding Distortion
+- **No 3D effects**: Distorts perception of values
+- **No unnecessary decorations**: No gradients, shadows, or chart junk
+- **Consistent scales**: Use same scale for comparable panels
+- **No truncated axes**: Unless clearly indicated and scientifically justified
+- **Linear vs. log scales**: Choose appropriate scale; always label clearly
+
+## Accessibility
+
+### Colorblind Considerations
+- Test with online simulators (e.g., Coblis, Color Oracle)
+- Use patterns/textures in addition to color
+- Provide alternative representations in supplementary materials if needed
+
+### Visual Impairment
+- High contrast between elements
+- Thick enough lines (minimum 0.5 pt)
+- Clear, uncluttered layouts
+
+### Data Availability
+- Include data tables in supplementary materials
+- Provide source data files for graphs
+- Consider interactive figures for online supplementary materials
+
+## Common Mistakes to Avoid
+
+1. **Font too small**: Text unreadable at final print size
+2. **Low resolution**: Pixelated or blurry images
+3. **Chart junk**: Unnecessary grid lines, 3D effects, decorations
+4. **Poor color choices**: Red/green combinations, low contrast
+5. **Missing elements**: No axis labels, no units, no error bars
+6. **Inconsistent styling**: Different fonts/sizes within figure or between figures
+7. **Data distortion**: Truncated axes, inappropriate scales, 3D effects
+8. **JPEG compression**: Artifacts around text and lines
+9. **Too much information**: Cramming too many data series into one plot
+10. **Inaccessible legends**: Legends outside the figure boundary after export
+
+## LLM Agent Harness Safeguards
+
+When an LLM agent writes matplotlib/seaborn scripts, guard against environment-dependent defaults:
+
+- **Fonts may be missing**: configure Pretendard as first choice and Arial as the primary fallback; use emergency system/CJK fallbacks only when both are unavailable. Embed vector fonts (`pdf.fonttype=42`, `ps.fonttype=42`).
+- **Seaborn may re-enable grids**: call the skill `rcparams()` after `sns.set_theme()` or pass `rc={'axes.grid': False}` unless the user asked for gridlines.
+- **Zero-origin axes need zero ticks**: after setting an axis lower limit to 0, explicitly verify the first major tick is labelled 0.
+- **Scatter-only data must stay scatter-only**: use `plot_scatter_only()` or `ax.scatter()` for independent observations; never use `ax.plot(..., marker='o')` because it creates connecting lines.
+- **Legends can hide evidence**: prefer outside legends for dense data; `loc='best'` is not proof of non-overlap.
+- **Figure size is final-size dependent**: choose journal width and panel count first, then scale fonts and spacing to that final physical size.
+- **Export semantics differ**: raster outputs need 600+ DPI; vector outputs should keep text and lines editable. Use tight bounding boxes, then inspect legends/colorbars for clipping.
+
+## Figure Checklist
+
+Before submission, verify:
+
+- [ ] Resolution meets journal requirements (300+ DPI for raster)
+- [ ] File format is acceptable (vector for plots, TIFF/PNG for images)
+- [ ] Figure dimensions match journal specifications
+- [ ] All text is readable at final size (minimum 6-7 pt)
+- [ ] Fonts are consistent and embedded (for PDF/EPS)
+- [ ] Colors are colorblind-friendly
+- [ ] Figure is interpretable in grayscale
+- [ ] All axes are labeled with units
+- [ ] Error bars or uncertainty indicators are present
+- [ ] Statistical significance is marked if applicable
+- [ ] Panel labels are present and consistent (A, B, C)
+- [ ] Legend is clear and complete
+- [ ] No chart junk or unnecessary elements
+- [ ] File naming follows journal conventions
+- [ ] Figure caption is comprehensive
+- [ ] Source data is available
+
+## Journal-Specific Considerations
+
+Always consult the specific journal's author guidelines. Common variations include:
+
+- **Nature journals**: RGB, 300 DPI minimum, specific size requirements
+- **Science**: EPS or high-res TIFF, specific font requirements
+- **Cell Press**: PDF or EPS preferred, Arial or Helvetica fonts
+- **PLOS**: TIFF or EPS, specific color space requirements
+- **ACS journals**: Application files (AI, EPS) or high-res TIFF
+
+See `journal_requirements.md` for detailed specifications from major publishers.

package/node_modules/@litcodex/lit-loop/vendor/scientific-visualization/references/seaborn_for_publications.md

@@ -0,0 +1,293 @@
+### Seaborn
+
+Seaborn provides a high-level, dataset-oriented interface for statistical graphics, built on matplotlib. It excels at creating publication-quality statistical visualizations with minimal code while maintaining full compatibility with matplotlib customization.
+
+**Scatter-only discipline:** use `sns.scatterplot()` for independent point observations. Do not use `sns.lineplot()` or `ax.plot(..., marker='o')` for unordered scatter data, because connecting observations implies a trajectory/interpolation. Add regression/model lines only when explicitly justified.
+
+**Key advantages for scientific visualization:**
+- Automatic statistical estimation and confidence intervals
+- Built-in support for multi-panel figures (faceting)
+- Colorblind-friendly palettes by default
+- Dataset-oriented API using pandas DataFrames
+- Semantic mapping of variables to visual properties
+
+#### Quick Start with Publication Style
+
+Configure seaborn first, then call `rcparams()`/`apply_publication_style()` so seaborn cannot silently re-enable grids or overwrite tick/legend defaults:
+
+```python
+import seaborn as sns
+import matplotlib.pyplot as plt
+from style_presets import rcparams
+
+# Configure seaborn without whitegrid
+sns.set_theme(style='ticks', context='paper', font_scale=1.1,
+              rc={'axes.grid': False})
+sns.set_palette('colorblind')
+
+# Re-apply the skill single source of truth after seaborn
+rcparams()
+
+# Create figure
+fig, ax = plt.subplots(layout='constrained')
+sns.scatterplot(data=df, x='time', y='response',
+                hue='treatment', style='condition', ax=ax)
+sns.despine()  # Remove top and right spines
+```
+
+#### Common Plot Types for Publications
+
+**Statistical comparisons:**
+```python
+# Box plot with individual points for transparency
+fig, ax = plt.subplots(figsize=(3.5, 3))
+sns.boxplot(data=df, x='treatment', y='response',
+            order=['Control', 'Low', 'High'], palette='Set2', ax=ax)
+sns.stripplot(data=df, x='treatment', y='response',
+              order=['Control', 'Low', 'High'],
+              color='black', alpha=0.3, size=3, ax=ax)
+ax.set_ylabel('Response (μM)')
+sns.despine()
+```
+
+**Distribution analysis:**
+```python
+# Violin plot with split comparison
+fig, ax = plt.subplots(figsize=(4, 3))
+sns.violinplot(data=df, x='timepoint', y='expression',
+               hue='treatment', split=True, inner='quartile', ax=ax)
+ax.set_ylabel('Gene Expression (AU)')
+sns.despine()
+```
+
+**Correlation matrices:**
+```python
+# Heatmap with proper colormap and annotations
+fig, ax = plt.subplots(figsize=(5, 4))
+corr = df.corr()
+mask = np.triu(np.ones_like(corr, dtype=bool))  # Show only lower triangle
+sns.heatmap(corr, mask=mask, annot=True, fmt='.2f',
+            cmap='RdBu_r', center=0, square=True,
+            linewidths=1, cbar_kws={'shrink': 0.8}, ax=ax)
+plt.tight_layout()
+```
+
+**Time series with confidence bands:**
+```python
+# Line plot with automatic CI calculation
+fig, ax = plt.subplots(figsize=(5, 3))
+sns.lineplot(data=timeseries, x='time', y='measurement',
+             hue='treatment', style='replicate',
+             errorbar=('ci', 95), markers=True, dashes=False, ax=ax)
+ax.set_xlabel('Time (hours)')
+ax.set_ylabel('Measurement (AU)')
+sns.despine()
+```
+
+#### Multi-Panel Figures with Seaborn
+
+**Using FacetGrid for automatic faceting:**
+```python
+# Create faceted plot
+g = sns.relplot(data=df, x='dose', y='response',
+                hue='treatment', col='cell_line', row='timepoint',
+                kind='line', height=2.5, aspect=1.2,
+                errorbar=('ci', 95), markers=True)
+g.set_axis_labels('Dose (μM)', 'Response (AU)')
+g.set_titles('{row_name} | {col_name}')
+sns.despine()
+
+# Save with correct DPI
+from figure_export import save_publication_figure
+save_publication_figure(g.figure, 'figure_facets',
+                       formats=['pdf', 'png'], dpi=600)
+```
+
+**Combining seaborn with matplotlib subplots:**
+```python
+# Create custom multi-panel layout
+fig, axes = plt.subplots(2, 2, figsize=(7, 6))
+
+# Panel A: Scatter with regression
+sns.regplot(data=df, x='predictor', y='response', ax=axes[0, 0])
+axes[0, 0].text(-0.15, 1.05, 'A', transform=axes[0, 0].transAxes,
+                fontsize=10, fontweight='bold')
+
+# Panel B: Distribution comparison
+sns.violinplot(data=df, x='group', y='value', ax=axes[0, 1])
+axes[0, 1].text(-0.15, 1.05, 'B', transform=axes[0, 1].transAxes,
+                fontsize=10, fontweight='bold')
+
+# Panel C: Heatmap
+sns.heatmap(correlation_data, cmap='viridis', ax=axes[1, 0])
+axes[1, 0].text(-0.15, 1.05, 'C', transform=axes[1, 0].transAxes,
+                fontsize=10, fontweight='bold')
+
+# Panel D: Time series
+sns.lineplot(data=timeseries, x='time', y='signal',
+             hue='condition', ax=axes[1, 1])
+axes[1, 1].text(-0.15, 1.05, 'D', transform=axes[1, 1].transAxes,
+                fontsize=10, fontweight='bold')
+
+plt.tight_layout()
+sns.despine()
+```
+
+#### Color Palettes for Publications
+
+Seaborn includes several colorblind-safe palettes:
+
+```python
+# Use built-in colorblind palette (recommended)
+sns.set_palette('colorblind')
+
+# Or specify custom colorblind-safe colors (Okabe-Ito)
+okabe_ito = ['#E69F00', '#56B4E9', '#009E73', '#F0E442',
+             '#0072B2', '#D55E00', '#CC79A7', '#000000']
+sns.set_palette(okabe_ito)
+
+# For heatmaps and continuous data
+sns.heatmap(data, cmap='viridis')  # Perceptually uniform
+sns.heatmap(corr, cmap='RdBu_r', center=0)  # Diverging, centered
+```
+
+#### Choosing Between Axes-Level and Figure-Level Functions
+
+**Axes-level functions** (e.g., `scatterplot`, `boxplot`, `heatmap`):
+- Use when building custom multi-panel layouts
+- Accept `ax=` parameter for precise placement
+- Better integration with matplotlib subplots
+- More control over figure composition
+
+```python
+fig, ax = plt.subplots(figsize=(3.5, 2.5))
+sns.scatterplot(data=df, x='x', y='y', hue='group', ax=ax)
+```
+
+**Figure-level functions** (e.g., `relplot`, `catplot`, `displot`):
+- Use for automatic faceting by categorical variables
+- Create complete figures with consistent styling
+- Great for exploratory analysis
+- Use `height` and `aspect` for sizing
+
+```python
+g = sns.relplot(data=df, x='x', y='y', col='category', kind='scatter')
+```
+
+#### Statistical Rigor with Seaborn
+
+Seaborn automatically computes and displays uncertainty:
+
+```python
+# Line plot: shows mean ± 95% CI by default
+sns.lineplot(data=df, x='time', y='value', hue='treatment',
+             errorbar=('ci', 95))  # Can change to 'sd', 'se', etc.
+
+# Bar plot: shows mean with bootstrapped CI
+sns.barplot(data=df, x='treatment', y='response',
+            errorbar=('ci', 95), capsize=0.1)
+
+# Always specify error type in figure caption:
+# "Error bars represent 95% confidence intervals"
+```
+
+#### Best Practices for Publication-Ready Seaborn Figures
+
+1. **Always set publication theme first:**
+   ```python
+   sns.set_theme(style='ticks', context='paper', font_scale=1.1)
+   ```
+
+2. **Use colorblind-safe palettes:**
+   ```python
+   sns.set_palette('colorblind')
+   ```
+
+3. **Remove unnecessary elements:**
+   ```python
+   sns.despine()  # Remove top and right spines
+   ```
+
+4. **Control figure size appropriately:**
+   ```python
+   # Axes-level: use matplotlib figsize
+   fig, ax = plt.subplots(figsize=(3.5, 2.5))
+
+   # Figure-level: use height and aspect
+   g = sns.relplot(..., height=3, aspect=1.2)
+   ```
+
+5. **Show individual data points when possible:**
+   ```python
+   sns.boxplot(...)  # Summary statistics
+   sns.stripplot(..., alpha=0.3)  # Individual points
+   ```
+
+6. **Include proper labels with units:**
+   ```python
+   ax.set_xlabel('Time (hours)')
+   ax.set_ylabel('Expression (AU)')
+   ```
+
+7. **Export at correct resolution:**
+   ```python
+    from figure_export import save_publication_figure
+    save_publication_figure(fig, 'figure_name',
+                           formats=['pdf', 'png'], dpi=600)
+   ```
+
+#### Advanced Seaborn Techniques
+
+**Pairwise relationships for exploratory analysis:**
+```python
+# Quick overview of all relationships
+g = sns.pairplot(data=df, hue='condition',
+                 vars=['gene1', 'gene2', 'gene3'],
+                 corner=True, diag_kind='kde', height=2)
+```
+
+**Hierarchical clustering heatmap:**
+```python
+# Cluster samples and features
+g = sns.clustermap(expression_data, method='ward',
+                   metric='euclidean', z_score=0,
+                   cmap='RdBu_r', center=0,
+                   figsize=(10, 8),
+                   row_colors=condition_colors,
+                   cbar_kws={'label': 'Z-score'})
+```
+
+**Joint distributions with marginals:**
+```python
+# Bivariate distribution with context
+g = sns.jointplot(data=df, x='gene1', y='gene2',
+                  hue='treatment', kind='scatter',
+                  height=6, ratio=4, marginal_kws={'kde': True})
+```
+
+#### Common Seaborn Issues and Solutions
+
+**Issue: Legend outside plot area**
+```python
+g = sns.relplot(...)
+g._legend.set_bbox_to_anchor((0.9, 0.5))
+```
+
+**Issue: Overlapping labels**
+```python
+plt.xticks(rotation=45, ha='right')
+plt.tight_layout()
+```
+
+**Issue: Text too small at final size**
+```python
+sns.set_context('paper', font_scale=1.2)  # Increase if needed
+```
+
+#### Additional Resources
+
+For more detailed seaborn information, see:
+- `scientific-packages/seaborn/SKILL.md` - Comprehensive seaborn documentation
+- `scientific-packages/seaborn/references/examples.md` - Practical use cases
+- `scientific-packages/seaborn/references/function_reference.md` - Complete API reference
+- `scientific-packages/seaborn/references/objects_interface.md` - Modern declarative API