MPS

📚 Miniscope Processing Pipeline Guide

Overview

This guide walks through the complete miniscope calcium imaging processing pipeline.

Quick Start

  1. Initial Setup
    • Install and launch MPS (Windows installer or macOS app)
  2. Loading Data
    • New Analysis: Start at Step 1 (Project Configuration)
    • Existing Analysis:
      • File → Load parameters file
      • Load previous data and choose the step to resume
      • Automation → Toggle / Run (all or from current)
License: Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Table of Contents

Getting Started

Initial Setup

Launch MPS from the installer-created shortcut (Windows) or the app bundle (macOS).

Load Data

  • File → Load parameters file (optional)
  • Enable automation to run multi-step pipelines unattended
  • Resume from previous cache by selecting the directory and target step

Pipeline Steps

Step 1: Project Configuration

Required inputs:

  • Animal ID
  • Session ID
  • Input directory
  • Output directory

Advanced: Dask workers (8), memory limits, % of video for tests.

Step 2: Data Preprocessing

2a: File Pattern Recognition
  • Regex for your video files (.avi default works)
  • Use an LLM to draft regex from an example path
2b: Background Removal & Denoising

Denoising: Median, Gaussian, Bilateral, Anisotropic (trade speed/edges).

Background: Tophat (robust), Uniform (fast/simple).

2c: Motion Correction
  • "frame" mode; expect high RAM usage
  • Recursive phase correlation
2d: Quality Control
  • Threshold factor: SDs above mean to drop frames
2e: Data Validation
  • Keep fill=0; validate transformed data
2f: Preview Results
  • Subset check; saves only stats

Step 3: Spatial Cropping & Initialization

3a: ROI
  • Keep crop tight; test on 10% data first
3b: NNDSVD Initialization
  • Components, power iters, sparsity, reg, chunk size
3c: Early Analysis Option

Some workflows stop here for prelim results.

Step 4: Component Detection

4a: Watershed Search
  • Min distances, threshold relativity, sigma values, sample size
4b: Apply Best Params
4c: Merging Units
4d: Temporal Extraction
4e: AC Initialization
4f: Final Component Prep
4g: Temporal Merging

Step 5: CNMF Preparation

5a: Noise Estimation
5b: Validation & Setup

Step 6: CNMF Processing

6a: YrA Computation
6b: YrA Validation
6c: Parameter Suggestion
6d: Update Temporal Components
6e: Filter & Validate

Step 7: Spatial Refinement

7a: Dilation
7b: Clustering
7c: Bounds
7d: Suggestions
7e: Spatial Update
7f: Merging & Validation

Step 8: Final Processing & Export

8a: YrA
8b: Final Temporal Update
8c: Filtering & Export (Zarr/NumPy/JSON/Pickle)

Tips & Best Practices

  1. Start small (10% data)
  2. Monitor memory
  3. Autosave
  4. Check intermediate steps (2f, 6b)
  5. Over-segment then merge
  6. Use temporal chunking for long videos

Common Issues & Solutions

Memory errors in YrA

  • Smaller batches; float32; raise dask memory

Fragmented components

  • Lower penalties; lower min-STD

Too many spurious units

  • Increase min size; conservative thresholds

Noisy traces

  • AR p=2; higher sparse penalty; verify noise map

Interpreting Results

Review A (spatial), C (calcium), S (spikes), QC metrics. Cross-check against videos.

Advanced Features

Line Splitting Detection

import numpy as np def detect_line_splitting_frames(xarray_data): left_edge = xarray_data.isel(width=slice(0, 20)) left_edge_means = left_edge.mean(dim=['height','width']).compute() overall_mean = left_edge_means.mean().item() overall_std = left_edge_means.std().item() threshold = overall_mean + 2 * overall_std return np.where(left_edge_means > threshold)[0].tolist()

Automation

  • Automation → Toggle Autorun / Run All / Run From Current
  • Save & load parameter files between datasets