The analysis summary HTML file is provided in the output folder after a Xenium Analyzer run completes. It is an initial point of reference for determining sample performance on the Xenium In Situ platform. Read the analysis summary overview for general interpretation guidance, including descriptions of the metrics and characteristic plots for the Xenium In Situ Gene Expression Solution:
On this page, we provide guidance on the alert warnings and errors that may appear at the top of the analysis summary file. The tables below provide information about:
- Alert message and description
- Threshold for triggering warnings or errors
- Possible explanations for the alert and suggested actions
A note on the difference between warnings and errors:
The analysis summary displays alerts based on many of the metrics computed in the pipeline to draw attention to metrics of concern and save the user time. However, no single metric determines the success or failure of a run and there is significant variation depending on the experiment and sample. Therefore when you see any alert, it is important to consider the experimental setup and whether the metric invalidates further analysis of the data.
- Warnings are displayed when a metric is within an "acceptable" range but could indicate a data quality issue (yellow triangle).
- Errors are displayed when a metric falls outside of an “acceptable” range. However, note that after manual review, the data may still be usable for downstream analysis (red triangle).
The sections below describe alerts related to gene panel, image-processing, segmentation, and decoding.
= Warnings, = Errors
| Alert definition | Associated metric & alert thresholds | Suggestions |
|---|---|---|
| Potentially wrong panel file used: Detected codewords do not match the panel file well (e.g. the proportion of unassigned codewords to assigned codewords is high). | Internal pipeline flag Warning: TrueError: N/A | A warning may indicate an incorrect panel file (gene_panel.json) was selected during run set up. Alternatively, the wrong probes were added to the slide. Suggested action: Check that the panel file and probes are correct. If the wrong panel file was selected, run Xenium Ranger relabel with the correct panel. |
= Warnings, = Errors
| Alert definition | Associated metric & alert thresholds | Suggestions |
|---|---|---|
| Poor quality imaging cycles detected: At least one imaging cycle has over 70% of transcripts missing. | Internal pipeline flag Warning: N/A Error: True | An error may indicate an algorithmic failure or instrument error. Alternatively, this can result from poor sample quality, low sample complexity, or problems with sample handling, as very low transcript density can trigger this error. This error will impact the quality scores of transcripts from genes that would have been imaged in the affected cycle-channels. Depending on the number of affected cycles, it may impact the number of Q-Score ≥ 20 transcripts. Suggested action: Look at the Image QC tab to identify whether any cycles or channels have missing data or unexplained artifacts. Contact [email protected] to rule out instrument errors. |
| Failed stitching of the morphology image: Flag for checking the success of the global FOV aligner. If the global FOV aligner fails, the target coordinates are used for blending/stitching images. This check is performed on xyz independently, and this flag becomes False if any of xyz fails. | Internal pipeline flag Warning: FalseError: N/A | Global FOV alignment for stitching failed. This may be caused by selecting too many FOVs without any tissue. The effects may include ghosting artifacts in the morphology image and RNA deduplication may have failed. Suggested action: Use Xenium Explorer to inspect the morphology image and transcripts (select all) where FOVs overlap. Check if empty or mostly empty FOVs are selected. |
| Inaccurate xy registration of the morphology image: This metric reports the xy deviation of the globally-aligned final estimated FOV coordinate from the pair-wise neighboring FOV registration. The worst value among all FOVs is reported in pixels. | Internal pipeline metric Warning: >10 pixelsError: N/A | Global FOV alignment for stitching shows unusually high errors. This may be caused by selecting one or more FOVs without any tissue. The effects may include ghosting artifacts in the morphology image and RNA deduplication may have failed. Suggested action: Use Xenium Explorer to inspect the morphology image and transcripts (select all) where FOVs overlap. Check if empty or mostly empty FOVs are selected. |
| Inaccurate z registration of the morphology image: This metric reports the Z-deviation of the globally-aligned final estimated FOV coordinate from the pair-wise neighboring FOV registration. The worst value among all FOVs is reported in pixels (before Z-subsampling). | Internal pipeline metric Warning: >12 pixelsError: N/A | Global FOV alignment for stitching shows unusually high errors. This may be caused by selecting one or more FOVs without any tissue. The effects may include ghosting artifacts in the morphology image and RNA deduplication may have failed. Suggested action: Use Xenium Explorer to inspect the morphology image and transcripts (select all) where FOVs overlap. Check if empty or mostly empty FOVs are selected. |
= Warnings, = Errors
| Alert definition | Associated metric & alert thresholds | Suggestions |
|---|---|---|
| High fraction of cells empty: Number of cells with 0 transcripts assigned / Number of cells | Percent of empty cells Warning: N/A Error: >10% | An unusually high fraction of segmented cells were found to contain no transcripts. This could be caused by using a panel that does not contain genes expressed by a major cell type in the sample or poor cell segmentation. Suggested action: Consider whether the gene panel is well-matched to the sample. Then use Xenium Explorer to check that cell segmentation is accurate. If Xenium segmentation does not accurately detect cells, try resegmenting with Xenium Ranger resegment or import-segmentation. |
| Low fraction of cells segmented by stain: (Number of boundary + Number of interior expansion segmented cells) / Number of cells | Percent of cells segmented by stains Warning: <70%Error: <50% | The boundary and interior stain were not informative for calling cell boundaries. This could be caused by suboptimal sample quality, sample type (i.e., non-validated tissue types or species), and/or errors during the Cell Segmentation Staining workflow (CG000749). In rare cases, the error could stem from a failure in the Xenium Analyzer run. Suggested action: Investigate cell segmentation staining morphology images to confirm the presence/absence and quality of boundary and interior stain, including how well they match to cell outlines colored by cell segmentation method. Additional details on assessing multimodal cell segmentation quality are described here. For debugging, consider xeniumranger resegment to disable either or both boundary and interior stains from segmentation logic and revert to nuclear expansion-based segmentation. Contact [email protected] with unexpected outputs. |
= Warnings, = Errors
| Alert definition | Associated metric & alert thresholds | Suggestions |
|---|---|---|
| High adjusted negative control codeword rate: Percent of negative control codewords decoded > Q20 / Percent of negative control codewords in Xenium codebook | Adjusted negative control codeword rate Warning: >1%Error: >5% | Results contain an unusually high rate of negative control codewords relative to the number of codewords in the panel. The presence of high rates of negative control codewords typically indicates problems with decoding and analysis. Suggested action: Contact [email protected]. |
| High negative control probe counts per control per cell: Number of negative control probes decoded > Q20 / Number of negative control probes in Xenium codebook / Number of cells | Negative control probe counts per control per cell Warning: >2.5%Error: >5% | The observed rate of negative control probes per cell per control is higher than anticipated. Information on this metric: What is the Xenium "Negative control probe counts per control per cell" metric? and here. If a few probes are high, these can potentially be excluded from the analysis. If all negative control probes are high, this could potentially indicate issues with the input sample quality or the assay workflow (e.g., probe washes were performed at incorrect temperature or wash was incomplete). Suggested action: Follow guidance in articles linked above and contact [email protected] for additional help. |
| Low decoded nuclear transcripts per 100 µm2: Number of transcripts decoded in nuclei > Q20 / Total nucleus area | Nuclear transcripts per 100 µm2 Warning: <10Error: <1 | The density of detected transcripts is unusually low. This metric is dependent on sample complexity and quality. In most cases, a warning or error may indicate poor sample quality, low sample complexity, or a problem with sample handling. The top two causes of low sample quality are 1) low RNA content in fresh frozen or FFPE samples or 2) over or under fixation in FFPE samples. The top two causes of problematic sample handling include 1) evaporation on the thermal cycler or 2) incorrect preparation of master mixes. Low density alerts can also stem from insufficient nucleus or cell segmentation. In rare cases, this alert could indicate algorithmic failures (e.g., insufficient nucleus segmentation). Suggested action: First, investigate the potential for low sample quality. For both FFPE and FF samples, a lack of punctate nuclei and gray tissue in the DAPI channel is usually associated with decreased decoding. In addition, focus on tissue integrity with H&E staining and RNA quality with DV200. Additional FFPE fixation considerations are outlined in Do you have recommendations for FFPE tissue fixation for Xenium? and Do you have tips and tricks for pre-fixation tissue handling for Xenium? KB articles. |
| Low fraction of gene transcripts decoded with high quality: Number of transcripts decoded > Q20 / Number of transcripts decoded | Percent of all gene transcripts that are high quality Warning: <60%Error: <50% | The quality of decoded transcripts is unusually low. This metric is dependent on sample complexity and quality. An error may indicate poor sample quality or low sample complexity, problems with sample handling, algorithmic failures, or instrument error. It can be triggered along with the "Poor imaging quality" alert. It can also be triggered when transcript density is very high, for example, in tumor samples with very high expression of multiple panel genes. Suggested action: Contact [email protected]. |
| Low fraction of predesigned transcripts decoded with high quality: Number of predesigned gene transcripts decoded > Q20 / Number of predesigned gene transcripts decoded | Percent of predesigned gene transcripts that are high quality Warning: <60%Error: <50% | An unusually low fraction of transcripts that belong to the pre-designed (10x-designed) portion of the gene panel decoded with high quality (Phred quality score ≥ 20). Suggested action: Contact [email protected]. |
| Low fraction of custom transcripts decoded with high quality: Number of custom gene transcripts decoded > Q20 / Number of custom gene transcripts decoded | Percent of custom gene transcripts that are high quality Warning: <60%Error: <50% | An unusually low fraction of transcripts that belong to the custom portion of the gene panel decoded with high quality (Phred quality score ≥ 20). Suggested action: Contact [email protected] |
| Low fraction of transcripts within cells: Number of transcripts decoded > Q20 assigned to cells / Number of transcripts decoded > Q20 | Percent of transcripts within cells Warning: <50%Error: N/A | An unusually low fraction of transcripts are assigned to cells. This may happen in tissues like the brain where transcripts contained in axonic projections, for example, tend to not be associated with a cell. Suggested action: Use Xenium Explorer to check that cell segmentation is accurate. If Xenium segmentation does not accurately detect cells, try resegmenting with Xenium Ranger resegment or import-segmentation. |