update prompts

interpret.py

@@ -18,8 +18,8 @@
 # Tone rules appended to every prompt.
 STYLE_GUIDE = """
 Style and register (apply throughout):
-- Write in the neutral, descriptive register of a peer-reviewed research paper. Report
-  what the data shows; do not editorialize, rate, or pass judgement on it.
+- Write in the neutral, descriptive register of a peer-reviewed research paper.
+  Report what the data shows; do not editorialize, rate, or pass judgement on it.
 - Remove judgemental and evaluative language. Do NOT use words such as: striking,
   remarkable, overwhelming, dominant(ly), extreme, dramatic, impressive, crucial,
   notable(ly), interesting, surprising, concerning, alarming, poor, excellent, good,
@@ -29,6 +29,7 @@
   "potentially". Prefer "associated with" over causal claims ("causes", "drives").
 - Report negative or null results plainly (e.g. "no differential signal was detected").
 - Present per-sample numbers in compact markdown tables rather than long inline lists.
+- When presenting summaries, check that all relevant samples are included.
 - Use plain formatting only: markdown headers, bold, and tables. Do NOT use LaTeX math
   ($...$, \\text{}, \\mathbf{}) or emoji.
 - Be concise: do not restate the section name or descriptor, and do not repeat the same
@@ -54,15 +55,13 @@
   group, high within-group variability, outlier influence) instead of implying certainty.
 """
 
-SYSTEM_PROMPT = """You are an expert in bioinformatics, sequencing technologies, genomics data analysis, and adjacent fields.
-
-You are given findings from a MultiQC report, generated by a bioinformatics workflow.
-MultiQC supports various bioinformatics tools that output QC metrics, and aggregates those metrics
-into a single report. It outputs a "General Statistics" table with key metrics for each sample across
-all tools. That table is followed by more detailed sections from specific tools, that can include tables,
-as well as plots of different types (bar plot, line plot, scatter plot, heatmap, etc.)
-
-You are given data of a MultiQC report. Your task is to analyse the data and give a concise summary.
+SYSTEM_PROMPT = """You are an expert bioinformatician. You are given a report generated
+by a bioinformatics workflow. The report incluced outputs from a number of bioinformatics
+tools and include quality control metrics, as well as actual aggregated analysis results.
+The report includes the samplesheet table that may contain important clinical metadata.
+Different report sections may have different structures and different biological meaning,
+and contains a short descriptor of the section's structure and meaning.Your task is to
+analyse the data and give a concise summary.
 """ + STYLE_GUIDE + EVIDENCE_RULES
 
 
@@ -313,21 +312,29 @@ def iter_analysis_sections(report: dict):
             yield name, section_obj
 
 
-SYNTHESIS_SYSTEM_PROMPT = """You are an expert bioinformatician. You are given the per-section analyses of a SINGLE MultiQC spatial transcriptomics report.
+SYNTHESIS_SYSTEM_PROMPT = """You are an expert bioinformatician. You are given
+the per-section analyses of a spatial transcriptomics report.
 
-Synthesize them into one concise executive summary of a few short paragraphs. Cover:
+Synthesize them into one concise executive summary of a few short paragraphs.
+Cover:
 - the overall picture and whether the pipeline appears to have run successfully,
+- any notable patterns or outliers in the data and other data quality issues,
 - the most important quantitative findings, citing key numbers and percentages,
-- a clear verdict on whether the data supports any responder vs non-responder difference.
-
-Only surface findings that are well supported: consistent across at least 2 samples per
-group, or supported by both the mean and the median. Exclude weak, single-sample-driven,
-or high-variability findings, or mention them only as not robust. Do not combine several
-weak signals into a strong conclusion. Where the data does not support a group difference,
-say so plainly.
-
-Be decisive and readable. Do not repeat each section verbatim or list sections one by one.
-Output only the summary prose — do NOT add your own title or markdown heading.
+- findings across the report sections that are consistent with each other, or 
+  contradict each other,
+- in case contrast analysis is present, provide a clear verdict on whether the 
+  data supports difference across metadata groups,
+- in case no metadata present, summary should focus on overall similarity patterns
+
+Only surface findings that are well supported: consistent across at least 2
+samples per group, or supported by both the mean and the median. Exclude weak,
+single-sample-driven, or high-variability findings, or mention them only as not
+robust. Do not combine several weak signals into a strong conclusion. Where the
+data does not support a group difference, say so plainly.
+
+Be decisive and readable. Do not repeat each section verbatim or list sections
+one by one. Output only the summary prose — do NOT add your own title or markdown
+heading.
 """ + STYLE_GUIDE + EVIDENCE_RULES
 
 

json_reduction/descriptor_schema.json

