Skip to content

CLAUDE.md

Latest commit

 

History

History
187 lines (142 loc) · 5.25 KB

CLAUDE.md

File metadata and controls

187 lines (142 loc) · 5.25 KB

Claude Code Instructions for biahub

This file contains project-specific instructions and environment setup for working on the biahub repository.

Environment Setup

Conda Environment Discovery

Custom conda environments location: /hpc/mydata/$USER/envs/

List all available conda environments:

conda env list --prefix /hpc/mydata/$USER/envs/

Neuroglancer Environment

For neuroglancer visualization tasks:

conda activate /hpc/mydata/$USER/envs/neuroglancer_iohub

Tools available:

  • neuroglancer_view.py - Neuroglancer viewer CLI for OME-Zarr datasets

Biautils Environment

For iohub and general bioimage analysis tasks:

module load anaconda
module load comp_micro
conda activate biautils

Tools available:

  • iohub - OME-Zarr I/O operations
  • biahub CLI - Core processing modules

Repository Structure

Current Structure (Single Package)

biahub/
├── pyproject.toml          # setuptools-based configuration
├── biahub/                 # Main package
│   ├── cli/                # Click-based CLI
│   ├── *.py               # Processing modules
│   └── vendor/            # Vendored dependencies
├── settings/              # Example YAML configurations
├── tests/                 # Test suite
└── docs/                  # Documentation

Planned Structure (UV Workspaces - See plan file)

biahub/
├── pyproject.toml          # Workspace root
├── packages/
│   ├── biahub/            # Core processing (unchanged name)
│   └── analysis-templates/ # Hydra-based workflows
└── ...

See plan: /hpc/mydata/$USER/code/biahub/plans/biahub-uv.md

Important Paths

Project Repositories

  • biahub: /hpc/mydata/$USER/code/biahub (this repository)
  • infected_vs: /hpc/mydata/$USER/code/infected_vs (hummingbird microscope processing)

Reference Data for Development

Widefield microscope (Hummingbird):

  • /hpc/projects/intracellular_dashboard/virtual_stain_ft_infected/2026_01_29_A549_H2B_CAAX_DAPI_DENV_ZIKV/
  • Stages: 0-convert, 1-reconstruct, 2-concatenate (+ zarrv3 variants)

Light-sheet + label-free microscope (Mantis):

  • /hpc/projects/intracellular_dashboard/organelle_dynamics/2025_08_26_A549_SEC61_TOMM20_ZIKV/
  • Stages: 0-convert, 1-preprocess, 2-assemble, 3-visualization, 4-phenotyping

Development Workflow

Current Branch

Check with git status and git branch

Running biahub CLI

# In current environment
biahub --help
biahub <command> --help

# Common commands
biahub reconstruct
biahub register
biahub stabilize
biahub concatenate

Testing

pytest tests/
pytest tests/test_concatenate.py -v

Migration to UV Workspaces (In Progress)

Status: Planning phase Plan file: plans/biahub-uv.md

Key decisions:

  • Keep biahub package name unchanged
  • New analysis-templates package for Hydra-based workflows
  • Start with 4-stage Dragonfly workflow (convert → reconstruct → register → virtual stain)
  • Data layout must match existing bash-based template output structure

Related PRs:

  • PR #200 (feature/merge-mantis-analysis-template): Do NOT merge
  • VisCy issue #353: Reference for UV workspaces pattern

Code Style & Conventions

Import Organization

  • Standard library first
  • Third-party packages second
  • Local imports last
  • Prefer absolute imports: from biahub.X import Y

CLI Development

  • Use Click for command-line interfaces
  • Lazy loading for command discovery (see biahub/cli/main.py)
  • Pydantic for configuration validation

Configuration

  • Pydantic v2 models in biahub/settings.py
  • YAML configuration files in settings/ directory
  • Extra fields forbidden to catch typos: extra="forbid"

Common Tasks

Viewing OME-Zarr Data

Two options for visualizing zarr stores during analysis or development:

Option 1: neuroglancer_view.py (preferred — faster)

conda activate /hpc/mydata/$USER/envs/neuroglancer_iohub
neuroglancer_view.py /path/to/data.zarr --position A/1/0

Option 2: ndimg_view.py (from nd-embedding-atlas — interactive browser UI)

conda activate /hpc/mydata/$USER/envs/idetik_iohub
python /hpc/mydata/$USER/code/nd-embedding-atlas/scripts/ndimg_view.py /path/to/data.zarr --position A/1/0
  • Launches a web dashboard at http://localhost:5055 with a table of FOVs and WebGL viewer
  • Supports multiple zarr stores for side-by-side comparison
  • Filter channels with --channels DAPI,TXR

Creating Test Data (iohub)

module load anaconda
module load comp_micro
conda activate biautils

python << 'EOF'
from iohub import open_ome_zarr
# ... see plans/biahub-uv.md for test data creation script
EOF

Checking Dataset Metadata

conda activate biautils
python -c "from iohub import open_ome_zarr; d = open_ome_zarr('/path/to/data.zarr'); print(d.channel_names, d.data.shape)"

Notes for Claude

  • When working with HPC paths, always use absolute paths
  • Check for existing conda environments before suggesting new ones
  • The user prefers Click over argparse for CLI development
  • The user works with OME-Zarr format via iohub library
  • Always check plans/biahub-uv.md for current migration status
  • Test data locations are important for validation