FAQs
What audit logs does SMS have?
All API calls to the Sample Matching Service will be audited in line with the Service Audit Requirements set out in Audit Requirements for SNP check service version 1.0.
These audit logs will be available as ad-hoc reports via the Genomics England Service Desk (www.bit.ly/ge-servicedesk).
What is the URL for the Sample Matching Service (SMS)?
The URL for the BETA and UAT instances of the Sample Matching Service is: https://samplematchservice-gms-beta.genomicsengland.nhs.uk
The URL for the production instance of the Sample Matching Service is: https://samplematchservice.genomicsengland.nhs.uk
What are the requirements for the VCF upload?
- Each VCF must represent one sample
- Each VCF must contain genotype information for ≥24 SNPs, including SNP calls to the reference base.
-
Upon submission of the VCF (via a secure REST web service) the following parameters will also be included as path parameters:
-
The human readable NGIS Referral ID (12 characters)
-
The human readable NGIS Patient ID (12 characters)
-
The dispatched_lab_sample_id from GeL1001 CSV
-
It is preferred that GLHs upload SNP VCF files with the ALT allele populated even at homozygous reference (wild type) positions (i.e. not missing or “.”) to avoid any potential for ambiguity in the VCF comparison. If this is not possible, the SMS can handle homozygous reference ALT alleles specified as missing (“.”).
-
Additionally, it is preferred all VCF entries are biallelic i.e. only have a single ALT allele specified. The service will attempt to decompose multi-allelic sites into the biallelic components but it is not expected they will be provided.
Who should upload SNP files?
SNP files are uploaded by the Genomic Laboratory Hub (GLH) who has access to the sample being tested e.g. the GLH who requested the test.
Where is the health check for the SMS?
The health check for the Sample Matching service can be found at this site:
PROD: https://samplematchservice.genomicsengland.nhs.uk/health/1/
UAT/BETA: https://samplematchservice-gms-beta.genomicsengland.nhs.uk/health/1/
Does the SMS work for RD and Cancer cases?
The SMS is only for rare disease referrals.
What happens if there is a SNP mismatch?
If there is a SNP mismatch between the SNPs calculated by Genomics England and the SNPs submitted by the GLH, the case will move into the "Identity Check Failures" tab of the Interpretation Portal and an email alert will be sent immediately to the GLH email address supplied to Genomics England for this purpose.
How is a SNP mismatch calculated?
SNP mismatches are calculated when the SNP files (one from the GLH and one from Genomics England) go through comparison. For each SNP, a match (a SNP shared between the two samples) is defined in one of two contexts:
-
Where none of the variants have a missing value (.) in the genotype:
- To be classified as a shared SNP, the SNP in the GLH file and the Genomics England file should share the same value for the following in the VCF fields:
- CHROM
- POS
- REF
- They should also share the same allele combination. Please note: this comparison always uses the ALT field, however Genomics England do support '.' values in the ALT field when the genotype is 0/0.
- To be classified as a shared SNP, the SNP in the GLH file and the Genomics England file should share the same value for the following in the VCF fields:
-
Where one or both variants have ONE missing value (.) in the genotype:
- To be classified as a shared SNP, the SNP in the GLH file and the Genomics England file should share the same value for the following in the VCF fields:
- CHROM
- POS
- REF
- They should also share the same allele count for all of the shared alleles between both variants.
- N.B. This is a more relaxed match to compensate for lack of data.
- To be classified as a shared SNP, the SNP in the GLH file and the Genomics England file should share the same value for the following in the VCF fields:
Description of the Comparison algorithm
The result of the comparison should be: - A list of matched SNPs - A list of mismatched SNPs - The probability of each shared SNP to be shared assuming the 2 samples are siblings, calculated using the allele frequency of each given population (this information is provided in the Genomics England VCF file) - The probability of each shared SNP to be shared assuming the 2 samples are unrelated, calculated using the allele frequency of each given population. - Combined probability of the probabilities for each of the SNPs calculated using the allele frequency of each given population and assuming samples are siblings. - Combined probability of the probabilities for each of the SNPs calculated using the allele frequency of each given population and assuming the samples are unrelated.
What is the minimum number of SNPs required?
The minimum number of SNPs required for the Sample Matching Service is 24.
What does the "-1 Something really bad happened error" mean?
This error means can mean, but is not limited to, that the user's token has expired. For more information regarding error messages in SMS, please contact the Genomics England Service Desk
How long does the SMS token last for?
The SMS token lasts for 20 minutes before timing out.
Can I use my CIP-API client credentials for the SMS?
Each GLH was issued a set of client credentials specifically for querying the SMS. Details of client credentials can be obtained from the Genomics England Service Desk.
When should I upload my SNP file?
Samples should only be uploaded to the SMS if they are present in Biobank.
GLHs can submit SNP files around 60 seconds after the submission of a GEL1001 CSV file in TOMs.
Once a user has posted a GEL1001 CSV file that has the particular sample to the SFTP server, an automated job runs in the background to push this into the Biobank. This process takes around 60 seconds, hence the small delay from submission of sample to submission of SNP file.
How is the comparison obtained?
The CIP-API gets the URL for the VCF file from HTSget, and then passes that to the SMS which does the comparison.
What should I do once I have uploaded a correct SNP file after a SNP check failure?
GLHs should not need to trigger a check - when a file it is uploaded, it will be updated automatically (if the case is already in CIPAPI).
How do I override the SNP check if I want to progress a case even if the SNP check fails to meet the pass criteria?
The SNP check can be overriden using the following parameter no_snp_sample=true:
e.g.
PUT https://{sms_url}/sample_vcf/{referral_id}/{patient_id}/{dispatched_lab_sample_id}?no_snp_sample=true
where sms_url is either:
samplematchservice-gms-beta.genomicsengland.nhs.uk for UAT
or
samplematchservice.genomicsengland.nhs.uk for PROD
This has to be a PUT request and cannot be done using a normal internet browser i.e. use POSTMAN etc. like you normally do when interacting with SMS
Warning
You should only use this option in exceptional circumstances (e.g. urgent cases and assay failures) after reviewing the reason for the SNP mismatches.