Skip to content

Quick Start

This guide will walk you through the basic workflow of using sleap-roots to extract morphological traits from plant root images.

Prerequisites

Before starting, make sure you have:

  1. Installed sleap-roots – See Installation
  2. SLEAP prediction files – .slp files generated by SLEAP
  3. Optional: Video files – .h5 or .mp4 files (for frame-by-frame analysis)

Don't have SLEAP predictions?

You can use the test data included in the repository: 

git clone https://github.com/talmolab/sleap-roots.git
cd sleap-roots
git lfs pull  # Download test data

Basic Workflow

The typical sleap-roots workflow has three steps:

  1. Load SLEAP predictions into a Series object
  2. Choose a pipeline appropriate for your plant type
  3. Compute traits and export to CSV

Example 1: Single Plant Analysis

Let's analyze a single dicot plant (e.g., soy or canola) with primary and lateral roots:

import sleap_roots as sr

# Step 1: Load SLEAP predictions
series = sr.Series.load(
    series_name="919QDUH",
    h5_path="tests/data/canola_7do/919QDUH.h5",
    primary_path="tests/data/canola_7do/919QDUH.primary.slp",
    lateral_path="tests/data/canola_7do/919QDUH.lateral.slp"
)

# Step 2: Create a pipeline
pipeline = sr.DicotPipeline()

# Step 3: Compute traits
traits_df = pipeline.compute_plant_traits(series, write_csv=True)

# View results
print(f"Shape: {traits_df.shape}")
print(traits_df[['plant_name', 'frame_idx', 'lateral_count', 'primary_length',
                 'lateral_lengths_mean', 'network_solidity']].head(3))

Output: 

Shape: (72, 117)
  plant_name  frame_idx  lateral_count  primary_length  lateral_lengths_mean  network_solidity
0    919QDUH          0              5      971.050417             40.400556          0.456066
1    919QDUH          1              3      948.174804             48.358652          0.455535
2    919QDUH          2              4      959.421417             66.388803          0.455535

What this returns: - One row per frame (72 frames total) - 117 trait columns including: - Scalar traits: primary_length, lateral_count, network_solidity (one value per frame) - Non-scalar traits: lateral_lengths_mean, lateral_angles_distal_mean, etc. (statistics across multiple roots within each frame) - CSV saved to 919QDUH_traits.csv

Example 2: Batch Processing with Summary Statistics

For high-throughput experiments, process multiple plants and get summary statistics:

import sleap_roots as sr

# Step 1: Find all SLEAP files in a directory
paths = sr.find_all_slp_paths("tests/data/soy_6do")

# Step 2: Load all plants
plants = sr.load_series_from_slps(paths, h5s=True)

# Step 3: Create pipeline and compute batch traits
pipeline = sr.DicotPipeline()
batch_df = pipeline.compute_batch_traits(plants, write_csv=True)

# View summary
print(f"Shape: {batch_df.shape}")
print(batch_df[['plant_name', 'lateral_count_mean', 'lateral_count_median',
                'lateral_lengths_mean_mean', 'lateral_lengths_mean_median']].head())

Output: 

Shape: (1, 1036)
  plant_name  lateral_count_mean  lateral_count_median  lateral_lengths_mean_mean  lateral_lengths_mean_median
0  6PR6AA22JK                4.2                   4.0                      45.34                        44.12

What this returns: - One row per plant (summarizing all frames) - 1036 summary statistic columns including: - Scalar traits: lateral_count_mean, primary_length_median (single statistic suffix) - Non-scalar traits: lateral_lengths_mean_mean, lateral_lengths_mean_median (double statistic suffix) - CSV saved to batch_traits.csv

Understanding Summary Statistics

compute_batch_traits() computes 9 summary statistics across frames for each plant: min, max, mean, median, std, p5, p25, p75, p95

See Understanding Summary Statistics below for details on the naming pattern.

Example 3: Using Individual Trait Functions

You can also use modular utility functions for custom analyses:

import sleap_roots as sr
from sleap_roots.lengths import get_root_lengths
from sleap_roots.angle import get_node_ind, get_root_angle

# Load data
series = sr.Series.load(
    series_name="my_plant",
    primary_path="primary_roots.slp"
)

# Get points for frame 0
pts = series.get_primary_points(frame_idx=0)

# Compute length using the first root instance
length = get_root_lengths(pts)

