@brainpilot/skills 0.0.6

package/skills/09_Cellular_Molecular_Neuroscience/calcium-imaging-analysis-guide/references/pipeline-details.md

@@ -0,0 +1,211 @@
+# Pipeline Details: Tool Comparison and Modality-Specific Processing
+
+## Tool Comparison Matrix
+
+### Overview
+
+Four major open-source pipelines exist for calcium imaging analysis. Each has distinct strengths depending on your imaging modality, data scale, and computational resources.
+
+### Suite2P (Pachitariu et al., 2017)
+
+- **Language**: Python
+- **Modality**: Primarily 2P; 1P support via preprocessing
+- **Repository**: [MouseLand/suite2p](https://github.com/MouseLand/suite2p)
+- **Key features**:
+ - Fastest processing: runs faster than real time on standard workstations
+ - Clustering-based ROI detection via PCA and spatial smoothing
+ - Integrated Cellpose support for anatomical detection
+ - Built-in GUI for manual curation with classifier retraining
+ - Neuropil coefficient estimated iteratively with deconvolution
+- **Best for**: Large 2P datasets (>10,000 neurons), rapid processing, labs with limited computational infrastructure
+- **Limitations**: Less flexible background modeling than CaImAn; 1P support is secondary
+
+### CaImAn (Giovannucci et al., 2019)
+
+- **Language**: Python (MATLAB version also available)
+- **Modality**: 2P and 1P (via CNMF-E mode)
+- **Repository**: [flatironinstitute/CaImAn](https://github.com/flatironinstitute/CaImAn)
+- **Key features**:
+ - CNMF-based source extraction with principled statistical model
+ - NoRMCorre for non-rigid motion correction (Pnevmatikakis & Giovannucci, 2017)
+ - CNMF-E background model for 1P data (Zhou et al., 2018)
+ - OnACID for online processing during acquisition (Giovannucci et al., 2017)
+ - CNN-based component evaluation
+ - MapReduce framework for datasets larger than RAM
+- **Best for**: 1P miniscope data (CNMF-E mode), principled statistical source separation, online processing, very large datasets
+- **Limitations**: More parameters to tune; slower than Suite2P for standard 2P processing
+
+### CNMF-E (Zhou et al., 2018)
+
+- **Language**: MATLAB (standalone) or Python (via CaImAn)
+- **Modality**: 1P / miniscope only
+- **Key features**:
+ - Extended background model explicitly captures large, structured 1P background
+ - Models background as low-rank spatiotemporal component rather than per-ROI annulus
+ - Best background subtraction performance compared to alternatives (Zhou et al., 2018)
+- **Best for**: 1P miniscope data where background subtraction is critical
+- **Limitations**:
+ - Computationally demanding (memory and CPU)
+ - Can over-segment: tends to split single neurons into multiple components
+ - Offline batch processing only (OnACID-E provides online variant)
+ - Requires careful merge parameter tuning
+
+### MIN1PIPE (Lu et al., 2018)
+
+- **Language**: MATLAB
+- **Modality**: 1P / miniscope only
+- **Repository**: [JinghaoLu/MIN1PIPE](https://github.com/JinghaoLu/MIN1PIPE)
+- **Key features**:
+ - Fully automatic with minimal parameter tuning
+ - Neural enhancing module for background removal via morphological operations
+ - Hierarchical movement correction handles deformations with minimal error propagation
+ - Seeds-cleansed extraction avoids setting unknown initialization parameters
+ - RNN-LSTM classifier for calcium transient validation
+- **Best for**: Labs new to 1P analysis wanting a turnkey solution; data with severe movement artifacts
+- **Limitations**: MATLAB only; less community support than CaImAn; no online processing mode
+
+### Summary Comparison Table
+
+| Feature | Suite2P | CaImAn | CNMF-E | MIN1PIPE |
+|---------|---------|--------|--------|----------|
+| 2P support | Excellent | Excellent | No | No |
+| 1P support | Limited | Excellent (CNMF-E mode) | Excellent | Excellent |
+| Speed | Fastest | Moderate | Slow | Moderate |
+| Background model | Per-ROI annulus | CNMF / CNMF-E low-rank | Low-rank spatio-temporal | Morphological |
+| Online processing | No | Yes (OnACID) | No (OnACID-E) | No |
+| GUI | Yes | Jupyter notebooks | No | No |
+| Auto-classification | Naive Bayes | CNN | Manual | RNN-LSTM |
+| Language | Python | Python/MATLAB | MATLAB/Python | MATLAB |
+| Scalability (>10k neurons) | Excellent | Excellent | Moderate | Moderate |
+
+## Preprocessing Differences: 2P vs. 1P
+
+### Two-Photon (2P) Microscopy
+
+**Characteristics**:
+- Optical sectioning: minimal out-of-focus fluorescence
+- Sparse, punctate background (neuropil only)
+- Higher SNR for individual neurons
+- Typical frame rates: 15-30 Hz (resonant scanning), 1-5 Hz (galvo scanning)
+- FOV: 500 um x 500 um typical at 16x-25x magnification
+
+**Preprocessing pipeline**:
+1. Motion correction (rigid or non-rigid)
+2. ROI detection (standard CNMF, Suite2P clustering, or Cellpose)
+3. Neuropil correction (annulus-based, r ~ 0.7; Chen et al., 2013)
+4. dF/F computation
+5. Deconvolution
+
+**2P-specific parameters**:
+- Registration max shift: **10% of FOV** (Suite2P default; Pachitariu et al., 2017)
+- Spatial scale for cell detection: auto-detect or set to match cell diameter in pixels
+- Neuropil inner radius: **2 pixels** gap between ROI and neuropil annulus (Suite2P default)
+
+### One-Photon (1P) / Miniscope
+
+**Characteristics**:
+- No optical sectioning: large, fluctuating background from out-of-focus fluorescence
+- Background can be 5-10x brighter than individual cell signals
+- Lower SNR per neuron than 2P
+- Typical frame rates: 10-30 Hz
+- FOV: depends on GRIN lens; typically 500-1000 um diameter
+- Imaging through GRIN lens adds optical aberrations
+
+**Preprocessing pipeline**:
+1. Spatial high-pass filtering or morphological opening (remove large-scale background before registration)
+2. Motion correction (on high-pass filtered data; Giovannucci et al., 2019)
+3. Apply motion correction vectors to original (unfiltered) data
+4. Source extraction with explicit background model (CNMF-E or MIN1PIPE)
+5. dF/F computation (background already subtracted by CNMF-E)
+6. Deconvolution
+
+**1P-specific parameters**:
+- Background model rank in CNMF-E: **1-3** (number of background components per patch; Zhou et al., 2018)
+- Ring model radius for CNMF-E: **~1.5x expected cell radius** (CaImAn documentation)
+- Spatial high-pass filter kernel: **~2-3x cell diameter** for preprocessing (expert consensus)
+- MIN1PIPE neural enhancing: morphological disk radius ~ cell diameter
+
+**Critical difference**: Do NOT use standard neuropil subtraction (F - r*Fneu) for 1P data. The neuropil annulus approach assumes sparse background, which is violated in 1P imaging. CNMF-E's low-rank background model is required (Zhou et al., 2018).
+
+### Fiber Photometry
+
+**Characteristics**:
+- Population-level signal (no single-cell resolution)
+- Uses fiber optic implant, not a microscope
+- Measures bulk fluorescence changes from indicator-expressing population
+- Typical sampling rates: 100-1000 Hz (photomultiplier/photodiode) or 20-40 Hz (camera-based)
+- Often uses isosbestic control channel (405-415 nm excitation)
+
+**Preprocessing pipeline**:
+1. Deinterleave signal and control channels (if time-division multiplexed)
+2. Smooth both channels (low-pass Butterworth filter, **< 10 Hz** cutoff for neural signals)
+3. Fit isosbestic channel to signal channel via regression
+4. Subtract fitted isosbestic from signal (motion + bleaching correction)
+5. Divide by fitted isosbestic to get dF/F
+6. Z-score for cross-subject comparison
+
+**Fiber photometry-specific parameters**:
+- Isosbestic excitation wavelength: **405-415 nm** (calcium-independent GCaMP excitation; Lerner et al., 2015)
+- Signal excitation wavelength: **470 nm** (calcium-dependent GCaMP excitation)
+- Regression method: IRLS preferred over OLS; OLS over-fits to neural dynamics and under-corrects artifacts
+- Event detection: use z-score threshold (typically **z > 2.58**, p < 0.01) or MAD-based threshold
+
+## Cell Classification Criteria
+
+### Automated Classification Features
+
+Suite2P's built-in classifier uses the following features (Pachitariu et al., 2017):
+
+| Feature | Description | Good Cell | Bad ROI |
+|---------|-------------|-----------|---------|
+| Skewness | Skewness of neuropil-subtracted trace | > 0.5 | ~ 0 or negative |
+| Compactness | Mean pixel distance from ROI center | Low (compact soma) | High (diffuse) |
+| Footprint | Spatial extent of trace-image correlation | Moderate (soma-sized) | Very large or very small |
+| Aspect ratio | Elongation of spatial footprint | ~ 1 (round) | >> 1 (elongated, likely dendrite) |
+
+CaImAn uses a CNN trained on spatial footprints plus temporal SNR:
+- **CNN probability > 0.5**: accept as cell (Giovannucci et al., 2019)
+- **Peak SNR > 3**: minimum transient amplitude relative to noise (Giovannucci et al., 2019)
+- **Spatial correlation > 0.8**: correlation between raw data and model prediction within ROI
+
+### Manual Curation Guidelines
+
+For any dataset included in a publication, manual curation should verify:
+
+1. **Spatial footprint**: Should resemble a filled circle (soma) of expected diameter for the brain region and cell type
+2. **Temporal trace**: Should contain clearly identifiable calcium transients (fast rise, slow decay) above the noise floor
+3. **Neuropil-corrected trace**: Transients should persist after neuropil subtraction (if they disappear, the signal was likely neuropil, not somatic)
+4. **No motion correlation**: Activity should not be correlated with registration shift metrics. Check scatter plot of neural activity vs. motion magnitude
+5. **No duplicate detection**: Ensure the same neuron is not detected as multiple ROIs. Check for ROI pairs with high temporal correlation (> 0.8) and spatial proximity (< 1 cell diameter)
+
+## Motion Metric Thresholds
+
+| Metric | Acceptable Range | Action if Exceeded | Source |
+|--------|-----------------|-------------------|--------|
+| Mean frame-to-reference correlation | > **0.8** | Check preparation stability, increase reference frame count | Expert consensus |
+| Max single-frame displacement | < **10% of FOV** | Flag frames, consider excluding session | Suite2P default |
+| Frame displacement SD | < **2 um** for 2P, < **5 um** for 1P | Apply non-rigid if using rigid only | Expert consensus |
+| Fraction of bad frames (outlier shifts) | < **5%** of total frames | Consider excluding session | Expert consensus |
+| Post-correction residual motion | < **0.5 um** RMS | Acceptable for most analyses | Dombeck et al., 2007 |
+
+**Assessment protocol**:
+1. Run registration and save displacement traces (x-shift, y-shift per frame)
+2. Compute correlation of each frame to the reference image
+3. Plot displacement and correlation over time; look for sudden jumps (animal movement) and slow drift (mechanical instability)
+4. If non-rigid correction does not adequately reduce motion artifacts, the imaging session may need to be excluded
+5. For awake behaving data, examine whether residual motion correlates with behavioral variables (running speed, licking). If so, neural-behavioral correlations may be confounded by motion
+
+## References
+
+- Chen, T. W., et al. (2013). Ultrasensitive fluorescent proteins for imaging neuronal activity. *Nature*, 499, 295-300.
+- Chen, X., et al. (2020). Soma-targeted imaging of neural circuits by ribosome tethering. *Neuron*, 107(3), 454-469.
+- Dombeck, D. A., et al. (2007). Imaging large-scale neural activity with cellular resolution in awake, mobile mice. *Neuron*, 56(1), 43-57.
+- Giovannucci, A., et al. (2017). OnACID: Online analysis of calcium imaging data in real time. In *Advances in Neural Information Processing Systems*.
+- Giovannucci, A., et al. (2019). CaImAn: An open source tool for scalable calcium imaging data analysis. *eLife*, 8, e38173.
+- Lerner, T. N., et al. (2015). Intact-brain analyses reveal distinct information carried by SNc dopamine subcircuits. *Cell*, 162(3), 635-647.
+- Lu, J., et al. (2018). MIN1PIPE: A miniscope 1-photon-based calcium imaging signal extraction pipeline. *Cell Reports*, 23(12), 3673-3684.
+- Mukamel, E. A., et al. (2009). Automated analysis of cellular signals from large-scale calcium imaging data. *Neuron*, 63(6), 747-760.
+- Pachitariu, M., et al. (2017). Suite2p: beyond 10,000 neurons with standard two-photon microscopy. *bioRxiv*, 061507.
+- Pnevmatikakis, E. A., et al. (2016). Simultaneous denoising, deconvolution, and demixing of calcium imaging data. *Neuron*, 89(2), 285-299.
+- Pnevmatikakis, E. A., & Giovannucci, A. (2017). NoRMCorre: An online algorithm for piecewise rigid motion correction. *Journal of Neuroscience Methods*, 291, 83-94.
+- Zhou, P., et al. (2018). Efficient and accurate extraction of in vivo calcium signals from microendoscopic video data. *eLife*, 7, e28728.

package/skills/09_Cellular_Molecular_Neuroscience/optogenetics-protocol-designer/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: "optogenetics-protocol-designer"
+description: "Domain-validated decision logic for optogenetic stimulation parameter selection, including opsin choice, light delivery, pulse protocols, fiber placement, and control conditions"
+domain: "cellular-molecular-neuroscience"
+authors:
+ - "Claude (AI-assisted synthesis)"
+version: "1.0.0"
+papers:
+ - "Deisseroth, 2015"
+ - "Fenno, Yizhar & Deisseroth, 2011"
+ - "Yizhar, Fenno, Davidson, Mogri & Deisseroth, 2011"
+ - "Mattis et al., 2012"
+ - "Aravanis et al., 2007"
+dependencies:
+ required:
+ - research-literacy
+review_status: "ai-generated"
+---
+
+# Optogenetics Protocol Designer
+
+## Purpose
+
+Optogenetic protocol design requires domain expertise that a general-purpose programmer would systematically get wrong. Selecting an opsin is not like selecting a software library — it requires understanding photocycle kinetics, ion selectivity, spectral overlap, expression toxicity, and the biophysics of light propagation through neural tissue. A naive approach risks tissue damage from heating, silencing neurons you intended to activate (depolarization block), or producing uninterpretable results from inadequate controls. This skill encodes the decision logic that bridges the gap between "I want to activate neurons" and a rigorous, publishable optogenetic protocol.
+
+## When to Use
+
+- Designing a new optogenetic experiment from scratch
+- Selecting an opsin for a specific excitation/inhibition application
+- Determining light delivery parameters (power, wavelength, pulse protocol)
+- Planning fiber optic implant specifications
+- Designing proper control conditions for optogenetic experiments
+- Troubleshooting failed or ambiguous optogenetic manipulations
+
+## Research Planning Protocol
+
+Before executing the domain-specific steps below, you MUST:
+
+1. **State the research question** — What neural circuit question is this optogenetic manipulation addressing?
+2. **Justify the method choice** — Why optogenetics (not chemogenetics, lesion, pharmacology)? What alternatives were considered?
+3. **Declare expected outcomes** — What behavioral/neural changes do you expect from activation/inhibition?
+4. **Note assumptions and limitations** — What does this approach assume about the circuit? Where could it mislead?
+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).
+
+## Decision Tree: Research Question to Protocol
+
+### Step 1: Define the Manipulation Type
+
+| Goal | Category | Key Constraint |
+|---|---|---|
+| Drive action potentials with millisecond precision | Excitation (fast) | Need opsin with tau-off < 15 ms |
+| Sustained depolarization / increased excitability | Excitation (tonic) | Step-function opsin or low-frequency pulsed |
+| Silence neurons during a behavioral epoch | Inhibition (sustained) | Need potent inhibitory opsin, manage heating |
+| Brief synaptic suppression | Inhibition (phasic) | Fast inhibitory opsin, short pulses |
+| Bidirectional control in same animal | Dual manipulation | Spectrally separated opsins required |
+
+### Step 2: Select Opsin Class
+
+#### Excitatory Opsins (Cation Channels)
+
+| Opsin | Peak lambda | Tau-off | Photocurrent | Best For | Key Citation |
+|---|---|---|---|---|---|
+| **ChR2 (H134R)** | 470 nm | ~10 ms | Moderate | Standard activation, well-characterized | Boyden et al., 2005; Nagel et al., 2005 |
+| **ChETA (E123T)** | 470 nm | ~3 ms | Lower | High-frequency spiking (>40 Hz) | Gunaydin et al., 2010 |
+| **ChrimsonR** | 630 nm | ~15 ms | Moderate | Red-shifted, deep tissue, dual-color | Klapoetke et al., 2014 |
+| **ChRmine** | 520-530 nm | ~60 ms | Very high | Ultra-sensitive, large volume activation | Marshel et al., 2019 |
+| **CheRiff** | 460 nm | ~8 ms | ~2x ChR2 | All-optical electrophysiology | Hochbaum et al., 2014 |
+| **C1V1(TT)** | 540 nm | ~50 ms | Moderate | Red-shifted, combinatorial experiments | Yizhar et al., 2011 |
+
+#### Inhibitory Opsins
+
+| Opsin | Peak lambda | Mechanism | Photocurrent | Best For | Key Citation |
+|---|---|---|---|---|---|
+| **eNpHR3.0** | 590 nm | Cl- pump | Low (pump) | Established inhibition, yellow-light | Gradinaru et al., 2010 |
+| **eArch3.0** | 520-550 nm | H+ pump | Moderate (pump) | Green-light inhibition | Chow et al., 2010; Mattis et al., 2012 |
+| **stGtACR2** | 480 nm | Anion channel | Very high | Most potent somatic inhibition | Mahn et al., 2018 |
+| **SwiChR++** | 480 nm | Anion channel (bistable) | Moderate | Sustained inhibition, low light | Berndt et al., 2016 |
+
+#### Step-Function Opsins (Bistable)
+
+| Opsin | Activation | Deactivation | Tau-off (dark) | Best For | Key Citation |
+|---|---|---|---|---|---|
+| **SSFO** | Blue (~470 nm) | Yellow (~590 nm) | ~29 min | Sustained excitability increase | Yizhar et al., 2011 |
+| **SOUL** | Blue (~470 nm) | Yellow (~590 nm) | ~29 min | Transcranial, minimally invasive | Gong et al., 2020 |
+| **SwiChR++** | Blue (~480 nm) | Red (~600 nm) | ~115 s | Bistable inhibition | Berndt et al., 2016 |
+
+See `references/opsin-catalog.md` for the complete opsin reference with detailed kinetics.
+
+### Step 3: Determine Light Parameters
+
+#### Power Density at Target Tissue
+
+- **ChR2 EPD50**: ~1.3 mW/mm2 (Mattis et al., 2012)
+- **stGtACR2 EPD50**: ~0.05 mW/mm2 (Mahn et al., 2018) — 100-200x more sensitive than NpHR
+- **eNpHR3.0 EPD50**: ~5-10 mW/mm2 (Mattis et al., 2012)
+- **ChRmine**: effective at sub-mW/mm2 levels (Marshel et al., 2019)
+- **Typical working range**: **1-10 mW/mm2** for most excitatory opsins at the fiber tip (Aravanis et al., 2007)
+
+**CRITICAL — Tissue Heating Threshold**:
+- Temperature increase of ~0.1-0.25 deg C per mW at fiber tip for 473 nm light (Stujenske et al., 2015)
+- Keep total tissue temperature rise **below 1 deg C** to avoid artifacts (Christie et al., 2013; Owen et al., 2019)
+- At 20 mW/mm2, duty cycles above ~40% risk exceeding 1 deg C (Stujenske et al., 2015)
+- Blue light at high power can alter firing rates even WITHOUT opsin expression (Owen et al., 2019)
+
+#### Light Attenuation in Tissue
+
+- **90% of 473 nm light is lost within 1 mm** of brain tissue (Aravanis et al., 2007; Yizhar et al., 2011)
+- At 500 um from fiber tip: ~3.2% of initial intensity remains
+- At 1 mm from fiber tip: ~0.56% of initial intensity remains
+- Red-shifted light (>600 nm) penetrates deeper due to lower scattering (Klapoetke et al., 2014)
+
+#### Wavelength Selection
+
+Match the laser/LED wavelength to the opsin's absorption peak:
+
+| Opsin Class | Recommended Wavelength | Common Laser Lines |
+|---|---|---|
+| ChR2 / CheRiff / stGtACR2 | 450-490 nm | 473 nm |
+| C1V1 / ChRmine / eArch3.0 | 520-560 nm | 532 nm, 561 nm |
+| eNpHR3.0 | 570-600 nm | 594 nm |
+| ChrimsonR | 600-650 nm | 638 nm |
+
+See `references/stimulation-parameters.md` for complete pulse protocol recipes.
+
+### Step 4: Design Pulse Protocol
+
+#### General Principles
+
+- **Pulse width**: 1-10 ms for fast excitatory opsins; 5-25 ms for slower or inhibitory opsins (Mattis et al., 2012)
+- **Frequency**: Must not exceed the opsin's temporal fidelity limit
+- **Duty cycle**: Balance activation efficacy against heating; keep below 40% for sustained protocols at moderate power (Stujenske et al., 2015)
+- **Ramp-down for inhibition**: When ending sustained inhibitory light, ramp down over 500 ms to 1 s to avoid rebound excitation (Mahn et al., 2016)
+
+#### Frequency Limits by Opsin
+
+| Opsin | Max Reliable Spike Rate | Notes |
+|---|---|---|
+| ChR2 (H134R) | ~30-40 Hz sustained | Fails above gamma range in sustained trains (Mattis et al., 2012) |
+| ChETA | ~100-200 Hz | Reduced photocurrent trade-off (Gunaydin et al., 2010) |
+| ChrimsonR | ~20-30 Hz | Slower kinetics than ChR2 (Klapoetke et al., 2014) |
+| ChRmine | ~50 Hz (80 Hz with hsChRmine) | Large photocurrent compensates for slower kinetics (Marshel et al., 2019) |
+| Chronos | ~100 Hz | Fastest known excitatory opsin (Klapoetke et al., 2014) |
+
+### Step 5: Fiber Optic Specifications
+
+| Parameter | Standard Value | Rationale |
+|---|---|---|
+| Core diameter | 200 um (mice), 200-400 um (rats/primates) | Balances illumination volume vs. tissue damage (Aravanis et al., 2007) |
+| Numerical aperture (NA) | 0.22 or 0.39 | 0.22 for focused beam; 0.39 for wider illumination |
+| Fiber type | Multimode step-index | Standard for optogenetics (Sparta et al., 2012) |
+| Ferrule diameter | 1.25 mm (standard) or 2.5 mm | Compatibility with patch cables and commutators |
+
+**Placement rule**: Position the fiber tip **200-500 um above** the target region to allow light cone to cover the structure while avoiding mechanical damage to the target itself (Yizhar et al., 2011).
+
+### Step 6: Control Conditions
+
+A rigorous optogenetic experiment requires AT MINIMUM three of the following controls (Fenno et al., 2011):
+
+| Control | What It Rules Out | Implementation |
+|---|---|---|
+| **Opsin-negative + light** | Heating, visual, auditory artifacts from light | Inject control virus (e.g., AAV-hSyn-eYFP), deliver identical light |
+| **Opsin-positive + no light** | Effects of viral expression alone | Implant fiber, run behavioral protocol without laser |
+| **Wavelength control** | Non-specific photic effects | Deliver light at a wavelength outside the opsin's activation spectrum |
+| **Fiber implant only** | Mechanical damage effects | Implant fiber without virus injection |
+| **Within-subject light-off epochs** | Temporal confounds | Interleave light-on and light-off trials within sessions |
+
+**The single most common critique of optogenetic studies is inadequate controls.** The opsin-negative + light control is non-negotiable (Fenno et al., 2011).
+
+## Common Pitfalls and Domain-Specific Warnings
+
+### 1. Depolarization Block (Silencing When You Intend to Activate)
+
+At high ChR2 expression levels or with prolonged/high-frequency stimulation, excessive cation influx causes sustained depolarization that inactivates sodium channels, STOPPING action potentials (Herman et al., 2014; Lin et al., 2009). This is especially dangerous with interneurons, which enter depolarization block more readily than pyramidal cells.
+
+**Signs**: Loss of spiking after initial pulses in a train; behavioral effect opposite to prediction.
+**Prevention**: Limit pulse width to 1-5 ms; keep frequency at or below 40 Hz for ChR2; titrate expression levels; use ChETA for high-frequency applications.
+
+### 2. Tissue Heating Artifacts
+
+Continuous illumination at high power heats tissue, altering neuronal firing even without opsin expression (Owen et al., 2019; Christie et al., 2013). Blue light (473 nm) is worse than red (638 nm) for heating.
+
+**Prevention**: Use pulsed (not continuous) light; keep duty cycle below 40% at moderate power; use temperature modeling (Stujenske et al., 2015); always include opsin-negative light controls.
+
+### 3. Viral Expression Toxicity
+
+High viral titers (>1e13 vg/mL) can cause cytotoxicity, especially with prolonged expression times (>8 weeks) (Miyashita et al., 2013). Overexpression of membrane proteins disrupts normal cell physiology.
+
+**Prevention**: Use titers of **1e12 to 5e12 vg/mL** for standard applications; check for cell health at the injection site post-mortem; limit expression time to 3-6 weeks for most applications.
+
+### 4. Backpropagation of Light Along Fibers
+
+Light can scatter back up the fiber and illuminate unintended brain regions above the target. This is especially problematic for superficial targets near the brain surface.
+
+**Prevention**: Use opaque ferrule sleeves; verify illumination volume with computational modeling; consider tapered fibers for focal illumination.
+
+### 5. Antidromic Activation with Axonal Opsins
+
+When inhibitory opsins (especially GtACR2, not soma-targeted) are expressed in axons, blue light can cause depolarization at the axon initial segment, producing paradoxical excitation (Mahn et al., 2018).
+
+**Prevention**: Use **soma-targeted** variants (stGtACR2) for inhibition; avoid illuminating axon terminals with anion channelrhodopsins; verify with electrophysiology.
+
+### 6. Chloride Loading with Halorhodopsin
+
+Prolonged eNpHR3.0 activation loads neurons with chloride, shifting the GABA-A reversal potential and causing rebound excitation upon light offset (Raimondo et al., 2012).
+
+**Prevention**: Limit continuous NpHR activation to **<15 seconds**; use pulsed protocols for longer inhibition; consider anion channels (stGtACR2) for sustained inhibition.
+
+## Viral Vector Quick Reference
+
+| Serotype | Tropism | Onset | Spread | Use Case |
+|---|---|---|---|---|
+| AAV1 | Broad neuronal | 1-2 weeks | Large | General transduction (Aschauer et al., 2013) |
+| AAV2 | Neuronal (restricted) | 2-4 weeks | Small | Precise local targeting |
+| AAV5 | Neurons + glia | 2-4 weeks | Moderate | Use with neuron-specific promoter |
+| AAV8 | Broad neuronal | 1-2 weeks | Large | Deep brain structures |
+| AAV9 | Broad, crosses BBB | 1-2 weeks | Large | Systemic delivery, broad transduction |
+| AAVrg | Retrograde neuronal | 2-4 weeks | Projection-specific | Circuit-specific targeting (Tervo et al., 2016) |
+
+**Always use a neuron-specific promoter** (hSyn, CaMKII) with AAV1/5/8/9, as ubiquitous promoters (CMV, CAG) will also transduce glia (Aschauer et al., 2013).
+
+**Standard injection volume**: 200-500 nL per site in mice; 1-2 uL per site in rats (Cetin et al., 2006).
+**Standard titer**: 1e12 to 5e12 vg/mL (Miyashita et al., 2013).
+**Wait for expression**: Minimum **2-3 weeks** post-injection; optimal at **3-6 weeks** for most AAVs.
+
+## Protocol Assembly Checklist
+
+Before finalizing a protocol, verify:
+
+- [ ] Opsin matches the manipulation type (excitation/inhibition/bistable)
+- [ ] Wavelength matches the opsin's absorption spectrum (+/- 20 nm)
+- [ ] Power density is within the opsin's effective range but below heating threshold
+- [ ] Pulse frequency does not exceed the opsin's temporal fidelity
+- [ ] Duty cycle is below 40% for sustained protocols at moderate-to-high power
+- [ ] Fiber is positioned 200-500 um above target
+- [ ] At least opsin-negative + light control is planned
+- [ ] Viral titer is in the 1e12-5e12 vg/mL range
+- [ ] Expression time is 3-6 weeks (not <2 weeks, not >8 weeks without toxicity check)
+- [ ] Post-hoc histology is planned to verify expression and fiber placement
+
+## Key References
+
+- Aravanis, A. M. et al. (2007). An optical neural interface: in vivo control of rodent motor cortex. *J. Neural Eng.*, 4(3), S143-S156.
+- Boyden, E. S. et al. (2005). Millisecond-timescale, genetically targeted optical control of neural activity. *Nat. Neurosci.*, 8(9), 1263-1268.
+- Chow, B. Y. et al. (2010). High-performance genetically targetable optical neural silencing by light-driven proton pumps. *Nature*, 463, 98-102.
+- Deisseroth, K. (2015). Optogenetics: 10 years of microbial opsins in neuroscience. *Nat. Neurosci.*, 18(9), 1213-1225.
+- Fenno, L., Yizhar, O. & Deisseroth, K. (2011). The development and application of optogenetics. *Annu. Rev. Neurosci.*, 34, 389-412.
+- Gunaydin, L. A. et al. (2010). Ultrafast optogenetic control. *Nat. Neurosci.*, 13(3), 387-392.
+- Hochbaum, D. R. et al. (2014). All-optical electrophysiology in mammalian neurons. *Nat. Methods*, 11, 825-833.
+- Klapoetke, N. C. et al. (2014). Independent optical excitation of distinct neural populations. *Nat. Methods*, 11, 338-346.
+- Mahn, M. et al. (2018). High-efficiency optogenetic silencing with soma-targeted anion-conducting channelrhodopsins. *Nat. Commun.*, 9, 4125.
+- Marshel, J. H. et al. (2019). Cortical layer-specific critical dynamics triggering perception. *Science*, 365(6453), eaaw5202.
+- Mattis, J. et al. (2012). Principles for applying optogenetic tools derived from direct comparative analysis of microbial opsins. *Nat. Methods*, 9, 159-172.
+- Stujenske, J. M. et al. (2015). Modeling the spatiotemporal dynamics of light and heat propagation for in vivo optogenetics. *Cell Rep.*, 12(3), 525-534.
+- Yizhar, O. et al. (2011). Optogenetics in neural systems. *Neuron*, 71(1), 9-34.

package/skills/09_Cellular_Molecular_Neuroscience/optogenetics-protocol-designer/references/opsin-catalog.md

@@ -0,0 +1,124 @@
+# Opsin Catalog
+
+Comprehensive reference for optogenetic opsins. All values represent typical measurements in cultured hippocampal neurons unless otherwise noted. Kinetic values are at room temperature (~22-25 deg C); in vivo values at 37 deg C are approximately 2x faster (Mattis et al., 2012).
+
+## Excitatory Opsins (Cation Channels — Depolarizing)
+
+### Blue-Light Activated
+
+| Opsin | Lambda Peak | Tau-on | Tau-off | Peak Photocurrent | EPD50 | Max Spike Rate | Key Feature | Citation |
+|---|---|---|---|---|---|---|---|---|
+| ChR2 (wild-type) | 470 nm | <1 ms | 9-12 ms | ~200 pA | ~1.3 mW/mm2 | ~30-40 Hz | Gold standard, most characterized | Boyden et al., 2005; Nagel et al., 2005 |
+| ChR2 (H134R) | 470 nm | <1 ms | ~18 ms | ~300 pA | ~1.3 mW/mm2 | ~25-35 Hz | Higher photocurrent, slightly slower | Nagel et al., 2005; Mattis et al., 2012 |
+| ChETA (E123T) | 470 nm | <1 ms | ~3 ms | ~100 pA | ~2 mW/mm2 | 100-200 Hz | Ultrafast, reduced photocurrent | Gunaydin et al., 2010 |
+| ChETA (E123A) | 470 nm | <1 ms | ~4 ms | ~120 pA | ~2 mW/mm2 | ~100 Hz | Fast, slightly more current than E123T | Mattis et al., 2012 |
+| ChIEF | 450 nm | <1 ms | ~8 ms | ~400 pA | ~1 mW/mm2 | ~40-50 Hz | High current, low desensitization | Lin et al., 2009 |
+| CheRiff | 460 nm | 0.5 ms | ~8 ms | ~1 nA | ~0.2 mW/mm2 | ~40 Hz | Highest photocurrent, 9x more sensitive than ChR2 | Hochbaum et al., 2014 |
+| Chronos | 500 nm | <1 ms | ~3.5 ms | ~200 pA | ~0.5 mW/mm2 | ~100 Hz | Fastest excitatory opsin, good current | Klapoetke et al., 2014 |
+| oChIEF | 450 nm | <1 ms | ~7 ms | ~500 pA | ~1 mW/mm2 | ~50 Hz | Optimized ChIEF, minimal desensitization | Lin et al., 2013 |
+| ChroME | 510 nm | <1 ms | ~5 ms | ~600 pA | ~0.5 mW/mm2 | ~50 Hz | Engineered for two-photon holography | Mardinly et al., 2018 |
+
+### Red-Shifted Excitatory Opsins
+
+| Opsin | Lambda Peak | Tau-on | Tau-off | Peak Photocurrent | EPD50 | Max Spike Rate | Key Feature | Citation |
+|---|---|---|---|---|---|---|---|---|
+| C1V1(TT) | 540 nm | ~1 ms | ~50 ms | ~250 pA | ~1 mW/mm2 | ~15-20 Hz | First practical red-shifted opsin | Yizhar et al., 2011 |
+| ReaChR | 590 nm | ~5 ms | ~20 ms | ~300 pA | ~0.5 mW/mm2 | ~20-30 Hz | Red-shifted, good current | Lin et al., 2013 |
+| ChrimsonR | 630 nm | ~2 ms | ~15 ms | ~200 pA | ~1 mW/mm2 | ~20-30 Hz | Most red-shifted fast opsin | Klapoetke et al., 2014 |
+| CsChrimson | 630 nm | ~3 ms | ~20 ms | ~250 pA | ~0.8 mW/mm2 | ~20 Hz | Higher expression than ChrimsonR | Klapoetke et al., 2014 |
+| bReaChES | 570 nm | ~1 ms | ~10 ms | ~350 pA | ~0.5 mW/mm2 | ~30-40 Hz | Fast red-shifted, good for dual-color | Rajasethupathy et al., 2015 |
+| ChRmine | 520-530 nm | ~5 ms | ~60 ms | >1 nA | <0.1 mW/mm2 | ~50 Hz | Ultra-high sensitivity, deep tissue | Marshel et al., 2019 |
+| hsChRmine | 520-530 nm | ~3 ms | ~30 ms | ~800 pA | ~0.2 mW/mm2 | ~80 Hz | Faster ChRmine variant | Kishi et al., 2022 |
+| frChRmine | 585 nm | ~4 ms | ~45 ms | ~700 pA | ~0.15 mW/mm2 | ~40 Hz | Further red-shifted ChRmine | Kishi et al., 2022 |
+
+### Usage Notes for Excitatory Opsins
+
+**ChR2 (H134R)** remains the most widely used and best-characterized excitatory opsin. Choose it as the default unless your experiment specifically demands:
+- Higher frequency (>40 Hz) — use ChETA or Chronos
+- Red-shifted activation — use ChrimsonR or ChRmine
+- Maximum sensitivity — use CheRiff or ChRmine
+- Dual-color experiments — use ChrimsonR paired with a blue-light inhibitory opsin
+
+**ChR2 desensitization**: Under continuous illumination, ChR2 photocurrent decays ~80% from peak to steady-state. This means the first pulse in a train produces a larger response than subsequent pulses (Nagel et al., 2003; Mattis et al., 2012). Design experiments with an initial "warm-up" period of 5-10 pulses before the analysis epoch.
+
+**ChRmine caution**: While ChRmine offers extraordinary sensitivity, its slow kinetics (~60 ms tau-off) mean it cannot produce individually timed spikes at high frequency. It is best suited for sustained activation paradigms or situations requiring minimal light delivery (e.g., deep brain, large volumes, or minimally invasive approaches) (Marshel et al., 2019).
+
+## Inhibitory Opsins
+
+### Ion Pumps (One Ion Per Photocycle)
+
+| Opsin | Lambda Peak | Mechanism | Photocurrent | EPD50 | Key Feature | Limitation | Citation |
+|---|---|---|---|---|---|---|---|
+| eNpHR3.0 | 590 nm | Cl- pump (inward) | ~50-100 pA | 5-10 mW/mm2 | Established, yellow-light | Cl- loading, rebound, low sensitivity | Gradinaru et al., 2010 |
+| eArch3.0 | 520-550 nm | H+ pump (outward) | ~100-150 pA | 3-5 mW/mm2 | Green-light, fast recovery | pH changes, paradoxical presynaptic release | Chow et al., 2010; Mattis et al., 2012 |
+| ArchT | 566 nm | H+ pump (outward) | ~200 pA | ~2 mW/mm2 | Higher sensitivity than Arch | Same pH concerns as eArch3.0 | Han et al., 2011 |
+| eMac3.0 | 550 nm | H+ pump (outward) | ~80-120 pA | ~5 mW/mm2 | Alternative proton pump | Lower photocurrent | Chow et al., 2010; Mattis et al., 2012 |
+
+### Anion Channels (High Conductance)
+
+| Opsin | Lambda Peak | Mechanism | Photocurrent | EPD50 | Key Feature | Limitation | Citation |
+|---|---|---|---|---|---|---|---|
+| GtACR1 | 515 nm | Anion channel | ~500-1000 pA | ~0.02 mW/mm2 | Highest photocurrent inhibitory opsin | Axonal excitation (not soma-targeted) | Govorunova et al., 2015 |
+| GtACR2 | 470 nm | Anion channel | ~600 pA | ~0.05 mW/mm2 | Blue-activated, high current | Axonal excitation, blue light heating | Govorunova et al., 2015 |
+| stGtACR2 | 480 nm | Anion channel (soma-targeted) | ~500 pA | ~0.05 mW/mm2 | Most potent somatic inhibition | Requires blue light | Mahn et al., 2018 |
+| iC++ | 480 nm | Engineered anion channel | ~200 pA | ~0.5 mW/mm2 | Improved Cl- selectivity | Lower current than GtACRs | Berndt et al., 2016 |
+| ZipACR | 520 nm | Anion channel | ~300 pA | ~0.1 mW/mm2 | Fast kinetics for inhibition | Less characterized | Govorunova et al., 2017 |
+
+### Usage Notes for Inhibitory Opsins
+
+**stGtACR2 vs. eNpHR3.0**: stGtACR2 is 100-200x more light-sensitive than eNpHR3.0 (EPD50: 0.05 vs. 5-10 mW/mm2), produces 5-10x larger photocurrents, does not cause chloride loading, and does not have the same rebound excitation problem (Mahn et al., 2018). For new experiments, **stGtACR2 should be the default inhibitory opsin** unless:
+- You need yellow/green light activation — use eNpHR3.0 or eArch3.0
+- You need spectral separation from a blue-activated excitatory opsin — use eNpHR3.0
+
+**Pump vs. channel inhibition**: Ion pumps (NpHR, Arch) transport one ion per photocycle, limiting their inhibitory capacity. Anion channels (GtACR, stGtACR2) open a pore, allowing many ions per channel opening and producing much larger currents. However, pumps can operate against the electrochemical gradient, while channels cannot (Wiegert et al., 2017).
+
+**Antidromic activation warning**: Non-soma-targeted anion channelrhodopsins (GtACR1, GtACR2) expressed in axons can cause paradoxical excitation due to the high chloride concentration in axons, which makes chloride channel opening depolarizing rather than hyperpolarizing at axon terminals (Mahn et al., 2018). Always use **soma-targeted** variants (stGtACR2) when somatic inhibition is the goal.
+
+**eNpHR3.0 time limit**: Continuous eNpHR3.0 activation should be limited to **<15 seconds** to avoid pathological chloride accumulation and GABA-A reversal potential shifts (Raimondo et al., 2012). For longer inhibition, use pulsed protocols (e.g., 5 s on / 2 s off) or switch to stGtACR2.
+
+**eArch3.0 presynaptic caveat**: Sustained eArch3.0 activation at presynaptic terminals paradoxically increases spontaneous neurotransmitter release through pH-mediated mechanisms. This pH change, not hyperpolarization, mediates the primary synaptic silencing effect (Bhatt et al., 2015; El-Gaby et al., 2016). Use eArch3.0 primarily for somatic inhibition, not presynaptic silencing.
+
+## Step-Function and Bistable Opsins
+
+| Opsin | Activate | Deactivate | Tau-off (dark) | Type | Key Feature | Citation |
+|---|---|---|---|---|---|---|
+| SFO (C128S) | 470 nm | 590 nm | ~30 s | Excitatory | First step-function opsin | Berndt et al., 2009 |
+| SSFO (C128S/D156A) | 470 nm | 590 nm | ~29 min | Excitatory | Ultra-stable, subthreshold depolarization | Yizhar et al., 2011 |
+| SOUL | 470 nm | 590 nm | ~29 min | Excitatory | Ultra-sensitive SSFO, transcranial capable | Gong et al., 2020 |
+| SwiChR++ | 480 nm | 600 nm | ~115 s | Inhibitory | Bistable Cl- channel | Berndt et al., 2016 |
+
+### Usage Notes for Step-Function Opsins
+
+**SSFO does NOT drive action potentials directly.** It produces subthreshold depolarization that increases the cell's sensitivity to endogenous synaptic inputs (Yizhar et al., 2011). This is fundamentally different from ChR2-driven spiking and is better suited for modulating excitability than for driving precise spike patterns.
+
+**Activation protocol for SSFO**: A brief pulse (1-2 s) of blue light activates the channel; it remains open in the dark for ~29 minutes. A pulse of yellow light (~590 nm) immediately closes it. This allows experiments with minimal total light delivery and virtually no heating concern.
+
+**SwiChR++ for sustained inhibition**: SwiChR++ can be activated by a brief blue pulse and remains in the inhibitory (chloride-conducting) state for ~115 s in the dark. Red light (600 nm) deactivates it within ~150 ms (Berndt et al., 2016). This is ideal for experiments requiring sustained inhibition without continuous illumination.
+
+## References
+
+- Berndt, A. et al. (2009). Bi-stable neural state switches. *Nat. Neurosci.*, 12, 229-234.
+- Berndt, A. et al. (2016). Structural foundations of optogenetics: determinants of channelrhodopsin ion selectivity. *PNAS*, 113(4), 822-829.
+- Boyden, E. S. et al. (2005). Millisecond-timescale, genetically targeted optical control of neural activity. *Nat. Neurosci.*, 8(9), 1263-1268.
+- Chow, B. Y. et al. (2010). High-performance genetically targetable optical neural silencing. *Nature*, 463, 98-102.
+- Gong, X. et al. (2020). An ultra-sensitive step-function opsin for minimally invasive optogenetic stimulation. *Neuron*, 107(1), 38-51.
+- Govorunova, E. G. et al. (2015). Natural light-gated anion channels. *Science*, 349(6248), 647-650.
+- Govorunova, E. G. et al. (2017). Extending the time domain of neuronal silencing with cryptophyte anion channelrhodopsins. *eNeuro*, 5(1), e0174-17.
+- Gradinaru, V. et al. (2010). Molecular and cellular approaches for diversifying and extending optogenetics. *Cell*, 141(1), 154-165.
+- Gunaydin, L. A. et al. (2010). Ultrafast optogenetic control. *Nat. Neurosci.*, 13(3), 387-392.
+- Han, X. et al. (2011). A high-light sensitivity optical neural silencer. *Front. Syst. Neurosci.*, 5, 18.
+- Hochbaum, D. R. et al. (2014). All-optical electrophysiology in mammalian neurons. *Nat. Methods*, 11, 825-833.
+- Kishi, K. E. et al. (2022). Structural basis for channel conduction in the pump-like channelrhodopsin ChRmine. *Cell*, 185, 672-689.
+- Klapoetke, N. C. et al. (2014). Independent optical excitation of distinct neural populations. *Nat. Methods*, 11, 338-346.
+- Lin, J. Y. et al. (2009). Characterization of engineered channelrhodopsin variants with improved properties and kinetics. *Biophys. J.*, 96(5), 1803-1814.
+- Lin, J. Y. et al. (2013). ReaChR: a red-shifted variant of channelrhodopsin enables deep transcranial optogenetic excitation. *Nat. Neurosci.*, 16, 1499-1508.
+- Mahn, M. et al. (2018). High-efficiency optogenetic silencing with soma-targeted anion-conducting channelrhodopsins. *Nat. Commun.*, 9, 4125.
+- Mardinly, A. R. et al. (2018). Precise multimodal optical control of neural ensemble activity. *Nat. Neurosci.*, 21, 881-893.
+- Marshel, J. H. et al. (2019). Cortical layer-specific critical dynamics triggering perception. *Science*, 365(6453), eaaw5202.
+- Mattis, J. et al. (2012). Principles for applying optogenetic tools. *Nat. Methods*, 9, 159-172.
+- Nagel, G. et al. (2003). Channelrhodopsin-2, a directly light-gated cation-selective membrane channel. *PNAS*, 100(24), 13940-13945.
+- Nagel, G. et al. (2005). Light activation of channelrhodopsin-2 in excitable cells of Caenorhabditis elegans. *Curr. Biol.*, 15(24), 2279-2284.
+- Raimondo, J. V. et al. (2012). Optogenetic silencing strategies differ in their effects on inhibitory synaptic transmission. *Nat. Neurosci.*, 15, 1102-1104.
+- Rajasethupathy, P. et al. (2015). Projections from neocortex mediate top-down control of memory retrieval. *Nature*, 526, 653-659.
+- Wiegert, J. S. et al. (2017). Silencing neurons: tools, applications, and experimental constraints. *Neuron*, 95(3), 504-529.
+- Yizhar, O. et al. (2011). Optogenetics in neural systems. *Neuron*, 71(1), 9-34.