Pre-Training Setup Guide

Numbers EEG Source Analysis Pipeline - New User Onboarding

Complete these steps BEFORE our first meeting. This will take approximately 45-60 minutes.

Overview

This guide is organized into two phases:

1. PHASE 1: Download & Install Software (20-30 min) - Get all the tools you need
2. PHASE 2: Setup Project & Data (20-30 min) - Clone the code, add data, and configure everything

What you'll need:

• Cursor IDE (code editor)
• Git (version control)
• Miniforge (Python package manager)
• EEG data (~1.7 GB download - we'll get this in Phase 2)

Important: We'll be doing almost everything inside Cursor IDE's built-in terminal. You can also use your operating system's terminal if you prefer.

PHASE 1: Download & Install Software

Install these three tools before moving to Phase 2.

Step 1: Install Cursor IDE

Cursor is an AI-powered code editor with a built-in terminal. We'll use Cursor for everything.

Official Website: https://cursor.com

Quick Introduction Video (4 minutes): Introduction to Cursor
Note: This video is about 10 months old, so Cursor looks a little different now, but it gives you a good idea of what you're downloading.

Why Cursor?

• AI-powered code completion and suggestions
• Built-in terminal (we'll use this for all commands!)
• Works with all VS Code extensions
• Available on Windows, macOS, and Linux

Windows

1. Go to https://cursor.com/download
2. Click "Download for Windows"
3. Run the downloaded .exe file
4. Follow the installation wizard (default settings are fine)

macOS

1. Go to https://cursor.com/download
2. Click "Download for macOS"
3. Open the downloaded .dmg file
4. Drag Cursor to your Applications folder

Linux

1. Go to https://cursor.com/download
2. Download the AppImage for your architecture (x86_64 for most systems)
3. Make it executable: chmod +x Cursor-*.AppImage

Don't open Cursor yet! We'll open it to the project folder after we clone the repository.

Step 2: Install Git

Git is version control software that lets you download and manage code.

Why Git?

• Keeps your code up-to-date with the latest fixes and features
• Required to clone (download) the repository

Windows

1. Download Git from: https://git-scm.com/download/win
2. Run the installer (accept default options)
3. Verify in your OS terminal (PowerShell or Command Prompt):
   • Open PowerShell (search "PowerShell" in Start menu)
   • Type: git --version
   • You should see something like git version 2.x.x

macOS

1. Open Terminal (Applications → Utilities → Terminal)
2. Type: git --version
3. If not installed, macOS will prompt you to install Xcode Command Line Tools
   • Click "Install" and follow prompts
   • OR install via Homebrew: brew install git
4. Verify: git --version

Linux (Ubuntu/Debian)

Open your terminal and run:

sudo apt-get update
sudo apt-get install git
git --version

Step 3: Install Miniforge (Python)

Miniforge is a lightweight conda installer that will manage Python and all scientific packages.

Note: If you already have Conda or Anaconda installed, you can skip Miniforge.

Why Miniforge?

• Installs Python and manages all scientific packages needed for EEG analysis
• Creates isolated environments so packages don't conflict with each other
• Automatically handles complex dependencies (MNE, NumPy, SciPy, etc.)
• Makes it easy to reproduce the exact same setup on different computers

Windows

1. Download Miniforge: https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe
2. Run the installer
3. IMPORTANT: Check the box "Add Miniforge to my PATH environment variable"
4. Complete installation
5. Verify in your OS terminal (PowerShell):

conda --version

You should see conda 24.x.x or similar

macOS

In your OS Terminal (Applications → Utilities → Terminal), run:

Note: You can run this from any directory - it will install Miniforge to your home folder by default.

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-$(uname -m).sh"
bash Miniforge3-MacOSX-$(uname -m).sh

Follow the installation prompts:

1. Press Enter to continue through the welcome screen

2. Read the license (keep pressing Enter to scroll), then type "yes" to accept

3. Press Enter to confirm the installation location (/Users/yourname/miniforge3)

4. When asked about conda init, type "yes" (this allows conda to work in any terminal)

The installer will ask: "Do you wish to update your shell profile to automatically initialize conda?" - Type yes

5. Installation complete!

6. Close and reopen Terminal, then verify: conda --version

You should see conda 24.x.x or similar. Your terminal prompt may now show (base) - this is normal and means conda is active.

Linux

In your terminal, run:

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh"
bash Miniforge3-Linux-x86_64.sh
# Follow prompts
# Close and reopen terminal
conda --version

✅ Phase 1 Checkpoint

Before moving to Phase 2, verify you have:

• Git installed (git --version works)
• Cursor IDE installed (application launches)
• Miniforge installed (conda --version works)

If any of these failed, check the Troubleshooting section at the bottom before continuing.

PHASE 2: Setup Project & Data

Now we'll clone the project, add the data, and configure everything.

Step 5: Clone the GitHub Repository

Now we'll download the analysis code from GitHub using your OS terminal (PowerShell/Terminal/Command Prompt).

Choose a Location

Pick a location for the project. Recommended:

• Windows: C:/Users/YourName/Projects/ or D:/Projects/
• macOS: ~/Projects/ or ~/Documents/
• Linux: ~/Projects/ or ~/workspace/

Clone Using Your OS Terminal

Open your OS terminal (the same one you used to verify Git installation) and run:

Windows:

# Create Projects folder if it doesn't exist
mkdir C:/Users/YourName/Projects/ -ErrorAction SilentlyContinue

# Navigate there
cd C:/Users/YourName/Projects/

# Clone the repository
git clone https://github.com/yurigushiken/numbers_eeg_source.git

# Enter the project directory
cd numbers_eeg_source

macOS/Linux:

# Create Projects folder if it doesn't exist
mkdir -p ~/Projects/

# Navigate there
cd ~/Projects/

# Clone the repository
git clone https://github.com/yurigushiken/numbers_eeg_source.git

# Enter the project directory
cd numbers_eeg_source

Open the Project in Cursor

Now that the repository is cloned, launch Cursor and open the project folder:

1. Launch Cursor (if not already open)
2. Go to File → Open Folder (or File → Open on macOS)
3. Navigate to the numbers_eeg_source folder you just cloned
4. Click "Select Folder" (or "Open" on macOS)

From now on, we'll use Cursor's built-in terminal for all commands!

To open Cursor's terminal: Press Ctrl + ` (Windows/Linux) or Cmd + ` (macOS)

Step 6: Download and Move the EEG Data

Now that you have the project cloned, let's add the EEG data (approximately 1.7 GB).

Goal: Your Final Project Structure

Here's what we're aiming for - your data folder should end up in the project root:

numbers_eeg_source/                    ← Your project root
│
├── code/                              ← Python analysis scripts
├── configs/                           ← YAML configuration files
├── new_user/                          ← Training materials
├── assets/                            ← EEG montage files
├── data/                              ← Your data folder!
│   └── data_preprocessed/
│       └── hpf_1.5_lpf_35_baseline-on/
│           ├── sub-02_preprocessed-epo.fif
│           ├── sub-02/
│           ├── sub-03_preprocessed-epo.fif
│           └── ... (more subjects)
├── environment.yml
└── README.md

Download the Data

🔗 Google Drive: https://drive.google.com/drive/folders/1N_UNP1LtLRItqV5NyaFNz6h1iuHqiH5F?usp=drive_link

1. Click the link above (you may need to sign in to Google)
2. You'll see a folder called data
3. Download the entire data folder:
   • Right-click on the data folder
   • Select "Download"
   • Google Drive will create a .zip file (this may take 5-10 minutes)
4. Save the zip file to your Downloads folder
5. Extract the zip file
   • The extracted folder should be called data

Move Data to Project

1. Open your file explorer (Windows Explorer, Finder on Mac, or your file manager on Linux)
2. Navigate to your Downloads folder
3. Find the data folder you extracted
4. Cut (or copy) the data folder:
   • Windows: Right-click → Cut (or Ctrl+X)
   • macOS: Right-click → Copy (or Cmd+C)
   • Linux: Right-click → Cut (or Ctrl+X)
5. Navigate to your numbers_eeg_source project folder
6. Paste the data folder into the root of the project:
   • Windows: Right-click → Paste (or Ctrl+V)
   • macOS: Right-click → Paste (or Cmd+V)
   • Linux: Right-click → Paste (or Ctrl+V)

That's it! Your data folder should now be in the project root, matching the structure shown above.

Step 7: Create Python Environment

Now we'll create a dedicated Python environment with all required packages using Cursor's terminal.

The project includes an environment.yml file that specifies all the packages you need. This ensures everyone has the exact same setup!

Create the Environment

In Cursor's terminal, make sure you're in the project directory, then run:

# Make sure you're in the project root
pwd  # Check your location first

# Create environment from file
conda env create -f environment.yml

# This will take 5-10 minutes to download and install all packages

macOS users: You'll see this in your terminal:

This single command will:

• Create an environment named numbers_eeg_source
• Install Python 3.11
• Install all required packages (MNE, NumPy, SciPy, PyVista, and more)

Activate the Environment

Once the environment is created, activate it in Cursor's terminal:

conda activate numbers_eeg_source

macOS users: After activating, you'll see the environment name in your prompt:

How to tell if it's activated:

• Your prompt will show (numbers_eeg_source) at the beginning
• Example: (numbers_eeg_source) C:\Users\YourName>

Verify Installation

With the environment activated in Cursor's terminal, run these tests:

# Test MNE
python -c "import mne; print(f'MNE version: {mne.__version__}')"

# Test PyVista (3D visualization)
python -c "import pyvista; print('PyVista OK')"

# Test all imports
python -c "import mne, numpy, scipy, pandas, matplotlib; print('All packages OK!')"

You should see output like:

MNE version: 1.x.x
PyVista OK
All packages OK!

Step 8: Explore the Project Structure

Now that Cursor is open with your project, let's see what's inside.

Project Structure

You should see these folders in Cursor's sidebar:

• code/ - Python analysis scripts
• configs/ - YAML configuration files
• new_user/ ← Start here!
• data/ ← Your EEG data
• assets/ - Montage files
• environment.yml - Environment spec
• requirements.txt - Package list

Step 9: Select Python Interpreter in Cursor

THIS IS CRITICAL! Cursor needs to know which Python interpreter to use.

Why do this? This tells Cursor to always use the numbers_eeg_source environment when running Python code. Without this, Cursor might use a different Python installation that doesn't have the required packages (MNE, NumPy, etc.), and your code won't work.

Select the Interpreter

1. With Cursor open, press:
   • Windows/Linux: Ctrl + Shift + P
   • macOS: Cmd + Shift + P
2. In the command palette, type: Python: Select Interpreter
3. Select the interpreter that says numbers_eeg_source:
   • Look for entries like:
     • Python 3.11.x ('numbers_eeg_source': conda)
     • Path examples:
       • Windows: C:\Users\YourName\miniforge3\envs\numbers_eeg_source\python.exe
       • macOS: /Users/YourName/miniforge3\envs/numbers_eeg_source/bin/python
       • Linux: /home/YourName/miniforge3/envs/numbers_eeg_source/bin/python
4. Click on it to select it

Verify the Interpreter is Selected

You should now see the environment displayed at the top of Cursor, confirming it's selected:

This ensures Cursor always uses the correct Python environment with all your installed packages.

Step 10: Test the Pipeline!

Let's make sure everything works by running the example analysis in Cursor's terminal.

Understanding the Config Files

Inside new_user/configs/ you'll find:

• 13_31/ - Example analysis comparing transitions 1→3 vs 3→1
• templates/ - Template files to copy when creating your own analyses

Run the Example Analysis

In Cursor's terminal, run:

Windows:

# Make sure environment is activated
conda activate numbers_eeg_source

# Run the script with the example config
.\new_user\run_analysis.bat new_user/configs/13_31/sensor_13_31.yaml

macOS/Linux:

# Make sure environment is activated
conda activate numbers_eeg_source

# Run the analysis
python -m code.run_full_analysis_pipeline --config new_user/configs/13_31/sensor_13_31.yaml --accuracy all

Note: You must specify the sensor-space config file. If the sensor analysis finds significant results, it will automatically run the source-space analyses. This is the proper workflow for running the pipeline!

What to Expect

The pipeline will:

1. Load your specified configuration
2. Run sensor-space analysis (~2-5 minutes)
3. If significant clusters found, run source-space analyses
4. Generate reports in new_user/derivatives/

[SCREENSHOT: Pipeline completing successfully with final output messages]

If successful, you're ready for the meeting! 🎉

Step 11: Run the Setup Checker

We've created an automated checker script that verifies everything is set up correctly.

Run the Checker

In Cursor's terminal, run:

python new_user/check_setup.py

The script will check:

• Git installation
• Conda/Miniforge installation
• Project structure
• Data directory and files
• All required Python packages

What to Expect

If everything is set up correctly, you'll see:

SUCCESS! Your setup is complete!
You are ready for the first training meeting.

If there are any issues, the script will show you exactly what needs to be fixed.

✅ Final Checklist: Are You Ready?

Before the meeting, verify ALL of these:

• ✅ Git installed (git --version works)
• ✅ Cursor IDE installed (application launches)
• ✅ Miniforge installed (conda --version works)
• ✅ Data downloaded and moved (data/ folder is in project root)
• ✅ Repository cloned (numbers_eeg_source/ folder exists)
• ✅ Python environment created (conda activate numbers_eeg_source works)
• ✅ Packages installed (python -c "import mne" works without errors)
• ✅ Cursor configured (bottom-right shows Python 3.11.x ('numbers_eeg_source'))
• ✅ Test run successful (example analysis ran without errors)

Troubleshooting

Git Issues

"Git clone failed with authentication error"

• The repository may be private. Ask your lab for access permissions.
• You may need to set up SSH keys or a Personal Access Token (PAT).

Data Issues

"Can't find the data_preprocessed folder on Google Drive"

• Make sure you're logged into the correct Google account.
• Ask your lab manager for access to the shared drive.

"Data folder is huge (several GB)!"

• The full dataset with all preprocessing variants is large.
• You only need: hpf_1.5_lpf_35_baseline-on/
• You can delete other preprocessing folders if needed to save space.

Cursor Issues

"Cursor won't open on macOS - 'App is damaged'"

• This is a security warning.
• Go to System Preferences → Security & Privacy
• Click "Open Anyway" next to the Cursor warning

"Cursor doesn't show my conda environment in interpreter list"

• Make sure conda is initialized: conda init
• Restart Cursor after creating the environment
• Try entering the full path manually:
  • Ctrl+Shift+P → "Python: Select Interpreter" → "Enter interpreter path"

Conda/Environment Issues

"conda: command not found" after installing Miniforge

• You need to restart your terminal/PowerShell
• Or manually initialize: conda init bash (or conda init zsh for macOS)
• Then restart terminal

"Package installation failed with conflicts"

• Try creating a fresh environment:

conda remove -n numbers_eeg_source --all
conda env create -f environment.yml

• If still failing, try Method 2 (manual installation) one package at a time

"Python says 'No module named mne' even after installation"

• Make sure you activated the environment: conda activate numbers_eeg_source
• Check that Cursor is using the correct interpreter (Ctrl+Shift+P → "Python: Select Interpreter")
• Verify which Python you're using:
  • macOS/Linux: which python
  • Windows: where python

"PyVista/VTK installation fails"

• These packages can be tricky on some systems
• Try installing separately: conda install -c conda-forge pyvista -y
• On older Macs, you may need to use pip: pip install pyvista

Shell Script Issues

"Permission denied when running shell scripts"

• Make the script executable: chmod +x new_user/run_analysis.sh

"Error: No config file specified!"

• You must provide the config file path as an argument
• Example: .\new_user\run_analysis.bat new_user/configs/13_31/sensor_13_31.yaml

"conda: command not found" (macOS)

• This means conda was not initialized during Miniforge installation
• Solution: Initialize conda manually:

  ~/miniforge3/bin/conda init zsh
  

• Then close and reopen Terminal
• Verify: conda --version
• If you followed the updated instructions and said "yes" to conda init during installation, this shouldn't happen

"conda activate does nothing" (Windows)

• The command runs but the environment doesn't activate (no (numbers_eeg_source) appears)
• This means Miniforge was not added to PATH during installation
• Quick solution: Use Miniforge Prompt instead of regular terminal:
  1. Open "Miniforge Prompt" from Windows Start Menu
  2. Navigate to project: cd path\to\numbers_eeg_source
  3. Run: conda env create -f environment.yml
  4. Run: conda activate numbers_eeg_source
• Proper fix: Reinstall Miniforge and check the "Add Miniforge to my PATH environment variable" box

"TypeError: data type '>a' not understood" (macOS Apple Silicon)

• This occurs on M1/M2/M3 Macs with older package versions
• Solution: Update MNE and NumPy to compatible versions:

  conda activate numbers_eeg_source
  conda install -c conda-forge "mne>=1.7" "numpy>=2.0" -y
  

• Then re-run your analysis
• Note: The updated environment.yml file already includes these requirements for new installations

Next Steps

Once you've completed this setup:

1. Read the Quickstart Guide: new_user/README.md
2. Explore the examples: Look at new_user/examples/sensor_13_31.yaml
3. Try creating your own analysis (follow the README guide)
4. Join the meeting ready to code!

Quick Reference Card

Project Repository: https://github.com/yurigushiken/numbers_eeg_source

Data Location: data/data_preprocessed/hpf_1.5_lpf_35_baseline-on/

Environment Files:

• environment.yml - Create with: conda env create -f environment.yml
• requirements.txt - Or use pip: pip install -r requirements.txt

Key Commands to Remember:

# ALWAYS activate before running analyses!
conda activate numbers_eeg_source

# Select Python interpreter in Cursor:
# Ctrl+Shift+P (Win/Linux) or Cmd+Shift+P (Mac)
# Type: "Python: Select Interpreter"

Questions?

If you have questions or run into issues, please email: mkg2145@tc.columbia.edu

We will try to get it set up and running before the first meeting.