@brainpilot/skills 0.0.6

package/skills/08_Computational_Neuroscience/spiking-network-model-builder/references/network-regimes.md

@@ -0,0 +1,130 @@
+# Network Regimes and Parameter Sweeps
+
+This reference document supplements `SKILL.md` with extended detail on the Brunel (2000) network regimes and practical parameter sweep guidance.
+
+## Brunel (2000) Network Regimes
+
+The behavior of a balanced random network of LIF neurons is determined by two key parameters (Brunel, 2000):
+
+1. **g**: Relative inhibitory synaptic strength (g = |J_I| / J_E)
+2. **nu_ext / nu_thr**: Ratio of external input rate to threshold rate
+
+### Regime Map
+
+| Regime | Abbreviation | g range | nu_ext/nu_thr | Firing pattern | Synchrony | Source |
+|---|---|---|---|---|---|---|
+| Synchronous Regular | SR | < 4 | > 1 | Regular (CV << 1) | High | Brunel, 2000 |
+| Synchronous Irregular | SI | 4--8 | < 1 | Irregular (CV ~ 1) | High (oscillatory) | Brunel, 2000 |
+| Asynchronous Regular | AR | < 4 | close to 1 | Regular (CV << 1) | Low | Brunel, 2000 |
+| **Asynchronous Irregular** | **AI** | **4--8** | **> 1** | **Irregular (CV ~ 1)** | **Low** | **Brunel, 2000** |
+
+The **AI regime** is the biologically relevant target for most cortical network models.
+
+### Practical Parameter Recommendations for AI Regime
+
+For a network of N_E = 8000 excitatory and N_I = 2000 inhibitory LIF neurons (Brunel, 2000):
+
+| Parameter | Value | Notes |
+|---|---|---|
+| Connection probability (epsilon) | 0.1 | Each neuron receives C_E = 800 excitatory and C_I = 200 inhibitory inputs |
+| Excitatory weight (J_E) | 0.1 mV (PSP amplitude) | Resulting in small unitary PSPs |
+| Relative inhibition (g) | 5--6 | Ensures AI regime |
+| External rate (nu_ext) | 2 * nu_thr | Drive just above threshold for sparse firing |
+| Expected excitatory firing rate | 1--5 Hz | Depends on exact g and nu_ext |
+| Expected inhibitory firing rate | 5--15 Hz | Higher than excitatory due to lower threshold or higher drive |
+
+### Transition Boundaries
+
+Key transitions as g increases (at fixed nu_ext > nu_thr):
+
+1. **g < 4**: Network is excitation-dominated; synchronous bursts
+2. **g ~ 4**: Transition to inhibition-dominated; onset of irregularity
+3. **g = 4--8**: AI regime; irregular firing, low synchrony
+4. **g > 8**: Firing rates drop substantially; may become quiescent
+
+Key transitions as nu_ext changes (at fixed g = 5):
+
+1. **nu_ext < nu_thr**: Subthreshold drive; network relies on recurrent excitation; SI regime with oscillations
+2. **nu_ext ~ nu_thr**: Transition region
+3. **nu_ext > nu_thr**: Suprathreshold drive; AI regime
+
+## Parameter Sweep Protocol
+
+When building a new network model, follow this systematic parameter sweep to find the AI regime:
+
+### Step 1: Fix Network Architecture
+- N_E = 4000, N_I = 1000 (or scale up by factor of 2)
+- epsilon = 0.1 (connection probability)
+- J_E = 0.1 mV (will be adjusted)
+
+### Step 2: Sweep g and nu_ext
+```
+g_values = [3, 4, 5, 6, 7, 8]
+nu_ext_values = [0.8, 1.0, 1.2, 1.5, 2.0, 3.0] * nu_thr
+```
+
+For each (g, nu_ext) pair:
+1. Simulate for 1500 ms (discard first 500 ms)
+2. Compute: mean firing rate, CV of ISI, synchrony index (chi)
+
+### Step 3: Identify AI Regime
+Select parameters where:
+- Mean excitatory rate: 1--10 Hz
+- CV of ISI: 0.8--1.2
+- Synchrony index chi < 0.2
+
+### Step 4: Fine-Tune
+Once in the approximate AI regime, fine-tune with smaller parameter steps if needed.
+
+## Weight Scaling Derivation
+
+For a balanced network (Brunel, 2000; van Vreeswijk & Sompolinsky, 1998):
+
+The mean input to a neuron:
+```
+mu = C_E * J_E * nu_E - C_I * J_I * nu_I + J_ext * C_ext * nu_ext
+```
+
+For balance (mu ~ 0 in the fluctuation-driven regime):
+```
+C_E * J_E * nu_E ~ C_I * J_I * nu_I
+```
+
+Since C_I/C_E = 1/4 (from the 80/20 split with equal connection probability):
+```
+J_I = 4 * J_E * (nu_E / nu_I)
+```
+
+For equal firing rates (nu_E ~ nu_I): J_I = 4 * J_E, hence g = 4 is the boundary.
+
+The variance of the input (which drives the irregular firing) scales as:
+```
+sigma^2 = C_E * J_E^2 * nu_E + C_I * J_I^2 * nu_I
+```
+
+For the CV to be ~1, sigma must be of order (V_thresh - V_rest), which constrains J_E relative to C_E (i.e., J_E ~ 1/sqrt(C_E)).
+
+## Multi-Population Extensions
+
+For networks with more than one excitatory and one inhibitory population (e.g., Potjans & Diesmann, 2014 cortical column model):
+
+### Potjans-Diesmann Cortical Column
+
+| Layer | Population | N | Source |
+|---|---|---|---|
+| L2/3 | E | 20,683 | Potjans & Diesmann, 2014 |
+| L2/3 | I | 5,834 | Potjans & Diesmann, 2014 |
+| L4 | E | 21,915 | Potjans & Diesmann, 2014 |
+| L4 | I | 5,479 | Potjans & Diesmann, 2014 |
+| L5 | E | 4,850 | Potjans & Diesmann, 2014 |
+| L5 | I | 1,065 | Potjans & Diesmann, 2014 |
+| L6 | E | 14,395 | Potjans & Diesmann, 2014 |
+| L6 | I | 2,948 | Potjans & Diesmann, 2014 |
+
+Connection probabilities between populations form a 8x8 matrix. See Potjans & Diesmann (2014), Table 5 for the full connectivity matrix.
+
+## References
+
+- Brunel, N. (2000). Dynamics of sparsely connected networks of excitatory and inhibitory spiking neurons. *Journal of Computational Neuroscience*, 8(3), 183--208.
+- Potjans, T. C., & Diesmann, M. (2014). The cell-type specific cortical microcircuit: Relating structure and activity in a full-scale spiking network model. *Cerebral Cortex*, 24(3), 785--806.
+- van Vreeswijk, C., & Sompolinsky, H. (1998). Chaotic balanced state in a model of cortical circuits. *Neural Computation*, 10(6), 1321--1371.

