AutoGineer
Generated banner for Cellprofiler
Generated logo for Cellprofiler

Cellprofiler

K-DenseCommunityCreated by K-Dense Inc.

  • Skill
  • Workflow
  • Science and research
  • MIT
  • Low risk
  • Has scripts
Download ZIP

From the author

Runs reproducible CellProfiler microscopy pipelines for nuclear segmentation, cell counts, and per-object fluorescence measurements. Supports image/channel manifests, headless batch execution, segmentation overlays, and measurement QC for 2D fluorescence assays.
— the description by K-Dense Inc.

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured workflow for running CellProfiler 4.2.8 microscopy pipelines in a headless, reproducible manner. It is designed for 2D fluorescence assays, specifically handling nuclear segmentation, cell counts, and per-object intensity measurements. The skill includes helper scripts to manage image manifests, execute batch processing, and perform quality control on the resulting measurements, ensuring that data extraction from microscopy images is consistent and verifiable.

What it does

  • Automates headless execution of CellProfiler pipelines for high-throughput microscopy.
  • Validates input image formats and metadata manifests before processing.
  • Generates per-object measurements including nuclear intensity, area, and shape.
  • Produces visual QC overlays showing nuclear boundaries on input images.
  • Performs automated quality control checks on output CSV data and run status.
  • Supports batch processing of microscopy plates, wells, and sites.

When to use it

  • When you need to perform repeatable nuclear segmentation and counting on 2D grayscale TIFF images.
  • When processing large batches of microscopy data that require consistent pipeline application.
  • When you need to integrate CellProfiler results into a larger data analysis pipeline with automated QC.
  • When you need to ensure that segmentation settings are frozen and applied uniformly across experimental conditions.

Advantages

  • Ensures reproducibility by enforcing a strict pipeline and manifest structure.
  • Provides automated QC checks to detect failed runs or invalid measurement data.
  • Supports headless execution suitable for containerized or server-based environments.
  • Standardizes the output format for downstream analysis of nuclear features.

Usage examples

“Prepare a manifest for my microscopy plate A01.”
The skill generates a load_data.csv file based on your images.csv, ready for CellProfiler processing.
“Run the nuclear segmentation pipeline on my image dataset.”
The skill executes the CellProfiler engine in headless mode, processes the images, and saves results to the specified output directory.
“Summarize the results of my recent microscopy run.”
The skill validates the generated CSV files and provides a summary of counts and QC status for the processed fields.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/k-dense-ai/cellprofiler/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip cellprofiler.zip -d .agents/skills

Documentation by K-Dense Inc.

CellProfiler quantitative microscopy

Use this skill when a user needs a repeatable CellProfiler .cppipe, nuclear counts, nuclear fluorescence, or batch microscopy measurements. The bundled assay accepts one 2D grayscale TIFF nuclear channel per field, with black-is-zero (MINISBLACK) pixels and bright nuclei on a dark background. Palette and white-is-zero TIFFs need an explicit conversion. For volumetric segmentation, multichannel cell painting, or tissue-specific models, design a separate pipeline and validate those assumptions rather than silently projecting or splitting the images.

The official application and manual remain 4.2.8. PyPI publishes 4.2.8.1; its seven modules used here and embedded Threshold module match the 4.2.8 source, but this review did not execute that native distribution. Keep the helper environment separate from CellProfiler's older dependency stack; see the runtime reference for the verification boundary.

Workflow

  1. Establish the acquisition unit: plate, well, site, time point if present, pixel size, nuclear channel identity, camera bit depth, exposure, and biological replicate. Keep original image intensities. Convert proprietary formats explicitly with Bio-Formats before using this helper.

  2. Create the CSV manifest below. image_path is absolute or relative to the manifest; sample IDs use letters, digits, dots, dashes, or underscores; sample IDs and plate/well/site combinations are unique. Use a nonnumeric sample ID such as sample_001: LoadData infers column types and can otherwise turn 001 into 1. Avoid surrounding whitespace in identifiers. TIFFs must be uint8 or uint16, single plane/series/resolution, and nonconstant. The helper rejects RGB, z-stacks, and float images rather than guessing channels.

  3. Use assets/nuclei.cppipe as a starting pipeline: LoadData → IdentifyPrimaryObjects → intensity/size measurements → outline overlay → CSV export. The initial diameter range is 8–80 pixels, with global Otsu thresholding, no threshold smoothing, and border objects excluded. Calibrate this range from representative images and acquisition pixel size before comparing conditions.

  4. Run a small pilot spanning controls, low/high density, dim images, and plate edges. Inspect saved overlays for missed nuclei, splits, merges, and edge exclusions. Adjust thresholding and declumping in CellProfiler, export the tuned .cppipe, and pass --pipeline to preserve it. Do not choose settings separately for each treatment to make their counts agree.

  5. Freeze the tuned pipeline and analyze the batch. Review input saturation warnings, zero counts, count/area distributions, and control behavior. Aggregation for inference belongs at the biological replicate level; thousands of cells from one well are not independent wells.

