@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/vendor/skills/skills/workflow-reports/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: workflow-reports
+description: Use this skill when asked to create, draft, or write a Galaxy workflow report template for the Workflow Editor's Report tab. Triggers on requests like "create a report for this workflow", "draft a workflow report template", "write a Galaxy report for workflow <id/url>".
+metadata:
+  surfaces: [loom]
+---
+
+# Galaxy Workflow Report Templates
+
+Draft reusable Galaxy markdown report templates for the Workflow Editor's **Report** tab.
+
+## Required Input
+
+**This skill requires the full workflow definition.** Two equivalent options:
+
+**Option A — `.ga` file** (preferred for local/IWC workflows):
+Read the `.ga` file directly. It is a JSON object with the same structure as the API response. The `report.markdown` field is what this skill writes — it defaults to a minimal template (`invocation_inputs`, `invocation_outputs`, `workflow_display`) that should be replaced.
+
+**Option B — Galaxy API**:
+```
+GET https://<instance>/api/workflows/<id>/download?style=editor
+```
+> **Critical:** Use the `/download?style=editor` endpoint — not `/api/workflows/<id>`. The regular endpoint does **not** return `step.label` or `workflow_outputs`, which are essential for writing directives. Without them, no `output="..."`, `input="..."`, or `step="..."` references will work.
+
+If the user provides a browser URL like `https://usegalaxy.eu/workflows/run?id=abc123`, extract the ID and construct the download URL yourself.
+
+**Output:** The drafted report markdown is written into the `report.markdown` field of the `.ga` file (with user confirmation), or presented as a code block for pasting into the Workflow Editor's Report tab.
+
+---
+
+## Core Philosophy
+
+Reports are **templates** — they are written before knowing what inputs the user will provide or whether the run will succeed. Never assume:
+- Inputs are valid, in the expected format, or of the expected type
+- The run completed successfully or produced expected outputs
+- Biological/scientific meaning of results (the same workflow can be used in different contexts)
+
+Use conditional, descriptive language throughout:
+- Summary: "is designed to", "expects", "should produce"
+- Output sections: "if the run completed successfully, this should show..."
+- Column descriptions: what a column *measures*, not what it *means*
+
+---
+
+## Step 1 — Parse the workflow
+
+From the JSON response, extract:
+
+**Inputs** — steps where `type` is `data_input` or `data_collection_input`:
+- `steps[N].label` → used in `input="..."` directives
+- `steps[N].annotation` → describes what data is expected (use for prose, not directives)
+- `steps[N].type` → `data_input` (single dataset) vs `data_collection_input` (list/paired collection)
+
+**Workflow outputs** — steps where `steps[N].workflow_outputs` is a non-empty array:
+- `steps[N].workflow_outputs[].label` → used in `output="..."` directives
+- `steps[N].label` → the step's short name, used in `step="..."` for `job_parameters`
+- `steps[N].annotation` → use for prose about what this output represents
+
+> **Important distinction:** `steps[N].label` is the short identifier (e.g. `"Color Deconvolution"`) used in directives. `steps[N].annotation` is a longer description useful only for prose. Do not confuse them.
+
+**Top-level metadata**: `name` (report title), `annotation` (primary source for Summary prose), `tags` (domain context), `license`, `creator`
+
+If working from a `.ga` file, also check for a co-located `README.md` in the same directory — IWC workflows often have one with richer descriptions than the `annotation` field.
+
+---
+
+## Step 2 — Select which outputs to feature
+
+Not every `workflow_outputs` entry deserves its own section. Apply these rules:
+
+**Always include:**
+- The final/terminal tabular output (primary quantitative result)
+- Any output that is the direct basis for the quantitative result (e.g. the binary mask an area measurement is computed from)
+
+**Include selectively:**
+- Intermediate images that help the user understand whether the pipeline worked correctly (e.g. a segmentation mask is more informative than a raw deconvolved channel)
+- Prefer outputs closest to the end of the pipeline over early intermediates
+
+**Skip or collapse:**
+- Purely intermediate outputs that are only inputs to subsequent steps
+- Outputs that duplicate information already shown
+
+**When in doubt:** ask yourself — if the run produced unexpected results, which output would a user look at first to debug it? That's the one to feature.
+
+---
+
+## Step 3 — Classify selected outputs
+
+| Output type | Directive |
+|-------------|-----------|
+| Image (TIFF, PNG, JPEG) | `history_dataset_as_image(output="<label>")` |
+| Collection of images | `history_dataset_as_image(output="<label>")` — same directive, works for collections too |
+| Tabular / TSV / CSV | `history_dataset_as_table(output="<label>", show_column_headers=true, compact=true)` + `history_dataset_link(output="<label>", label="Download ...")` |
+| HTML / text | `history_dataset_embedded(output="<label>")` |
+| Unknown | `history_dataset_display(output="<label>")` |
+
+For image-type **inputs**, use `history_dataset_as_image(input="<input label>")`.  
+For non-image inputs or a general input listing, use `invocation_inputs()`.
+
+---
+
+## Step 4 — Build the report
+
+### Required sections
+
+**1. Title + run timestamp**
+
+````
+# <Workflow Name>
+
+```galaxy
+invocation_time()
+```
+````
+
+**2. Summary**
+- One paragraph: what the workflow is designed to do, what inputs it expects, what outputs it should produce.
+- Use the top-level `annotation` and step annotations to inform the prose — do not copy them verbatim.
+- End the section with `workflow_image()`.
+
+**3. Inputs**
+- Brief prose describing what the input(s) represent and what format/type is expected.
+- For image inputs: `history_dataset_as_image(input="<label>")`.
+- For non-image or multiple inputs: `invocation_inputs()`.
+
+**4. Key output sections** (one subsection per selected output)
+- Brief prose: what this output represents and how it was produced — phrased conditionally.
+- The appropriate directive immediately follows.
+- For processed images (masks, segmentations): explain the visual encoding conditionally ("in a successful run, white pixels should represent...").
+
+**5. Results** (when tabular outputs exist)
+- A markdown table of expected columns: name and description (factual/definitional only) — this goes **before** the directive so the reader understands the columns before seeing the live data.
+- Then `history_dataset_as_table(...)` followed by `history_dataset_link(...)`.
+
+**6. Reproducibility**
+
+```galaxy
+history_link()
+```
+
+### Optional sections
+
+- `job_parameters(step="<label>", collapse="Show <step> parameters")` — for analytical steps where the chosen parameters significantly affect interpretation
+- `invocation_outputs()` — useful when the workflow has many outputs and a full listing helps
+- `workflow_display(collapse="Show full workflow details")`
+
+---
+
+## Directive Syntax Rules
+
+**Block syntax only — no exceptions:**
+
+```galaxy
+directive_name(arg=value)
+```
+
+One directive per fenced block. Never stack multiple directives in one block. The `${galaxy ...}` inline syntax does **not** work.
+
+**Abstract references in workflow templates** (never hardcode IDs):
+- `input="<label>"` — workflow input by its label
+- `output="<label>"` — marked workflow output by its label
+- `step="<label>"` — step by its label
+
+Quotes are required when the value contains spaces.
+
+See `references/directives.md` for the full directive reference (synced from upstream Galaxy via `make sync-directives`).
+
+---
+
+## Gotchas
+
+| Issue | What to do |
+|-------|-----------|
+| `step.label` is null for many steps | Only use `job_parameters(step=...)` for steps that have a non-null `label`. Silently skip others. |
+| `workflow_outputs` is empty for a step that should be an output | Flag to the user: they must open the step in the Workflow Editor, star the output, and save. Then the `output="..."` directive can reference it. |
+| An important terminal output isn't marked (e.g. a final column-computation step) | Flag it specifically — name the step and describe what it produces. Don't silently omit it or use a less complete upstream output as a substitute without noting the limitation. |
+| Step annotations are very long | Use them to inform prose — do not copy them verbatim into the report. |
+| Multiple image outputs at different pipeline stages | Prefer the output closest to the final result. Intermediate outputs can be omitted or mentioned in prose only. |
+
+---
+
+## After drafting
+
+Present the template in a code block ready to paste into the Workflow Editor's Report tab.
+
+Also explicitly flag:
+1. Any important steps whose output is **not** marked as a `workflow_output` — name the step, what it produces, and instruct the user to star it in the editor.
+2. Any steps referenced in prose that have no `label` and therefore cannot be used with `job_parameters`.
+
+See `examples/histology-staining.md` for a complete worked example.

