Python-Based EEG Processing#

This tutorial shows how to process EEG data using AutoClean’s Python API with file manager navigation and the Config Wizard for creating custom tasks.

What You Need#

  • Python environment with AutoClean installed

  • EEG data files in supported formats (.raw, .set, .eeg, .bdf, .fif)

  • Access to your system’s file manager (Finder, File Explorer, Files)

  • Web browser for the Config Wizard

Setup Your Environment#

Install and set up AutoClean:

# Install if needed
import subprocess
subprocess.run(["pip", "install", "autocleaneeg"])

# Set up workspace
subprocess.run(["autoclean", "setup"])

This creates your workspace folder (typically ~/Documents/AutoClean-EEG) with the drop-and-go structure.

Basic Processing with Built-in Tasks#

Start by processing data with AutoClean’s built-in tasks:

from autoclean import Pipeline
from pathlib import Path

# Initialize pipeline
pipeline = Pipeline(output_dir="my_results")

# Use file manager to find your data file path
data_file = "/path/to/your/data.raw"  # Copy path from file manager

# Process with a built-in task
pipeline.process_file(data_file, task="RestingEyesOpen")

Available Built-in Tasks: - RestingEyesOpen - Resting state with eyes open - ASSR - Auditory steady-state response - ChirpDefault - Chirp auditory stimuli - HBCD_MMN - Mismatch negativity - StatisticalLearning - Statistical learning paradigms

Creating Custom Tasks with Config Wizard#

For your specific experimental needs, create custom tasks using the web-based Config Wizard:

Step 1: Open the Config Wizard

Navigate to https://cincibrainlab.github.io/Autoclean-ConfigWizard/ in your web browser.

Step 2: Configure Your Task

  1. Select EEG System - Choose your hardware (e.g., EGI, BrainVision, BioSemi)

  2. Choose Paradigm - Select your experimental type (resting, auditory, visual, etc.)

  3. Set Processing Options - Configure filtering, ICA, epoching parameters

  4. Download Task File - Get your custom Python task file

Step 3: Drop Into Workspace

Use your file manager to save the downloaded task file:

  1. Open your file manager (Finder/File Explorer/Files)

  2. Navigate to your AutoClean workspace (typically ~/Documents/AutoClean-EEG)

  3. Drop the downloaded Python file into the tasks folder

  4. Done! AutoClean automatically discovers the new task

Step 4: Use Your Custom Task

from autoclean import Pipeline

pipeline = Pipeline(output_dir="results")

# Your custom task is now available
pipeline.process_file("data.raw", task="MyCustomTask")

File Management with GUI#

Use your system’s file manager throughout the process:

Finding Data Files: 1. Open Finder/File Explorer/Files 2. Navigate to your EEG data folder 3. Right-click on files/folders to copy paths for Python scripts

Viewing Results: 1. Navigate to your output directory 2. Browse timestamped result folders 3. Open quality reports (HTML/PDF files) by double-clicking

Managing Tasks: 1. Open workspace tasks folder in file manager 2. Drag and drop new task files from downloads 3. Remove tasks by moving files to trash

Processing Multiple Files#

Use Python loops with file manager navigation for batch processing:

from pathlib import Path
from autoclean import Pipeline

# Use file manager to find your data directory
data_dir = Path("/path/to/data/folder")  # Copy from file manager
pipeline = Pipeline(output_dir="batch_results")

# Process all .raw files
for eeg_file in data_dir.glob("*.raw"):
    print(f"Processing: {eeg_file.name}")
    pipeline.process_file(str(eeg_file), task="RestingEyesOpen")

print("Batch processing complete!")

GUI Workflow for Batch Processing: 1. Use file manager to navigate to your data folder 2. Note the folder path for your Python script 3. Run the script to process all files 4. Use file manager to browse individual result folders

Complete Example#

Here’s a complete workflow from setup to results:

from pathlib import Path
from autoclean import Pipeline

# Step 1: Setup (run once)
import subprocess
subprocess.run(["autoclean", "setup"])