Run the bounded assay

From this skill directory, create images.csv:

sample_id,image_path,plate,well,site
control_A01_1,images/control_A01_1_DAPI.tif,Plate1,A01,1
python scripts/nuclei_assay.py prepare images.csv load_data.csv
python scripts/nuclei_assay.py run images.csv results --executable cellprofiler
python scripts/nuclei_assay.py summarize results

run requires a fresh/empty output directory and executes CellProfiler with -c -r, a saved pipeline copy, --data-file, output folder, and --done-file. Success requires exit code zero, a Complete marker, and valid measurement tables. It records the command, pipeline checksum, input image checksums, and sample QC in assay_qc.json before execution, retaining failed status and the error if execution or output validation fails. CellProfiler output goes to cellprofiler.log. Rerun in a new output folder. summarize checks CSV contents independently; it does not prove an engine run completed.

Custom pipelines must preserve DNA, Nuclei, Metadata_Sample, integer-dtype scaling, and the unprefixed single-object Image.csv/Nuclei.csv export contract. Keep the required intensity/area measurements. A renamed object set or different intensity scale needs a corresponding helper adaptation, not an unchecked --pipeline substitution.

The executable can also be the CellProfiler application launcher or a local container launcher; see references/runtime-and-qc.md for the container target, filesystem mapping, and verification evidence. prepare and summarize work without CellProfiler.

Interpret the outputs

  • Image.csv: one image/field row, including Count_Nuclei and acquisition metadata.

  • Nuclei.csv: one accepted object per row, with mean/integrated DNA intensity, area, and shape.

  • *_nuclei.png: green nuclear boundaries over the input image for visual QC.

  • pipeline.cppipe and cellprofiler.done: the exact pipeline copy and engine completion marker.

  • assay_qc.json: run status, unique image/object keys, exact counts, finite mean/integrated intensity and positive area checks, field mean area in pixels, and storage saturation flags.

LoadData ignores camera metadata for scaling in this asset and divides by the integer storage maximum: uint8 → 255, uint16 → 65535. A 12-bit camera stored in uint16 therefore has a maximum near 0.0625. Do not compare intensities across different bit depths, exposures, gains, or staining batches without an explicit calibration. A saturated image can pass segmentation while its intensity measurement is unusable. Illumination correction and background subtraction are assay-specific additions; this starter does neither.

The saturation fraction only counts pixels at the storage maximum. A 12-bit detector may saturate at 4095 while the uint16 storage maximum is 65535; inspect the known acquisition ceiling separately. Integrated intensity sums pixel values and may exceed 1; only per-pixel mean intensity is constrained to 0–1. The field's mean nuclear intensity weights each nucleus equally, rather than weighting each pixel equally.

A count check cannot prove correct segmentation. Inspect overlays and independently annotated fields; report boundary exclusions and segmentation errors alongside the biological result. The optional synthetic engine test targets a known three-nucleus example, not assay performance on unseen cell types. It was skipped in the current review because no engine was configured.

Sources

Files

references/runtime-and-qc.md

Runtime and assay verification

CellProfiler 4.2.8

The pipeline targets the full CellProfiler 4.2.8, not merely cellprofiler-core: IdentifyPrimaryObjects and measurement modules live in the full package. The official image cellprofiler/cellprofiler:4.2.8 is a Linux amd64 environment. Its digest, rechecked against the official registry on 2026-09-30, is sha256:fec440caa2b44edf80f9bd440a3d8c6b214d72437332ad2586a32d79e2eae2a4. Apple Silicon runs that image with --platform linux/amd64 under emulation. The image is about 1.54 GB compressed; allow space for its expanded layers before pulling.

The application download and manual still advertise 4.2.8, while PyPI offers 4.2.8.1 (2026-03-09). Released wheels were inspected without installing their native stack. All seven pipeline modules, plus Threshold, are byte-identical to the tagged 4.2.8 source. The CLI source diff adds Wayland display detection; -c -r -p, --data-file, -o, and --done-file are unchanged. This source comparison is not a 4.2.8.1 engine execution test.

For containers, run the helper inside a mounted working directory or mount input images, manifest, pipeline, and outputs at the same absolute paths as the host. LoadData CSV file URLs must resolve inside the container. A relative path inside a manifest is resolved before export; a host file URL does not automatically become /work/... when mounted there.

