@brainpilot/skills 0.0.6

package/skills/03_Cognitive_Psychology/signal-detection-analysis/references/sdt-formulas.md

@@ -0,0 +1,318 @@
+# SDT Formulas and Computational Details
+
+This reference file supplements the main `SKILL.md` with detailed mathematical formulas, lookup tables, correction methods, and computational procedures for Signal Detection Theory analysis.
+
+## 1. Core Formulas by Paradigm
+
+### 1.1 Yes/No (Single-Interval) Design
+
+**Equal-variance Gaussian model** (Green & Swets, 1966, Ch. 1):
+
+```
+d' = z(H) - z(FA)
+c = -0.5 * [z(H) + z(FA)]
+ln(beta) = d' * c
+beta = exp(d' * c)
+c' = c / d'
+```
+
+Where:
+- H = hit rate = P("yes" | signal)
+- FA = false alarm rate = P("yes" | noise)
+- z() = inverse of the standard normal cumulative distribution function (probit transform)
+
+### 1.2 Two-Alternative Forced Choice (2AFC / 2IFC)
+
+**Standard formula** (Green & Swets, 1966, Ch. 6; Macmillan & Creelman, 2005, Ch. 5):
+
+```
+d'(2AFC) = z(PC) * sqrt(2)
+```
+
+Where PC = proportion correct across all trials.
+
+**Relationship to yes/no d'**:
+
+```
+d'(2AFC) = d'(yes/no) * sqrt(2)
+```
+
+This means that for the same underlying sensitivity, 2AFC yields a d' that is sqrt(2) times larger than yes/no. This conversion factor arises because the 2AFC observer effectively takes two independent samples and compares them (Green & Swets, 1966, Ch. 6).
+
+**No independent bias measure** is available in 2AFC because the observer only indicates which interval contained the signal, not whether a signal was present.
+
+### 1.3 Same-Different Paradigm
+
+Two models describe observer strategy (Macmillan & Creelman, 2005, Ch. 6):
+
+**Independent observations model** (used when stimuli are from a fixed, small set):
+
+The observer independently classifies each stimulus and responds "same" if both classifications agree. Hit rate (P("different" | different pair)) and false alarm rate (P("different" | same pair)) are used. d' is obtained from lookup tables (Macmillan & Creelman, 2005, Table A5.3) or numerically because there is no closed-form solution.
+
+**Differencing model** (used when stimuli vary along a continuum / roving design):
+
+The observer computes the perceived difference between stimuli and responds "different" if the difference exceeds a criterion. d' is again obtained via lookup tables (Macmillan & Creelman, 2005, Table A5.4) or numerical computation.
+
+For the differencing model, the relationship between d' and the hit/FA rates involves the non-central chi-squared distribution and requires iterative numerical methods. Software implementations (e.g., R package `psyphy`, Macmillan's `d'plus` program) handle this automatically.
+
+### 1.4 ABX Paradigm
+
+Two stimuli A and B are presented, followed by X (which equals A or B). The observer identifies X. As with same-different, two observer models exist (Macmillan & Creelman, 2005, Ch. 6):
+
+**Independent observations model**:
+
+```
+d'(ABX) = z(H) - z(FA)
+```
+
+where H = P(correct | X = A) and FA = P(incorrect | X = B), or equivalently using the proportion correct with appropriate lookup tables (Macmillan & Creelman, 2005, Table A5.5).
+
+**Differencing model** (default assumption for roving designs):
+
+d' is obtained from proportion correct via lookup tables (Macmillan & Creelman, 2005, Table A5.6). There is no closed-form solution; numerical methods or published tables are required.
+
+### 1.5 Oddity (3AFC-Odd)
+
+Three stimuli are presented (two identical, one different); the observer identifies the odd one. For the differencing model (Macmillan & Creelman, 2005, Ch. 7):
+
+```
+d'(oddity) is obtained from P(correct) via Table A5.7
+```
+
+General relationship: d'(oddity) is smaller than d'(2AFC) for the same proportion correct because the task is inherently harder (Macmillan & Creelman, 2005, Ch. 7).
+
+## 2. Correction Methods for Extreme Proportions
+
+### 2.1 The 1/(2N) Rule (Macmillan & Kaplan, 1985)
+
+Applied only to extreme values (0 or 1):
+
+```
+If H = 0: H_corrected = 0.5 / N_signal
+If H = 1: H_corrected = (N_signal - 0.5) / N_signal
+If FA = 0: FA_corrected = 0.5 / N_noise
+If FA = 1: FA_corrected = (N_noise - 0.5) / N_noise
+```
+
+Where N_signal = number of signal trials, N_noise = number of noise trials.
+
+**Limitations**: Can either overestimate or underestimate true d'; applied asymmetrically (only to extreme cells), which introduces inconsistency (Hautus, 1995).
+
+### 2.2 The Log-Linear Rule (Hautus, 1995) -- Recommended
+
+Applied to all cells unconditionally:
+
+```
+H_corrected = (hits + 0.5) / (N_signal + 1)
+FA_corrected = (false_alarms + 0.5) / (N_noise + 1)
+```
+
+Equivalently, add 0.5 to each cell of the 2x2 matrix:
+
+```
+hits_adj = hits + 0.5
+misses_adj = misses + 0.5
+fa_adj = false_alarms + 0.5
+cr_adj = correct_rejections + 0.5
+
+H_corrected = hits_adj / (hits_adj + misses_adj)
+FA_corrected = fa_adj / (fa_adj + cr_adj)
+```
+
+**Properties** (Hautus, 1995):
+- Always underestimates true d' (provides a conservative lower bound)
+- Less biased than the 1/(2N) rule across all parameter combinations tested
+- Converges to the uncorrected value as N increases
+- Should be applied **uniformly** to all participants/conditions for consistency, not only when extremes are present
+
+### 2.3 Worked Example
+
+Suppose an observer has 50 signal trials and 50 noise trials:
+- Hits = 50, Misses = 0 (H = 1.0)
+- False Alarms = 5, Correct Rejections = 45 (FA = 0.10)
+
+Without correction: d' = z(1.0) - z(0.10) = infinity - (-1.28) = undefined
+
+**1/(2N) correction**:
+- H_corrected = (50 - 0.5) / 50 = 0.99
+- FA remains 0.10
+- d' = z(0.99) - z(0.10) = 2.33 - (-1.28) = 3.61
+
+**Log-linear correction** (applied to all cells):
+- H_corrected = 50.5 / 51 = 0.990
+- FA_corrected = 5.5 / 51 = 0.108
+- d' = z(0.990) - z(0.108) = 2.33 - (-1.24) = 3.57
+
+## 3. ROC Analysis
+
+### 3.1 Constructing an ROC Curve
+
+**From rating data**: If observers use a K-point confidence scale, each scale boundary yields a different (H, FA) pair. With K rating categories, you obtain K-1 ROC points.
+
+Procedure (Macmillan & Creelman, 2005, Ch. 3):
+
+1. For each criterion k (from most conservative to most liberal):
+ - H(k) = P(rating >= k | signal)
+ - FA(k) = P(rating >= k | noise)
+2. Plot FA(k) on x-axis, H(k) on y-axis
+3. Add the points (0, 0) and (1, 1) as anchors
+4. The resulting curve bows above the diagonal for above-chance performance
+
+### 3.2 Computing Az (Area Under the ROC)
+
+**Parametric estimate** (assuming Gaussian distributions; Swets, 1986):
+
+```
+Az = Phi(da / sqrt(2))
+```
+
+Where Phi() is the standard normal CDF and da is the sensitivity index from the fitted model.
+
+For the equal-variance model (slope = 1):
+
+```
+Az = Phi(d' / sqrt(2))
+```
+
+**Nonparametric estimate** (trapezoidal rule):
+
+```
+Az_nonpar = sum over k of: 0.5 * (H(k+1) - H(k)) * (FA(k) + FA(k+1))
+```
+
+This is equivalent to the Wilcoxon-Mann-Whitney statistic and makes no distributional assumptions.
+
+### 3.3 The zROC and Unequal Variance
+
+Plotting z(H) vs. z(FA) yields the zROC. Under the equal-variance Gaussian model, this is a straight line with slope = 1 and intercept = d'.
+
+Under the **unequal-variance model** (Macmillan & Creelman, 2005, Ch. 3):
+
+```
+zROC: z(H) = (1/s) * z(FA) + d_a / s
+```
+
+Where:
+- s = sigma_noise / sigma_signal (ratio of standard deviations)
+- The zROC slope = 1/s
+- If slope < 1: signal distribution has greater variance (common in recognition memory)
+
+**Typical finding in recognition memory**: zROC slope ~ **0.80** (i.e., s ~ 0.80, meaning sigma_target / sigma_lure ~ 1.25; Ratcliff, Sheu, & Gronlund, 1992; Mickes, Wixted, & Wais, 2007).
+
+### 3.4 Unequal-Variance Sensitivity: da
+
+When variances are unequal, use da instead of d' (Macmillan & Creelman, 2005, Ch. 3):
+
+```
+da = sqrt(2 / (1 + s^2)) * [z(H) - s * z(FA)]
+```
+
+Where s = sigma_noise / sigma_signal (the zROC slope).
+
+When s = 1 (equal variance), da reduces to d'. When s != 1, da provides a **criterion-free** sensitivity measure that standard d' does not.
+
+## 4. Nonparametric Sensitivity Measures
+
+### 4.1 A' (A-prime)
+
+Originally proposed by Pollack & Norman (1964) as a nonparametric single-point sensitivity estimate.
+
+**Formula** (corrected version from Zhang & Mueller, 2005):
+
+```
+If H >= FA:
+ A' = 0.5 + [(H - FA) * (1 + H - FA)] / [4 * H * (1 - FA)]
+
+If FA > H:
+ A' = 0.5 - [(FA - H) * (1 + FA - H)] / [4 * FA * (1 - H)]
+```
+
+Range: 0.5 (chance) to 1.0 (perfect).
+
+**Caution**: Despite being called "nonparametric," A' implicitly assumes a specific (approximately logistic) distribution model (Macmillan & Creelman, 1996). It is less accurate than parametric measures when the underlying distributions are Gaussian (Macmillan & Creelman, 2005, Ch. 3). Use Az from ROC data when possible.
+
+### 4.2 B''_D (Nonparametric Bias)
+
+The commonly paired nonparametric bias measure (Donaldson, 1992):
+
+```
+B''_D = [(1 - H) * (1 - FA) - H * FA] / [(1 - H) * (1 - FA) + H * FA]
+```
+
+Range: -1 (extreme liberal) to +1 (extreme conservative). B''_D = 0 indicates no bias.
+
+## 5. Confidence Interval and Variance of d'
+
+### 5.1 Variance of d'
+
+The variance of d' can be approximated as (Gourevitch & Galanter, 1967; Macmillan & Creelman, 2005, Ch. 8):
+
+```
+Var(d') = [H*(1-H)] / [N_signal * phi(z(H))^2] + [FA*(1-FA)] / [N_noise * phi(z(FA))^2]
+```
+
+Where phi() is the standard normal probability density function.
+
+### 5.2 Approximate 95% Confidence Interval
+
+```
+d' +/- 1.96 * sqrt(Var(d'))
+```
+
+This approximation works well for moderate sample sizes (N > 20 per stimulus class) and non-extreme rates (Macmillan & Creelman, 2005, Ch. 8).
+
+## 6. Quick Reference: d' Lookup Table (Yes/No)
+
+Selected d' values for common (H, FA) combinations (computed from standard equal-variance model):
+
+| H \ FA | 0.01 | 0.05 | 0.10 | 0.20 | 0.30 | 0.50 |
+|--------|------|------|------|------|------|------|
+| 0.50 | 2.33 | 1.64 | 1.28 | 0.84 | 0.52 | 0.00 |
+| 0.60 | 2.58 | 1.90 | 1.53 | 1.10 | 0.78 | 0.25 |
+| 0.70 | 2.86 | 2.17 | 1.80 | 1.37 | 1.05 | 0.52 |
+| 0.80 | 3.17 | 2.48 | 2.12 | 1.68 | 1.37 | 0.84 |
+| 0.90 | 3.61 | 2.92 | 2.56 | 2.12 | 1.80 | 1.28 |
+| 0.95 | 3.97 | 3.29 | 2.92 | 2.48 | 2.17 | 1.64 |
+| 0.99 | 4.65 | 3.97 | 3.61 | 3.17 | 2.86 | 2.33 |
+
+## 7. Quick Reference: 2AFC Proportion Correct to d'
+
+| PC (2AFC) | d'(2AFC) |
+|-----------|----------|
+| 0.55 | 0.18 |
+| 0.60 | 0.36 |
+| 0.65 | 0.54 |
+| 0.70 | 0.74 |
+| 0.75 | 0.95 |
+| 0.80 | 1.19 |
+| 0.85 | 1.47 |
+| 0.90 | 1.81 |
+| 0.95 | 2.33 |
+
+(Values computed as z(PC) * sqrt(2); Macmillan & Creelman, 2005, Table A5.1)
+
+## 8. Software Implementations
+
+| Software | Language | Key Function / Package | Reference |
+|----------|----------|----------------------|-----------|
+| `psyphy` | R | `dprime.SD()`, `dprime.ABX()`, `dprime.oddity()` | Knoblauch, 2014 |
+| `psychopy` | Python | `data.sdt` module | Peirce et al., 2019 |
+| `scipy.stats` | Python | `norm.ppf()` for z-transforms (compute d' manually) | -- |
+| `d'plus` | Standalone | All paradigms, bias measures | Macmillan, 2007 |
+| `sensR` | R | `d.primeSS()`, `d.prime2AFC()`, `SDT()` | Brockhoff & Christensen, 2010 |
+| `MLE_metad` | MATLAB/Python | Type 2 SDT, meta-d' | Maniscalco & Lau, 2012 |
+
+## References
+
+- Donaldson, W. (1992). Measuring recognition memory. *Journal of Experimental Psychology: General*, 121, 275-277.
+- Gourevitch, V., & Galanter, E. (1967). A significance test for one parameter isosensitivity functions. *Psychometrika*, 32, 25-33.
+- Green, D. M., & Swets, J. A. (1966). *Signal detection theory and psychophysics*. New York: Wiley.
+- Hautus, M. J. (1995). Corrections for extreme proportions and their biasing effects on estimated values of d'. *Behavior Research Methods, Instruments, & Computers*, 27, 46-51.
+- Macmillan, N. A., & Creelman, C. D. (1996). Triangles in ROC space: History and theory of "nonparametric" measures of sensitivity and response bias. *Psychonomic Bulletin & Review*, 3, 164-170.
+- Macmillan, N. A., & Creelman, C. D. (2005). *Detection theory: A user's guide* (2nd ed.). Mahwah, NJ: Erlbaum.
+- Macmillan, N. A., & Kaplan, H. L. (1985). Detection theory analysis of group data. *Psychological Bulletin*, 98, 185-199.
+- Mickes, L., Wixted, J. T., & Wais, P. E. (2007). A direct test of the unequal-variance signal detection model of recognition memory. *Psychonomic Bulletin & Review*, 14, 858-865.
+- Pollack, I., & Norman, D. A. (1964). A nonparametric analysis of recognition experiments. *Psychonomic Science*, 1, 125-126.
+- Ratcliff, R., Sheu, C. F., & Gronlund, S. D. (1992). Testing global memory models using ROC curves. *Psychological Review*, 99, 518-535.
+- Swets, J. A. (1986). Indices of discrimination or diagnostic accuracy. *Psychological Bulletin*, 99, 100-117.
+- Zhang, J., & Mueller, S. T. (2005). A note on ROC analysis and non-parametric estimate of sensitivity. *Psychometrika*, 70, 203-212.

package/skills/03_Cognitive_Psychology/visual-search-array-generator/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: "visual-search-array-generator"
+description: "Specifies display parameters, set sizes, target-distractor similarity, and randomization constraints for visual search experiments"
+domain: "cognitive-psychology"
+version: "1.0.0"
+authors:
+ - "Claude (AI-assisted)"
+papers:
+ - "Treisman & Gelade, 1980"
+ - "Wolfe, 1994"
+ - "Wolfe, 2021"
+ - "Duncan & Humphreys, 1989"
+ - "Chun & Wolfe, 1996"
+dependencies:
+ required:
+ - research-literacy
+review_status: "ai-generated"
+---
+
+# Visual Search Array Generator
+
+## Purpose
+
+This skill encodes expert methodological knowledge for designing and generating visual search arrays. A competent programmer could easily generate random stimulus displays, but without domain training they would likely violate critical constraints: items too closely spaced (causing crowding), eccentricities beyond useful vision, inappropriate set sizes that cannot distinguish search types, target-distractor similarity levels that produce ceiling or floor effects, or trial ratios that distort search behavior. This skill provides the validated parameters needed to create psychophysically sound visual search experiments.
+
+## When to Use
+
+Use this skill when:
+
+- Designing a visual search experiment (feature search, conjunction search, spatial configuration search)
+- Generating stimulus arrays with specific set sizes, spacings, and feature dimensions
+- Selecting target-distractor similarity levels to manipulate search efficiency
+- Choosing set sizes and trial structure for measuring search slopes
+- Configuring display timing, inter-trial intervals, and response windows
+
+Do **not** use this skill when:
+
+- The task is not visual search (e.g., change detection, visual working memory, attentional capture without search)
+- You are analyzing existing visual search data rather than designing new experiments
+- The display involves naturalistic scenes rather than controlled arrays (use scene perception methods)
+
+## Research Planning Protocol
+
+Before executing the domain-specific steps below, you MUST:
+
+1. **State the research question** -- What specific question is this analysis/paradigm addressing?
+2. **Justify the method choice** -- Why is this approach appropriate? What alternatives were considered?
+3. **Declare expected outcomes** -- What results would support vs. refute the hypothesis?
+4. **Note assumptions and limitations** -- What does this method assume? 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).
+
+## Search Type Classification
+
+### Feature Search (Parallel / Pop-out)
+
+Target defined by a single unique feature (Treisman & Gelade, 1980).
+
+- **Search slope**: < **10 ms/item** for target-present trials (Wolfe, 2021)
+- **RT x set size function**: Flat or near-flat
+- **Example**: Red target among green distractors; vertical target among horizontal distractors
+- **Theoretical basis**: Pre-attentive feature maps can detect unique singletons without serial scanning (Treisman & Gelade, 1980)
+
+### Conjunction Search (Inefficient / Serial)
+
+Target defined by a combination of features shared individually with distractors (Treisman & Gelade, 1980).
+
+- **Search slope**: **20-30 ms/item** for target-present trials (Wolfe, 2021)
+- **Absent:present slope ratio**: Approximately **2:1** if search is self-terminating (Treisman & Gelade, 1980)
+- **Example**: Red vertical target among red horizontal and green vertical distractors
+- **Note**: Many conjunction searches are more efficient than predicted by strict serial models; guided search theory accounts for this (Wolfe, 1994)
+
+### Spatial Configuration Search
+
+Target differs from distractors in spatial arrangement of parts rather than simple features.
+
+- **Search slope**: **30-50+ ms/item** (Wolfe, 2021)
+- **Example**: T among Ls; 2 among 5s
+- **These are among the most inefficient search tasks** and should be used when studying attentional limits
+
+### Search Slope Classification Benchmarks
+
+| Slope (ms/item) | Classification | Citation |
+|-----------------|---------------|----------|
+| < **5** | Highly efficient / pop-out | Wolfe, 2021 |
+| **5-10** | Efficient (feature-like) | Wolfe, 2021 |
+| **10-20** | Moderately efficient (guided) | Wolfe, 1994; Wolfe, 2021 |
+| **20-30** | Inefficient (conjunction-like) | Treisman & Gelade, 1980; Wolfe, 2021 |
+| > **30** | Very inefficient (serial) | Wolfe, 2021 |
+
+## Display Parameters
+
+### Spatial Layout
+
+| Parameter | Recommended Value | Citation / Rationale |
+|-----------|------------------|---------------------|
+| **Maximum eccentricity** | **15 degrees** of visual angle from fixation | Beyond ~15 deg, acuity drops substantially; standard upper bound (Wolfe et al., 1998) |
+| **Minimum inter-item spacing** | > **1 degree** center-to-center | Prevents crowding effects (Bouma, 1970: crowding zone ~ 0.5 x eccentricity) |
+| **Item size** | **0.5-2 degrees** of visual angle | Standard range for search items (Wolfe, 2021) |
+| **Display area** | Circular or rectangular region within eccentricity limit | Avoid items near monitor edges where distortion may occur |
+| **Fixation cross** | Present for **500-1000 ms** before array onset | Standard in visual search (Wolfe et al., 1998) |
+
+### Preventing Crowding
+
+Crowding impairs identification when flanking items are too close to the target, especially in the periphery (Pelli & Tillman, 2008).
+
+- **Critical spacing**: Approximately **0.5 x eccentricity** (Bouma, 1970)
+- At **5 degrees** eccentricity, items must be > **2.5 degrees** apart to avoid crowding
+- At **10 degrees** eccentricity, items must be > **5 degrees** apart
+- For items near fixation (< 2 degrees), minimum spacing of **1 degree** is sufficient
+
+### Set Sizes
+
+| Design Goal | Recommended Set Sizes | Rationale |
+|-------------|----------------------|-----------|
+| **Classify search type** | **4, 8, 12, 16** (minimum 3 set sizes) | Need multiple points to estimate slope reliably (Wolfe, 2021) |
+| **Test for pop-out** | **8, 16, 32** (wide range) | Pop-out confirmed if slope ~ 0 even at large set sizes (Treisman & Gelade, 1980) |
+| **Standard conjunction search** | **4, 8, 12, 16, 20** | Finer-grained slope estimation (Wolfe, 1994) |
+| **Quick screening** | **6, 12, 18** | Three evenly spaced set sizes for slope estimation |
+
+**Minimum set sizes**: At least **3 different set sizes** are required to reliably estimate a search slope. Two set sizes cannot distinguish linear from nonlinear search functions.
+
+**Maximum set size**: Constrained by display density. With **1 degree minimum spacing** and **15 degree eccentricity limit**, the practical maximum is approximately **40-50 items** for typical item sizes (Wolfe et al., 1998).
+
+### Trial Structure
+
+| Parameter | Recommended Value | Citation |
+|-----------|------------------|----------|
+| **Target-present : target-absent ratio** | **1:1** (50% present) | Chun & Wolfe, 1996; standard in most search tasks |
+| **Low prevalence condition** | **10% target-present** | Wolfe et al., 2005 (miss rate increases dramatically) |
+| **Trials per cell** | Minimum **20-30** trials per set size x presence combination | Wolfe, 2021; more for stable RT distributions |
+| **Practice trials** | **10-20 trials** before data collection | Standard practice |
+| **Total trial count** | Typically **400-800** for a standard search task | Depends on number of conditions and set sizes |
+
+**Critical warning about target prevalence**: When target prevalence drops below ~25%, miss rates increase dramatically -- the "prevalence effect" (Wolfe et al., 2005). This is a critical design consideration for applied search tasks (e.g., medical image screening).
+
+### Timing Parameters
+
+| Parameter | Recommended Value | Rationale |
+|-----------|------------------|-----------|
+| **Fixation duration** | **500-1000 ms** | Allow fixation stabilization |
+| **Display duration** | Until response (standard) or fixed (brief search) | Self-paced search is default (Wolfe, 2021) |
+| **Brief display search** | **100-200 ms** (then mask) | Tests pre-attentive processing (Treisman & Gelade, 1980) |
+| **Response deadline** | **3000-5000 ms** | Exclude abnormally slow RTs |
+| **Inter-trial interval** | **500-1000 ms** | Prevent carryover effects |
+| **Feedback duration** | **500 ms** (if used) | Brief error/correct feedback |
+
+## Feature Dimensions and Similarity
+
+### Color
+
+| Parameter | Guideline | Citation |
+|-----------|-----------|----------|
+| **Feature search JND** | Target-distractor color difference > **30 degrees** in CIE L*a*b* or CIELUV hue angle for pop-out | Derived from Nagy & Sanchez, 1990 |
+| **Conjunction control** | Equate target-distractor color distance across conditions | Essential for isolating conjunction cost |
+| **Number of colors** | Typically **2-4** distinct colors for conjunction search | Wolfe, 1994 |
+| **Luminance** | Equate luminance across colors to avoid luminance pop-out | Use isoluminant colors or verify with photometer |
+| **Color space** | Specify in CIE L*a*b* or Munsell; avoid RGB for scientific reporting | RGB is device-dependent |
+
+### Orientation
+
+| Parameter | Guideline | Citation |
+|-----------|-----------|----------|
+| **Feature search JND** | Target-distractor difference > **15-20 degrees** for efficient search | Foster & Ward, 1991 |
+| **Pop-out threshold** | Orientation difference > **30 degrees** produces reliable pop-out | Wolfe et al., 1992 |
+| **Cardinal advantage** | Vertical and horizontal orientations are detected faster than obliques | Appelle, 1972 |
+| **Recommended**: Use oblique orientations (e.g., 45 deg, 135 deg) to avoid cardinal effects unless cardinals are of interest |
+
+### Size
+
+| Parameter | Guideline | Citation |
+|-----------|-----------|----------|
+| **Feature search JND** | Target at least **1.5-2x** distractor size for pop-out | Treisman & Gelade, 1980 |
+| **Weber fraction** | Size discrimination Weber fraction ~ **0.04-0.06** (JND/standard) | Nachmias, 2011 |
+| **For search**: Size ratio of > **1.5:1** (target:distractor) typically needed for efficient search | Wolfe, 2021 |
+
+## Target-Distractor Similarity and Distractor Heterogeneity
+
+### Duncan & Humphreys (1989) Framework
+
+Search efficiency depends on two factors:
+
+1. **Target-distractor (T-D) similarity**: Higher similarity = less efficient search
+2. **Distractor-distractor (D-D) similarity**: Lower D-D similarity (heterogeneous distractors) = less efficient search
+
+| T-D Similarity | D-D Similarity | Expected Search | Example |
+|---------------|---------------|-----------------|---------|
+| Low | High | Very efficient (pop-out) | Red among identical greens |
+| Low | Low | Efficient | Red among varied colors (not red) |
+| High | High | Inefficient | Pink among reds |
+| High | Low | Very inefficient | Pink among varied warm colors |
+
+### Practical Implementation
+
+- **Homogeneous distractors**: All distractors identical; cleanest test of T-D similarity
+- **Heterogeneous distractors**: Distractors vary in the search-relevant feature; tests the D-D similarity effect
+- **Controlling heterogeneity**: Sample distractor features from a uniform distribution within a defined range (e.g., orientation distractors drawn from 0 +/- 10 degrees; Duncan & Humphreys, 1989)
+
+## Array Generation Algorithm
+
+### Placement Algorithm (Recommended)
+
+1. Define the display region (circular with radius = max eccentricity)
+2. Generate candidate positions using one of:
+ - **Grid + jitter**: Place items on a regular grid, then add random jitter (uniform, +/- 0.3 deg) to break regularity (Wolfe et al., 1998)
+ - **Random placement with rejection**: Sample random positions; reject any that violate minimum spacing
+ - **Concentric rings**: Place items on concentric rings at fixed eccentricities (controls eccentricity distribution)
+3. Enforce minimum inter-item spacing (> 1 degree center-to-center)
+4. Enforce minimum distance from fixation (> 1 degree; avoids masking by fixation cross)
+5. Balance target position across eccentricity bins and quadrants over the experiment
+6. For each trial, randomly assign target to one position (present trials) or assign no target (absent trials)
+
+### Randomization Constraints
+
+- **Target position**: Counterbalance across quadrants and eccentricity bins within each set size
+- **Set size order**: Randomize or pseudorandomize within blocks
+- **Target presence**: Pseudorandomize to avoid long runs of present or absent trials (max run length: **4 consecutive same-type trials**; standard practice)
+- **Feature assignment**: For conjunction search, ensure equal numbers of each distractor type (e.g., 50% share color with target, 50% share orientation; Treisman & Gelade, 1980)
+- **Block structure**: If multiple set sizes are used, either mix within blocks or block by set size (within-block mixing is standard; Wolfe, 2021)
+
+## Common Pitfalls
+
+1. **Not controlling for eccentricity confounds**: Larger set sizes place items at greater eccentricities on average, confounding set size with acuity. Solution: Use a fixed display area and add items by filling in gaps, not by expanding the area (Wolfe et al., 1998).
+
+2. **Interpreting null set-size effects as "pop-out" without verification**: A flat slope does not guarantee parallel processing. Verify with brief presentations (100-200 ms + mask) and check that accuracy remains high (Treisman & Gelade, 1980).
+
+3. **Ignoring the prevalence effect**: With low target prevalence (<25%), observers adopt a more liberal quitting threshold, increasing miss rates from ~5% to >25% (Wolfe et al., 2005). Design accordingly for applied contexts.
+
+4. **Using too few set sizes**: Two set sizes define only a line; you cannot assess linearity or detect nonlinear search functions. Use at least **3 set sizes**, preferably **4-5** (Wolfe, 2021).
+
+5. **Not equating luminance across color conditions**: Luminance differences create an unintended pop-out cue. Always measure and equate luminance (use a photometer or validated software settings; Nagy & Sanchez, 1990).
+
+6. **Placing items too close together**: Violating minimum spacing creates crowding, where items become unidentifiable not because of search difficulty but because of peripheral vision limits (Bouma, 1970; Pelli & Tillman, 2008).
+
+7. **Confounding distractor heterogeneity with target discriminability**: Adding distractor variability reduces search efficiency independently of T-D similarity. Manipulate one while controlling the other (Duncan & Humphreys, 1989).
+
+8. **Failing to counterbalance target position**: If the target systematically appears at certain locations, observers develop spatial biases. Counterbalance across quadrants and eccentricities.
+
+## Minimum Reporting Checklist
+
+Based on current best practices in visual search research:
+
+- [ ] Search type (feature, conjunction, spatial configuration) and theoretical motivation
+- [ ] Set sizes used and number of trials per set size per target-presence condition
+- [ ] Target-present to target-absent ratio
+- [ ] Display parameters: eccentricity range, item size (in degrees of visual angle), minimum spacing
+- [ ] Item features: colors (in device-independent space), orientations (in degrees), sizes (in degrees)
+- [ ] Target-distractor similarity metric and value
+- [ ] Distractor composition (homogeneous vs. heterogeneous; how features were assigned)
+- [ ] Viewing distance and display specifications (size, resolution, refresh rate)
+- [ ] Timing: fixation duration, display duration, response deadline, ITI
+- [ ] Randomization scheme: how set size, target presence, and target position were randomized
+- [ ] Search slope values (ms/item) with confidence intervals for target-present and target-absent
+- [ ] Slope ratio (absent:present) to assess self-termination
+- [ ] Error rates by condition (especially miss rates)
+- [ ] RT trimming criteria and percentage of data excluded
+- [ ] Software used for stimulus generation and presentation (with version)
+
+## References
+
+- Appelle, S. (1972). Perception and discrimination as a function of stimulus orientation: The "oblique effect" in man and animals. *Psychological Bulletin*, 78, 266-278.
+- Bouma, H. (1970). Interaction effects in parafoveal letter recognition. *Nature*, 226, 177-178.
+- Chun, M. M., & Wolfe, J. M. (1996). Just say no: How are visual searches terminated when there is no target present? *Cognitive Psychology*, 30, 39-78.
+- Duncan, J., & Humphreys, G. W. (1989). Visual search and stimulus similarity. *Psychological Review*, 96, 433-458.
+- Foster, D. H., & Ward, P. A. (1991). Asymmetries in oriented-line detection indicate two orthogonal filters in early vision. *Proceedings of the Royal Society B*, 243, 75-81.
+- Nachmias, J. (2011). Shape and size discrimination compared. *Vision Research*, 51, 400-407.
+- Nagy, A. L., & Sanchez, R. R. (1990). Critical color differences determined with a visual search task. *Journal of the Optical Society of America A*, 7, 1209-1217.
+- Pelli, D. G., & Tillman, K. A. (2008). The uncrowded window of object recognition. *Nature Neuroscience*, 11, 1129-1135.
+- Treisman, A. M., & Gelade, G. (1980). A feature-integration theory of attention. *Cognitive Psychology*, 12, 97-136.
+- Wolfe, J. M. (1994). Guided Search 2.0: A revised model of visual search. *Psychonomic Bulletin & Review*, 1, 202-238.
+- Wolfe, J. M. (2021). Guided Search 6.0: An updated model of visual search. *Psychonomic Bulletin & Review*, 28, 1060-1092.
+- Wolfe, J. M., Cave, K. R., & Franzel, S. L. (1989). Guided search: An alternative to the feature integration model for visual search. *Journal of Experimental Psychology: Human Perception and Performance*, 15, 419-433.
+- Wolfe, J. M., Friedman-Hill, S. R., Stewart, M. I., & O'Connell, K. M. (1992). The role of categorization in visual search for orientation. *Journal of Experimental Psychology: Human Perception and Performance*, 18, 34-49.
+- Wolfe, J. M., Horowitz, T. S., & Kenner, N. M. (2005). Rare items often missed in visual searches. *Nature*, 435, 439-440.
+- Wolfe, J. M., O'Neill, P., & Bennett, S. C. (1998). Why are there eccentricity effects in visual search? Perception & Psychophysics, 60, 140-156.
+
+See `references/array-generation-parameters.yaml` for a machine-readable parameter specification.