@@ -1,13 +1,13 @@
 {
   "multiqc_samplesheet": {
-    "description": "The sample sheet provided as input to the pipeline. Contains per-sample metadata. Only the response label is relevant for analysis; file paths (data_directory, expression_profile) are excluded.",
+    "description": "The sample sheet provided as input to the pipeline. Contains per-sample metadata columns. Columns containing file paths (data_directory, expression_profile) are excluded.",
     "structure": "sample_id to { metadata fields }",
     "properties": {
       "responce": "Treatment response label (example: responder / non-responder)."
     }
   },
   "multiqc_atlas": {
-    "description": "Summary of the cells and genes in the reference atlas. If the same atlas is used for multiple samples, table rows will be repeated.",
+    "description": "Summary of the cells and genes in the reference atlas. Transcription profiles from the reference atlas are used to infer cell types in the samples.",
     "structure": "atlas_id to { QC metrics }",
     "properties": {
       "n_genes": "Total unique genes in the atlas.",
@@ -19,13 +19,13 @@
     }
   },
   "multiqc_atlas_ct": {
-    "description": "Summary of the cell types in the atlas. Values are raw cell counts per type.",
+    "description": "Summary of the cell types in the reference atlas. Values are raw cell counts per type. Cell transcriptional profiles from the reference atlas are used to infer cell types in the samples.",
     "structure": "atlas_id to { cell_type_name: count }",
-    "key_type": "Cell type names (example: 'acinar cell', 'type B pancreatic cell'). 'unknown' = unassigned cells.",
+    "key_type": "Cell type names (example: 'acinar cell', 'type B pancreatic cell'). 'unknown', 'NA' = unassigned cells.",
     "value_type": "integer - raw cell count per type"
   },
   "multiqc_adata": {
-    "description": "Summary of the AnnData object right after it was read. Represents the input tissue sample before any processing.",
+    "description": "Summary of the sample AnnData object right after it was read. Represents the input tissue sample before any processing. Low non-zero expression counts (<100) or high percent mitochondrial counts (>20%) may indicate low-quality spots.",
     "structure": "sample_id to { QC metrics }",
     "properties": {
       "n_genes": "Total unique genes in the sample.",
@@ -39,7 +39,7 @@
   "multiqc_deconvolved_ct": {
     "description": "Assigned cell types based on deconvolution / cell typing results. Values are spot counts per assigned type.",
     "structure": "sample_id to { cell_type_name: count }",
-    "key_type": "Cell type names. 'unknown' = spots with no confident assignment.",
+    "key_type": "Cell type names. 'unknown', 'NA', or empty column names = spots with no confident assignment.",
     "value_type": "integer - number of spots assigned to each cell type"
   },
   "multiqc_deconvolved_probs": {
@@ -49,15 +49,16 @@
     "value_type": "float, range 0-1 - higher = more confident assignment"
   },
   "multiqc_squidpy_ligrec_interactions": {
-    "description": "Squidpy ligand-receptor interaction scores. Mean interaction across samples, shown when no differential interactions were found between sample groups.",
+    "description": "Squidpy ligand-receptor interaction scores. This is always a pre-filtered report. Mean interaction across samples are shown when no differential interactions were found between sample groups, otherwise the most contrasting once are shown.",
     "structure": "sample_id to { interaction_key: score }",
-    "key_format": "LIGAND-RECEPTOR | Sender_cell_type -> Receiver_cell_type",
+    "key_format": "LIGAND-RECEPTOR-Sender_cell_type-Receiver_cell_type",
     "key_example": "'MIF-CD74-type B pancreatic cell-type A enteroendocrine cell' = MIF (ligand) binding CD74 (receptor), type B pancreatic cell sending to type A enteroendocrine cell.",
     "value_type": "float - mean interaction score; higher = stronger interaction",
-    "note": "Some gene names contain hyphens (example: HLA-C, HLA-DRA), so the key cannot be split on hyphens alone."
+    "note": "Some gene names contain hyphens (example: HLA-C, HLA-DRA), so the key cannot be split on hyphens alone.",
+    "analysis_instructions": "Look for top differences in interaction scores across metadata groups, top similarities across groups, but also the frequency of ligands and receptors."
   },
   "multiqc_Moran_I_interactions": {
-    "description": "Moran's I spatial autocorrelation scores per gene. Mean interaction across samples, shown when no differential interactions were found between sample groups.",
+    "description": "Moran's I spatial autocorrelation scores per gene. This is always a pre-filtered report. Mean interaction across samples are shown when no differential interactions were found between sample groups, otherwise the most contrasting ones are shown.",
     "structure": "sample_id to { GENE-I: score }",
     "key_format": "GENE_NAME-I (example: 'CXCL14-I', 'HLA-DRB1-I')",
     "value_type": "float, range 0-1 - higher = expression more spatially clustered across tissue spots",
@@ -67,6 +68,7 @@
     "description": "Cell type immediate neighborhood across samples. Each section (multiqc_spatial_neighbors, _1, _2, ...) represents one focal cell type and counts how many neighbors of each type surround it. Focal cell types are dynamically generated during merge based on actual data.",
     "structure": "sample_id to { neighbor_cell_type: count }",
     "key_type": "Cell type names. 'NA' = spots with no valid neighborhood assignment.",
-    "value_type": "float - number of immediate neighbors of that cell type"
+    "value_type": "float - number of immediate neighbors of that cell type",
+    "analysis_instructions": "Compare groups for difference and similarities. Also estimate mean neighborhood frequency without 'self' neighbours, this way the border of cell type clusters can be assessed."
   }
 }