LBM-Suite2p Quickstart

1. LBM-Suite2p Quickstart#

Example Dataset

Example dataset collected by Kevin Barber with Dr. Alipasha Vaziri @ Rockefeller University.

Field

Value

Animal

mk301

Date

2025-03-01

Virus

jGCaMP8s

Framerate

17 Hz

FOV

900 µm × 900 µm

Resolution

2 µm × 2 µm × 16 µm

For installation with all gui/notebook dependencies, the following imports could take up to a minute depending on system resources.

from pathlib import Path
import os
import matplotlib.pyplot as plt
import numpy as np
import suite2p
import mbo_utilities as mbo
import fastplotlib as fpl
from copy import deepcopy
import lbm_suite2p_python as lsp

See the assembly documentation for a guide on extracting data before input into suite2p.

Assembly TLDR

files = mbo.get_files("path/to/files", "tif", 2)
scan = mbo.read_scan(files)

# directory where you want to save the results
mbo.save_as(scan, "C://Users//RBO//data//")

Suite2p is primarily a 2D pipeline - we will run each z-plane sequentially and combine results at the end.

animal_path = Path(r"D:\W2_DATA\kbarber\2025_03_01\mk301")  # (optional) the parent directory for this session
assembled_path = animal_path.joinpath("assembled")          # where our assembled tiffs live

1.1. Input data#

The tifs we use as input are planar timeseries [Txy].

Raw ScanImage tiffs will not work here, as they are not in the correct frame order.

input_files = mbo.get_files(assembled_path, str_contains='tif', max_depth=3)

mbo_utilities.get_metadata() will retrieve the ScanImage metadata (frame rate, pixel resolution, image dimensions).

We then feed this metadata into mbo_utilities.params_from_metadata() to autofill the suite2p parameters that rely on these metadata.

metadata = mbo.get_metadata(input_files[0])
ops = suite2p.default_ops()
ops = mbo.params_from_metadata(metadata, ops)

# we filled in pixel resolution and frame rate
ops["dx"], ops["dy"], ops["fs"]

This ops object is the first argument to lbm_suite2p_python.run_plane().

We pick a single z-plane in our list of files for the second arugment to

input_file = Path(input_files[7]) # pick a zplane in the middle of the cavity for example
input_file

Pick somewhere to save the results.

For convenience, here we save to the same directory as this code is being run from.

save_path = Path("./results")
save_path.mkdir(exist_ok=True)
print(f"Saving suite2p results to:  {save_path.resolve()}")

1.2. Process a single z-plane#

ops = lsp.run_plane(
    ops=ops,
    input_tiff=input_file,
    save_path=save_path,
    save_folder = str(input_file.stem),  # strip the path and extension from this filename
    replot=True
)

1.2.1. Planar Outputs#

Previous users of Suite2p will regonize several files in their save_path::

  • ops.npy

  • stat.npy

  • spks.npy

  • iscell.npy

  • F.npy

  • Fneu.npy

Additionally, LBM-Suite2p-Python adds summary plots::

  • summary images (max-projection, mean-image)

  • Accepted/rejected masks drawn on summary image

  • 20 randomly selected DF/F traces

../_images/planar_output_files.png

Note that depending on your suite2p I/O parameters, you may have a few additional files i.e. /reg_tif if you set ops["reg_tif"]=True.

1.3. Process full volume#

To run the entire volume, lbm_suite2p_python.run_volume() takes the same inputs as its planar variant, except give the full list of input files rather than a single input tiff file.

output_ops = lsp.run_volume(ops, input_files, save_path)

Once that is finished, we can use get_files to get a list of all ops.npy files.

ops_files = mbo.get_files(save_path.parent, 'ops', 8)
ops_files

Or all stat.npy files:

stat_files = mbo.get_files(save_path.parent, 'stat.npy', max_depth=5)
stat_files[:3]

1.3.1. Volumetric Outputs#

A few new files are now present at the root directory::

  • f_concat.npy : Volumetric version of F.npy

  • volume_stats.npy : Contains signal quality, #accepted/rejected neurons for each Z-plane

  • model.npy : If you have rastermap installed, this is the rastermap output

  • F_embedding.npy : Another file used by rastermap

And a few new figures::

  • max_images_volume.mp4

  • mean_images_volume.mp4

  • segmentation_volume.mp4

  • execution_time.png

  • mean_volume_signal.png

  • rastermap.png

Movies are essentially gifs that will play 1 z-plane per second.

Contents