{"id":34108410,"url":"https://github.com/cincibrainlab/autocleaneeg-icvision","last_synced_at":"2026-03-10T09:02:06.125Z","repository":{"id":313429572,"uuid":"989023317","full_name":"cincibrainlab/autocleaneeg-icvision","owner":"cincibrainlab","description":"Automated ICA artifact classification and removal for EEG data using OpenAI Vision API. Generates component visualizations, classifies artifacts, and produces cleaned datasets with detailed reports.","archived":false,"fork":false,"pushed_at":"2026-01-14T22:14:24.000Z","size":808,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-15T04:43:54.527Z","etag":null,"topics":["artifact-removal","automation","eeg","eeglab","ica","machine-learning","mne-python","reproducibility","vision-api"],"latest_commit_sha":null,"homepage":"https://github.com/cincibrainlab/autocleaneeg-icvision","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cincibrainlab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY_AUDIT_REPORT.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-05-23T12:43:58.000Z","updated_at":"2026-01-14T22:14:28.000Z","dependencies_parsed_at":"2025-09-06T01:31:05.574Z","dependency_job_id":"3935ecab-b9f1-4deb-8d0e-f8007732edaf","html_url":"https://github.com/cincibrainlab/autocleaneeg-icvision","commit_stats":null,"previous_names":["cincibrainlab/icvision"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cincibrainlab/autocleaneeg-icvision","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cincibrainlab%2Fautocleaneeg-icvision","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cincibrainlab%2Fautocleaneeg-icvision/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cincibrainlab%2Fautocleaneeg-icvision/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cincibrainlab%2Fautocleaneeg-icvision/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cincibrainlab","download_url":"https://codeload.github.com/cincibrainlab/autocleaneeg-icvision/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cincibrainlab%2Fautocleaneeg-icvision/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30328269,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T05:25:20.737Z","status":"ssl_error","status_checked_at":"2026-03-10T05:25:17.430Z","response_time":106,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artifact-removal","automation","eeg","eeglab","ica","machine-learning","mne-python","reproducibility","vision-api"],"created_at":"2025-12-14T18:17:24.895Z","updated_at":"2026-03-10T09:02:06.103Z","avatar_url":"https://github.com/cincibrainlab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Autoclean EEG ICVision (Standalone)\r\n\r\n[![PyPI version](https://badge.fury.io/py/autoclean-icvision.svg)](https://badge.fury.io/py/autoclean-icvision)\r\n[![Python versions](https://img.shields.io/pypi/pyversions/autoclean-icvision.svg)](https://pypi.org/project/autoclean-icvision/)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\r\n\r\nAutomated ICA component classification for EEG data using OpenAI's Vision API.\r\n\r\n## Overview\r\n\r\nICVision automates the tedious process of classifying ICA components from EEG data by generating component visualizations and sending them to OpenAI's Vision API for intelligent artifact identification.\r\n\r\n**Workflow**: Raw EEG + ICA → Generate component plots → OpenAI Vision classification → Automated artifact removal → Clean EEG data\r\n\r\n**Key Features**:\r\n- Automated classification of 7 component types (brain, eye, muscle, heart, line noise, channel noise, other)\r\n- **🔄 Drop-in replacement for MNE-ICALabel**: Same API, enhanced with OpenAI Vision\r\n- **⚡ Strip Layout Mode**: Batch 9 components per API call for **88% cost reduction**\r\n- **🌐 Custom Endpoint Support**: Use OpenAI-compatible APIs (e.g., CLIProxy, Azure OpenAI)\r\n- Multi-panel component plots (topography, time series, PSD, ERP-image)\r\n- MNE-Python integration with `.fif` and `.set` file support\r\n- **EEGLAB .set file auto-detection**: Single file input with automatic ICA detection\r\n- **Smart file organization**: Basename-prefixed output files prevent overwrites when processing multiple datasets\r\n- **Continuous data only**: Graceful error handling for epoched data with helpful conversion instructions\r\n- **Enhanced PDF reports**: Professional dual-header layout with color-coded classification results\r\n- **OpenAI cost tracking**: Automatic cost estimation and logging for budget monitoring\r\n- Parallel processing with configurable batch sizes\r\n- Command-line and Python API interfaces\r\n- Comprehensive PDF reports and CSV results\r\n\r\n## Installation\r\n\r\n```bash\r\npip install autocleaneeg-icvision\r\n```\r\n\r\n**Requirements**: Python 3.8+ and OpenAI API key with vision model access (e.g., `gpt-4.1`)\r\n\r\n```bash\r\nexport OPENAI_API_KEY='your_api_key_here'\r\n```\r\n\r\n## Usage\r\n\r\n### Command-Line Interface (CLI)\r\n\r\nThe primary way to use ICVision is through its command-line interface.\r\n\r\n**Basic Usage:**\r\n\r\n**Single EEGLAB .set file (Recommended):**\r\n```bash\r\nautoclean-icvision /path/to/your_data.set\r\n# or legacy command: icvision /path/to/your_data.set\r\n```\r\n\r\n**Separate files:**\r\n```bash\r\nautoclean-icvision /path/to/your_raw_data.set /path/to/your_ica_decomposition.fif\r\n# or legacy command: icvision /path/to/your_raw_data.set /path/to/your_ica_decomposition.fif\r\n```\r\n\r\nICVision can automatically detect and read ICA data from EEGLAB `.set` files, making single-file usage possible when your `.set` file contains both raw data and ICA decomposition.\r\n\r\nThis command will:\r\n1.  Load the raw EEG data and ICA solution (auto-detected from `.set` file or from separate files).\r\n2.  Classify components using the default settings.\r\n3.  Create an `autoclean_icvision_results/` directory in your current working directory.\r\n4.  Save the following into the output directory (with input filename prefix for organization):\r\n    *   Cleaned raw data (artifacts removed): `{basename}_icvis_cleaned_raw.{format}`\r\n    *   Updated ICA object with component labels: `{basename}_icvis_classified_ica.fif`\r\n    *   `{basename}_icvis_results.csv` detailing classifications for each component.\r\n    *   `{basename}_icvis_summary.txt` with overall statistics.\r\n    *   `{basename}_icvis_report_all_comps.pdf` (comprehensive PDF report with visualizations).\r\n\r\n**Note**: `{basename}` is extracted from your input filename (e.g., `sub-01_task-rest_eeg.set` → `sub-01_task-rest_eeg` prefix). This prevents file overwrites when processing multiple datasets.\r\n\r\n### Recent Improvements\r\n\r\n**Enhanced File Organization (v2024.12)**:\r\n- **Shared workspace**: All results now saved to `autoclean_icvision_results/` directory by default\r\n- **Smart naming**: Input filename prefixes (e.g., `sub-01_task-rest_eeg_icvis_results.csv`) prevent conflicts\r\n- **Multi-file friendly**: Process multiple datasets without overwrites - perfect for batch processing subjects\r\n\r\n**Improved User Experience**:\r\n- **Epoched data handling**: Clear error messages with EEGLAB conversion instructions for unsupported epoched data\r\n- **Enhanced PDF reports**: Professional layout with IC Component titles and color-coded Vision Classification results\r\n- **Clean logging output**: Professional, user-focused logging with optional verbose mode for debugging\r\n- **Better error messages**: Informative CLI output with suggested solutions\r\n\r\n### Strip Layout Mode (New in v0.3.0)\r\n\r\nStrip layout batches multiple ICA components into a single image, reducing API calls by ~88%:\r\n\r\n```bash\r\n# Single-image mode (default, 1 API call per component)\r\nautoclean-icvision data.set\r\n\r\n# Strip mode (9 components per API call, 88% fewer calls)\r\nautoclean-icvision data.set --layout strip\r\n```\r\n\r\n**Performance comparison** (24 components):\r\n\r\n| Mode | API Calls | Time | Cost |\r\n|------|-----------|------|------|\r\n| Single | 24 | ~85s | ~$0.29 |\r\n| Strip | 3 | ~50s | ~$0.04 |\r\n\r\nStrip mode is recommended for production pipelines. Classification accuracy is comparable to single-image mode.\r\n\r\n### Custom Endpoint Support (New in v0.2.1)\r\n\r\nUse OpenAI-compatible endpoints like CLIProxy or Azure OpenAI:\r\n\r\n```bash\r\n# Using environment variables (recommended)\r\nexport OPENAI_BASE_URL=\"https://your-proxy.example.com/v1\"\r\nexport OPENAI_API_KEY=\"your-api-key\"\r\nautoclean-icvision data.set --layout strip\r\n\r\n# Or via CLI flags\r\nautoclean-icvision data.set \\\r\n    --base-url https://your-proxy.example.com/v1 \\\r\n    --api-key your-api-key \\\r\n    --model gpt-5.2 \\\r\n    --layout strip\r\n```\r\n\r\n**Common Options (with defaults):**\r\n\r\n*   `--api-key YOUR_API_KEY`: Specify OpenAI API key (default: `OPENAI_API_KEY` env variable)\r\n*   `--base-url URL`: Custom API endpoint (default: OpenAI, or `OPENAI_BASE_URL` env variable)\r\n*   `--output-dir /path/to/output/`: Output directory (default: `./autoclean_icvision_results`)\r\n*   `--model MODEL_NAME`: OpenAI model (default: `gpt-4.1`, supports `gpt-5.2`)\r\n*   `--layout single|strip`: Classification layout mode (default: `single`)\r\n*   `--strip-size 9`: Components per strip image when `--layout=strip` (default: `9`)\r\n*   `--reasoning-effort none|low|medium|high`: Reasoning effort for gpt-5.x models (default: proxy default)\r\n*   `--confidence-threshold 0.8`: Confidence threshold for auto-exclusion (default: `0.8`)\r\n*   `--psd-fmax 45`: Maximum frequency for PSD plots in Hz (default: `45`)\r\n*   `--labels-to-exclude eye muscle heart`: Artifact labels to exclude (default: all non-brain types)\r\n*   `--batch-size 10`: Components per API request (default: `10`)\r\n*   `--max-concurrency 4`: Max parallel requests (default: `4`)\r\n*   `--no-auto-exclude`: Disable auto-exclusion (default: auto-exclude enabled)\r\n*   `--prompt-file /path/to/prompt.txt`: Custom classification prompt (default: built-in prompt)\r\n*   `--no-report`: Disable PDF report (default: report generation enabled)\r\n*   `--verbose`: Enable detailed logging (default: standard logging)\r\n*   `--version`: Show ICVision version\r\n*   `--help`: Show full list of commands and options\r\n\r\n**Examples with options:**\r\n\r\nSingle .set file usage:\r\n```bash\r\nautoclean-icvision data/subject01_eeg.set \\\r\n    --api-key sk-xxxxxxxxxxxxxxxxxxxx \\\r\n    --confidence-threshold 0.9 \\\r\n    --verbose\r\n```\r\n\r\nTraditional separate files:\r\n```bash\r\nautoclean-icvision data/subject01_raw.fif data/subject01_ica.fif \\\r\n    --api-key sk-xxxxxxxxxxxxxxxxxxxx \\\r\n    --model gpt-4.1 \\\r\n    --confidence-threshold 0.8 \\\r\n    --labels-to-exclude eye muscle line_noise channel_noise \\\r\n    --batch-size 8 \\\r\n    --verbose\r\n```\r\n\r\nFor ERP studies with low-pass filtered data:\r\n```bash\r\nautoclean-icvision data/erp_study.set \\\r\n    --psd-fmax 40 \\\r\n    --confidence-threshold 0.85 \\\r\n    --verbose\r\n```\r\n\r\nMulti-file batch processing:\r\n```bash\r\n# Process multiple subjects - all results go to shared directory\r\nautoclean-icvision data/sub-01_task-rest_eeg.set --verbose\r\nautoclean-icvision data/sub-02_task-rest_eeg.set --verbose\r\nautoclean-icvision data/sub-03_task-rest_eeg.set --verbose\r\n\r\n# Results organized in autoclean_icvision_results/ with prefixed filenames\r\nls autoclean_icvision_results/\r\n# sub-01_task-rest_eeg_icvis_results.csv\r\n# sub-01_task-rest_eeg_icvis_classified_ica.fif\r\n# sub-02_task-rest_eeg_icvis_results.csv\r\n# sub-02_task-rest_eeg_icvis_classified_ica.fif\r\n# ...\r\n```\r\n\r\n### Python API\r\n\r\nYou can also use ICVision programmatically within your Python scripts.\r\n\r\n**Single .set file usage (NEW):**\r\n```python\r\nfrom pathlib import Path\r\nfrom icvision.core import label_components\r\n\r\n# --- Configuration ---\r\nAPI_KEY = \"your_openai_api_key\"  # Or set as environment variable OPENAI_API_KEY\r\nDATA_PATH = \"path/to/your_data.set\"  # EEGLAB .set file with ICA\r\nOUTPUT_DIR = Path(\"icvision_output\")\r\n\r\n# --- Run ICVision (ICA auto-detected from .set file) ---\r\ntry:\r\n    raw_cleaned, ica_updated, results_df = label_components(\r\n        raw_data=DATA_PATH,              # EEGLAB .set file path\r\n        # ica_data parameter is optional - auto-detected from .set file\r\n        api_key=API_KEY,                 # Optional if OPENAI_API_KEY env var is set\r\n        output_dir=OUTPUT_DIR,\r\n    )\r\n```\r\n\r\n**Traditional separate files:**\r\n```python\r\nfrom pathlib import Path\r\nfrom icvision.core import label_components\r\n\r\n# --- Configuration ---\r\nAPI_KEY = \"your_openai_api_key\"  # Or set as environment variable OPENAI_API_KEY\r\nRAW_DATA_PATH = \"path/to/your_raw_data.set\"\r\nICA_DATA_PATH = \"path/to/your_ica_data.fif\"\r\nOUTPUT_DIR = Path(\"icvision_output\")\r\n\r\n# --- Run ICVision with all parameters ---\r\ntry:\r\n    raw_cleaned, ica_updated, results_df = label_components(\r\n        raw_data=RAW_DATA_PATH,          # Can be MNE object or path string/Path object\r\n        ica_data=ICA_DATA_PATH,          # Can be MNE object, path, or None for auto-detection\r\n        api_key=API_KEY,                 # Optional if OPENAI_API_KEY env var is set\r\n        output_dir=OUTPUT_DIR,\r\n        model_name=\"gpt-4.1\",            # Default: \"gpt-4.1\"\r\n        confidence_threshold=0.80,       # Default: 0.8\r\n        labels_to_exclude=[\"eye\", \"muscle\", \"heart\", \"line_noise\", \"channel_noise\"],  # Default: all non-brain\r\n        generate_report=True,            # Default: True\r\n        batch_size=5,                    # Default: 10\r\n        max_concurrency=3,               # Default: 4\r\n        auto_exclude=True,               # Default: True\r\n        custom_prompt=None,              # Default: None (uses built-in prompt)\r\n        psd_fmax=40.0                    # Default: None (uses 80 Hz); useful for ERP studies\r\n    )\r\n\r\n    print(\"\\n--- ICVision Processing Complete ---\")\r\n    print(f\"Cleaned raw data channels: {raw_cleaned.info['nchan']}\")\r\n    print(f\"Updated ICA components: {ica_updated.n_components_}\")\r\n    print(f\"Number of components classified: {len(results_df)}\")\r\n\r\n    if not results_df.empty:\r\n        print(f\"Number of components marked for exclusion: {results_df['exclude_vision'].sum()}\")\r\n        print(\"\\nClassification Summary:\")\r\n        print(results_df[['component_name', 'label', 'confidence', 'exclude_vision']].head())\r\n\r\n    print(f\"\\nResults saved in: {OUTPUT_DIR.resolve()}\")\r\n\r\nexcept Exception as e:\r\n    print(f\"An error occurred: {e}\")\r\n\r\n```\r\n\r\n## 🔄 ICLabel Drop-in Replacement\r\n\r\nICVision can serve as a **drop-in replacement** for MNE-ICALabel with identical API and output format. This means you can upgrade existing ICLabel workflows to use OpenAI Vision API without changing any other code.\r\n\r\n### Quick Migration\r\n\r\n**Before (using MNE-ICALabel):**\r\n```python\r\nfrom mne_icalabel import label_components\r\n\r\n# Classify components with ICLabel\r\nresult = label_components(raw, ica, method='iclabel')\r\nprint(result['labels'])  # ['brain', 'eye blink', 'other', ...]\r\nprint(ica.labels_scores_.shape)  # (n_components, 7)\r\n```\r\n\r\n**After (using ICVision):**\r\n```python\r\nfrom icvision.compat import label_components  # \u003c-- Only line that changes!\r\n\r\n# Classify components with ICVision (same API!)\r\nresult = label_components(raw, ica, method='icvision')\r\nprint(result['labels'])  # Same format: ['brain', 'eye blink', 'other', ...]\r\nprint(ica.labels_scores_.shape)  # Same shape: (n_components, 7)\r\n```\r\n\r\n### What You Get\r\n\r\n- **🎯 Identical API**: Same function signature, same return format\r\n- **📊 Same Output**: Returns dict with `'y_pred_proba'` and `'labels'` keys\r\n- **⚙️ Same ICA Modifications**: Sets `ica.labels_scores_` and `ica.labels_` exactly like ICLabel\r\n- **🚀 Enhanced Intelligence**: OpenAI Vision API instead of fixed neural network\r\n- **💡 Detailed Reasoning**: Each classification includes explanation (available in full API)\r\n\r\n### Why Use ICVision over ICLabel?\r\n\r\n| Feature | ICLabel | ICVision |\r\n|---------|---------|----------|\r\n| **Classification Method** | Fixed neural network (2019) | OpenAI Vision API (latest models) |\r\n| **Accuracy** | Good on typical datasets | Enhanced with modern vision AI |\r\n| **Reasoning** | No explanations | Detailed reasoning for each decision |\r\n| **Customization** | Fixed model | Customizable prompts and models |\r\n| **Updates** | Static model | Benefits from OpenAI improvements |\r\n| **API Compatibility** | ✅ Original | ✅ Drop-in replacement |\r\n\r\n### Integration Example\r\n\r\nThe compatibility layer works seamlessly with existing MNE workflows:\r\n\r\n```python\r\ndef analyze_ica_components(raw, ica, method='icvision'):\r\n    \"\"\"Generic function that works with both ICLabel and ICVision\"\"\"\r\n\r\n    if method == 'icvision':\r\n        from icvision.compat import label_components\r\n    else:\r\n        from mne_icalabel import label_components\r\n\r\n    # Same API for both!\r\n    result = label_components(raw, ica, method=method)\r\n\r\n    # Same return format for both\r\n    print(f\"Classified {len(result['labels'])} components\")\r\n\r\n    # Same ICA object modifications for both\r\n    brain_components = ica.labels_['brain']\r\n    artifact_components = [idx for key, indices in ica.labels_.items()\r\n                          if key != 'brain' for idx in indices]\r\n\r\n    print(f\"Brain components: {brain_components}\")\r\n    print(f\"Artifact components: {artifact_components}\")\r\n\r\n    return result\r\n\r\n# Works with either classifier\r\nresult = analyze_ica_components(raw, ica, method='icvision')\r\n```\r\n\r\n### Two APIs, Same Power\r\n\r\nICVision provides **two complementary interfaces**:\r\n\r\n1. **Original ICVision API**: Rich output with detailed results and file generation\r\n   ```python\r\n   from icvision.core import label_components\r\n   raw_cleaned, ica_updated, results_df = label_components(...)\r\n   ```\r\n\r\n2. **ICLabel-Compatible API**: Simple output matching ICLabel exactly\r\n   ```python\r\n   from icvision.compat import label_components\r\n   result = label_components(raw, ica, method='icvision')\r\n   ```\r\n\r\nChoose the API that best fits your workflow - both use the same underlying OpenAI Vision classification.\r\n\r\n---\r\n\r\n## Configuration Details\r\n\r\n### Input File Support\r\n\r\n**EEGLAB .set files:**\r\n- **Raw data**: Supports EEGLAB `.set` files for raw EEG data\r\n- **ICA data**: Now supports automatic ICA detection from `.set` files using `mne.preprocessing.read_ica_eeglab()`\r\n- **Single file mode**: Use just a `.set` file when it contains both raw data and ICA decomposition\r\n\r\n**MNE formats:**\r\nOther supported formats include:\r\n- **Raw data**: `.fif`, `.edf`, `.raw`\r\n- **ICA data**: `.fif` files containing MNE ICA objects\r\n\r\n### Default Parameter Values\r\n\r\n| Parameter | Default Value | Description |\r\n|-----------|---------------|-------------|\r\n| `model_name` | `\"gpt-4.1\"` | OpenAI model for classification (also supports `gpt-5.2`) |\r\n| `base_url` | `None` | Custom API endpoint (uses `OPENAI_BASE_URL` env var if set) |\r\n| `layout` | `\"single\"` | Classification mode: `\"single\"` or `\"strip\"` |\r\n| `strip_size` | `9` | Components per strip image (when `layout=\"strip\"`) |\r\n| `reasoning_effort` | `None` | Reasoning effort for gpt-5.x: `none`, `low`, `medium`, `high` |\r\n| `psd_fmax` | `45.0` | Maximum frequency for PSD plots (Hz) |\r\n| `confidence_threshold` | `0.8` | Minimum confidence for auto-exclusion |\r\n| `auto_exclude` | `True` | Automatically exclude artifact components |\r\n| `labels_to_exclude` | `[\"eye\", \"muscle\", \"heart\", \"line_noise\", \"channel_noise\", \"other_artifact\"]` | Labels to exclude (all non-brain) |\r\n| `output_dir` | `\"./autoclean_icvision_results\"` | Output directory for results |\r\n| `generate_report` | `True` | Generate PDF report |\r\n| `batch_size` | `10` | Components per API request |\r\n| `max_concurrency` | `4` | Maximum parallel API requests |\r\n| `api_key` | `None` | Uses `OPENAI_API_KEY` environment variable |\r\n| `custom_prompt` | `None` | Uses built-in classification prompt |\r\n\r\n### Component Labels\r\n\r\nThe standard set of labels ICVision uses (and expects from the API) are:\r\n- `brain` - Neural brain activity (retained)\r\n- `eye` - Eye movement artifacts\r\n- `muscle` - Muscle artifacts\r\n- `heart` - Cardiac artifacts\r\n- `line_noise` - Electrical line noise\r\n- `channel_noise` - Channel-specific noise\r\n- `other_artifact` - Other artifacts\r\n\r\nThese are defined in `src/icvision/config.py`.\r\n\r\n### Output Files\r\n\r\nICVision creates organized output files with input filename prefixes to prevent overwrites when processing multiple datasets:\r\n\r\n*   `{basename}_icvis_classified_ica.fif`: MNE ICA object with labels and exclusions\r\n*   `{basename}_icvis_results.csv`: Detailed classification results per component\r\n*   `{basename}_icvis_cleaned_raw.{format}`: Cleaned EEG data with artifacts removed\r\n*   `{basename}_icvis_summary.txt`: Summary statistics by label type\r\n*   `{basename}_icvis_report_all_comps.pdf`: Comprehensive PDF report (if enabled)\r\n*   `component_IC{N}_vision_analysis.webp`: Individual component plots used for API classification\r\n\r\n**Example**: Processing `sub-01_task-rest_eeg.set` creates files like:\r\n- `sub-01_task-rest_eeg_icvis_results.csv`\r\n- `sub-01_task-rest_eeg_icvis_classified_ica.fif`\r\n- `sub-01_task-rest_eeg_icvis_cleaned_raw.set`\r\n\r\n**Multi-file Processing**: All results are saved to the same `autoclean_icvision_results/` directory, with basename prefixes ensuring no conflicts:\r\n```bash\r\nautoclean_icvision_results/\r\n├── sub-01_task-rest_eeg_icvis_results.csv\r\n├── sub-01_task-rest_eeg_icvis_classified_ica.fif\r\n├── sub-02_task-rest_eeg_icvis_results.csv\r\n├── sub-02_task-rest_eeg_icvis_classified_ica.fif\r\n└── pilot_data_icvis_results.csv\r\n```\r\n\r\n### Custom Classification Prompt\r\n\r\nThe default prompt is optimized for EEG component classification on EGI128 nets. You can customize it by:\r\n- **CLI**: `--prompt-file /path/to/custom_prompt.txt`\r\n- **Python API**: `custom_prompt=\"Your custom prompt here\"`\r\n- **View default**: Check `src/icvision/config.py`\r\n\r\n### OpenAI API Costs\r\n\r\nICVision automatically tracks and estimates OpenAI API costs during processing:\r\n\r\n**Typical Costs (2025-05-29 pricing)**:\r\n- **gpt-4.1**: ~$0.0012 per component\r\n- **gpt-4.1-mini**: ~$0.0002 per component (recommended)\r\n- **gpt-4.1-nano**: ~$0.0001 per component (budget option)\r\n\r\n**Example costs for full ICA analysis**:\r\n- 10 components: $0.0006-0.012 depending on model\r\n- 30 components: $0.002-0.036 depending on model\r\n- 64 components: $0.004-0.077 depending on model\r\n\r\nCost estimates are automatically logged during processing. Use `--verbose` flag to see detailed per-component cost tracking.\r\n\r\n### Logging and Verbosity\r\n\r\nICVision provides two logging modes for different use cases:\r\n\r\n**Normal Mode** (Default - Clean output for researchers):\r\n```bash\r\nautoclean-icvision data.set\r\n# Output:\r\n# 2025-05-29 13:33:43 - INFO - Starting ICVision CLI v0.1.0\r\n# 2025-05-29 13:33:44 - INFO - OpenAI classification complete. Processed 20/20 components\r\n# 2025-05-29 13:33:45 - INFO - ICVision workflow completed successfully!\r\n```\r\n\r\n**Verbose Mode** (Detailed debugging information):\r\n```bash\r\nautoclean-icvision data.set --verbose\r\n# Output:\r\n# 2025-05-29 13:33:43 - icvision - INFO - Verbose logging enabled - showing module details\r\n# 2025-05-29 13:33:44 - icvision.core - DEBUG - Loading and validating input data...\r\n# 2025-05-29 13:33:45 - icvision.api - DEBUG - Response ID: resp_123..., Tokens: 400/50, Cost: $0.001200\r\n# 2025-05-29 13:33:45 - icvision.plotting - DEBUG - Plotting progress: 10/20 components completed\r\n```\r\n\r\n**Verbose mode provides**:\r\n- Module-level debugging information\r\n- Detailed OpenAI API cost tracking per component\r\n- Progress indicators for long-running operations\r\n- External library logging (httpx, openai, etc.)\r\n- Full error stack traces for troubleshooting\r\n\r\n**Use verbose mode when**:\r\n- Debugging processing issues\r\n- Monitoring API costs in detail\r\n- Contributing to development\r\n- Troubleshooting unexpected behavior\r\n\r\n## Development\r\n\r\nContributions are welcome! Please see `CONTRIBUTING.md` for guidelines.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the `LICENSE` file for details.\r\n\r\n## Citation\r\n\r\nIf you use ICVision in your research, please consider citing it (details to be added upon publication/DOI generation).\r\n\r\n## Acknowledgements\r\n\r\n*   This project relies heavily on the [MNE-Python](https://mne.tools/) library.\r\n*   Utilizes the [OpenAI API](https://openai.com/api/).\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcincibrainlab%2Fautocleaneeg-icvision","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcincibrainlab%2Fautocleaneeg-icvision","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcincibrainlab%2Fautocleaneeg-icvision/lists"}