TIMS analysis agent notes (repo root)

TIMS analysis agent notes (repo root)

These instructions apply to everything under this directory tree.

Project structure (don’t assume a src/ package)

• No src/ directory in this repo.
• Reusable “core” code goes in: preprocessing.py, plot_helpers.py.

Data conventions (stable)

• Inputs: BrainVision *.vhdr (+ *.eeg/*.vmrk).
• Framework: MNE (mne.io.read_raw_brainvision, mne.EpochsArray(..., baseline=None, verbose=False)).
• Shapes:
  • epoch_signal(...) -> (n_epochs, n_samples) + time_axis_seconds length n_samples
  • epoch_multichannel(...) -> (n_epochs, n_channels, n_samples)
• Units: process in Volts; convert to microvolts (* 1e6) only for plots/summary numbers.

Before writing any code

1. Read the relevant standards and latest decision context first.
   • Start with docs/standards/SKRIPT.md and the latest relevant memo or readme.md entry.
2. Search for reusable logic in the core modules.
   • Prefer rg -n "keyword" preprocessing.py plot_helpers.py.
   • Reuse a helper only when it is non-trivial, already validated, and clearer than short MNE-native code.
   • Do not call a helper just because it exists.
3. Read the closest reference script and follow the scientific pattern when the question matches.
   • Match: windows, mask usage, channel picking, filter settings, naming, and I/O style.
   • Do not copy unrelated structure that would make one script answer more than one question.
4. Decide whether to extend an existing script or create a new one.
   • Extend only if the script still answers one narrow question after the change.
   • Otherwise split and create a new script.

When writing code

• Keep paths single-source and explicit.
  • Use Path(r"...") (Windows-style raw strings) for scripts intended to run with Windows Python.
  • No fallback paths, no auto-discovery, no interactive prompts, no silent try/except.
• Keep analysis scripts deterministic.
  • No “click to continue” flows unless the script is explicitly an interactive QC tool (e.g., manual ICA selection).
  • Prefer verbose=False on MNE I/O and processing unless debugging.
• Prefer “core module” placement for reusable logic.
  • If it’s used in more than one script, it goes into preprocessing.py or plot_helpers.py.
  • Helpers added to core should have clear names and explicit units in the signature (e.g., window_start_s, sampling_rate_hz).
• Naming rules.
  • Use descriptive names: stim_onsets_samples, epoch_time_seconds, main_cut_window_s.
  • Avoid ambiguous names like d2, tmp, x1 unless they are loop indices.
• Naming alone is not enough where scientific choices matter.
  • Add comments for why windows, bands, channels, thresholds, and helper calls are scientifically justified.
• Analysis script size should follow docs/standards/SKRIPT.md.
  • Typical target: about 70-150 lines.
  • 300+ lines is not acceptable.
  • If repeated mechanics push a script beyond that range, move those mechanics into preprocessing.py or plot_helpers.py.

Analysis script quality rules

Follow docs/standards/SKRIPT.md for all analysis script rules (layout, naming, comments, forbidden patterns, checklist).

• If any local rule in this file conflicts with docs/standards/SKRIPT.md for analysis-script design, follow docs/standards/SKRIPT.md.
• This file should keep repo-specific constraints only: data conventions, paths, output layout, reusable-module placement, and reporting expectations.

Output directory

• Always write outputs into an explicit output_directory created via mkdir(parents=True, exist_ok=True).

Reporting changes (in the final message)

• Be surgical and specific: “changed X in file.py:line to fix Y” (not “fixed a bug”).
• Include a short accounting line:
  • Lines: <approx added/modified> | Reused: <fn1(), fn2()> | New functions: <names or none> | Output: <dir or file>