v2.2.7

Highlights

• New reporting system with combined image output and caching for ICA plots (sources, PSD, topography)
• ConfigKit introduced for Python task config validation (schema boundary) and clearer task defaults
• CLI UX improvements: themed console, new workspace/auth commands, refined help and startup banner
• File export revamp: robust EEG-only re-exports for .set, richer QA manifest and fastplot summaries
• BIDS compliance updates: improved derivatives structure and dataset_description handling
• Visualization refactor: consolidate on matplotlib; improved layout and error handling
• Docs cleanup: remove legacy MkDocs artifacts; add maintenance notes and focused pages

Compatibility

• Python 3.10–3.12
• Package: autocleaneeg-pipeline 2.2.7 (PyPI)

Notable changes

• See commit list below for detailed changes.

Install / Upgrade

pip install -U autocleaneeg-pipeline

Changes since ${PREV_TAG}

• docs: update Sphinx version to 2.2.7 (b8e8092)
• chore(release): bump version to 2.2.7 (f7d8ce5)
• export: for .set outputs, re-export EEG-only via mne (epochs if possible, else synthetic short epochs from raw) with run_id in description; skip files with no EEG channels; keep regular copy for other files; robust error handling and messages. (8c848b8)
• reporting: remove fastplotlib path and standardize on matplotlib; simplify API and messages; ensure EEG-only selection and better handling when no EEG channels are present; rename renderer function to _render_fastplot_image; improve docstrings. (c153b52)
• config,eog: BREAKING change EOG step schema to object {eog_indices,eog_drop}; update processing to use indices and optionally drop EOG channels. Add migration path via runtime defaults; older task files continue to run with empty value treated as None. (d27b5bd)
• feat(fastplot): add summary generation after file exports and improve error handling for missing epochs (a2b6fa5)
• fix(plotting): change temporary file extension from .tiff to .png and streamline cleanup process (f0dd2a1)
• feat(qa-manifest): include source file information in QA manifest updates for generated images (38ac2ab)
• feat(qa-manifest): implement QA manifest update functionality for generated images (23db983)
• refactor(plotting): streamline image loading and title banner creation for enhanced plot rendering (0802a5a)
• refactor(directory-setup): improve directory creation and error handling for key directories and file exports (4add501)
• refactor(mixins): enhance artifact path resolution with fallback logging for unresolved paths (4d00285)
• refactor(error-handling): improve error reporting for directory validation and file copying processes (f82477d)
• refactor(directories): enhance directory validation and path resolution for ICA and QA directories (cbe8207)
• refactor(cli, mixins, reports): streamline path handling for processing logs and improve relative path resolution (79de720)
• refactor(readme): update output structure and installation instructions for clarity and consistency (76a9afe)
• refactor(reports): update metadata directory path in JSON summary creation for improved clarity (9096019)
• refactor(logging): update logger configuration to use a single log file per task and simplify log rotation settings (8cc9d99)
• refactor(reports): rename processing log file and implement migration for legacy task-root logs (9da3ede)
• refactor(directories): unify handling of final_files and exports paths for consistency and clarity (4617b09)
• refactor(directories): standardize directory names for ICA and QA, updating paths for improved clarity and compatibility (afa693b)
• refactor(ica): update control sheet and metadata directory handling to improve structure and compatibility (c672b05)
• refactor(reports): update CSV path handling for task processing logs and migrate legacy logs to task root (e884498)
• refactor(directories): update handling of final_files to final_exports for improved clarity and backward compatibility (54f3fbd)
• feat(qa): implement QA directory handling for Fastplot summary and enhance image file search in QA folder (fed1b78)
• refactor(directories): remove version marker writing from directory preparation process (4f49491)
• refactor(directories): relocate final_files directory to task root and update related paths in report generation (3abc67e)
• feat(bids): enhance dataset_description.json handling to include task name and pipeline branding (4396f69)
• refactor(directories): update stage output path to write directly under BIDS derivatives for improved clarity (2a7469a)
• refactor(reports): remove redundant saving of report to derivatives path (aab86b4)
• refactor(directories): streamline directory handling for ICA and BIDS compliance, removing versioning from derivatives paths (cb371c2)
• refactor(ica): update ICA file path handling to prefer configured directory and ensure directory structure adheres to BIDS standards (801c5ee)
• Restructure task output directories for non-derivative artifacts (a1508b0)
• feat(config): add montage and move_flagged_files options to task settings schema; update RestingState tasks to include new config options (34a5c65)
• Ensure CLI reports failure when errors logged (9c49d70)
• docs: clarify no YAML pipeline configs in CLAUDE.md; remove load_config from utils API reference (b41ad0b)
• test: update unit/integration tests to reflect removal of YAML pipeline loader (e505a02)
• refactor(utils/config): remove duplicate legacy schema code; hard-disable YAML pipeline loader (84405a1)
• refactor(template-fallback): replace large fallback with thin re-export of canonical template (c087a83)
• feat(config): introduce configkit schema boundary and validate Python task configs at Task init (d3709c1)
• feat(template): add wavelet_threshold defaults and apply_wavelet_threshold in canonical template; align RestingState_BasicWavelet to explicit, config-driven behavior (22a00b5)
• feat: add wavelet threshold configuration and update fallback template for EEG tasks (a93939e)
• Update CLAUDE.md with additional development guidance and fix README typo (9ae35d0)
• docs: update commit guidelines and improve development commands (eb646ad)
• docs: update commit guidelines and improve development commands (b9733c9)
• feat: enhance cmd_view to support active source and improve error handling for EEG file viewing (a581569)
• Remove MkDocs documentation site (e60d2b1)
• feat: add post-command task reminder for improved user guidance (856a192)
• feat: add task reminder for workspace initialization in CLI (b2654cc)
• Update CLAUDE.md with additional development guidance and fix README typo (4ad5e21)
• docs: update installation instructions and remove obsolete theme section (b1e64bb)
• fix: add comprehensive error handling for ICA report generation (c78c8b1)
• Remove dev files (6fbf0d2)
• feat: implement comprehensive ICA batch optimization system (5d9cbfc)
• feat: implement intelligent ICA sources caching system (a930641)
• feat: enhance ICA component classification with source metadata and vision attributes (880e24f)
• fix: smooth ICA PSD plots (aea217f)
• feat: display ICA classifier in reports (53ebd4b)
• Add ICA custom layout helpers and documentation (f53ec8a)
• Add FastPlot report mixin for combined EEG visualization and summary generation (afb8466)
• feat: add ICA directory support and enhance report logging structure (c16f0b4)
• feat: enhance wavelet report generation with relative path support (310fa60)
• fix: improve error message for missing input file or directory in CLI (b783919)
• feat: centralize report outputs under shared hierarchy (c467f03)
• feat: allow numeric workspace selection (0738bba)
• feat: export wavelet threshold reports (abb6e9f)
• feat: implement wavelet thresholding mixin and integrate into RestingState task (95f3732)
• Add ERP-aware wavelet thresholding options (5d1fc54)
• Integrate wavelet reporting with thresholding module (fa96c52)
• feat: add psd analytics to wavelet report (635efaf)
• chore: add wavelet reporting CLI and docs (9a3d7bc)
• feat: add wavelet thresholding PDF report (dbf3557)
• fix: clamp wavelet decomposition level for short segments (d744018)
• fix: update package names in dependencies and error messages for consistency (a4d3752)
• fix: update version to 2.2.6 in pyproject.toml and init.py (6ceabab)
• Add wavelet thresholding function (c6f6f2d)
• docs: explain PyQt5 build fix (025934c)
• Add tests for input selection loop and task copy activation (fec8831)
• fix: update version to 2.2.5 in pyproject.toml and init.py (894344e)
• fix(cli): add graceful handling for missing OPENAI_API_KEY in report chat (28bcb92)
• fix(cli): replace Console import with get_console utility (754d4ac)
• feat(cli): interactive selection for when not using latest\n\n- Prompt user to use the latest run; if declined, show a rich table of recent runs\n- Table includes Run ID, Created, Task, File, Status, Success, Backup, and Artifacts count\n- User selects a run number; chat uses that run's outputs (llm context or reconstruction) (c010177)
• fix(cli): set database path for defaults\n\n- Initialize DB path to workspace output dir so latest run lookup works outside pipeline\n- Keeps behavior no-op if anything goes wrong (guarded) (a247f19)
• fix(cli): parse metadata JSON when loading latest run for default\n\n- returns metadata as a JSON string; parse it before accessing step_prepare_directories\n- Keeps change minimal; leverages existing resolver + reconstruction logic (ce30f3a)
• docs: directory backup resolution plan (Phase 1/2)\n\nfeat(phase1):\n- file_system: return backup_info when auto-backup triggers\n- pipeline: persist backup info in current run metadata and audit logs\n- path_resolution: add resolve_moved_path() using recent runs' metadata\n- cli report chat: default resolver for metadata/bids paths, reconstruct context from last run\n\nThis enables locating last outputs even after auto-backups without mutating legacy records. (cb9ca7b)
• feat(cli): make default to latest run\n\n- now optional; when omitted, loads latest run's llm_reports/context.json\n- If absent, reconstructs a minimal context from latest processing_log.csv + PDF\n- Fully guarded; prints a friendly error if nothing is available (e89212c)
• chore(templates): add ai_reporting flag (default False) to task templates\n\n- Update package template and fallback template to include with guidance\n- Keeps AI reporting opt-in by default for newly created tasks (ddb773d)
• feat(task): gate LLM reporting behind task config flag\n\n- Add early return in Task.emit_llm_reports() when is absent/False (default OFF)\n- Guard placed before any imports or file checks to avoid API key checks when disabled\n\nThis keeps AI reporting opt-in and prevents pipeline overhead/errors when disabled. (d81eef9)
• feat(task): integrate LLM reporting into Task with emit_llm_reports() and call from Pipeline\n\n- Add Task.emit_llm_reports() that builds RunContext from per-file processing_log.csv and the generated autoclean_report.pdf\n- Use always-present outputs to populate FilterParams, EpochStats, and limited ICAStats\n- Write reports under metadata/llm_reports via reporting.create_reports()\n- Invoke emit_llm_reports() after PDF generation in Pipeline, with safe error handling\n\nThis makes LLM-backed reporting automatic (when configured) without relying on internal JSON summaries. (08916af)
• fix(reporting): coerce JSON to dataclasses in report create; repair LLM client return indentation\n\n- Add run_context_from_dict to convert plain JSON into nested dataclasses (FilterParams, ICAStats, EpochStats) and return a proper RunContext\n- Export helper via reporting package \n- Update cmd_report_create to use coercion and override run_id when provided\n- Fix SyntaxError in LLMClient.generate_json caused by mis-indented return (return outside function)\n\nThis resolves crashes when calling:\n\n autocleaneeg-pipeline report create --context-json ... --out-dir ...\n\nby ensuring asdict(context) and render_methods() receive valid dataclass instances.\n (fae15c7)
• feat: add LLM reporting module (ae27a5f)
• feat(reporting): mark ICVision-labeled components in hybrid runs\n\n- In hybrid classification, set DataFrame annotator=ic_vision for reclassified components\n- Add "[Vision]" tag to component labels in full-duration and summary PDF reports\n- Adjust table column widths for readability (48748aa)
• chore: ignore and remove stray coverage artifact (e172e1c)
• fix(ica): hybrid ICLabel→ICVision merge to avoid length mismatch\n\n- Preserve full ICLabel labels/scores, run ICVision on subset, then merge\n- Rebuild per-component labels and full-size confidence matrix (n_components x 7)\n- Update ICA.labels_ and ICA.labels_scores_ to merged values before DataFrame build\n- Resolves runtime error: values length (subset) != index length (all components) (f55331d)
• fix(ica): align ICLabel calls with mne_icalabel API by removing verbose kwarg\n\n- Remove unsupported verbose kwarg in mne_icalabel.label_components calls\n- Keep function-level verbose param for our own logging\n- Minor formatting and component index calc cleanup (58748ec)
• feat(ica): add hybrid ICLabel-ICVision classification (c475402)
• feat(config): add temp_highpass_for_ica parameter support (fbc9399)
• fix(tasks): remove debug breakpoint from RestingState_Basic (c264803)
• refactor(ica): improve component classification and logging (a0487cc)
• feat: add temp_highpass_for_ica parameter to ICA configuration (a7f946a)
• feat: log to workspace directory (9ffb033)
• remove deprecated Dockerfiles, coverage files, and example scripts (b8be711)
• bump version to 2.2.3 in pyproject.toml and init.py (c2f8f2b)
• Remove legacy container CLI (a8912b4)
• Add ASCII icon fallback (cf0d559)
• chore(release): bump version to 2.2.2 (28656c6)
• Format processing log numeric fields (b611b10)
• docs: describe task pipeline steps (138c151)
• fix(gitignore): add src/.DS_Store to ignore list (1090d52)
• fix(config): update high-frequency cutoff to 100 Hz; disable cropping step (a316027)
• task(copy): single-input UX to derive filename and class; autosanitize; collision-safe; concise summary output (5872167)
• task(copy): prompt for filename and class rename; ensure unique filename; validate class identifier; rename class in file via safe regex; verify class post-copy (0be2235)
• task(copy): interactive selection when no source; combine built-in and custom; keep existing conflict handling (fb7b637)
• tasks: move legacy/bulk tasks to tasks/pending_approval; keep RestingState_Basic active (5a101ad)
• task(list): simplify header/banner; add centered counts summary (e141f35)
• workspace(show): minimal header; strict validity check; centered lines (5095a99)
• fix(workspace): eliminate confusing "not configured" message on fresh installs (cf2ddff)
• bump: version 2.2.0 → 2.2.1 (86dcf01)
• fix: remove input subcommands from task help display (639e92d)
• Add ICA processing subcommand (c9e94b6)
• Add ICA control sheet workflow (07bef49)
• feat: set default value for verbose flag in CLI arguments (fe216c7)
• feat: include task parameters in report (29089d1)
• cli,pipeline: support brace-expansion for globs (e.g. '*.{raw,set}') so .raw/.set files are detected; fix process guard file counting and deduplicate matches (847faa3)
• Include raw files in default glob (45dd8ef)
• feat: add rich error handling for unknown top-level commands in CLI (eaf406b)
• feat: allow disabling flagged file relocation (d5c3b1b)
• fix: update PSD computation to use epochs for original and cleaned data (27f63ce)
• chore: remove matlab keys before saving (1134b5e)
• refactor: replace tight_layout with subplots_adjust (2142e18)
• fix(cli/input): allow quoted paths in interactive file/folder prompts\n\n- Strip wrapping quotes inside interactive selection in user_config\n- Update prompt text to indicate quotes are accepted\n- Prevents false 'File not found' when pasting quoted paths (97e8a9d)
• feat(cli/input): accept quoted paths for input set (bd8e1a1)
• feat: add interactive process command guard (2958454)
• feat(cli): introduce input command, deprecate source; elegant help + banners; show active input with icons; add to quick belt\n\n- Add new input subcommand and root help topic; mark source as deprecated alias with guidance\n- Root help: list input under Commands; add Input topic; keep Source topic as deprecated pointer\n- When source is invoked without subcommand, show elegant help (also for input)\n- Startup and main banners: display Active input with file (📄) vs folder (📂) icons; guard for missing/not set\n- Subcommand banner: show workspace, task, and input context consistently\n- Quick command belt: include input for discoverability\n- Process messages and fallbacks: use "input" terminology and hints (input set) instead of "source"\n- Keep internal storage via user_config active_source to avoid broad refactor (7672963)
• feat: implement active source path management system (57a5ecf)
• feat(cli): edit/copy/delete default to active task with confirmation\n\n- Make arguments optional: omit target/source uses active task if set\n- Prompt to confirm using active task; cancel if declined\n- Update help text and task topic list to reflect behavior (ac12aac)
• feat(cli): always show active workspace and active task under banner\n\n- Show active task (or 'not set') in startup context and root banner\n- Add active task line to setup and compliance headers\n- Include active task status for all sub-commands header\n- Ensure process/view help screens print startup context with workspace+task (2846a06)
• feat(cli): include active task commands in 'task' help\n\n- Add rows for: task set, task unset, task show\n- Visible in 'autocleaneeg-pipeline task' and '-h task' outputs (8147f31)
• feat(cli): display active task beneath Workspace in banner and help\n\n- Centered line: 🎯 Active task: \n- Shown on root banner and rich help/startup context\n- No change if no active task set (22ac00b)
• Add active task functionality for simplified CLI workflow (c682ede)
• Implement robust CLI process logging with security features (96b95ea)
• fix: adjust spacing in help menu and refactor workspace setup wizard invocation (0a42234)
• workspace UX: redesign reconfiguration copy and selection — clear 'Change Workspace Folder' header, 3-choice selector (current/default/custom) with summarized table; pass current dir into prompt (c3ee64c)
• workspace UX: streamline 'workspace set' interactive flow (skip duplicate prompt using direct wizard); hide identical current/default table; reduce vispy logging noise (eb4f4e4)
• workspace set: make path optional; if omitted, launch interactive workspace chooser (same wizard) (64c53ee)
• docs: add Web Task Generator Wizard quick start with new 'workspace' and 'task' commands (import/edit/copy/delete), run examples, and troubleshooting (19efebf)
• "Claude Code Review workflow" (cad8fac)
• "Claude PR Assistant workflow" (9fdd4e3)
• task: add 'delete' and 'copy' subcommands with safety prompts; update help topic; support name/path resolution and workspace guards (c41d3d7)
• task: add 'import' subcommand to copy task file into workspace with prompts (--name, --force) and usage guidance; add to help topic (bd5dd50)
• refactor: improve formatting and readability in help messages and command descriptions (5d1bf5d)
• workspace: enhance 'cd' subcommand to print shell-specific commands for directory change (f00b26d)
• workspace: add 'cd' subcommand; prints path for command substitution or --spawn to open subshell in workspace; include in help topic (bdafb8d)
• workspace: add 'default' subcommand to set recommended default location; wire into dispatcher and help topic (307ac71)
• workspace: add subcommands explore/size/set/unset; dispatch + rich help topic; update parser and banner help to include workspace actions (6d494f0)
• banner: remove left-justified workspace fallback and fix tip indentation in main banner (9ecfa75)
• commands: add top-level 'workspace' command for workspace config; move compliance guidance under 'auth'; update help/banners/docs and messages to reference 'workspace'; deprecate 'setup' from main UX (51f42a9)
• setup UX: center workspace line directly under banner; add centered hint + compliance status; center workspace under compliance header as well (f1c9acf)
• setup UX: display workspace folder in setup banner (standard and compliance flows) (2d7dc52)
• setup UX: remove system information display during workspace directory selection (first-time and existing workspace) for a focused, minimalist flow (e4cea41)
• setup UX: clarify copy and flow — concise compliance status, 'Configure workspace' phrasing, cleaner choices; update workspace setup messages; add '-h setup' topic; improve setup parser help (170ab78)
• cli UX: replace 'list-tasks' with 'task' in main banner command belt and root help commands list (bb53a34)
• cli task UX: show elegant task subcommand help when no subcommand; add '-h task' topic; remove default-to-list behavior (91da02a)
• cli task: add 'task explore' to open workspace tasks folder via OS (open/xdg-open/Explorer); default 'task' to 'list' and keep 'task list' alias to 'list-tasks' (84e9999)
• cli: add 'task' main command default to 'list' (so 'task' == 'task list'); reflect alias in help row for 'list-tasks' (97dbfff)
• cli UX: add brief, styled help for 'process' when task or input is missing (with usage, options overview, and docs link) (7b042e9)
• cli UX: make 'view' file positional optional and show a brief, styled usage/help block when missing (with docs link) (d88df5a)
• cli UX: improve code formatting for readability and consistency (1b7ac6d)
• cli UX: replace help 'Tip' with docs link and add bottom padding (6076ec7)
• cli UX: refine help screen — add Usage line; simplify tables (no examples), add icons and 'help' entry; consistent minimalist layout (19acf82)
• cli UX: add centered attribution line (Pedapati Lab @ Cincinnati Children's Hospital Medical Center) (ac6298c)
• cli UX: wrap banner links onto separate lines; add GitHub meta line (code • issues • discussions) (48f7b14)
• cli UX: add centered Docs and GitHub links under key commands belt (e07bfb5)
• cli UX: help alias mirrors -h/--help, reuse root help printer; add 'help' to centered commands; remove Quick Start section for minimalist banner (bfd7a4d)
• cli: add centered minimalist key commands belt (setup · view · list-tasks · process · review) above Quick Start on bare invocation (17cc255)
• cli: fix RootRichHelpAction help table indentation; remove config from main help; reorder commands (setup, view, list-tasks, process, review) (99fc735)
• feat: add OpenGL_accelerate dependency (792403b)
• feat(cli): add 'auth' subcommand group (login/logout/whoami/diagnostics/setup/enable/disable); wire dispatch; update help topics and examples (64f2415)
• feat(cli): support '-h auth' and 'help auth' topic; add curated Auth Commands table; center startup context in help; keep existing commands intact (5f5ee30)
• feat(cli): center header context universally; rich -h shows header + centered system/workspace info; curated root help table; add CLI help backup markdown (74220c8)
• fix(cli): avoid Panel(box=None); render borderless banner via Align.center to prevent Rich AttributeError (89953a0)
• feat(cli): update startup banner — no borders; show 'AutocleanEEG Pipeline' with version; keep existing tagline (b323a43)
• refactor(tests): remove unnecessary blank lines in test files (08a8b2b)
• docs(README): document --theme and color env vars (7f504a5)
• refactor(user_config): switch setup/status prints to semantic styles (f344994)
• refactor(cli_display): use semantic styles and shared Console (f410992)
• refactor(cli): switch to shared get_console; remove local theming; use semantic styles (e611a8d)
• feat(utils.console): add themed Console factory and semantic Theme (c2ff7c8)
• CLI: add theme-aware Console and semantic styles; add --theme flag; centralize Console usage (7681d3a)
• fix: update tagline for branding consistency and improve code formatting (55e2d01)
• bump: version 2.2.0 in pyproject.toml (16c4613)
• bump: version 2.2.0 (a114c35)
• feat: consolidate all dependencies into main package (af491f6)
• fix: adjust indentation for author entry in pyproject.toml (c6818a1)
• fix: reorder authors and add new optional dependency (372b390)
• fix: apply ruff auto-fixes and code quality improvements (1b2de5f)
• refactor: update package references throughout codebase (8f962f4)
• test: reformat test fixture files (5374e22)
• ci: exclude intentionally broken test fixtures from formatting (41c9722)
• docs: update documentation for new package name (8e711ce)
• feat: rename package to autocleaneeg-pipeline (62c5c95)
• README: switch installation and workflow to Astral uv (uv tool install, uv pip for dev) and add Quick Start with new CLI. (c7680e9)
• Rename distribution and CLI to autocleaneeg-pipeline; remove alias; update install instructions, GUI extras hints, and all CLI references across code and docs. (c24828d)