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:
{"timestamp":"YYYY-MM-DDTXX:XXXXXX",
"level":"ERROR",
"fields": {"file_name":"features.tsv.gz",
"field_name":"XXXX","found":"1 column","expected":"At least 2 tab-delimited columns (Ensembl ID and gene symbol)"},
"target":"Input"}
The above error message usually means there's less than 3 columns in the features.tsv.gz
file. Please ensure that the first and second columns contain the gene ID and gene name, respectively, and that the third column contains 'Gene Expression'.
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.000 or 1.234 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 2
30 1 1
There are cases where an unnormalized matrix is stored in floating-point format, with all integers displayed as "N.000". For example:
%%MatrixMarket matrix coordinate real general
%
20514 57886 94756451
13 1 1.000
14 1 2.000
30 1 1.000
If this is the case, you can use the following command lines to perform the conversion. (This script might take a while to run.)
(echo -e "%%MatrixMarket matrix coordinate integer general\n%"; awk '{print $1,$2,int($3)}' <(gzip -cd matrix.mtx.gz | tail -n +3)) > matrix.mtx
gzip -c matrix.mtx > matrix.mtx.gz
However, if in your matrix file, the 3rd column contains non-zero decimal places (e.g., 1.023), this indicates that your matrix file is normalized. Using the command line above in this case will result in an incorrect prediction.
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.gz
file should look like:
4. Annotation file errors:
4.1 Annotation file is missing:
The archive must contain exactly one (.csv, .tsv) file
The error message above indicates that the annotation file is either missing or does not have a .csv
or .tsv
extension. For example, an annotation file with a .txt
extension or a compressed file (e.g., annotation.csv.gz
) will trigger the same error message.
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).