package/extensions/orbit/vendor/skills/skills/workflow-reports/examples/histology-staining.md

@@ -0,0 +1,145 @@
+# Example: Histological Staining Area Quantification
+
+A complete worked example of applying the workflow-reports skill to a real imaging analysis workflow.
+
+## Workflow Metadata
+
+| Field | Value |
+|-------|-------|
+| Name | histology-stain-area-quantification |
+| Instance | usegalaxy.eu |
+| ID | `e429074ee0a47cb3` |
+| Download URL | `https://usegalaxy.eu/api/workflows/e429074ee0a47cb3/download?style=editor` |
+| Purpose | Quantify staining area in brightfield histological images using colour deconvolution and automated thresholding |
+| Compatible stainings | IHC (DAB chromogen), Masson's Trichrome |
+
+## Extracted Data
+
+### Inputs
+
+| Step | Label | Type | Annotation |
+|------|-------|------|-----------|
+| 0 | `ROI image for staining analysis` | `data_collection_input` | Brightfield TIFF images, RGB, one ROI per element |
+
+### Workflow Outputs
+
+| Step | Step label | Output label | Type |
+|------|-----------|--------------|------|
+| 3 | `Color Deconvolution` | `Deconvolved Image` | Multi-channel image |
+| 5 | `Split Image Channels for Staining Detection` | `Collection: Individual Deconvolved Channels` | Image collection |
+| 8 | `Collection: Extract Stain Channel from Sub-Collections` | `Selected Stain Channel` | Image collection |
+| 11 | `Threshold Stain Channel Collection` | `Selected Stain Channel Thresholded` | Image collection (binary mask) |
+| 13 | `Extract Image Features` | `Collection of Tabular: Staining Quantification Results` | Tabular collection |
+| 25 | `Tabular: Staining Feature Results` | `Tabular File: Staining Feature Results` | Tabular (TSV) |
+
+**Note:** Step 27 (`Percent area computation`) computes the `percent_area` column but its output is **not marked as a workflow output**. The marked output (`Tabular File: Staining Feature Results`, step 25) is the pre-percent-area table. To include `percent_area` in the embedded table, the step 27 output must be starred in the Workflow Editor.
+
+### Key Step Labels (for `job_parameters`)
+
+- `Color Deconvolution`
+- `Threshold Stain Channel Collection`
+- `Extract Image Features`
+
+### Output Columns (`Tabular File: Staining Feature Results`)
+
+| Column | Description |
+|--------|-------------|
+| `sample_id` | Identifier derived from the input image filename |
+| `label` | Region label assigned by the thresholding step |
+| `mean_intensity` | Average pixel intensity within the detected region |
+| `area` | Pixel count of the positively stained region |
+| `area_filled` | Stained area with internal holes filled |
+
+---
+
+## Resulting Report Template
+
+````markdown
+# Histological Staining Area Quantification
+
+```galaxy
+invocation_time()
+```
+
+---
+
+## Summary
+
+This workflow is designed to quantify the area and intensity of a specific stain in brightfield
+histological images. It takes a collection of input images, applies H-E-DAB colour deconvolution
+to separate the target stain channel from the haematoxylin counterstain, then uses automated
+thresholding to segment positive-staining pixels. Per-sample measurements are collated into a
+single tabular output.
+
+Compatible staining types include immunohistochemistry (IHC) with a DAB chromogen and Masson's
+Trichrome (MT). The workflow expects RGB TIFF images — one region of interest (ROI) per
+collection element.
+
+```galaxy
+workflow_image()
+```
+
+---
+
+## Input Images
+
+The input to this workflow is a list collection of brightfield microscopy images. Each element
+should represent one region of interest from a tissue section. The images provided for this
+run are shown below.
+
+```galaxy
+history_dataset_as_image(input="ROI image for staining analysis")
+```
+
+---
+
+## Staining Mask
+
+If the run completed successfully, each input image will have been converted into a binary mask
+via colour deconvolution and automated thresholding. In a successful run, white pixels represent
+regions classified as positively stained and black pixels represent background. This mask is
+what the quantification measurements are derived from.
+
+```galaxy
+history_dataset_as_image(output="Selected Stain Channel Thresholded")
+```
+
+---
+
+## Results
+
+If the workflow completed successfully, the table below shows per-sample staining measurements —
+one row per input image. The expected columns are described below.
+
+| Column | Description |
+|--------|-------------|
+| `sample_id` | Identifier derived from the input image filename |
+| `label` | Region label assigned by the thresholding step |
+| `mean_intensity` | Average pixel intensity within the detected region |
+| `area` | Pixel count of the positively stained region |
+| `area_filled` | Stained area with internal holes filled |
+
+```galaxy
+history_dataset_as_table(output="Tabular File: Staining Feature Results", title="Staining Feature Results", show_column_headers=true, compact=true)
+```
+
+```galaxy
+history_dataset_link(output="Tabular File: Staining Feature Results", label="Download results (TSV)")
+```
+
+---
+
+## Reproducibility
+
+```galaxy
+history_link()
+```
+````
+
+---
+
+## Notes
+
+- The `history_dataset_as_image` directive works for both single images and collections — no special handling needed.
+- `Selected Stain Channel Thresholded` was chosen over `Deconvolved Image` or `Selected Stain Channel` as the primary visual output because it directly represents what the quantification is based on.
+- The Methods / `job_parameters` blocks were omitted from this template to keep it focused. They can be added as collapsible sections for workflows where parameter choices significantly affect interpretation.

