Tutorials

If you haven’t already installed the CellTune software, please start with the Download & Install page before continuing.

Step 1: Download Demo Data

Download images and tables for the tutorial

After downloading, unzip the folder.
You can extract it to your Downloads folder or create a dedicated folder such as CellTune_Data in your Documents.

Demo Data Folder Contents

Demo Data Contents

The demo dataset included with CellTune provides a complete example of spatial proteomics analysis using multiplexed tissue images from control and GVHD intestinal biopsies, as described in Azulay et al., bioRxiv 2025.

`CellTune_Demo_Data/`

cellTable_features_calculated.parquet
Pre-computed single-cell features, including intensity, morphology, and spatial statistics.
Labels.csv
Cell-level annotations for training and evaluation.
PopulationSetInfo.csv
Metadata describing the populations (cell types).
Images/
Contains all image data and segmentations used in the tutorial.

`Images/`

This folder contains 75 subfolders, each corresponding to a single field of view (FOV) from either control or GVHD tissue:

Control_01_FOV_1, Control_01_FOV_2, …, GVHD_03_FOV_2, etc.

Each Image (FOV) folder includes:

Protein (Marker) Channels
Single-channel grayscale .tif images (e.g., CD3.tif, CD4.tif, CD8.tif, FOXP3.tif, etc.) representing individual protein markers.
Additional Feature Channels
Folders may also include:
- Subregion masks (e.g., epithelium, muscle, vasculature)
- Composite or colocalization images (combining multiple marker channels) used for feature extraction
Segmentation Files
- segmentation_labels.tiff: Cell instance segmentation image.
  Each pixel is labeled with a unique cell ID, with background as 0.
- segmentation_borders.tiff: Outlines of segmented cell borders (purely for visualization).

Each FOV in this dataset has 73 channel files + 2 segmentation files.

Single Image Folder Contents
…

These files will be loaded directly into CellTune when starting a new project.

Step 2: New Project Setup

Create a new project using the demo data:

Step 3: Main Window

3A. Select and Adjust Channels

Select channels and adjust channel brightness:

3B. Create Channel Groups

Create channel groups: (You can select and change groups of channels with a single click!)

Type the channel group name in the box, then press the (+) button. To delete a channel group press the (-) button. If you change the channels with an existing channel group name selected, the (+) button will update the channel group.

Tip: You can scroll through channel groups with the up and down arrows.

3C. Change Image

The top left panel allows you to select different images from your project.

Tip: When an image is selected, you can scroll through images with the up and down arrows.

3D. Adjust Segmentation

Adjust segmentation opacity and hover fill through segment controls.

Tip: 0.4 is our favorite opacity setting for the segmentation.

Step 4: Features

4A. Compute Features

Features must be computed or imported in order to enable gating, classification, & hover info.

4B. Import Features

Features can be imported via a cellTable (CSV or parquet file) The cellTable should have the columns: (image, cellID)

4C. Hover Legend Features

Select features that will be displayed while hovering

Step 5: Create Empty Population Set

Create an empty population set. You can add populations to it (e.g. from gating)

Step 6: Gating

6A. Gating Basics

Select the feature that you want to gate and click “Apply Gate”. Shown is an example of gating CD3+ and CD4+ cells.

Gating occurs across the entire project currently. (We are adding the capability to limit to the current image).

6B. Adjust Gating Appearance

You can adjust the opacity and whether gated cells are filled in.

Currently gated cells can only be displayed in the color cyan. (We are adding the capability to edit this).

6C. Create Population from Gating

6D. Filter Gate by Population

You can select populations in the current population set and use them as a filter for your gating.

6E. Edit Gating Expression

You can edit your gating expression to use AND (&), OR (

), and NOT (!) operations.

By default the gating expression uses AND (&) for all compound gates.

Step 7: Import Population Set

Population sets can be imported from files (CSV). Columns should be (image, cellID, class). Here we are importing labels to be used for training a classifier later. We can also import Population set info which includes colors, channels, and definitions for cell types (useful later).

A cell can belong to multiple populations. For population sets that are used as labels for training classifiers we encourage limiting a cell to one population.

Step 8: Classification

8A. Create Classifier

Create a classifier and select the features it will use for training. The features were computed or imported previously in step 4.

8B. Add Labels to Classifier

Add training labels to a classifier. You can select an existing population set. This action will create a new population set called “Labels_{Classifier_Name}”

8C. Train Classifier

Trains the CellTune classifier using the features and labels. Please be patient.

CellTune trains two models XGBoost and CatBoost by default. CatBoost is slow without GPU (1-2 hours), so LightGBM may be substituted if desired.

8D. Plot Confusions

Plot a confusion matrix showing the agreements and disagreements between the two models trained.

Step 9: Visualize Populations

You can select a population set and color the cells by the populations. Here we select the predictions from the classifier and visualize the predictions.

You can put one population on and make it transparent to compare it to the protein expression as shown:

Step 9: Sampling and Labeling

9A. Cell Sampling

You can adjust the default settings for sampling.

!Note if you get an error while loading review, then you need to import PopulationSetInfo for Pred_ALL_Classifier_1. This will be corrected in the upcoming version 0.1.1.