Sample Command

Create subset datasets with various sampling strategies

The sample command creates a subset of a dataset using various sampling strategies, with optional category filtering and format conversion.

Usage

panlabel sample -i <INPUT> -o <OUTPUT> [OPTIONS]

Parameters

--input · path · required

Input path to the source dataset.

Short form: -i

--output · path · required

Output path for the sampled dataset.

Short form: -o

--from · string · default: "auto"

Source format (or auto-detect).

Supported values: auto, ir-json, coco, cvat, label-studio, tfod, yolo, voc

--to · string

Target format for the output.

Behavior:

• If omitted and --from is explicit, uses the same format as input
• If omitted and --from auto, defaults to ir-json

Supported values: ir-json, coco, cvat, label-studio, tfod, yolo, voc

--n · integer

Number of images to sample (absolute count).

Short form: -n

Note: Exactly one of --n or --fraction is required.

--fraction · float

Fraction of images to sample (0.0 to 1.0).

Examples:

• 0.1 - Sample 10% of images
• 0.5 - Sample 50% of images

Note: Exactly one of --n or --fraction is required.

--seed · integer

Random seed for deterministic sampling.

Using the same seed with the same input will always produce the same sample. Useful for reproducible experiments.

--strategy · string · default: "random"

Sampling strategy to use.

Options:

• random - Uniform random sampling
• stratified - Category-aware stratified sampling (maintains category distribution)

--categories · string

Comma-separated list of category names to filter on.

Example: person,car,bicycle

When specified, only images containing at least one of these categories are considered for sampling (see --category-mode).

--category-mode · string · default: "images"

How to handle category filtering.

Options:

• images - Keep whole images that contain at least one selected category (all annotations preserved)
• annotations - Keep only annotations of selected categories (other annotations removed)

--allow-lossy · flag · default: "false"

Allow lossy format conversions that may drop information.

Without this flag, the command fails if the target format cannot preserve all information from the source.

Sampling Strategies

Random Sampling (--strategy random)

Selects images uniformly at random from the dataset.

Characteristics:

• Fast and simple
• May not preserve category distribution
• Good for general-purpose sampling

Example:

panlabel sample -i dataset.json -o sample.json -n 100 --strategy random

Stratified Sampling (--strategy stratified)

Selects images while attempting to maintain the original category distribution.

Characteristics:

• Preserves category proportions
• Better for training/validation splits
• Ensures rare categories are represented

Example:

panlabel sample -i dataset.json -o sample.json --fraction 0.2 --strategy stratified

Category Filtering

Image Mode (--category-mode images)

Keeps entire images that contain at least one annotation of the specified categories. All annotations on those images are preserved, even if they’re not in the category list.

Use case: Training a detector for specific objects while keeping scene context.

Example:

# Keep all images with people or cars (and all their annotations)
panlabel sample -i dataset.json -o filtered.json \
  --categories person,car \
  --category-mode images \
  -n 500

Annotation Mode (--category-mode annotations)

Keeps only the annotations that match the specified categories. Images may end up with fewer annotations than the original.

Use case: Creating a dataset for a specific subset of classes.

Example:

# Keep only person and car annotations
panlabel sample -i dataset.json -o filtered.json \
  --categories person,car \
  --category-mode annotations \
  --fraction 1.0

With --category-mode annotations, images that lose all annotations are still kept in the output (as images without annotations).

Reproducibility

Use the --seed parameter to ensure reproducible sampling:

# Always produces the same sample
panlabel sample -i dataset.json -o sample.json -n 100 --seed 42

This is essential for:

• Creating consistent train/validation splits
• Reproducing experiments
• Sharing sampling configurations with collaborators

Examples

Sample 20% Randomly

panlabel sample -i large_dataset.json -o small_dataset.json --fraction 0.2

Sample 1000 Images with Stratified Sampling

panlabel sample -i training_data.json -o sample.json \
  -n 1000 \
  --strategy stratified \
  --seed 42

Filter for Specific Categories

panlabel sample -i dataset.json -o people_only.json \
  --categories person,pedestrian \
  --category-mode images \
  --fraction 1.0

Sample and Convert Format

panlabel sample -i coco_dataset.json -o yolo_sample/ \
  --from coco \
  --to yolo \
  -n 500 \
  --allow-lossy

Create Validation Split

# Stratified 80/20 split
panlabel sample -i full_dataset.json -o train.json \
  --fraction 0.8 \
  --strategy stratified \
  --seed 42

panlabel sample -i full_dataset.json -o val.json \
  --fraction 0.2 \
  --strategy stratified \
  --seed 43  # Different seed for non-overlapping sample

Category-Specific Subset with Annotation Filtering

panlabel sample -i multi_class.json -o binary.json \
  --categories positive_class,negative_class \
  --category-mode annotations \
  --fraction 1.0

Auto-Detect and Sample YOLO Dataset

panlabel sample -i /data/yolo_full/ -o /data/yolo_sample/ \
  --from auto \
  -n 200 \
  --seed 42

Important Notes

IDs are preserved: Sampled images and annotations retain their original IDs from the source dataset.

All categories preserved: The output dataset includes all category definitions from the source, even if some categories have no annotations after sampling.

When using --fraction with small datasets, the actual number of images may be less than expected due to rounding. Use -n for precise control.

Output

After sampling, Panlabel prints a summary:

Sampled 1000 images -> 200 images: dataset.json (coco) -> sample.json (coco)

Conversion Report:
  ✓ Lossless conversion
  Images: 200
  Annotations: 1,456
  Categories: 8

Common Workflows

Create Train/Val/Test Splits

#!/bin/bash
SEED=42

# 70% train
panlabel sample -i full.json -o train.json \
  --fraction 0.7 --strategy stratified --seed $SEED

# 20% val
panlabel sample -i full.json -o val.json \
  --fraction 0.2 --strategy stratified --seed $((SEED + 1))

# 10% test
panlabel sample -i full.json -o test.json \
  --fraction 0.1 --strategy stratified --seed $((SEED + 2))

Sample for Quick Experimentation

# Quick 100-image sample for testing code
panlabel sample -i huge_dataset.json -o quick_test.json -n 100

Balance Rare Classes

# First, get all images with rare class
panlabel sample -i dataset.json -o rare_class_images.json \
  --categories rare_class \
  --category-mode images \
  --fraction 1.0

# Then sample from that filtered set
panlabel sample -i rare_class_images.json -o balanced_sample.json \
  -n 500 --strategy random

Exit Codes

• 0 - Sampling successful
• 1 - Error occurred (invalid parameters, lossy conversion blocked, etc.)

See Also

Convert Command

Convert without sampling

Stats Command

Analyze category distribution before sampling

Validate Command

Validate sampled output