package/skills/09_Cellular_Molecular_Neuroscience/calcium-imaging-analysis-guide/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: "calcium-imaging-analysis-guide"
+description: "Domain-validated pipeline guidance for calcium imaging data analysis: motion correction, ROI extraction, neuropil correction, spike inference, and quality control"
+domain: "cellular-molecular-neuroscience"
+version: "1.0.0"
+authors:
+ - "Claude (AI-assisted)"
+papers:
+ - "Chen et al., 2013"
+ - "Pachitariu et al., 2017"
+ - "Giovannucci et al., 2019"
+ - "Friedrich et al., 2017"
+ - "Zhang et al., 2023"
+dependencies:
+ required:
+ - research-literacy
+review_status: "ai-generated"
+---
+
+# Calcium Imaging Analysis Guide
+
+## Purpose
+
+This skill encodes expert methodological knowledge for analyzing calcium imaging data from fluorescent genetically encoded calcium indicators (GECIs). It covers the domain-specific decisions that a general-purpose programmer or data scientist would get wrong without specialized training in optical neurophysiology: choosing deconvolution parameters based on indicator kinetics, correcting neuropil contamination, handling modality-specific preprocessing, and interpreting fluorescence signals as neural activity.
+
+## When to Use This Skill
+
+- Designing an analysis pipeline for two-photon, one-photon/miniscope, or fiber photometry data
+- Choosing motion correction strategy for awake behaving animal recordings
+- Selecting ROI detection method for your preparation density and imaging modality
+- Setting deconvolution parameters matched to your calcium indicator
+- Evaluating whether extracted signals reflect genuine single-neuron activity
+- Troubleshooting common artifacts: photobleaching, neuropil contamination, motion
+
+## Research Planning Protocol
+
+Before executing the domain-specific steps below, you MUST:
+
+1. **State the research question** — What neural activity question is this calcium imaging analysis addressing?
+2. **Justify the method choice** — Why calcium imaging (not electrophysiology, fMRI, etc.)? What alternatives were considered?
+3. **Declare expected outcomes** — What activity patterns would support vs. refute the hypothesis?
+4. **Note assumptions and limitations** — What does this method assume? Where could it mislead (e.g., indicator kinetics, neuropil)?
+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: Which Pipeline for Your Modality
+
+```
+What is your imaging modality?
+ |
+ +-- Two-photon (2P) microscopy
+ | |
+ | +-- Sparse labeling (Cre-dependent, cell-type specific)?
+ | | --> Suite2P or CaImAn with standard CNMF
+ | | Neuropil coefficient ~0.7 (Chen et al., 2013)
+ | |
+ | +-- Dense labeling (pan-neuronal)?
+ | --> Suite2P with increased max_overlap (>=0.75)
+ | or CaImAn CNMF with careful merge parameters
+ | Consider soma-targeted indicators (Chen et al., 2020)
+ |
+ +-- One-photon (1P) / miniscope
+ | |
+ | --> CNMF-E (Zhou et al., 2018) or MIN1PIPE (Lu et al., 2018)
+ | Standard CNMF will FAIL: 1P has large structured background
+ | that requires explicit background modeling
+ | CaImAn supports 1P via CNMF-E mode
+ |
+ +-- Fiber photometry (population-level)
+ |
+ --> No single-cell extraction needed
+ Use isosbestic channel (405-415 nm) for motion/bleaching correction
+ IRLS regression preferred over OLS (Lerner et al., 2015)
+ Compute dF/F or z-scored signal
+```
+
+## Core Pipeline Steps
+
+### Step 1: Motion Correction
+
+Motion correction must precede all other analysis. Uncorrected motion creates false transients and blurs cellular signals.
+
+| Parameter | Rigid | Non-Rigid | Source |
+|-----------|-------|-----------|--------|
+| Use case | Anesthetized or head-fixed, stable | Awake behaving, brain pulsation | Pnevmatikakis & Giovannucci, 2017 |
+| Max shift | 10% of FOV (default) | 10% of FOV per patch | Suite2P default |
+| Reference frame | Iterative: top 20 of 300 random frames | Same, per-patch | Pachitariu et al., 2017 |
+
+**Domain judgment**:
+- Always use non-rigid registration for awake behaving animals. Brain tissue deforms non-uniformly due to heartbeat, respiration, and locomotion (Dombeck et al., 2007).
+- For 1P/miniscope data, apply spatial high-pass filtering before estimating motion vectors, because the large fluctuating background confounds rigid correlation-based registration (Giovannucci et al., 2019).
+- Inspect registration quality by computing the correlation of each frame to the reference. Frames with correlation below **0.5** indicate severe motion and should be flagged or excluded (expert consensus).
+- Edge pixels that shift out of the FOV during registration should be cropped; ROIs near edges may have unreliable signals.
+
+### Step 2: ROI Detection
+
+| Method | Best For | Tool | Source |
+|--------|----------|------|--------|
+| CNMF / sparse NMF | 2P, moderate density | CaImAn | Pnevmatikakis et al., 2016 |
+| Clustering + PCA | 2P, large FOV | Suite2P | Pachitariu et al., 2017 |
+| CNMF-E | 1P / miniscope | CaImAn (1P mode) | Zhou et al., 2018 |
+| Cellpose (anatomical) | Weak functional signal, good morphology | Suite2P + Cellpose | Stringer et al., 2021 |
+| PCA/ICA | Legacy, not recommended for dense data | Various | Mukamel et al., 2009 |
+
+**Domain judgment**:
+- Set expected cell diameter to match your preparation. Cortical pyramidal somata are ~10-15 um; Purkinje cells are ~25 um; granule cells are ~5 um. Converting to pixels depends on your magnification and pixel size.
+- For dense labeling, increase `max_overlap` to 0.75-1.0 (Suite2P) or adjust merge thresholds (CaImAn). Default overlap rejection discards valid overlapping neurons.
+- Set `connected=False` when detecting dendrites or axonal boutons, which are not spatially contiguous in 2D projections.
+- Always manually curate detected ROIs. Automated classifiers achieve near-human performance (Giovannucci et al., 2019) but are not perfect, especially for non-standard preparations.
+
+### Step 3: Neuropil Contamination Correction
+
+**Why this matters**: In 2P imaging, each ROI's fluorescence contains signal from the surrounding neuropil (dense mesh of dendrites and axons). Without correction, you will observe artificial correlations between neurons, inflated response amplitudes, and obscured cell-specific tuning (Chen et al., 2013).
+
+**Correction formula**:
+```
+F_corrected = F_raw - r * F_neuropil
+```
+
+| Parameter | Typical Value | Source |
+|-----------|---------------|--------|
+| Neuropil coefficient (r) | **0.7** (range: 0.5-0.8) | Chen et al., 2013 |
+| Neuropil annulus inner gap | 2 pixels from ROI border | Suite2P default |
+| Minimum neuropil pixels | 350 | Suite2P default |
+
+**Domain judgment**:
+- The coefficient r = 0.7 is an empirically derived average for 2P cortical imaging. It was estimated by measuring fluorescence in blood vessels (which should have zero true signal) relative to surrounding neuropil (Chen et al., 2013).
+- Suite2P estimates r iteratively together with spike deconvolution, minimizing the deconvolution residual. This data-driven approach is preferred over a fixed coefficient.
+- For 1P data, neuropil correction is handled differently: CNMF-E models the background as a low-rank spatiotemporal component rather than a per-ROI annulus (Zhou et al., 2018).
+- Over-subtraction (r too high) produces negative fluorescence values. If you see many negative dF/F values, reduce r.
+- For soma-targeted indicators (e.g., soma-GCaMP6f; Chen et al., 2020), neuropil contamination is reduced but not eliminated.
+
+### Step 4: dF/F Computation
+
+**Baseline estimation methods**:
+
+| Method | Description | Best For | Source |
+|--------|-------------|----------|--------|
+| Rolling percentile (8th) | 8th percentile over sliding window | Continuous recordings, moderate activity | Dombeck et al., 2007 |
+| Rolling percentile (10th-20th) | Higher percentile over sliding window | Lower activity preparations | Expert consensus |
+| Exponential fit | Fit decaying exponential to session | Strong photobleaching | Giovannucci et al., 2019 |
+| Mode of distribution | Histogram mode of fluorescence | Stable baseline, high frame rate | Peron et al., 2015 |
+
+**Formula**:
+```
+dF/F = (F(t) - F0) / F0
+```
+
+**Domain judgment**:
+- The sliding window for rolling percentile should be **30-60 seconds** to capture slow baseline fluctuations without tracking fast transients (expert consensus).
+- Using the mean as baseline inflates dF/F for highly active neurons. Use a low percentile (8th-10th) or the mode instead (Dombeck et al., 2007).
+- Photobleaching causes an exponential decay in baseline fluorescence. If uncorrected, early time points will have artificially low dF/F and late time points artificially high dF/F. Fit and subtract an exponential before computing dF/F (Giovannucci et al., 2019).
+
+### Step 5: Deconvolution / Spike Inference
+
+Deconvolution estimates the underlying spike train from the slow calcium fluorescence signal.
+
+| Algorithm | Type | Speed | Strengths | Source |
+|-----------|------|-------|-----------|--------|
+| OASIS | Model-based (AR) | Very fast (1 us/frame) | Online, warm-startable, scalable | Friedrich et al., 2017 |
+| FOOPSI | Model-based (L1) | Fast | Sparse, non-negative | Vogelstein et al., 2010 |
+| CASCADE | Deep learning | Moderate | Noise-adaptive, calibrated rates | Rupprecht et al., 2021 |
+| MLSpike | Bayesian | Slow | Principled uncertainty | Deneux et al., 2016 |
+
+**Critical**: The deconvolution kernel decay constant (tau) must match your calcium indicator. See `references/indicator-parameters.md` for the full table.
+
+| Indicator | tau (decay time) for deconvolution | Source |
+|-----------|------------------------------------|--------|
+| GCaMP6s | **~1.0-1.5 s** | Chen et al., 2013 |
+| GCaMP6f | **~0.4 s** | Chen et al., 2013 |
+| jGCaMP7f | **~0.3 s** | Dana et al., 2019 |
+| jGCaMP8f | **~0.2 s** | Zhang et al., 2023 |
+| jGCaMP8m | **~0.14 s** | Zhang et al., 2023 |
+| jGCaMP8s | **~0.2 s** | Zhang et al., 2023 |
+
+**Domain judgment**:
+- If tau is wrong, deconvolution is systematically biased. Too long produces sluggish traces; too short produces overshoot artifacts.
+- The kernel is fixed to tau in Suite2P; it is not fit to the data. Always verify your indicator and set tau explicitly.
+- Do NOT threshold deconvolved events to create binary spike trains. This discards magnitude information: a 1-spike event and a 10-spike burst become identical (Pachitariu et al., 2017).
+- Deconvolved amplitudes are in arbitrary units. There is an unknown scaling factor between fluorescence and spike count. Do not interpret amplitudes as absolute firing rates.
+- CASCADE (Rupprecht et al., 2021) can produce calibrated spike rate estimates by resampling ground truth data to match your recording's noise level, but still has systematic errors at low SNR.
+
+### Step 6: Quality Metrics for ROI Acceptance
+
+| Metric | Criterion | Rationale | Source |
+|--------|-----------|-----------|--------|
+| SNR (peak transient / noise SD) | > **3** | Below this, transients are indistinguishable from noise | Giovannucci et al., 2019 |
+| Skewness of dF/F trace | > **0.5** | Real calcium transients produce right-skewed distributions; noise is symmetric | Suite2P classifier |
+| Spatial footprint compactness | Compact, soma-shaped | Diffuse or fragmented footprints indicate neuropil or artifacts | Giovannucci et al., 2019 |
+| Spatial-temporal CNN score | > **0.5** (CaImAn) | Learned classifier combining shape and activity | Giovannucci et al., 2019 |
+
+**Domain judgment**:
+- SNR varies dramatically with indicator brightness, expression level, and imaging depth. An SNR of 3 is a minimum; SNR > 5 is preferred for reliable spike inference.
+- Skewness exploits the biophysics: calcium transients have fast rise and slow decay, producing a positively skewed fluorescence distribution. Gaussian noise has skewness near zero.
+- Always examine the spatial footprint. A valid somatic ROI should be roughly circular (10-20 um diameter in cortex). Elongated or multi-lobed footprints often indicate dendrites, overlapping cells, or motion artifacts.
+
+## Common Pitfalls
+
+1. **Wrong tau for your indicator**: Using GCaMP6s parameters for GCaMP6f data (or vice versa) produces incorrect deconvolution. Always check which indicator was used.
+
+2. **Skipping neuropil correction**: Without subtracting r * F_neuropil, apparent correlations between nearby neurons will be inflated by shared neuropil signal. This is the most common error in published calcium imaging analyses.
+
+3. **Using standard CNMF for 1P data**: One-photon microscopy has large, spatially structured background fluorescence from out-of-focus tissue. Standard CNMF assumes a sparse background and will fail. Use CNMF-E or MIN1PIPE.
+
+4. **Ignoring photobleaching**: GECIs photobleach over minutes to hours. Uncorrected bleaching creates a downward trend that biases dF/F computation and can mask late-session activity.
+
+5. **Motion artifacts in awake animals**: Residual motion after correction creates false transients synchronized across neurons (they all move together). Check for correlated artifacts by examining the relationship between motion metrics and neural activity.
+
+6. **Indicator saturation at high firing rates**: GECIs have a limited dynamic range. At high firing rates (> 10-20 Hz for GCaMP6s, > 50 Hz for GCaMP8f), the fluorescence signal saturates and underestimates true activity (Chen et al., 2013). Faster indicators saturate at higher rates.
+
+7. **Over-aggressive neuropil subtraction**: Setting r too high produces negative fluorescence, especially with bright indicators. Negative dF/F values that exceed noise levels indicate over-subtraction.
+
+8. **Interpreting deconvolved amplitudes as spike counts**: The mapping from fluorescence to spike number is nonlinear and depends on indicator expression level, baseline calcium, and imaging conditions. Treat deconvolved traces as relative activity measures.
+
+## Minimum Reporting Checklist
+
+Based on community standards (Giovannucci et al., 2019; Pachitariu et al., 2017):
+
+- [ ] Calcium indicator used (name and version, e.g., GCaMP6f, jGCaMP8s)
+- [ ] Imaging modality and frame rate (e.g., 2P at 30 Hz, 1P miniscope at 20 Hz)
+- [ ] Motion correction method (rigid/non-rigid) and software version
+- [ ] ROI detection method and key parameters (cell diameter, threshold)
+- [ ] Number of ROIs detected and accepted after curation
+- [ ] Neuropil correction method and coefficient used
+- [ ] dF/F baseline estimation method and window
+- [ ] Deconvolution algorithm and tau value used
+- [ ] Quality metrics and acceptance thresholds (SNR, skewness)
+- [ ] Number of sessions, animals, and total neurons in final dataset
+
+## Key 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.
+- Dana, H., et al. (2019). High-performance calcium sensors for imaging activity in neuronal populations and microcompartments. *Nature Methods*, 16, 649-657.
+- Deneux, T., et al. (2016). Accurate spike estimation from noisy calcium signals via supervised learning. *Nature Communications*, 7, 12190.
+- Dombeck, D. A., et al. (2007). Imaging large-scale neural activity with cellular resolution in awake, mobile mice. *Neuron*, 56(1), 43-57.
+- Friedrich, J., Zhou, P., & Paninski, L. (2017). Fast online deconvolution of calcium imaging data. *PLOS Computational Biology*, 13(3), e1005423.
+- 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.
+- Peron, S. P., et al. (2015). A cellular resolution map of barrel cortex activity during tactile behavior. *Neuron*, 86(3), 783-799.
+- 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 of calcium imaging data. *Journal of Neuroscience Methods*, 291, 83-94.
+- Rupprecht, P., et al. (2021). A database and deep learning toolbox for noise-optimized, generalized spike inference from calcium imaging. *Nature Neuroscience*, 24, 1324-1337.
+- Stringer, C., et al. (2021). Cellpose: a generalist algorithm for cellular segmentation. *Nature Methods*, 18, 100-106.
+- Vogelstein, J. T., et al. (2010). Fast nonnegative deconvolution for spike train inference from population calcium imaging. *Journal of Neurophysiology*, 104(6), 3691-3704.
+- Zhang, Y., et al. (2023). Fast and sensitive GCaMP calcium indicators for imaging neural populations. *Nature*, 615, 884-891.
+- Zhou, P., et al. (2018). Efficient and accurate extraction of in vivo calcium signals from microendoscopic video data. *eLife*, 7, e28728.
+
+See `references/pipeline-details.md` for tool comparisons and `references/indicator-parameters.md` for indicator kinetics tables.

