@yibeichan/claude-skills 1.0.2

package/skills/neuroimaging-qc/scripts/parse_mriqc.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Parse MRIQC group outputs and flag subjects for exclusion.
+
+Usage:
+    python parse_mriqc.py group_bold.tsv --fd-thresh 0.3 --fd-perc-thresh 30 -o qc.csv
+    python parse_mriqc.py group_T1w.tsv --type anat -o qc.csv
+"""
+
+import argparse
+import pandas as pd
+import numpy as np
+from pathlib import Path
+
+
+def load_mriqc_group(tsv_path: str) -> pd.DataFrame:
+    """Load MRIQC group TSV file."""
+    return pd.read_csv(tsv_path, sep='\t')
+
+
+def flag_bold_subjects(df, fd_mean_thresh=0.3, fd_perc_thresh=30, tsnr_zscore=-2):
+    """Flag BOLD subjects for exclusion."""
+    results = df[['bids_name']].copy()
+    
+    results['fd_mean'] = df['fd_mean']
+    results['flag_fd_mean'] = df['fd_mean'] > fd_mean_thresh
+    
+    results['fd_perc'] = df['fd_perc']
+    results['flag_fd_perc'] = df['fd_perc'] > fd_perc_thresh
+    
+    results['tsnr'] = df['tsnr']
+    tsnr_z = (df['tsnr'] - df['tsnr'].mean()) / df['tsnr'].std()
+    results['flag_low_tsnr'] = tsnr_z < tsnr_zscore
+    
+    flag_cols = [c for c in results.columns if c.startswith('flag_')]
+    results['exclude'] = results[flag_cols].any(axis=1)
+    
+    return results
+
+
+def flag_anat_subjects(df, zscore_thresh=3):
+    """Flag anatomical subjects for exclusion using z-score outlier detection."""
+    results = df[['bids_name']].copy()
+    
+    higher_worse = ['qi_1', 'cjv', 'efc']
+    lower_worse = ['cnr', 'snr_gm', 'snr_wm']
+    
+    for metric in higher_worse:
+        if metric in df.columns:
+            results[metric] = df[metric]
+            z = (df[metric] - df[metric].mean()) / df[metric].std()
+            results[f'flag_{metric}'] = z > zscore_thresh
+    
+    for metric in lower_worse:
+        if metric in df.columns:
+            results[metric] = df[metric]
+            z = (df[metric] - df[metric].mean()) / df[metric].std()
+            results[f'flag_{metric}'] = z < -zscore_thresh
+    
+    flag_cols = [c for c in results.columns if c.startswith('flag_')]
+    results['exclude'] = results[flag_cols].any(axis=1)
+    
+    return results
+
+
+def generate_summary(results, modality):
+    """Generate text summary of QC results."""
+    n_total = len(results)
+    n_exclude = results['exclude'].sum()
+    
+    summary = f"""
+MRIQC QC Summary ({modality.upper()})
+{'=' * 40}
+Total subjects: {n_total}
+Excluded: {n_exclude} ({100*n_exclude/n_total:.1f}%)
+Included: {n_total - n_exclude}
+"""
+    
+    flag_cols = [c for c in results.columns if c.startswith('flag_')]
+    summary += "\nExclusion breakdown:\n"
+    for col in flag_cols:
+        n = results[col].sum()
+        summary += f"  {col}: {n}\n"
+    
+    return summary
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Parse MRIQC outputs for QC')
+    parser.add_argument('input', help='MRIQC group TSV file')
+    parser.add_argument('--type', choices=['bold', 'anat'], default='bold')
+    parser.add_argument('--fd-thresh', type=float, default=0.3)
+    parser.add_argument('--fd-perc-thresh', type=float, default=30)
+    parser.add_argument('--zscore-thresh', type=float, default=3)
+    parser.add_argument('-o', '--output', help='Output CSV path')
+    
+    args = parser.parse_args()
+    
+    df = load_mriqc_group(args.input)
+    
+    if args.type == 'bold':
+        results = flag_bold_subjects(df, args.fd_thresh, args.fd_perc_thresh)
+    else:
+        results = flag_anat_subjects(df, args.zscore_thresh)
+    
+    print(generate_summary(results, args.type))
+    
+    if args.output:
+        results.to_csv(args.output, index=False)
+        print(f"\nResults saved to {args.output}")
+
+
+if __name__ == '__main__':
+    main()

package/skills/neuroimaging-qc/scripts/qc_report.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""
+Generate QC reports with visualizations for neuroimaging data.
+
+Usage:
+    python qc_report.py mriqc_bold.tsv --type bold -o qc_report
+    python qc_report.py qc_summary.csv --type custom --metrics fd_mean,tsnr -o report
+"""
+
+import argparse
+import pandas as pd
+import numpy as np
+from pathlib import Path
+
+# Try to import matplotlib, but don't fail if not available
+try:
+    import matplotlib.pyplot as plt
+    HAS_MPL = True
+except ImportError:
+    HAS_MPL = False
+    print("Warning: matplotlib not available, skipping plots")
+
+
+def plot_qc_distributions(df: pd.DataFrame, metrics: list, thresholds: dict = None, 
+                          output_path: Path = None):
+    """
+    Plot QC metric distributions with optional threshold lines.
+    
+    Parameters
+    ----------
+    df : pd.DataFrame
+        QC data
+    metrics : list
+        Metrics to plot
+    thresholds : dict
+        Optional {metric: (value, direction)} where direction is 'above' or 'below'
+    output_path : Path
+        Optional output path for saving figure
+    """
+    if not HAS_MPL:
+        return None
+    
+    n_metrics = len(metrics)
+    n_cols = min(2, n_metrics)
+    n_rows = (n_metrics + n_cols - 1) // n_cols
+    
+    fig, axes = plt.subplots(n_rows, n_cols, figsize=(6*n_cols, 4*n_rows))
+    if n_metrics == 1:
+        axes = [axes]
+    else:
+        axes = axes.flatten()
+    
+    for i, metric in enumerate(metrics):
+        if metric not in df.columns:
+            continue
+        
+        ax = axes[i]
+        data = df[metric].dropna()
+        
+        ax.hist(data, bins=30, edgecolor='black', alpha=0.7)
+        ax.set_xlabel(metric)
+        ax.set_ylabel('Count')
+        ax.set_title(f'{metric} Distribution (n={len(data)})')
+        
+        # Add threshold line if provided
+        if thresholds and metric in thresholds:
+            thresh_val, direction = thresholds[metric]
+            color = 'red'
+            ax.axvline(thresh_val, color=color, linestyle='--', linewidth=2,
+                      label=f'Threshold: {thresh_val}')
+            ax.legend()
+        
+        # Add mean line
+        ax.axvline(data.mean(), color='blue', linestyle='-', alpha=0.5,
+                  label=f'Mean: {data.mean():.3f}')
+    
+    # Hide unused axes
+    for j in range(i+1, len(axes)):
+        axes[j].set_visible(False)
+    
+    plt.tight_layout()
+    
+    if output_path:
+        plt.savefig(output_path, dpi=150, bbox_inches='tight')
+        print(f"Saved plot to {output_path}")
+    
+    return fig
+
+
+def plot_qc_scatter(df: pd.DataFrame, x_metric: str, y_metric: str, 
+                    color_by: str = None, output_path: Path = None):
+    """Plot scatter of two QC metrics."""
+    if not HAS_MPL:
+        return None
+    
+    fig, ax = plt.subplots(figsize=(8, 6))
+    
+    if color_by and color_by in df.columns:
+        scatter = ax.scatter(df[x_metric], df[y_metric], c=df[color_by], 
+                            cmap='coolwarm', alpha=0.6)
+        plt.colorbar(scatter, label=color_by)
+    else:
+        ax.scatter(df[x_metric], df[y_metric], alpha=0.6)
+    
+    ax.set_xlabel(x_metric)
+    ax.set_ylabel(y_metric)
+    ax.set_title(f'{x_metric} vs {y_metric}')
+    
+    # Add correlation
+    valid = df[[x_metric, y_metric]].dropna()
+    if len(valid) > 2:
+        r = valid[x_metric].corr(valid[y_metric])
+        ax.text(0.05, 0.95, f'r = {r:.3f}', transform=ax.transAxes, 
+               fontsize=12, verticalalignment='top')
+    
+    plt.tight_layout()
+    
+    if output_path:
+        plt.savefig(output_path, dpi=150, bbox_inches='tight')
+    
+    return fig
+
+
+def generate_text_report(df: pd.DataFrame, metrics: list, exclusion_col: str = 'exclude') -> str:
+    """Generate text summary report."""
+    report = []
+    report.append("=" * 60)
+    report.append("NEUROIMAGING QC REPORT")
+    report.append("=" * 60)
+    report.append("")
+    
+    # Sample summary
+    n_total = len(df)
+    report.append(f"Total subjects/runs: {n_total}")
+    
+    if exclusion_col in df.columns:
+        n_exclude = df[exclusion_col].sum()
+        report.append(f"Excluded: {n_exclude} ({100*n_exclude/n_total:.1f}%)")
+        report.append(f"Included: {n_total - n_exclude}")
+    
+    report.append("")
+    report.append("-" * 40)
+    report.append("METRIC STATISTICS")
+    report.append("-" * 40)
+    
+    for metric in metrics:
+        if metric not in df.columns:
+            continue
+        
+        data = df[metric].dropna()
+        report.append(f"\n{metric}:")
+        report.append(f"  N:      {len(data)}")
+        report.append(f"  Mean:   {data.mean():.4f}")
+        report.append(f"  Std:    {data.std():.4f}")
+        report.append(f"  Median: {data.median():.4f}")
+        report.append(f"  Min:    {data.min():.4f}")
+        report.append(f"  Max:    {data.max():.4f}")
+        report.append(f"  IQR:    [{data.quantile(0.25):.4f}, {data.quantile(0.75):.4f}]")
+    
+    return "\n".join(report)
+
+
+def generate_html_report(df: pd.DataFrame, metrics: list, title: str = "QC Report",
+                        output_path: Path = None) -> str:
+    """Generate HTML report with embedded statistics."""
+    html = f"""
+<!DOCTYPE html>
+<html>
+<head>
+    <title>{title}</title>
+    <style>
+        body {{ font-family: Arial, sans-serif; margin: 40px; }}
+        h1 {{ color: #333; }}
+        table {{ border-collapse: collapse; width: 100%; margin: 20px 0; }}
+        th, td {{ border: 1px solid #ddd; padding: 8px; text-align: left; }}
+        th {{ background-color: #4CAF50; color: white; }}
+        tr:nth-child(even) {{ background-color: #f2f2f2; }}
+        .excluded {{ background-color: #ffcccc; }}
+        .metric-summary {{ background-color: #f9f9f9; padding: 15px; margin: 10px 0; }}
+    </style>
+</head>
+<body>
+    <h1>{title}</h1>
+    <p>Generated from {len(df)} subjects/runs</p>
+"""
+    
+    # Summary statistics
+    html += "<h2>Metric Summary</h2>"
+    html += "<table><tr><th>Metric</th><th>Mean</th><th>Std</th><th>Min</th><th>Max</th></tr>"
+    
+    for metric in metrics:
+        if metric not in df.columns:
+            continue
+        data = df[metric].dropna()
+        html += f"""
+        <tr>
+            <td>{metric}</td>
+            <td>{data.mean():.4f}</td>
+            <td>{data.std():.4f}</td>
+            <td>{data.min():.4f}</td>
+            <td>{data.max():.4f}</td>
+        </tr>
+        """
+    
+    html += "</table>"
+    
+    # Subject table
+    html += "<h2>Subject Details</h2>"
+    html += "<table><tr>"
+    
+    display_cols = ['bids_name'] + [m for m in metrics if m in df.columns]
+    if 'exclude' in df.columns:
+        display_cols.append('exclude')
+    
+    for col in display_cols:
+        html += f"<th>{col}</th>"
+    html += "</tr>"
+    
+    for _, row in df.iterrows():
+        row_class = 'excluded' if row.get('exclude', False) else ''
+        html += f"<tr class='{row_class}'>"
+        for col in display_cols:
+            val = row.get(col, '')
+            if isinstance(val, float):
+                val = f"{val:.4f}"
+            html += f"<td>{val}</td>"
+        html += "</tr>"
+    
+    html += "</table></body></html>"
+    
+    if output_path:
+        with open(output_path, 'w') as f:
+            f.write(html)
+        print(f"Saved HTML report to {output_path}")
+    
+    return html
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Generate QC reports')
+    parser.add_argument('input', help='Input CSV/TSV file')
+    parser.add_argument('--type', choices=['bold', 'anat', 'custom'], default='custom')
+    parser.add_argument('--metrics', help='Comma-separated metrics to analyze')
+    parser.add_argument('-o', '--output', help='Output prefix for reports')
+    parser.add_argument('--html', action='store_true', help='Generate HTML report')
+    parser.add_argument('--no-plots', action='store_true', help='Skip plot generation')
+    
+    args = parser.parse_args()
+    
+    # Load data
+    sep = '\t' if args.input.endswith('.tsv') else ','
+    df = pd.read_csv(args.input, sep=sep)
+    
+    # Determine metrics
+    if args.metrics:
+        metrics = args.metrics.split(',')
+    elif args.type == 'bold':
+        metrics = ['fd_mean', 'fd_perc', 'tsnr', 'dvars_std']
+    elif args.type == 'anat':
+        metrics = ['qi_1', 'cnr', 'cjv', 'snr_gm', 'efc']
+    else:
+        # Auto-detect numeric columns
+        metrics = [c for c in df.columns if df[c].dtype in ['float64', 'int64']][:6]
+    
+    # Filter to existing metrics
+    metrics = [m for m in metrics if m in df.columns]
+    
+    # Generate text report
+    report = generate_text_report(df, metrics)
+    print(report)
+    
+    output_prefix = args.output or 'qc_report'
+    
+    # Save text report
+    with open(f"{output_prefix}.txt", 'w') as f:
+        f.write(report)
+    print(f"\nSaved text report to {output_prefix}.txt")
+    
+    # Generate HTML if requested
+    if args.html:
+        generate_html_report(df, metrics, output_path=Path(f"{output_prefix}.html"))
+    
+    # Generate plots
+    if not args.no_plots and HAS_MPL:
+        plot_qc_distributions(df, metrics, output_path=Path(f"{output_prefix}_distributions.png"))
+        
+        # Create fd_mean vs tsnr scatter if both exist
+        if 'fd_mean' in df.columns and 'tsnr' in df.columns:
+            plot_qc_scatter(df, 'fd_mean', 'tsnr', 
+                          color_by='exclude' if 'exclude' in df.columns else None,
+                          output_path=Path(f"{output_prefix}_scatter.png"))
+
+
+if __name__ == '__main__':
+    main()

