How to interpret common Upload Reference Dataset error messages in Xenium Panel Designer

1. features.tsv.gz file errors:

1.1  'Gene Expression' is missing from the third column of  features.tsv.gz file:

{"timestamp":"YYYY-MM-DDTXX:XXXXXX",
 "level":"ERROR",
 "fields":
     {"file_name":"matrix",
      "field_name":"num_features",
      "found":"0 \"Gene Expression\" features",
      "expected":"At least one \"Gene Expression\" feature. We only use features with the type \"Gene Expression\", which is usually the third column of features.tsv.gz. Please see https://www.10xgenomics.com/support/software/cell-ranger/analysis/outputs/cr-outputs-mex-matrices for details."},
 "target":"Input"}

The error above means that the 'Gene Expression' is missing from the third column of your features.tsv.gz file. Please go back and check if your features.tsv.gz file contains a third column that identifies the type of the feature. Xenium Panel Designer only uses features with the type 'Gene Expression.' An error will occur if there is no third column or if 'Gene Expression' is not present in the third column.

1.2 Gene names are missing:

{"timestamp":"YYYY-MM-DDTXX:XXXXXX",
 "level":"ERROR",
 "fields":
     {"file_name":"",
      "field_name":"","found":"0 genes","expected":"At least 1 gene"},
 "target":"Input"}

{"timestamp":"YYYY-MM-DDTXX:XXXXXX",
  "level":"ERROR",
  "fields":
      {"file_name":"CUSTOMER",
       "message":"Unable to load parameters: Must provide at least one gene"},
  "target":"IO"}

The above error message means that gene names are missing from your features.tsv.gz file. Your  uploaded  features.tsv.gz file may look like:

Please ensure there are gene id and gene name in the first and second columns.

The correct format of the features.tsv.gz file should look similar to below - the first column should be the Ensembl ID, the second column should be the gene name, and the third column should be the feature type. The feature type will typically be 'Gene Expression' if you want the Xenium Panel Designer to recognize this gene. For more details on features.tsv.gz file, please refer to https://www.10xgenomics.com/support/software/cell-ranger/latest/analysis/outputs/cr-outputs-mex-matrices.

 

2. matrix.mtx.gz file errors:

{"timestamp":"YYYY-MM-DDTXX:XXXXXX",
 "level":"ERROR",
 "fields":
     {"file_name":"matrix.mtx.gz",
      "message":"Matrix type was wrong (Float)"},
 "target":"Input"}

The error message above means that the count in the matrix.mtx.gz file is stored as a float datatype A float is a number that includes decimals; for example, 1.000000 is a float, and 1 is an integer. 

The raw matrix.mtx.gz file should not, and should never have been, normalized. This means the first line should be %%MatrixMarket matrix coordinate integer general, and all values in the matrix should be integers.

It is very important that this matrix is not normalized or gene-filtered. Normalizing/filtering limits our ability to assess the impacts of optical crowding. If the matrix contains a subset of the total gene count data, the representation per gene will be skewed.

The unnormalized matrix.mtx.gz file should look like:

%%MatrixMarket matrix coordinate integer general
%
20514 57886 94756451
13 1 1
14 1 1
30 1 1

For more details on matrix.mtx.gz file, please refer to https://www.10xgenomics.com/support/software/xenium-panel-designer/latest/tutorials/create-single-cell-reference#ref-format-matrix

 

3. barcodes.tsv.gz file errors:

{"timestamp":"YYYY-MM-DDTXX:XXXXXX",
 "level":"ERROR",
 "fields":
     {"file_name":"matrix",
      "field_name":"barcodes.tsv.gz",
      "found":"x_number entries",
      "expected":"y_number entries (the number of barcodes in your single cell matrix)"},
 "target":"Input"}

The above error message means that the number of lines (x_number) in the barcodes.tsv.gz file is inconsistent with the number of barcodes (y_number) in the matrix.mtx.gz file. We generally require the number of barcodes in the barcodes.tsv.gz file equal to the number of barcodes in the matrix.mtx.gz file. 

You can find the number of barcodes from the first data line of the matrix.mtx.gz file. Using the matrix.mtx.gz file above as an example, the first data line shows the size of the matrix. There are 20,514 rows (features), 57,886 columns (barcodes), and 94,756,451 non-zero values.

Please note barcodes.tsv.gz file should only contain barcodes; this error sometimes occurs because there's a name or header in the barcodes.tsv.gz file. You can check if there is a header at the top or bottom of the file by using the following command lines:

gzip -cd barcodes.tsv.gz | head -n 2
gzip -cd barcodes.tsv.gz | tail -n 2

The correct format of the barcodes.tsv.gzfile should look like:

 

4. Annotation file errors:

4.1 Annotation file is missing:

The archive must contain exactly one (.csv, .tsv) file

The above error message means the annotation file is missing.

4.2 Annotation file has an incorrect header:

Only files containing the headers (barocde, annotation) are accepted

The above error message means the header of annotation file is either missing or not (barcode,annotation).