From 75d6443d5f676a1d15d3685e223b80edcee238c9 Mon Sep 17 00:00:00 2001 From: dariarom94 Date: Thu, 14 May 2026 13:33:25 +0200 Subject: [PATCH 1/3] Add CLAUDE.md with codebase guidance for Claude Code Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e71049f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,79 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Framework: Viash + Nextflow + +This is a [Viash](https://viash.io)-based benchmarking task for spatial transcriptomics cell segmentation, part of the [OpenProblems](https://openproblems.bio) initiative. Every executable is a **Viash component** — a self-contained unit pairing a `config.vsh.yaml` (metadata, arguments, Docker setup) with a `script.py` or `script.R`. Nextflow workflows orchestrate multi-component pipelines. + +## Common Commands + +```bash +# Sync test resources from S3 (required before testing) +scripts/sync_resources.sh + +# Build all components (Docker-cached) +viash ns build --parallel --setup cachedbuild + +# Test a single component +viash test src/methods/cellpose/config.vsh.yaml + +# Test all components in parallel +viash ns test --parallel + +# Run benchmark locally (test scale) +scripts/run_benchmark/run_test_local.sh + +# Run full local benchmark +scripts/run_benchmark/run_full_local.sh + +# Create a new method or metric from template +common/scripts/create_component +``` + +## Architecture + +The task follows a fixed pipeline defined by the API specs in `src/api/`: + +``` +Raw spatial data + → [data_processor] process_dataset → unlabelled + solution files + → [method / control_method] → prediction file + → [data_processor] process_prediction → formatted prediction + → [metric] ari → score file +``` + +**Component types** (each defined in `src/api/comp_*.yaml`): +- `control_method` — baseline segmentations (random Voronoi, true labels, empty labels) +- `method` — segmentation algorithms under evaluation (currently: Cellpose) +- `data_processor` — preprocessing and postprocessing steps +- `metric` — evaluation metrics (currently: ARI) +- `workflow` — Nextflow pipelines in `src/workflows/` + +**File format contracts** are defined in `src/api/file_*.yaml`. All component I/O must conform to these schemas. The `common/component_tests/run_and_check_output.py` helper enforces them during tests. + +## Component Structure + +Each component under `src/` follows this pattern: +``` +src/// +├── config.vsh.yaml # arguments, Docker image, test resources, test defaults +└── script.py # or script.R +``` + +Test resources and default parameters for `viash test` are declared inside `config.vsh.yaml` under `info.test_resources` and `info.test_default`. + +## Data Formats + +- **Spatial data**: Zarr-based `SpatialData` objects (`.zarr/`) +- **Single-cell data**: AnnData HDF5 files (`.h5ad`) +- Additional sources of ground truth will include spatial proteomics or annotated histology +- Test datasets live in `resources_test/` (downloaded via `scripts/sync_resources.sh` from S3) + +## Important Notes + +- The `common/` directory is a **git submodule** — clone with `git clone --recursive` or run `git submodule update --init` after cloning. +- `README.md` is **auto-generated** from the YAML API specs; do not edit it directly. +- All components run inside Docker containers by default. Use `--platform docker` / `--engine docker` flags with Viash when needed. +- `_viash.yaml` is the project-level Viash config (project name, organization, package registry, test resource S3 paths). +- Don't commit to main, always create a new branch From 1879d81d66ca2796233d510dca997f306009f54c Mon Sep 17 00:00:00 2001 From: dariarom94 Date: Fri, 15 May 2026 00:07:30 +0200 Subject: [PATCH 2/3] add instructions on summary --- CLAUDE.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index e71049f..eefc529 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,6 +15,9 @@ scripts/sync_resources.sh # Build all components (Docker-cached) viash ns build --parallel --setup cachedbuild +# Build all Docker containers (run before local benchmark) +scripts/project/build_all_docker_containers.sh + # Test a single component viash test src/methods/cellpose/config.vsh.yaml @@ -29,6 +32,16 @@ scripts/run_benchmark/run_full_local.sh # Create a new method or metric from template common/scripts/create_component + +# Inspect the Docker image ID and Dockerfile for a built component +target/executable// ---docker_image_id +target/executable// ---dockerfile + +# Run a single built component directly +target/executable// --input --output + +# Run a built component as a Nextflow workflow +nextflow run target/nextflow/ -profile docker --id --input --publish_dir out/ ``` ## Architecture @@ -77,3 +90,4 @@ Test resources and default parameters for `viash test` are declared inside `conf - All components run inside Docker containers by default. Use `--platform docker` / `--engine docker` flags with Viash when needed. - `_viash.yaml` is the project-level Viash config (project name, organization, package registry, test resource S3 paths). - Don't commit to main, always create a new branch +- Fill in the summary for a src/methods//config.vsh.yaml. Write a one sentence summary and a one paragraph summary of how this method works based on documentation and references. \ No newline at end of file From 45e6521b95e1d39206c35e4cd97ffd51737dd1cd Mon Sep 17 00:00:00 2001 From: dariarom94 Date: Sat, 16 May 2026 22:00:07 +0200 Subject: [PATCH 3/3] add test instructions --- CLAUDE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index eefc529..de122ca 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -90,4 +90,5 @@ Test resources and default parameters for `viash test` are declared inside `conf - All components run inside Docker containers by default. Use `--platform docker` / `--engine docker` flags with Viash when needed. - `_viash.yaml` is the project-level Viash config (project name, organization, package registry, test resource S3 paths). - Don't commit to main, always create a new branch -- Fill in the summary for a src/methods//config.vsh.yaml. Write a one sentence summary and a one paragraph summary of how this method works based on documentation and references. \ No newline at end of file +- Fill in the summary for a src/methods//config.vsh.yaml. Write a one sentence summary and a one paragraph summary of how this method works based on documentation and references. +- always use viash test to test new components \ No newline at end of file