Example container pattern, from a working directory containing images.csv, images/, and a copy of this skill directory called cellprofiler-skill/:

docker run --rm --platform linux/amd64 --entrypoint python \
  -v "$PWD:/work" -w /work cellprofiler/cellprofiler:4.2.8 \
  cellprofiler-skill/scripts/nuclei_assay.py run images.csv results

The image supplies its own numpy and tifffile versions. Do not upgrade those in place to the helper test versions. Native helper-only verification uses Python 3.12, numpy==2.5.3, and tifffile==2026.9.20 in a separate environment. Full native CellProfiler has additional Java, GUI/build, and database client dependencies; follow the official installation instructions. The current 4.2.8.1 PyPI metadata still pins mysqlclient==1.4.6, scipy==1.9.0, scikit-image==0.18.3, scikit-learn<1, and tifffile<2022.4.22. A previous development installation stopped on missing mysql_config; a fresh native installation was not attempted in this review. The container command above is an execution pattern requiring an available Docker engine and image; it was not rerun during this review.

Input and output contracts

The released LoadData implementation accepts URL_DNA with file: URLs and Metadata_Sample/Plate/Well/Site. --data-file overrides its configured CSV. It infers metadata types across each column; quote marks in CSV do not force strings. Prefix sample and plate identifiers with text when leading zeros matter. Use canonical site numbers and well names such as A01 to keep acquisition identities unambiguous.

The starter sets LoadData Rescale intensities? to No, which ignores camera-range metadata and divides unsigned image pixels by their integer storage maximum. It does not preserve raw integer intensity units in measurements. The TIFF helper rejects additional pages/series and pyramids so a reader cannot silently choose the first image or level.

ExportToSpreadsheet's single-object CSV uses ImageNumber and ObjectNumber as keys; object numbers run from 1 to Count_Nuclei within each image. The helper rejects duplicate keys, orphan rows, missing object indices, fractional counts, nonfinite mean/integrated intensities, and nonpositive/nonfinite areas. An image with zero nuclei remains present, with null means and an explicit warning. Shape area is in square pixels, not square micrometres.

In the released CLI, --done-file records the pipeline's Exit_Status. Without that switch, some non-complete statuses can still produce exit code zero. The helper therefore requests the marker and requires Complete, then separately checks ModuleError_* and table contents. status: complete means these execution/consistency checks passed; it does not assert that segmentation is biologically accurate. The log and assay_qc.json remain available after a process or output-validation failure. If the helper itself is killed, a running report is incomplete evidence and must not be treated as success.

Scientific checks

  • Establish a manually counted set of fields across the acquisition range. Assess precision, missed objects, splits, and merges, not only mean count correlation.

  • Compare nuclear area distributions with plausible biology. Inflated area may indicate merges or illumination background; many tiny objects may be debris or threshold noise.

  • Check boundary policy. This starter excludes objects touching an image edge; overlapping acquisition tiles need a deliberate deduplication/edge policy.

  • Flat-field correction uses a separately estimated illumination function. Do not independently normalize each image to its own minimum/maximum before intensity comparisons.

  • Review out-of-focus and saturated fields. A >1% saturation warning is a triage heuristic, not a universal acceptance limit; set acceptance criteria for the assay.

  • Preserve field identities and experimental replicates when aggregating cells to wells.

Verification scope

The original development record reports that the asset was serialized by CellProfiler 4.2.8 module APIs and executed headlessly on a synthetic uint16 TIFF with three separated disks (radius 10 pixels; intensities 20,000, 30,000, 40,000). The regression asserts three nuclei, mean normalized intensity near 30,000/65,535, and a saved outline PNG. That engine run was not repeated in the 2026-09-30 review. Current tests execute manifest/TIFF handling and CSV QC with synthetic data, and simulate the subprocess contract to test completion and failure reporting. These tests do not execute CellProfiler segmentation.

To repeat the real integration test in a repository checkout, set CELLPROFILER_TEST_EXECUTABLE to an installed cellprofiler executable or a launcher that forwards all arguments and mounts the paths unchanged. Run only tests/cellprofiler/ in that pytest process. The test is explicitly skipped without that executable; helper tests still run.

Review sources

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

The author says: Python 3.12+ with numpy and tifffile for current helper-only dependencies; a separate CellProfiler 4.2.8 application/container for segmentation. Full CellProfiler has older native dependencies. Network access is needed for installation only. No credentials required.

Security

What our scanner noticed· Low risk

  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
K-Dense Inc.
Publisher
K-Dense (Community)
Source
K-Dense-AI/scientific-agent-skills · skills/cellprofiler · commit a25cf9e
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE.md)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by K-Dense Inc. or K-Dense.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download cellprofiler.zip