# Compute angle: first find the proximal node, then calculate angle
node_ind = get_node_ind(pts, proximal=True)
angle = get_root_angle(pts, node_ind=node_ind, proximal=True, base_ind=0)

print(f"Primary root length: {length:.2f} pixels")
print(f"Primary root angle: {angle:.2f} degrees")

Available Pipelines

Choose a pipeline based on your plant type and root system:

Pipeline Use Case Root Types
DicotPipeline Dicots with primary + laterals Primary, Lateral
YoungerMonocotPipeline Young monocots Primary, Crown
OlderMonocotPipeline Mature monocots (no primary) Crown
MultipleDicotPipeline Multi-plant images Primary, Lateral
PrimaryRootPipeline Primary root only Primary
LateralRootPipeline Lateral roots only Lateral

See the Pipeline Guide for detailed information about each pipeline.

Understanding the Output

Frame-Level vs Plant-Level Outputs

sleap-roots provides two types of outputs:

Frame-Level: compute_plant_traits()

Returns one row per frame with raw trait measurements:

# Shape: (72, 117) - 72 frames, 117 columns
  plant_name  frame_idx  lateral_count  primary_length  lateral_lengths_mean
0    919QDUH          0              5      971.050417             40.400556
1    919QDUH          1              3      948.174804             48.358652

Use this when you want to: - Track how traits change over time - Plot growth curves - Analyze temporal dynamics

Plant-Level: compute_batch_traits()

Returns one row per plant with summary statistics across all frames:

# Shape: (1, 1036) - 1 plant, 1036 summary statistic columns
  plant_name  lateral_count_mean  lateral_lengths_mean_median
0  6PR6AA22JK                4.2                        44.12

Use this when you want to: - Compare different plants/genotypes/treatments - Run statistical tests between groups - Generate high-level phenotyping summaries

Understanding Summary Statistics

When using compute_batch_traits(), sleap-roots computes 9 summary statistics across all frames:

  • min – Minimum value
  • max – Maximum value
  • mean – Average (arithmetic mean)
  • median – Middle value (50th percentile)
  • std – Standard deviation
  • p5, p25, p75, p95 – Percentiles

Column Naming Pattern

Scalar traits (one value per frame) get single-suffixed names: 

primary_length → primary_length_mean, primary_length_median, primary_length_max, ...
lateral_count → lateral_count_mean, lateral_count_std, ...

Non-scalar traits (multiple values per frame) get double-suffixed names: 

lateral_lengths → lateral_lengths_mean_mean, lateral_lengths_mean_median, ...
                   ↑ first suffix      ↑ second suffix

The double suffix indicates two levels of summarization:

  1. First suffix (frame-level): Statistic across multiple roots within each frame
  2. Example: lateral_lengths_mean = mean across all lateral roots in that frame
  3. Second suffix (plant-level): Statistic across all frames for the plant
  4. Example: lateral_lengths_mean_median = median of all frame means

Example breakdown: 

lateral_lengths_mean_median
│                │    └─ median across all 72 frames
│                └────── mean across lateral roots within each frame
└───────────────────── trait name

When to Use Which Statistic

  • mean: Use for normally distributed data, sensitive to all values
  • median: Use when data may have outliers, more robust
  • min/max: Use for extreme values (e.g., maximum growth potential)
  • std: Use to assess variability or consistency
  • percentiles (p5, p25, p75, p95): Use for robust estimates ignoring outliers

Common use cases: - Comparing growth: primary_length_mean or primary_length_median - Finding vigorous plants: primary_length_max, lateral_count_max - Measuring variability: lateral_angles_proximal_std_mean (higher = more variable) - Finding consistency: Lower *_std values = more consistent across frames

Common Traits

Frame-level outputs include:

  • Scalar traits: primary_length, lateral_count, network_solidity
  • Non-scalar traits: lateral_lengths_mean, lateral_angles_distal_median, root_widths_p95

For the complete list, see the API Reference.

Working with CSV Output

The CSV files work with any analysis tool (Python/pandas, R, Excel, etc.). SLEAP predictions are measured in pixels. To convert pixel measurements to real-world units (mm, cm), include a ruler or reference object of known length in your images during capture.

Common Issues

For installation problems, import errors, file errors, and troubleshooting, see the Troubleshooting Guide.

Next Steps