run-shennong-single-cell-workflow

Files (2)

• SKILL.md
• shennong.skill.yaml

SKILL.md (first lines)

# Run a Shennong single-cell workflow

The Runtime image already provides `Shennong`, `ShennongData`, their read-only
MCP discovery servers, and their package Skills. Keep executable analysis in
explicit versioned R scripts; MCP discovery never replaces the script or result
provenance.

1. Require an active Project and inspect inputs before computation. Preserve
   organism, assay, genome build, annotation, sample/patient IDs, groups,
   biological replicates, and measurement transformation. Use governed DB tools
   for Resource discovery and `ShennongData::` APIs inside reproducible R code.
2. Call `plan.propose` with separate steps for input audit, environment, QC and
   clustering, annotation and markers, communication/regulatory analysis,
   external-cohort survival, artifacts, and validation. Before each Runtime
   submission, call `plan.update(status = "in_progress")`; pass the returned
   `plan_id` and exact `plan_step_id` to `runtime.submit_job`.
3. Use `environment.plan` for optional backends. The two Shennong packages are
   global image capabilities, but Seurat, SingleR, CellChat/LIANA, decoupleR,
   DoRothEA, and other method packages remain explicit Pixi-locked Project
   dependencies.
4. Write reviewable scripts under `project://current/scripts/` and outputs under
   `project://current/results/`. Use `Rscript --vanilla`, explicit inputs,
   outputs, resources, timeout, seed, and environment lock. Keep raw data
   unchanged.
5. For a PBMC3K-like workflow, use current exported APIs: initialize/materialize
   the object, run QC, call `sn_run_cluster()`, annotate with
   `sn_run_annotation(method = "consensus")`, review low-confidence calls with
   `sn_review_annotation()`, and discover cluster markers with
   `sn_find_de(return_object = TRUE)`. Retrieve stored results with
   `sn_list_results()` and `sn_get_result()` rather than reading `object@misc`
   ad hoc.
6. Run communication with `sn_run_cell_communication()` and TF activity with
   `sn_run_regulatory_activity(method = "dorothea")`. Treat one PBMC3K sample as
   descriptive only: condition effects require biological replicates and
   `sample_by`; cells are not independent replicates.
7. A PBMC3K object has no patient survival outcome. To ask which cell population
   is associated with favorable or adverse prognosis, first select a separate
   blood-cancer bulk expression cohort with aligned patient-level time/event
   metadata. Build one predeclared marker signature per annotated population,
   score those signatures per patient, and call `sn_run_survival()` with
   prespecified covariates and multiplicity correction. Report hazard ratios,
   confidence intervals, proportional-hazards diagnostics, and cohort limits;
   never label a population "good" or "bad" from PBMC3K alone or claim
   causality from an association.
8. Poll every Job to a terminal state, verify non-empty expected artifacts, then
   update its plan step. Register figures, tables, objects, scripts, environment
   locks, and reports with complete provenance.
9. Run `analysis.validate` after the final scientific computation and before
   interpretation. Stop when validation fails and cite only backend-issued
   EvidenceRefs.

Do not claim successful computation until the Runtime job and expected artifacts are verified.

From zerostwo/shennong-os, Apache-2.0.

More from zerostwo/shennong-os