Introduction to OpenHCS

Installation

pip install openhcs

Requirements: - Python 3.8+ - For GPU acceleration: CUDA-compatible GPU with appropriate drivers

Installation Options

Standard Installation (with GPU support):

pip install openhcs
# Includes GPU libraries: pyclesperanto, cupy, etc.

CPU-Only Installation (for CI/testing environments):

# Install with minimal dependencies
pip install openhcs --no-deps
pip install numpy scipy scikit-image pandas

# Enable CPU-only mode
export OPENHCS_CPU_ONLY=1

Development Installation:

git clone https://github.com/your-org/openhcs.git
cd openhcs
pip install -e .

See CPU-Only Mode for detailed CPU-only configuration.

Basic Example

This example shows the core OpenHCS workflow: creating a pipeline with processing steps and running it on microscopy data.

from openhcs.core.pipeline import Pipeline
from openhcs.core.steps.function_step import FunctionStep
from openhcs.core.orchestrator.orchestrator import PipelineOrchestrator
from openhcs.core.config import GlobalPipelineConfig
from openhcs.processing.backends.processors.torch_processor import stack_percentile_normalize
from openhcs.processing.backends.analysis.cell_counting_cpu import count_cells_single_channel
from openhcs.constants.constants import VariableComponents

# Define processing steps
pipeline = Pipeline([
    # Normalize images
    FunctionStep(
        func=(stack_percentile_normalize, {
            'low_percentile': 1.0,
            'high_percentile': 99.0
        }),
        name="normalize",
        variable_components=[VariableComponents.SITE]
    ),

    # Count cells
    FunctionStep(
        func=(count_cells_single_channel, {}),
        name="count_cells",
        variable_components=[VariableComponents.SITE]
    )
])

# Configure and run
config = GlobalPipelineConfig(num_workers=2)
orchestrator = PipelineOrchestrator(
    plate_path="/path/to/your/microscopy/data",
    global_config=config
)

# Execute pipeline
orchestrator.run_pipeline(pipeline)

Understanding the Example

The basic example demonstrates key OpenHCS concepts:

Pipeline: A list of processing steps that execute in sequence

FunctionStep: The basic processing unit that wraps a function with configuration

Variable Components: Defines how data is grouped for processing (SITE processes each imaging position separately)

Orchestrator: Manages pipeline execution across your dataset

Interactive Development

OpenHCS provides two interface options:

Desktop GUI (Recommended for local use):

# Install with GUI support
pip install "openhcs[gui]"

# Launch desktop application
openhcs-gui

Terminal Interface (For remote/SSH use):

# Install with TUI support
pip install "openhcs[tui]"

# Launch terminal interface
openhcs-tui

Both interfaces provide: - Microscopy data directory selection - Pipeline configuration and editing - Real-time execution monitoring - Results visualization

Next Steps

After running the basic example, explore these areas:

Core Concepts: Core Concepts

Understand pipelines, steps, function patterns, and data organization

Function Library: Function Library

Learn about available image processing functions and backends

Configuration: Storage System

Configure storage backends, memory management, and output options

Advanced Examples: Integration Guides

Multi-channel analysis, GPU acceleration, and large dataset processing

Common Patterns

Multi-Channel Analysis:

# Different analysis for different channels
FunctionStep(
    func={
        '1': (count_cells_single_channel, {}),  # DAPI channel
        '2': (trace_neurites, {})               # GFP channel
    },
    group_by=GroupBy.CHANNEL,
    variable_components=[VariableComponents.SITE]
)

Function Chains:

# Sequential processing steps
FunctionStep(
    func=[
        (gaussian_filter, {'sigma': 2.0}),
        (threshold_otsu, {}),
        (binary_opening, {'footprint_radius': 3})
    ],
    variable_components=[VariableComponents.SITE]
)

1-minute Quick Start

If you want to try OpenHCS quickly with minimal setup, copy this tiny pipeline into a file named quickstart.py and run it with a small folder of images (or a single image for testing):

# quickstart.py — minimal pipeline
from openhcs.core.pipeline import Pipeline
from openhcs.core.steps.function_step import FunctionStep
from openhcs.core.orchestrator.orchestrator import PipelineOrchestrator
from openhcs.core.config import GlobalPipelineConfig
from openhcs.processing.backends.processors.torch_processor import stack_percentile_normalize
from openhcs.processing.backends.analysis.cell_counting_cpu import count_cells_single_channel

pipeline = Pipeline([
    FunctionStep(func=(stack_percentile_normalize, {'low_percentile':1.0,'high_percentile':99.0}), name='normalize'),
    FunctionStep(func=(count_cells_single_channel, {}), name='count_cells')
])

config = GlobalPipelineConfig(num_workers=1)
orchestrator = PipelineOrchestrator(plate_path='path/to/images', global_config=config)
orchestrator.run_pipeline(pipeline)

This runs a normalization step followed by a simple per-site cell counting analysis. Use path/to/images to point to a folder with one or more test images. The snippet is intentionally minimal — see the full “Basic Example” above for more realistic configurations.