package/extensions/orbit/vendor/skills/skills/workflow-reports/examples/tissue-microarray-analysis.md

@@ -0,0 +1,176 @@
+# Example: End-to-End Tissue Microarray Analysis
+
+A complete worked example of applying the workflow-reports skill to a multiplex tissue image analysis pipeline.
+
+## Workflow Metadata
+
+| Field | Value |
+|-------|-------|
+| Name | End-to-End Tissue Microarray Analysis |
+| Source | `.ga` file |
+| Path | `workflows/imaging/tissue-microarray-analysis/tissue-microarray-analysis/tissue-micro-array-analysis.ga` |
+| Purpose | Complete MTI analysis pipeline for TMA data: illumination correction, stitching, dearray, segmentation, quantification, phenotyping, and interactive visualisation |
+
+## Extracted Data
+
+### Inputs
+
+| Step | Label | Type |
+|------|-------|------|
+| 0 | `Raw cycle images` | `data_collection_input` (list of TIFF/OME-TIFF, ordered by cycle) |
+| 1 | `markers.csv` | `data_input` (CSV with columns: round, channel, marker_name) |
+| 2 | `PhenotypeWorkflow` | `data_input` (Scimap-formatted phenotype workflow CSV) |
+
+### Workflow Outputs
+
+| Step | Step label | Output label | Selected for report |
+|------|-----------|--------------|---------------------|
+| 3 | `Illumination correction with Basic` | `DFP images`, `FFP images` | No — early intermediates |
+| 4 | `Stitching and registration with Ashlar` | `Registered image` | No — intermediate |
+| 5 | `TMA dearray with UNetCoreograph` | `Dearray images`, `Dearray masks`, `TMA dearray map` | `TMA dearray map` only — most informative for verifying dearray |
+| 6 | `Nuclear segmentation` | `Nuclear mask` | Yes — direct basis for quantification |
+| 7 | `Convert dearray images to OME-TIFF` | `Converted image` | No — format conversion intermediate |
+| 8 | `Cell feature quantification with MC-Quant` | `Primary Mask Quantification` | Yes — primary quantitative result |
+| 9 | `Rename OME-TIFF channels` | `Renamed image` | No — intermediate |
+| 10 | `Convert to Anndata` | `Anndata feature table` | No — superseded by phenotyped output |
+| 11 | `Scimap phenotyping` | `Phenotyped feature table` | Yes — enriched final result |
+| 12 | `Create a Vitessce dashboard` | `Vitessce dashboard`, `Vitessce Dashboard Config` | `Vitessce dashboard` only — config is auxiliary |
+
+### Step Labels Available for `job_parameters`
+
+All steps have labels. Key ones used: `Nuclear segmentation`.
+
+---
+
+## Resulting Report Template
+
+````markdown
+# End-to-End Tissue Microarray Analysis
+
+```galaxy
+invocation_time()
+```
+
+## Summary
+
+This workflow is designed to perform a complete multiplex tissue image (MTI) analysis pipeline
+for tissue microarray (TMA) data imaged using cyclic immunofluorescence. It expects a
+round-ordered collection of raw cycle images (TIFF or OME-TIFF), a CSV markers file with
+channel names in the third column, and a Scimap-formatted phenotype workflow file.
+
+Starting from raw images, the pipeline applies illumination correction (BaSiC), stitches and
+registers cycles into a single whole-slide OME-TIFF (ASHLAR), and segments TMA cores into
+individual image crops (UNetCoreograph). Each core image then undergoes nuclear segmentation
+(Mesmer), per-cell feature quantification (MCQUANT), cell phenotyping (Scimap), and interactive
+visualisation (Vitessce). If the run completes successfully, it should produce pyramidal
+OME-TIFF images, nuclear segmentation masks, a quantified feature table, a phenotype-annotated
+AnnData object, and an interactive Vitessce dashboard.
+
+```galaxy
+workflow_image()
+```
+
+## Inputs
+
+The workflow expects three inputs:
+
+- **Raw cycle images** — a list collection of raw fluorescence cycle images (TIFF or OME-TIFF)
+  ordered by acquisition cycle (e.g. `cycle_1.tiff`, `cycle_2.tiff`, ...).
+- **markers.csv** — a comma-separated file with columns `round`, `channel`, and `marker_name`.
+  The marker names in the third column are assigned as channel names during stitching.
+- **PhenotypeWorkflow** — a Scimap-formatted phenotype workflow CSV that maps hierarchical
+  cell phenotypes to marker combinations.
+
+```galaxy
+invocation_inputs()
+```
+
+## TMA Dearray Map
+
+After stitching and registration, UNetCoreograph segments individual TMA cores and produces a
+map image showing the detected core positions overlaid on the whole-slide image. If dearray
+completed successfully, this image should show each TMA core outlined or labelled within the
+tissue array. It is useful for verifying that the expected number of cores was detected and
+that core boundaries are correct before proceeding with per-core batch analysis.
+
+```galaxy
+history_dataset_as_image(output="TMA dearray map")
+```
+
+## Nuclear Segmentation Masks
+
+Mesmer performs nuclear segmentation on each dearrayed core image and produces a collection of
+labelled nuclear mask TIFFs. If segmentation completed successfully, each mask should show
+individual nuclei as distinct integer-labelled regions against a black background — each unique
+integer corresponds to one segmented nucleus. These masks are the basis for cell boundary
+delineation used in feature quantification.
+
+```galaxy
+history_dataset_as_image(output="Nuclear mask")
+```
+
+```galaxy
+job_parameters(step="Nuclear segmentation", collapse="Show nuclear segmentation parameters")
+```
+
+## Cell Feature Quantification
+
+MCQUANT quantifies per-cell features from each core image using the nuclear masks, producing a
+CSV table where each row represents one segmented cell and columns contain mean marker
+intensities, spatial coordinates, and morphological measurements.
+
+| Column | Description |
+|--------|-------------|
+| `CellID` | Unique integer identifier for each segmented cell |
+| `X_centroid` | X coordinate of the cell centroid in pixels |
+| `Y_centroid` | Y coordinate of the cell centroid in pixels |
+| `<marker>_mean` | Mean fluorescence intensity of the named marker channel within the cell mask |
+| `Area` | Area of the segmented cell nucleus in pixels |
+| `MajorAxisLength` | Length of the major axis of the fitted ellipse |
+| `MinorAxisLength` | Length of the minor axis of the fitted ellipse |
+| `Eccentricity` | Eccentricity of the fitted ellipse (0 = circle, 1 = line) |
+| `Solidity` | Ratio of cell area to convex hull area |
+| `Extent` | Ratio of cell area to bounding box area |
+| `Orientation` | Angle of the major axis relative to the x-axis |
+
+```galaxy
+history_dataset_as_table(output="Primary Mask Quantification", show_column_headers=true, compact=true)
+```
+
+```galaxy
+history_dataset_link(output="Primary Mask Quantification", label="Download quantification table (CSV)")
+```
+
+## Phenotyped Feature Table
+
+Scimap performs automated GMM-based cell phenotyping using the provided phenotype workflow and
+appends cell type annotations to the quantification data. The output is an AnnData (h5ad)
+object compatible with single-cell and spatial analysis packages. Note that GMM-based
+thresholding works best for highly abundant markers with a strong bimodal distribution;
+results should be reviewed carefully before downstream interpretation.
+
+```galaxy
+history_dataset_link(output="Phenotyped feature table", label="Download phenotyped AnnData (h5ad)")
+```
+
+## Interactive Vitessce Dashboard
+
+Vitessce combines the renamed OME-TIFF core images, nuclear segmentation masks, and phenotyped
+AnnData into an interactive dashboard. If the run completed successfully, the dashboard should
+allow linked exploration of spatial image data alongside single-cell scatter plots and cell
+type visualisations.
+
+```galaxy
+history_dataset_embedded(output="Vitessce dashboard")
+```
+
+## Reproducibility
+
+```galaxy
+history_link()
+```
+
+```galaxy
+workflow_display(collapse="Show full workflow details")
+```
+````