package/skills/09_Cellular_Molecular_Neuroscience/calcium-imaging-analysis-guide/references/indicator-parameters.md

@@ -0,0 +1,242 @@
+# Indicator Parameters: Calcium Indicator Properties and Analysis Implications
+
+## Genetically Encoded Calcium Indicator (GECI) Kinetics
+
+### GCaMP Family Overview
+
+The GCaMP family of genetically encoded calcium indicators is the most widely used class of GECIs in neuroscience. Each generation has improved sensitivity and/or kinetics, with direct implications for analysis pipeline configuration.
+
+**Key principle**: Faster indicators allow resolving higher firing rates but may have lower sensitivity (smaller dF/F per spike). Slower indicators integrate more spikes, producing larger signals but poorer temporal resolution. This tradeoff was largely resolved with the jGCaMP8 family (Zhang et al., 2023).
+
+### Kinetics Table: In Vivo Measurements
+
+All values are for single action potential responses unless otherwise noted. In vivo values are reported where available, as in vitro kinetics are typically faster.
+
+#### GCaMP6 Family (Chen et al., 2013)
+
+| Indicator | Half-Rise Time (ms) | Half-Decay Time (ms) | dF/F per 1 AP (%) | Kd (nM) | Source |
+|-----------|---------------------|-----------------------|--------------------|---------|--------|
+| GCaMP6s | ~180 | ~550-600 | ~24 | ~144 | Chen et al., 2013 |
+| GCaMP6m | ~80 | ~270 | ~15 | ~167 | Chen et al., 2013 |
+| GCaMP6f | ~45 | ~140-200 | ~12 | ~375 | Chen et al., 2013 |
+
+**Deconvolution tau recommendations for GCaMP6**:
+- GCaMP6s: **tau = 1.0-1.5 s** (Suite2P default uses 1.0 s)
+- GCaMP6m: **tau = 0.5-0.7 s**
+- GCaMP6f: **tau = 0.3-0.4 s**
+
+Note: The half-decay time and the exponential decay constant (tau) used for deconvolution are related but not identical. The half-decay time is t_1/2 = tau * ln(2). Suite2P uses tau as the exponential time constant. The values above account for this conversion and empirical tuning.
+
+#### jGCaMP7 Family (Dana et al., 2019)
+
+| Indicator | Half-Rise Time (ms) | Half-Decay Time (ms) | dF/F per 1 AP (%) | Kd (nM) | Source |
+|-----------|---------------------|-----------------------|--------------------|---------|--------|
+| jGCaMP7s | ~200 | ~600 | ~42 | ~68 | Dana et al., 2019 |
+| jGCaMP7f | ~25-30 | ~270-280 | ~18 | ~174 | Dana et al., 2019 |
+| jGCaMP7b | ~20 | ~120 | ~7 | ~82 | Dana et al., 2019 |
+| jGCaMP7c | ~25 | ~250 | ~12 | ~298 | Dana et al., 2019 |
+
+**Deconvolution tau recommendations for jGCaMP7**:
+- jGCaMP7s: **tau = 1.0-1.5 s**
+- jGCaMP7f: **tau = 0.3-0.4 s**
+- jGCaMP7b: **tau = 0.15-0.2 s**
+- jGCaMP7c: **tau = 0.3-0.4 s**
+
+#### jGCaMP8 Family (Zhang et al., 2023)
+
+Measured in vivo in Drosophila L2 neurons:
+
+| Indicator | Half-Rise Time (ms) | Half-Decay Time (ms) | dF/F per 1 AP (%) | Source |
+|-----------|---------------------|-----------------------|--------------------|--------|
+| jGCaMP8s | ~80 | ~198 | ~38 | Zhang et al., 2023 |
+| jGCaMP8m | ~58 | ~137 | ~34 | Zhang et al., 2023 |
+| jGCaMP8f | ~76 | ~192 | ~24 | Zhang et al., 2023 |
+
+**Deconvolution tau recommendations for jGCaMP8**:
+- jGCaMP8s: **tau = 0.2-0.3 s**
+- jGCaMP8m: **tau = 0.14-0.2 s**
+- jGCaMP8f: **tau = 0.2-0.3 s**
+
+Note: jGCaMP8 kinetics measured in Drosophila may differ from mouse cortical neurons. Verify with pilot data when possible. In mouse V1, preliminary data suggest similar trends with slightly longer time constants due to calcium buffering differences.
+
+### Cross-Generation Comparison: Speed vs. Sensitivity
+
+| Indicator | Relative Speed | Relative Sensitivity (1 AP) | Best Use Case |
+|-----------|---------------|------------------------------|---------------|
+| GCaMP6s | Slowest | High | Low-firing populations, dendrites |
+| GCaMP6f | Moderate | Moderate | General purpose 2P |
+| jGCaMP7f | Moderate-Fast | High | General purpose, improved over 6f |
+| jGCaMP7s | Slow | Highest (GCaMP7 family) | Maximum sensitivity needed |
+| jGCaMP8s | Fast | Very high | High sensitivity + speed |
+| jGCaMP8m | Fastest | Very high | Fast-spiking neurons, burst detection |
+| jGCaMP8f | Fast | High | General purpose, best kinetics/sensitivity balance |
+
+## Choosing an Indicator Based on Expected Firing Rate
+
+The temporal resolution of calcium imaging is fundamentally limited by indicator kinetics. The maximum resolvable firing rate depends on the indicator's decay time.
+
+### Firing Rate Resolution Limits
+
+| Indicator | Approximate Max Resolvable Rate | Rationale | Source |
+|-----------|---------------------------------|-----------|--------|
+| GCaMP6s | **~2-3 Hz** | Consecutive transients merge above ~2 Hz | Chen et al., 2013 |
+| GCaMP6f | **~5-10 Hz** | Resolution interval ~50-75 ms | Chen et al., 2013 |
+| jGCaMP7f | **~5-10 Hz** | Similar decay to GCaMP6f but higher sensitivity | Dana et al., 2019 |
+| jGCaMP8m | **~15-30 Hz** | Fastest decay in the family | Zhang et al., 2023 |
+| jGCaMP8f | **~10-20 Hz** | Good balance for most applications | Zhang et al., 2023 |
+
+**Domain judgment for indicator choice**:
+- **Cortical pyramidal neurons** (typical firing rate 0.1-10 Hz): GCaMP6f, jGCaMP7f, or jGCaMP8f are all suitable
+- **Fast-spiking interneurons** (10-100 Hz): jGCaMP8m preferred; GCaMP6s will severely underestimate activity due to saturation
+- **Cerebellar Purkinje cells** (simple spikes ~50-100 Hz): Standard GECIs cannot resolve individual simple spikes; complex spikes (~1 Hz) are resolvable with GCaMP6f or faster
+- **Hippocampal place cells** (burst firing, 5-20 Hz within field): jGCaMP7f or jGCaMP8f recommended
+- **Dopamine neurons** (tonic ~5 Hz, burst ~20 Hz): jGCaMP8f for distinguishing burst from tonic
+- **Dendrites and spines** (local calcium signals): GCaMP6s or jGCaMP7s preferred for maximum sensitivity at low amplitudes
+
+### Saturation Effects
+
+All GECIs have a finite dynamic range (F_max / F_min) that causes fluorescence to saturate at high calcium concentrations.
+
+| Indicator | Dynamic Range (F_max/F_min) | Approximate Saturation Onset | Source |
+|-----------|----------------------------|------------------------------|--------|
+| GCaMP6s | ~63 | ~10-20 spikes in burst | Chen et al., 2013 |
+| GCaMP6f | ~52 | ~20-30 spikes in burst | Chen et al., 2013 |
+| jGCaMP7f | ~40 | ~15-25 spikes in burst | Dana et al., 2019 |
+| jGCaMP8f | ~83 | ~30+ spikes in burst | Zhang et al., 2023 |
+
+**Implication for analysis**: When fluorescence approaches saturation, the relationship between firing rate and dF/F becomes sublinear. Deconvolution algorithms that assume a linear model will underestimate spike counts during high-frequency bursts. This is a fundamental biophysical limit, not an algorithmic failure.
+
+## Red Calcium Indicators
+
+For experiments requiring a second color channel (e.g., dual-population imaging or co-expression with green optogenetic actuators):
+
+| Indicator | Half-Decay (ms) | dF/F per 1 AP (%) | Excitation (nm) | Emission (nm) | Source |
+|-----------|-----------------|--------------------|-----------------|--------------------|--------|
+| jRGECO1a | ~350 | ~12 | 560 | 590 | Dana et al., 2016 |
+| jRCaMP1a | ~500 | ~5 | 560 | 590 | Dana et al., 2016 |
+| jRCaMP1b | ~350 | ~8 | 560 | 590 | Dana et al., 2016 |
+
+**Warning**: Red indicators are generally dimmer and less sensitive than green GCaMPs. Analysis requires adjusted SNR thresholds and more conservative deconvolution.
+
+## Expression Systems
+
+### AAV Serotype Selection
+
+The choice of AAV serotype determines which cell types and brain regions are effectively transduced.
+
+| Serotype | Brain Tropism | Cell Preference | Notes | Source |
+|----------|---------------|-----------------|-------|--------|
+| AAV1 | Broad, cortex-preferred | Neurons (strong) | High transduction efficiency; first approved for gene therapy | Aschauer et al., 2013 |
+| AAV2 | Moderate, localized | Neurons | Smaller spread from injection site; retrograde with AAV2-retro | Aschauer et al., 2013 |
+| AAV5 | Broad | Astrocytes preferred, also neurons | Best for glial targeting | Aschauer et al., 2013 |
+| AAV8 | Broad | Neurons and astrocytes | Good for deep structures | Aschauer et al., 2013 |
+| AAV9 | Very broad, crosses BBB | Neurons, some glia | Can be delivered IV in neonates | Aschauer et al., 2013 |
+| PHP.eB | CNS-wide (IV delivery) | Neurons (strong) | Engineered for systemic delivery in mice; tropism is strain-dependent (C57BL/6 best) | Chan et al., 2017 |
+| AAV2-retro | Retrograde from terminals | Projection neurons | Inject at projection target to label cell bodies in source region | Tervo et al., 2016 |
+
+**Critical notes**:
+- Tropism varies between species and even mouse strains. PHP.eB works well in C57BL/6 but poorly in BALB/c mice (Hordeaux et al., 2018).
+- Always validate expression pattern in your specific preparation before running experiments.
+- Higher viral titers produce brighter expression but risk cytotoxicity and nuclear GCaMP accumulation (overexpression toxicity; see below).
+
+### Promoter Selection
+
+| Promoter | Expression Pattern | Strength | Use Case | Source |
+|----------|-------------------|----------|----------|--------|
+| CaMKIIa | Excitatory neurons | Moderate | Standard for cortical/hippocampal pyramidal cells | Dittgen et al., 2004 |
+| Synapsin (hSyn) | Pan-neuronal | Strong | All neurons; most common for calcium imaging | Kugler et al., 2003 |
+| CAG | Ubiquitous | Very strong | Maximum brightness; includes glia with non-neuronal AAVs | Niwa et al., 1991 |
+| EF1a | Ubiquitous | Strong | Common alternative to CAG | Kim et al., 1990 |
+| mDlx | GABAergic interneurons | Moderate | Inhibitory neuron-specific imaging | Dimidschstein et al., 2016 |
+| GFAP | Astrocytes | Moderate | Astrocyte calcium imaging | Lee et al., 2008 |
+
+### Cre-Dependent Expression Strategies
+
+For cell-type-specific expression, Cre-dependent constructs are used in Cre driver lines:
+
+- **DIO (Double-floxed Inverted Open reading frame)**: Inverted GCaMP is flipped into sense orientation only in Cre-expressing cells
+- **FLEX**: Similar double-floxed strategy; most common
+- **Advantage**: Sparse, cell-type-specific labeling reduces neuropil contamination and simplifies ROI detection
+- **Disadvantage**: Expression level depends on Cre driver line activity and AAV titer
+
+### Transgenic Mouse Lines
+
+| Line | Indicator | Expression | Notes | Source |
+|------|-----------|------------|-------|--------|
+| Ai93 (TITL-GCaMP6f) | GCaMP6f | Cre-dependent, tTA-dependent | Requires both Cre and tTA drivers; widely used in Allen Brain Observatory | Madisen et al., 2015 |
+| Ai94 (TITL-GCaMP6s) | GCaMP6s | Cre-dependent, tTA-dependent | Slower but more sensitive than Ai93 | Madisen et al., 2015 |
+| Ai148 (TIT2L-GC6f-ICL-tTA2) | GCaMP6f | Cre-dependent, self-amplifying | Brighter than Ai93; standard for Allen Institute | Daigle et al., 2018 |
+| Thy1-GCaMP6 | GCaMP6s/f | Sparse, layer 5 pyramidal | No Cre required; variable expression across founders | Dana et al., 2014 |
+| CaMPARI | Photoconvertible | Activity-dependent, all-optical | Converts green-to-red upon simultaneous calcium and UV light | Fosque et al., 2015 |
+
+**Domain judgment on expression method**:
+- Viral expression (AAV) takes 2-4 weeks to reach stable levels. Imaging too early produces dim signals; too late risks overexpression toxicity.
+- Transgenic lines provide more uniform expression but may have lower signal amplitude than high-titer AAV.
+- Overexpression toxicity: chronically high GCaMP levels can cause nuclear filling (GCaMP enters the nucleus), altered calcium buffering, and abnormal neural activity. Signs include: bright fluorescence with no transients, nuclear fluorescence visible, and abnormally high baseline fluorescence (Chen et al., 2013; Daigle et al., 2018).
+
+## Indicator-Specific Analysis Implications
+
+### GCaMP6s
+- **Deconvolution**: Tau = 1.0-1.5 s. Deconvolution strongly recommended because raw traces are very slow.
+- **Baseline window**: Use longer sliding window (60-90 s) because transients are prolonged and a short window tracks them.
+- **Neuropil correction**: Standard r = 0.7 works well. High sensitivity means transients are usually distinguishable from neuropil.
+- **Spike inference quality**: Good for low-rate neurons (< 3 Hz). Above ~5 Hz, individual spikes merge into plateau.
+
+### GCaMP6f
+- **Deconvolution**: Tau = 0.3-0.4 s. Most common choice for general-purpose 2P.
+- **Baseline window**: 30-60 s sliding window is appropriate.
+- **Neuropil correction**: Standard r = 0.7. Lower SNR per spike than GCaMP6s means neuropil correction is more critical.
+- **Spike inference quality**: Resolves spikes up to ~10 Hz. Standard workhorse indicator.
+
+### jGCaMP7f
+- **Deconvolution**: Tau = 0.3-0.4 s (similar to GCaMP6f decay but higher amplitude).
+- **Baseline window**: 30-60 s.
+- **Neuropil correction**: Brighter than GCaMP6f; over-subtraction risk is higher. Consider starting with r = 0.6 and adjusting.
+- **Spike inference quality**: Better single-spike detection than GCaMP6f due to higher dF/F.
+
+### jGCaMP8f
+- **Deconvolution**: Tau = 0.2-0.3 s. Fastest widely available indicator.
+- **Baseline window**: 20-40 s may be sufficient due to faster kinetics.
+- **Neuropil correction**: Very bright; monitor for over-subtraction artifacts.
+- **Spike inference quality**: Best temporal resolution in the family. Can resolve bursts up to ~20 Hz.
+- **Note**: Ground truth data for jGCaMP8 deconvolution is still being accumulated (as of 2025). CASCADE has begun incorporating jGCaMP8 ground truth (Rupprecht et al., 2025 preprint).
+
+### jGCaMP8m
+- **Deconvolution**: Tau = 0.14-0.2 s. The fastest variant.
+- **Frame rate requirement**: Benefits from higher frame rates (> 20 Hz) to capture fast dynamics.
+- **Best for**: Fast-spiking interneurons, cerebellar granule cells, any application where temporal precision matters most.
+
+### jGCaMP8s
+- **Deconvolution**: Tau = 0.2-0.3 s.
+- **Analysis advantage**: Combines good sensitivity with improved kinetics over GCaMP6s.
+- **Best for**: Replacing GCaMP6s in experiments where both sensitivity and speed matter.
+
+## Wavelength and Optical Parameters
+
+| Parameter | Green GCaMP | Red jRGECO1a | Source |
+|-----------|-------------|--------------|--------|
+| Excitation peak (1P) | 488 nm | 560 nm | Manufacturer data |
+| Excitation peak (2P) | 920-940 nm | 1000-1040 nm | Dana et al., 2016 |
+| Isosbestic point | 405-415 nm | ~530 nm | Lerner et al., 2015 |
+| Emission peak | 510 nm | 590 nm | Manufacturer data |
+| Emission filter | 500-550 nm BP | 570-640 nm BP | Common configurations |
+
+## References
+
+- Aschauer, D. F., et al. (2013). Analysis of transduction efficiency, tropism and axonal transport of AAV serotypes 1, 2, 5, 6, 8 and 9 in the mouse brain. *PLoS ONE*, 8(9), e76310.
+- Chan, K. Y., et al. (2017). Engineered AAVs for efficient noninvasive gene delivery to the central and peripheral nervous systems. *Nature Neuroscience*, 20(8), 1172-1179.
+- 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.
+- Daigle, T. L., et al. (2018). A suite of transgenic driver and reporter mouse lines with enhanced brain-cell-type targeting and functionality. *Cell*, 174(2), 465-480.
+- Dana, H., et al. (2014). Thy1-GCaMP6 transgenic mice for neuronal population imaging in vivo. *PLoS ONE*, 9(9), e108697.
+- Dana, H., et al. (2016). Sensitive red protein calcium indicators for imaging neural activity. *eLife*, 5, e12727.
+- Dana, H., et al. (2019). High-performance calcium sensors for imaging activity in neuronal populations and microcompartments. *Nature Methods*, 16, 649-657.
+- Dimidschstein, J., et al. (2016). A viral strategy for targeting and manipulating interneurons across vertebrate species. *Nature Neuroscience*, 19(12), 1743-1749.
+- Dittgen, T., et al. (2004). Lentivirus-based genetic manipulations of cortical neurons and their optical and electrophysiological monitoring in vivo. *Proceedings of the National Academy of Sciences*, 101(52), 18206-18211.
+- Fosque, B. F., et al. (2015). Neural circuits. Labeling of active neural circuits in vivo with designed calcium integrators. *Science*, 347(6223), 755-760.
+- Hordeaux, J., et al. (2018). The neurotropic properties of AAV-PHP.B are limited to C57BL/6J mice. *Molecular Therapy*, 26(3), 664-668.
+- Kugler, S., et al. (2003). Human synapsin 1 gene promoter confers highly neuron-specific long-term transgene expression from an adenoviral vector in the adult rat brain. *Gene Therapy*, 10(4), 337-347.
+- Madisen, L., et al. (2015). Transgenic mice for intersectional targeting of neural sensors and effectors with high specificity and performance. *Neuron*, 85(5), 942-958.
+- Rupprecht, P., et al. (2021). A database and deep learning toolbox for noise-optimized, generalized spike inference from calcium imaging. *Nature Neuroscience*, 24, 1324-1337.
+- Tervo, D. G. R., et al. (2016). A designer AAV variant permits efficient retrograde access to projection neurons. *Neuron*, 92(2), 372-382.
+- Zhang, Y., et al. (2023). Fast and sensitive GCaMP calcium indicators for imaging neural populations. *Nature*, 615, 884-891.