package/skills/scientific-writer/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: scientific-writing
+description: Write rigorous scientific manuscripts, research papers, grant proposals, and literature reviews. Use when drafting or revising any part of a scientific document including abstracts, introductions, methods, results, and discussions. Applies IMRAD structure, citation styles (APA/AMA/Vancouver/IEEE), reporting guidelines (CONSORT/STROBE/PRISMA), and publication standards. Triggers on requests to write research papers, journal articles, scientific reports, academic manuscripts, grant applications, or improve scientific prose.
+---
+
+# Scientific Writing
+
+Write publication-ready scientific manuscripts using established academic conventions and evidence-based practices.
+
+## Core Principles
+
+### Evidence-Based Claims
+
+Every substantive claim requires support from peer-reviewed literature. Use appropriate hedging: "suggests" for correlational evidence, "demonstrates" for causal evidence. Never assert without citation or data support.
+
+### Clarity Over Flourish
+
+Scientific writing prioritizes precision. Use domain-specific terminology correctly, define terms on first use, prefer active voice in methods, and avoid vague qualifiers ("very significant" → "statistically significant, p < 0.001").
+
+### Reproducibility Standard
+
+Methods must enable replication: include all parameters, software versions, statistical tests, sample sizes, inclusion/exclusion criteria, effect sizes alongside p-values, and relevant reporting guideline compliance.
+
+## Two-Stage Writing Process
+
+**Stage 1: Outline with Evidence**
+Create structured outlines with bullet points marking main arguments, key citations, data points, and logical flow. This is scaffolding—not the final manuscript.
+
+**Stage 2: Convert to Prose**
+Transform outlines into complete paragraphs with proper transitions, integrated citations, and logical sentence flow. Final manuscripts contain NO bullet points except in specific Methods subsections (inclusion criteria, materials lists).
+
+## Manuscript Structure (IMRAD)
+
+### Abstract
+Write as flowing paragraph(s), NOT labeled sections. Cover: (1) context/problem, (2) methods summary, (3) key findings with statistics, (4) significance. Typically 150-300 words. Only use structured format if journal explicitly requires it.
+
+Example structure:
+```
+[Context sentence establishing importance]. [Gap or problem addressed]. 
+[Study objective]. [Methods: design, N, key measures]. [Primary result with 
+statistics]. [Secondary findings]. [Conclusion and implications].
+```
+
+### Introduction
+Follow funnel structure:
+1. Broad context (1-2 paragraphs): field importance
+2. Literature review (2-4 paragraphs): what is known, organized thematically
+3. Gap identification (1 paragraph): what remains unknown
+4. Present study (1 paragraph): objectives, hypotheses, approach
+
+### Methods
+Standard subsections:
+- **Participants/Subjects**: demographics, recruitment, ethics approval
+- **Materials/Stimuli**: detailed descriptions, validated instrument citations
+- **Procedure**: chronological protocol with timing
+- **Data Analysis**: statistical approach, software, multiple comparison corrections
+
+Include power analysis. Report all conditions. Enable replication.
+
+### Results
+Structure: (1) preliminary analyses, (2) primary hypotheses, (3) secondary/exploratory (labeled).
+
+Report consistently:
+- Descriptive: M ± SD or Mdn (IQR)
+- Inferential with effect sizes: "t(48) = 2.31, p = .025, d = 0.67"
+- Confidence intervals when possible
+
+No interpretation here—save for Discussion.
+
+### Discussion
+Structure: (1) summary without statistics, (2) interpretation in literature context, (3) limitations, (4) implications, (5) future directions, (6) conclusion.
+
+Address alternative explanations. Avoid overclaiming.
+
+## Citation Practices
+
+### Source Hierarchy
+1. Systematic reviews/meta-analyses (strongest synthesis)
+2. Randomized controlled trials (causal inference)
+3. Prospective cohort studies (temporal precedence)
+4. Cross-sectional studies (associations)
+5. Case studies/expert opinion (hypothesis-generating)
+
+### Best Practices
+- Cite primary sources, not secondary summaries
+- Balance recent work (last 5 years) with foundational papers
+- Verify claims against original sources
+- Flag contradictory evidence rather than omitting it
+- Self-citations <20%
+
+For detailed citation formatting by style, see [references/citation_styles.md](references/citation_styles.md).
+
+## Reporting Guidelines
+
+Match guideline to study type:
+- **CONSORT**: Randomized controlled trials
+- **STROBE**: Observational studies (cohort, case-control, cross-sectional)
+- **PRISMA**: Systematic reviews and meta-analyses
+- **STARD**: Diagnostic accuracy studies
+- **TRIPOD**: Prediction models
+- **ARRIVE**: Animal research
+- **CARE**: Case reports
+
+For checklists and details, see [references/reporting_guidelines.md](references/reporting_guidelines.md).
+
+## Writing Style
+
+### Verb Tense
+| Section | Tense |
+|---------|-------|
+| Introduction (established facts) | Present |
+| Introduction (prior studies) | Past |
+| Methods | Past |
+| Results | Past |
+| Discussion (your findings) | Past |
+| Discussion (interpretations) | Present |
+| Conclusions | Present |
+
+### Common Errors
+| Error | Correction |
+|-------|------------|
+| "Data shows..." | "Data show..." (plural) |
+| "Proves that..." | "Suggests/demonstrates that..." |
+| "Significant" (colloquial) | "Substantial" or "statistically significant" |
+| "In order to" | "To" |
+| "Due to the fact that" | "Because" |
+
+### Paragraph Structure
+- Open with topic sentence stating main point
+- Provide evidence and elaboration
+- Connect logically to next paragraph
+- Typical length: 4-8 sentences
+
+## Field-Specific Conventions
+
+### Biomedical/Clinical
+- Use precise anatomical/clinical terminology
+- Follow standardized nomenclature (ICD, DSM, SNOMED-CT)
+- Generic drug names first, brands in parentheses
+- "Patients" for clinical, "participants" for community research
+
+### Molecular Biology
+- Gene symbols italicized (*TP53*), proteins regular (p53)
+- Species-specific: human uppercase (*BRCA1*), mouse sentence case (*Brca1*)
+- Full species name first, then abbreviation (*Escherichia coli* → *E. coli*)
+
+### Chemistry
+- IUPAC nomenclature for compounds
+- Concentrations with units (mM, μM, nM)
+- Standard notation (SMILES, InChI)
+
+For comprehensive field conventions, see [references/field_conventions.md](references/field_conventions.md).
+
+## Figures and Tables
+
+### When to Use Which
+- **Tables**: Precise numerical data, exact values needed
+- **Figures**: Trends, patterns, relationships, visual comparisons
+
+### Requirements
+- Self-explanatory with complete captions
+- Consistent formatting and terminology
+- All axes/columns labeled with units
+- Sample sizes (n) and statistical annotations
+- No duplication between text, tables, and figures
+
+For detailed guidance, see [references/figures_tables.md](references/figures_tables.md).
+
+## Workflow Summary
+
+**Stage 1: Planning**
+1. Identify target journal, review author guidelines
+2. Determine applicable reporting guideline
+3. Outline manuscript structure
+4. Plan figures/tables as data story backbone
+
+**Stage 2: Drafting**
+1. Start with figures/tables
+2. Draft Methods first (easiest)
+3. Write Results (describe figures/tables)
+4. Compose Discussion (interpret findings)
+5. Write Introduction (set up research question)
+6. Craft Abstract last (summarize complete work)
+
+**Stage 3: Revision**
+1. Check logical flow throughout
+2. Verify terminology consistency
+3. Confirm reporting guideline adherence
+4. Verify all citations accurate
+5. Proofread for clarity
+
+## Pre-Submission Checklist
+
+- [ ] Abstract accurately reflects content (written as prose, not labeled sections)
+- [ ] All claims have citations or data support
+- [ ] Methods enable replication
+- [ ] Statistics include effect sizes and CIs
+- [ ] Figures have informative captions
+- [ ] References follow target journal style
+- [ ] Reporting guideline checklist completed
+- [ ] Word count within limits
+- [ ] Author contributions and conflicts declared