CLI Reference

U-FISH provides a comprehensive command-line interface for all major operations.

Overview

The U-FISH CLI can be accessed via:

ufish <command> [options]

Or alternatively:

python -m ufish <command> [options]

To see all available commands:

ufish --help

Commands

predict

Predict FISH spots in a single image.

ufish predict <input_image> <output_csv> [options]

Arguments:

input_image: Path to input image file
output_csv: Path to save detected spots

Options:

--threshold: Detection threshold (default: 0.5)
--min-distance: Minimum distance between spots (default: 3)
--model: Path to custom model file
--save-enhanced: Save enhanced image to file
--device: Device to use (‘cpu’ or ‘gpu’, default: auto)
--verbose: Enable verbose output

Examples:

# Basic usage
ufish predict image.tiff spots.csv

# With custom threshold
ufish predict image.tiff spots.csv --threshold 0.3

# Save enhanced image
ufish predict image.tiff spots.csv --save-enhanced enhanced.tiff

# Use GPU
ufish predict image.tiff spots.csv --device gpu

predict-imgs

Process multiple images in a directory.

ufish predict-imgs <input_dir> <output_dir> [options]

Arguments:

input_dir: Directory containing input images
output_dir: Directory to save results

Options:

--pattern: File pattern to match (default: “.tif”)
--threshold: Detection threshold (default: 0.5)
--min-distance: Minimum distance between spots (default: 3)
--model: Path to custom model file
--save-enhanced: Save enhanced images
--parallel: Number of parallel workers (default: 1)
--recursive: Process subdirectories recursively

Examples:

# Process all TIFF files
ufish predict-imgs ./images ./results

# Process specific pattern
ufish predict-imgs ./images ./results --pattern "*_DAPI_*.tiff"

# Parallel processing
ufish predict-imgs ./images ./results --parallel 4

# Recursive with enhanced images
ufish predict-imgs ./images ./results --recursive --save-enhanced

train

Train or fine-tune a model.

ufish train <train_dir> <val_dir> [options]

Arguments:

train_dir: Training data directory
val_dir: Validation data directory

Options:

--epochs: Number of training epochs (default: 100)
--batch-size: Batch size (default: 8)
--lr: Learning rate (default: 1e-4)
--model-save-dir: Directory to save model
--checkpoint-interval: Save checkpoint every N epochs
--resume: Resume from checkpoint
--pretrained: Path to pretrained model
--augmentation: Enable data augmentation
--device: Device to use (‘cpu’ or ‘gpu’)

Examples:

# Train from scratch
ufish train ./train ./val --model-save-dir ./models

# Fine-tune pretrained model
ufish train ./train ./val --pretrained ufish_default.onnx

# Resume training
ufish train ./train ./val --resume checkpoint_epoch_50.pt

# Custom parameters
ufish train ./train ./val --epochs 200 --lr 5e-5 --batch-size 16

evaluate

Evaluate model performance on test data.

ufish evaluate <test_dir> [options]

Arguments:

test_dir: Test data directory

Options:

--model: Path to model file
--cutoff: Matching distance cutoff (default: 3.0)
--output: Save evaluation results to file
--plot: Generate evaluation plots
--per-image: Show per-image results

Examples:

# Basic evaluation
ufish evaluate ./test

# With custom model and cutoff
ufish evaluate ./test --model custom.onnx --cutoff 2.5

# Save detailed results
ufish evaluate ./test --output eval_results.json --per-image

convert

Convert between different model formats.

ufish convert <input_model> <output_model> [options]

Arguments:

input_model: Input model file
output_model: Output model file

Options:

--input-format: Input format (‘pytorch’, ‘onnx’)
--output-format: Output format (‘pytorch’, ‘onnx’)
--opset-version: ONNX opset version (default: 11)
--simplify: Simplify ONNX model

Examples:

# PyTorch to ONNX
ufish convert model.pt model.onnx

# ONNX simplification
ufish convert model.onnx model_simple.onnx --simplify

benchmark

Run performance benchmarks.

ufish benchmark <image_or_dir> [options]

Arguments:

image_or_dir: Image file or directory

Options:

--model: Path to model file
--iterations: Number of iterations (default: 100)
--warmup: Warmup iterations (default: 10)
--device: Device to use
--batch-size: Batch size for throughput test

Examples:

# Single image benchmark
ufish benchmark image.tiff --iterations 100

# Directory benchmark
ufish benchmark ./images --device gpu --batch-size 8

load-weights

Load model weights for chaining with other commands.

ufish load-weights <weights_path> - <next_command>

Examples:

# Load weights then predict
ufish load-weights custom.onnx - predict image.tiff spots.csv

# Load weights then batch process
ufish load-weights custom.onnx - predict-imgs ./input ./output

visualize

Visualize detection results.

ufish visualize <image> <spots_csv> [options]

Arguments:

image: Input image file
spots_csv: CSV file with detected spots

Options:

--output: Output image file
--true-spots: Ground truth spots CSV for comparison
--cutoff: Matching cutoff for evaluation
--spot-size: Size of spot markers
--dpi: Output resolution

Examples:

# Basic visualization
ufish visualize image.tiff spots.csv --output result.png

# With ground truth comparison
ufish visualize image.tiff spots.csv --true-spots truth.csv

Configuration Files

U-FISH supports configuration files for complex workflows:

# config.yaml
model:
  path: "custom_model.onnx"
  device: "gpu"

prediction:
  threshold: 0.4
  min_distance: 3
  save_enhanced: true

training:
  epochs: 150
  batch_size: 16
  learning_rate: 1e-4
  augmentation: true

Use configuration:

ufish --config config.yaml predict-imgs ./input ./output

Environment Variables

U-FISH recognizes several environment variables:

UFISH_MODEL_PATH: Default model path
UFISH_CACHE_DIR: Cache directory for downloaded models
UFISH_DEVICE: Default device (‘cpu’ or ‘gpu’)
UFISH_LOG_LEVEL: Logging level (‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’)

Example:

export UFISH_DEVICE=gpu
export UFISH_MODEL_PATH=/models/custom.onnx
ufish predict image.tiff spots.csv

Batch Scripts

Example batch processing script:

#!/bin/bash
# process_batch.sh

# Set parameters
MODEL="finetuned_model.onnx"
THRESHOLD=0.4

# Process each subdirectory
for dir in data/*/; do
    name=$(basename "$dir")
    echo "Processing $name..."

    ufish load-weights $MODEL - predict-imgs \
        "$dir/images" \
        "results/$name" \
        --threshold $THRESHOLD \
        --save-enhanced \
        --parallel 4
done

PowerShell example for Windows:

# process_batch.ps1

$model = "finetuned_model.onnx"
$threshold = 0.4

Get-ChildItem -Path "data" -Directory | ForEach-Object {
    $name = $_.Name
    Write-Host "Processing $name..."

    ufish load-weights $model - predict-imgs `
        "$($_.FullName)\images" `
        "results\$name" `
        --threshold $threshold `
        --save-enhanced `
        --parallel 4
}

Tips and Tricks

Chaining Commands: Use - to chain commands:

ufish load-weights model.onnx - evaluate test/ - visualize test/img.tiff results.csv

Parallel Processing: Use --parallel for batch operations:

ufish predict-imgs ./large_dataset ./results --parallel $(nproc)

Memory Management: For large images, use tiling:

ufish predict large_image.tiff spots.csv --tile-size 1024 --overlap 128

Progress Monitoring: Use --verbose for detailed progress:

ufish predict-imgs ./images ./results --verbose --parallel 4