# Step 2: Create custom task at Config Wizard
# Visit: https://cincibrainlab.github.io/Autoclean-ConfigWizard/
# Download task file and drop into workspace/tasks/ folder

# Step 3: Process your data
data_path = Path("/Users/researcher/EEG_Study/subject01.raw")
output_path = Path("/Users/researcher/Results")

pipeline = Pipeline(output_dir=str(output_path))
result = pipeline.process_file(str(data_path), task="MyCustomTask")

# Step 4: View results in file manager
print(f"Results saved to: {output_path}")
print("Open the folder in your file manager to view reports!")

This workflow integrates Python processing with familiar file management, making EEG analysis accessible while maintaining the power of programmatic control.

Real example:

autoclean process RestingEyesOpen subject001_rest.raw

What you’ll see: - Welcome message and setup information - Progress messages as AutoClean works - “Processing completed successfully!” when done

How long does it take? - Small files (< 10 minutes): 2-5 minutes - Medium files (10-60 minutes): 5-15 minutes - Large files (> 1 hour): 15-30 minutes

While it’s running: - Don’t close the command window - You can minimize it and do other work - Watch for any error messages

📊 Step 6: Find Your Results#

Check where results are saved:

autoclean config show

This shows your workspace location. Your results are in the “output” folder.

Navigate to your results:

# Go to your workspace output folder
cd Documents/Autoclean-EEG/output

# See what's there
ls    # Mac/Linux
dir   # Windows

What you’ll find:

output/
├── subject001_rest_TIMESTAMP/
│   ├── bids/                 # Processed data files
│   ├── logs/                 # Processing logs
│   ├── metadata/             # Reports and summaries
│   └── stage/                # Intermediate files

🔍 Step 7: View Your Results#

Open your results folder in file explorer:

# Windows
explorer Documents\Autoclean-EEG\output

# Mac
open ~/Documents/Autoclean-EEG/output

# Linux
xdg-open ~/Documents/Autoclean-EEG/output

Key files to look at:

metadata/run_report.pdf

Visual summary of processing results - open this first!

bids/derivatives/

Your cleaned EEG data ready for analysis

logs/

Detailed logs if you need to troubleshoot

📈 Step 8: Understanding Your Results#

Quality Control Report (run_report.pdf): - Shows before/after data comparison - Highlights removed artifacts - Provides data quality metrics - Red flags any potential issues

Look for: - ✅ Green indicators = good data quality - ⚠️ Yellow warnings = check these issues - ❌ Red errors = data may need attention

Processed Data Files: - Clean continuous EEG data - Artifact-free epochs (if applicable) - ICA components and artifact classifications

🆘 Troubleshooting Common Issues#

“Task not found” error:

# Check available tasks
autoclean list-tasks

# Make sure you typed the task name exactly

“File not found” error:

# Check you're in the right folder
pwd    # Mac/Linux
cd     # Windows

# List files to see exact names
ls     # Mac/Linux
dir    # Windows

Processing fails with errors: - Check the logs folder for detailed error messages - Ensure your EEG file isn’t corrupted - Try a different task if the current one doesn’t fit your data

No results appear: - Check that processing completed successfully - Look for error messages in the command window - Verify the output folder location with autoclean config show

🎉 Success! What’s Next?#

Congratulations! You’ve successfully processed your first EEG file with AutoClean.

Next steps:

  1. Analyze your results: Import the cleaned data into your analysis software

  2. Process more files: Use the same command with different filenames

  3. Learn batch processing: Process multiple files automatically

  4. Explore custom tasks: Create workflows specific to your experiments

Useful follow-up tutorials: - Understanding AutoClean Results - Deep dive into what AutoClean produces - Creating a Custom Task - Create workflows specific to your experiments - Command Line Basics for AutoClean - Learn more command line skills

💡 Tips for Success#

Keep good records: - Note which task you used for each experiment type - Save the processing logs for your records - Document any custom settings you use

Start simple: - Use built-in tasks when possible - Process one file first before doing batches - Review quality control reports carefully

Get help when needed: - Check our troubleshooting guide - Ask on the community forums - Contact your lab’s technical support

Happy analyzing! 🧠