Skip to content

QUICKSTART.md

Latest commit

 

History

History
216 lines (151 loc) · 6.1 KB

QUICKSTART.md

File metadata and controls

216 lines (151 loc) · 6.1 KB
Raw

Spyglass Quickstart

Get from zero to analyzing neural data with Spyglass in just a few commands.

Choose Your Path

Joining an Existing Lab? (Recommended)

If you received database credentials from your lab admin, this is you! The installer will:

  • Set up your development environment
  • Connect you to your lab's existing database
  • Prompt you to change your temporary password
  • Configure all necessary directories

Time: ~5 minutes | Database: Connect to lab's existing database

Trying Spyglass Locally?

Want to explore Spyglass features without joining a lab? The installer can:

  • Set up a local trial database using Docker
  • Create an isolated test environment
  • Let you experiment with sample data

Time: ~10 minutes | Database: Local Docker container (requires Docker Desktop)

Prerequisites

  • Python: Version 3.10 or higher
  • Disk Space: ~10GB for installation + data storage
  • Operating System: macOS or Linux (Windows experimental)
  • Package Manager: conda (23.10.0+ recommended) or mamba

If you don't have mamba/conda, install miniforge first.

Installation (2 steps)

Step 1: Run the installer

# Clone the repository
git clone https://github.com/LorenFrankLab/spyglass.git
cd spyglass

# Run interactive installer
python scripts/install.py

The installer will prompt you to choose:

  1. Installation type: Minimal (recommended) or Full
  2. Database setup:
    • Remote (recommended for lab members) - Connect to lab's existing database
    • Docker - Local trial database for testing
    • Skip - Configure manually later

If joining a lab, you'll be prompted to change your password during installation.

Step 2: Validate installation

# Activate the environment
conda activate spyglass

# Run validation
python scripts/validate.py

That's it! Setup complete in ~5-10 minutes.

Next Steps

Run first tutorial

cd notebooks
jupyter notebook 01_Concepts.ipynb

Configure for your data

  • Place NWB files in your configured raw directory (default: $SPYGLASS_BASE_DIR/raw/)
  • See Data Import Guide for details

Join community

Installation Options

Need something different? The installer supports these options:

python scripts/install.py --minimal        # Core dependencies only (~5 min)
python scripts/install.py --full           # All optional dependencies (~15 min)
python scripts/install.py --docker         # Set up local Docker database
python scripts/install.py --remote         # Connect to existing database
python scripts/install.py --env-name myenv # Custom conda environment name
python scripts/install.py --help           # See all options

What Gets Installed

The installer creates:

  • Conda environment with Spyglass and core dependencies
  • Database connection (remote lab database OR local Docker container)
  • Data directories in ~/spyglass_data/
  • Jupyter environment for running tutorials

Troubleshooting

Installation fails?

# Remove environment and retry
conda env remove -n spyglass
python scripts/install.py

Validation fails?

  1. Check error messages for specific issues
  2. If using Docker database, ensure Docker Desktop is running
  3. If database connection fails, verify credentials with your lab admin
  4. Skip database setup and configure later: choose "Skip" when prompted

Need help?

For Lab Administrators

If you're setting up Spyglass for your lab, you can pre-configure lab-wide settings so new members don't need to enter them manually.

Lab-Wide vs User-Specific Settings

Setting Lab-Wide User-Specific
Database host ✅
Database port ✅
Base data directory ✅
Kachery zone ✅
Database username ✅
Database password ✅

Option 1: Environment Variables (Recommended)

Add to your shared machine's profile (e.g., /etc/profile.d/spyglass.sh):

# Lab-wide Spyglass configuration
export SPYGLASS_BASE_DIR="/your/lab/shared/data"

New members run the installer and only need to enter their credentials:

python scripts/install.py --remote \
    --db-host your-db-server.edu \
    --db-user $USER
# Password prompted securely

Option 2: Lab-Specific Setup Script

Create a wrapper script for your lab. See scripts/setup_franklab.sh for an example that pre-configures Frank Lab settings.

# For Frank Lab members:
./scripts/setup_franklab.sh

What to Tell New Lab Members

  1. SSH to your shared server
  2. Clone the repository: git clone https://github.com/LorenFrankLab/spyglass.git
  3. Run the installer (or your lab's setup script)
  4. Enter their database username and temporary password
  5. Change their password when prompted

Next tutorial: 01_Concepts.ipynb Full documentation: lorenfranklab.github.io/spyglass