# DRAGEN TSO 500 and TSO 500 ctDNA Analysis Software
DRAGEN TruSight™ Oncology 500 and DRAGEN TruSight™ Oncology 500 ctDNA Analysis Software support secondary analysis for the data generated by assays in the TruSight™ Oncology 500 (TSO 500) portfolio:
* **DRAGEN TruSight™ Oncology 500 Analysis Software** supports the following assays, all Research Use Only (RUO):
* TruSight Oncology 500 Assay
* TruSight Oncology 500 High-Throughput Assay
* TruSight Oncology 500 HRD Add-on Assay
* TruSight Oncology 500 v2 Assay
* **DRAGEN TruSight™ Oncology 500 ctDNA Analysis Software** supports the following assays, all Research Use Only (RUO):
* TruSight Oncology 500 ctDNA Assay v1
* TruSight Oncology 500 ctDNA v2 Assay
Depending on the version, the analysis software is available on:
* **Illumina BioInsight Platform Core (formerly ICA):** A cloud-based secure platform for data analysis and management. Analysis setup, monitoring, and results access is facilitated via user-friendly interface of BaseSpace Sequence Hub.
* **DRAGEN server:** An on-premises server that offers secondary analysis in a fraction of the time compared with a traditional CPU-based system.
* **On-board of select instruments:** Enabled by a user-friendly analysis application installed on a sequencer.
This resource provides information on installation, configuration, running, troubleshooting as well as analysis algorithms of DRAGEN TruSight™ Oncology 500 and DRAGEN TruSight™ Oncology 500 ctDNA Analysis Software.
# F2 Support on BioInsight Platform Core
#### **Mandatory Upgrade for TSO on BioInsight Platform Core (formerly ICA)**
[Amazon recently announced](https://aws.amazon.com/about-aws/whats-new/2025/02/amazon-ec2-f2-6xlarge-new-f2-instance-size/) that their F1 instances, which are used by TSO 500 pipelines on BioInsight Platform Core (formerly ICA), will be replaced by a new generation of FPGA-powered cloud hardware, Amazon EC2 F2 instances. Furthermore, F1 instances will cease availability on December 20, 2025, their end-of-life date. To ensure uninterrupted service, Illumina is releasing new versions of current DRAGEN TSO 500 and DRAGEN TSO 500 ctDNA pipelines on Platform Core compatible with F2 instances.
**F2-compatibility provides *****significant***** performance improvements**: 40% lower turnaround time for TSO 500 analyses, on average. Furthermore, this suite of versions has been validated to produce bit-exact results.
To aide your transition to F2-compatible pipelines, this document contains:
* [Recommended transition paths](#recommended_transition_paths) for all current pipeline versions
* [Instructions for accessing new pipelines](#how-to-access-new-pipeline-versions), no matter how you launch analyses
* [Detailed comparisons](#pipeline_differences_across) between pipeline versions on each transition path
## **Bit exact results comparisons**
Bit-exact means that the new F2-compatible versions will have no analytical changes to the bioinformatics pipeline and results are identical to the current F1-compatible versions.
For each new pipeline version, the same data set was analyzed with both the F2-compatible and F1-compatible pipeline versions. For each output file in Logs\_Intermediates/ and Results/ folders, F1 and F2 outputs were compared using an automated script. All differences were logged and manually reviewed.
Across all pipeline versions, the only changes observed were those that were expected: related to versioning and naming (pipeline name, analysis ID, time stamp, etc.) and the mapping rate, a metric found in mapping\_metrics.csv, an output of DNA and RNA Map/ Align.\
\
Mapping Rate is a measure of speed, in millions of reads per second. It varies based on the hardware used, can be different between cloud, local, different fpga cards, etc. Changes to mapping rate do not impact map/ align outputs, and therefore there is no impact to results.
## **Turnaround time improvements**
F2 instances introduce significant capacity and performance improvements compared to the currently used F1 instances, with approximately 40% lower turnaround time for the same TSO 500 analysis on F2 instances versus F1.
See a summary of turnaround time improvements in the table below. Run Time is the time analysis was ongoing, while Analysis Turnaround Time (TAT) is the end-to-end processing time: from submitting the analysis to results being available on Platform Core.
| Pipeline Version | Run Time Improvement | Analysis TAT Improvement |
| ------------------------------ | ------------------------- | ------------------------- |
| DRAGEN TSO 500 v2.6.0.8 | 1.84x (46%) | 1.69x (41%) |
| DRAGEN TSO 500 v2.5.2.6 | 2.46x (59%) | 1.86x (46%) |
| DRAGEN TSO 500 ctDNA v2.6.1.8 | 1.55x (35%) | 1.40x (29%) |
| DRAGEN TSO 500 ctDNA v2.6.0.25 | 1.90x (47%) | 1.74x (42%) |
| **TSO 500 Overall** | **1.80x (44% reduction)** | **1.65x (39% reduction)** |
## **Recommended transition paths**
Starting in May 2025, Illumina will be releasing F2-compatible versions (of some, but not all, current pipelines) on Platform Core.
For pipelines *without* bit-exact F2 versions, we recommend following Transition Path A and upgrading to the highest available F2-compatible pipeline (v2.6.0.8 tissue and v2.6.1.8 ctDNA).
For pipelines with bit-exact F2 versions, you may choose to transition to the bit-exact version (Transition Path B) or upgrade to the highest available version (Transition Path A).
For those following Transition Path A and upgrading their pipeline to a newer version, we provide additional information about changes between pipeline versions [here](#pipeline_differences_across).
### **DRAGEN TSO 500 Recommended Transitions**
Current Version
Recommended Version
Transition Path
v2.1.2
v2.6.0.8*
A: pipeline upgrade
v2.1.2 HRD
v2.6.0.8*
A: pipeline upgrade
v2.5.2
v2.5.2.6*
B: bit-exact
v2.5.2 HRD
v2.5.2.6*
B: bit-exact
v2.6.0
v2.6.0.8*
B: bit-exact
v2.6.0 HRD
v2.6.0.8*
B: bit-exact
**\*will include HRD**
{% hint style="success" %}
A note for those using the HRD add-on assay kit:
With previous pipelines versions on Platform Core, Illumina released two configurations: DRAGEN TSO 500 HRD, which supported all TSO analysis steps including those enabled by the HRD add-on assay (GIS, LOH#, Absolute Copy Number#) and DRAGEN TSO 500, which did not include those outputs specific to the HRD add-on assay.
For F2-compatible pipeline versions, Illumina will only release one configuration, DRAGEN TSO 500, which will support both options: TSO 500 with and without the HRD add-on assay kit.
#LOH and Absolute Copy Number are beta features, available starting in DRAGEN TSO 500 v2.5.2.
{% endhint %}
### **DRAGEN TSO 500 ctDNA Recommended Transitions**
Current Version
Recommended Version
Transition Path
v2.1.1
v2.6.1.8
A: pipeline upgrade
v2.5.0
v2.6.1.8
A: pipeline upgrade
v2.6.0
v2.6.0.25
B: bit-exact
v2.6.1
v2.6.1.8
B: bit-exact
## **How to access new pipeline versions…**
Access to new Platform Core pipelines depends on whether you launch analysis manually (via the Platform Core command line or user interface); or use auto-launch to automatically kick off analyses after sequencing.
### **…when manually launching on Platform Core**
To kick off analysis with a new pipeline version, you need that pipeline to be accessible within your Platform Core project. In other words, the bundle containing that pipeline must be linked to your project.
If the new pipeline version is bit-exact to the current version, i.e. [Transition Path B](#recommended_transition_paths), there is nothing for you to do. The new version will be added to the same bundle as your current pipeline and automatically linked to your project. Simply select the new version from the list of pipelines available in your project when you want to use it for a new analysis.
If the new pipeline version is an upgrade from your current version, i.e. [Transition Path A](#recommended_transition_paths), you must link the bundle for that pipeline to your Platform Core project. The bundles are found in Entitled Bundles and named with the corresponding 3-digit pipeline version (e.g. DRAGEN TSO 500 v2.6.0). See the [TSO 500 User Guide](/dragen-tso-500-guides/dragen-tso-500-v2.6/launching-analysis/analysis-launch-on-ica/manual-launch) for instructions on getting started on Platform Core.
### **…when Auto-launching via BaseSpace Sequence Hub**
To auto-launch a new pipeline version, you need to make sure your sample sheet has the correct URN. Updated URNs will be listed on this page when the F2-compatible pipelines are available. See the User Guide for instructions on [Auto-launching TSO 500 pipelines](/dragen-tso-500-guides/dragen-tso-500-v2.6/launching-analysis/analysis-launch-on-ica/autolaunch).
{% hint style="success" %}
**Note:** If you are auto-launching TSO 500 from FASTQ (by first auto-launching BCL Convert 3.10.9), you can continue to use the same BCL Convert 3.10.9 pipeline as before: it does not run on F1 nodes and will therefore continue to work as before.
{% endhint %}
## **Guidance for Upgrading TSO 500 Pipelines (Transition Path A)**
The following sections contain information to guide users that are transitioning from one pipeline version to a higher one (e.g. 2.1 to 2.6). Analytical output changes are detailed along with differences in sample sheet and input requirements.
### **Bioinformatics changes**
Refer to the tables below for a summary of analytical changes (algorithm updates, new variant types, accuracy improvements, etc.) between v2.1 and v2.6.
#### DRAGEN TSO 500 Analytical Changes
For a detailed understanding of [analysis methodology](/dragen-tso-500-guides/dragen-tso-500-v2.6/overview-1) and [output files](/dragen-tso-500-guides/dragen-tso-500-v2.6/analysis-output), please refer to the relevant section of the DRAGEN TSO 500 v2.6 user guide.
Analysis Step
v2.1.2 to v2.5.2
v2.5.2 to v2.6.0
Demultiplex
No change
No change
DNA Map/ Align
No change
No change
Small Variants
• Manifest expanded 8bp into introns
• MNVs and component SNVs/ indels all reported in VCF
• Accuracy improvements
No change
Tumor Mutational Burden
Updates from small variant caller
MNVs removed from TMB calculation
Microsatellite Instability
No change
No change
Copy Number Variants
• Report predicted sex
• Expand CNVs from 55 genes to 514
• Report deletions in addition to amplifications
No change
BRCA Large Rearrangements
• Breakpoint coordinates shifted (now 0-based instead of 1-based)
• Algorithm update for events with small fold change
Genomic Instability Score*
Accuracy improvements
No change
Loss of Heterozygosity*
New biomarker (beta feature)
No change
Absolute Copy Number*
New biomarker (beta feature)
No change
RNA Map/ Align
No change
Differences due to update in DRAGEN versions
RNA Fusions
No change
Accuracy improvements
Splice Variants
No change
Differences due to RNA map align updates
QC Metrics
Added: PER_GENE_MEDIAN_COVERAGE (RNA)
Added:
• gene- and exon-level coverage
• PCT_Q30
• PCT_SOFT_CLIPPED_BASES
Removed: PCT_PF_UQ_READS (%)
DRAGEN SW
v3.10.9 to v3.10.16
v3.10.16 to v3.10.17
**\*only for HRD samples**
#### DRAGEN TSO 500 ctDNA Analytical Changes
For a detailed understanding of [analysis methodology](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/analysis-methods) and [output files](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/analysis-output), please refer to the relevant section of the DRAGEN TSO 500 ctDNA v2.6 user guide.
Analysis Step
v2.1.1 to v2.5.0
v2.5.0 to v2.6.0
v2.6.0 to v2.6.1
Demultiplex
No change
No change
No change
Map/ Align
No change
No change
No change
Small Variants
• MNVs and component SNVs/ indels all reported in VCF
• Accuracy improvements
No change
No change
Tumor Mutational Burden
No change
No change
No change
Microsatellite Instability
No change
No change
No change
Copy Number Variants
Report predicted sex
No change
No change
DNA Fusions
SV evidence BAM added to Logs_Intermediates/
No change
Improved SV detection in samples with high chimeric reads
QC Metrics
No change
• gene- and exon-level coverage
• PCT_Q30
• PCT_SOFT_CLIPPED_BASES
No change
DRAGEN SW
v3.10.9 to v3.10.15
v3.10.15 to v3.10.17
v3.10.17 to v3.10.18
### **Input changes**
#### DRAGEN TSO 500 Input Changes
Refer to the table below for a summary of changes to input requirements between 2.1.2 and 2.6.0. To ensure your sample sheet will pass validation in the 2.6 pipeline, please refer to the [sample sheet requirements](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-requirements) detailed in the DRAGEN TSO 500 v2.6 user guide.
DRAGEN TSO 500 Inputs
v2.1.2
v2.5.2
v2.6.0
Sample sheet section: [Sequencing_Settings]
LibraryPrepKits field is now required.
Valid values are: TSO500, TSO500HT
Sample sheet section: [TSO500S_Data]
Index ID is now optional
FASTQ folder structure
Sub-folders per sample
Sub-folders per sample or one folder with all FASTQs
No change
#### DRAGEN TSO 500 ctDNA Input Changes
Refer to the table below for a summary of changes to input requirements between 2.1.1 and 2.6.0. To ensure your sample sheet will pass validation in the 2.6 pipeline, please refer to the [sample sheet requirements](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/run-planning/sample-sheet-requirements) detailed in the DRAGEN TSO 500 ctDNA v2.6 user guide.
Inputs
v2.1.1
v2.5.0
v2.6.0
v2.6.1
Sample sheet section: [TSO500L_Data]
Index ID is now optional
FASTQ folder structure
Sub-folders per sample
Sub-folders per sample or one folder with all FASTQs
No change
No change
### **References**
For additional details on changes between versions, please refer to the customer release notes for not only the last version, but also each version in between.
####
# Performance Testing
The following sections describe performance testing methods.
## Analytical Performance Testing
Illumina tests the analytical performance of variant calling for TruSight Oncology 500 and TruSight Oncology 500 ctDNA assays using an approach that covers the entire workflow including library preparation, sequencing, and secondary analysis. This approach is used to test a diverse selection of variants. When the variant calling pipeline is expanded to call a new variant class, this approach is always used.
Some versions of the DRAGEN TruSight™ Oncology 500 Analysis Software and DRAGEN TruSight™ Oncology 500 ctDNA Analysis Software include results generated by features tested *in silico* and by beta features. Beta features have not been fully evaluated for performance, see [Beta Features](#beta-features) for more details.
## *In Silico* Testing Methods
Illumina uses *in silico* testing to the test the ability of the software to call an expanded scope of clinically relevant variants, including rare variants. *In silico* testing is used as a complementary method to analytical performance testing with wet lab step to expand the scope of testing. For example, while Illumina has analytically verified the performance of the software for calling complex variants in EGFR, the *in silico* testing approach characterizes the ability of the software to call complex variants in other genes.
For *in silico* testing of the DRAGEN TruSight Oncology 500 Analysis Software, variants of interest are compiled from public databases like COSMIC and ClinVar. Each variant is simulated at different VAF levels by, depending on the variant class, spiking in mutant reads into a normal FFPE background (for sequence variants) or by increasing or decreasing the coverage of exons in the normal FFPE sample (for CNVs, for example, exon-level CNVs). The simulated reads match the expected quality of typical FFPE samples, such as fragment length, error rate, and family size. After the simulation, the software processes samples with spiked-in variants and determines the results. This approach does not include library prep and sequencing of tumor FFPE samples that include the rare variants of interest. The software reports these variants, but analytical verification was not performed.
*In silico* tested features for DRAGEN TruSight Oncology 500 Analysis Software and DRAGEN TruSight Oncology 500 ctDNA Analysis Software are summarized in the table below.
| Name | in Silico Tested Features |
| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DRAGEN TruSight Oncology 500 Analysis Software for TruSight Oncology 500 and TruSight Oncology 500 HT (v2.1+) |
Complex variants in genes beyond EGFR
Insertions and deletions > 25 bp
CNV amplifications
CNV deletions
Variants in intron-exon junctions (2 bp – 10 bp into introns)
|
## Beta Features
DRAGEN TruSight Oncology 500 Analysis Software also includes beta features. The features have not been verified by Illumina due to limited access to samples or lack of an appropriate orthogonal method to perform testing, and, the use of *in silico* testing alone was not sufficient for verification purposes.
Customers are responsible for evaluating and demonstrating performance of any beta features they choose to implement. Beta features are indicated as such in the CombinedVariantOutput.tsv file produced by the DRAGEN TruSight Oncology 500 Analysis Software. Illumina will continue to evaluate beta features with intent to fully release upon completion of verification for each feature.
Beta features are summarized in the table below.
{% hint style="warning" %}
Beta feature results are included in the Combined Variant Output file and other files. However, disclaimers that the results are generated by beta features are only provided in the Combined Variant Output file.
{% endhint %}
| Name | Beta Features |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
DRAGEN TruSight Oncology 500 Analysis Software (v2.6.2+) for :
|
# Known Limitations with Commercial Controls
Using cell lines or contrived samples for validation or as positive controls may result in inconsistent or unusual results depending on how the samples were constructed. Illumina recommends using commercial controls only for the variant class they are intended for. For example, if the sample is contrived for CNVs but not explicitly for SNV, MSI, TMB, or fusions, we would not recommend using this sample for validation or as a positive control for SNV, MSI, TMB, or fusions.
The table below summarizes known limitations with commercial controls for TruSight Oncology 500 assays.
#### **TruSight Oncology 500 ctDNA v2**
Low recall on Deletion chr17 41245586 CT>C (BRCA1 p.K654fs*47) due to a high noise region adjacent to a homopolymer. Under review to be addressed in the future SW versions.
All
Seraseq ctDNA Complete Mutation Mix AF0.5% (MN 0710-0531) or above
All
Lower recall due to the variant observed VAF below the limit of detection (LOD) of the TSO 500 ctDNA assay. See section for more details.
Not recommended for TMB validation due to many small variants having VAF close to the TMB limit of detection. Small changes in preparation and dilution result in significant changes in TMB scores (behavior not observed in clinical samples).
All
Twist cfDNA Pan-Cancer Reference Standard v2
Fusions
False negatives due to a known issue on high efficiently libraries.
2.6.0 and below
Seraseq ctDNA Mutation Mix v2 (multiple VAF)
Fusions
False negatives due to a known issue on high efficiently libraries.
2.6.0 and below
#### **TruSight Oncology 500 v1 and v2**
Product Name
Variant Class
Description
SW Version Impacted
Seraseq® FFPE BRCA1/2 LGR Reference Material (MN 0730-0564)
BRCA LR
Not recommended for LR validation due to 1) high level of noise 2) method of contriving resulting in some artifacts. We have found Seraseq BRCA 1/2 Exon Deletions DNA Mix (MN 0730-0570) to work well.
All
Samples with tumor fraction > 90%
HRD, GIS
The GIS algorithm does not produce reliable results if the sample’s tumor fraction is over 90%, for example, in pure cell samples.
All
### Troubleshooting Missing Variants in Control Samples
If you are using commercial controls to test analytical performance of a TSO 500 or TSO 500 ctDNA assay and an expected variant is not reported, use the following troubleshooting steps:
1. Confirm the variant of interest is within the callable assay manifest BED region. Contact Illumina's Technical Support for the manifest file.
2. Confirm the sample passes the QC metric for the relevant variant class.
3. Confirm the truth set and output use the same genome annotation, for example, hg19 truth set to hg19 output.
4. Confirm the variant of interest is expected to be present with allele frequency above the assay's limit of detection. Review [recommendations for planning analytical studies for TSO 500 ctDNA](/performance-testing/commercial-control-use-with-tso-500-ctdna).
5. Depending on the control, confirm how variant presence was established. Orthogonal methods can differ from the methods used by TSO 500 or TSO 500 ctDNA.
After these preliminary checks, inspect the intermediate output files for the variant of interest. The relevant files are listed in the DNA output sections but some additional variant specific considerations are below.
* **Small variants:** If an expected call is not reported, first check whether the variant is present in `{SAMPLE_ID}_hard-filtered.vcf.gz`. If the variant is present but filtered, review the filter flag to identify the reason. If the variant of interest is not present in that VCF, examine deviations from the reference in `{SAMPLE_ID}_hard-filtered.gvcf.gz` or visualize the locus in the BAM file.
* **CNVs:** If an expected call is not reported, review all gene-level fold changes in `{SAMPLE_ID}.cnv.vcf`. This file reports fold changes regardless of CNV call status. The Segment Mean (SM), which is synonymous with fold change, can be compared directly to the thresholds for amplification and deletion calls used to determine whether a gene is reported as AMP or DEL. In some cases, the fold change is very close to the call threshold, and the lack of a call can be explained by stochastic variability rather than lack of signal. Also note that TSO 500 and TSO 500 ctDNA call only whole-gene deletions or amplifications. If a focal CNV event covers only a small portion of the gene, for example, 1 of 10 exons, the event might not be called.
# Commercial Control Use with TSO 500 ctDNA
The page aggregates materials to help plan analytical studies with commercial controls for TruSight Oncology ctDNA v2 assay.
### Best Practices
* Use commercial controls only for the variant class they are intended for. For example, if the sample is contrived for CNVs but not explicitly for SNV, or fusions, we would not recommend using this sample for validation or as a positive control for SNV or fusions.
* Plan the studies taking into account that the actual VAFs in the control do not match exactly the targeted VAFs and can vary from lot to lot based on the manufacture’s process for creating the controls. The recall could be lower for variants with VAF below the assay’s LOD. Include dilutions above LOD, at LOD, and below LOD.
{% hint style="warning" %}
Sensitivity 95% for variants at 0.5% VAF means that a variant with 0.5% VAF (Limit of detection (LOD)) can be detected at least 95% of the time, for example, in 95 out of 100 replicates. If VAF is lower, the sensitivity is lower and the variant is detected less consistently, less than 95% of the time.
{% endhint %}
* Consult the manufacturer’s CoA for particular lots to determine their stated VAF for the targets in question as well as also understand the limitations and variability in the manufacturer’s method of quantitation of the targets (such as ddPCR or other method). Examples: [technical report](https://www.seracare.com/globalassets/seracare-resources/tpr-0710-0531-seraseq-ctdna-complete-mm-af-0.5-10704781.pdf) for Seraseq ctDNA Complete Mutation Mix AF0.5%, [Certificate of Analysis](https://www.seracare.com/globalassets/seracare-resources/coa-0710-3099-seraseq-ctdna-mutation-mix-v4-af-0.5-10687645.pdf) for Seraseq® ctDNA Mutation Mix v4 AF0.5%.
* Confirm assay’s LOD. LOD values for each variant class are provided in the [TSO 500 ctDNA v2 data sheet](https://www.illumina.com/content/dam/illumina/gcs/assembled-assets/marketing-literature/trusight-oncology-500-ctdna-v2-m-gl-02196/tso500-ctdna-v2-data-sheet-m-gl-02196.pdf).
* Use a pilot study to identify observed VAFs with TSO 500 ctDNA v2 assays before planning a larger study. VAFs determined by TSO 500 ctDNA v2 assay can be found in the “Allele Frequency” column in the Combined Variant Output file.
* Understand the variability inherent in the control sample and that some variability will also exist due to the library preparation.
* Run multiple replicates of the control, especially when near LoD, to account for sample to sample and run to run variability.
* Refer to the [Known Limitations with Commercial Controls](/performance-testing/known-limitations-with-commercial-controls) section for known limitations and deviations in performance, including due to the lot-to-lot variations.
* Use assay performance materials provided by Illumina:
* [TSO 500 ctDNA v2 data sheet](https://www.illumina.com/content/dam/illumina/gcs/assembled-assets/marketing-literature/trusight-oncology-500-ctdna-v2-m-gl-02196/tso500-ctdna-v2-data-sheet-m-gl-02196.pdf)
* Application note on [Using lower input amounts with TruSight™ Oncology ctDNA v2](https://www.illumina.com/content/dam/illumina/gcs/assembled-assets/marketing-literature/trusight-oncology-500-ctdna-v2-input-titration-tech-note-m-gl-02229/tso-500-ctdna-v2-input-titration-tech-note-m-gl-02229.pdf)
* Application notes demonstrating performance for select instruments: [NextSeq 2000 System](https://www.illumina.com/content/dam/illumina/gcs/assembled-assets/marketing-literature/tso-500-ctdna-v2-nextseq-2000-tech-note-m-gl-03798/tso-500-ctdna-v2-nextseq-2000-tech-note-m-gl-03798.pdf), [NovaSeq X System](https://www.illumina.com/content/dam/illumina/gcs/assembled-assets/marketing-literature/tso500-ctdna-v2-novaseq-6000-x-concordance-tech-note-m-gl-03016/tso500-ctdna-v2-novaseq-6000-x-concordance-tech-note-m-gl-03016.pdf) (for [NovaSeq 6000](https://www.illumina.com/content/dam/illumina/gcs/assembled-assets/marketing-literature/trusight-oncology-500-ctdna-v2-m-gl-02196/tso500-ctdna-v2-data-sheet-m-gl-02196.pdf), see [TSO 500 ctDNA v2 data sheet](https://www.illumina.com/content/dam/illumina/gcs/assembled-assets/marketing-literature/trusight-oncology-500-ctdna-v2-m-gl-02196/tso500-ctdna-v2-data-sheet-m-gl-02196.pdf)).
* Section [TSO 500 ctDNA v2 Performance for Seraseq ctDNA Complete Mutation Mix 0.5%AF](#tso-500-ctdna-v2-performance-for-seraseq-ctdna-complete-mutation-mix-0.5-af)
* [Known Limitations with Commercial Controls](/performance-testing/known-limitations-with-commercial-controls) section
* [Demo Data](/performance-testing/demo-data) section
### VAF in Seraseq ctDNA Complete Mutation Mix
Factors that impact variant VAF in Seraseq ctDNA Complete Mutation Mix products:
* The mutation mix products are formulated so that the target VAFs fall within a specified range [as measured by dPCR](https://digital.seracare.com/cg-faq?_gl=1*phm459*_gcl_au*MTE0MjgxNzQyMC4xNzY5MDM1NzIw); for example, the Seraseq ctDNA Complete Mutation Mix AF0.5% includes variants with dPCR‑measured VAFs between approximately 0.400% and 0.625%. For certain variant classes - such as indels and fusions - a VAF near 0.4% is below the LOD for TSO 500 ctDNA v2, which may result in less consistent detection.
* VAFs are measured by dPCR before DNA fragmentation. Subsequent fragmentation can alter the observed VAF.
* Technical reports, [see example](https://www.seracare.com/globalassets/seracare-resources/tpr-0710-0531-seraseq-ctdna-complete-mm-af-0.5-10704781.pdf), provide VAFs determined by the Archer® Reveal ctDNA™ 28 kit. VAFs measured by dPCR can differ from VAFs determined by NGS, as well as change after fragmentation In addition, VAFs are assay‑dependent, and VAFs observed using the TSO 500 ctDNA v2 assay may differ from those determined using the Archer® Reveal ctDNA™ 28 assay.
* Seraseq ctDNA Complete Mutation Mix products may show some batch‑to‑batch variation in individual variant VAFs while still meeting quality control specifications established by dPCR. Illumina aggregates customer reports regarding variants that are not detected due to lower‑than‑expected VAFs in certain batches and can provide additional information upon request.
The newly released next‑generation [Seraseq® ctDNA v4 Reference Materials](https://www.seracare.com/globalassets/seracare-resources/ps-0710-3097.3099.3100.3101-seraseq-ctdna-mutation-mix-v4.pdf) offer several advantages for TSO 500 ctDNA studies:
* The VAF is determined using TSO 500 ctDNA instead of the Archer® Reveal ctDNA™ 28 assay. See [example of Certificate of Analysis](https://www.seracare.com/globalassets/seracare-resources/coa-0710-3099-seraseq-ctdna-mutation-mix-v4-af-0.5-10687645.pdf) for Seraseq® ctDNA Mutation Mix v4 AF0.5%.
* Improved fragmentation process to lower background noise >10x compared to Seraseq ctDNA Complete products
* Expanded number of variants including SNVs, deletions, insertions, INDELs, CNVs, and translocations for the broader coverage.
### MSI testing
When designing analytical performance studies for MSI (also referred to as bMSI), Illumina recommends using as a truth set MSI status for real cancer samples or cell lines, established using an orthogonal method, for example, PCR or tissue NGS. Using contrived reference samples with limited number of microsatellite sites is not recommended due to the design of the MSI algorithm, specifically, the use of > 2,300 microsatellite sites with 6-7 bp size. See [MSI algorithm page](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/analysis-methods/msi) for more details.
### Performance for Seraseq ctDNA Complete Mutation Mix 0.5%AF
The table below summarizes the variant calling results by the TSO 500 ctDNA v2 assay for Seraseq ctDNA Complete Mutation Mix AF0.5% (Material Number 0710-0531, Lot 10624818) across 9 customer sites that participated in the early access program. The call rate, and the average observed VAF, depth and read counts are generated across 9 sites and 19 replicates.
| Gene | AA Change | Variant type | Call Rate | Expected VAF, %\* | Observed VAF, % | Observed Depth | # Variant Allele Reads |
| --------- | ------------------------- | ------------- | --------- | ---------------------- | ---------------- | -------------- | ---------------------- |
| AKT1 | p.E17K | SNV | 100% | 0.51 | 0.32 ± 0.09 | 5424 ± 1745 | 17 ± 6 |
| ALK | p.F1174L | SNV | 100% | 0.54 | 0.57 ± 0.12 | 3115 ± 832 | 18 ± 6 |
| ALK | p.G1202R | SNV | 100% | 0.48 | 0.45 ± 0.12 | 2774 ± 792 | 12 ± 4 |
| BRAF | p.V600E | SNV | 100% | 0.46 | 0.5 ± 0.14 | 4405 ± 1294 | 22 ± 7 |
| BRCA1 | p.K654fs\*47 | Del | 58% | 0.46 | 0.5 ± 0.09 | 4018 ± 1254 | 20 ± 7 |
| BRCA2 | p.R2645fs\*3 | Del | 100% | 0.59 | 0.57 ± 0.11 | 4400 ± 1383 | 25 ± 7 |
| EGFR | p.E746\_A750 del ELREA | Del | 100% | 0.64 | 0.51 ± 0.14 | 2663 ± 628 | 14 ± 5 |
| EGFR | p.L747\_P753>S | Del | 100% | 0.50 | 0.51 ± 0.12 | 2649 ± 563 | 14 ± 5 |
| EGFR | p.L858R | SNV | 100% | 0.53 | 0.49 ± 0.16 | 3605 ± 983 | 18 ± 8 |
| EGFR | p.S752\_I759 del SPKANKEI | Del | 100% | 0.50 | 0.54 ± 0.1 | 3932 ± 1257 | 22 ± 9 |
| EGFR | p.T790M | SNV | 100% | 0.42 | 0.48 ± 0.12 | 4558 ± 1347 | 22 ± 7 |
| ERBB2 | p.A775\_G776 ins YVMA | Ins | 100% | 0.56 | 0.53 ± 0.15 | 4043 ± 1284 | 22 ± 9 |
| KIT | p.D816V | SNV | 100% | 0.56 | 0.46 ± 0.12 | 3717 ± 1205 | 17 ± 7 |
| KRAS | p.G12C | SNV | 100% | 0.54 | 0.5 ± 0.13 | 2920 ± 604 | 15 ± 5 |
| KRAS | p.G12D | SNV | 100% | 0.55 | 0.68 ± 0.18 | 2201 ± 513 | 15 ± 5 |
| KRAS | p.Q61H | SNV | 100% | 0.55 | 0.4 ± 0.12 | 3401 ± 975 | 14 ± 6 |
| NRAS | p.Q61R | SNV | 100% | 0.56 | 0.37 ± 0.11 | 4953 ± 1514 | 18 ± 7 |
| PIK3CA | p.H1047R | SNV | 100% | 0.56 | 0.49 ± 0.12 | 4448 ± 1399 | 21 ± 6 |
| PIK3CA | p.N1068fs\*4 | Ins | 97% | 0.52 | 0.49 ± 0.14 | 3108 ± 766 | 15 ± 5 |
| ERBB2 | | Amplification | 100% | 2.56 copies or 1.28 FC | 1.31 ± 0.01 (FC) | | |
| MET | | Amplification | 100% | 2.41 copies or 1.21 FC | 1.41 ± 0.02 (FC) | | |
| MYC | | Amplification | 92% | 2.37 copies or 1.19 FC | 1.2 ± 0.01 (FC) | | |
| CD74-ROS1 | | Translocation | 89% | 0.53 | 0.41 ± 0.16 | 4291 ± 1153 | 18 ± 8 |
| EML4-ALK | | Translocation | 100% | 0.49 | 0.34 ± 0.12 | 4261 ± 1070 | 14 ± 5 |
| NCOA4-RET | | Translocation | 83% | 0.56 | 0.22 ± 0.07 | 3740 ± 1034 | 8 ± 3 |
\*Expected VAF (%) provided as detected by dPCR for Seraseq ctDNA Complete Mutation Mix AF0.5% (MN 0710-0531, lot 10624818), [Technical Report.](https://www.seracare.com/globalassets/seracare-resources/tpr-0710-0531-seraseq-ctdna-complete-mm-af-0.5-10704781.pdf)
# Demo Data
Illumina provides demo data of several common commercial controls on BaseSpace Sequence Hub generated using different instruments and flow cells.
{% hint style="info" %}
Please log in to your BaseSpace account before accessing demo data via the links provided below.
{% endhint %}
### TruSight Oncology 500 v2
Sequencer
Flow Cell
Description
Data Access
NovaSeq 6000Dx
S1
Several replicas of HD795 and other solid tumor samples. Includes DNA, RNA, HRD.
For the summarized perfrormance and other materials for the TSO 500 ctDNA assay, refer to the [Commercial Control Use with TSO 500 ctDNA](/performance-testing/commercial-control-use-with-tso-500-ctdna) page.
# DRAGEN TSO 500 v2.6
# Introduction to DRAGEN TSO 500 Analysis Software v2.6.x
## Scope
This resource provides information on installation, configuration, running, troubleshooting and analysis algorithms for the following software:
* DRAGEN TruSight Oncology 500 Analysis Software v2.6.0
* for standalone DRAGEN server
* on BioInsight Platform Core (formerly ICA)
* on NovaSeq 6000Dx v2.6.0 (uses a paired DRAGEN server)
* DRAGEN TruSight Oncology 500 Analysis Software on BioInsight Platform Core v2.6.0.8
* DRAGEN TruSight Oncology 500 Analysis Software v2.6.1 (for standalone DRAGEN server)
* DRAGEN TruSight Oncology 500 Analysis Software v2.6.2
* for standalone DRAGEN server
* on BioInsight Platform Core
* on NovaSeq 6000Dx (uses a paired DRAGEN server)
The content is applicable to all software versions unless otherwise specified. The content related to setting up and running the analysis on Platform Core is only relevant to v2.6.0.
## Overview
DRAGEN TruSight™ Oncology 500 Analysis Software supports data analysis for TruSight Oncology 500 Assay , TruSight Oncology 500 High-Throughput Assay, and TruSight Oncology 500 v2 Assay all Research Use Only (RUO).
The software provides local and cloud analysis for DNA and RNA libraries generated from formalin-fixed, paraffin-embedded (FFPE) tissue samples. The assays and the software are optimized to provide high sensitivity and specificity for low-frequency somatic variants across coding exons and additional regions of biological relevance in 523 genes for DNA and RNA biomarkers.
In addition, this software supports data analysis for TruSight Oncology 500 HRD (RUO), which enables detection of homologous recombination deficiency (HRD) through assessment of a genomic instability score (GIS). TSO 500 HRD is available as an optional library prep in TruSight Oncology 500 v2 or as an add-on kit to TruSight Oncology 500.
{% hint style="info" %}
TruSight Oncology 500 v2 and TruSight Oncology 500 HRD are not available in Japan.
{% endhint %}
### DNA biomarkers
* Single nucleotide variants (SNVs)
* Insertions
* Deletions
* Copy number variants (CNVs)
* Exon-level CNVs
* Multinucleotide variants (MNVs)
* Genomic Instability Score (GIS Score) \*
* Tumor fraction\*
* Ploidy\*
### DNA Immunotherapy biomarkers
* Tumor mutational burden (TMB)
* Microsatellite instability (MSI)
### RNA biomarkers (called from 55 genes)
* Fusions
* Splice variants
### Beta features
* Absolute copy numbers (ACN)\*
* Loss of heterozygosity (LOH)\*
Details of the regions covered by the assays can be found in the assay manifest file. Contact your local Illumina representative for more information.
{% hint style="info" %}
\*Requires TruSight Oncology 500 v2 kit or TruSight Oncology 500 HRD add-on kit
{% endhint %}
{% hint style="info" %}
Variant reporting by DRAGEN TruSight™ Oncology 500 Analysis Software is limited by a manifest file and a [block list file](/dragen-tso-500-guides/dragen-tso-500-v2.6/analysis-output/block-list). The manifest file excludes regions where the probe set does not effectively capture targets, and the block list file excludes specific positions from variant calling. TSO 500 assay probes target at least 97% of the CDS of 474 genes. Please contact your local Illumina representative for more information if needed.
{% endhint %}
## Local and Cloud Deployments
Local analysis is available using a standalone DRAGEN server or Illumina Run Manager which is a user interface installed on NovaSeq 6000Dx. The software on the standalone DRAGEN server allows for analysis on a single DRAGEN server or splitting across multiple servers.
Cloud analysis is available on Platform Core with auto-launch or manual launch. Both methods are available from BCLs and FASTQs.
## Instrument Compatibility
DRAGEN TruSight Oncology 500 analysis software v2.6.x is compatible with data generated on the Illumina instruments as summarized in the table below.
Instrument
Bioinsight Platform Core
Standalone DRAGEN Server
Paired DRAGEN server
On-board DRAGEN
NextSeq 550Dx (RUO mode)
Yes
Yes
No
N/A
NextSeq 500/550
Yes
Yes
N/A
N/A
NovaSeq 6000
Yes
Yes
N/A
N/A
NovaSeq 6000Dx (RUO mode)
Yes
Yes
Yes
N/A
NextSeq 1000/2000
Yes
Yes
N/A
No
NovaSeq X1
Yes
Yes
N/A
No
1\. Data generated with 5B flow cell is only compatible with DRAGEN TSO 500 analysis software v2.6.2. For required sample sheet modifications for cloud auto-launch analysis, follow steps described here in [Sample Sheet Preparation for 5B Flow Cell](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-preparation-for-5b-flow-cell). For analysis on the DRAGEN server, refer to [Analysis Launch on Standalone DRAGEN Server](/dragen-tso-500-guides/dragen-tso-500-v2.6/launching-analysis/run-dragen-tso-software) page.
## Navigation of Guide
This resource provides information on installation, configuration, running, troubleshooting as well as analysis algorithms of DRAGEN TruSight Oncology 500 analysis software on BioInsight Platform Core, standalone DRAGEN server, and the NovaSeq 6000Dx analysis application.
# Getting Started
# Installation of 2.6.0 on Standalone DRAGEN Server
## Overview
The installation script for DRAGEN TruSight Oncology 500 Analysis Software installs the following software and dependencies:
1. DRAGEN TruSight Oncology 500 Analysis Software itself
2. DRAGEN Software if a compatible version is not present
3. Docker software if a compatible version is not present
4. A script required to generate DRAGEN genome hash table
5. A script to check that DRAGEN TruSight Oncology 500 Analysis Software is installed properly
## Installation Requirements
### Hardware
* DRAGEN server v3 or v4.
* If performing analysis for the TruSight Oncology 500 High-Throughput assay, mkfifo needs to be enabled on the network-attached storage (NAS).
### Software
* By default Linux CentOS 7.9 operating system (or later) or Oracle Linux 8 (or later), is provided. Oracle Linux 8 is recommended.
* Docker Software, see table below.
* DRAGEN Software, see table below.
| Software Dependency | Compatible | Installs |
| ------------------- | -------------------------------- | ----------------------- |
| Docker | 20.10 or greater | Docker 20.10.15 |
| DRAGEN Software | v3.10.x where x is 17 or greater | DRAGEN Software 3.10.17 |
{% hint style="warning" %}
DRAGEN TruSight Oncology 500 v2.6.0 Analysis Software is not compatible with DRAGEN Software v4.0 or above on the same standalone DRAGEN server.
{% endhint %}
### Licenses
* `TSO500Combined` license
* `TSO500_HRD` license (to analyze data generated with the TSO 500 HRD add-on kit)
`TSO500Combined` license has been pre-installed to DRAGEN servers in manufacturing since August 2022 and `TSO500_HRD` since February 2025 and additionally distributed to DRAGEN servers connected online. To generate a list of installed DRAGEN server licenses, run the following command: `/opt/edico/bin/dragen_lic`. If a license is not installed, contact Illumina Customer Care at for the license.
### Permissions
Illumina recommends logging in as root user for installation, but as a non-root user for running TSO 500 analysis.
* A non-root user must be a member of the Docker group to run Docker. For more information on Docker permission requirements and alternatives to running as root, refer to the Docker documentation available on the [Docker website](https://www.docker.com/).
* Installing and uninstalling DRAGEN TruSight Oncology 500 Analysis Software and running the system check requires root privileges.
* Run DRAGEN TruSight Oncology 500 Analysis Software without being logged in as a root user. Running the DRAGEN TruSight Oncology 500 Analysis Software as root is not required or recommended.
## Compatibility with other TruSight Oncology 500 and TruSight Oncology 500 ctDNA Analysis Software
DRAGEN TruSight Oncology 500 Analysis Software v2.6.0 can be installed on one DRAGEN server with:
1. DRAGEN TruSight Oncology 500 ctDNA Analysis Software v2.6.0 (v3.10.17\*)
2. One prior 2.x version of DRAGEN TruSight Oncology 500 ctDNA Analysis Software (v2.1.1 (v3.10.9\*), v2.5.0 (v3.10.15\*), 2.6.0 (v3.10.17\*), 2.6.1 (v3.10.18\*))
3. One prior 2.x version of DRAGEN TruSight Oncology 500 Analysis Software (v2.1.1 (v3.10.9\*), v2.5.3 (v3.10.16\*)dr
\*DRAGEN Software version
Contrary to the prior versions, the installation scripts for DRAGEN TruSight Oncology 500 Analysis Software v2.6.0 and DRAGEN TruSight Oncology 500 ctDNA v2.6.0 do not uninstall previous versions of DRAGEN TruSight Oncology 500 Analysis Software. To uninstall a previous version of DRAGEN TruSight Oncology 500 Analysis Software, refer to the respective guide.
{% hint style="info" %}
When installing DRAGEN TruSight Oncology 500 and DRAGEN TruSight Oncology 500 ctDNA software on the same DRAGEN server, install the software with the highest corresponding DRAGEN Software version last, as versions below v2.6.0 will overwrite with its corresponding DRAGEN Software version.
{% endhint %}
{% hint style="warning" %}
If a prior version of DRAGEN TruSight Oncology 500 Analysis Software (eg. v2.5.3) is installed after v2.6.0, re-execute the installation script for v2.6.0 to install the compatible version of DRAGEN Software without impacting other installations.
{% endhint %}
## Installation Instructions
As a root user, perform the following steps to install DRAGEN TruSight Oncology 500 v2.6.0 Analysis Software:
1. Contact Illumina Customer Care at to obtain the DRAGEN TruSight Oncology 500 Analysis Software installer package.
2. Download the installation package provided in the email from Illumina. **The link expires after 7 days.**
{% hint style="info" %}
It is recommended to use a command line tool like wget or curl to download the file rather than pasting the link into the web browser bar. For example:
`curl -o {filename} "{link}"`
`wget -O {filename} '{link}'`
Where the file name is the installation script file name, and the link is provided by Illumina Customer Care.
{% endhint %}
3. Make sure no other analysis is being performed. Installing the software while performing other analyses prevent the installer process from proceeding.
4. Copy the install script to the `/staging` directory to store the script in the directory.
{% hint style="info" %}
Installation Script: install\_DRAGEN\_TSO500-2.6.0.run
MD5sum: 578cda2b8837845b26e2c3c020f2264c
{% endhint %}
5. Use the following command to update the run script permission:\
`chmod +x /staging/install_DRAGEN_TSO500-2.6.0.run`
6. Use the following command to run the installation script, which runs for approximately 20 minutes:
1. For Docker, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500-2.6.0.run` . The script installs compatible DRAGEN software and removes any previously installed versions.
2. For Apptainer, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500-2.6.0.run -- --noDockerInstall` This will not install Apptainer, but will install the analysis software in the SIF container format and modify the software to launch analyses using Apptainer.
7. During the installation process, you might be instructed to reboot or power cycle the system to complete the installation of the DRAGEN software. A power cycle of the system requires the server be shut down and restarted.
8. Log out of the server and then log back in.
9. Use the following command to build the DRAGEN server hash table, which runs for approximately 60 minutes:\
`/usr/local/bin/build-hashtable_DRAGEN_TSO500-2.6.0.sh`\
Refer to [Troubleshooting](/dragen-tso-500-guides/dragen-tso-500-v2.6/troubleshooting) if any errors occur.
## License Installation
Review license requirements, how to check which licenses are installed and how to receive a license in [Licenses](#licenses). Licenses can be installed before or after DRAGEN TSO 500 software installation.
To install a license (`TSO500Combined` and/or `TSO500_HRD`) on a DRAGEN server connected to the internet:
1. Confirm that the server is connected to the Internet, example: `ping www.illumina.com`
2. Run the following command: `/opt/edico/bin/dragen_lic -i auto`
To install a license (`TSO500Combined` and/or `TSO500_HRD`) on a DRAGEN server not connected to the internet:
1. Contact Customer Care at to request a license file for each of the needed licenses
2. Download and save the license file(s) to a location that is accessible from the DRAGEN server
3. For each license file, run the command, where \ is the absolute path to the license file: `sudo /opt/edico/bin/dragen_lic -i /tmp/.bin`
To check the success of license installation, run: `/opt/edico/bin/dragen_lic`. Installed licenses should be in the list.
## Running the System Check
After installation is complete, make sure the system functions properly by running the following command: `/usr/local/bin/check_DRAGEN_TSO500-2.6.0.sh`
The script checks that:
* All required services are running
* Proper Docker image is installed
* DRAGEN TruSight Oncology 500 Analysis Software can successfully process a test data set
The system check script runs for approximately 25 minutes. If the script prints a failure message, contact Illumina Technical Support and provide the `/staging/check_DRAGEN_TSO500_.tgz` output file.
If using MacOS to connect to a server, an error can occur if the local settings are not in English. To resolve the error, disable the ability to set environment variables automatically in Terminal settings.
## Uninstall Software
The DRAGEN TruSight Oncology 500 Analysis Software installation includes an uninstall script called `uninstall_DRAGEN_TSO500-2.6.0.sh`, which is located in `/usr/local/bin`.
Executing the uninstall script removes the following assets:
* All DRAGEN TruSight Oncology 500 Analysis Software related scripts located in `/usr/local/bin`
* Resources found in `/staging/illumina/DRAGEN_TSO500`
* The `dragen_tso500:2.6.0`: Docker image
To uninstall the DRAGEN TruSight Oncology 500 Analysis Software, run the following command as a root user:
`uninstall_DRAGEN_TSO500-2.6.0.sh`
You are not required to uninstall Docker or DRAGEN software. To remove Docker, review the install instructions for your operating system in the Docker documentation.
# Installation of 2.6.1 on Standalone DRAGEN Server
## Overview
The installation script for DRAGEN TruSight Oncology 500 Analysis Software installs the following software and dependencies:
1. DRAGEN TruSight Oncology 500 Analysis Software itself
2. DRAGEN Software if a compatible version is not present
3. Docker software if a compatible version is not present
4. A script required to generate DRAGEN genome hash table
5. A script to check that DRAGEN TruSight Oncology 500 Analysis Software is installed properly
## Installation Requirements
### Hardware
* DRAGEN server v3 or v4
* Network-attached storage (NAS) with enabled mkfifo if performing analysis for the TruSight Oncology 500 High-Throughput assay
### Software
* Linux CentOS 7.9 operating system (or later) or Oracle Linux 8 (or later), one of which is provided on the server. Oracle Linux 8 is recommended.
* Docker Software, see table below for minimum version needed. If sufficient Docker software is not present on the server, the TSO 500 installer will install compatible Docker software.
* DRAGEN Server Software\*, see table below for minimum version needed as the host version on the server. If sufficient DRAGEN software is not present on the server, the TSO 500 installer will install compatible DRAGEN software.
| Software Dependency | Compatible | Installs |
| ------------------------ | --------------------- | ----------------------- |
| Docker | 20.10 or greater | Docker 20.10.15 |
| DRAGEN Server Software\* | v3.10.x, where x ≥ 19 | DRAGEN Software 3.10.19 |
{% hint style="info" %}
\*The DRAGEN Server Software version may be higher than the DRAGEN version used by the DRAGEN TSO 500 v2.6.1 pipeline (DRAGEN v3.10.17), which is provided inside the DRAGEN TSO 500 docker image.
{% endhint %}
### Licenses
* `TSO500Combined` license
* `TSO500_HRD` license (to analyze data generated with the TSO 500 HRD add-on kit)
`TSO500Combined` license has been pre-installed to DRAGEN servers in manufacturing since August 2022 and `TSO500_HRD` since February 2025 and additionally distributed to DRAGEN servers connected online. To generate a list of installed DRAGEN server licenses, run the following command: `/usr/bin/dragen_lic`. If a license is not installed, contact Illumina Customer Care at for the license.
### Permissions
Illumina recommends logging in as root user for installation, but as a non-root user for running TSO 500 analysis.
* A non-root user must be a member of the Docker group to run Docker. For more information on Docker permission requirements and alternatives to running as root, refer to the Docker documentation available on the [Docker website](https://www.docker.com/).
* Installing and uninstalling DRAGEN TruSight Oncology 500 Analysis Software and running the system check requires root privileges.
* Run DRAGEN TruSight Oncology 500 Analysis Software without being logged in as a root user. Running the DRAGEN TruSight Oncology 500 Analysis Software as root is not required or recommended.
## Compatibility with other DRAGEN pipelines
DRAGEN TSO 500 Analysis Software v2.6.1 is multi-version compatible. Multi-version compatibility refers to ability to be installed on a single DRAGEN server with software running a different version of DRAGEN software. For example, multi-version compatible pipelines running DRAGEN v4.3.6 can be co-installed on a server alongside DRAGEN TSO 500 pipelines running DRAGEN v3.10.17. For more details on DRAGEN multi-version compatibility, please visit [page 7 of the DRAGEN v4.3.6 software release notes](https://support.illumina.com/content/dam/illumina-support/documents/downloads/software/dragen/release-notes/200056923_00_DRAGEN_4_3_6_Customer-Release-Notes.pdf).
Software versions without multi-version compatibility referred to as single-version compatible. DRAGEN TSO 500 Analysis Software v2.6.1 will disrupt installations of single-version compatible software from the DRAGEN server. To uninstall a previous version of DRAGEN TSO 500 Analysis Software, refer to the respective guide.
Compatibility of software for co-installation with DRAGEN TSO 500 v2.6.1 on a DRAGEN server is summarized in the table below:
Software
Version
Type
Compatible
DRAGEN TSO 500
2.6.0
Single-version
No
DRAGEN TSO 500
2.5.4
Multi-version
Yes*
DRAGEN TSO 500
2.5.3 or below
Single-version
No
DRAGEN TSO 500 ctDNA
2.6.2+
Multi-version
Yes
DRAGEN TSO 500 ctDNA
2.6.1 or below
Single-version
No
DRAGEN pipelines**
4.3.6+
Multi-version
Yes
DRAGEN pipelines**
4.2 or below
Single-version
No
\*DRAGEN TSO 500 Analysis Software v2.6.1 can run on a single server with another multi-version compatible DRAGEN TSO 500 Analysis Software, e.g. DRAGEN TSO 500 v2.5.4 (v2.5.4 should be installed before installing v2.6.1). DRAGEN TSO 500 Analysis Software v2.6.1 can be co-installed with multi-version compatible DRAGEN TSO 500 ctDNA Analysis Software or other DRAGEN pipelines with any order of installation.
\*\*For example, DRAGEN Enrichment, DRAGEN Germline, DRAGEN WGS Heme v1.0.0 and others. Order of installation does not matter.
## Installation Instructions
As a root user, perform the following steps to install DRAGEN TruSight Oncology 500 v2.6.1 Analysis Software:
1. Contact Illumina Customer Care at to obtain the DRAGEN TruSight Oncology 500 Analysis Software installer package.
2. Download the installation package provided in the email from Illumina. **The link expires after 7 days.**
{% hint style="info" %}
It is recommended to use a command line tool like wget or curl to download the file rather It is recommended to use a command line tool like wget or curl to download the file rather than pasting the link into the web browser bar. For example:
`curl -o {filename} "{link}"`
`wget -O {filename} '{link}'`
Where the file name is the installation script file name, and the link is provided by Illumina Customer Care.
{% endhint %}
3. Make sure no other analysis is being performed. Installing the software while performing other analyses prevent the installer process from proceeding.
4. Copy the install script to the `/staging` directory to store the script in the directory.
{% hint style="info" %}
Installation Script: install\_DRAGEN\_TSO500-2.6.1.run
MD5sum value:
sha256:83caa30860363e1c7027f1b021157ce32d78b31841bec788611796ed470e96bd
{% endhint %}
5. Use the following command to update the run script permission:\
`chmod +x /staging/install_DRAGEN_TSO500-2.6.1.run`
6. Use the following command to run the installation script, which runs for approximately 20 minutes:
1. For Docker, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500-2.6.1.run` . The script installs compatible DRAGEN software and removes any previously installed versions.
2. For Apptainer, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500-2.6.1.run -- --noDockerInstall` This will not install Apptainer, but will install the analysis software in the SIF container format and modify the software to launch analyses using Apptainer.
7. During the installation process, you might be instructed to reboot or power cycle the system to complete the installation of the DRAGEN software. A power cycle of the system requires the server be shut down and restarted.
8. Log out of the server and then log back in.
9. Use the following command to build the DRAGEN server hash table, which runs for approximately 60 minutes:\
`/usr/local/bin/build-hashtable_DRAGEN_TSO500-2.6.1.sh`\
Refer to [Troubleshooting](/dragen-tso-500-guides/dragen-tso-500-v2.6/troubleshooting) if any errors occur.
## License Installation
Review license requirements, how to check which licenses are installed and how to receive a license in [Licenses](#licenses). Licenses can be installed before or after DRAGEN TSO 500 software installation.
To install a license (`TSO500Combined` and/or `TSO500_HRD`) on a DRAGEN server connected to the internet:
1. Confirm that the server is connected to the Internet, example: `ping www.illumina.com`
2. Run the following command: `/usr/bin/dragen_lic -i auto`
To install a license (`TSO500Combined` and/or `TSO500_HRD`) on a DRAGEN server not connected to the internet:
1. Contact Customer Care at to request a license file for each of the needed licenses
2. Download and save the license file(s) to a location that is accessible from the DRAGEN server
3. For each license file, run the command, where \ is the absolute path to the license file: `sudo /usr/bin/dragen_lic -i /tmp/.bin`
To check the success of license installation, run: `/usr/bin/dragen_lic`. Installed licenses should be in the list.
## Running the System Check
After installation is complete, make sure the system functions properly by running the following command: `/usr/local/bin/check_DRAGEN_TSO500-2.6.1.sh`
The script checks that:
* All required services are running
* Proper Docker image is installed
* DRAGEN TruSight Oncology 500 Analysis Software can successfully process a test data set
The system check script runs for approximately 25 minutes. If the script prints a failure message, contact Illumina Technical Support and provide the `/staging/check_DRAGEN_TSO500_.tgz` output file.
If using MacOS to connect to a server, an error can occur if the local settings are not in English. To resolve the error, disable the ability to set environment variables automatically in Terminal settings.
## Uninstall Software
The DRAGEN TruSight Oncology 500 Analysis Software installation includes an uninstall script called `uninstall_DRAGEN_TSO500-2.6.1.sh`, which is located in `/usr/local/bin`.
Executing the uninstall script removes the following assets:
* All DRAGEN TruSight Oncology 500 Analysis Software related scripts located in `/usr/local/bin`
* Resources found in `/staging/illumina/DRAGEN_TSO500`
* The `dragen_tso500:2.6.1`: Docker image
To uninstall the DRAGEN TruSight Oncology 500 Analysis Software, run the following command as a root user:
`uninstall_DRAGEN_TSO500-2.6.1.sh`
You are not required to uninstall Docker or DRAGEN software. To remove Docker, review the install instructions for your operating system in the Docker documentation.
# Installation of 2.6.2 on Standalone DRAGEN Server
## Overview
The installation script for DRAGEN TruSight Oncology 500 Analysis Software installs the following software and dependencies:
1. DRAGEN TruSight Oncology 500 Analysis Software itself
2. DRAGEN Software if a compatible version is not present
3. Docker software if a compatible version is not present
4. A script required to generate DRAGEN genome hash table
5. A script to check that DRAGEN TruSight Oncology 500 Analysis Software is installed properly
## Installation Requirements
### Hardware
* DRAGEN server v3 or v4
* Network-attached storage (NAS) with enabled mkfifo if performing analysis for the TruSight Oncology 500 High-Throughput assay
### Software
* Linux CentOS 7.9 operating system (or later) or Oracle Linux 8 (or later), one of which is provided on the server. Oracle Linux 8 is recommended.
* Docker Software, see table below for minimum version needed. If sufficient Docker software is not present on the server, the TSO 500 installer will install compatible Docker software.
* DRAGEN Server Software\*, see table below for minimum version needed as the host version on the server. If sufficient DRAGEN software is not present on the server, the TSO 500 installer will install compatible DRAGEN software.
| Software Dependency | Compatible | Installs |
| ------------------------ | -------------------- | ---------------------- |
| Docker | 20.10 or greater | Docker 20.10.15 |
| DRAGEN Server Software\* | v3.11.x, where x ≥ 2 | DRAGEN Software 3.11.2 |
{% hint style="info" %}
\*The DRAGEN Server Software version may be higher than the DRAGEN version used by the DRAGEN TSO 500 v2.6.2 pipeline (DRAGEN v3.11.2), which is provided inside the DRAGEN TSO 500 docker image.
{% endhint %}
### Licenses
* `TSO500Combined` license
* `TSO500_HRD` license (to analyze data generated with the TSO 500 HRD add-on kit)
`TSO500Combined` license has been pre-installed to DRAGEN servers in manufacturing since August 2022 and `TSO500_HRD` since February 2025 and additionally distributed to DRAGEN servers connected online. To generate a list of installed DRAGEN server licenses, run the following command: `/usr/bin/dragen_lic`. If a license is not installed, contact Illumina Customer Care at for the license.
### Permissions
Illumina recommends logging in as root user for installation, but as a non-root user for running TSO 500 analysis.
* A non-root user must be a member of the Docker group to run Docker. For more information on Docker permission requirements and alternatives to running as root, refer to the Docker documentation available on the [Docker website](https://www.docker.com/).
* Installing and uninstalling DRAGEN TruSight Oncology 500 Analysis Software and running the system check requires root privileges.
* Run DRAGEN TruSight Oncology 500 Analysis Software without being logged in as a root user. Running the DRAGEN TruSight Oncology 500 Analysis Software as root is not required or recommended.
## Compatibility with other DRAGEN pipelines
DRAGEN TSO 500 Analysis Software v2.6.2 is multi-version compatible. Multi-version compatibility refers to ability to be installed on a single DRAGEN server with software running a different version of DRAGEN software. For example, multi-version compatible pipelines running DRAGEN v4.3.6 can be co-installed on a server alongside DRAGEN TSO 500 pipelines running DRAGEN v3.10.19+. For more details on DRAGEN multi-version compatibility, please visit [page 7 of the DRAGEN v4.3.6 software release notes](https://support.illumina.com/content/dam/illumina-support/documents/downloads/software/dragen/release-notes/200056923_00_DRAGEN_4_3_6_Customer-Release-Notes.pdf).
Software versions without multi-version compatibility referred to as single-version compatible. DRAGEN TSO 500 Analysis Software v2.6.2 will disrupt single-version compatible software on the DRAGEN server. To uninstall a previous version of DRAGEN TSO 500 Analysis Software, refer to the respective guide.
Compatibility of software for co-installation with DRAGEN TSO 500 v2.6.2 on a DRAGEN server is summarized in the table below:
Software
Version
Type
Compatible
DRAGEN TSO 500
2.6.1
Multi-version
Yes
DRAGEN TSO 500
2.6.0
Single-version
No
DRAGEN TSO 500
2.5.4
Multi-version
Yes*
DRAGEN TSO 500
2.5.3 or below
Single-version
No
DRAGEN TSO 500 ctDNA
2.6.2+
Multi-version
Yes
DRAGEN TSO 500 ctDNA
2.6.1 or below
Single-version
No
DRAGEN pipelines**
4.3.6+
Multi-version
Yes
DRAGEN pipelines**
4.2 or below
Single-version
No
\*DRAGEN TSO 500 Analysis Software v2.6.2 can run on a single server with another multi-version compatible DRAGEN TSO 500 Analysis Software, e.g. DRAGEN TSO 500 v2.5.4 (v2.5.4 should be installed before installing v2.6.1). DRAGEN TSO 500 Analysis Software v2.6.2 can be co-installed with multi-version compatible DRAGEN TSO 500 ctDNA Analysis Software or other DRAGEN pipelines with any order of installation.
\*\*For example, DRAGEN Enrichment, DRAGEN Germline, DRAGEN WGS Heme v1.0.0 and others. Order of installation does not matter.
## Installation Instructions
As a root user, perform the following steps to install DRAGEN TruSight Oncology 500 v2.6.2 Analysis Software:
1. Contact Illumina Customer Care at to obtain the DRAGEN TruSight Oncology 500 Analysis Software installer package.
2. Download the installation package provided in the email from Illumina. **The link expires after 7 days.**
{% hint style="info" %}
It is recommended to use a command line tool like wget or curl to download the file rather It is recommended to use a command line tool like wget or curl to download the file rather than pasting the link into the web browser bar. For example:
`curl -o {filename} "{link}"`
`wget -O {filename} '{link}'`
Where the file name is the installation script file name, and the link is provided by Illumina Customer Care.
{% endhint %}
3. Make sure no other analysis is being performed. Installing the software while performing other analyses prevent the installer process from proceeding.
4. Copy the install script to the `/staging` directory to store the script in the directory.
{% hint style="info" %}
Installation Script: install\_DRAGEN\_TSO500-2.6.2.run
SHA-256 value: c477c36abcf0d05aea7ac9ab965ef83d522fe5af60c2a99a456cb9a2e3d47a7f
{% endhint %}
5. Use the following command to update the run script permission:\
`chmod +x /staging/install_DRAGEN_TSO500-2.6.2.run`
6. Use the following command to run the installation script, which runs for approximately 20 minutes:
1. For Docker, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500-2.6.2.run` . The script installs compatible DRAGEN software and removes any previously installed versions.
2. For Apptainer, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500-2.6.2.run -- --noDockerInstall` This will not install Apptainer, but will install the analysis software in the SIF container format and modify the software to launch analyses using Apptainer.
7. During the installation process, you might be instructed to reboot or power cycle the system to complete the installation of the DRAGEN software. A power cycle of the system requires the server be shut down and restarted.
8. Log out of the server and then log back in.
9. Use the following command to build the DRAGEN server hash table, which runs for approximately 60 minutes:\
`/usr/local/bin/build-hashtable_DRAGEN_TSO500-2.6.2.sh`\
Refer to [Troubleshooting](/dragen-tso-500-guides/dragen-tso-500-v2.6/troubleshooting) if any errors occur.
## License Installation
Review license requirements, how to check which licenses are installed and how to receive a license in [Licenses](#licenses). Licenses can be installed before or after DRAGEN TSO 500 software installation.
To install a license (`TSO500Combined` and/or `TSO500_HRD`) on a DRAGEN server connected to the internet:
1. Confirm that the server is connected to the Internet, example: `ping www.illumina.com`
2. Run the following command: `/usr/bin/dragen_lic -i auto`
To install a license (`TSO500Combined` and/or `TSO500_HRD`) on a DRAGEN server not connected to the internet:
1. Contact Customer Care at to request a license file for each of the needed licenses
2. Download and save the license file(s) to a location that is accessible from the DRAGEN server
3. For each license file, run the command, where \ is the absolute path to the license file: `sudo /usr/bin/dragen_lic -i /tmp/.bin`
To check the success of license installation, run: `/usr/bin/dragen_lic`. Installed licenses should be in the list.
## Running the System Check
After installation is complete, make sure the system functions properly by running the following command: `/usr/local/bin/check_DRAGEN_TSO500-2.6.2.sh`
The script checks that:
* All required services are running
* Proper Docker image is installed
* DRAGEN TruSight Oncology 500 Analysis Software can successfully process a test data set
The system check script runs for approximately 25 minutes. If the script prints a failure message, contact Illumina Technical Support and provide the `/staging/check_DRAGEN_TSO500_.tgz` output file.
If using MacOS to connect to a server, an error can occur if the local settings are not in English. To resolve the error, disable the ability to set environment variables automatically in Terminal settings.
## Uninstall Software
The DRAGEN TruSight Oncology 500 Analysis Software installation includes an uninstall script called `uninstall_DRAGEN_TSO500-2.6.2.sh`, which is located in `/usr/local/bin`.
Executing the uninstall script removes the following assets:
* All DRAGEN TruSight Oncology 500 Analysis Software related scripts located in `/usr/local/bin`
* Resources found in `/staging/illumina/DRAGEN_TSO500`
* The `dragen_tso500:2.6.2`: Docker image
To uninstall the DRAGEN TruSight Oncology 500 Analysis Software, run the following command as a root user:
`uninstall_DRAGEN_TSO500-2.6.2.sh`
You are not required to uninstall Docker or DRAGEN software. To remove Docker, review the install instructions for your operating system in the Docker documentation.
# Getting Started on Illumina BioInsight Platform Core
## Prerequisites
An Illumina BioInsight Platform subscription includes access to DRAGEN TruSight Oncology 500 Analysis Software on BioInsight Platform Core (formerly ICA). To get started, you need:
* A BioInsight Platform account with a valid subscription
* A positive balance of Illumina BioInsight Credits (BICs) for data storage
Refer to [Software Set Up](https://help.connected.illumina.com/account-management/rg-registration) for information on how to register a BioInsight Platform subscription and BICs.
# Installation of NovaSeq 6000Dx TSO 500 Analysis Application
Instructions to install DRAGEN TSO 500 Analysis Application on NovaSeq 6000Dx (RUO mode).
## Prerequisites
* A NovaSeq 6000Dx sequencing instrument with paired DRAGEN server v4
* Illumina Run Manager installed by Illumina support personnel
* `TSO500Combined` and `TSO500_HRD` licenses installed by Illumina support personnel
* `TSO500Combined` and `TSO500_HRD` licenses are pre-installed in manufacturing since February 2025 and will need to be installed only for instruments purchased prior to that
* The user installing the app must have admin privileges on Illumina Run Manager
## Installation Instructions
1. Contact Illumina Customer Care\
Contact Illumina Customer Care at to obtain installation package for Illumina DRAGEN TruSight Oncology 500 (HRD) Analysis Application on NovaSeq 6000Dx.
2. Download the installation package\
Download the installation package provided in the email by Illumina Customer Care. The link will expire after 7 days.
{% hint style="info" %}
It is recommended to use a command line tool like wget or curl to download the file rather than pasting the link into the web browser bar. For example:
`curl -o {filename} "{link}"`
`wget -O {filename} '{link}'`
Where the file name is the name of either DRAGEN TSO 500 Analysis Application file or DRAGEN ires file, and the link is provided by Illumina Customer Care.
{% endhint %}
3. Installation package contents\
The installation package contains the following:
{% hint style="warning" %}
The v2.6.2 app uses DRAGEN v3.11.2, which is not designed to be co-installed with earlier DRAGEN versions (e.g. v3.10.18 and below, v4.3.5 and below). When launching analysis after installing another NovaSeq 6000Dx app and its dependent version of DRAGEN (that does not support multi-version installation), the software may sporadically be unable to run.\
\
For example, users may encounter an issue if the following steps occur in order:
1. installation of the DRAGEN TSO 500 v2.6.2 app for NovaSeq 6000Dx and its dependent DRAGEN, v3.11.2
2. installation of the DRAGEN TSO 500 v2.6.0 app\* for NovaSeq 6000Dx and its dependent DRAGEN, v3.10.17
3. analysis is initiated using DRAGEN TSO 500 v2.6.2 app
\*or any other app requiring an incompatible DRAGEN version. See [Installation of 2.6.2 on Standalone DRAGEN Server](/dragen-tso-500-guides/dragen-tso-500-v2.6/getting-started/installation-of-2.6.2-on-standalone-dragen-server) for DRAGEN co-installation compatibility.
See Troubleshooting section for a workaround. [NovaSeq 6000Dx App Troubleshooting](/dragen-tso-500-guides/dragen-tso-500-v2.6/troubleshooting/novaseq-6000dx-app-troubleshooting)
{% endhint %}
4. Install the DRAGEN version using the ires:
1. Log into Illumina Run Manager as a user with admin credentials
2. Navigate to the top left menu to "DRAGEN" in the drop down
3. Select "Add DRAGEN Installer" and upload the DRAGEN ires file
4. The installation is complete once the DRAGEN version as list in table above is in the install version(s) list
# Run Planning
Here are the articles in this section:
{% content-ref url="/pages/bChhg7owXZ97w4kPauJD" %}
[Sample Sheet Introduction](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-introduction)
{% endcontent-ref %}
{% content-ref url="/pages/xkGmgj4NpoJhMamjPF1e" %}
[Sample Sheet Requirements](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-requirements)
{% endcontent-ref %}
{% content-ref url="/pages/zyQANEw1Jg3iB6lNsHE4" %}
[Sample Sheet Creation in BaseSpace Run Planning tool](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-creation-in-basespace-run-planning-tool)
{% endcontent-ref %}
{% content-ref url="/pages/AllQzamwxQUYHAYYom15" %}
[NovaSeq 6000Dx Run Set Up](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/novaseq-6000dx-run-set-up)
{% endcontent-ref %}
{% content-ref url="/pages/mBL32ZhbMdpmtnU0wGzp" %}
[Sample Sheet Templates](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-templates)
{% endcontent-ref %}
# Sample Sheet Introduction
## Overview
A sample sheet is required for each analysis with DRAGEN TruSight Oncology 500 Analysis Software. A sample sheet is a comma-separated value (\*.csv) file format used by Illumina instruments, platforms, and analysis pipelines to store settings and data for sequencing and analysis. The DRAGEN TruSight Oncology 500 Analysis Software is compatible with the sample sheet v2. For general information on the sample sheet v2, refer to [Illumina BioInsight Platform - Sample Sheet](https://help.connected.illumina.com/run-set-up/overview).
The sample sheet includes a list of samples and their index sequences, along with additional information required to run DRAGEN TruSight Oncology 500 Analysis Software. For example, DNA samples with the TruSight Oncology 500 HRD add-on probes must be indicated in the Sample Feature column of the sample sheet. Appropriate index adapter sequences are determined by the assay used to perform analysis.
When running analysis on a standalone DRAGEN server or on BioInsight Platform Core (formerly ICA), a valid sample sheet can be created by:
* BaseSpace Run Planner (preferred), see [Sample Sheet Creation in BaseSpace Run Planner page](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-creation-in-basespace-run-planning-tool) for details
* Downloading and modifying a sample sheet template following the requirements, see [Sample Sheet Requirements page](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-requirements) for details
When running analysis using a NovaSeq 6000Dx Analysis Application, a valid sample sheet can be created by:
* Using the user interface of the DRAGEN TruSight Oncology 500 Analysis Application, see [NovaSeq 6000Dx Run Set Up](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/novaseq-6000dx-run-set-up) for details
* Downloading and modifying a sample sheet template following the requirements (see [Sample Sheet Requirements page](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-requirements) for details), then importing it to Illumina Run Manager.
The "Run Planning" section of this guide includes specific instructions to plan a run and set up a valid sample sheet for each deployment of DRAGEN TruSight Oncology 500 Analysis Software.
# Sample Sheet Requirements
DRAGEN TSO 500 Analysis Software has optional and required fields that are required in addition to general sample sheet requirements. Follow the steps below to create a valid sample sheet.
## Standard Sample Sheet Requirements
The following sample sheet requirements describe required and optional fields for DRAGEN TSO 500 Analysis Software. Depending on the deployment (standalone DRAGEN server, BioInsight Platform Core (formerly ICA) with auto-launch, Platform Core with manual launch, NovaSeq 6000Dx analysis application), certain sections and required values can deviate from the standard requirements. These deviations are noted in the information below.
{% hint style="warning" %}
The analysis fails if the sample sheet requirements are not met.
{% endhint %}
Use the following steps to create a valid sample sheet.
1. Download the [sample sheet v2 template](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-templates) that matches the instrument & assay run.
2. In the Sequencing Settings section, enter the following required parameters:
### \[Sequencing\_Settings] Section
| Sample Parameter | Required | Details |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LibraryPrepKits | Required |
Accepted values are:
TSO500 (for UP or CP indexes)
TSO500HT (for UDP indexes)
TSO500\_v2 (for UDP v3 indexes)
Analysis results may be compromised if this value does not match the index set used.
|
3. In the BCL Convert Settings section, enter the following required parameters:
### \[BCLConvert\_Settings] Section
| Sample Parameter | Required | Details |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required |
The DRAGEN component software version. For example, TruSight Oncology 500 2.6.0 requires 3.10.17. To ensure you are using the latest compatible version, refer to the software release notes.
|
| AdapterRead1 | Required |
If using TSO 500 Library Prep Kit (with UP or CP indexes): AGATCGGAAGAGCACACGTCTGAACTCCAGTCA
If using TSO 500 HT Library Prep Kit (with UDP indexes): CTGTCTCTTATACACATCTCCGAGCCCACGAGAC
If using TSO500 v2 Library Prep Kit (with UCP v3 indexes):
CTGTCTCTTATACACATCT
|
| AdapterRead2 | Required |
If using TSO 500 Library Prep Kit: AGATCGGAAGAGCGTCGTGTAGGGAAAGAGTGT
If using TSO 500 HT Library Prep Kit: CTGTCTCTTATACACATCTGACGCTGCCGACGA
If using TSO500 v2 Library Prep Kit:
CTGTCTCTTATACACATCT
|
| AdapterBehavior | Required | Enter `trim` This indicates that the BCL Convert software trims the specified adapter sequences from each read. |
| MinimumTrimmedReadLength | Required | Enter `35`. Reads with a length trimmed below this point are masked. |
| MaskShortReads | Required | Enter `35`. Reads with a length trimmed below this point are masked. |
4. In the BCL Convert Data section, enter the following parameters for each sample:
### \[BCLConvert\_Data] Section
{% hint style="warning" %}
Mismatches between the samples and index primers can cause incorrect results due to loss of positive sample identification. Enter sample IDs and assign indexes in the sample sheet before beginning library preparation. Record sample IDs, indexes, and plate well orientation for reference during library preparation.
{% endhint %}
| Sample Parameter | Required | Details |
| ---------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sample\_ID | Required |
The unique ID to identify a sample. The sample ID is included in the output file names.
Sample IDs must have the following characteristics:
Case-insensitive unique values
1 to 40 characters
Alphanumeric, dash, and underscore characters only
An underscore or dash must have an alphanumeric character immediately before and after
Cannot be called all, default, none, unknown, undetermined, stats, or reports.
Each sample must have a unique combination of Lane (if applicable), sample ID, and index ID or the analysis will fail.
|
| Index | Required | Index 1 sequence valid for Index\_ID assigned to matching Sample\_ID in the TSO 500 Data section. |
| Index2 | Required | Index 2 sequence valid for Index\_ID assigned to matching Sample\_ID in the TSO 500 Data section. |
| Lane | Not Required. Only for NovaSeq 6000 XP, NovaSeq 6000Dx, or NovaSeq X workflows |
Indicates which lane corresponds to a given sample. Enter a single numeric value per row. Cannot be empty, i.e the analysis fails if the Lane column is present without a value in each row.
|
5. In the TSO 500 Data section, enter the following parameters:
{% hint style="info" %}
TSO 500 Data Section header changes depending on the deployment:
* Standalone DRAGEN Server and Platform Core with Manual Launch: `TSO500S_Data`
* Platform Core with Auto-launch: `Cloud_TSO500S_Data`
* Illumina DRAGEN TruSight Oncology 500 (HRD) Analysis Application on NovaSeq 6000Dx: `TSO500HRD_Data`
{% endhint %}
### \[TSO500S\_Data] Section
| Sample Parameter | Required | Details |
| ------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sample\_ID | Required |
The unique ID to identify a sample. The sample ID is included in the output file names. Sample IDs are not case sensitive. Sample IDs must have the following characteristics: - Unique for the run. - 1–40 characters. - No spaces. - Alphanumeric characters with underscores and dashes. If you use an underscore or dash, enter an alphanumeric character before and after the underscore or dash. eg, Sample1-T5B1\_022515. - Cannot be called all, default, none, unknown, undetermined, stats, or reports. - Must match a Sample\_ID listed in the BCLConvert data section. - Illumina recommends that the sample ID be based on the pair ID. Example: \-DNA,\-RNA.
|
| Sample\_Type | Required |
Enter DNA or RNA. For HRD samples, this parameter must be DNA.
|
| Pair\_ID | Required |
A unique ID that links DNA and RNA from the same biological sample from the same individual. Pair ID shares, at most, one DNA and one RNA sample per run. eg, if a Sample\_ID is TestSample1-DNA for DNA and TestSample1-RNA for RNA, the Pair\_ID TestSample1 will link these samples that are on different rows in the sample sheet together. If the pair ID is associated with more than one DNA or RNA sample, the analysis fails.
|
| Sample\_Feature | Required when using HRD add-on kit |
Required for HRD enriched samples. For DNA samples that have undergone HRD enrichment, enter HRD in this column of the sample sheet. If the sample has not undergone HRD enrichment, leave the field empty.
|
| Sample\_Description | Not Required |
Sample description must meet the following requirements: - 1–50 characters. - Alphanumeric characters with underscores, dashes and spaces. If you enter a underscore, dash, or space, enter an alphanumeric character before and after. eg, Solid-FFPE\_213.
|
To ensure a successful analysis, follow these guidelines:
1. Avoid any blank lines at the end of the sample sheet; these can cause the analysis to fail.
2. When running local analysis, using the command line, save the sample sheet in the sequencing run folder with the default name `SampleSheet.csv`, or choose a different name and specify the path in the command-line options.
## Illumina Platform Core with Auto-launch: Sample Sheet Requirements
Refer to the following requirements to create sample sheets for running the analysis on Platform Core with Auto-launch. For sample sheet requirements common between deployments see [Standard Sample Sheet Requirements](#standard-sample-sheet-requirements). Samples sheets can be created using BaseSpace Run Planning Tool or manually by downloading and editing a sample sheet template.
{% hint style="info" %}
To auto-launch analysis from the sequencer run folder, ensure the StartsFromFastq and SampleSheetRequested fields are set to FALSE. To auto-launch analysis from FASTQs after BCL Convert auto-launch, StartsFromFastq and SampleSheet Requested fields must be set to TRUE
{% endhint %}
### **\[Cloud\_TSO500S\_Data] Section**
Refer to [\[TSO500\_Data\] Section](#tso-500-data) for this section's requirements.
### **\[Cloud\_TSO500S\_Settings] Section**
| Parameters | Required | Details |
| -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| SoftwareVersion | Not Required | The TSO500S software version. |
| StartsFromFastq | Required | Set the value to TRUE or FALSE. To auto-launch from BCL files, set to FALSE. To auto-launch from FASTQ files after auto-launch of BCL Convert, set to TRUE. |
| SampleSheetRequested | Required |
Set the value to TRUE or FALSE.
To auto-launch from BCL files, set to FALSE. To auto-launch from FASTQ files after auto-launch of BCL Convert, set to TRUE.
|
### \[Cloud\_Data] Section
| Parameters | Required | Details |
| ------------------- | ------------ | ------------------------------------------------------------------------------------------ |
| Sample\_ID | Not Required | The same sample ID used in the Cloud\_TSO500S\_Data section. |
| ProjectName | Not Required | The BaseSpace project name. |
| LibraryName | Not Required | Combination of sample ID and index values in the following format: sampleID\_Index\_Index2 |
| LibraryPrepKitName | Required | The Library Prep Kit used. |
| IndexAdapterKitName | Not Required | The Index Adapter Kit used. |
### \[Cloud\_Settings] Section
| Parameter | Required | Details |
| ----------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GeneratedVersion | Not Required | The cloud GSS version used to create the sample sheet. Optional if manually updating a sample sheet. |
| CloudWorkflow | Not Required | Ica\_workflow\_1 |
| Cloud\_TSO500\_Pipeline | Required |
This value is a universal record number (URN) . The valid values are:
v2.6.0.8 (F2 compatible, includes HRD) urn:ilmn:ica:pipeline:142fb3af-f0aa-41f2-b043-f2913671e0b4#DRAGEN\_TruSight\_Oncology\_500\_v2\_6\_0\_8
|
| BCLConvert\_Pipeline | Required | urn:ilmn:ica:pipeline:a0778b16-f318-40df-ae04-95998e3a7564#BCL\_Convert\_v3\_10\_9\_for\_TSO500 |
## NovaSeq 6000Dx Analysis Application: Sample Sheet Requirements
This section describes fields specific for sample sheets for NovaSeq 6000Dx Analysis Application. For more information on DRAGEN TSO 500 Analysis Software sample sheet requirements, refer to the sections above.
### \[BCLConvert\_Settings] Section
| Parameter Name | Required | |
| --------------- | -------- | ------------------------------------------------ |
| SoftwareVersion | Required | Enter the IRM iapp software version 2.6.0-2v12ui |
### \[TSO500S\_Data] Section
Refer to \[[TSO500S\_Data\] Section](#tso500s_data-section) for this section's requirements.
# Sample Sheet Creation in BaseSpace Run Planning tool
## How to Create TSO 500 Sample Sheets in BaseSpace Run Planning tool
The BaseSpace Sequence Hub Run Planning tool is available, and is used to generate a valid sample sheet in v2 format for use on a TSO 500 supported sequencer for both BioInsight Platform Core (formerly ICA) and Standalone DRAGEN Server analysis options. Filling out the form on the user interface will produce a exportable sample sheet with the required fields filled in. Refer to [Platform Core Auto-launch Sample Sheet Requirements](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-requirements#ica-auto-launch-sample-sheet-requirements) for descriptions of fields that appear in Platform Core sample sheets.
The sections below represent each step in the BaseSpace Run Planning tool.
{% hint style="info" %}
Note that NovaSeq X Series has a different run set up configuration screen than other instrument platforms. TSO 500 does not support multi analysis, and in order to run TSO 500 on NovaSeq X Series, enter the appropriate Read 1, Read 2, Index 1 and Index 2 described in the instructions below.
{% endhint %}
{% hint style="warning" %}
BaseSpace Run Planning tool cannot generate a valid sample sheet for NovaSeq 6000Dx Analysis Application. Refer to [Sample Sheet Requirements page](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-requirements#novaseq-6000dx-analysis-application-sample-sheet-requirements) to create a valid sample sheet.
{% endhint %}
### Step 1: Run Settings
| Parameter Name | Required | Description |
| ------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Run Name | Required | Run Name can contain 255 alphanumeric characters, dashes, underscores, periods, and spaces; and must start with an alphanumeric, a dash or an underscore. |
| Run Description | Optional | Run Description can contain 255 characters except square brackets, asterisks, and commas. |
| Instrument Platform | Required |
Choose from TSO 500 supported instruments:
NextSeq 500/550
NextSeq 1000/2000
NovaSeq 6000/6000Dx
NovaSeq X Series
|
| Secondary Analysis | Required |
BaseSpace/Platform Core (to generate sample sheet for cloud analysis. May also be used for analysis on a DRAGEN server.)
Local (only for analysis onboard the sequencer— not applicable to TSO 500)
None (to generate a sample sheet for analysis on a DRAGEN server. Note that cloud sample sheets may also be used for local analysis.)
|
| Read 1 | Required on Instrument Platform NovaSeq X Series | Fill with value 101 for TSO 500 analysis |
| Index 1 | Required on Instrument Platform NovaSeq X Series |
Fill the value depending on the TSO 500 assay used:
TSO 500 v2: 10
TSO 500 HT: 10
TSO 500: 8
|
| Index 2 | Required on Instrument Platform NovaSeq X Series |
Fill the value depending on the TSO 500 assay used:
TSO 500 v2: 10
TSO 500 HT: 10
TSO 500: 8
|
| Read 2 | Required on Instrument Platform NovaSeq X Series | Fill with value 101 for TSO 500 analysis |
| Sample Container ID | Optional | Unique Identifier for the container that holds the sample |
### Step 2: Configuration
{% hint style="info" %}
Note: On NovaSeq X Series, this page is called "Configuration 1". The right hand corner of the UI displays the Read 1, Read 2, Index 1 and Index 2 entered on the previous run settings screen.
{% endhint %}
For sample sheet generation, each Library Prep Kit has two options for Index Adapter Kit. The options are need to ensure i5 indexes are in the correct orientation (forward or reverse complement) in the sample sheet. Select the option that aligns with the sequencing instrument used.
### Step 3: Sample Settings
Users can manually enter sample information, or download a template file to bulk upload sample information. Users can import the completed template or a compatible sample sheet.
Parameter Name
Required
Description
Read Lengths: Read 1 and Read 2
Required Not applicable on NovaSeq X Series
Auto filled with the standard values, but can be optionally overwritten.
Override Cycles
Required on NovaSeq X Series
Entered based on Run Settings read lengths & index 1 / index 2.
Lane Usage
Not applicable on NovaSeq X Series or NextSeq 1000 / 2000
Checkbox allows users to apply the same lane across samples.
Lane
Required if Lane Usage is unchecked Not applicable on NextSeq 1000 / 2000
Specify lanes for each sample. The unmarked checkbox at the top of the dropdown selects all lanes.
Pair ID
Required
The identifier used to pair DNA and RNA samples in a run. The field is mandatory whether a sample is part of a pair, or not.
To note: The Sample ID field in the generated samplesheet will be auto-filled based on the Pair ID values captured. “_dna” and “_rna” (for DNA and RNA samples respectively) will be appended to the Pair ID value to create the Sample ID.
DNA Index ID
Required
Index set ID options are based on selected Index Adapter Kit.
DNA Sample Feature
Required
Enter for HRD enriched DNA Samples.
RNA Index ID
Required
Index set ID options are based on selected Index Adapter Kit.
Project
Optional
Optional field to describe the associated project.
Starts from Fastq
Required
True or False
If auto-launching TSO 500 from BCL files, set the value to False. If auto-launching TSO 500 from FASTQ after auto-launching BCL Convert, set the value to True.
DNA Barcode Mismatches Index 1
DNA Barcode Mismatches Index 2
RNA Barcode Mismatches Index 1
RNA Barcode Mismatches Index 2
Required on NovaSeq X
Default value is set to 1.
These fields are not used in TSO 500 analysis.
### Step 4: Run Review
Once all details are captured and pass validation, the user can review the details on the Run Review screen. From here they can choose to edit details in previous screens or export the sample sheet. Once completed, press the Cancel button to finish run planning.
**Note**: once leaving this screen, the run and sample sheet will not be accessible.
For NovaSeqX Plus users, the run can be saved as a draft or as a planned run (via “Save as Draft” and “Save as Planned” buttons respectively). Either selection will save the run to the Planned Runs screen on BaseSpace. There is no option to export the sample sheet on this screen.
#### Planned Runs Screen (NovaSeq X Series only)
The Planned Runs screen lists all planned or drafted runs. Users can set drafted runs to planned, export the sample sheet, and edit or delete a run on this screen.
Once the run is saved as Planned, it will appear on the NovaSeq X Series instrument where it can be selected for sequencing.
For more information on run planning, refer to the [BaseSpace Sequence Hub support site page](https://help.basespace.illumina.com/).
### Guided Examples
Please review these guided examples of analysis workflows that include a step of setting up a run in BaseSpace Run Planning tool:
* [NovaSeq 6000Dx: TSO 500 Auto-launch Analysis in Cloud](https://help.connected.illumina.com/cross-product-tutorials/autolaunch-novaseqdx-tso500)
* [NextSeq 500/550Dx: TSO 500 and Connected Insights Auto-launch Analysis in Cloud](https://help.connected.illumina.com/cross-product-tutorials/nextseq550-tso500)
# Multi-Assay Flow Cells
How to plan a run and analyze data with multiple assays loaded individually per lane on one flow cell.
## Introduction
The NovaSeq X platform supports loading samples from different assays into different lanes within a single sequencing run. To ensure compatibility, the DRAGEN TSO 500 analysis software (v2.6.0 and above) supports sample sheets containing multiple data sections, with one section per assay (for example, TSO500S\_Data and TSO500L\_Data).
This section describes how the software validates and processes multi-assay sample sheets and details the specific rules and logic applied during validation.
## Planning a Run with a Multi-Assay Flow Cell
1. In the BaseSpace Sequence Hub home page, click "Runs" -> "New Run" -> "Run Planning".
2. In the "Create a Run" page, select "NovaSeq X Series" as instrument platform.
3. Provide information for the first assay until the "Run Review" page.
* For TSO 500 or TSO 500 ctDNA assays, to auto-launch multiple pipelines at once, set "[Starts from FASTQ](/dragen-tso-500-guides/dragen-tso-500-v2.6/launching-analysis/analysis-launch-on-ica/autolaunch/auto-launch-with-fastqs-generated-by-standalone-bcl-convert-pipeline-start-from-fastq)" to True
4. In the "Run Review" page, click "Add another configuration" to add the sample prep info for the second assay.
5. A sample sheet containing multiple data sections (one per assay) will be available for exporting at the end of the run planning.
## Analyzing Data from a Multi-Assay Flow Cell
### **Sample Sheet Validation**
The sample sheet validator determines which data section(s) to validate based on the active workflow type. The list of samples to process is generated only from the relevant section (for example, Solid or ctDNA). This ensures that only valid samples for the selected workflow are validated.
The workflow’s data section may contain fewer samples than the BCLConvert\_Data section. However, all samples listed in the workflow data section must exist in BCLConvert\_Data section. The downstream pipeline will only process samples found in the workflow-specific data section.
#### **Library Prep Kits**
Multi-assay sample sheets may include multiple library prep kits values separated by semicolons (";").
Validation Logic:
| Workflow Type | Validation Logic | Example of Accepted Values |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| **Solid** | One and only one value must match the predefined Solid kit set: `TSO500`, `TSO500HT`, or `TSO500_v2`. The validation fails if none or more than one valid Solid kit is provided. The validated value will be written into the intermediate sample sheet for baseline selection. | `TSO500HT` |
| **ctDNA** | The library prep kit and the `Sequencing_Settings` section are not required. The library prep kit validation rule is skipped, and the `Sequencing_Settings` section is excluded from the intermediate sample sheet. | *N/A* |
#### **Adapter Reads**
When working with multiple assays, the "AdapterRead" field in the sample sheet may include multiple adapter sequences separated by "+". The adapter read of the selected workflow will be filled in the intermediate sample sheet.
#### **Override Cycles**
Override cycles are determined by the index and read length specified in the "Reads" section of the RunInfo.xml file and assay specifics. For multi-assay flow cells, the index and read length provided in RunInfo.xml should be the longer of the sequencing cycles required by the two assays. Override cycles for assays requiring shorter indexes and read lengths will be padded to match the cycle lengths used in the run.
#### **BCL Convert Settings and Data**
**Starting from BCL:**
* Sample Sheet Validator recalculates and inserts the correct override cycles into the BCLConvert\_Data section of the intermediate sample sheet.
* If index lengths vary, the logic has been enhanced to automatically pad shorter indexes with `"N"` to standardize cycle lengths.
* Sample Sheet Validator also writes in values for: Adapter Reads, MaskShortReads, AdapterBehavior, MinimumTrimmedReadLength. These values are based on the TSO 500 library prep kit determined from the input sample sheet.
* The intermediate sample sheet includes only samples listed in the TSO 500 Data section.
* BCL Convert (inside the TSO 500 workflow) then generates FASTQ files only for those samples.
**Starting from FASTQ:**
* If users run BCL Convert separately to generate FASTQ files:
* The input sample sheet must already contain valid override cycles, adapter reads, and other BCL Convert Settings.
* The resulting TSO 500 workflow run will start from FASTQ input files.
* BCLConvert\_Settings and BCLConvert\_Data sections will be excluded from the intermediate sample sheet created by the TSO 500 workflow.
### **BaseSpace Autolaunch**
Analyses of samples in multi-assay flow cells can be launched simultaneously from BaseSpace. As long as "Starts from FASTQ" is set to True in Analysis Settings, all samples from a multi-assay flow cell will be demultiplexed first to generate FASTQ files. Then, the Platform Core pipelines (e.g. DRAGEN TSO 500, DRAGEN TSO 500 ctDNA) will be launched simultaneously to process the samples for each of the assays.
{% hint style="success" %}
For more information about auto-launching BCL Convert before starting TSO 500 analysis from FASTQ, see [Auto-Launch with FASTQs generated by Standalone BCL Convert Pipeline (Start from FASTQ)](/dragen-tso-500-guides/dragen-tso-500-v2.6/launching-analysis/analysis-launch-on-ica/autolaunch/auto-launch-with-fastqs-generated-by-standalone-bcl-convert-pipeline-start-from-fastq)
{% endhint %}
### Summary of Rule Changes
| Component | Update Summary | Effect |
| ------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Sample Index Rule** | Filtered to process samples only from workflow-specific data section | Prevents validation failures for multi-assay sample sheets |
| **Sample Parity Rule** | Enforces that workflow samples exist in BCLConvert\_Data | Ensures downstream consistency |
| **Library Prep Kit Rule** | Supports multiple values separated by `;` | Allows multi-assay sample sheets |
| **Adapter Read Rule** | Supports multiple adapters separated by `+` | Expands flexibility across assays |
| **Override Cycles** | Auto-calculated or user-provided depending on workflow | Maintains correct cycle definitions per sample |
# NovaSeq 6000Dx Run Set Up
The following instructions describe steps to set up a run on NovaSeq 6000Dx Analysis Application.
Use the following steps to configure a TruSight™ Oncology 500 run in Illumina Run Manager:
1. Go to the "Runs" section of Illumina Run Manager by selecting "Runs" on the left-hand side
2. Enter sample data manually or by importing a sample sheet
3. To enter sample data run manually, select “Create Run”
4. Choose "DRAGEN TruSight™ Oncology 500 (with HRD) Analysis Application" from the "Create Run" screen to set-up and analyze runs for TruSight Oncology 500 assay with or without HRD add-on
## Run Settings
1. On the "Run Settings" screen, enter a run name with the following criteria:
1. 1 - 40 characters.
2. Alphanumeric characters, underscores, or dashes only.
3. Unique across all runs on the instrument.
The run name identifies the run from sequencing through analysis.
2. \[Optional] Enter a run description. The run description must have the following criteria:
1. 1 - 50 characters.
2. Alphanumeric characters or spaces only.
3. Spaces must be preceded and followed by an alphanumeric character.
3. Select kit used during library preparation:
1. TruSight Oncology 500
2. TruSight Oncology 500 High-Throughput
3. TruSight Oncology 500 v2
4. Index adapter kit will be automatically selected based on the library prep kit selection.
5. \[Optional] Enter a library tube ID.
Depending on the library prep kit selected, additional fields will be populated for run settings and are not editable. Read and index lengths will differ between library prep kit type.
## Sample Data
Use the table on the "Sample Data" screen to enter sample information manually.
Alternately, select Import Samples to upload sample information. Refer to[ NovaSeq 6000Dx Analysis Application: Sample Sheet Requirements](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-requirements#importing-a-sample-sheet-on-novaseq-6000dx-in-ruo-mode) for sample sheet requirements.
1. Select lane information. Options include one to four, or all lanes.
2. Enter a unique sample ID in the sample ID field with the following criteria:
1. Controls should be added first.
2. 1 - 40 characters.
3. Alphanumeric characters, underscores, or dashes only.
4. Underscores and dashes must be preceded and followed by an alphanumeric character.
3. Select an index set ID for the DNA / RNA library prepared from the sample.
4. \[Optional] Enter a library name.
Depending on the options selected for index set ID, additional fields will be auto-populated for sample data and are not editable.
## Sample Settings
Use the table on the "Sample Settings" screen to enter additional sample information.
1. Enter Pair ID with the following criteria:
1. 1 - 40 characters.
2. Alphanumeric characters, underscores, or dashes only.
3. Underscores and dashes must be preceded and followed by an alphanumeric character.
4. Pairs at most one DNA and one RNA samples from the same biological sample from the same individual.
Note: If the sample is not paired, this field is still required. In this case, one could choose to use the same value for sample ID and pair ID (as long as your pair IDs remain unique in the run); or, use a value that fits with your chosen schema.
2. Select Sample Type: DNA or RNA
3. Enter Sample Feature: Select HRD for DNA samples with HRD probes. For all other samples, leave the field blank.
4. \[Optional] Enter a sample name with the following criteria:
1. 1 - 50 characters.
2. Alphanumeric characters, dashes, underscores, or spaces.
3. Spaces, underscores, and dashes must be preceded and followed by an alphanumeric character.
5. \[Optional] Enter a sample description with the following criteria:
1. 1 - 50 characters.
2. Alphanumeric characters, dashes, underscores, or spaces.
3. Spaces, underscores, and dashes must be preceded and followed by an alphanumeric character.
Additional fields will be auto-populated based on selections made in the Sample Data screen, which are not editable.
Before starting your run, review that the information entered is correct in the “Run Review” page before saving.
# Sample Sheet Templates
Sample Sheet templates for TSO 500 standalone DRAGEN server & Platform Core manual launch analysis can be found in the table below. For auto-launch compatible sample sheets, use BaseSpace Run Planner.
DRAGEN TSO 500 analysis software is compatible with several instruments and assay workflows (standard, XP), each of which have implications for the sample sheet.
Sample sheet templates contain all required fields, including index sequences in the proper orientation for all indexes from a given library prep kit. The templates are provided as a starting point for creating a sample sheet manually when launching analysis on a standalone DRAGEN server or on Platform Core using manual launch.
{% hint style="info" %}
For interactive run planning or to create a sample sheet for Platform Core Autolaunch, use [BaseSpace Run Planner](https://basespace.illumina.com/) to create valid sample sheets for either local or cloud analysis. To set up a run in BaseSpace run planner, refer to [Sample Sheet Creation in BaseSpace Run Planner](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-creation-in-basespace-run-planning-tool).
{% endhint %}
Users can visit the [Sample Sheet guidelines](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-requirements) section to learn additional details on required fields and values as they fill-in their sample information. Use the lookup table below to select and download the sample sheet template that matches your instrument, assay, and workflow configuration:
# Sample Sheet Preparation for 5B Flow Cell
Prepare a sample sheet for a NovaSeq X 5B flow cell.
{% hint style="info" %}
Data generated by 5B flow cell (NovaSeq X) is only compatible with DRAGEN TSO 500 analysis software v2.6.2
{% endhint %}
NovaSeq X 5B flow cells use a two-step analysis workflow:
1. Generate FASTQ files with BCL Convert v4.4.10.
2. Run variant calling with DRAGEN TSO 500 v2.6.2 from FASTQ files.
To create a sample sheet to enable 5B data analysis, follow the steps below.
{% stepper %}
{% step %}
### Create and export the sample sheet
1. Follow [Sample Sheet Creation in BaseSpace Run Planning tool](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/run-planning/sample-sheet-creation-in-basespace-run-planning-tool).
2. Set **Starts from Fastq** to `True`.
3. Export the generated sample sheet.
{% endstep %}
{% step %}
### Update the BCL Convert pipeline URN
1. Open the exported file in a text editor.
2. Use **Find and Replace** to replace this value:
```
urn:ilmn:ica:pipeline:a0778b16-f318-40df-ae04-95998e3a7564#BCL_Convert_v3_10_9_for_TSO500
```
with this value:
```
urn:ilmn:ica:pipeline:4bdae602-abe4-4230-b0c6-f886af563b26#BclConvert_v4_4_10
```
3. Save the modified sample sheet.
{% endstep %}
{% step %}
### Use the updated file
Upload the updated sample sheet to the pre-planned sequencing run on NovaSeq X.
{% endstep %}
{% endstepper %}
# Launching Analysis
# Input Checks
Items to check before submitting your analysis
## Input Validation Steps
In addition to sample sheet validation, before starting an analysis, the software performs the following checks:
* Resource bundle integrity
* DRAGEN license validity
* NEW in v2.6.2! Instrument Type determination
Instrument type is required by the software because different instrument platforms produce output with distinct systematic noise profiles. DRAGEN TSO 500 analysis software requires instrument-specific baseline noise files. Before kicking off analysis, the software determines the instrument type in order to select which baseline files to use. This means that even when starting from FASTQ, all samples in the run must be sequenced on the same type of instrument.
## Instrument Type Determination for Baselines
When starting analysis from BCL files, the software references the `RunInfo.xml` file in the Run folder to identify the sequencing instrument type. For analyses beginning with FASTQ files, the software reads the FASTQ file headers for this information. Correct baselines for variant calling are then applied based on the determined instrument type.
{% hint style="danger" %}
For analysis starting from FASTQ files, if a mixed instrument type is detected, the software will exit with an error.
{% endhint %}
**The Combined Variant Output File will include the instrument type** [Combined Variant Output](/dragen-tso-500-guides/dragen-tso-500-v2.6/analysis-output/combined-variant-output)
Baselines are selected based on a combination of Library Prep Kit and Instrument Type.
* Library Prep Kit: TSO500\_v2
* Instrument Types**:**
* NovaSeq 6000, NovaSeq 6000Dx, NextSeq 500, NextSeq 550: Use one set of baselines.
* NextSeq 1000/ 2000: Use a different set of baselines.
* NovaSeqX, NovaSeqXPlus: Use another set of baselines.
* Library Prep Kit: TSO500 or TSO500HT
* A single set of baselines applies to all instrument types.
{% hint style="success" %}
If instrument type is undetermined (ie not matching any of the below), the software will set instrument type to NA, and the baselines for NovaSeq 6000, NovaSeq 6000Dx, NextSeq 500, and NextSeq 550 will be applied.
{% endhint %}
/Run/Instrument in RunInfo.xml or Header of the FASTQ GZ Files Starts With
Instrument Type
A
NovaSeq6000
ADX
NovaSeq6000Dx
NS50 or NB50 or NL50
NextSeq500
NS55 or NB55 or NDX
NextSeq550
VH
NextSeq1k2k
LH
NovaSeqXPlus
LL
NovaSeqX
# Analysis Launch on Standalone DRAGEN Server
Start the DRAGEN TruSight Oncology 500 Analysis Software with the `DRAGEN_TSO500-2.6.0.sh` Bash script. The script is installed in the `/usr/local/bin` directory. The Bash script is executed on the command line and runs the software with Docker (or Apptainer if specified).
For arguments, refer to [Command-Line Options](/dragen-tso-500-guides/dragen-tso-500-v2.6/launching-analysis/run-dragen-tso-software/command-line-options). You can start from BCL files or from the FASTQ folder produced by BCL Convert. The following requirements apply for both methods:
* Path to the sequencing run or FASTQ folder. Copy the run or FASTQ folder to the DRAGEN server into the staging folder with the following recommended organization: `/staging/runs/{RunID}`. You can copy the run folder onto the DRAGEN server using Linux commands such as `rsync`. The sample sheet within the run folder is used unless otherwise specified through the command line.
* Run folder must be intact. Refer to [Starting from BCL Files](/dragen-tso-500-guides/dragen-tso-500-v2.6/launching-analysis/run-dragen-tso-software/command-line-options#starting-from-bcl-files) for input requirements.
* If the analysis output folder path is different from the default, provide the analysis output folder path. Refer to [Command-Line Options](/dragen-tso-500-guides/dragen-tso-500-v2.6/launching-analysis/run-dragen-tso-software/command-line-options).
{% hint style="warning" %}
Data generated by **5B flow cell (NovaSeq X)** requires a modified analysis workflow on DRAGEN server:
* Perform demultiplexing using **BCL Convert v4.4.10**. You may need to install this version first.
* Start **DRAGEN TSO 500 v2.6.2** from the generated FASTQ files after demultiplexing is complete. Other versions of DRAGEN TSO 500 software are not compatible with 5B data.
{% endhint %}
{% hint style="info" %}
Before running the analysis, confirm that the output directory for the software to write to is empty and does not include results of previous analyses.
{% endhint %}
### Storage Requirements
For optimal performance, run analysis on data stored locally on the DRAGEN server. Analysis of data stored on network-attached storage (NAS) can take longer and performance can be less reliable.
The DRAGEN server provides an NVMe SSD in the /staging directory to use as the software output directory. Network-attached storage is required for long-term storage.
When running the DRAGEN TruSight Oncology 500 Analysis Software, use the default settings or set the -analysisFolder command line option to a directory in /staging to make sure the DRAGEN server processes read and write data on the NVMe SSD.
Before beginning analysis, develop a strategy to copy data from the DRAGEN server to a network‑attached storage. Delete output data on the DRAGEN server as soon as possible.
The following are the run and analysis output sizes for each sequencing system per 101 bp:
| Sequencing System | Run Folder Output (Gb) | Analysis Output (Gb) | Minimum Disk Space (Gb) |
| ---------------------------------------- | ---------------------- | -------------------- | ----------------------- |
| NextSeq 500/550/550Dx (RUO) HO flow cell | 32-55 | 82-85 | 150 |
| NovaSeq 6000/6000Dx (RUO) SP Flow Cell | 85-100 | 250-374 | 300 |
| NovaSeq 6000/6000Dx (RUO) S1 Flow Cell | 164-200 | 360-665 | 800 |
| NovaSeq 6000/6000Dx (RUO) S2 Flow Cell | 290-460 | 890-1600 | 1500 |
| NovaSeq 6000/6000Dx (RUO) S4 Flow Cell | 800-1200 | 2700-4100 | 3000 |
| NovaSeq X 1.5B | 213 | 352 | 800 |
| NovaSeq X 10B | 1100 | 1800 | 3000 |
| NovaSeq X 25B | 1800 | 3300 | 4000 |
| NextSeq 1000/2000 | 41 | 107 | 150 |
When launching the analysis, the software checks that the minimum disk space required is available. If the minimum disk space is not available, the software shows an error message and prevents analysis from starting. If disk space is exhausted during a run, the run shows an error and stops analyzing.
{% hint style="warning" %}
Moving or modifying files during an analysis may cause the analysis to fail or provide incorrect results.
{% endhint %}
# Command-Line Options
You can use the following command-line options with DRAGEN TruSight Oncology 500 Analysis Software.
To learn more about the input requirements, use the `--help` command-line option.
Option
Required
Description
--help
No
Displays a help screen with available command line options.
--analysisFolder
No
Path to the local analysis folder. The default location is /staging/DRAGEN_TSO500_2.6.0_Analysis_{timestamp}. If not using the default location, provide the full path to the local analysis folder. Folder must have sufficient space and must be on an NVMe SSD drive. For example, the /staging directory on the DRAGEN server. Refer to table in Storage Requirements for minimum disk space requirements.
--resourcesFolder
No
Path to the resource folder location. The default location is /staging/illumina/DRAGEN_TSO500_2.6.0/resources. If not using the default location, enter the full path to the resource folder.
--runFolder
Yes
Required when --fastqFolder is not specified. Provide the full path to the local run folder.
--fastqFolder
Yes
Required when --runFolder is not specified. Provide the full path to the local FASTQ folder. Analysis starts at this location.
--user
No
Optional for Docker. Specify the user ID to be used within the Docker container.
--version
No
Displays the version of the software.
--sampleSheet
No
Provide the full path, including file name, if not provided as SampleSheet.csv in the run folder.
--sampleOrPairIDs
No
Provide the comma-delimited sample or pair IDs that should be processed on this node with no spaces. For example, Pair_1,Pair_2,Sample_1.
--demultiplexOnly
No
Demultiplex to generate FASTQ only without additional analysis.
--gather
No
Follow this option for any directories with results that should be gathered into a single Results folder.
--hashtableFolder
No
Defaults to the DRAGEN hash table location created upon install. If not using the default location, enter the hash table location.
Note:
* Use full paths when specifying the file paths in the command line.
* Avoid special characters such as &, \*, #, and spaces.
* When starting from BCL files, only the run folder needs to be specified. The immediate parent directory containing the BCL files does not need to be specified.
When running the analysis software using SSH, Illumina recommends using additional software to prevent unexpected termination of analysis. Illumina recommends `screen` and `tmux`.
1. Wait for any running DRAGEN TruSight Oncology 500 Analysis Software containers to complete before launching a new analysis. Run the following command to generate a list of running containers:`docker ps`
2. Select from one of the following options:
* Start from BCL files in the run folder with the sample sheet included in the run folder.\
`DRAGEN_TSO500-2.6.0.sh \`\
`--runFolder /staging/{RunFolderName} \`\
`--analysisFolder /staging/{AnalysisFolderName}`
* Start from BCL files in the run folder with the sample sheet located in a folder other than the run folder.\
`DRAGEN_TSO500.sh \`\
`--runFolder /staging/{RunFolderName} \`\
`--analysisFolder /staging/{AnalysisFolderName} \`\
`--sampleSheet /staging/{SampleSheetName}.csv`
* Start from BCL files in the run folder with a different sample sheet and demultiplexing only.\
`DRAGEN_TSO500-2.6.0.sh \`\
`--runFolder /staging/{RunFolderName} \`\
`--analysisFolder /staging/{AnalysisFolderName} \`\
`--sampleSheet /staging/{SampleSheetName}.csv \`\
`--demultiplexOnly`
* Start from FASTQ with the sample sheet included in the FASTQ folder and with different resources and hash table folders.\
`DRAGEN_TSO500-2.6.0.sh \`\
`--resourcesFolder /staging/illumina/DRAGEN_TSO500/resources \`\
`--hashtableFolder /staging/illumina/DRAGEN_TSO500/ref_hashtable \`\
`--fastqFolder /staging/{FastqFolderName} \`\
`--analysisFolder /staging/{AnalysisFolderName}`
* Start from FASTQ folder with sample sheet included in the FASTQ folder and subset of samples or pairs.\
`DRAGEN_TSO500-2.6.0.sh \`\
`--fastqFolder /staging/{FastqFolderName} \`\
`--analysisFolder /staging/{AnalysisFolderName} \`\
`--sampleOrPairIDs "Pair_1,Pair2"`
## Starting from BCL Files
If starting from BCL (\*.bcl) files, DRAGEN TruSight Oncology 500 Analysis Software requires the run folder to contain certain files and folders. These inputs are required for Docker.
The run folder contains data from the sequencing run, make sure that the folder contains the following files:
| Folder/File | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Config folder | Configuration files. |
| Data folder | \*.bcl files. |
| Images folder | \[Optional] Raw sequencing image files. |
| InterOp folder | InterOp metric files. |
| Logs folder | \[Optional] Sequencing system log files. |
| RTALogs folder | Real-Time Analysis (RTA) log files. |
| RunInfo.xml file | Run information. |
| RunParameters.xml file | Run parameters. |
| SampleSheet.csv file | Sample information. If you want to use a sample sheet that is not in the run folder or a sample sheet named something other than `SampleSheet.csv`, provide the full path. |
## Starting from FASTQ Files
The following inputs are required for running the DRAGEN TruSight Oncology 500 Analysis Software using FASTQ (\*.fastq) files. The requirements apply to Docker.
* Full path to an existing FASTQ folder.
* The FASTQ folder structure conforms to the folder structure in [FASTQ File Organization.](#fastq-file-organization)
* The sample sheet is in the FASTQ folder path, or you can set the path to the sample sheet with the `--sampleSheet` override command line option.
Make sure there is sufficient disk space for the analysis to complete. Refer to the `--help` command line argument details for disk space requirements.
{% hint style="info" %}
Use BCL Convert to produce FASTQ files for DRAGEN TruSight Oncology 500 Analysis Software. Using bcl2fastq does not produce the same results and is discouraged.
{% endhint %}
{% hint style="info" %}
Make sure that BCL Convert is set to write UMI sequences to the read headers in the FASTQ files.
{% endhint %}
### FASTQ File Organization
Store FASTQ files in individual subfolders that correspond to a specific Sample\_ID. Keep file pairs together in the same folder. Alternatively, store the FASTQ files in one flat folder structure where the FASTQ files are stored in one folder.
The DRAGEN TruSight Oncology 500 Analysis Software requires separate FASTQ files per sample. Do not merge FASTQ files.
The instrument generates two FASTQ files per flow cell lane, so that there are eight FASTQ files per sample.
`Sample1_S1_L001_R1_001.fastq.gz`
* Sample1 represents the Sample ID.
* The S in S1 means sample, and the 1 in S1 is based on the order of samples in the sample sheet, so S1 is the first sample.
* L001 represents the flow cell lane number.
* The R in R1 means Read, so R1 refers to Read 1.
# Run on Multiple DRAGEN Servers
DRAGEN TruSight Oncology 500 Analysis Software can be used to run in parallel on multiple DRAGEN servers to decrease overall processing time. This is possible using a three stage process called scatter/ gather, which consists of demultiplexing, analysis, and result gathering.
## Demultiplex and Scatter
The first stage is demultiplexing. Demultiplexing runs once on the entire run folder, generates FASTQ files for each sample in the run, and then separates sample files into respective folders. Once complete, note the output directory containing the sample directories holding the FASTQ files.
The process for scattering the analysis on multiple DRAGEN servers is as follows:
1. Determine how many DRAGEN servers are available to run.
2. Run demultiplex
1. on a single DRAGEN server; or
2. if the flow cell was loaded with individually-addressable lanes, follow the tip below to avoid copying data across servers.
{% hint style="success" %}
To run scatter for flow cells loaded with individually-addressable lanes (i.e. using the NovaSeq 6000 XP workflow), modify the sample sheet to include a subset of the lanes. For example, on an S2 flowcell, create two modified sample sheets with one containing the samples from lane 1 and the other from lane 2. This allows only the sample sheet to be modified instead of copying files between servers. This strategy would use the start from Run Folder commands without the `--demultiplexOnly` option. The entire run folder would need to be copied to each analysis server as demultiplexing is performed once per server.
{% endhint %}
3. Transfer the FASTQ folder output from the original DRAGEN server to additional servers (not needed if option 2b was used).
* Find the FASTQ folder at: `Logs_Intermediates/FastqGeneration.`
{% hint style="warning" %}
Moving or modifying files during an analysis may cause the analysis to fail or provide incorrect results.
{% endhint %}
## Analysis
Run analysis software using the `--fastqFolder` option on both the original and additional DRAGEN servers.
* Option 1 Copy the original `SampleSheet.csv` to each server. Then provide a subsetted list to the Bash script on each DRAGEN server with the intended samples/pairs to run.
* Option 2 Copy and modify the `SampleSheet.csv` to each DRAGEN server to only contain the list of samples/pairs to run.\
\
The software verifies that all samples in the sample sheet are contained within the FASTQ folders unless the `--sampleOrPairIDs` command-line option is present in the analysis launch. Failure to account for these checks results in an error.
## Gather Results
Copy the results from demultiplexing and each analysis run onto a single server, and then generate the final `/Results` directory, which contains the aggregated results. Enter the `--gather` command followed by the output directories of the demultiplexing step and each individual analysis run.
## Commands for Multi-node Analysis
| Step | Command |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Demultiplexing | `DRAGEN_TSO500_2.6.0.sh --resourcesFolder /staging/illumina/DRAGEN_TSO500/resources --hashtableFolder /staging/illumina/DRAGEN_TSO500/ref_hashtable --runFolder /staging/{RunFolderName} --analysisFolder /staging/{DemultiplexAnalysisFolderName} --demultiplexOnly --sampleSheet /staging/illumina/{SampleSheetName}` |
| Analysis (one server) | `DRAGEN_TSO500_2.6.0.sh --resourcesFolder /staging/illumina/DRAGEN_TSO500/resources --hashtableFolder /staging/illumina/DRAGEN_TSO500/ref_hashtable --fastqFolder /staging/{DemultiplexAnalysisFolderName}/Logs_Intermediates/FastqGeneration/ --analysisFolder /staging/{Node1AnalysisFolderName} --sampleSheet /staging/illumina/{SampleSheetName} --sampleOrPairIDs Pair_1,Pair_2` |
| Analysis (additional servers) | `DRAGEN_TSO500_2.6.0.sh --resourcesFolder /staging/illumina/DRAGEN_TSO500/resources --hashtableFolder /staging/illumina/DRAGEN_TSO500/ref_hashtable --fastqFolder /staging/{DemultiplexAnalysisFolderName}/Logs_Intermediates/FastqGeneration/ --analysisFolder /staging/{Node1AnalysisFolderName} --sampleSheet /staging/illumina/{SampleSheetName} --sampleOrPairIDs Pair_3` |
| Gather | `DRAGEN_TSO500_2.6.0.sh --analysisFolder /Gathered_Results --resourcesFolder staging/illumina/DRAGEN_TSO500/resources --runFolder /staging/{RunFolderName}/--sampleSheet /staging/illumina/{SampleSheetName} --gather /Demultiplex_Output /Node1_Output /Node2_Output` |
# Analysis Launch on BioInsight Platform Core
## Methods for Launching Analysis
Illumina BioInsight Platform Core (formerly ICA) supports the following methods for launching DRAGEN TruSight Oncology 500 Analysis Software.
* [Auto-launch](/dragen-tso-500-guides/dragen-tso-500-v2.6/launching-analysis/analysis-launch-on-ica/autolaunch)—Stream run data directly from the instrument to Platform Core via a specially configured sample sheet and automatically begin DRAGEN TSO 500 analysis.
* [Manual launch](/dragen-tso-500-guides/dragen-tso-500-v2.6/launching-analysis/analysis-launch-on-ica/manual-launch)—Initiate DRAGEN TSO 500 analysis on Platform Core using the run files and sample sheet files in the project.
For more information about using Platform Core or BaseSpace Sequence Hub, refer to the following support pages on the Illumina support site.
* [BioInsight Platform Core support site page](https://help.ica.illumina.com/)
* [BaseSpace Sequence Hub support site page](https://help.basespace.illumina.com/)
## Resources used by Platform Core Analyses
### EC2 Instance Support
As of DRAGEN TSO500 v2.6.2, Platform Core pipelines are able to run on F2 instance type nodes (in addition to F1, when available).
For additional details on performance and availability of supported instance types, please see: [F2 Support on BioInsight Platform Core](/f2-support-on-ica)
### **BCL Convert in parallel by lane**
As of DRAGEN TSO500 v2.6.2, BCL Convert in Platform Core pipeline is parallelized by lane. A node is created to convert BCL to fastq from a particular lane. After demultiplex is complete for all lanes, the fastq files are then aggregated per sample. On average, the turn-around time for BCL Convert per lane is \~35mins.
# Auto-Launch of DRAGEN TSO 500 Analysis on BioInsight Platform Core
## Auto-launch Prerequisites and Workflow
\*The BaseSpace Sequence Hub setting for run monitoring and storage must be selected on the instrument to use DRAGEN TSO 500 analysis auto-launch. For information on preparing your instrument for DRAGEN TSO 500 auto-launch, refer to the documentation for your instrument.
1. Use BaseSpace Sequence Hub Run Planning tool or the sample sheet templates provided on the support page to create and export a sample sheet.
1. If BaseSpace Run Planning tool is not available in your region, use the sample sheet template.
2. Import the sample sheet to the instrument and start the sequencing run. Refer to [Platform Core Auto-launch Sample Sheet Requirements](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-requirements#ica-auto-launch-sample-sheet-requirements) for sample sheet guidance.
1. Data is uploaded to BaseSpace Sequence Hub and then pushed to Platform Core. You can monitor the run in BaseSpace Sequence Hub.
2. Analysis auto launches in Platform Core when sequencing and the upload completes. You can monitor the status of the analysis in BaseSpace Sequence Hub or Platform Core
3. If necessary, you can requeue the analysis via BaseSpace Sequence Hub.
3. View the analysis output results in either BaseSpace Sequence Hub or Platform Core.
{% hint style="warning" %}
To avoid invalid sample sheet configurations, Illumina recommends using BaseSpace Run Planning tool to generate sample sheets. Using an invalid sample sheet can result in failed runs and analyses.
{% endhint %}
## BaseSpace Sequence Hub Requirements for Platform Core Auto-Launch
BaseSpace Run Planning tool is a multi-step workflow that generates a manual launch or auto-launch capable sample sheet for export and requires the following additional settings:
* Access to BaseSpace Sequence Hub.
* Platform Core Run Storage is enabled under BaseSpace Sequence Hub settings.
Refer to the[ ](https://support.illumina.com/sequencing/sequencing_software/basespace.html)[BaseSpace Sequence Hub support site page](https://help.basespace.illumina.com/) for information on setting up a BaseSpace Sequence Hub project.
## Requeue Analysis
You can requeue analysis of a run via the run's Summary page in BaseSpace Sequence Hub.
Refer to the [BaseSpace Sequence Hub support site page](https://help.basespace.illumina.com/) for more information on requeuing an analysis.
## Minimum Storage Requirements on Platform Core
Sequencing System
Minimum Disk Space (Gb)
NextSeq 500/550/550Dx (RUO) HO flow cell
350
NovaSeq 6000/6000Dx (RUO) SP Flow Cell
500
NovaSeq 6000/6000Dx (RUO) S1 Flow Cell
1100
NovaSeq 6000/6000Dx (RUO) S2 Flow Cell
2500
NovaSeq 6000/6000Dx (RUO) S4 Flow Cell
4300
NovaSeq X 1.5B
2000
NovaSeq X 10B
4300
NovaSeq X 25B
8400
NextSeq 1000/2000
350
Refer to the [Software Registration page](https://help.connected.illumina.com/account-management/rg-registration) for information on how to manage accounts and subscriptions.
### Guided Examples
Please review these guided examples of using DRAGEN TSO 500 Analysis Software with auto-launch on Platform Core:
* [NovaSeq 6000Dx: TSO 500 Auto-launch Analysis in Cloud](https://help.connected.illumina.com/cross-product-tutorials/autolaunch-novaseqdx-tso500)
* [NextSeq 500/550Dx: TSO 500 and Connected Insights Auto-launch Analysis in Cloud](https://help.connected.illumina.com/cross-product-tutorials/nextseq550-tso500)
# Auto-Launch with FASTQs generated by Standalone BCL Convert Pipeline (Start from FASTQ)
When using BSSH Run Planning to generate a sample sheet to auto-launch analysis on Platform Core, you must designate "Start from Fastq" to be True or False (default is False).\
If you choose "False", BSSH will kick off the TSO 500 pipeline normally using BCL input from the run folder.
If you choose "True" for this option, BSSH will run two Platform Core pipelines in sequence:
* First, it will run the BCL Convert v3.10.9 pipeline to generate the FASTQ files
* Second, it will kick off the TSO 500 pipeline using the FASTQ files generated above as the input
{% hint style="warning" %}
Please note. Run QC metrics are generated inside the TSO 500 pipeline from interop files in the run folder. When starting TSO 500 from FASTQ (via auto-launch or manual launch), Run QC metrics will not be generated.
{% endhint %}
When the auto-launched analysis completed, you will see the analysis result shows results from both the BCL Convert pipeline and the TSO 500 pipeline, like below:
# Manual Launch of DRAGEN TSO 500 Analysis on BioInsight Platform Core
## How to Launch Analysis
1. **Create a Project:** Project can be specific for the DRAGEN TruSight Oncology 500 pipeline or it can contain multiple Pipelines and/or Tools. For information on creating Projects, refer to the Projects section in [Illumina BioInsight Platform Core help](https://help.ica.illumina.com/home/h-projects).
{% hint style="info" %}
BioInsight Platform Core (formerly ICA) standard storage is used by default as soon as the Project is saved. To connect a different storage source, set it up before creating your Project. For details and options, refer to the Storage section in [Illumina BioInsight Platform Core help](http://help.ica.illumina.com/home/h-storage).
{% endhint %}
2. **Edit Project and Add Bundle:** Edit the Project and add the bundle titled, "DRAGEN TSO 500 v2.6.0 (XX)." XX is a 2-letter code designating the region from which you are launching the analysis. Adding the Bundle automatically adds the pipeline and associated resource files and datasets to the Project. For information on Bundles, refer to the Bundles section in [Illumina BioInsight Platform Core help](https://help.ica.illumina.com/home/h-bundles).
{% hint style="info" %}
After adding the Bundle to the Project, an example dataset becomes available in the Demo\_Data folder for the Project.
{% endhint %}
2. **Upload the sequencing data:** For information on viewing and uploading data, refer to the Data section in [Illumina BioInsight Platform Core help](https://help.ica.illumina.com/project/p-data).
3. **Start Analysis:** In the Project, navigate to Pipelines, select the TSO 500 v2.6.0 Pipeline, and then select "Start New Analysis". Set up the new analysis by configuring the parameters listed in the [table below](#analysis-parameters-on-ica). When the required files are completed, start analysis.
4. **Download Results:** After analysis is complete, navigate to results in the configured output location.
Please see the Illumina Support Shorts for guidance on how to set up and run DRAGEN TSO 500 RUO analysis on Platform Core.
{% embed url="" %}
## Analysis Parameters on BioInsight Platform Core
To launch an analysis via the Platform Core user interface, configure a DRAGEN TSO 500 pipeline analysis with the following parameters.
| Parameter Name | Description |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| User Reference | The analysis run name. |
| User Tags | Text labels to help index the analysis. |
| Notify me when task is completed | Option to receive an email notification when analysis is complete. |
| Output Folder |
The path to the analysis output folder. The default path is the project output folder.
|
| Entitlement Bundle | Automatically populated from the project details. |
| Sample Sheet |
Select a sample sheet in CSV format for the analysis.
To note: Sample Sheet selection is optional if starting from a run folder, and required when submitting a FASTQ folder.
|
| Input Folder | The run folder or FASTQ folder that contains files to analyze. |
| FASTQ List CSV | Do not use, this only applies to auto-launch TSO 500 analysis from FASTQs after BCL auto-launch. |
| Starts from FASTQ |
True for analysis performed on files in the FASTQ folder. False for analysis performed on files in the run folder.
|
| Sample or Pair IDs | Optional subset of Sample IDs or Pair IDs to analyze. |
| Sample List | Do not use, this only applies to auto-launch TSO 500 analysis from FASTQs after BCL auto-launch. |
| Storage Size |
The storage size to allocate for the analysis. The default and recommended value is Large.
|
## **Known Limitations**
* FASTQ Folder Naming Requirements
* When specifying input FASTQ folder names, avoid using folder names that consist entirely of numeric characters with a leading zero, as this will cause the software to error out.
* Unsupported naming pattern:
* '01234' (numeric-only with leading zero)
* Supported naming patterns:
* '12340' (numeric without leading zero)
* 'sample01' (alphanumeric)
* 'A1234' (alphanumeric)
* 'test\_sample' (alphanumeric with underscore)
For information about using pipelines, refer to [Illumina BioInsight Platform Core support site page](https://support.illumina.com/sequencing/sequencing_software/illumina-connected-analytics.html).
# Analysis Launch with NovaSeq 6000Dx Application
When using the NovaSeq 6000Dx application, DRAGEN TSO 500 analysis starts automatically after sequencing completes.
{% hint style="warning" %}
The v2.6.2 app uses DRAGEN v3.11.2, which is not designed to be co-installed with earlier DRAGEN versions (e.g. v3.10.18 and below, v4.3.5 and below). When launching analysis after installing another NovaSeq 6000Dx app and its dependent version of DRAGEN (that does not support multi-version installation), the software may sporadically be unable to run.\
\
For example, users may encounter an issue if the following steps occur in order:
1. installation of the DRAGEN TSO 500 v2.6.2 app for NovaSeq 6000Dx and its dependent DRAGEN, v3.11.2
2. installation of the DRAGEN TSO 500 v2.6.0 app\* for NovaSeq 6000Dx and its dependent DRAGEN, v3.10.17
3. analysis is initiated using DRAGEN TSO 500 v2.6.2 app
\*or any other app requiring an incompatible DRAGEN version. See [Installation of 2.6.2 on Standalone DRAGEN Server](/dragen-tso-500-guides/dragen-tso-500-v2.6/getting-started/installation-of-2.6.2-on-standalone-dragen-server) for DRAGEN co-installation compatibility.
See Troubleshooting section for a workaround. [NovaSeq 6000Dx App Troubleshooting](/dragen-tso-500-guides/dragen-tso-500-v2.6/troubleshooting/novaseq-6000dx-app-troubleshooting)
{% endhint %}
# Analysis Output
When the analysis run completes, the DRAGEN TruSight Oncology 500 Analysis Software generates an analysis output folder in a specified location.
To view analysis output, navigate to the analysis output folder and select the files that you want to view.
## Single Node Analysis Output Folder Structure
Single output folder structure is as follows.
* Logs\_Intermediates
* AdditionalSarjMetrics— Contains per pair ID calculations to support the PCT\_TARGET\_250X metric.
* Annotation—Contains outputs for small variant annotation.
* Subfolders per sample ID—Contains the aligned small variants JSON.
* CombinedVariantOutput
* Subfolders per pair ID—Contains the combined variant output TSV files.
* A combined output log file.
* Contamination
* Subfolders per DNA sample ID—Contains the contamination metrics JSON file and output logs.
* DnaDragenCaller
* Subfolders per sample ID—Contains the aligned BAM and index files, small variant VCF and gVCF, copy number variant VCF, MSI JSON, exon coverage report bed, and QC outputs in CSV format.
* DnaDragenExonCNVCaller
* Subfolders per DNA sample ID—Contains the exon-level CNV JSON,the supporting calculation, and the QC files.
* DnaFastqValidation—Contains the FASTQ validation output log for DNA samples.
* FastqDownsample
* Subfolders per RNA sample ID—Contains FASTQ files and output logs.
* FastqDownsample output
* FastqGeneration
* Gis—Contains GIS-related files for HRD samples.
* Subfolders per HRD sample ID—Contains the GIS JSON, the supporting calculation, and the QC files.
* Also contains the annotated CNV VCF and gene level TSV file with absolute copy number and minor copy number information
* LrAnnotation
* Subfolders per DNA sample ID—Contains the annotated exon-level CNV JSON.
* LrCalculator
* Subfolders per DNA sample ID—Contains the exon-level CNV VCF.
* MetricsOutput
* Subfolders per pair ID—Contains the metrics output TSV files.
* A combined output log file.
* ResourceVerification—Contains the resource file checksum verification logs.
* RnaAnnotation
* Subfolders per RNA sample ID—Contains the annotated splice variant JSON.
* RnaDragenCaller
* Subfolders per sample ID—Contains the aligned BAM, fusion candidates CSV, exon coverage report bed and QC outputs in CSV format.
* RnaFastqValidation—Contains the FASTQ validation output log for RNA samples.
* RnaFusion
* Subfolders per RNA sample ID—Contains the All Fusions CSV and Fusion Processor logs.
* RnaQcMetrics
* Subfolders per RNA sample ID—Contains the RNA QC metrics JSON.
* RnaSpliceVariantCalling
* Subfolders per RNA sample ID—Contains the splice variants VCF.
* Run QC—Contains the Run QC metrics JSON, Intermediate Run QC metrics JSON, and log file.
* SampleAnalysisResults
* Subfolders per pair ID—Contains the Sample Analysis Results JSON and detailed log file.
* SampleSheetValidation—Contains the Intermediate sample sheet and validation log.
* Tmb
* Subfolders per DNA sample ID—Contains the TMB metrics CSV, TMB trace TSV, and related files and logs. `passing_sample_steps.json`\
—Contains the steps passed for each sample ID.\
`pipeline_trace.txt`—Contains a summary and troubleshooting file that lists each Nextflow task executed and the status (for example, COMPLETED or FAILED).\
`run.log`—Contains a complete trace-level log file describing the Nextflow pipeline execution.\
`run_report.html`—Contains high-level run statistics (performance, usage, etc.)\
`run_timeline.html` —Contains timeline-related information about the analysis run.
* Results
* Metrics Output TSV (all pair IDs)
* Pair ID—The following outputs are produced for each sample:
* Combined Variant Output TSV
* Metrics Output TSV
* TMB Trace TSV
* Small Variant Genome VCF
* Small Variant Genome Annotated JSON
* Copy Number Variant VCF
* GIS JSON
* MSI JSON
* Large Rearrangements CNV VCF
* Large Rearrangements CNV Annotated JSON
* All Fusion CSV
* Splice Variant VCF
* Splice Variant Annotated JSON
* Exon Coverage Report TSV
* Gene Coverage Report TSV
## Multiple Node Analysis Output Folder Structure
Multiple output folder structure is as follows.
* Demultiplex Output
* A Logs\_Intermediates folder containing FASTQ files per sample.
* Node(X) Output—The following outputs are produced for each node used:
* A Logs\_Intermediates folder containing step specific and component specific outputs and logs for every step/component run in the analysis pipeline for the sample run on the node.
* A Results folder containing results only for the sample run on the node.
* Gathered Output
* A Logs\_Intermediates folder containing step specific and component specific outputs and logs for every step/component run in each analysis pipeline on every node—this contains outputs for all samples and pairs ran across all nodes in the analysis.
* A Results folder containing results for all samples and pairs ran across all nodes—results are organized by Pair\_ID, then Sample\_ID. This folder also contains summary files which contain information on all samples.
## BioInsight Platform Core Output Folder Structure
This section describes each output folder generated during analysis and where to find metric and analytic files when the pipeline is executed. The same output folder structure and content exist in BioInsight Platform Core (formerly ICA) and BaseSpace Sequence Hub.
### High-Level Folder Structure
* Run ID
* TSO500\_Nextflow\_logs
* \_manifest.json
* Results
* \_tags.json
* Logs\_intermediates
* Errors—This folder is only present when analysis fails
### TSO500\_Nextflow\_logs Folder Structure
The TSO\_500\_Nextflow\_Logs provides information related to the execution of the pipeline on Platform Core as a whole and for specific nodes (when an analysis is split across multiple nodes). It contains files used to execute parts of the workflow on different nodes as well as records of the nextflow execution on those nodes.
* TSO\_500\_Nextflow\_Logs
* \_manifest.json
### Results Folder Structure
Contains the aggregated MetricsOutput.tsv file at the root level. Additionally, the Results folder contains a subfolder for each pair ID.
* Results
* MetricsOutput.tsv
* Sample\_1
* Sample\_2
* Sample\_<#>
* \_tags.json
The `Results` subfolder contains the following files:
* Results
* [MetricsOutput.tsv](/dragen-tso-500-guides/dragen-tso-500-v2.6/analysis-output/metrics-output)
* \
* [CombinedVariantOutput.tsv](/dragen-tso-500-guides/dragen-tso-500-v2.6/analysis-output/combined-variant-output)
* \\_MetricsOutput.tsv
* \ see [DNA Outputs](/dragen-tso-500-guides/dragen-tso-500-v2.6/analysis-output/dna-output)
* \ see [RNA Outputs](/dragen-tso-500-guides/dragen-tso-500-v2.6/analysis-output/rna-output)
### Logs\_intermediates Folder Structure
Contains folders for each submodule in the DRAGEN TSO 500 on Platform Core pipeline. The folders contain a copy of all the relevant files required to create the metric output files and report files, as well as the combined log files at the root level and subfolders for each sample.
* Logs\_intermediates
* DnaDragenCaller
* AdditionalSarjMetrics
* CombinedVariantOutput
* FastqGeneration
* MetricsOutput
* DnaDragenExonCnvCaller
* DnaFastqValidation
* DNACoverageReport
* Gis
* Tmb
* SampleAnalysisResults
* SampleSheetValidation
* passing\_sample\_steps.json
* RnaFusion
* Contamination
* Annotation
* RnaAnnotation
* RnaDragenCaller
* RnaSpliceVariantCalling
* RunQc
* FastqDownsample
* PassingSampleSteps
* ResourceVerification
* LrCalculator
* LrAnnotation
* RnaQcMetrics
* RnaFastqValidation
* RNACoverageReport
### Errors Folder Structure
Contains Errors.tsv. This file contains the summary of all the errors encountered during pipeline execution.
* Errors
* Errors.tsv
## NovaSeq 6000Dx Analysis Application Output Folder Structure
The following files and folders are created during analysis by NovaSeq 6000Dx Analysis Application:
* analysisResults.json
* CopyComplete.txt
* edgeos.nextflow\.config
* inputs/
* sampleMapping.json
* SampleSheet.csv
* SampleSheet.json
* Manifest.tsv
* params.json
* Results/
* workflowLogs/
* nf-main-\*\*\*.log
When the analysis run completes, the analysis application generates an analysis output in a specified location. To view analysis output, follow the steps below:
1. On the “Completed” runs tab, select the run
2. Review the run details page, and this will give the information to access the output folder
3. External Location: is the input for the run
4. Analysis Output Folder: is where the output is stored. To navigate to this page, follow the “server location” and the gds analysis output folder
5. Navigate to the directory that contains the analysis output folder
6. Open the folder, and then select the files that you want to view
# DNA Output
Refer to [DNA Analysis Methods](/dragen-tso-500-guides/dragen-tso-500-v2.6/overview-1/dna-analysis-methods) for more information.
## Small Variant gVCF
File name: `{SAMPLE_ID}_hard-filtered.gvcf.gz`
The small variant genome variant call file contains information on all candidate small variants evaluated, including complex variants up to 15 bp from phased variant calling across the entire TSO 500 panel.
The variant status is determined by the FILTER column in the genome VCF as follows.
| Filter | Note |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| PASS | PASS variants. |
| base\_quality | Site filtered because median base quality of alt reads at this locus does not meet threshold. |
| filtered\_reads | Site filtered because the fraction of reads is too large. |
| fragment\_length | Site filtered because absolute difference between the median fragment length of alt reads and median fragment length of ref reads at this locus exceeds threshold. |
| low\_depth | Site filtered because the read depth is too low. |
| low\_frac\_info\_reads | Site filtered because the fraction of informative reads is below threshold. |
| long\_indel | Site filtered because the indel length is too long. |
| mapping\_quality | Site filtered because median mapping quality of alt reads at this locus does not meet threshold. |
| multiallelic | Site filtered because more than two alt alleles pass tumor LOD. |
| no\_reliable\_supporting\_read | Site filtered because no reliable supporting somatic read exists. |
| read\_position | Site filtered because median of distances between start/end of read and this locus is below threshold. |
| str\_contraction | Site filtered due to suspected PCR error where the alt allele is one repeat unit less than the reference. |
| too\_few\_supporting\_reads | Site filtered because there are too few supporting reads in the tumor sample. |
| weak\_evidence | Somatic variant score (SQ) does not meet threshold. |
| systematic\_noise | Site filtered based on evidence of systematic noise in normal sample. |
| excluded\_regions | Site overlaps with VC excluded regions bed. |
## Small Variant Annotated JSON
File name: `{SAMPLE_ID}_DNAVariants_Annotated.json.gz`
The small variants annotated file provides variant annotation information for all nonreference positions from the genome VCF including pass and nonpass variants.
## TMB Trace
The TMB trace file provides comprehensive information on how the TMB value is calculated for a given sample. All passing small variants from the small variant filtering step are included in this file. To calculate the numerator of the TmbPerMb value in the TMB JSON, set the TSV file filter to use the IncludedInTMBNumerator with a value of True.
The TMB trace file is not intended to be used for variant inspections. The filtering statuses are exclusively set for TMB calculation purposes. Setting a filter does not translate into the classification of a variant as somatic or germline.
| Column | Description |
| ------------------------ | ---------------------------------------------------------------------------------- |
| Chromosome | Chromosome |
| Position | Position of variant |
| RefCall | Reference base |
| AltCall | Alternate base |
| VAF | Variant allele frequency |
| Depth | Coverage of position |
| CytoBand | Cytoband of variant |
| GeneName | Name of gene if applicable. A semicolon delimited list is used for multiple genes. |
| VariantType | Type of the variant: SNV, insertion, deletion, MNV |
| CosmicIDs | Cosmic IDs, if multiple concatenated by “;” |
| MaxCosmicCount | Maximum Cosmic study count |
| AlleleCountsGnomadExome | Variant allele count in gnomAD exome database |
| AlleleCountsGnomadGenome | Variant allele count in gnomAD genome database |
| AlleleCounts1000Genomes | Variant allele count in 1000 genomes database |
| MaxDatabaseAlleleCounts | Maximum variant allele count over the three databases |
| GermlineFilterDatabase | TRUE if variant was filtered by the database filter |
| GermlineFilterProxi | TRUE if variant was filtered by the proxi filter |
| CodingVariant | TRUE if variant is in the coding region |
| Nonsynonymous | TRUE if variant has any transcript annotations with nonsynonymous consequences |
| IncludedinTMBNumerator | TRUE if variant is used in the TMB calculation |
## Copy Number VCF
File name: `{SAMPLE_ID}.cnv.vcf`
The copy number VCF file contains CNV calls for DNA libraries for 500 of the 523 genes from the TSO 500 manifest, as some genes have high homology to other genes or only have probes covering one exon region. The CNV call indicates fold change results for each gene classified as reference, deletion, or amplification. The CNV vcf reports fold change for all 500 genes while the [Combined Variant output](/dragen-tso-500-guides/dragen-tso-500-v2.6/analysis-output/combined-variant-output) reports only genes that have events qualifying as amplifications or deletions.
The value in the QUAL column of the VCF is a Phred transformation of the p-value where Q=-10xlog10(p-value). The p-value is derived from the t-test between the fold change of the gene against the rest of the genome. Higher Q-scores indicate higher confidence in the CNV call.
In the VCF notation, \ indicates the detected fold change (FC) is greater than a predefined amplification cutoff. \ indicates the detected FC is less than a predefined deletion cutoff for that gene. This cutoff can vary from gene to gene.
{% hint style="info" %}
In analysis versions prior to v2.5, \ calls in the VCF are marked as LowValidation. The LowValidation filter indicates that the calls have been validated only with in silico data sets and are provided as information only.
{% endhint %}
Each copy number variant is reported as a fold change on normalized read depth in a testing sample relative to the normalized read depth in diploid genomes. Given tumor purity, you can infer the ploidy of a gene in the sample from the reported fold change.
Given tumor purity X%, for a reported fold change Y, you can calculate the copy number n using the following equation (with a diploid assumption):
$$
n=\[(200Y)-2(100-X)]/X
$$
For example, a tumor purity at 30% and a MET with fold change of 2.2x indicates that 10 copies of MET DNA are observed.
## HRD JSON
The GIS Score is a Proprietary Genomic Instability Score (GIS) indicating level of genomic instability in sample genome. Combination of Loss of Heterozygosity (LOH), Telomeric allelic imbalance and Large-scale State Transitions (LST) scores.\
\
The GIS scores provided by TruSight Oncology 500 HRD show good correlation (R2= 0.98) with Myriad Genetics GIS however they are not identical (Refer to TruSight Oncology 500 HRD Product Data Sheet Doc# M-GL-00748 for more details). GIS from alternative HRD assays should be not be considered equivalent to Illumina/Myriad GIS.
{% hint style="info" %}
Within the HRD output (Logs\_Intermediates/Gis/), LOH variants are not denoted in the .abcn\_annotated.vcf; instead this information can be found in the abcn\_genes.tsv
{% endhint %}
{% hint style="warning" %}
\*The GIS algorithm within the TSO500 pipeline (which does not have a cell line mode due to the TSO500 pipeline being non-configurable) is only intended for FFPE samples. Cell line samples will not accurately report GIS results as the tumor fraction (>90%) is too high to reliably distinguish tumor vs germline variants.
{% endhint %}
# HRD and GIS Outputs
The Illumina DRAGEN TruSight Oncology 500 Analysis Software allows for analysis of sequencing data generated from the TruSight Oncology 500 HRD assay. When HRD samples are analyzed new results and metrics are included in the CombinedVariantOutput and MetricsOutput files respectively. The following tables detail how these scores and QC metrics are derived.
| Metric | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Genomic Instability Score (GIS) |
Proprietary Genomic Instability Score (GIS) indicating level of genomic instability in sample genome. Combination of Loss of Heterozygosity (LOH), Telomeric allelic imbalance and Large-scale State Transitions (LST) scores.
The GIS scores provided by TruSight Oncology 500 HRD show good correlation (R2= 0.98) with Myriad Genetics GIS however they are not identical (Refer to TruSight Oncology 500 HRD Product Data Sheet Doc# M-GL-00748 for more details). GIS from alternative HRD assays should be not be considered equivalent to Illumina/Myriad GIS.
|
{% hint style="warning" %}
The GIS algorithm within the TSO500 pipeline (which does not have a cell line mode due to the TSO500 pipeline being non-configurable) is only intended for FFPE samples. Cell line samples will not accurately report GIS results as the tumor fraction (>90%) is too high to reliably distinguish tumor vs germline variants.
{% endhint %}
### HRD Metrics Included in Metrics Output File
| Metric | Description | Section in Metrics Output |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
| PCT\_TARGET\_HRD\_50X | Percent of HRD probe SNP panel covered by at least 50X coverage | DNA Library QC Metrics for GIS |
| EXCESSIVE\_TF | EXCESSIVE TF indicates if there is excessive tumor content in sample. Troubleshooting: Samples with pure tumor fraction >90% are outside the design for GIS estimation (this includes pure tumor cell lines) | DNA Library QC Metrics for GIS |
| ALLELE\_DOSAGE\_RATIO | Proprietary Myriad Genetics estimate of b-allele dosage based on b-allele noise/signal ratio. B-Allele noise is correlated with coverage; lower coverage samples will have higher noise. B-allele signal is also correlated with tumor fraction; a higher tumor fraction produces a higher signal for b-allele sites. Samples with lower tumor fraction and higher amount of noise (or lower coverage) will have higher Allele Dosage Ratio. The upper limit of the score is 50, therefore any sample with 50 Allele Dosage Ratio can be assumed to have tumor fraction close to zero and typically has a GIS = 0. | DNA Expanded Metrics |
| MEDIAN\_TARGET\_HRD\_COVERAGE | Median target fragment coverage across all target positions in the genome. Coverage is the total number of non-duplicate pair alignments that overlap. | DNA Expanded Metrics |
# RNA Output
Refer to [RNA Analysis Methods](/dragen-tso-500-guides/dragen-tso-500-v2.6/overview-1/rna-analysis-methods) for more information.
## Splice Variant VCF
The splice variant VCF contains all candidate splice variants targeted by the analysis panel identified by the RNA analysis pipeline. You can apply the following filters for each variant call:
| Filter Name | Description |
| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
| LowQ | Splice variant score < passing quality score threshold value of 1. |
| PASS | Splice variant score ≥ passing quality score threshold value of 1. |
| LowUniqueAlignments | All splice junction supporting reads map to a unique genomic interval near at least one of the two splice sites. |
Refer to the headers in the output for more information about each column.
## Splice Variant Annotated JSON
If available, each splice variant is annotated using the Illumina Annotation Engine. The following information is captured in the JSON:
* HGNC Gene
* Transcript
* Exons
* Introns
* Canonical
* Consequence
## All Fusions CSV
The all fusions CSV file contains all candidate fusions identified by the DRAGEN RNA pipeline. Two output columns in the file describe the candidate fusions: Filter and KeepFusion.
The following table describes the semicolon-separated output found in the Filter columns. The output is either a confidence filter or information only as indicated. If none of the confidence filters are triggered, the Filter column contains the output PASS, else it contains the output FAIL.
Filter Column Output
| Filter | Filter Type | Description |
| -------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DOUBLE\_BROKEN\_EXON | Confidence filter | If both breakpoints are distant from annotated exon boundaries, the number of supporting reads do not satisfy a high threshold requirement (≥ 10 supporting reads). |
| LOW\_MAPQ | Confidence filter | All fusion supporting read alignments at either of the breakpoints have MAPQ < 20. |
| LOW\_UNIQUE\_ALIGNMENTS | Confidence filter | All fusion supporting read alignments map to a unique genomic interval at either of the breakpoints. |
| LOW\_SCORE | Confidence filter | The fusion candidate has probabilistic score as determined by the features of the candidate. |
| MIN\_SUPPORT | Confidence filter | The fusion candidate has very few fusion supporting reads (< 5 supporting read pairs). |
| READ\_THROUGH | Confidence filter | The breakpoints are cis neighbors (< 200 kbp) on the reference genome. |
| ANCHOR\_SUPPORT | Information only | Read alignments of fusion supporting reads are not long enough (12 bp) at either of the two breakpoints. |
| HOMOLOGOUS | Information only | The candidate is likely a false candidate generated because the two genes involved have high gene homology. |
| LOW\_ALT\_TO\_REF | Information only | The number of fusion supporting reads is < 1% of the number of reads supporting the reference transcript at either of the two breakpoints. |
| LOW\_GENE\_COVERAGE | Information only | Each breakpoint in an enriched gene has fewer than 125 bp with nonzero read coverage. |
| NO\_COMPLETE\_SPLIT\_READS | Confidence filter | For every fusion-supporting split read, the total number of aligned bases across two breakpoints is less 60% of the read length. |
| UNENRICHED\_GENE | Confidence filter | Neither of the two parent genes is in the enrichment panel. |
The KeepFusion column of the output has a value of TRUE when none of the confidence filters are triggered.
Refer to the headers in the output for more information about each column.
Fusion Columns
| Fusion Object Field | Source |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Gene A | The gene associated with the A side of the fusion. A semicolon delimited list is used for multiple genes. |
| Gene B | The gene associated with the B side of the fusion. A semicolon delimited list is used for multiple genes. |
| Gene A Breakpoint | \[Information only] The chromosome and offset of the Gene A side of the fusion. |
| Gene A Location |
Location of the breakpoint within Gene A: - IntactExon—Matches exon boundary - BrokenExon—Inside an exon - Intronic—Within an intron - Intergenic—No gene overlap (currently excluded) If multiple genes are in Gene A, then semicolon separated list of locations. This column is used internally to identify genes to report when a breakpoint occurs in a region overlapping multiple genes. Occasionally, additional values are listed for genes that were excluded from the GeneA list.
|
| Gene A Sense | Boolean indicating whether left/right breakpoint order suggests fusion transcript is in the same sense of Gene A. If multiple genes are in Gene A, then semicolon separated list of bools. |
| Gene A Strand | Strand of Gene A, + for forward, - for reverse. |
| Gene B Breakpoint | \[Information only] The chromosome and offset of the Gene B side of the fusion. |
| Gene B Location |
Location of the breakpoint within Gene B: - IntactExon—Matches exon boundary - BrokenExon—Inside an exon - Intronic—Within an intron - Intergenic—No gene overlap (currently excluded) If multiple genes in Gene B, then semicolon separated list of locations. This column is used internally to identify genes to report when a breakpoint occurs in a region overlapping multiple genes. Occasionally, additional values are listed for genes that were excluded from the GeneB list.
|
| Gene B Sense | Boolean indicating whether left/right breakpoint order suggests fusion transcript is in the same sense of Gene B. If multiple genes are in Gene B, then semicolon separated list of bools. |
| Gene B Strand | Strand of Gene B, + for forward, - for reverse. |
| Score | The quality of fusion as determined by DRAGEN server. |
| Filter | The filter associated with the fusion as determined by the respective caller. Results from different callers are not equivalent. |
| Ref A Dedup | Gene A uniquely mapping reads paired across or split by the junction. Does not support fusion. Duplicate reads are not included. |
| Ref B Dedup | Gene B uniquely mapping reads paired across or split by the junction. Does not support fusion. Duplicate reads are not included. |
| Alt Split Dedup | Uniquely mapping reads split by the junction. Supports fusion. Duplicate reads are not included. |
| Alt Pair Dedup | Uniquely mapping reads paired across junction. Supports fusion. Duplicate reads are not included. |
| KeepFusion | The determination whether the fusion should be kept or dropped from the list of fusions. |
| Fusion Directionality Known | Whether fusion directionality is known and indicated by gene order. |
When using Microsoft Excel to view this report, genes that are convertible to dates (such as MARCH1 automatically convert to dd-mm format (1 Mar) by Excel. The following are fusion allow list genes:
* ABL1
* AKT3
* ALK
* AR
* AXL
* BCL2
* BRAF
* BRCA1
* BRCA2
* CDK4
* CSF1R
* EGFR
* EML4
* ERBB2
* ERG
* ESR1
* ETS1
* ETV1
* ETV4
* ETV5
* EWSR1
* FGFR1
* FGFR2
* FGFR3
* FGFR4
* FLI1
* FLT1
* FLT3
* JAK2
* KDR
* KIF5B
* KIT
* KMT2A
* MET
* MLLT3
* MSH2
* MYC
* NOTCH1
* NOTCH2
* NOTCH3
* NRG1
* NTRK1
* NTRK2
* NTRK3
* PAX3
* PAX7
* PDGFRA
* PDGFRB
* PIK3CA
* PPARG
* RAF1
* RET
* ROS1
* RPS6KB1
* TMPRSS2
# Combined Variant Output
File name: `{Pair_ID}_CombinedVariantOutput.tsv`
The combined variant output file contains the variants and biomarkers in a single file that is based on a single sample. If using pair ID, the file is based on paired DNA and RNA samples from the same individual. The output contains the following variant types and biomarkers:
* Small variants
* Copy number variants (CNV) (with absolute copy number when HRD Assay is run)
* TMB
* MSI
* Fusions
* Splice variants
* GIS (when HRD Assay is run)
* Gene-level Loss of Heterozygosity (when HRD Assay is run)
* Large Rearrangements
The combined variant output file also contains Analysis Details and Sequencing Run Details sections. The details of each are listed in the following table:
| Analysis Details | Sequencing Run Details |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
- Pair ID - DNA Sample ID (if DNA is run) - RNA Sample ID (if RNA is run)
- Library Prep Kit - Output Date - Output Time - Module Version - Pipeline Version (Docker image version #)
|
- Run Name - Run Date - DNA Sample Index ID (if DNA is run) - RNA Sample Index ID (if RNA is run) - Instrument ID - Instrument Control Software Version - Instrument Type
- Instrument Platform
- \[HRD] Sample feature
|
Combined variant output produces small variants with blank fields in the following situations:
* The variant has been matched to a canonical RefSeq transcript on an overlapping gene not targeted by TruSight Oncology 500.
* The variant is located in a region designated iSNP, indel, or Flanking in the `TST500_Manifest.bed` file located in the Resources folder.
## Variant Filtering Rules
* **Small Variants -** All variants with the FILTER field marked as PASS in the hard-filtered genome VCF are present in the combined variant output.
* Gene information is only present for variants belonging to canonical transcripts that are within the Gene Allow List–Small Variants.
* Transcript information is only present for variants belonging to canonical transcripts that are within the Gene Allow List–Small Variants.
* **Copy Number Variants -** All variants with the FILTER field marked as PASS and ALT field is \ in cnv.vcf file from DRAGEN DNA call or abcn\_annotated.vcf from GIS step(HRD assay))are present in the combined variant output:
* Gene Name.
* Fold Change.
* Copy Number Variant (\) .
* Absolute Copy Number (HRD Assay) – This value is included only if the HRD assay was run and the sample passed HRD sample QC. If the HRD assay failed QC , the Absolute Copy Number will be reported as NA, and the CNVs will be sourced from the DRAGEN DNA call (cnv.vcf).
* **Fusion Variants -** Fusion variants must meet the following conditions:
* Passing variant call (KeepFusion field is true).
* Contains at least one gene on the fusion allow list.
* Genes separated by a dash (-) indicate that the fusion directionality could be determined. Genes separated by a slash (/) indicate that the fusion directionality could not be determined.
* **Biomarkers TMB/MSI -** Always present when DNA sample is processed.
* **Splice Variants -** Passing splice variants that are contained on genes EGFR, MET, and AR.
* **Biomarker GIS -** Present only if TruSight Oncology 500 HRD analysis is performed
* **Loss of Heterozygosity** - Present only when TruSight Oncology 500 HRD is run. Loss of heterozygosity (LOH) must meet the following condition:
* MCN field is equal to 0
* **Large Rearrangements CNV -** Large Rearrangements CNVs must meet the following conditions:
* BRCA1 or BRCA2 contains at least one affected exon.
* ALT field is \ or \ .
# Metrics Output
## Metrics Output
One metrics output file is generated for the entire run. An additional file is generated for each sample (or DNA-RNA pair).
The `MetricsOutput.tsv` file contains the following quality control metrics for all samples:
* DNA library QC metrics for:
* Small variant calling
* TMB
* MSI
* CNV
* \[HRD] GIS
* RNA library QC metrics
* Run QC metrics, analysis status, and contamination
This TSV file also includes expanded DNA library QC metrics per sample, based on total reads, collapsed reads, chimeric reads, and on-target reads. Analysis using RNA samples also produces RNA library QC metrics and expanded RNA library QC metrics per sample based on total reads and coverage.
The `MetricsOutput.tsv` file is a final combined metrics report with sample status, key analysis metrics, and metadata. Sample metrics within the report include suggested lower specification limits (LSL) and upper specification limits (USL) for each sample in the run.
For troubleshooting information, refer to [Troubleshooting](/dragen-tso-500-guides/dragen-tso-500-v2.6/troubleshooting)
# Coverage Reports
The gene and exon coverage report files are tab-separated value (TSV) files with coverage values matching respectively the exons and genes for both DNA and RNA samples specified in the manifest file.
# Block List
The block list represents high noise regions in the panel where false positive variant calls are likely produced. As a result, all positions in the gVCF are marked as Filter=excluded\_regions to indicate variant call results are not reliable in such regions.
The block list includes the following genes:
* HLA A
* HLA B
* HLA C
* KMT2B
* KMT2C
* KMT2D
* chrY
* Any position with VAF 1% occurrence in six or more of the 60 baseline samples.
# Analysis Methods
The software processes sequencing data to perform quality control, detect variants, determine tumor mutational burden (TMB), microsatellite instability (MSI) status, and genomic instability score (GIS), and report results. The following sections describe the analysis methods used in DRAGEN TruSight Oncology 500 Analysis Software.
DRAGEN TruSight Oncology 500 Analysis Software uses the following workflows to analyze sequencing data.
* FASTQ Generation
* DNA Analysis
* DNA Alignment and Error Correction
* Small Variant Calling and Filtering
* Copy Number Variant (CNV) Calling
* BRCA Large Rearrangements
* Annotation
* Tumor Mutational Burden (TMB) Scoring
* Microsatellite Instability (MSI) Status
* Genomic Instability Score (GIS)
* Tumor purity (beta)
* Ploidy (beta)
* Absolute Copy Number (beta)
* Gene-level Losss of Heterozygosity (LOH) (beta)
* Contamination Detection
* RNA Analysis
* Downsampling
* Read Trimming
* Alignment
* Fusion Calling and Filtering
* Splice Variant Calling
* Fusion Merging
* Annotation
* Quality Control
* Run QC
* DNA Sample QC
* RNA Sample QC
# FastQ Generation
Sequencing data stored in BCL format are demultiplexed through a process that uses the index sequences unique to each sample to assign clusters to the library from which they originated. Each cluster contains two indexes (i7 and i5 sequences, one at each end of the library fragment). The combination of those index sequences are used to demultiplex the pooled libraries.
After demultiplexing, this process generates FASTQ files, which contain the sequencing reads for each individual sample library and the associated quality scores for each base call, excluding reads from any clusters that did not pass filter.
# Quality Control
# Run QC
## Run QC
The Run Metrics section of the metrics output report provides sequencing run quality metrics along with suggested values to determine if they are within an acceptable range. The overall percentage of reads passing filter is compared to a minimum threshold. For Read 1 and Read 2, the average percentage of bases ≥ Q30, which gives a prediction of the probability of an incorrect base call (Q‑score), are also compared to a minimum threshold. The following tables show run metric and quality threshold information for different systems.
The values in the Run Metrics section are listed as NA in the following situations:
* If the analysis was started from FASTQ files.
* If the analysis was started from BCL files and the InterOp files are missing or corrupt.
### NextSeq 500/550 or NextSeq 550Dx (RUO)
| Metric | Description | Recommended Guideline Quality Threshold | Variant Class |
| ------------------ | --------------------------------------------------- | --------------------------------------- | ------------- |
| PCT\_PF\_READS (%) | Total percentage of reads passing filter. | ≥80.0 | All |
| PCT\_Q30\_R1 (%) | Percentage of Read 1 reads with quality score ≥ 30. | ≥80.0 | All |
| PCT\_Q30\_R2 (%) | Percentage of Read 2 reads with quality score ≥ 30. | ≥80.0 | All |
### NovaSeq 6000 or NovaSeq 6000Dx (RUO)
| Metric | Description | Recommended Guideline Quality Threshold | Variant Class |
| ------------------ | --------------------------------------------------- | --------------------------------------- | ------------- |
| PCT\_PF\_READS (%) | Total percentage of reads passing filter. | ≥55.0 | All |
| PCT\_Q30\_R1 (%) | Percentage of Read 1 reads with quality score ≥ 30. | ≥80.0 | All |
| PCT\_Q30\_R2 (%) | Percentage of Read 2 reads with quality score ≥ 30. | ≥80.0 | All |
### NextSeq 1000/2000
| Metric | Description | Recommended Guideline Quality Threshold | Variant Class |
| ---------------- | --------------------------------------------------- | --------------------------------------- | ------------- |
| PCT\_Q30\_R1 (%) | Percentage of Read 1 reads with quality score ≥ 30. | ≥85.0 | All |
| PCT\_Q30\_R2 (%) | Percentage of Read 2 reads with quality score ≥ 30. | ≥85.0 | All |
### NovaSeq X
| Metric | Description | Recommended Guideline Quality Threshold | Variant Class |
| ---------------- | --------------------------------------------------- | --------------------------------------- | ------------- |
| PCT\_Q30\_R1 (%) | Percentage of Read 1 reads with quality score ≥ 30. | ≥85.0 | All |
| PCT\_Q30\_R2 (%) | Percentage of Read 2 reads with quality score ≥ 30. | ≥85.0 | All |
# Contamination
The contamination score evaluates presence of sample-to-sample contamination. The algorithm uses common germline SNPs in the homozygous state expected to have variant allele frequencies (VAF) at 0% and 100%. In contaminated samples, the VAFs shift away from the expected values allowing the detection of sample-to-sample contamination.
{% hint style="success" %}
The contamination score can detect sample-to-sample contamination greater than or equal to 2% (more than 2% of DNA input is coming from the non-source sample)
{% endhint %}
### Contamination Score Calculation
The contamination score is calculated using the SNP error file and Pileup file that are generated during the small variant calling, as well as the TMB trace file. The algorithm includes the following steps:
* All positions that overlap with a pre-defined set of common SNPs that have variant allele frequencies of < 25% or > 75% are collected (only SNP are considered, indels are excluded)
* Variants in CNV events are removed using a clustering method
* The likelihood that the positions are an error or a real mutation is calculated by:
* Estimating the error rate per sample
* Counting mutation support
* Counting total depth
* The contamination score is calculated as the sum of all the log likelihood scores across the pre-defined SNP positions whose minor allele frequency is <25% in the sample and not likely due to CNV events:
CONTAMINATION_SCORE = sum(log10(P(vi is False Positive)))
### Contamination Score Interpretation
* The contamination score is output in the metrics output file, `MetricsOutput.tsv`
* If a contamination score is equal or below 1457 (the upper specification limit provided in the "USL Guideline" field in the metrics output file, see [Metrics Output page](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/analysis-output/metrics-output)), the sample has less than 2% sample-to-sample contamination.
* If a contamination score is above 1457, the sample has more than 2% sample-to-sample contamination. In this case, an estimation of the contamination can be obtained from the PCT\_CONTAMINATION\_EST metric, see more details on the [DNA Expanded Metrics page](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/quality-control/dna-expanded-metrics). As noted, PCT\_CONTAMINATION\_EST is not valid unless the contamination score exceeds 1457.
{% hint style="warning" %}
Samples with highly rearranged genomes (HRD samples) can have variants with VAFs that shift away from the expected frequencies due to genomic rearrangement, which can lead to false-positive contamination scores
{% endhint %}
* Visual examination can help determine if a shift of VAFs is due to true contamination
Visual investigation of VAFs across the genome can help determine if a shift of VAFs is due to true contamination
### How to build a VAF plot for visual examination
1. To build a VAF plot, use the `{Sample_ID}.tmb.trace.csv` file. Filter to only germline variants (for example, by using tags "Germline\_DB" and "Germline\_Proxi" in the column "Status") and use values in the VAF column.
2. Select Scatter from the Charts menu
3. Review plot as described above analyzing whether variants are scattered or clustered around 50% and 100% VAF
# Sample QC
{% hint style="success" %}
These metrics and guidelines apply to DRAGEN TSO 500 v2.1 and above.
{% endhint %}
## DNA Sample QC
DNA library QC results are available in the `MetricsOutput.tsv` file.
| Metric | Description | Recommended Guideline Quality Threshold | Variant Class |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | ----------------- |
| CONTAMINATION\_SCORE | The contamination score is based on VAF distribution of SNPs. | ≤ 1457 | All |
| MEDIAN\_EXON\_COVERAGE | Median exon fragment coverage across all exon bases. | ≥ 150 | Small variant TMB |
| PCT\_CHIMERIC\_READS | Proportion of total number of non-supplementary, non-secondary, and passing QC reads after alignment to the whole genome sequence. | ≤ 8 | Small variant TMB |
| PCT\_EXON\_50X | Percent exon bases with 50x fragment coverage. | ≥ 90.0 | Small variant TMB |
| MEDIAN\_INSERT\_SIZE | The median fragment length in the sample. | ≥ 70 | Small variant TMB |
| USABLE\_MSI\_SITES | The number of MSI sites usable for MSI calling. | ≥ 40 | MSI |
| GENE\_SCALED\_MAD | The median of absolute deviations normalized by gene fold change | ≤ 0.134 | CNV |
| MEDIAN\_BIN\_COUNT\_CNV\_TARGET | The median raw bin count per CNV target. | ≥ 1.0 | CNV |
| PCT\_TARGET\_HRD\_50X (HRD samples) | Percent of HRD probe SNP panel covered by at least 50X coverage | ≥ 50 | GIS |
| EXCESSIVE\_TF (HRD samples) | EXCESSIVE TF indicates if there is excessive tumor content in sample. Troubleshooting: Samples with pure tumor fraction >90% are outside the design for GIS estimation (this includes pure tumor cell lines) |
= 0 (= 1 indicates Excessive TF)
| GIS |
## RNA Sample QC
The input for RNA Library QC is RNA alignment. Metrics and guideline thresholds can be found in the `MetricsOutput.tsv` file.
| Metric | Description | Recommended Guideline Quality Threshold | Variant Classes |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | --------------- |
| MEDIAN\_CV\_GENE\_500X | The median CV for all genes with median coverage > 500x. Genes with median coverage > 500x are likely to be highly expressed. Higher CV median > 500x indicates an issue with library preparation (poor sample input and/or probes pulldown issue). | ≤ 0.93 | Fusion, Splice |
| MEDIAN\_INSERT\_SIZE | The median fragment length in the sample. | ≥ 80 | Fusion, Splice |
| TOTAL\_ON\_TARGET\_READS\* | The total number of reads that map to the target regions. |
≥ 9000000 (v1)
≥ 2,500,000 (v2)
| Fusion, Splice |
| GENE\_MEDIAN\_COVERAGE\*\* | The median deduped coverage across all genes in the RNA panel (55 genes). | N/A | Fusion, Splice |
\*TOTAL\_ON\_TARGET\_READS is the only QC metric with guidelines specific to chemistry (v1 vs. v2 assay); all other guidelines are applicable to both
\*\* To avoid failing RNA samples unnecessarily, Illumina does not recommend a universal threshold for GENE\_MEDIAN\_COVERAGE to determine RNA sample quality. RNA expression varies significantly across tissue types and a small panel size (55 genes), which makes normalization challenging. Tissue-specific thresholds could be considered for normalization.
# DNA Expanded Metrics
DNA expanded metrics are provided for information only. They can be informative for troubleshooting but are provided without explicit specification limits and are not directly used for sample quality control. For additional guidance, contact Illumina Technical Support.
| Metric | Description | Troubleshooting |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TOTAL\_PF\_READS (count) | Total number of non-supplementary, non-secondary, and passing QC reads after alignment to the whole genome sequence. |
Primarily driven by data output of sequencer, quality of library and balancing of library in library pool. If TOTAL\_PF\_READS is in line with other samples, but coverage metrics are more may suggest non-specific enrichment.
Low values for all samples indicate a poor quality run with possible low cluster numbers or low numbers of Q30 and PF%.
A low value for an individual sample indicates poor pooling of this library into the final pool.
|
| MEAN\_FAMILY\_SIZE (count) |
A UMI Family is a group of reads that all have the same UMI barcode. The family size is the number of reads in family. MEAN\_FAMILY\_SIZE is the mean of the entire population of reads assembled into UMI families.
In V1 chemistry only the TSO500 manifest is considered while in V2 the TSO500 and HRD manifests are both considered.
|
The mean UMI family size decreases with increased unique read numbers, and more input DNA leads to more unique reads. Conversely over sequencing of a fixed population of unique DNA molecules leads to increased family size.
As a guide, for a good run with optimal cluster density, passing specs, even sample pooling, and good quality DNA we usually observe values <10.
UMI family size = 1 is not ideal as it is harder to correct for errors.
UMI family size of 2 to 5 enables efficient error correction without wasting sequencing capacity on high percentages of duplicate reads.
|
| MEDIAN\_TARGET\_COVERAGE (count) | Median depth across all the unique loci occurring in all regions of the manifest file. | Lower median target coverage may be due to poor sample input/quality, library preparation issues or low sequencing output. |
| PCT\_EXON\_100X (%) | Percentage of exon bases with 100X fragment coverage. Calculated against all regions in manifest containing \_exon in name. | Can be used in combination with other PCT\_EXON metrics to understand under or over coverage of exons. |
| PCT\_READ\_ENRICHMENT (%) |
Percentage of reads that have overlapping sequence with the target regions defined in the sample manifest.
In V1 chemistry only the TSO500 manifest is considered while in V2 the TSO500 and HRD manifests are both considered.
| Indicative of general enrichment performance. Reduced proportions of enriched reads may indicate issues with the enrichment proportion of the library preparation. |
| PCT\_USABLE\_UMI\_READS (%) | Percentage of reads that have valid UMI sequences associated with them. | As UMI reads are sequenced at the start of each read, loss of valid UMI sequence may be cause by sequencing issues impacting the quality of base calling in this portion of the sequencing read. |
| MEAN\_TARGET\_COVERAGE (count) | Mean depth across all the unique loci defined in the manifest file. | Lower mean target coverage may be due to poor sample input/quality, library preparation issues or low sequencing output. Large differences between the median and mean target coverage values may indicated a skewed distribution of target coverage. |
| PCT\_ALIGNED\_READS (%) | Proportion of aligned reads that are non-supplementary, non-secondary and pass QC versus aligned reads that are non-supplementary, non-secondary, mapped and pass QC. | |
| PCT\_CONTAMINATION\_EST (%) |
This metric should only be evaluated if the CONTAMINATION\_SCORE metric exceed the USL. This metric estimates the amount of contamination in a sample. The contamination level is computed by taking 2.0\* the average of the adjusted allele frequencies of all variants that were selected. The adjusted alllele frequency is either the actual allele frequency of the variant if it is less than 0.5, or 1 -allele frequency if it is greater than or equal to 0.5.
If the sample does not fail the CONTAMINATION\_SCORE this metric has no intended meaning as it will be driven by statistical noise (e.g. the few variants that naturally fall outside an expected interval around 0.5 due to random chance)
|
High contamination estimates may be due to any of the following:
Inter-sample contamination caused by mixing of samples during extraction or library preparation.
Intra-sample contamination, due to mixing of clonally different cell populations during extraction. Large scale genomic rearrangements that cause unexpected VAFs for large numbers of variants.
|
| PCT\_TARGET\_0.4X\_MEAN (%) | Parentage of target (all locations in manifest) reads that have a coverage depth of greater the 0.4x the mean target coverage depth (see definition above). | Provides an indication of uniformity of coverage of the target regions in the manifest file. When trended over time reductions in this metric may indicate an issue with the enrichment process resulting in coverage bias. |
| PCT\_TARGET\_50X (%) | Percentage of target bases with 50X fragment coverage. Calculated against all regions in manifest file. | Can be used in combination with other PCT\_TARGET metrics to understand under or over coverage of targets. |
| PCT\_TARGET\_100X (%) | Percentage of target bases with 100X fragment coverage. Calculated against all regions in manifest file. | Can be used in combination with other PCT\_TARGET metrics to understand under or over coverage of targets. |
| PCT\_TARGET\_250X (%) | Percentage of target bases with 250X fragment coverage. Calculated against all regions in manifest file. | Can be used in combination with other PCT\_TARGET metrics to understand under or over coverage of targets. |
| PCT\_SOFT\_CLIPPED\_BASES (%) | percentage of based that were not used for alignment but retained as part of the alignment file | Soft clipped reads are used as a part of the downstream analysis for small variants calling. A higher-than-expected number could indicate a low-quality enrichment step. |
| PCT\_Q30\_BASES (%) | Average percentage of bases ≥ Q30. A prediction of the probability of an incorrect base call (Q‑score). | An indicator of sequencing run quality, low Q30 across all samples on a run could be the result of run overclustering. |
| ALLELE DOSAGE\_RATIO (HRD samples) | Proprietary Myriad Genetics estimate of b-allele dosage based on b-allele noise/signal ratio. B-Allele noise is correlated with coverage; lower coverage samples will have higher noise. B-allele signal is also correlated with tumor fraction; a higher tumor fraction produces a higher signal for b-allele sites. Samples with lower tumor fraction and higher amount of noise (or lower coverage) will have higher Allele Dosage Ratio. | Any sample with >50 Allele Dosage Ratio can be assumed to have tumor fraction close to zero and typically has a GIS = 0. |
| MEDIAN TARGET HRD (HRD samples) | Median target fragment coverage across all target positions in the HRD manifest. Coverage is the total number of non-duplicate pair alignments that overlap. | |
# RNA Expanded Metrics
RNA expanded metrics are provided for information only. They can be informative for troubleshooting but are provided without explicit specification limits and are not directly used for sample quality control. For additional guidance, contact Illumina Technical Support.
| Metric | Description | Units |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| PCT\_CHIMERIC\_READS | Percentage of reads that are aligned as two segments which map to nonconsecutive regions in the genome. | % |
| PCT\_ON\_TARGET\_READS | Percentage of reads that cross any part of the target region versus total reads. A read that partially maps to a target region is counted as on target. | % |
| SCALED\_MEDIAN\_GENE\_COVERAGE | Median of median base coverage of genes scaled by length. An indication of median coverage depth of genes in the panel. | Count |
| TOTAL\_PF\_READS | Total number of reads passing filter. | Count |
| GENE\_MEDIAN\_COVERAGE | The median coverage depth of all genes in the panel. | Count |
| GENE\_ABOVE\_MEDIAN\_CUTOFF | Number of genes above the median coverage cutoff. | Count |
| PER\_GENE\_MEDIAN\_COVERAGE | Median deduped coverage across each gene (available in Logs\_Intermediates only) | Count |
| PCT\_SOFT\_CLIPPED\_BASES | percentage of based that were not used for alignment but retained as part of the alignment file | % |
| RNA\_PCT\_030\_BASES | Average percentage of bases ≥ Q30. A prediction of the probability of an incorrect base call (Q‑score). Troubleshooting: An indicator of sequencing run quality, low Q30 across all samples on a run could be the result of run overclustering. | % |
# DNA Analysis Methods
## DNA Alignment and Error Correction
DNA alignment and error correction involves aligning sequencing reads derived from DNA libraries to a reference genome and correcting errors in the sequencing reads prior to variant calling.
DRAGEN unique molecular identifier (UMI) error correction comprises three main steps:
1. DRAGEN UMI uses its HW accelerated mapper (based on a hash table implementation) to align DNA sequences in FASTQ files to the hg19 reference genome. These alignments are not written to a BAM.
2. The raw alignments are processed to remove errors, including errors introduced during FFPE preservation, PCR amplification, and sequencing. Reads from the same original DNA molecule are tagged with the same UMI during library preparation. The UMI allows DRAGEN to compare related reads, remove outlier signals, and collapse multiple reads into a single high-quality sequence. Read collapsing adds the following BAM tags:
* RX/XU—UMI.
* XV—Number of reads in the family.
* XW—Number of reads in the duplex-family or 0 if not a duplex family.
3. DRAGEN performs a final alignment step on the UMI-collapsed reads. These final alignments are then written to a BAM file and a corresponding BAM index file is created.
DRAGEN continues to use these final alignments as input for gene amplification (copy number) calling, small variant calling (SNV, indel, MNV, delin), microsatellite instability (MSI) status determination, and DNA library quality control.
## Small Variant Calling and Filtering
DRAGEN supports calling SNVs, indels, MNVs, and delins in tumor-only samples by using mapped and aligned DNA reads from a tumor sample as input. Variants are detected via both column wise pileup analysis and local de novo assembly of haplotypes. The de novo haplotypes allow the detection of much larger insertions and deletions than possible through column wise pileup analysis only. DRAGEN insertions and deletions are validated with lengths of at least 0–25 bp and more than 25 bp can be supported. In addition, DRAGEN also uses the de novo assembly to detect SNVs, insertions, and deletions that are co-phased and part of the same haplotypes. Any such co-phased variants that are within a window of 15 bp can then be reassembled into complex variants (MNVs and delins). The tumor-only pipeline produces a VCF file containing both germline and somatic variants that can be further analyzed to identify tumor mutations. Variant calling extends ± 10 bp into introns; details of the regions covered can be found in the assay manifest file. The pipeline makes no ploidy assumptions, enabling detection of low-frequency alleles.
DRAGEN small variant calling includes the following steps:
1. Detects regions with sufficient read coverage (callable regions).
2. Detects regions where the reads deviate from the reference and there is a possibility of a germline or somatic call (active regions).
3. Assembles de novograph haplotypes are assembled from reads (haplotype assembly).
4. Extracts possible somatic or germline calls (events) from column wise pileup analysis.
5. Calibrates read base qualities to account for FFPE noise.
6. Computes read likelihoods for each read/ haplotype pair.
7. Performs variant calling by summing the genotype probabilities across all reads/haplotype pairs.
8. Performs additional filtering to improve variant calling accuracy, including using a systematic noise file. The systematic noise file indicates the statistical probability of noise at specific positions in the genome. This noise file is constructed using clean (normal) samples. Regions where noise is common (eg, difficult to map regions) have higher noise values. The small variant caller penalizes those regions to reduce the probability of making false positive calls.
## Copy Number Variant Calling
The DRAGEN copy number variant caller performs amplification, reference, and deletion calling for CNV targets within the assay. It counts the coverage of each target interval on the panel, uses a preprocessed panel of normal samples to normalize target counts, corrects for GC coverage bias, and calculates scores of a CNV event from observed coverage and makes copy number calls.
Sex genotype determination for TSO 500 is based on the ratio of median coverage on the Y chromosome relative to the autosomes. A sample is classified as male when the Y‑to‑autosome median coverage ratio exceeds 0.05, under the assumption that female samples have zero or near‑zero median coverage on the Y chromosome. In some cases, insufficient coverage of the X chromosome may prevent reliable assessment, resulting in an undetermined sex genotype call.
{% hint style="info" %}
Tumor fraction is not incorporated into the CNV calling algorithm.
{% endhint %}
## BRCA Large Rearrangement Calling
The BRCA large rearrangement step generates segmentation of the BRCA1 and BRCA2 genes for exon-level CNV detection from the BAM file. Using the same method as CNV calling, the large rearrangement component counts coverage of each target interval of the panel, performs normalization, and calculates the fold change values for each probe across the BRCA genes. Normalization includes GC bias correction, sequencing depth, and probe efficiency using a collection of normal FFPE and genomic DNA samples. Initial segmentation is performed for each gene with circular binary segmentation. The merging of segments is then determined by amplitude, noise, and variance at adjacent segments using thresholds established with *in silico* data. A large rearrangement is reported for genes with more than one segment. Coordinates of the exon-level CNV and the log2 mean fold change for each of the BRCA gene segments are found in the `*_DragenExonCNV.json` file.
In rare cases when a sample contains more than three segments the software may not be able to accurate annotate the BRCA LR which will result in a NA in `*_CombinedVariantOutput.tsv`. This reflects a limitation of the segmentation based annotation logic and does not indicate the absence of a BRCA large rearrangement.
## Annotation
The Illumina Annotation Engine performs annotation of small variants, CNVs, and exon-level CNVs. The inputs are gVCF files and the outputs are annotated JSON files.
The Illumina Annotation Engine processes each variant entry and annotates with available information from databases such as dbSNP, gnomAD genome and exome, 1000 genomes, ClinVar, COSMIC, RefSeq, and Ensembl. The header includes version information and general details. Each annotated variant is included as a nested dictionary structure in separate lines following the header.
The following table shows version information for each annotation database:
| Database | Version |
| -------------------- | ------------------------------------------------- |
| gnomeAD | 2.1 |
| COSMIC | v84 |
| ClinVar | 2019-02-04 |
| dbSNP | v151 |
| 1000 Genomes Project | Phase 3 v5a |
| RefSeq | NCBI Homo sapiens Annotation Release 105.20201022 |
## Tumor Mutational Burden
DRAGEN is used to compute tumor mutational burden (TMB) in coding regions where there is sufficient coverage.
The following variants are excluded from the TMB calculation:
* Non-PASS variants.
* Mitochondrial variants.
* MNVs.
* Variants that do not meet a minimum depth threshold (50).
* Variants that do not meet the minimum variant allele threshold (0.05).
* Variants that fall outside the eligible regions.
* Tumor driver mutations. Variants with a population allele count ≥ 50 are treated as tumor driver mutations. Germline variants are not counted towards TMB. Variants are determined as germline based on a database and a proxy filter.
Variants with a population allele count ≥ 10 that are observed in either the 1000 Genomes or gnomAD databases are marked as germline. MNVs, which do not count towards TMB, may be marked as germline when all their component small variants are marked as germline. The proxy filter scans the variants surrounding a specific variant and identifies those variants with similar variant allele frequencies (VAF). If the majority of surrounding variants of similar VAF are germline, then the variant is also marked as germline.
The formula for TMB calculation is:
$$TMB = {Filtered\ Variants \over Eligible\ Region\ Size (Mbp)}$$
$$Nonsynonymous TMB = {Filtered\ Nonsynonymous\ Variants \over Eligible\ Region\ Size (Mbp)}$$
Outputs are captured in a *`_TMB_Trace.tsv` file that contains information on variants used in the TMB calculation and a* `.tmb.json` file that contains the TMB score calculation and configuration details.
## Microsatellite Instability Status
DRAGEN can determine the MSI status of a sample. It uses a normal reference file, which was created from a set of normal samples. Normal reference files were generated by tabulating read counts for each microsatellite site. The normal file contains the read count distribution for each microsatellite site.
MSI calling is assessed on a predefined list of 130 A and T repeats. The first step in calculating the MSI score is determining how many sites are assessable. A site is considered assessable if it has at least 60 spanning reads. A spanning read is defined as one that extends 5 bp before and after the repeat.
Once assessable sites are identified, the distribution of repeat lengths is compared to the panel of normals. A site is classified as unstable if:
* **Jensen-Shannon distance ≥ 0.1**, and
* **P-value ≤ 0.01**.
After all sites are evaluated, DRAGEN reports:
* The total number of sites assessed
* The count of unstable sites
* The percentage of unstable sites across the sample
Finally, the MSI score is calculated as:
## Genomic Instability Score
{% hint style="info" %}
Requires HRD add-on assay (included with v2 kits)
{% endhint %}
Genomic instability score (GIS) is a whole genome signature for homologous recombination deficiency. The GIS is composed of the sum of three components: loss of heterozygosity, telomeric allele imbalance, and large-scale state transition. These components are estimated using the GIS algorithm contracted from Myriad Genetics, which uses an input of the b-allele frequency and coverage across a genome-wide single nucleotide panel. A panel of normal samples is used for both bias reduction and normalization prior to GIS estimation. Final GIS results can be found in the `*.gis.json` file.
### **Tumor fraction**
Tumor fraction is calculated as described in the User Guide, section “HRD Metrics Report” and leverages the Myriad Genetics algorithm. Tumor fraction is output in the Logs\_Intermediates/Gis/SAMPLE/SAMPLE.gis.json and Combined Variant Output file.
### Ploidy
Ploidy is calculated as described in the User Guide, section “HRD Metrics Report” and leverages the Myriad Genetics algorithm. Ploidy is output in the in the Logs\_Intermediates/Gis/SAMPLE/SAMPLE.gis.json and Combined Variant Output file.
## Absolute Copy Number (Beta)
{% hint style="warning" %}
This is a beta feature. Beta feature results are included in the Combined Variant Output file and other files. However, disclaimers that the results are generated by beta features are only provided in the Combined Variant Output file. Requires HRD add-on assay.
{% endhint %}
Absolute copy numbers are calculated by leveraging the Myriad Genetics algorithm. The algorithm segments the entire genome using the HRD panel and provides an A and B allele estimate for each segment. After the TSO 500 pipeline determines CNV calls (using the TSO 500 panel), the segment covering the gene is identified, and the A and B allele numbers of the segment overlapping the gene are reported. If the gene is within 300 kbases from the segment boundary, the estimate is unreliable and “NA” is output. Absolute copy numbers are output in the Logs\_Intermediates/Gis/SAMPLE/SAMPLE.abcn\_annotated.vcf, Logs\_Intermediates/Gis/SAMPLE/SAMPLE.abcn\_genes.tsv and Combined Variant Output file.
## Gene-level Loss of Heterozygosity (Beta)
{% hint style="warning" %}
This is a beta feature. Beta feature results are included in the Combined Variant Output file and other files. However, disclaimers that the results are generated by beta features are only provided in the Combined Variant Output file. Requires HRD add-on assay.
{% endhint %}
Gene-level loss of heterozygosity is calculated based on the minor copy number reported in the abcn\_annotated.vcf. If the minor copy number is 0 then the gene is assumed to have a loss of heterozygosity. Gene-level loss of heterozygosity is output in the Logs\_Intermediates/Gis/SAMPLE/SAMPLE.abcn\_genes.tsv and Combined Variant Output file.
## Contamination Detection
The contamination analysis step detects foreign human DNA contamination using the SNP error file and pileup file that are generated during the small variant calling and the TMB trace file. The software determines whether a sample has foreign DNA using the contamination score. In contaminated samples, the variant allele frequencies in SNPs shift from the expected values of 0%, 50%, or 100%. The algorithm collects all positions that overlap with common SNPs that have variant allele frequencies of <25% or >75%. Then, the algorithm computes the likelihood that the positions are an error or a real mutation. The contamination score is the sum of all the log likelihood scores across the predefined SNP positions with minor allele frequency <25% in the sample and are not likely due to CNV events.
The larger the contamination score, the more likely there is foreign DNA contamination. A sample is considered to be contaminated if the contamination score is above predefined quality threshold. The contamination score was found to be high in samples with highly rearranged genomes or HRD samples. 1% of HRD samples found to be above the threshold with no evidence for actual contamination.
# Block List
The block list represents high noise regions in the panel where false positive variant calls are likely produced. As a result, all positions in the gVCF are marked as Filter=excluded\_regions to indicate variant call results are not reliable in such regions.
The block list includes the following genes:
* HLA A
* HLA B
* HLA C
* KMT2B
* KMT2C
* KMT2D
* chrY
* Any position with VAF 1% occurrence in six or more of the 60 baseline samples.
# RNA Analysis Methods
Refer to [RNA Output](/dragen-tso-500-guides/dragen-tso-500-v2.6/analysis-output/rna-output) for more information.
## Downsampling
Each sample is downsampled to 30 million RNA reads. This number represents the total number of single reads (eg, R1 + R2, from all lanes). When using the recommended sequencing configurations or plexity, the samples can have fewer reads than the downsampling limit. In these cases, the FASTQ files are left as-is.
## Read Trimming
Reads are trimmed to 76 base pairs for further processing.
## RNA Alignment and Fusion Detection
RNA alignment and fusion detection uses trimmed reads in FASTQ format as input. The outputs include a BAM file that contains duplicate-marked read alignments, an SJ.out.tab file that contains unannotated splice junctions, and a CSV file that contains fusion candidates.
DRAGEN aligns RNA reads in a transcript-aware mode using the human hg19 genome containing unplaced contigs (ie, chrUn\_gl regions) and uses GENCODEv19 transcript annotations to identify splice sites. DRAGEN identifies and marks duplicate read alignments using start and end coordinates of alignments, which are adjusted for soft clipped reads.
Fusion and splice variant calling only use deduped fragments to score variants. DRAGEN identifies fusion candidates using chimeric split read alignments (pairs of primary and supplementary alignments) against multiple genes. DRAGEN scores and filters reads based on the various features of each candidate such as the number of supporting reads, mapping quality of supporting reads, and sequence homology between parent genes.
The DRAGEN RNA Fusion caller identifies gene fusions by searching for chimeric reads spanning two distinct parent genes. Based on the chimeric reads, DRAGEN first creates a list of fusion candidates, then scores the candidates to report the list of high confidence fusion calls from the candidate pool.
DRAGEN RNA Fusion caller performs the following steps:
1. Generates fusion candidate generation based on split read alignment.
2. Recruits additional evidence from fusion supporting discordant read pairs and soft-clipped reads.
3. Computes fusion candidate features such as gene coverage, read mapping quality, alternate allele frequency, gene homology, alignment anchor length, and breakpoint distance from exon boundary.
4. Scores and ranks the fusion candidates using a logistic regression model.
5. Selects a final list of fusion calls based on score and other filters including number of supporting reads, unique read alignment count, read through transcripts, and fusions matching the enriched regions.
> Note: In v2.6.2 the rna\_repeats\_hg19.bed file was been updated to include NPM1 to increase sensitivity for that gene (previously this list included only DUX4, SEPT14, CIC, and PSPH).
## Splice Variant Calling
RNA splice variant calling is performed for RNA sample libraries. Candidate splice variants (junctions) from RNA Alignment are compared against a database of known transcripts and a splice variant baseline of non-tumor junctions generated from a set of normal FFPE samples from different tissue types. Any splice variants that match the database or baseline are filtered out unless they are in a set of junctions with known oncological function. If there is sufficient read support, the candidate splice variant is kept. This process also identifies candidate RNA fusions.
## RNA Fusion Merging
Fusions identified during RNA fusion calling are merged with fusions from proximal genes identified during RNA splice variant calling. These are then annotated with gene symbols or names with respect to a static database of transcripts (GENCODE Release 19). The result of this process is a set of fusion calls that are eligible for reporting
## RNA Splice Variant Annotation
The Illumina Annotation Engine annotates detected RNA splice variant calls with transcript-level changes (eg, affected exons in the transcript of a gene) with respect to RefSeq. This RefSeq database is the same RefSeq database used by the small variant annotation process.
# Troubleshooting
# Standalone DRAGEN Server - Troubleshooting
| Failure Type | Actions |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The output file directory contains information from previous analyses |
If this issue is seen, specify a new target output folder and repeat analysis
To prevent this issue: specify an empty directory before starting analysis
|
| Multinode Gather | If the following error appears, check if the sample or pair ID was included multiple times during separate node analysis runs, before being gathered together. If the error exists, rerun one of the analyses without the duplicate and reattempt gathering. `ERROR:Gather:Destination file ... already exists - check if the same sample ID is in multiple input folders` |
# BioInsight Platform Core Pipeline Troubleshooting
In addition to TSO 500 managed sample sheet validations, BioInsight Platform Core (formerly ICA) managed TSO 500 errors include the following:
| Error | Description |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Failure type: ValueError: Could not find pipeline ID for app BCLConvert in sample sheet SampleSheet.csv | Action: Ensure StartsFromFastq field is in the \[TSO500S\_Settings] section, and it is not present in the \[BCLConvert\_Settings] Section. Refer to [Sample Sheet Requirements](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-requirements#ica-auto-launch-sample-sheet-requirements) for more information. |
# NovaSeq 6000Dx App Troubleshooting
| Failure Type | Action Taken |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Analysis is unable to start, hanging indefinitely after installing another app with incompatible DRAGEN version. For detailed scenario, see: [Analysis Launch with NovaSeq 6000Dx Application](/dragen-tso-500-guides/dragen-tso-500-v2.6/launching-analysis/analysis-launch-with-novaseq-6000dx-application) |
The following steps need to be executed by a user with root access to the server that is paired with the NovaSeq 6000Dx:
Locate the DRAGEN .run file on the server
The file should be under the following path with the following name pattern: /staging/data/install/dragen/illumina.drageninstaller@{dragen\_version}/dragen-{dragen\_version}..run, where dragen\_version is the version of DRAGEN needed for the application
For example: /staging/data/install/dragen/illumina.drageninstaller\@3.10.19/dragen-3.10.19-11.multi.el8.x86\_64.run
Execute the DRAGEN run file by typing the appropriate command into the server terminal similar to the following:
Navigate to the DRAGEN page from the IRM menu to see that the installed version of DRAGEN is as intended. If the version has not updated, navigate away from the DRAGEN page and then return to the DRAGEN page.
|
| Same problem as above, but running an app using a lower version of DRAGEN (ie 2.6.0 using DRAGEN 3.10.17) | Same instructions as above |
# Sample Sheet Troubleshooting
## General troubleshooting for a failed sample sheet:
In DRAGEN TruSight Oncology 500 Analysis Software, the analysis fails if a sample sheet is invalid. If an invalid sample sheet in suspected, log files can help troubleshoot a failed analysis. Use the following steps to find the log file for the sample sheet:
1. Navigate to the following location `//Logs_Intermediates/SamplesheetValidation.`
2. Open the `SamplesheetValidation-.log` file
3. Find a line with the following: `SampleSheetValidationTask:NA:1 exited with return code 1 which has not been declared as a valid return code.`
4. Search for errors in the sample sheet validation log and compare with the guidelines and warnings in [Sample Sheet Requirements](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-requirements) and the following tables.
| Failure Type | Action |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sample Sheet not found | Verify that `SampleSheet.csv` is present at the top level of the run folder with the name "SampleSheet.csv". If the sample sheet is in a different location, supply the sample sheet using the `--sampleSheet` option |
| Indexes are not valid for the sequencer and/or assay | See Valid indexes for assay and instrument combinations for correct indexes for the sequencer and assay. |
| Pair\_ID is not unique | Pair\_ID column is required in the TSO500S\_Data section of the sample sheet, which pairs at most one RNA and one DNA sample together for analysis. If the sample does not have a pair, use a unique pair ID for single samples. |
| Sample Sheet is not in v2 format | Verify that the format of the sample sheet is v2. v1 sample sheet is not compatible with DRAGEN TruSight Oncology 500 Analysis Software. |
| Analysis does not run | Verify the analysis starts from the run folder, and BCLs or FASTQs are in the correct locations as outlined in Starting From BCL Files and Starting From FASTQ Files respectively. |
## Indexes included in Library Prep Kit:
| Assay | Index Set ID |
| ---------- | ------------------------------------------------------------ |
| TSO 500 |
UP1-UP16
CP1-CP16 (DNA Only)
|
| TSO 500 HT |
UDP0001–UDP0192
|
| TSO 500 v2 |
UDP0001–UDP0384 (v3 index when applicable)
|
## Troubleshooting BCL issues
| Failure Type | Action |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Lane Column without Values | Ensure that the column is completed. If lane is not applicable to the run, delete the column. |
| Format of v2 sample sheet is incorrect |
Verify that the following sections and fields are present in the sample sheet and follow the individual rules in Sample Sheet Requirements
|
| HRD analysis is missing | Verify that HRD is in the Sample Feature column in the sample sheet. Refer to [Sample Sheet Requirements](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-requirements) for more information. |
## Troubleshooting FASTQs issues
| Failure Type | Action |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sample\_ID and/or Sample\_Type is not present | Verify that the sample sheet has columns and values for Sample\_ID and Sample\_Type. |
| Unique sample IDs | Verify that the Sample\_IDs are unique in the sample sheet. |
| Format of v2 Sample Sheet is incorrect |
Verify that the following sections and fields are present in the sample sheet and follow the individual rules in Sample Sheet Requirements. \[TS0500S\_Data] - Sample\_ID - Index\_ID - Sample\_Type - Pair\_ID
- Sample Feature (Optional) Verify when FASTQs were generated using the HRD add-kit (Not available in Japan), Sample Feature is added to those DNA Samples. Refer to Sample Sheet Requirements for more information.
|
| Incorrect folder structure | Verify that the FASTQ files are in the correct structure. Refer to [Starting From FASTQ Files](/dragen-tso-500-guides/dragen-tso-500-v2.6/launching-analysis/run-dragen-tso-software/command-line-options#starting-from-fastq-files) for more information. |
| Invalid FASTQ input files | If the FASTQs are invalid, start TSO 500 analysis from BCL files. |
| HRD analysis missing | Make sure that HRD is in the correct column in the sample sheet. |
# Analysis Pipeline Troubleshooting
| Failure Type | Action |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| One or more pipeline steps fail |
- Open the log file ./\/Logs\_Intermediates/pipeline\_trace.txt. This log file displays each pipeline step run by the Nextflow workflow manager software. If a step fails, it is marked as FAILED. Each step generates log files that are stored in step-specific subfolders in the Logs\_Intermediates folder. Review the log files in the relevant Logs\_Intermediates folder for the step to identify potential sources of error. - Open the errors folder ./\/errors. The workflow creates an error file, error\_\.json, for each step that failed during analysis. For steps that fail per sample, there is a separately labeled file for each sample that failed each step error\_\\_\.json. These files contain the command and stdout and stderr from the step.
|
| One or more samples are missing results for one or more variant types | Open the combined metrics output results file `.//Results//MetricsOutput.tsv`. If a sample fails an analysis step, the Pair ID that contains the sample shows the failure under `FAILED_STEPS` in the Analysis Status section, and `COMPLETED_ALL_STEPS` shows as False. If available, review the individual log files for the failed steps under `.//Logs_Intermediates` to identify potential sources of error. |
| Single exon (single probe) genes are still reported in the CNV VCF file, but not the CNV TSV file |
No action needed; software is working as expected.
For v2.6.1 and below, CNV events for genes with low probe coverage are not emitted to the Copy Number Variants section of our CombinedVariantOutput.tsv. However, you can still find these events in the cnv.vcf.gz.
Due to the low probe coverage, accurate CNV calling has not been validated and as such they are emitted as REF These events are no longer included in the VCF starting in v2.6.2.
|
| Testing of cell lines, contrived samples and commercial controls does not return expected results | Review recommendations for using these samples types [here](/performance-testing/known-limitations-with-commercial-controls). |
# DRAGEN TSO 500 v2.5
# Introduction to DRAGEN TSO 500 Analysis Software v2.5.x
## Scope
This resource provides information on installation, configuration, running, troubleshooting and analysis algorithms for the following software:
* DRAGEN TruSight Oncology 500 Analysis Software on BioInsight Platform Core (formerly ICA) v2.5.2
* DRAGEN TruSight Oncology 500 Analysis Software v2.5.3 (for standalone DRAGEN server)
* DRAGEN TruSight Oncology 500 Analysis Software v2.5.4 (for standalone DRAGEN server)
The content is applicable to all 3 software versions unless otherwise specified. The content related to setting up and running the analysis on Platform Core is only relevant to v2.5.2.
## Overview
DRAGEN TruSight™ Oncology 500 Analysis Software supports data analysis for TruSight Oncology 500 Assay and TruSight Oncology 500 High-Throughput Assay, both Research Use Only (RUO).
The software provides local and cloud analysis for DNA and RNA libraries generated from formalin-fixed, paraffin-embedded (FFPE) tissue samples. The assays and the software are optimized to provide high sensitivity and specificity for low-frequency somatic variants across coding exons and additional regions of biological relevance in 523 genes for DNA biomarkers.
In addition, this software supports data analysis for TruSight Oncology 500 HRD (RUO), an optional add-on kit to TruSight Oncology 500, that enables detection of homologous recombination deficiency (HRD) through assessment of a genomic instability score (GIS).
{% hint style="info" %}
TruSight Oncology 500 HRD is not available in Japan
{% endhint %}
### DNA biomarkers:
* Single nucleotide variants (SNVs)
* Insertions
* Deletions
* Copy number variants (CNVs)
* Exon-level CNVs
* Multinucleotide variants (MNVs)
* Genomic Instability Score (GIS Score) \*
### DNA Immunotherapy Biomarkers:
* Tumor mutational burden (TMB)
* Microsatellite instability (MSI)
### RNA biomarkers (called from 55 genes):
* Fusions
* Splice variants
### Beta features:
* Absolute copy numbers (ACN)\*
* Loss of heterozygosity (LOH)\*
* Tumor fraction\*
* Ploidy\*
Details of the regions covered by the assays can be found in the assay manifest file. Contact your local Illumina representative for more information.
{% hint style="info" %}
\*Requires TruSight Oncology 500 HRD add-on kit
{% endhint %}
{% hint style="info" %}
Variant reporting by DRAGEN TruSight™ Oncology 500 Analysis Software is limited by a manifest file and a [block list file](/dragen-tso-500-guides/dragen-tso-500-v2.5/analysis-methods/dna-analysis-methods/block-list). The manifest file excludes regions where the probe set does not effectively capture targets, and the block list file excludes specific positions from variant calling. TSO 500 assay probes target at least 97% of the CDS of 474 genes. Please contact your local Illumina representative for more information if needed.
{% endhint %}
## Local and Cloud Deployments
Local analysis is available using a standalone DRAGEN server. The software on the standalone DRAGEN server allows for analysis on a single DRAGEN server or splitting across multiple servers.
Cloud analysis is available on Platform Core with auto-launch (from BCL) or manual launch (from BCLs and FASTQs), see exceptions for NextSeq 1000/2000 and NovaSeq X in the instrument compatibility tabel below.
## Instrument Compatibility
DRAGEN TruSight Oncology 500 analysis software v2.5.x is compatible with data generated on the Illumina instruments as summarized in the table below.
Instrument
BioInsight Platform Core*
Standalone DRAGEN Server
Paired DRAGEN server
On-board DRAGEN
NextSeq 550Dx (RUO mode)
Yes
Yes
No
N/A
NextSeq 500/550
Yes
Yes
N/A
N/A
NovaSeq 6000
Yes
Yes
N/A
N/A
NovaSeq 6000Dx (RUO mode)
Yes
Yes
No
N/A
NextSeq 1000/2000
Yes**
Yes**
N/A
No
NovaSeq X
Yes**
Yes**
N/A
No
\*Among v2.5.x, only DRAGEN TruSight Oncology 500 analysis software v2.5.2 is supported on Platform Core
\*\*For the data generated with NextSeq 1000/2000 and NovaSeq X, analysis can be started only from FASTQs (not from BCLs). Only manual launch is available for Platform Core.
# Getting Started
# Installation of 2.5.3 on Standalone DRAGEN Server
## Overview
The installation script for DRAGEN TruSight Oncology 500 Analysis Software installs the following software and dependencies:
1. DRAGEN TruSight Oncology 500 Analysis Software itself
2. DRAGEN Software if a compatible version is not present
3. Docker software if a compatible version is not present
4. A script required to generate DRAGEN genome hash table
5. A script to check that DRAGEN TruSight Oncology 500 Analysis Software is installed properly
## Installation Requirements
### Hardware
* DRAGEN server v3 or v4
* Network-attached storage (NAS) with enabled mkfifo if performing analysis for the TruSight Oncology 500 High-Throughput assay
### Software
The following software is required to successfully install DRAGEN TSO 500 v2.5.3:
* Linux CentOS 7.9 operating system (or later) or Oracle Linux 8 (or later), one of which is provided on the server. Oracle Linux 8 is recommended.
* Docker Software, see table below for minimum version needed. If sufficient Docker software is not present on the server, the TSO 500 installer will install compatible Docker software.
* DRAGEN Server Software, see table below for minimum version needed as the host version on the server. If sufficient DRAGEN software is not present on the server, the TSO 500 installer will install compatible DRAGEN software.
| Software Dependency | Compatible | Installs |
| ------------------- | -------------------------------- | ----------------------- |
| Docker | 20.10 or greater | Docker 20.10.15 |
| DRAGEN Software | v3.10.x where x is 16 or greater | DRAGEN Software 3.10.16 |
### Licenses
* `TSOCombined` license
* `TSO500_HRD` license (to analyze data generated with the TSO 500 HRD add-on kit)
`TSOCombined` license has been pre-installed to DRAGEN servers in manufacturing since August 2022 and `TSO500_HRD` since February 2025 and additionally distributed to DRAGEN servers connected online. To generate a list of installed DRAGEN server licenses, run the following command: `/opt/edico/bin/dragen_lic`. If a license is not installed, contact Illumina Customer Care at for the license.
### Permissions
Illumina recommends logging in as root user for installation, but as a non-root user for running TSO 500 analysis.
* A non-root user must be a member of the Docker group to run Docker. For more information on Docker permission requirements and alternatives to running as root, refer to the Docker documentation available on the [Docker website](https://www.docker.com/).
* Installing and uninstalling DRAGEN TruSight Oncology 500 Analysis Software and running the system check requires root privileges.
* Run DRAGEN TruSight Oncology 500 Analysis Software without being logged in as a root user. Running the DRAGEN TruSight Oncology 500 Analysis Software as root is not required or recommended.
## Compatibility with other DRAGEN Pipelines
DRAGEN TSO 500 Analysis Software v2.5.3 is single-version compatible. It does not include multi-version compatibility that refers to ability to be installed on a single DRAGEN server with software running a different version of DRAGEN software. For example, multi-version compatible pipelines running DRAGEN v4.3.6 can be co-installed on a server alongside DRAGEN TSO 500 pipelines running DRAGEN v3.10.17. For more details on DRAGEN multi-version compatibility, please visit [page 7 of the DRAGEN v4.3.6 software release notes](https://support.illumina.com/content/dam/illumina-support/documents/downloads/software/dragen/release-notes/200056923_00_DRAGEN_4_3_6_Customer-Release-Notes.pdf).
Compatibility of software for co-installation with DRAGEN TSO 500 v2.5.3 on a DRAGEN server is summarized in the table below:
Software
Version
Type
Compatible
DRAGEN TSO 500
2.5.2 or below
Single-version
No
DRAGEN TSO 500
2.5.4
Multi-version
No
DRAGEN TSO 500
2.6.0
Single-version
Yes*
DRAGEN TSO 500
2.6.1+
Multi-version
No
DRAGEN TSO 500 ctDNA
1.2 or below
Single-version
No
DRAGEN TSO 500 ctDNA
2.1.1, 2.5.0, 2.6.0, 2.6.1
Single-version
Yes**
DRAGEN TSO 500 ctDNA
2.6.2+
Multi-version
No
DRAGEN pipelines***
3.10.16
Single-version
Yes
DRAGEN pipelines***
Any version except 3.10.16
Single- or multi-version
No
\*Install DRAGEN TSO 500 Analysis Software v2.6.0 after installing 2.5.3. If v2.5.3 is installed after v2.6.0, re-execute the installation script for v2.6.0 to install the compatible version of DRAGEN Software without impacting v2.5.3.
\*\* When co-installing v2.5.3 with DRAGEN TSO 500 ctDNA software on the same DRAGEN server, install the software with the highest corresponding DRAGEN Software version last. Find DRAGEN software versions for DRAGEN TSO 500 ctDNA software in parentheses: v2.1.1 (v3.10.9), v2.5.0 (v3.10.15), 2.6.0 (v3.10.17), 2.6.1 (v3.10.18).
\*\*\*For example, DRAGEN Enrichment, DRAGEN Germline, and others
## Installation Instructions
As a root user, perform the following steps to install DRAGEN TSO 500 v2.5.3 Analysis Software:
1. Contact Illumina Customer Care at to obtain the DRAGEN TSO 500 Analysis Software installer package.
2. Download the installation package provided in the email from Illumina. **The link expires after 7 days.**
{% hint style="info" %}
It is recommended to use a command line tool like wget or curl to download the file rather than pasting the link into the web browser bar. For example:
`curl -o {filename} "{link}"`
`wget -O {filename} '{link}'`
Where the file name is the installation script file name, and the link is provided by Illumina Customer Care.
{% endhint %}
3. Make sure no other analysis is being performed. Installing the software while performing other analyses prevent the installer process from proceeding
4. Copy the install script to the `/staging` directory to store the script in the directory.
{% hint style="info" %}
Installation Script: install\_DRAGEN\_TSO500-2.5.3.run
MD5sum: sha256:ab9fae7ba58842d797ba689e702693c0fd7a5c2852dda610dce6d68152fe1f8d
{% endhint %}
5. Use the following command to update the run script permission:\
`chmod +x /staging/install_DRAGEN_TSO500-2.5.3.run`
6. Use the following command to run the installation script (run time \~ 20 mins):
1. For Docker, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500-2.5.3.run`. The script installs compatible DRAGEN software and removes any previously installed versions.
2. For Apptainer, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500-2.5.3.run -- --noDockerInstall` This will not install Apptainer, but will install the analysis software in the SIF container format and modify the software to launch analyses using Apptainer.
7. During the installation process, you might be instructed to reboot or power cycle the system to complete the installation of the DRAGEN software. A power cycle of the system requires the server be shut down and restarted.
8. Log out of the server and then log back in.
9. Use the following command to build the DRAGEN server hash table, which runs for approximately 60 minutes:\
`/usr/local/bin/build-hashtable_DRAGEN_TSO500-2.5.3.sh`\
Refer to [Troubleshooting](/dragen-tso-500-guides/dragen-tso-500-v2.5/troubleshooting) if any errors occur.
## License Installation
Review license requirements, how to check which licenses are installed and how to receive a license in [Licenses](#licenses). Licenses can be installed before or after DRAGEN TSO 500 software installation.
To install a license (`TSOCombined` and/or `TSO500_HRD`) on a DRAGEN server connected to the internet:
1. Confirm that the server is connected to the Internet, example: `ping www.illumina.com`
2. Run the following command: `/opt/edico/bin/dragen_lic -i auto`
To install a license (`TSOCombined` and/or `TSO500_HRD`) on a DRAGEN server not connected to the internet:
1. Contact Customer Care at to request a license file for each of the needed licenses
2. Download and save the license file(s) to a location that is accessible from the DRAGEN server
3. For each license file, run the command, where \ is the absolute path to the license file: `sudo /opt/edico/bin/dragen_lic -i /tmp/.bin`
To check the success of license installation, run: `/opt/edico/bin/dragen_lic`. Installed licenses should be in the list.
## Running the System Check
After installation is complete, make sure the system functions properly by running the following command: `/usr/local/bin/check_DRAGEN_TSO500-2.5.3.sh`
The script checks that:
* All required services are running
* Proper Docker image is installed
* DRAGEN TSO 500 Analysis Software can successfully process a test data set
The system check script runs for approximately 25 minutes. If the script prints a failure message, contact Illumina Technical Support and provide the `/staging/check_DRAGEN_TSO500_.tgz` output file.
If using MacOS to connect to a server, an error can occur if the local settings are not in English. To resolve the error, disable the ability to set environment variables automatically in Terminal settings.
## Uninstall Software
The DRAGEN TruSight Oncology 500 Analysis Software installation includes an uninstall script called `uninstall_DRAGEN_TSO500-2.5.3.sh`, which is located in `/usr/local/bin`.
Executing the uninstall script removes the following assets:
* All DRAGEN TruSight Oncology 500 Analysis Software related scripts located in `/usr/local/bin`
* Resources found in `/staging/illumina/DRAGEN_TSO500`
* The `dragen_tso500:2.5.3`: Docker image
To uninstall the DRAGEN TSO 500 Analysis Software, run the following command as a root user:
`uninstall_DRAGEN_TSO500-2.5.3.sh`
You are not required to uninstall Docker or DRAGEN software. To remove Docker, review the install instructions for your operating system in the Docker documentation.
# Installation of v2.5.4 on Standalone DRAGEN Server
## Overview
The installation script for DRAGEN TruSight Oncology 500 Analysis Software installs the following software and dependencies:
1. DRAGEN TruSight Oncology 500 Analysis Software itself
2. DRAGEN Software if a compatible version is not present
3. Docker software if a compatible version is not present
4. A script required to generate DRAGEN genome hash table
5. A script to check that DRAGEN TruSight Oncology 500 Analysis Software is installed properly
## Installation Requirements
### Hardware
* DRAGEN server v3 or v4
* Network-attached storage (NAS) with enabled mkfifo if performing analysis for the TruSight Oncology 500 High-Throughput assay
### Software
The following software is required to successfully install DRAGEN TSO 500 v2.5.4:
* Linux CentOS 7.9 operating system (or later) or Oracle Linux 8 (or later), one of which is provided on the server. Oracle Linux 8 is recommended.
* Docker Software, see table below for minimum version needed. If sufficient Docker software is not present on the server, the TSO 500 installer will install compatible Docker software.
* DRAGEN Server Software\*, see table below for minimum version needed as the host version on the server. If sufficient DRAGEN software is not present on the server, the TSO 500 installer will install compatible DRAGEN software.
Software Dependency
Compatible
Installs
Docker
20.10 or greater
Docker 20.10.15
DRAGEN Server Software*
v3.10.x, where x >=19, v4.3+
DRAGEN Software 3.10.19
{% hint style="info" %}
\*The DRAGEN Server Software version may be higher than the DRAGEN version used by the DRAGEN TSO 500 v2.5.4 pipeline (DRAGEN v3.10.16), which is provided inside the DRAGEN TSO 500 docker image.
{% endhint %}
### Licenses
* `TSOCombined` license
* `TSO500_HRD` license (to analyze data generated with the TSO 500 HRD add-on kit)
`TSOCombined` license has been pre-installed to DRAGEN servers in manufacturing since August 2022 and `TSO500_HRD` since February 2025 and additionally distributed to DRAGEN servers connected online. To generate a list of installed DRAGEN server licenses, run the following command: `/opt/edico/bin/dragen_lic`. If a license is not installed, contact Illumina Customer Care at for the license.
### Permissions
Illumina recommends logging in as root user for installation, but as a non-root user for running TSO 500 analysis.
* A non-root user must be a member of the Docker group to run Docker. For more information on Docker permission requirements and alternatives to running as root, refer to the Docker documentation available on the [Docker website](https://www.docker.com/).
* Installing and uninstalling DRAGEN TruSight Oncology 500 Analysis Software and running the system check requires root privileges.
* Run DRAGEN TruSight Oncology 500 Analysis Software without being logged in as a root user. Running the DRAGEN TruSight Oncology 500 Analysis Software as root is not required or recommended.
## Compatibility with other DRAGEN pipelines
DRAGEN TSO 500 Analysis Software v2.5.4 is multi-version compatible. Multi-version compatibility refers to ability to be installed on a single DRAGEN server with software running a different version of DRAGEN software. For example, multi-version compatible pipelines running DRAGEN v4.3.6 can be co-installed on a server alongside DRAGEN TSO 500 pipelines running DRAGEN v3.10.17. For more details on DRAGEN multi-version compatibility, please visit [page 7 of the DRAGEN v4.3.6 software release notes](https://support.illumina.com/content/dam/illumina-support/documents/downloads/software/dragen/release-notes/200056923_00_DRAGEN_4_3_6_Customer-Release-Notes.pdf).
Software versions without multi-version compatibility referred to as single-version compatible. DRAGEN TSO 500 Analysis Software v2.5.4 will disrupt installations of single-version compatible software from the DRAGEN server. To uninstall a previous version of DRAGEN TSO 500 Analysis Software, refer to the respective guide.
Compatibility of software for co-installation with DRAGEN TSO 500 v2.5.4 on a DRAGEN server is summarized in the table below:
Software
Version
Type
Compatible
DRAGEN TSO 500
2.6.1
Multi-version
Yes*
DRAGEN TSO 500
2.6.0
Single-version
No
DRAGEN TSO 500
2.5.3 or below
Single-version
No
DRAGEN TSO 500 ctDNA
2.6.2+
Multi-version
Yes
DRAGEN TSO 500 ctDNA
2.6.1 or below
Single-version
No
DRAGEN pipelines**
4.3.6+
Multi-version
Yes
DRAGEN pipelines**
4.2 or below
Single-version
No
\*DRAGEN TSO 500 Analysis Software v2.5.4 can run on a single server with another multi-version compatible DRAGEN TSO 500 Analysis Software, e.g. DRAGEN TSO 500 v2.6.1, and should be installed before v2.6.1. DRAGEN TSO 500 Analysis Software v2.5.4 can be co-installed with multi-version compatible DRAGEN TSO 500 ctDNA Analysis Software or other DRAGEN pipelines with any order of installation.
\*\*For example, DRAGEN Enrichment, DRAGEN Germline, DRAGEN WGS Heme v1.0.0 and others. Order of installation does not matter.
## Installation Instructions
As a root user, perform the following steps to install DRAGEN TruSight Oncology 500 Analysis Software v2.5.4:
1. Contact Illumina Customer Care at to obtain the DRAGEN TruSight Oncology 500 Analysis Software installer package.
2. Download the installation package provided in the email from Illumina. **The link expires after 7 days.**
{% hint style="info" %}
It is recommended to use a command line tool like wget or curl to download the file rather than pasting the link into the web browser bar. For example:
`curl -o {filename} "{link}"`
`wget -O {filename} '{link}'`
Where the file name is the installation script file name, and the link is provided by Illumina Customer Care.
{% endhint %}
3. Make sure no other analysis is being performed. Installing the software while performing other analyses prevent the installer process from proceeding
4. Copy the install script to the `/staging` directory to store the script in the directory.
{% hint style="info" %}
Installation Script: install\_DRAGEN\_TSO500-2.5.4.run
MD5sum: sha256:0d871d8b93b4e535c0c1b5614c180fdb815f80764274279881c8a25a4e153160
{% endhint %}
5. Use the following command to update the run script permission:\
`chmod +x /staging/install_DRAGEN_TSO500-2.5.4.run`
6. Use the following command to run the installation script (run time \~ 20 mins):
1. For Docker, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500-2.5.4.run`. The script installs compatible DRAGEN software and removes any previously installed versions.
2. For Apptainer, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500-2.5.4.run -- --noDockerInstall` This will not install Apptainer, but will install the analysis software in the SIF container format and modify the software to launch analyses using Apptainer.
7. During the installation process, you might be instructed to reboot or power cycle the system to complete the installation of the DRAGEN software. A power cycle of the system requires the server be shut down and restarted.
8. Log out of the server and then log back in.
9. Use the following command to build the DRAGEN server hash table (run time \~ 1 hr):\
`/usr/local/bin/build-hashtable_DRAGEN_TSO500-2.5.4.sh`\
Refer to [Troubleshooting](/dragen-tso-500-guides/dragen-tso-500-v2.5/troubleshooting) if any errors occur.
## License Installation
Review license requirements, how to check which licenses are installed and how to receive a license in [Licenses](#licenses). Licenses can be installed before or after DRAGEN TSO 500 software installation.
To install a license (`TSOCombined` and/or `TSO500_HRD`) on a DRAGEN server connected to the internet:
1. Confirm that the server is connected to the Internet, example: `ping www.illumina.com`
2. Run the following command: `/usr/bin/dragen_lic -i auto`
To install a license (`TSOCombined` and/or `TSO500_HRD`) on a DRAGEN server not connected to the internet:
1. Contact Customer Care at to request a license file for each of the needed licenses
2. Download and save the license file(s) to a location that is accessible from the DRAGEN server
3. For each license file, run the command, where \ is the absolute path to the license file: `sudo /usr/bin/dragen_lic -i /tmp/.bin`
To check the success of license installation, run: `/usr/bin/dragen_lic`. Installed licenses should be in the list.
## Running the System Check
After installation is complete, make sure the system functions properly by running the following command: `/usr/local/bin/check_DRAGEN_TSO500-2.5.4.sh`
The script checks that:
* All required services are running
* Proper Docker image is installed
* DRAGEN TSO 500 Analysis Software can successfully process a test data set
The system check script runs for approximately 25 minutes. If the script prints a failure message, contact Illumina Technical Support and provide the `/staging/check_DRAGEN_TSO500_.tgz` output file.
If using MacOS to connect to a server, an error can occur if the local settings are not in English. To resolve the error, disable the ability to set environment variables automatically in Terminal settings.
## Uninstall Software
The DRAGEN TSO 500 Analysis Software installation includes an uninstall script called `uninstall_DRAGEN_TSO500-2.5.4.sh`, which is located in `/usr/local/bin`.
Executing the uninstall script removes the following assets:
* All DRAGEN TSO 500 Analysis Software related scripts located in `/usr/local/bin`
* Resources found in `/staging/illumina/DRAGEN_TSO500`
* The `dragen_tso500:2.5.4`: Docker image
To uninstall the DRAGEN TSO 500 Analysis Software, run the following command as a root user:
`uninstall_DRAGEN_TSO500-2.5.4.sh`
You are not required to uninstall Docker or DRAGEN software. To remove Docker, review the install instructions for your operating system in the Docker documentation.
# Getting Started on Illumina BioInsight Platform Core
## Prerequisites
An Illumina BioInsight Platform subscription includes access to DRAGEN TruSight Oncology 500 Analysis Software on BioInsight Platform Core (formerly ICA). To get started, you need:
* A BioInsight Platform account with a valid subscription. Refer to the [Software Registration page](https://help.connected.illumina.com/account-management/rg-registration) for information on how to register a BioInsight Platform subscription and Illumina BioInsight Credits (BICs).
* A positive balance of BICs for data storage. Please refer to the [BioInsight Credits pricing page](https://help.ica.illumina.com/reference/r-pricing) and [storage requirements](#minimum-storage-requirements-on-ica) for more information.
## Minimum Storage Requirements on Platform Core
The table provides guidance on the storage needs and associated Platform Core storage size settings.
Sequencing System
Minimum Disk Space (Gb)
Platform Core Storage Size Value
NextSeq 500/550/550Dx (RUO) HO flow cell
350
Large
NovaSeq 6000/6000Dx (RUO) SP Flow Cell
500
Large
NovaSeq 6000/6000Dx (RUO) S1 Flow Cell
1100
Large
NovaSeq 6000/6000Dx (RUO) S2 Flow Cell
2,500
Large
NovaSeq 6000/6000Dx (RUO) S4 Flow Cell
4,300
Large
NovaSeq X 1.5B
2,000
Large
NovaSeq X 10B
4,300
Large
NovaSeq X 25B
8,400
XLarge
NextSeq 1000/2000
350
Large
# Run Planning
# Sample Sheet Introduction
## Overview
A sample sheet is required for each analysis with DRAGEN TruSight Oncology 500 Analysis Software. A sample sheet is a comma-separated value (\*.csv) file format used by Illumina instruments, platforms, and analysis pipelines to store settings and data for sequencing and analysis. The DRAGEN TruSight Oncology 500 Analysis Software is compatible with the sample sheet v2. For general information on the sample sheet v2, refer to [Illumina BioInsight Platform - Sample Sheet](https://help.connected.illumina.com/run-set-up/overview).
The sample sheet includes a list of samples and their index sequences, along with additional information required to run DRAGEN TruSight Oncology 500 Analysis Software. For example, DNA samples with the TruSight Oncology 500 HRD add-on probes must be indicated in the Sample Feature column of the sample sheet. Appropriate index adapter sequences are determined by the assay used to perform analysis.
When running analysis on a standalone DRAGEN server or on BioInsight Platform Core (formerly ICA), a valid sample sheet can be created by:
* BaseSpace Run Planner (preferred), see [Sample Sheet Creation in BaseSpace Run Planner page](/dragen-tso-500-guides/dragen-tso-500-v2.5/run-planning/sample-sheet-creation-in-basespace-run-planning-tool) for details
* Downloading and modifying a sample sheet template following the requirements, see [Sample Sheet Requirements page](/dragen-tso-500-guides/dragen-tso-500-v2.5/run-planning/sample-sheet-requirements) for details
The run set up section of this guide includes specific instructions to plan a run and set up a valid sample sheet for each deployment of DRAGEN TruSight Oncology 500 Analysis Software.
# Sample Sheet Requirements
DRAGEN TSO 500 Analysis Software has optional and required fields that are required in addition to general sample sheet requirements. Follow the steps below to create a valid samplesheet.
## Standard Sample Sheet Requirements
The following sample sheet requirements describe required and optional fields for DRAGEN TSO 500 Analysis Software. Depending on the deployment (standalone DRAGEN server, BioInsight Platform Core (formerly ICA) with auto-launch, Platform Core with manual launch), certain sections and required values can deviate from the standard requirements. These deviations are noted in the information below.
{% hint style="warning" %}
The analysis fails if the sample sheet requirements are not met.
{% endhint %}
Use the following steps to create a valid sample sheet.
1. Download the sample sheet v2 template that matches the instrument & assay run.
2. In the BCL Convert Settings section, enter the following required parameters:
### \[BCLConvert\_Settings] Section
Sample Parameter
Required
Details
SoftwareVersion
Required
The DRAGEN component software version. For DRAGEN TSO 500 v2.5.3 and v2.5.4 specify 3.10.16.
AdapterRead1
Required
If using 8 bp indexes starting with UP or CP (used with TSO 500): AGATCGGAAGAGCACACGTCTGAACTCCAGTCA
If using 10 bp indexes with UDP (used with TSO 500 HT): CTGTCTCTTATACACATCTCCGAGCCCACGAGAC
Analysis fails if the incorrect adapter sequences are used
AdapterRead2
Required
If using 8 bp indexes starting with UP or CP (used with TSO 500): AGATCGGAAGAGCGTCGTGTAGGGAAAGAGTGT
If using 10 bp indexes with UDP (used with TSO 500 HT): CTGTCTCTTATACACATCTGACGCTGCCGACGA
Analysis fails if the incorrect adapter sequences are used
AdapterBehavior
Required
Enter trim This indicates that the BCL Convert software trims the specified adapter sequences from each read.
MinimumTrimmedReadLength
Required
Enter 35. Reads with a length trimmed below this point are masked.
MaskShortReads
Required
Enter 35. Reads with a length trimmed below this point are masked.
3. In the BCL Convert Data section, enter the following parameters for each sample.
### \[BCLConvert\_Data] Section
Sample Parameter
Required
Details
Sample_ID
Required
Must match a Sample_ID listed in the TSO 500 Data section.
Index
Required
Index 1 sequence valid for Index_ID assigned to matching Sample_ID in the TSO 500 Data section.
Index2
Required
Index 2 sequence valid for Index_ID assigned to matching Sample_ID in the TSO 500 Data section.
Lane
Only for NovaSeq 6000 XP, NovaSeq 6000Dx, or NovaSeq X workflows
Indicates which lane corresponds to a given sample. Enter a single numeric value per row. Cannot be empty, i.e the analysis fails if the Lane column is present without a value in each row.
4. In the TSO 500 Data section, enter the following parameters:
{% hint style="info" %}
TSO 500 Data Section header changes depending on the deployment:
* Standalone DRAGEN Server and Platform Core with Manual Launch: `TSO500S_Data`
* Platform Core with Auto-launch: `Cloud_TSO500S_Data`
{% endhint %}
### \[TSO500S\_Data] Section
Sample Parameter
Required
Details
Sample_ID
Required
The unique ID to identify a sample. The sample ID is included in the output file names. Sample IDs are not case sensitive. Sample IDs must have the following characteristics: - Unique for the run. - 1–40 characters. - No spaces. - Alphanumeric characters with underscores and dashes. If you use an underscore or dash, enter an alphanumeric character before and after the underscore or dash. eg, Sample1-T5B1_022515. - Cannot be called all, default, none, unknown, undetermined, stats, or reports. - Must match a Sample_ID listed in the TSO 500 Data section. - Illumina recommends that the sample ID be based on the pair ID. Example: <Pair_ID>-DNA,<Pair_ID>-RNA. - Each sample must have a unique combination of Lane (if applicable), sample ID, and index ID or the analysis will fail.
Sample_Type
Required
Enter DNA or RNA. For HRD samples, this parameter must be DNA.
Pair_ID
Required
A unique ID that links DNA and RNA from the same biological sample from the same individual. Pair ID shares, at most, one DNA and one RNA sample per run. eg, if a Sample_ID is TestSample1-DNA for DNA and TestSample1-RNA for RNA, the Pair_ID TestSample1 will link these samples that are on different rows in the sample sheet together. If the pair ID is associated with more than one DNA or RNA sample, the analysis fails.
Sample_Feature
Required when using HRD add-on kit
Required for HRD enriched samples. For DNA samples that have undergone HRD enrichment, enter HRD in this column of the sample sheet. If the sample has not undergone HRD enrichment, leave the field empty.
Sample_Description
Not Required
Sample description must meet the following requirements: - 1–50 characters. - Alphanumeric characters with underscores, dashes and spaces. If you enter a underscore, dash, or space, enter an alphanumeric character before and after. eg, Solid-FFPE_213.
To ensure a successful analysis, follow these guidelines:
1. Avoid any blank lines at the end of the sample sheet; these can cause the analysis to fail.
2. When running local analysis using the command line save the sample sheet in the sequencing run folder with the default name `SampleSheet.csv`, or choose a different name and specify the path in the command-line options.
## BioInsight Platform Core with Auto-launch: Sample Sheet Requirements
Refer to the following requirements to create sample sheets for running the analysis on Platform Core with Auto-launch. For sample sheet requirements common between deployments see [Standard Sample Sheet Requirements](#standard-sample-sheet-requirements). Samples sheets can be created using BaseSpace Run Planning Tool or manually by downloading and editing a sample sheet template
### **\[Cloud\_TSO500S\_Data] Section**
Refer to [\[TSO500\_Data\] Section](#tso-500-data) for this section's requirements.
### **\[Cloud\_TSO500S\_Settings] Section**
Parameters
Required
Details
SoftwareVersion
Not Required
The TSO500S software version
StartsFromFastq
Required
Set the value to TRUE or FALSE. To auto-launch from BCL files, set to FALSE.
### \[Cloud\_Data] Section
Parameters
Required
Details
Sample_ID
Not Required
The same sample ID used in the Cloud_TSO500S_Data section.
ProjectName
Not Required
The BaseSpace project name.
LibraryName
Not Required
Combination of sample ID and index values in the following format: sampleID_Index_Index2
LibraryPrepKitName
Not Required
The Library Prep Kit used.
IndexAdapterKitName
Not Required
The Index Adapter Kit used.
### \[Cloud\_Settings] Section
Parameter
Required
Details
GeneratedVersion
Not Required
The cloud GSS version used to create the sample sheet. Optional if manually updating a sample sheet.
CloudWorkflow
Not Required
Ica_workflow_1
Cloud_TSO500_Pipeline
Required
This value is a universal record number (URN). The valid values are:
The value is a URN in the following format: urn:ilmn:ica:pipeline: <pipeline-ID>#<pipeline-name>
# Sample Sheet Creation in BaseSpace Run Planning tool
## How to Create TSO 500 Sample Sheets in BaseSpace Run Planning tool
The BaseSpace Sequence Hub Run Planning tool is available and is used to generate a valid sample sheet in v2 format for use on a TSO 500 supported sequencer for both BioInsight Platform Core (formerly ICA) and Standalone DRAGEN Server analysis options. Filling out the form on the user interface will produce a exportable sample sheet with the required fields filled in. Refer to [Platform Core Auto-launch Sample Sheet Requirements](/dragen-tso-500-guides/dragen-tso-500-v2.5/run-planning/sample-sheet-requirements#ica-with-auto-launch-sample-sheet-requirements) for descriptions of fields that appear in Platform Core sample sheets.
The sections below represent each step in the BaseSpace Run Planning tool.
#### Step 1: Run Settings
Parameter Name
Required
Description
Run Name
Required
Run Name can contain 255 alphanumeric characters, dashes, underscores, periods, and spaces; and must start with an alphanumeric, a dash or an underscore.
Run Description
Optional
Run Description can contain 255 characters except square brackets, asterisks, and commas.
Instrument Platform
Required
Choose from TSO 500 supported instruments:
NextSeq 500/550
NovaSeq 6000/6000Dx
Secondary Analysis
Required
BaseSpace/Platform Core (to generate sample sheet for cloud analysis)
Local
Sample Container ID
Optional
Unique Identifier for the container that holds the sample
#### Step 3: Sample Settings
Users can manually enter sample information, or download a template file to bulk upload sample information. Users can import the completed template or a compatible sample sheet.
Parameter Name
Required
Description
Read Lengths: Read 1 and Read 2
Required
Auto filled with the standard values, but can be optionally overwritten.
Lane Usage
Optional
Checkbox allows users to apply the same lane across samples.
Lane
Required if Lane Usage is unchecked
Specify lanes for each sample. The unmarked checkbox at the top of the dropdown selects all lanes.
Pair ID
Required
The identifier used to pair DNA and RNA samples in a run. The field is mandatory whether a sample is part of a pair, or not.
To note: The Sample ID field in the generated samplesheet will be auto-filled based on the Pair ID values captured. “_dna” and “_rna” (for DNA and RNA samples respectively) will be appended to the Pair ID value to create the Sample ID.
DNA Index ID
Required
Index set ID options are based on selected Index Adapter Kit
DNA Sample Feature
Required for TSO 500 HRD
Column appears when TSO 500 HRD application is selected. Enter for HRD enriched DNA Samples
RNA Index ID
Required
Index set ID options are based on selected Index Adapter Kit
Project
Optional
Optional field to describe the associated project
Starts from Fastq
Required
True or False
If auto-launching TSO 500 from BCL files, set the value to False.
#### Step 4: Run Review
Once all details are captured and pass validation, the user can review the details on the Run Review screen. From here they can choose to edit details in previous screens or export the sample sheet. Once completed, press the Cancel button to finish run planning.
**Note**: once leaving this screen, the run and sample sheet will not be accessible.
### Guided Examples
Please review these guided examples of analysis workflows that include a step of setting up a run in BaseSpace Run Planning tool:
* [NovaSeq 6000Dx: TSO 500 Auto-launch Analysis in Cloud](https://help.connected.illumina.com/cross-product-tutorials/autolaunch-novaseqdx-tso500)
* [NextSeq 500/550Dx: TSO 500 and Connected Insights Auto-launch Analysis in Cloud](https://help.connected.illumina.com/cross-product-tutorials/nextseq550-tso500)
# Sample Sheet Templates
Sample Sheet templates for TSO 500 v2.5.x standalone DRAGEN server and Platform Core manual launch analysis can be found below. For auto-launch compatible sample sheets, use BaseSpace Run Planner.
DRAGEN TSO 500 analysis software is compatible with several instruments and assay workflows (standard, XP), each of which have implications for the sample sheet.
Sample sheet templates contain all required fields, including index sequences in the proper orientation for all indexes from a given library prep kit. The templates are provided as a starting point for creating a sample sheet manually when launching analysis on a standalone DRAGEN server or on Platform Core using manual launch.
{% hint style="info" %}
For interactive run planning or to create a sample sheet for Platform Core Auto-launch, use [BaseSpace Run Planner](https://basespace.illumina.com/) to create valid sample sheets for either local or cloud analysis. To set up a run in BaseSpace run planner, refer to [Sample Sheet Creation in BaseSpace Run Planner](/dragen-tso-500-guides/dragen-tso-500-v2.5/run-planning/sample-sheet-creation-in-basespace-run-planning-tool).
{% endhint %}
Users can visit the [Sample Sheet guidelines](/dragen-tso-500-guides/dragen-tso-500-v2.5/run-planning/sample-sheet-requirements) section to learn additional details on required fields and values as they fill-in their sample information. Use the lookup table below to select and download the sample sheet template that matches your instrument, assay, and workflow configuration:
\*Lane numbers cannot exceed what is supported by the flow cell in use.
# Launching Analysis
# Analysis Launch on Standalone DRAGEN Server
Start the DRAGEN TruSight Oncology 500 Analysis Software with the `DRAGEN_TSO500.sh` Bash script. The script is installed in the `/usr/local/bin directory`. The Bash script is executed on the command line and runs the software with Docker (or Apptainer if specified).
For arguments, refer to [Command-Line Options](/dragen-tso-500-guides/dragen-tso-500-v2.5/launching-analysis/analysis-launch-on-standalone-dragen-server/command-line-options). You can start from BCL files or from the FASTQ folder produced by BCL Convert. The following requirements apply for both methods:
* Path to the sequencing run or FASTQ folder. Copy the run or FASTQ folder to the DRAGEN server into the staging folder with the following recommended organization: `/staging/runs/{RunID}`. You can copy the run folder onto the DRAGEN server using Linux commands such as `rsync`. The sample sheet within the run folder is used unless otherwise specified through the command line.
* Run folder must be intact. Refer to [Starting from BCL Files](/dragen-tso-500-guides/dragen-tso-500-v2.5/launching-analysis/analysis-launch-on-standalone-dragen-server/command-line-options#starting-from-bcl-files) for input requirements.
* If the analysis output folder path is different from the default, provide the analysis output folder path. Refer to [Command-Line Options](/dragen-tso-500-guides/dragen-tso-500-v2.5/launching-analysis/analysis-launch-on-standalone-dragen-server/command-line-options).
{% hint style="info" %}
Before running the analysis, confirm that the output directory for the software to write to is empty and does not include results of previous analyses.
{% endhint %}
### Storage Requirements
For optimal performance, run analysis on data stored locally on the DRAGEN server. Analysis of data stored on NAS can take longer and performance can be less reliable.
The DRAGEN server provides an NVMe SSD in the /staging directory to use as the software output directory. Network-attached storage is required for long-term storage.
When running the DRAGEN TruSight Oncology 500 Analysis Software, use the default settings or set the -analysisFolder command line option to a directory in /staging to make sure the DRAGEN server processes read and write data on the NVMe SSD.
Before beginning analysis, develop a strategy to copy data from the DRAGEN server to a network‑attached storage. Delete output data on the DRAGEN server as soon as possible.
The following are the run and analysis output sizes for each sequencing system per 101 bp:
| Sequencing System | Run Folder Output (Gb) | Analysis Output (Gb) | Minimum Disk Space (Gb) |
| ---------------------------------------- | ---------------------- | -------------------- | ----------------------- |
| NextSeq 500/550/550Dx (RUO) HO flow cell | 32-55 | 82-85 | 150 |
| NovaSeq 6000/6000Dx (RUO) SP Flow Cell | 85-100 | 250-374 | 300 |
| NovaSeq 6000/6000Dx (RUO) S1 Flow Cell | 164-200 | 360-665 | 800 |
| NovaSeq 6000/6000Dx (RUO) S2 Flow Cell | 290-460 | 890-1600 | 1500 |
| NovaSeq 6000/6000Dx (RUO) S4 Flow Cell | 800-1200 | 2700-4100 | 3000 |
| NovaSeq X 1.5B | 213 | 352 | 800 |
| NovaSeq X 10B | 1100 | 1800 | 3000 |
| NovaSeq X 25B | 1800 | 3300 | 4000 |
| NextSeq 1000/2000 | 41 | 107 | 150 |
When launching the analysis, the software checks that the minimum disk space required is available. If the minimum disk space is not available, the software shows an error message and prevents analysis from starting. If disk space is exhausted during a run, the run shows an error and stops analyzing.
{% hint style="warning" %}
Moving or modifying files during an analysis may cause the analysis to fail or provide incorrect results.
{% endhint %}
# Command-Line Options
You can use the following command-line options with DRAGEN TruSight Oncology 500 Analysis Software.
To learn more about the input requirements, use the `--help` command-line option.
Option
Required
Description
--help
No
Displays a help screen with available command line options.
--analysisFolder
No
Path to the local analysis folder. The default location is /staging/DRAGEN_TSO500_Analysis_{timestamp}. If not using the default location, provide the full path to the local analysis folder. Folder must have sufficient space and must be on an NVMe SSD drive. For example, the /staging directory on the DRAGEN server. Refer to table in Storage Requirements for minimum disk space requirements.
--resourcesFolder
No
Path to the resource folder location. The default location is /staging/illumina/DRAGEN_TSO500/resources. If not using the default location, enter the full path to the resource folder.
--runFolder
Yes
Required when --fastqFolder is not specified. Provide the full path to the local run folder.
--fastqFolder
Yes
Required when --runFolder is not specified. Provide the full path to the local FASTQ folder. Analysis starts at this location.
--user
No
Optional for Docker. Specify the user ID to be used within the Docker container.
--version
No
Displays the version of the software.
--sampleSheet
No
Provide the full path, including file name, if not provided as SampleSheet.csv in the run folder
--sampleOrPairIDs
No
Provide the comma-delimited sample or pair IDs that should be processed on this node with no spaces. For example, Pair_1,Pair_2,Sample_1.
--demultiplexOnly
No
Demultiplex to generate FASTQ only without additional analysis.
--gather
No
Follow this option for any directories with results that should be gathered into a single Results folder.
--hashtableFolder
No
Defaults to the DRAGEN hash table location created upon install. If not using the default location, enter the hash table location.
Note:
* Use full paths when specifying the file paths in the command line.
* Avoid special characters such as &, \*, #, and spaces.
* When starting from BCL files, only the run folder needs to be specified. The immediate parent directory containing the BCL files does not need to be specified.
When running the analysis software using SSH, Illumina recommends using additional software to prevent unexpected termination of analysis. Illumina recommends `screen` and `tmux`.
1. Wait for any running DRAGEN TruSight Oncology 500 Analysis Software containers to complete before launching a new analysis. Run the following command to generate a list of running containers:`docker ps`
2. Select from one of the following options:
* Start from BCL files in the run folder with the sample sheet included in the run folder.\
`DRAGEN_TSO500.sh \`\
`--runFolder /staging/{RunFolderName} \`\
`--analysisFolder /staging/{AnalysisFolderName}`
* Start from BCL files in the run folder with the sample sheet located in a folder other than the run folder.\
`DRAGEN_TSO500.sh \`\
`--runFolder /staging/{RunFolderName} \`\
`--analysisFolder /staging/{AnalysisFolderName} \`\
`--sampleSheet /staging/{SampleSheetName}.csv`
* Start from BCL files in the run folder with a different sample sheet and demultiplexing only.\
`DRAGEN_TSO500.sh \`\
`--runFolder /staging/{RunFolderName} \`\
`--analysisFolder /staging/{AnalysisFolderName} \`\
`--sampleSheet /staging/{SampleSheetName}.csv \`\
`--demultiplexOnly`
* Start from FASTQ with the sample sheet included in the FASTQ folder and with different resources and hash table folders.\
`DRAGEN_TSO500.sh \`\
`--resourcesFolder /staging/illumina/DRAGEN_TSO500/resources \`\
`--hashtableFolder /staging/illumina/DRAGEN_TSO500/ref_hashtable \`\
`--fastqFolder /staging/{FastqFolderName} \`\
`--analysisFolder /staging/{AnalysisFolderName}`
* Start from FASTQ folder with sample sheet included in the FASTQ folder and subset of samples or pairs.\
`DRAGEN_TSO500.sh \`\
`--fastqFolder /staging/{FastqFolderName} \`\
`--analysisFolder /staging/{AnalysisFolderName} \`\
`--sampleOrPairIDs "Pair_1,Pair2"`
## Starting from BCL Files
{% hint style="info" %}
For the data generated by NextSeq 1000/2000 and NextSeq X, the analysis can only be started from FASTQs and not from BCLs.
{% endhint %}
If starting from BCL (\*.bcl) files, DRAGEN TruSight Oncology 500 Analysis Software requires the run folder to contain certain files and folders. These inputs are required for Docker.
The run folder contains data from the sequencing run, make sure that the folder contains the following files:
Folder/File
Description
Config folder
Configuration files
Data folder
*.bcl files
Images folder
[Optional] Raw sequencing image files.
Interop folder
Interop metric files.
Logs folder
[Optional] Sequencing system log files.
RTALogs folder
Real-Time Analysis (RTA) log files.
RunInfo.xml file
Run information.
RunParameters.xml file
Run parameters.
SampleSheet.csv file
Sample information. If you want to use a sample sheet that is not in the run folder or a sample sheet named something other than SampleSheet.csv, provide the full path.
## Starting from FASTQ Files
The following inputs are required for running the DRAGEN TruSight Oncology 500 Analysis Software using FASTQ (\*.fastq) files. The requirements apply to Docker.
* Full path to an existing FASTQ folder.
* The FASTQ folder structure conforms to the folder structure in [FASTQ File Organization.](#fastq-file-organization)
* The sample sheet is in the FASTQ folder path, or you can set the path to the sample sheet with the `--sampleSheet` override command line option.
Make sure there is sufficient disk space for the analysis to complete. Refer to the `--help` command line argument details for disk space requirements.
{% hint style="info" %}
Use BCL Convert to produce FASTQ files for DRAGEN TruSight Oncology 500 Analysis Software. Using bcl2fastq does not produce the same results and is discouraged.
{% endhint %}
{% hint style="info" %}
Make sure that BCL Convert is set to write UMI sequences to the read headers in the FASTQ files.
{% endhint %}
### FASTQ File Organization
Store FASTQ files in individual subfolders that correspond to a specific Sample\_ID. Keep file pairs together in the same folder. Alternatively, store the FASTQ files in one flat folder structure where the FASTQ files are stored in one folder.
The DRAGEN TruSight Oncology 500 Analysis Software requires separate FASTQ files per sample. Do not merge FASTQ files.
The instrument generates two FASTQ files per flow cell lane, so that there are eight FASTQ files per sample.
`Sample1_S1_L001_R1_001.fastq.gz`
* Sample1 represents the Sample ID.
* The S in S1 means sample, and the 1 in S1 is based on the order of samples in the sample sheet, so S1 is the first sample.
* L001 represents the flow cell lane number.
* The R in R1 means Read, so R1 refers to Read 1.
# Run on Multiple DRAGEN Servers
DRAGEN TruSight Oncology 500 Analysis Software can be used to run a subset of samples on different DRAGEN servers to decrease overall processing time. This is possible using a three stage process called scatter/gather, which consists of demultiplexing, analysis, and result gathering.
The first stage is demultiplexing. Demultiplexing runs once on the entire run folder, generates FASTQ files for each sample in the run, and then separates sample files into respective folders. Once complete, note the output directory containing the sample directories holding the FASTQ files.
The process for scattering the analysis on multiple DRAGEN servers is as follows:
1. Determine how many DRAGEN servers are available to run.
2. Run demultiplexing on a single DRAGEN server.
{% hint style="warning" %}
Moving or modifying files during an analysis may cause the analysis to fail or provide incorrect results.
{% endhint %}
{% hint style="info" %}
To sequence runs on multiple DRAGEN servers using the NovaSeq 6000 XP workflow, modify the sample sheet to include a subset of the lanes. For example, on an S2 flowcell, create two modified sample sheets with one containing the samples from lane 1 and the other from lane 2. This allows only the sample sheet to be modified instead of copying files between servers. This strategy would use the start from Run Folder commands without the `--demultiplexOnly` option. The entire run folder would need to be copied to each analysis server as demultiplexing is performed once per server.
{% endhint %}
3. Transfer the FASTQ folder output from the original DRAGEN server to additional servers.
1. `Logs_Intermediates/FastqGeneration.`
4. Run analysis software using the `--fastqFolder` option on both the original and additional DRAGEN servers.
* Option 1 Copy the original `SampleSheet.csv` to each server. Then provide a subsetted list to the Bash script on each DRAGEN server with the intended samples/pairs to run.
* Option 2 Copy and modify the `SampleSheet.csv` to each DRAGEN server to only contain the list of samples/pairs to run.\
\
The software verifies that all samples in the sample sheet are contained within the FASTQ folders unless the `--sampleOrPairIDs` command-line option is present in the analysis launch. Failure to account for these checks results in an error.
5. Copy the results from demultiplexing and each analysis run onto a single server, and then generate the final `/Results` directory, which contains the aggregated results. Enter the `--gather` command followed by the output directories of the demultiplexing step and each individual analysis run.
## Commands for Multinode Analysis
# Analysis Launch on BioInsight Platform Core
## Methods for Launching Analysis
Illumina BioInsight Platform Core (formerly ICA) supports the following methods for launching DRAGEN TruSight Oncology 500 Analysis Software.
* [Auto-launch](/dragen-tso-500-guides/dragen-tso-500-v2.5/launching-analysis/analysis-launch-on-ica/auto-launch-of-dragen-tso-500-analysis-on-ica)—Stream run data directly from the instrument to Platform Core via a specially configured sample sheet and automatically begin DRAGEN TSO 500 analysis.
* [Manual launch](/dragen-tso-500-guides/dragen-tso-500-v2.5/launching-analysis/analysis-launch-on-ica/manual-launch-of-dragen-tso-500-analysis-on-ica)—Initiate DRAGEN TSO 500 analysis on Platform Core using the run files and sample sheet files in the project.
{% hint style="warning" %}
For the data generated by NextSeq 1000/2000 and NextSeq X, only manual option for launching analysis on Platform Core is available. The analysis can only start from FASTQs files.
{% endhint %}
For more information about using Platform Core or BaseSpace Sequence Hub, refer to the following support pages on the Illumina support site.
* [BioInsight Platform Core support site page](https://help.ica.illumina.com/)
* [BaseSpace Sequence Hub support site page](https://help.basespace.illumina.com/)
# Auto-Launch of DRAGEN TSO 500 Analysis on BioInsight Platform Core
## Auto-launch Prerequisites and Workflow
\*The BaseSpace Sequence Hub setting for run monitoring and storage must be selected on the instrument to use DRAGEN TSO 500 analysis auto-launch. For information on preparing your instrument for DRAGEN TSO 500 Auto-launch, refer to the documentation for your instrument.
1. Use BaseSpace Sequence Hub Run Planning tool or the sample sheet templates provided on the support page to create and export a sample sheet.
1. If BaseSpace Run Planning tool is not available in your region, use the sample sheet template.
2. Import the sample sheet to the instrument and start the sequencing run. Refer to [Platform Core Auto-launch Sample Sheet Requirements](/dragen-tso-500-guides/dragen-tso-500-v2.5/run-planning/sample-sheet-requirements#ica-with-auto-launch-sample-sheet-requirements) for sample sheet guidance.
1. Data is uploaded to BaseSpace Sequence Hub and then pushed to Platform Core. You can monitor the run in BaseSpace Sequence Hub.
2. Analysis auto launches in Platform Core when sequencing and the upload completes. You can monitor the status of the analysis in BaseSpace Sequence Hub or Platform Core
3. If necessary, you can requeue the analysis via BaseSpace Sequence Hub.
3. View the analysis output results in either BaseSpace Sequence Hub or Platform Core.
{% hint style="warning" %}
To avoid invalid sample sheet configurations, Illumina recommends using BaseSpace Run Planning tool to generate sample sheets. Using an invalid sample sheet can result in failed runs and analyses.
{% endhint %}
{% hint style="warning" %}
For the data generated by NextSeq 1000/2000 and NextSeq X, only manual option for launching analysis on Platform Core is available. The analysis can only start from FASTQs files.
{% endhint %}
## BaseSpace Sequence Hub Requirements for Platform Core Auto-Launch
BaseSpace Run Planning tool is a multi-step workflow that generates a manual launch or auto-launch capable sample sheet for export and requires the following additional settings:
* Access to BaseSpace Sequence Hub.
* Platform Core Run Storage is enabled under BaseSpace Sequence Hub settings.
Refer to the[ ](https://support.illumina.com/sequencing/sequencing_software/basespace.html)[BaseSpace Sequence Hub support site page](https://help.basespace.illumina.com/) for information on setting up a BaseSpace Sequence Hub project.
## Requeue Analysis
You can requeue analysis of a run via the run's Summary page in BaseSpace Sequence Hub.
Refer to the [BaseSpace Sequence Hub support site page](https://help.basespace.illumina.com/) for more information on requeuing an analysis.
## Minimum Storage Requirements on Platform Core
Sequencing System
Minimum Disk Space (Gb)
NextSeq 500/550/550Dx (RUO) HO flow cell
350
NovaSeq 6000/6000Dx (RUO) SP Flow Cell
500
NovaSeq 6000/6000Dx (RUO) S1 Flow Cell
1100
NovaSeq 6000/6000Dx (RUO) S2 Flow Cell
2500
NovaSeq 6000/6000Dx (RUO) S4 Flow Cell
4300
NovaSeq X 1.5B
2000
NovaSeq X 10B
4300
NovaSeq X 25B
8400
NextSeq 1000/2000
350
Refer to the [Software Registration page](https://help.connected.illumina.com/account-management/rg-registration) for information on how to manage accounts and subscriptions.
### Guided Examples
Please review these guided examples of using DRAGEN TSO 500 Analysis Software with auto-launch on Platform Core:
* [NovaSeq 6000Dx: TSO 500 Auto-launch Analysis in Cloud](https://help.connected.illumina.com/cross-product-tutorials/autolaunch-novaseqdx-tso500)
* [NextSeq 500/550Dx: TSO 500 and Connected Insights Auto-launch Analysis in Cloud](https://help.connected.illumina.com/cross-product-tutorials/nextseq550-tso500)
# Manual Launch of DRAGEN TSO 500 Analysis on Platform Core
## How to Launch Analysis
1. **Create a Project:** Project can be specific for the DRAGEN TruSight Oncology 500 pipeline or it can contain multiple Pipelines and/or Tools). For information on creating Projects, refer to the Projects section in [Illumina BioInsight Platform Core help](https://help.ica.illumina.com/home/h-projects).
{% hint style="info" %}
BioInsight Platform Core (formerly ICA) standard storage is used by default as soon as the Project is saved. To connect a different storage source, set it up before creating your Project. For details and options, refer to the Storage section in [Illumina BioInsight Platform Core help](http://help.ica.illumina.com/home/h-storage).
{% endhint %}
2. **Edit Project and Add Bundle:** Edit the Project and add the bundle titled, "DRAGEN TSO 500 v2.5.2 (XX)." XX is a 2-letter code designating the region from which you are launching the analysis. Adding the Bundle automatically adds the pipeline and associated resource files and datasets to the Project. For information on Bundles, refer to the Bundles section in [Illumina BioInsight Platform Core help](https://help.ica.illumina.com/home/h-bundles).
{% hint style="info" %}
After adding the Bundle to the Project, an example dataset becomes available in the Demo\_Data folder for the Project.
{% endhint %}
2. **Upload the sequencing data:** For information on viewing and uploading data, refer to the Data section in [Illumina BioInsight Platform Core help](https://help.ica.illumina.com/project/p-data).
3. **Start Analysis:** In the Project, navigate to Pipelines, desired TSO 500 Pipeline, and then select "Start New Analysis". Set up the new analysis by configuring the parameters listed in the [table below](#analysis-parameters-on-ica). When the required files are completed, start analysis.
4. **Download Results:** After analysis is complete, navigate to results in the configured output location.
Please see the Illumina Support Shorts for guidance on how to set up and run DRAGEN TSO 500 RUO analysis on Platform Core.
{% embed url="" %}
## Analysis Parameters on BioInsight Platform Core
To launch an analysis via the Platform Core user interface, configure a DRAGEN TSO 500 pipeline analysis with the following parameters.
Parameter Name
Description
User Reference
The analysis run name.
User Tags
Text labels to help index the analysis.
Notify me when task is completed
Option to receive an email notification when analysis is complete.
Output Folder
The path to the analysis output folder. The default path is the project output folder.
Entitlement Bundle
Automatically populated from the project details.
Sample Sheet
Select a sample sheet in CSV format for the analysis.
To note: Sample Sheet selection is optional if starting from a run folder, and required when submitting a FASTQ folder.
Input Folder
The run folder or FASTQ folder that contains files to analyze.
Starts from FASTQ
True for analysis performed on files in the FASTQ folder. False for analysis performed on files in the run folder.
Sample or Pair IDs
Optional subset of Sample IDs or Pair IDs to analyze.
Storage Size
The storage size to allocate for the analysis. The default and recommended value is Large.
## **Known Limitations**
* FASTQ Folder Naming Requirements
* When specifying input FASTQ folder names, avoid using folder names that consist entirely of numeric characters with a leading zero, as this will cause the software to error out.
* Unsupported naming pattern:
* '01234' (numeric-only with leading zero)
* Supported naming patterns:
* '12340' (numeric without leading zero)
* 'sample01' (alphanumeric)
* 'A1234' (alphanumeric)
* 'test\_sample' (alphanumeric with underscore)
For information about using pipelines, refer to [Illumina BioInsight Platform Core support site page](https://support.illumina.com/sequencing/sequencing_software/illumina-connected-analytics.html).
# Analysis Output
When the analysis run completes, the DRAGEN TruSight Oncology 500 Analysis Software generates an analysis output folder in a specified location.
To view analysis output, navigate to the analysis output folder and select the files that you want to view.
## Single Node Analysis Output Folder Structure
Single output folder structure is as follows.
* Logs\_Intermediates
* AdditionalSarjMetrics— Contains per pair ID calculations to support the PCT\_TARGET\_250X metric.
* Annotation—Contains outputs for small variant annotation.
* Subfolders per sample ID—Contains the aligned small variants JSON.
* CombinedVariantOutput
* Subfolders per pair ID—Contains the combined variant output TSV files.
* A combined output log file.
* Contamination
* Subfolders per DNA sample ID—Contains the contamination metrics JSON file and output logs.
* DnaDragenCaller
* Subfolders per sample ID—Contains the aligned BAM and index files, small variant VCF and gVCF, copy number variant VCF, MSI JSON, and QC outputs in CSV format.
* DnaDragenExonCNVCaller
* Subfolders per DNA sample ID—Contains the exon-level CNV JSON,the supporting calculation, and the QC files.
* DnaFastqValidation—Contains the FASTQ validation output log for DNA samples.
* FastqDownsample
* Subfolders per RNA sample ID—Contains FASTQ files and output logs.
* FastqDownsample output
* FastqGeneration
* Gis—Contains GIS-related files for HRD samples.
* Subfolders per HRD sample ID—Contains the GIS JSON, the supporting calculation, and the QC files.
* Also contains the annotated CNV VCF and gene level TSV file with absolute copy number and minor copy number information
* LrAnnotation
* Subfolders per DNA sample ID—Contains the annotated exon-level CNV JSON.
* LrCalculator
* Subfolders per DNA sample ID—Contains the exon-level CNV VCF.
* MetricsOutput
* Subfolders per pair ID—Contains the metrics output TSV files.
* A combined output log file.
* ResourceVerification—Contains the resource file checksum verification logs.
* RnaAnnotation
* Subfolders per RNA sample ID—Contains the annotated splice variant JSON.
* RnaDragenCaller
* Subfolders per sample ID—Contains the aligned BAM, fusion candidates CSV and QC outputs in CSV format.
* RnaFastqValidation—Contains the FASTQ validation output log for RNA samples.
* RnaFusion
* Subfolders per RNA sample ID—Contains the All Fusions CSV and Fusion Processor logs.
* RnaQcMetrics
* Subfolders per RNA sample ID—Contains the RNA QC metrics JSON.
* RnaSpliceVariantCalling
* Subfolders per RNA sample ID—Contains the splice variants VCF.
* Run QC—Contains the Run QC metrics JSON, Intermediate Run QC metrics JSON, and log file.
* SampleAnalysisResults
* Subfolders per pair ID—Contains the Sample Analysis Results JSON and detailed log file.
* SampleSheetValidation—Contains the Intermediate sample sheet and validation log.
* Tmb
* Subfolders per DNA sample ID—Contains the TMB metrics CSV, TMB trace TSV, and related files and logs. `passing_sample_steps.json`\
—Contains the steps passed for each sample ID.\
`pipeline_trace.txt`—Contains a summary and troubleshooting file that lists each Nextflow task executed and the status (for example, COMPLETED or FAILED).\
`run.log`—Contains a complete trace-level log file describing the Nextflow pipeline execution.\
`run_report.html`—Contains high-level run statistics (performance, usage, etc.)\
`run_timeline.html` —Contains timeline-related information about the analysis run.
* Results
* Metrics Output TSV (all pair IDs)
* Pair ID—The following outputs are produced for each sample:
* Combined Variant Output TSV
* Metrics Output TSV
* TMB Trace TSV
* Small Variant Genome VCF
* Small Variant Genome Annotated JSON
* Copy Number Variant VCF
* GIS JSON
* MSI JSON
* Large Rearrangements CNV VCF
* Large Rearrangements CNV Annotated JSON
* All Fusion CSV
* Splice Variant VCF
* Splice Variant Annotated JSON
## Multiple Node Analysis Output Folder Structure
Multiple output folder structure is as follows.
* Demultiplex Output
* A Logs\_Intermediates folder containing FASTQ files per sample.
* Node(X) Output—The following outputs are produced for each node used:
* A Logs\_Intermediates folder containing step specific and component specific outputs and logs for every step/component run in the analysis pipeline for the sample run on the node.
* A Results folder containing results only for the sample run on the node.
* Gathered Output
* A Logs\_Intermediates folder containing step specific and component specific outputs and logs for every step/component run in each analysis pipeline on every node—this contains outputs for all samples and pairs ran across all nodes in the analysis.
* A Results folder containing results for all samples and pairs ran across all nodes—results are organized by Pair\_ID, then Sample\_ID. This folder also contains summary files which contain information on all samples.
## BioInsight Platform Core Output Folder Structure
This section describes each output folder generated during analysis and where to find metric and analytic files when the pipeline is executed. The same output folder structure and content exist in BioInsight Platform Core (formerly ICA) and BaseSpace Sequence Hub.
### High-Level Folder Structure
* Run ID
* TSO500\_Nextflow\_logs
* \_manifest.json
* Results
* \_tags.json
* Logs\_intermediates
* Errors—This folder is only present when analysis fails
### TSO500\_Nextflow\_logs Folder Structure
The TSO\_500\_Nextflow\_Logs provides information related to the execution of the pipeline on Platform Core as a whole and for specific nodes (when an analysis is split across multiple nodes). It contains files used to execute parts of the workflow on different nodes as well as records of the nextflow execution on those nodes.
* TSO\_500\_Nextflow\_Logs
* \_manifest.json
### Results Folder Structure
Contains the aggregated MetricsOutput.tsv file at the root level. Additionally, the Results folder contains a subfolder for each pair ID.
* Results
* MetricsOutput.tsv
* Sample\_1
* Sample\_2
* Sample\_<#>
* \_tags.json
The `Results` subfolder contains the following files:
* Results
* MetricsOutput.tsv
* \
* [CombinedVariantOutput.tsv](/dragen-tso-500-guides/dragen-tso-500-v2.5/analysis-output/combined-variant-output)
* \\_MetricsOutput.tsv
* \ see [DNA Outputs](/dragen-tso-500-guides/dragen-tso-500-v2.5/analysis-output/dna-output)
* \ see [RNA Outputs](/dragen-tso-500-guides/dragen-tso-500-v2.5/analysis-output/rna-output)
### Logs\_intermediates Folder Structure
Contains folders for each submodule in the DRAGEN TSO 500 on Platform Core pipeline. The folders contain a copy of all the relevant files required to create the metric output files and report files, as well as the combined log files at the root level and subfolders for each sample.
* Logs\_intermediates
* DnaDragenCaller
* AdditionalSarjMetrics
* CombinedVariantOutput
* FastqGeneration
* MetricsOutput
* DnaDragenExonCnvCaller
* DnaFastqValidation
* Gis
* Tmb
* SampleAnalysisResults
* SampleSheetValidation
* passing\_sample\_steps.json
* RnaFusion
* Contamination
* Annotation
* RnaAnnotation
* RnaDragenCaller
* RnaSpliceVariantCalling
* RunQc
* FastqDownsample
* PassingSampleSteps
* ResourceVerification
* LrCalculator
* LrAnnotation
* RnaQcMetrics
* RnaFastqValidation
### Errors Folder Structure
Contains Errors.tsv. This file contains the summary of all the errors encountered during pipeline execution.
* Errors
* Errors.tsv
# DNA Output
Refer to [DNA Analysis Methods](/dragen-tso-500-guides/dragen-tso-500-v2.5/analysis-methods/dna-analysis-methods) for more information.
## Small Variant gVCF
File name: `{SAMPLE_ID}_hard-filtered.gvcf.gz`
The small variant genome variant call file contains information on all candidate small variants evaluated, including complex variants up to 15 bp from phased variant calling across the entire TSO 500 panel.
The variant status is determined by the FILTER column in the genome VCF as follows.
| Filter | Note |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| PASS | PASS variants. |
| base\_quality | Site filtered because median base quality of alt reads at this locus does not meet threshold. |
| filtered\_reads | Site filtered because the fraction of reads is too large. |
| fragment\_length | Site filtered because absolute difference between the median fragment length of alt reads and median fragment length of ref reads at this locus exceeds threshold. |
| low\_depth | Site filtered because the read depth is too low. |
| low\_frac\_info\_reads | Site filtered because the fraction of informative reads is below threshold. |
| long\_indel | Site filtered because the indel length is too long. |
| mapping\_quality | Site filtered because median mapping quality of alt reads at this locus does not meet threshold. |
| multiallelic | Site filtered because more than two alt alleles pass tumor LOD. |
| no\_reliable\_supporting\_read | Site filtered because no reliable supporting somatic read exists. |
| read\_position | Site filtered because median of distances between start/end of read and this locus is below threshold. |
| str\_contraction | Site filtered due to suspected PCR error where the alt allele is one repeat unit less than the reference. |
| too\_few\_supporting\_reads | Site filtered because there are too few supporting reads in the tumor sample. |
| weak\_evidence | Somatic variant score (SQ) does not meet threshold. |
| systematic\_noise | Site filtered based on evidence of systematic noise in normal sample. |
| excluded\_regions | Site overlaps with VC excluded regions bed. |
## Small Variant Annotated JSON
File name: `{SAMPLE_ID}_DNAVariants_Annotated.json.gz`
The small variants annotated file provides variant annotation information for all nonreference positions from the genome VCF including pass and nonpass variants.
## TMB Trace
The TMB trace file provides comprehensive information on how the TMB value is calculated for a given sample. All passing small variants from the small variant filtering step are included in this file. To calculate the numerator of the TmbPerMb value in the TMB JSON, set the TSV file filter to use the IncludedInTMBNumerator with a value of True.
The TMB trace file is not intended to be used for variant inspections. The filtering statuses are exclusively set for TMB calculation purposes. Setting a filter does not translate into the classification of a variant as somatic or germline.
| Column | Description |
| ------------------------ | ---------------------------------------------------------------------------------- |
| Chromosome | Chromosome |
| Position | Position of variant |
| RefCall | Reference base |
| AltCall | Alternate base |
| VAF | Variant allele frequency |
| Depth | Coverage of position |
| CytoBand | Cytoband of variant |
| GeneName | Name of gene if applicable. A semicolon delimited list is used for multiple genes. |
| VariantType | Type of the variant: SNV, insertion, deletion, MNV |
| CosmicIDs | Cosmic IDs, if multiple concatenated by “;” |
| MaxCosmicCount | Maximum Cosmic study count |
| AlleleCountsGnomadExome | Variant allele count in gnomAD exome database |
| AlleleCountsGnomadGenome | Variant allele count in gnomAD genome database |
| AlleleCounts1000Genomes | Variant allele count in 1000 genomes database |
| MaxDatabaseAlleleCounts | Maximum variant allele count over the three databases |
| GermlineFilterDatabase | TRUE if variant was filtered by the database filter |
| GermlineFilterProxi | TRUE if variant was filtered by the proxi filter |
| CodingVariant | TRUE if variant is in the coding region |
| Nonsynonymous | TRUE if variant has any transcript annotations with nonsynonymous consequences |
| IncludedinTMBNumerator | TRUE if variant is used in the TMB calculation |
## Copy Number VCF
The copy number VCF file contains CNV calls for DNA libraries of the amplification genes targeted by DRAGEN TruSight Oncology 500 Analysis Software. The CNV call indicates fold change results for each gene classified as reference, deletion, or amplification.
The value in the QUAL column of the VCF is a Phred transformation of the p-value where Q=-10xlog10(p-value). The p-value is derived from the t-test between the fold change of the gene against the rest of the genome. Higher Q-scores indicate higher confidence in the CNV call.
In the VCF notation, \ indicates the detected fold change (FC) is greater than a predefined amplification cutoff. \ indicates the detected FC is less than a predefined deletion cutoff for that gene. This cutoff can vary from gene to gene.
{% hint style="info" %}
In analysis versions prior to v2.5, \ calls in the VCF are marked as LowValidation. The LowValidation filter indicates that the calls have been validated only with in silico data sets and are provided as information only.
{% endhint %}
Each copy number variant is reported as a fold change on normalized read depth in a testing sample relative to the normalized read depth in diploid genomes. Given tumor purity, you can infer the ploidy of a gene in the sample from the reported fold change.
Given tumor purity X%, for a reported fold change Y, you can calculate the copy number n using the following equation (with a diploid assumption):
$$
n=\[(200Y)-2(100-X)]/X
$$
For example, a tumor purity at 30% and a MET with fold change of 2.2x indicates that 10 copies of MET DNA are observed.
# HRD and GIS Outputs
The Illumina DRAGEN TruSight Oncology 500 Analysis Software allows for analysis of sequencing data generated from the TruSight Oncology 500 HRD assay. When HRD samples are analyzed new results and metrics are included in the CombinedVariantOutput and MetricsOutput files respectively. The following tables detail how these scores and QC metrics are derived.
| Metric | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Genomic Instability Score (GIS) |
Proprietary Genomic Instability Score (GIS) indicating level of genomic instability in sample genome. Combination of Loss of Heterozygosity (LOH), Telomeric allelic imbalance and Large-scale State Transitions (LST) scores.
The GIS scores provided by TruSight Oncology 500 HRD show good correlation (R2= 0.98) with Myriad Genetics GIS however they are not identical (Refer to TruSight Oncology 500 HRD Product Data Sheet Doc# M-GL-00748 for more details). GIS from alternative HRD assays should be not be considered equivalent to Illumina/Myriad GIS.
|
{% hint style="warning" %}
The GIS algorithm within the TSO500 pipeline (which does not have a cell line mode due to the TSO500 pipeline being non-configurable) is only intended for FFPE samples. Cell line samples will not accurately report GIS results as the tumor fraction (>90%) is too high to reliably distinguish tumor vs germline variants.
{% endhint %}
### HRD Metrics Included in Metrics Output File
| Metric | Description | Section in Metrics Output |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
| PCT\_TARGET\_HRD\_50X | Percent of HRD probe SNP panel covered by at least 50X coverage | DNA Library QC Metrics for GIS |
| EXCESSIVE\_TF | EXCESSIVE TF indicates if there is excessive tumor content in sample. Troubleshooting: Samples with pure tumor fraction >90% are outside the design for GIS estimation (this includes pure tumor cell lines) | DNA Library QC Metrics for GIS |
| ALLELE\_DOSAGE\_RATIO | Proprietary Myriad Genetics estimate of b-allele dosage based on b-allele noise/signal ratio. B-Allele noise is correlated with coverage; lower coverage samples will have higher noise. B-allele signal is also correlated with tumor fraction; a higher tumor fraction produces a higher signal for b-allele sites. Samples with lower tumor fraction and higher amount of noise (or lower coverage) will have higher Allele Dosage Ratio. The upper limit of the score is 50, therefore any sample with 50 Allele Dosage Ratio can be assumed to have tumor fraction close to zero and typically has a GIS = 0. | DNA Expanded Metrics |
| MEDIAN\_TARGET\_HRD\_COVERAGE | Median target fragment coverage across all target positions in the genome. Coverage is the total number of non-duplicate pair alignments that overlap. | DNA Expanded Metrics |
# RNA Output
Refer to [RNA Analysis Methods](/dragen-tso-500-guides/dragen-tso-500-v2.5/analysis-methods/rna-analysis-methods) for more information.
## Splice Variant VCF
The splice variant VCF contains all candidate splice variants targeted by the analysis panel identified by the RNA analysis pipeline. You can apply the following filters for each variant call:
| Filter Name | Description |
| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
| LowQ | Splice variant score < passing quality score threshold value of 1. |
| PASS | Splice variant score ≥ passing quality score threshold value of 1. |
| LowUniqueAlignments | All splice junction supporting reads map to a unique genomic interval near at least one of the two splice sites. |
Refer to the headers in the output for more information about each column.
## Splice Variant Annotated JSON
If available, each splice variant is annotated using the Illumina Annotation Engine. The following information is captured in the JSON:
* HGNC Gene
* Transcript
* Exons
* Introns
* Canonical
* Consequence
## All Fusions CSV
The all fusions CSV file contains all candidate fusions identified by the DRAGEN RNA pipeline. Two output columns in the file describe the candidate fusions: Filter and KeepFusion.
The following table describes the semicolon-separated output found in the Filter columns. The output is either a confidence filter or information only as indicated. If none of the confidence filters are triggered, the Filter column contains the output PASS, else it contains the output FAIL.
Filter Column Output
| Filter | Filter Type | Description |
| -------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DOUBLE\_BROKEN\_EXON | Confidence filter | If both breakpoints are distant from annotated exon boundaries, the number of supporting reads do not satisfy a high threshold requirement (≥ 10 supporting reads). |
| LOW\_MAPQ | Confidence filter | All fusion supporting read alignments at either of the breakpoints have MAPQ < 20. |
| LOW\_UNIQUE\_ALIGNMENTS | Confidence filter | All fusion supporting read alignments map to a unique genomic interval at either of the breakpoints. |
| LOW\_SCORE | Confidence filter | The fusion candidate has probabilistic score as determined by the features of the candidate. |
| MIN\_SUPPORT | Confidence filter | The fusion candidate has very few fusion supporting reads (< 5 supporting read pairs). |
| READ\_THROUGH | Confidence filter | The breakpoints are cis neighbors (< 200 kbp) on the reference genome. |
| ANCHOR\_SUPPORT | Information only | Read alignments of fusion supporting reads are not long enough (12 bp) at either of the two breakpoints. |
| HOMOLOGOUS | Information only | The candidate is likely a false candidate generated because the two genes involved have high gene homology. |
| LOW\_ALT\_TO\_REF | Information only | The number of fusion supporting reads is < 1% of the number of reads supporting the reference transcript at either of the two breakpoints. |
| LOW\_GENE\_COVERAGE | Information only | Each breakpoint in an enriched gene has fewer than 125 bp with nonzero read coverage. |
| NO\_COMPLETE\_SPLIT\_READS | Confidence filter | For every fusion-supporting split read, the total number of aligned bases across two breakpoints is less 60% of the read length. |
| UNENRICHED\_GENE | Confidence filter | Neither of the two parent genes is in the enrichment panel. |
The KeepFusion column of the output has a value of TRUE when none of the confidence filters are triggered.
Refer to the headers in the output for more information about each column.
Fusion Columns
| Fusion Object Field | Source |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Gene A | The gene associated with the A side of the fusion. A semicolon delimited list is used for multiple genes. |
| Gene B | The gene associated with the B side of the fusion. A semicolon delimited list is used for multiple genes. |
| Gene A Breakpoint | \[Information only] The chromosome and offset of the Gene A side of the fusion. |
| Gene A Location |
Location of the breakpoint within Gene A: - IntactExon—Matches exon boundary - BrokenExon—Inside an exon - Intronic—Within an intron - Intergenic—No gene overlap (currently excluded) If multiple genes are in Gene A, then semicolon separated list of locations. This column is used internally to identify genes to report when a breakpoint occurs in a region overlapping multiple genes. Occasionally, additional values are listed for genes that were excluded from the GeneA list.
|
| Gene A Sense | Boolean indicating whether left/right breakpoint order suggests fusion transcript is in the same sense of Gene A. If multiple genes are in Gene A, then semicolon separated list of bools. |
| Gene A Strand | Strand of Gene A, + for forward, - for reverse. |
| Gene B Breakpoint | \[Information only] The chromosome and offset of the Gene B side of the fusion. |
| Gene B Location |
Location of the breakpoint within Gene B: - IntactExon—Matches exon boundary - BrokenExon—Inside an exon - Intronic—Within an intron - Intergenic—No gene overlap (currently excluded) If multiple genes in Gene B, then semicolon separated list of locations. This column is used internally to identify genes to report when a breakpoint occurs in a region overlapping multiple genes. Occasionally, additional values are listed for genes that were excluded from the GeneB list.
|
| Gene B Sense | Boolean indicating whether left/right breakpoint order suggests fusion transcript is in the same sense of Gene B. If multiple genes are in Gene B, then semicolon separated list of bools. |
| Gene B Strand | Strand of Gene B, + for forward, - for reverse. |
| Score | The quality of fusion as determined by DRAGEN server. |
| Filter | The filter associated with the fusion as determined by the respective caller. Results from different callers are not equivalent. |
| Ref A Dedup | Gene A uniquely mapping reads paired across or split by the junction. Does not support fusion. Duplicate reads are not included. |
| Ref B Dedup | Gene B uniquely mapping reads paired across or split by the junction. Does not support fusion. Duplicate reads are not included. |
| Alt Split Dedup | Uniquely mapping reads split by the junction. Supports fusion. Duplicate reads are not included. |
| Alt Pair Dedup | Uniquely mapping reads paired across junction. Supports fusion. Duplicate reads are not included. |
| KeepFusion | The determination whether the fusion should be kept or dropped from the list of fusions. |
| Fusion Directionality Known | Whether fusion directionality is known and indicated by gene order. |
When using Microsoft Excel to view this report, genes that are convertible to dates (such as MARCH1 automatically convert to dd-mm format (1 Mar) by Excel. The following are fusion allow list genes:
* ABL1
* AKT3
* ALK
* AR
* AXL
* BCL2
* BRAF
* BRCA1
* BRCA2
* CDK4
* CSF1R
* EGFR
* EML4
* ERBB2
* ERG
* ESR1
* ETS1
* ETV1
* ETV4
* ETV5
* EWSR1
* FGFR1
* FGFR2
* FGFR3
* FGFR4
* FLI1
* FLT1
* FLT3
* JAK2
* KDR
* KIF5B
* KIT
* KMT2A
* MET
* MLLT3
* MSH2
* MYC
* NOTCH1
* NOTCH2
* NOTCH3
* NRG1
* NTRK1
* NTRK2
* NTRK3
* PAX3
* PAX7
* PDGFRA
* PDGFRB
* PIK3CA
* PPARG
* RAF1
* RET
* ROS1
* RPS6KB1
* TMPRSS2
# Combined Variant Output
File name: `{Pair_ID}_CombinedVariantOutput.tsv`
The combined variant output file contains the variants and biomarkers in a single file that is based on a single sample. If using pair ID, the file is based on paired DNA and RNA samples from the same individual. The output contains the following variant types and biomarkers:
* Small variants
* Copy number variants (CNV) (with absolute copy number when HRD Assay is run)
* TMB
* MSI
* Fusions
* Splice variants
* GIS (when HRD Assay is run)
* Gene-level Loss of Heterozygosity (when HRD Assay is run)
* Exon-level CNVs
The combined variant output file also contains Analysis Details and Sequencing Run Details sections. The details of each are listed in the following table:
| Analysis Details | Sequencing Run Details |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
- Pair ID - DNA sample ID (if DNA is run) - RNA sample ID (if RNA is run) - Output date - Output time - Module version - Pipeline version (Docker image version #)
|
- Run name - Run date - DNA sample index ID (if DNA is run) - RNA sample index ID (if RNA is run) - \[HRD] Sample feature - Instrument ID - Instrument control software version - Instrument type - RTA version - Reagent cartridge lot number
|
Combined variant output produces small variants with blank fields in the following situations:
* The variant has been matched to a canonical RefSeq transcript on an overlapping gene not targeted by TruSight Oncology 500.
* The variant is located in a region designated iSNP, indel, or Flanking in the `TST500_Manifest.bed` file located in the Resources folder.
## Variant Filtering Rules
* **Small Variants -** All variants with the FILTER field marked as PASS in the hard-filtered genome VCF are present in the combined variant output.
* Gene information is only present for variants belonging to canonical transcripts that are within the Gene Allow List–Small Variants.
* Transcript information is only present for variants belonging to canonical transcripts that are within the Gene Allow List–Small Variants.
* **Copy Number Variants -** Copy number variants must meet the following conditions:
* FILTER field marked as PASS.
* ALT field is \ .
* **Fusion Variants -** Fusion variants must meet the following conditions:
* Passing variant call (KeepFusion field is true).
* Contains at least one gene on the fusion allow list.
* Genes separated by a dash (-) indicate that the fusion directionality could be determined. Genes separated by a slash (/) indicate that the fusion directionality could not be determined.
* **Biomarkers TMB/MSI -** Always present when DNA sample is processed.
* **Splice Variants -** Passing splice variants that are contained on genes EGFR, MET, and AR.
* **Biomarker GIS -** Present only if TruSight Oncology 500 HRD analysis is performed
* **Loss of Heterozygosity** - Present only when TruSight Oncology 500 HRD is run. Loss of heterozygosity (LOH) must meet the following condition:
* MCN field is equal to 0
* **Exon-level CNVs -** Exon-levels CNVs must meet the following conditions:
* BRCA1 or BRCA2 contains at least one affected exon.
* ALT field is \ or \ .
# Metrics Output
## Metrics Output
One metrics output file is generated for the entire run. An additional file is generated for each sample (or DNA-RNA pair).
The `MetricsOutput.tsv` file contains the following quality control metrics for all samples:
* DNA library QC metrics for:
* Small variant calling
* TMB
* MSI
* CNV
* \[HRD] GIS
* RNA library QC metrics
* Run QC metrics, analysis status, and contamination
This TSV file also includes expanded DNA library QC metrics per sample, based on total reads, collapsed reads, chimeric reads, and on-target reads. Analysis using RNA samples also produces RNA library QC metrics and expanded RNA library QC metrics per sample based on total reads and coverage.
The `MetricsOutput.tsv` file is a final combined metrics report with sample status, key analysis metrics, and metadata. Sample metrics within the report include suggested lower specification limits (LSL) and upper specification limits (USL) for each sample in the run.
For troubleshooting information, refer to [Troubleshooting](/dragen-tso-500-guides/dragen-tso-500-v2.5/troubleshooting)
# Analysis Methods
The software processes sequencing data to perform quality control, detect variants, determine tumor mutational burden (TMB), microsatellite instability (MSI) status, and genomic instability score (GIS), and report results. The following sections describe the analysis methods used in DRAGEN TruSight Oncology 500 Analysis Software.
DRAGEN TruSight Oncology 500 Analysis Software uses the following workflows to analyze sequencing data.
* FASTQ Generation
* DNA Analysis
* DNA Alignment and Realignment
* Read Collapsing
* Small Variant Calling
* Small Variant Filtering
* Copy Number Variant (CNV) Calling
* Phased Variant Calling
* Variant Merging
* Annotation
* Tumor Mutational Burden (TMB) Scoring
* Microsatellite Instability (MSI) Status
* Contamination Detection
* RNA Analysis
* Downsampling
* Read Trimming
* Alignment
* Duplicate Marking
* Fusion Calling
* RNA Fusion Filtering
* Splice Variant Calling
* Annotation
* Fusion Merging
* Quality Control
* Run QC
* DNA Sample QC
* RNA Sample QC
# FASTQ Generation
Sequencing data stored in BCL format are demultiplexed through a process that uses the index sequences unique to each sample to assign clusters to the library from which they originated. Each cluster contains two indexes (i7 and i5 sequences, one at each end of the library fragment). The combination of those index sequences are used to demultiplex the pooled libraries.
After demultiplexing, this process generates FASTQ files, which contain the sequencing reads for each individual sample library and the associated quality scores for each base call, excluding reads from any clusters that did not pass filter.
# DNA Analysis Methods
## DNA Alignment and Error Correction
DNA alignment and error correction involves aligning sequencing reads derived from DNA libraries to a reference genome and correcting errors in the sequencing reads prior to variant calling.
DRAGEN unique molecular identifier (UMI) error correction comprises three main steps:
1. DRAGEN UMI uses its HW accelerated mapper (based on a hash table implementation) to align DNA sequences in FASTQ files to the hg19 reference genome. These alignments are not written to a BAM.
2. The raw alignments are processed to remove errors, including errors introduced during FFPE preservation, PCR amplification, and sequencing. Reads from the same original DNA molecule are tagged with the same UMI during library preparation. The UMI allows DRAGEN to compare related reads, remove outlier signals, and collapse multiple reads into a single high-quality sequence. Read collapsing adds the following BAM tags:
* RX/XU—UMI.
* XV—Number of reads in the family.
* XW—Number of reads in the duplex-family or 0 if not a duplex family.
3. DRAGEN performs a final alignment step on the UMI-collapsed reads. These final alignments are then written to a BAM file and a corresponding BAM index file is created.
DRAGEN continues to use these final alignments as input for gene amplification (copy number) calling, small variant calling (SNV, indel, MNV, delin), microsatellite instability (MSI) status determination, and DNA library quality control.
## Small Variant Calling and Filtering
DRAGEN supports calling SNVs, indels, MNVs, and delins in tumor-only samples by using mapped and aligned DNA reads from a tumor sample as input. Variants are detected via both column wise pileup analysis and local de novo assembly of haplotypes. The de novo haplotypes allow the detection of much larger insertions and deletions than possible through column wise pileup analysis only. DRAGEN insertions and deletions are validated with lengths of at least 0–25 bp and more than 25 bp can be supported. In addition, DRAGEN also uses the de novo assembly to detect SNVs, insertions, and deletions that are co-phased and part of the same haplotypes. Any such co-phased variants that are within a window of 15 bp can then be reassembled into complex variants (MNVs and delins). The tumor-only pipeline produces a VCF file containing both germline and somatic variants that can be further analyzed to identify tumor mutations. Variant calling extends ± 10 bp into introns; details of the regions covered can be found in the assay manifest file. The pipeline makes no ploidy assumptions, enabling detection of low-frequency alleles.
DRAGEN small variant calling includes the following steps:
1. Detects regions with sufficient read coverage (callable regions).
2. Detects regions where the reads deviate from the reference and there is a possibility of a germline or somatic call (active regions).
3. Assembles de novo graph haplotypes are assembled from reads (haplotype assembly).
4. Extracts possible somatic or germline calls (events) from column wise pileup analysis.
5. Calibrates read base qualities to account for FFPE noise.
6. Computes read likelihoods for each read/haplotype pair.
7. Performs variant calling by summing the genotype probabilities across all reads/haplotype pairs.
8. Performs additional filtering to improve variant calling accuracy, including using a systematic noise file. The systematic noise file indicates the statistical probability of noise at specific positions in the genome. This noise file is constructed using clean (normal) samples. Regions where noise is common (eg, difficult to map regions) have higher noise values. The small variant caller penalizes those regions to reduce the probability of making false positive calls.
## Copy Number Variant Calling
The DRAGEN copy number variant caller performs amplification, reference, and deletion calling for CNV targets within the assay. It counts the coverage of each target interval on the panel, uses a preprocessed panel of normal samples to normalize target counts, corrects for GC coverage bias, and calculates scores of a CNV event from observed coverage and makes copy number calls.
Sex genotype determination for TSO 500 is based on the ratio of median coverage on the Y chromosome relative to the autosomes. A sample is classified as male when the Y‑to‑autosome median coverage ratio exceeds 0.05, under the assumption that female samples have zero or near‑zero median coverage on the Y chromosome. In some cases, insufficient coverage of the X chromosome may prevent reliable assessment, resulting in an undetermined sex genotype call.
{% hint style="info" %}
Tumor fraction is not incorporated into the CNV calling algorithm.
{% endhint %}
## BRCA Large Rearrangement Calling
The BRCA large rearrangement step generates segmentation of the BRCA1 and BRCA2 genes for exon-level CNV detection from the BAM file. Using the same method as CNV calling, the large rearrangement component counts coverage of each target interval of the panel, performs normalization, and calculates the fold change values for each probe across the BRCA genes. Normalization includes GC bias correction, sequencing depth, and probe efficiency using a collection of normal FFPE and genomic DNA samples. Initial segmentation is performed for each gene with circular binary segmentation. The merging of segments is then determined by amplitude, noise, and variance at adjacent segments using thresholds established with *in silico* data. A large rearrangement is reported for genes with more than one segment. Coordinates of the exon-level CNV and the log2 mean fold change for each of the BRCA gene segments are found in the `*_DragenExonCNV.json` file.
In rare cases when a sample contains more than three segments the software may not be able to accurate annotate the BRCA LR which will result in a NA in `*_CombinedVariantOutput.tsv`. This reflects a limitation of the segmentation based annotation logic and does not indicate the absence of a BRCA large rearrangement.
## Annotation
The Illumina Annotation Engine performs annotation of small variants, CNVs, and exon-level CNVs. The inputs are gVCF files and the outputs are annotated JSON files.
The Illumina Annotation Engine processes each variant entry and annotates with available information from databases such as dbSNP, gnomAD genome and exome, 1000 genomes, ClinVar, COSMIC, RefSeq, and Ensembl. The header includes version information and general details. Each annotated variant is included as a nested dictionary structure in separate lines following the header.
The following table shows version information for each annotation database:
| Database | Version |
| -------------------- | ------------------------------------------------- |
| gnomeAD | 2.1 |
| COSMIC | v84 |
| ClinVar | 2019-02-04 |
| dbSNP | v151 |
| 1000 Genomes Project | Phase 3 v5a |
| RefSeq | NCBI Homo sapiens Annotation Release 105.20201022 |
## Tumor Mutational Burden
DRAGEN is used to compute tumor mutational burden (TMB) in coding regions where there is sufficient coverage.
The following variants are excluded from the TMB calculation:
* Non-PASS variants.
* Mitochondrial variants.
* MNVs.
* Variants that do not meet a minimum depth threshold (50).
* Variants that do not meet the minimum variant allele threshold (0.05).
* Variants that fall outside the eligible regions.
* Tumor driver mutations. Variants with a population allele count ≥ 50 are treated as tumor driver mutations. Germline variants are not counted towards TMB. Variants are determined as germline based on a database and a proxy filter.
Variants with a population allele count ≥ 10 that are observed in either the 1000 Genomes or gnomAD databases are marked as germline. MNVs, which do not count towards TMB, may be marked as germline when all their component small variants are marked as germline. The proxy filter scans the variants surrounding a specific variant and identifies those variants with similar variant allele frequencies (VAF). If the majority of surrounding variants of similar VAF are germline, then the variant is also marked as germline.
The formula for TMB calculation is:
$$TMB = {Filtered\ Variants \over Eligible\ Region\ Size (Mbp)}$$
$$Nonsynonymous TMB = {Filtered\ Nonsynonymous\ Variants \over Eligible\ Region\ Size (Mbp)}$$
Outputs are captured in a *`_TMB_Trace.tsv` file that contains information on variants used in the TMB calculation and a* `.tmb.json` file that contains the TMB score calculation and configuration details.
## Microsatellite Instability Status
DRAGEN can determine the MSI status of a sample. It uses a normal reference file, which was created from a set of normal samples. Normal reference files were generated by tabulating read counts for each microsatellite site. The normal file contains the read count distribution for each microsatellite site.
MSI calling is assessed on a predefined list of 130 A and T repeats. The first step in calculating the MSI score is determining how many sites are assessable. A site is considered assessable if it has at least 60 spanning reads. A spanning read is defined as one that extends 5 bp before and after the repeat.
Once assessable sites are identified, the distribution of repeat lengths is compared to the panel of normals. A site is classified as unstable if:
* **Jensen-Shannon distance ≥ 0.1**, and
* **P-value ≤ 0.01**.
After all sites are evaluated, DRAGEN reports:
* The total number of sites assessed
* The count of unstable sites
* The percentage of unstable sites across the sample
Finally, the MSI score is calculated as:
## Genomic Instability Score
{% hint style="info" %}
Requires HRD add-on assay
{% endhint %}
Genomic instability score (GIS) is a whole genome signature for homologous recombination deficiency. The GIS is composed of the sum of three components: loss of heterozygosity, telomeric allele imbalance, and large-scale state transition. These components are estimated using the GIS algorithm contracted from Myriad Genetics, which uses an input of the b-allele frequency and coverage across a genome-wide single nucleotide panel. A panel of normal samples is used for both bias reduction and normalization prior to GIS estimation. Final GIS results can be found in the `*.gis.json` file.
## Contamination Detection
The contamination analysis step detects foreign human DNA contamination using the SNP error file and pileup file that are generated during the small variant calling and the TMB trace file. The software determines whether a sample has foreign DNA using the contamination score. In contaminated samples, the variant allele frequencies in SNPs shift from the expected values of 0%, 50%, or 100%. The algorithm collects all positions that overlap with common SNPs that have variant allele frequencies of < 25% or > 75%. Then, the algorithm computes the likelihood that the positions are an error or a real mutation. The contamination score is the sum of all the log likelihood scores across the predefined SNP positions with minor allele frequency < 25% in the sample and are not likely due to CNV events.
The larger the contamination score, the more likely there is foreign DNA contamination. A sample is considered to be contaminated if the contamination score is above predefined quality threshold. The contamination score was found to be high in samples with highly rearranged genomes or HRD samples. 1% of HRD samples found to be above the threshold with no evidence for actual contamination.
### **Tumor fraction**
Tumor fraction is calculated as described in the User Guide, section “HRD Metrics Report” and leverages the Myriad Genetics algorithm. Tumor fraction is output in the Logs\_Intermediates/Gis/SAMPLE/SAMPLE.gis.json and Combined Variant Output file.
### Ploidy
Ploidy is calculated as described in the User Guide, section “HRD Metrics Report” and leverages the Myriad Genetics algorithm. Ploidy is output in the in the Logs\_Intermediates/Gis/SAMPLE/SAMPLE.gis.json and Combined Variant Output file.
### Absolute Copy Number (Beta)
{% hint style="warning" %}
This is a beta feature. Beta feature results are included in the Combined Variant Output file and other files. However, disclaimers that the results are generated by beta features are only provided in the Combined Variant Output file. Requires HRD add-on assay.
{% endhint %}
Absolute copy numbers are calculated by leveraging the Myriad Genetics algorithm. The algorithm segments the entire genome using the HRD panel and provides an A and B allele estimate for each segment. After the TSO 500 pipeline determines CNV calls (using the TSO 500 panel), the segment covering the gene is identified, and the A and B allele numbers of the segment overlapping the gene are reported. If the gene is within 300 kbases from the segment boundary, the estimate is unreliable and “NA” is output. Absolute copy numbers are output in the Logs\_Intermediates/Gis/SAMPLE/SAMPLE.abcn\_annotated.vcf, Logs\_Intermediates/Gis/SAMPLE/SAMPLE.abcn\_genes.tsv and Combined Variant Output file.
### Gene-Level Loss of Heterozygosity (Beta)
{% hint style="warning" %}
This is a beta feature. Beta feature results are included in the Combined Variant Output file and other files. However, disclaimers that the results are generated by beta features are only provided in the Combined Variant Output file. Requires HRD add-on assay.
{% endhint %}
Gene-level loss of heterozygosity is calculated based on the minor copy number reported in the abcn\_annotated.vc f. If the minor copy number is 0 then the gene is assumed to have a loss of heterozygosity. Gene-level loss of heterozygosity is output in the Logs\_Intermediates/Gis/SAMPLE/SAMPLE.abcn\_genes.tsv and Combined Variant Output file.
# Block List
The block list represents high noise regions in the panel where false positive variant calls are likely produced. As a result, all positions in the gVCF are marked as Filter=excluded\_regions to indicate variant call results are not reliable in such regions.
The block list includes the following genes:
* HLA A
* HLA B
* HLA C
* KMT2B
* KMT2C
* KMT2D
* chrY
* Any position with VAF 1% occurrence in six or more of the 60 baseline samples.
# RNA Analysis Methods
Refer to [RNA Output](/dragen-tso-500-guides/dragen-tso-500-v2.5/analysis-output/rna-output) for more information.
## Downsampling
Each sample is downsampled to 30 million RNA reads. This number represents the total number of single reads (eg, R1 + R2, from all lanes). When using the recommended sequencing configurations or plexity, the samples can have fewer reads than the downsampling limit. In these cases, the FASTQ files are left as-is.
## Read Trimming
Reads are trimmed to 76 base pairs for further processing.
## RNA Alignment and Fusion Detection
RNA alignment and fusion detection uses trimmed reads in FASTQ format as input. The outputs include a BAM file that contains duplicate-marked read alignments, an SJ.out.tab file that contains unannotated splice junctions, and a CSV file that contains fusion candidates.
DRAGEN aligns RNA reads in a transcript-aware mode using the human hg19 genome containing unplaced contigs (ie, chrUn\_gl regions) and uses GENCODEv19 transcript annotations to identify splice sites. DRAGEN identifies and marks duplicate read alignments using start and end coordinates of alignments, which are adjusted for soft clipped reads.
Fusion and splice variant calling only use deduped fragments to score variants. DRAGEN identifies fusion candidates using chimeric split read alignments (pairs of primary and supplementary alignments) against multiple genes. DRAGEN scores and filters reads based on the various features of each candidate such as the number of supporting reads, mapping quality of supporting reads, and sequence homology between parent genes.
The DRAGEN RNA Fusion caller identifies gene fusions by searching for chimeric reads spanning two distinct parent genes. Based on the chimeric reads, DRAGEN first creates a list of fusion candidates, then scores the candidates to report the list of high confidence fusion calls from the candidate pool.
DRAGEN RNA Fusion caller performs the following steps:
1. Generates fusion candidate generation based on split read alignment.
2. Recruits additional evidence from fusion supporting discordant read pairs and soft-clipped reads.
3. Computes fusion candidate features such as gene coverage, read mapping quality, alternate allele frequency, gene homology, alignment anchor length, and breakpoint distance from exon boundary.
4. Scores and ranks the fusion candidates using a logistic regression model.
5. Selects a final list of fusion calls based on score and other filters including number of supporting reads, unique read alignment count, read through transcripts, and fusions matching the enriched regions.
## Splice Variant Calling
RNA splice variant calling is performed for RNA sample libraries. Candidate splice variants (junctions) from RNA Alignment are compared against a database of known transcripts and a splice variant baseline of non-tumor junctions generated from a set of normal FFPE samples from different tissue types. Any splice variants that match the database or baseline are filtered out unless they are in a set of junctions with known oncological function. If there is sufficient read support, the candidate splice variant is kept. This process also identifies candidate RNA fusions.
## RNA Fusion Merging
Fusions identified during RNA fusion calling are merged with fusions from proximal genes identified during RNA splice variant calling. These are then annotated with gene symbols or names with respect to a static database of transcripts (GENCODE Release 19). The result of this process is a set of fusion calls that are eligible for reporting
## RNA Splice Variant Annotation
The Illumina Annotation Engine annotates detected RNA splice variant calls with transcript-level changes (eg, affected exons in the transcript of a gene) with respect to RefSeq. This RefSeq database is the same RefSeq database used by the small variant annotation process.
# Troubleshooting
## General Troubleshooting on Standalone DRAGEN Server
Failure Type
Actions
Software
- Open the log file ./<AnalysisFolder>/Logs_Intermediates/pipeline_trace.txt. This log file displays each pipeline step run by the Nextflow workflow manager software. If a step fails, it is marked as FAILED. Each step generates log files that are stored in step-specific subfolders in the Logs_Intermediates folder. Review the log files in the relevant Logs_Intermediates folder for the step to identify potential sources of error. - Open the errors folder ./<AnalysisFolder>/errors. The workflow creates an error file, error_<NameOfFailedStep>.json, for each step that failed during analysis. For steps that fail per sample, there is a separately labeled file for each sample that failed each step error_<NameOfFailedStep>_<SampleIDIfRelevant>.json. These files contain the command and stdout and stderr from the step.
Samples
Open the combined metrics output results file ./<AnalysisFolder>/Results/<PairId>/MetricsOutput.tsv. If a sample fails an analysis step, the Pair ID that contains the sample shows the failure under FAILED_STEPS in the Analysis Status section, and COMPLETED_ALL_STEPS shows as False. If available, review the individual log files for the failed steps under ./<AnalysisFolder>/Logs_Intermediates to identify potential sources of error.
Multinode Gather
If the following error appears, check if the sample or pair ID was included multiple times during separate node analysis runs, before being gathered together. If the error exists, rerun one of the analyses without the duplicate and reattempt gathering. ERROR:Gather:Destination file ... already exists - check if the same sample ID is in multiple input folders
## Sample Sheet Validation Failures
In DRAGEN TruSight Oncology 500 Analysis Software, the analysis fails if a sample sheet is invalid. If an invalid sample sheet in suspected, log files can help troubleshoot a failed analysis. Use the following steps to find the log file for the sample sheet:
1. Navigate to the following location `//Logs_Intermediates/SamplesheetValidation.`
2. Open the `SamplesheetValidation-.log` file
3. Find a line with the following: `SampleSheetValidationTask:NA:1 exited with return code 1 which has not been declared as a valid return code.`
4. Search for errors in the sample sheet validation log and compare with the guidelines and warnings in [Sample Sheet Requirements](/dragen-tso-500-guides/dragen-tso-500-v2.5/run-planning/sample-sheet-requirements) and the following tables.
### General troubleshooting for a failed sample sheet:
Failure Type
Action
Sample Sheet not found
Verify that SampleSheet.csv is present at the top level of the run folder with the name "SampleSheet.csv". If the sample sheet is in a different location, supply the sample sheet using the --sampleSheet option
Indexes are not valid for the sequencer and/or assay
See Valid indexes for assay and instrument combinations for correct indexes for the sequencer and assay.
Pair_ID is not unique
Pair_ID column is required in the TSO500S_Data section of the sample sheet, which pairs at most one RNA and one DNA sample together for analysis. If the sample does not have a pair, use a unique pair ID for single samples.
Sample Sheet is not in v2 format
Verify that the format of the sample sheet is v2. v1 sample sheet is not compatible with DRAGEN TruSight Oncology 500 Analysis Software.
Analysis does not run
Verify the analysis starts from the run folder, and BCLs or FASTQs are in the correct locations as outlined in Starting From BCL Files and Starting From FASTQ Files respectively.
### Valid indexes for assay and instrument combinations:
| Assay | Index Set ID |
| ---------- | ------------------------------------------------------ |
| TSO 500 |
UP1-UP16
CP1-CP16 (DNA Only)
|
| TSO 500 HT |
UDP0001–UDP0192
|
### Troubleshooting BCL issues:
Failure Type
Action
Lane Column without Values
Ensure that the column is completed. If lane is not applicable to the run, delete the column.
Format of v2 sample sheet is incorrect
Verify that the following sections and fields are present in the sample sheet and follow the individual rules in Sample Sheet Requirements
Verify that HRD is in the Sample Feature column in the sample sheet. Refer to Sample Sheet Requirements for more information.
### Troubleshooting FASTQs issues:
Failure Type
Action
Sample_ID and/or Sample_Type is not present
Verify that the sample sheet has columns and values for Sample_ID and Sample_Type.
Unique sample IDs
Verify that the Sample_IDs are unique in the sample sheet.
Format of v2 Sample Sheet is incorrect
Verify that the following sections and fields are present in the sample sheet and follow the individual rules in Sample Sheet Requirements. [TS0500S_Data] - Sample_ID - Index_ID - Sample_Type - Pair_ID
- Sample Feature (Optional) Verify when FASTQs were generated using the HRD add-kit (Not available in Japan), Sample Feature is added to those DNA Samples. Refer to Sample Sheet Requirements for more information.
Incorrect folder structure
Verify that the FASTQ files are in the correct structure. Refer to Starting From FASTQ Files for more information.
Invalid FASTQ input files
If the FASTQs are invalid, start TSO 500 analysis from BCL files.
HRD analysis missing
Make sure that HRD is in the correct column in the sample sheet.
## Other Troubleshooting Tips
Failure Type
Action
The output file directory contains information from previous analyses
If this issue is seen: specify a new target output folder and repeat analysis
To prevent this issue: specify an empty directory before starting analysis
Single exon (single probe) genes are still reported in the CNV VCF file, but not the CNV TSV file
No action needed; software is working as expected.
Currently all single probe genes are not emitted to the Copy Number Variants section of our CombinedVariantOutput.tsv. However, you can still find these events in the cnv.vcf.gz.
Due to the single probe nature, accurate CNV calling has not been validated and as such they are emitted as REF
Testing of cell lines, contrived samples and commercial controls does not return expected results
Review recommendations for using these samples types here.
## Troubleshooting on BioInsight Platform Core
In addition to TSO 500 managed sample sheet validations, BioInsight Platform Core (formerly ICA) managed TSO 500 errors include the following:
Error
Description
Failure type: ValueError: Could not find pipeline ID for app BCLConvert in sample sheet SampleSheet.csv
Action: Ensure StartsFromFastq field is in the [TSO500S_Settings] section, and it is not present in the [BCLConvert_Settings] Section. Refer to Sample Sheet Requirements for more information.
# DRAGEN TSO 500 ctDNA v2.6
# Introduction to DRAGEN TSO 500 ctDNA Analysis Software v2.6
The Illumina DRAGEN TruSight Oncology 500 (TSO 500) ctDNA Analysis Software supports analysis for DNA libraries that are isolated from plasma and prepared using TruSight Oncology 500 ctDNA v2 and v1 assays. The software, which can be run on the DRAGEN Server, on Illumina BioInsight Platform Core (formerly ICA), and as an analysis application on NovaSeq 6000Dx, produces a variant call file (VCF) for small variants. Other outputs include tumor mutational burden (TMB), a Jensen-Shannon divergence (sum JSD) score that can be used for evaluating microsatellite instability (MSI) status, files with copy number variants (CNV), fusions as well as coverage reports.
The secondary analysis software starts from a sequencing run folder containing base call files (BCL) or from FASTQ files staged in a FASTQ folder.
This document provides information on installation, configuration, running, troubleshooting as well as analysis algorithms of DRAGEN TruSight Oncology 500 ctDNA analysis software on Platform Core, standalone DRAGEN server, and the NovaSeq 6000Dx analysis application.
The software is optimized for analyzing sequencing outputs generated by the TruSight Oncology 500 ctDNA v2 and v1 assays. Modification might lead to inaccurate data and is a violation of the [Illumina Software Subscription Agreement](https://www.illumina.com/company/legal/terms-and-conditions.html).
{% hint style="info" %}
Variant reporting by DRAGEN TruSight™ Oncology 500 ctDNA Analysis Software is limited by a manifest file and a [block list file](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/analysis-output/block-list). The manifest file excludes regions where the probe set does not effectively capture targets, and the block list file excludes specific positions from variant calling. TSO 500 ctDNA assay probes target at least 97% of the CDS of 474 genes. Please contact your local Illumina representative for more information if needed.
{% endhint %}
## Scope
This resource provides information on installation, configuration, running, troubleshooting and analysis algorithms for the following software:
DRAGEN TruSight Oncology 500 ctDNA Analysis Application on NovaSeq 6000Dx (uses a paired DRAGEN server)
v2.6.0
v2.6.1
v2.6.3
The content is applicable to all software versions as listed for each deployment above, unless otherwise specified.
## Local and Cloud Deployments
Local analysis is available using a standalone DRAGEN server or an application with a user interface on NovaSeq 6000Dx. The software on the standalone DRAGEN server allows for analysis on a single DRAGEN server or splitting across multiple servers.
Cloud analysis is available on Platform Core with auto-launch or manual launch. Both methods are available from BCLs and FASTQs.
## Instrument Compatibility
DRAGEN TruSight Oncology 500 ctDNA analysis software v2.6.x is compatible with data generated on the Illumina instruments as summarized in the table below.
Instrument
BioInsight Platform Core
Standalone DRAGEN Server
Paired DRAGEN server
On-board DRAGEN
NovaSeq 6000:
S1, S2, S4
Yes (v2.6.0.25, v2.6.1.8, v2.6.31)
Yes
N/A
N/A
NovaSeq 6000Dx(RUO mode):
S1, S2, S4
Yes (v2.6.0.25, v2.6.1.8, v2.6.31)
Yes
Yes (v2.6.0, v2.6.1, v2.6.31)
N/A
NovaSeq X:
1.5B, 5B, 10B, 25B
Yes (v2.6.0.25, v2.6.1.8, v2.6.32,3, v2.6.42)
Yes
N/A
No
NextSeq 2000: P4
Yes (v2.6.3)
Yes
N/A
No
1. Version compatible with S1 flow cell
2. Version compatible with 25B flow cell
3. Version compatible with 5B flow cell. For required sample sheet modifications for cloud auto-launch analysis, follow steps described here [Sample Sheet Preparation for 5B Flow Cell](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/run-planning/sample-sheet-preparation-for-5b-flow-cell). For analysis on the DRAGEN server, refer to [Analysis Launch on Standalone DRAGEN Server](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/launching-analysis/analysis-launch-on-standalone-dragen-server) page.
## Navigation of Guide
This resource provides information on installation, configuration, running, troubleshooting as well as analysis algorithms of DRAGEN TruSight Oncology 500 ctDNA analysis software on Platform Core, standalone DRAGEN server, and the NovaSeq 6000Dx analysis application.
## Workflow Diagram
Workflow Overview
# Getting Started
# Installation of TSO 500 ctDNA v2.6.0, v2.6.1 on Standalone DRAGEN Server
## Overview
The installation script for DRAGEN TruSight Oncology 500 ctDNA Analysis Software installs the following software and dependencies:
1. DRAGEN TruSight Oncology 500 ctDNA Analysis Software itself
2. DRAGEN Software if a compatible version is not present
3. Docker software if a compatible version is not present
4. A script required to generate DRAGEN genome hash table
5. A script to check that DRAGEN TruSight Oncology 500 ctDNA Analysis Software is installed properly
## Installation Requirements
### Hardware
* DRAGEN server v3 or v4
### Software
* By default Linux CentOS 7.9 operating system (or later) or Oracle Linux 8 (or later), is provided. Oracle Linux 8 is recommended.
* Docker Software, see table below.
* DRAGEN Software, see table below.
| Software Dependency | Compatible | Installs |
| ------------------- | -------------------------------- | ----------------------- |
| Docker | 20.10 or greater | Docker 20.10.15 |
| DRAGEN Software | v3.10.x where x is 17 or greater | DRAGEN Software 3.10.17 |
{% hint style="warning" %}
DRAGEN TruSight Oncology 500 ctDNA v2.6.0 Analysis Software is not compatible with DRAGEN Software v4.0 or above on the same standalone DRAGEN server.
{% endhint %}
### Licenses
* `TSO500Combined` license
`TSO500Combined` license has been pre-installed to DRAGEN servers in manufacturing since August 2022. To generate a list of installed DRAGEN server licenses, run the following command: `/opt/edico/bin/dragen_lic`. If a license is not installed, contact Illumina Customer Care at for the license.
### Permissions
Illumina recommends logging in as root user for installation, but as a non-root user for running TSO 500 ctDNA analysis.
* A non-root user must be a member of the Docker group to run Docker. For more information on Docker permission requirements and alternatives to running as root, refer to the Docker documentation available on the [Docker website](https://www.docker.com/).
* Installing and uninstalling DRAGEN TruSight Oncology 500 ctDNA Analysis Software and running the system check requires root privileges.
* Run DRAGEN TruSight Oncology 500 ctDNA Analysis Software without being logged in as a root user. Running the DRAGEN TruSight Oncology 500 ctDNA Analysis Software as root is not required or recommended.
## Compatibility with other TruSight Oncology 500 ctDNA and TruSight Oncology 500 Analysis Software
DRAGEN TruSight Oncology 500 Analysis Software ctDNA v2.6.0 can be installed on one DRAGEN server with:
1. DRAGEN TruSight Oncology 500 Analysis Software v2.6.0 (v3.10.17\*)
2. One prior 2.x version of DRAGEN TruSight Oncology 500 ctDNA Analysis Software (v2.1.1 (v3.10.9\*), v2.5.0 (v3.10.15\*), 2.6.0 (v3.10.17\*), 2.6.1 (v3.10.18\*))
3. One prior 2.x version of DRAGEN TruSight Oncology 500 Analysis Software (v2.1.1 (v3.10.9\*), v2.5.3 (v3.10.16\*)
\*DRAGEN Software version
Contrary to the prior versions, the installation scripts for DRAGEN TruSight Oncology 500 ctDNA Analysis Software v2.6.0 and DRAGEN TruSight Oncology 500 v2.6.0 do not uninstall previous versions of DRAGEN TruSight Oncology 500 Analysis Software. To uninstall a previous version of DRAGEN TruSight Oncology 500 ctDNA Analysis Software, refer to the respective guide.
{% hint style="info" %}
When installing DRAGEN TruSight Oncology 500 and DRAGEN TruSight Oncology 500 ctDNA software on the same DRAGEN server, install the software with the highest corresponding DRAGEN Software version last, as versions below v2.6.0 will overwrite with its corresponding DRAGEN Software version.
{% endhint %}
{% hint style="warning" %}
If a prior version of DRAGEN TruSight Oncology 500 ctDNA Analysis Software (eg. v2.5.0) is installed after v2.6.0, re-execute the installation script for v2.6.0 to install the compatible version of DRAGEN Software without impacting other installations.
{% endhint %}
## Installation Instructions
As a root user, perform the following steps to install DRAGEN TruSight Oncology 500 ctDNA v2.6.0 Analysis Software:
1. Contact Illumina Customer Care at to obtain the DRAGEN TruSight Oncology 500 Analysis Software installer package.
2. Download the installation package provided in the email from Illumina. **The link expires after 7 days.**
{% hint style="info" %}
It is recommended to use a command line tool like wget or curl to download the file rather than pasting the link into the web browser bar. For example:
`curl -o {filename} "{link}"`
`wget -O {filename} "{link}"`
Where the file name is the installation script file name, and the link is provided by Illumina Customer Care.
{% endhint %}
3. Make sure no other analysis is being performed. Installing the software while performing other analyses prevent the installer process from proceeding.
4. Copy the install script to the `/staging` directory to store the script in the directory.
{% hint style="info" %}
Installation Script:
install\_DRAGEN\_TSO500\_ctDNA-2.6.0.run
install\_DRAGEN\_TSO500\_ctDNA-2.6.1.run
**MD5sum values**\
v2.6.0: sha256:e98ab87152b02e2c7958f2f750fa37880a496d68e77858a09f4ad5fb07b2145b\
v2.6.1: sha256:026efd4402e91e8472effb30749e231817958532aae128334c5f9943564e4b8d
{% endhint %}
5. Use the following command to update the run script permission:\
`chmod +x /staging/install_DRAGEN_TSO500_CTDNA-2.6.0.run`
6. Use the following command to run the installation script, which runs for approximately 20 minutes:
1. For Docker, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500_CTDNA-2.6.0.run` . The script installs compatible DRAGEN software and removes any previously installed versions.
2. For Apptainer, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500_CTDNA-2.6.0.run -- --noDockerInstall` This will not install Apptainer, but will install the analysis software in the Singularity Image File (SIF) format and modify the software to launch analyses using Apptainer.
7. During the installation process, you might be instructed to reboot or power cycle the system to complete the installation of the DRAGEN software. A power cycle of the system requires the server be shut down and restarted.
8. Log out of the server and then log back in.
9. Install your DRAGEN server licenses if needed:
1. To run DRAGEN TruSight Oncology 500 ctDNA v2.6.0 Analysis Software, you need `TSOCombined` license. This license is pre-installed on DRAGEN servers purchased after August 2022. To check if the license is already installed, run `/opt/edico/bin/dragen_lic`command.
2. For servers connected to the Internet, install your software licenses as follows:
1. First, test and confirm that the server is connected to the Internet. Example: `ping www.illumina.com`
2. To install the license, enter: `/opt/edico/bin/dragen_lic -i auto`
3. For servers not connected to the internet, contact Illumina Customer Care at for license information.
10. After installing DRAGEN server licenses, generate a list of installed DRAGEN server licenses by running the following command: `/opt/edico/bin/dragen_lic`
If license installation is successful, the list should include `TSOCombined`.
If the expected licenses are not installed, contact Illumina Customer Care.
## Running the System Check
After installation is complete, make sure the system functions properly by running the following command: `/usr/local/bin/check_DRAGEN_TSO500_CTDNA-2.6.0.sh`
The script checks that:
* All required services are running
* Proper Docker image is installed
* DRAGEN TruSight Oncology 500 ctDNA Analysis Software can successfully process a test data set
The system check script runs for approximately 25 minutes. If the script prints a failure message, contact Illumina Technical Support and provide the `/staging/check_DRAGEN_TSO500_CTDNA_.tgz` output file.
If using MacOS to connect to a server, an error can occur if the local settings are not in English. To resolve the error, disable the ability to set environment variables automatically in Terminal settings.
## Uninstall Software
The DRAGEN TruSight Oncology 500 Analysis Software installation includes an uninstall script called `uninstall_DRAGEN_TSO500_CTDNA-2.6.0.sh`, which is located in `/usr/local/bin`.
Executing the uninstall script removes the following assets:
* All DRAGEN TruSight Oncology 500 ctDNA Analysis Software related scripts located in `/usr/local/bin`
* Resources found in `/staging/illumina/DRAGEN_TSO500_CTDNA`
* The `dragen_tso500_ctdna` Docker image
To uninstall the DRAGEN TruSight Oncology 500 ctDNA Analysis Software, run the following command as a root user:
`uninstall_DRAGEN_TSO500_CTDNA-2.6.0.sh`
You are not required to uninstall Docker or DRAGEN software. To remove Docker, review the install instructions for your operating system in the Docker documentation.
# Installation of TSO 500 ctDNA v2.6.2, v2.6.3, v2.6.4 on Standalone DRAGEN Server
## Overview
The installation script for DRAGEN TruSight Oncology 500 ctDNA Analysis Software installs the following software and dependencies:
1. DRAGEN TruSight Oncology 500 ctDNA Analysis Software itself
2. DRAGEN Software if a compatible version is not present
3. Docker software if a compatible version is not present
4. A script required to generate DRAGEN genome hash table
5. A script to check that DRAGEN TruSight Oncology 500 ctDNA Analysis Software is installed properly
## Installation Requirements
### Hardware
* DRAGEN server v3 or v4
### Software
* Linux CentOS 7.9 operating system (or later) or Oracle Linux 8 (or later), one of which is provided on the server. Oracle Linux 8 is recommended.
* Docker Software, see table below for minimum version needed. If sufficient Docker software is not present on the server, the TSO 500 installer will install compatible Docker software.
* DRAGEN Server Software\*, see table below for minimum version needed as the host version on the server. If sufficient DRAGEN software is not present on the server, the TSO 500 installer will install compatible DRAGEN software.
| Software Dependency | Compatible | Installs |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Docker | 20.10 or greater | Docker 20.10.15 |
| DRAGEN Server Software\* |
v3.10.x, where x >=19, v4.3+ for TSO500 ctDNA v2.6.2;
v3.11.x, where x >=2, v4.3+ for TSO500 ctDNA v2.6.3 and v2.6.4
|
DRAGEN Software 3.10.19 for TSO500 ctDNA v2.6.2;
DRAGEN Software 3.11.2 for TSO500 ctDNA v2.6.3 and v2.6.4
|
{% hint style="info" %}
\*The DRAGEN Server Software version may be higher than the DRAGEN version used by the DRAGEN TSO 500 ctDNA v2.6.2 pipeline (DRAGEN v3.10.18), which is provided inside the DRAGEN TSO 500 ctDNA docker image.
{% endhint %}
### Licenses
* `TSO500Combined` license
`TSO500Combined` license has been pre-installed to DRAGEN servers in manufacturing since August 2022. To generate a list of installed DRAGEN server licenses, run the following command: `/usr/bin/dragen_lic`. If a license is not installed, contact Illumina Customer Care at for the license.
### Permissions
Illumina recommends logging in as root user for installation, but as a non-root user for running TSO 500 ctDNA analysis.
* A non-root user must be a member of the Docker group to run Docker. For more information on Docker permission requirements and alternatives to running as root, refer to the Docker documentation available on the [Docker website](https://www.docker.com/).
* Installing and uninstalling DRAGEN TruSight Oncology 500 ctDNA Analysis Software and running the system check requires root privileges.
* Run DRAGEN TruSight Oncology 500 ctDNA Analysis Software without being logged in as a root user. Running the DRAGEN TruSight Oncology 500 ctDNA Analysis Software as root is not required or recommended.
## Compatibility with other DRAGEN pipelines
DRAGEN TSO 500 Analysis Software ctDNA v2.6.2, v2.6.3, and v2.6.4 (v2.6.2+) are multi-version compatible. Multi-version compatibility refers to ability to be installed on a single DRAGEN server with software running a different version of DRAGEN software. For example, multi-version compatible pipelines running DRAGEN v4.3.6+ can be co-installed on a server alongside DRAGEN TSO 500 ctDNA pipelines with DRAGEN server software v3.10.19 and above. For more details on DRAGEN multi-version compatibility, please visit [page 7 of the DRAGEN v4.3.6 software release notes](https://support.illumina.com/content/dam/illumina-support/documents/downloads/software/dragen/release-notes/200056923_00_DRAGEN_4_3_6_Customer-Release-Notes.pdf).
Software versions without multi-version compatibility referred to as single-version compatible. DRAGEN TSO 500 ctDNA Analysis Software v2.6.2+ will disrupt installations of single-version compatible software from the DRAGEN server. To uninstall a previous version of DRAGEN TSO 500 ctDNA Analysis Software, refer to the respective guide.
Compatibility of software for co-installation with DRAGEN TSO 500 ctDNA on a DRAGEN server is summarized in the table below:
Software
Version
Type
Compatible
DRAGEN TSO 500 ctDNA
2.6.2+
Multi-version
Yes
DRAGEN TSO 500 ctDNA
2.6.1 or below
Single-version
No
DRAGEN TSO 500
2.6.1+
Multi-version
Yes
DRAGEN TSO 500
2.6.0
Single-version
No
DRAGEN TSO 500
2.5.4
Multi-version
Yes*
DRAGEN TSO 500
2.5.3 or below
Single-version
No
DRAGEN pipelines**
4.3.6+
Multi-version
Yes
DRAGEN pipelines**
4.2 or below
Single-version
No
\*DRAGEN TSO 500 Analysis Software ctDNA v2.6.2+ can run on a single server with DRAGEN TSO 500 v2.5.4, and should be installed after v2.5.4. DRAGEN TSO 500 Analysis Software ctDNA v2.6.2+ can be co-installed with multi-version compatible DRAGEN TSO 500 Analysis Software or other DRAGEN pipelines with any order of installation.
\*\*For example, DRAGEN Enrichment, DRAGEN Germline, and others. Order of installation does not matter.
## Installation Instructions
### Pre- and Post- Installation Steps
1. Uninstall all existing single-version compatible software on the server (see table above)
2. Install DRAGEN TSO 500 ctDNA Analysis Software v2.6.2+
* This step will disrupt previously installed single-version compatible software but will not impact multi-version compatible ones (see table above)
3. Install other multi-version DRAGEN software/pipelines if needed
* Multi-version software can be installed in any order
### Steps to Install DRAGEN TSO 500 ctDNA Analysis Software v2.6.2+
As a root user, perform the following steps to install DRAGEN TSO 500 ctDNA Analysis Software v2.6.2, v2.6.3, and v2.6.4 (v2.6.2 for an example):
1. Contact Illumina Customer Care at to obtain the DRAGEN TSO 500 ctDNA Analysis Software installer package.
2. Download the installation package provided in the email from Illumina. **The link expires after 7 days.**
{% hint style="info" %}
It is recommended to use a command line tool like wget or curl to download the file rather than pasting the link into the web browser bar. For example:
`curl -o {filename} "{link}"`
`wget -O {filename} "{link}"`
Where the file name is the installation script file name, and the link is provided by Illumina Customer Care.
{% endhint %}
3. Make sure no other analysis is being performed. Installing the software while performing other analyses prevents the installer process from proceeding.
4. Copy the install script to the `/staging` directory to store the script in the directory.
{% hint style="info" %}
**v2.6.2 Installation Script:** install\_DRAGEN\_TSO500\_CTDNA-2.6.2.run
**v2.6.2 SHA256 value:** 1324c86183526e12afb267f553a569cf78b01fd7a4ee85f8e07cc2f6a33d8f41
**v2.6.3 Installation Script:** install\_DRAGEN\_TSO500\_CTDNA-2.6.3.run
**v2.6.3 SHA256 value:** 77a4f3b44af22c8c83e0bfe43d3b186d2b74dc58b8bbdb6f324ba3ce6220ab9e
**v2.6.4 Installation Script:** install\_DRAGEN\_TSO500\_CTDNA-2.6.4.run
**v2.6.4 SHA256 value:** 0b3528687dcaacf7621fcac6b76b9b668c586471c86f5f112999e4a3f0dfc877
{% endhint %}
5. Use the following command to update the run script permission:\
`chmod +x /staging/install_DRAGEN_TSO500_CTDNA-2.6.2.run`
6. Use the following command to run the installation script (run time \~ 20 minutes):
1. For Docker, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500_CTDNA-2.6.2.run` . The script installs compatible DRAGEN software and removes any previously installed versions.
1. If new DRAGEN version is not installed from the above command, use `sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500_CTDNA-2.6.2.run -- --forceDragenInstall` to force a reinstall of DRAGEN.
2. For Apptainer, use the following command:\
`sudo TMPDIR=/staging /staging/install_DRAGEN_TSO500_CTDNA-2.6.2.run -- --noDockerInstall` This will not install Apptainer, but will install the analysis software in the Singularity Image File (SIF) format and modify the software to launch analyses using Apptainer.
7. During the installation process, you may be instructed to reboot or power cycle the system to complete the installation of the DRAGEN software. A power cycle of the system requires the server be shut down and restarted.
8. Log out of the server and log back in.
9. Install your DRAGEN server licenses if needed (use `/opt/dragen/3.11.2/bin/dragen_lic` for v2.6.3 and v2.6.4):
1. To run DRAGEN TSO 500 ctDNA Analysis Software v2.6.2 , you need `TSOCombined` license. This license is pre-installed on DRAGEN servers purchased after August 2022. To check if the license is already installed, run `/opt/dragen/3.10.19/bin/dragen_lic` command.
2. For servers connected to the Internet, install your software licenses as follows:
1. First, test and confirm that the server is connected to the Internet. Example: `ping www.illumina.com`
2. To install the license, enter: `/opt/dragen/3.10.19/bin/dragen_lic -i auto`
3. For servers not connected to the internet, contact Illumina Customer Care at for license information.
10. After installing DRAGEN server licenses, generate a list of installed licenses by running the following command: `/opt/edico/bin/dragen_lic`
If license installation is successful, the list should include `TSOCombined`.
If the expected licenses are not installed, contact Illumina Customer Care.
## Running the System Check
After installation is complete, make sure the system functions properly by running the following command: `/usr/local/bin/check_DRAGEN_TSO500_CTDNA-2.6.2.sh`
The script checks that:
* All required services are running
* Proper Docker image is installed
* DRAGEN TSO 500 ctDNA Analysis Software can successfully process a test data set
The system check script runs for approximately 25 minutes. If the script prints a failure message, contact Illumina Technical Support and provide the `/staging/check_DRAGEN_TSO500_CTDNA_.tgz` output file.
If using MacOS to connect to a server, an error can occur if the local settings are not in English. To resolve the error, disable the ability to set environment variables automatically in Terminal settings.
## Uninstall Software
The DRAGEN TSO 500 ctDNA Analysis Software installation includes an uninstall script called `uninstall_DRAGEN_TSO500_CTDNA-2.6.2.sh`, which is located in `/usr/local/bin`.
Executing the uninstall script removes the following assets:
* All DRAGEN TSO 500 Analysis Software related scripts located in `/usr/local/bin`
* Resources found in `/staging/illumina/DRAGEN_TSO500_CTDNA-2.6.2`
* The `dragen_tso500_ctdna Docker` image
To uninstall the DRAGEN TSO 500 ctDNA Analysis Software, run the following command as a root user:
`uninstall_DRAGEN_TSO500_CTDNA-2.6.2.sh`
You are not required to uninstall Docker or DRAGEN software. To remove Docker, review the install instructions for your operating system in the Docker documentation.
# Getting Started on Illumina BioInsight Platform Core
## Prerequisites
An Illumina BioInsight Platform subscription includes access to DRAGEN TruSight Oncology 500 ctDNA Analysis Software on BioInsight Platform Core (formerly ICA). To get started, you need:
* A BioInsight Platform account with a valid subscription
* A positive balance of Illumina BioInsight Credits (BICs) for data storage
Refer to the [Software Setup page](https://help.connected.illumina.com/account-management/rg-registration) for information on how to register a BioInsight Platform subscription and BICs.
# Installation of NovaSeq 6000Dx TSO 500 ctDNA Analysis Application
Instructions to install DRAGEN TSO 500 ctDNA Analysis Application on NovaSeq 6000Dx (RUO mode)
## Prerequisites
The following requirements must be met to install and run DRAGEN TruSight Oncology 500 ctDNA Analysis Application on NovaSeq 6000Dx:
* A NovaSeq 6000Dx sequencing instrument with Illumina Run Manager v1.6.2 installed and paired with DRAGEN Server v4.
* Administrator privileges on Illumina Run Manager.
## Installation Instructions
Perform the following steps to download and install the DRAGEN TruSight Oncology 500 ctDNA Analysis Application on NovaSeq 6000Dx installation package:
1. Contact Illumina Customer Care for the link to the installation package. The link expires after 7 days.
2. Download the installation package with the link provided in the email from Illumina Customer Care. The installation package contains the following files:
1. DRAGEN IRES file: `drageninstaller_.el8.x86_64_prod.ires`
2. Illumina Run Manager: `TSO500L_v.iapp`
3. Install the DRAGEN version using the IRES file.
1. Log into Illumina Run Manager as an administrator.
2. From the Settings menu, select DRAGEN.
3. Select Add DRAGEN Installer.
4. Select the DRAGEN IRES file to begin installation.
5. Check the install versions list to verify that the appropriate DRAGEN version is listed
4. Install the Illumina Run Manager-compatible application.
1. Log into Illumina Run Manager as an administrator.
2. From the left-hand menu, select Applications.
3. Select the RUO tab, select Install Application, and then select the IAPP file to install the application.
4. Check the RUO Applications list to verify that the appropriate application version is listed. You can configure application settings such as required users from this list.
## External Storage Configuration
Perform the following steps to specify a location to store analysis results:
1. Log into Illumina Run Manager as an administrator.
2. From the Settings menu, select External Storage for Analysis Results.
3. Configure the following parameters:
1. Server Location: The path of the preferred output file location. A change to the server location may prompt you to enter the domain, user name, and password to the new server location.
1. In addition to storing the analysis results from any sequencing runs, this location contains the input data created when setting up runs. Make sure that the server location has sufficient storage space for your run.
2. Encryption—Select Require encryption during file transfer.
4. Select Save to preserve the changes to the external storage output parameters.
{% hint style="warning" %}
The v2.6.3 app uses DRAGEN v3.11.2, which is not designed to be co-installed with earlier DRAGEN versions (e.g. v3.10.18 and below, v4.3.5 and below). When launching analysis after installing another NovaSeq 6000Dx app and its dependent version of DRAGEN (that does not support multi-version installation), the software may sporadically be unable to run.\
\
For example, users may encounter an issue if the following steps occur in order:
1. installation of the DRAGEN TSO 500 ctDNA v2.6.3 app for NovaSeq 6000Dx and its dependent DRAGEN, v3.11.2
2. installation of the DRAGEN TSO 500 ctDNA v2.6.1 app\* for NovaSeq 6000Dx and its dependent DRAGEN, v3.10.18
3. analysis is initiated using DRAGEN TSO 500 ctDNA v2.6.3 app
\*or any other app requiring an incompatible DRAGEN version. See [Installation of TSO 500 ctDNA v2.6.2, v2.6.3, v2.6.4 on Standalone DRAGEN Server](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/getting-started/installation-of-tso-500-ctdna-v2.6.2-v2.6.3-v2.6.4-on-standalone-dragen-server) for DRAGEN co-installation compatibility.
See Troubleshooting section for a workaround. [NovaSeq 6000Dx App Troubleshooting](/dragen-tso-500-guides/dragen-tso-500-v2.6/troubleshooting/novaseq-6000dx-app-troubleshooting)
{% endhint %}
# Run Planning
# Sample Sheet Introduction
## Overview
A sample sheet is required for each analysis with DRAGEN TruSight Oncology 500 ctDNA Analysis Software. A sample sheet is a comma-separated value (\*.csv) file format used by Illumina instruments, platforms, and analysis pipelines to store settings and data for sequencing and analysis. The DRAGEN TruSight Oncology 500 ctDNA Analysis Software is compatible with the sample sheet v2. For general information on the sample sheet v2, refer to [Illumina BioInsight Platform - Sample Sheet](https://help.connected.illumina.com/run-set-up/overview).
The sample sheet includes a list of samples and their index sequences, along with additional information required to run DRAGEN TruSight Oncology 500 ctDNA Analysis Software. For example, the library prep kit used for analysis will need to be listed in the sample sheet. Appropriate index adapter sequences are determined by the assay used to perform analysis.
When running analysis on a standalone DRAGEN server or on BioInsight Platform Core (formerly ICA), a valid sample sheet can be created by:
* BaseSpace Run Planner (preferred), see [Sample Sheet Creation in BaseSpace Run Planner page](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/run-planning/sample-sheet-creation-in-basespace-run-planning-tool) for details
* Downloading and modifying a sample sheet template following the requirements, see [Sample Sheet Requirements page](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/run-planning/sample-sheet-requirements) for details
When running analysis using a NovaSeq 6000Dx Analysis Application, a valid sample sheet can be created by:
* Using the user interface of the DRAGEN TruSight Oncology 500 ctDNA Analysis Application, see [Run Planning on Illumina Run Manager](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/run-planning) for details
* Downloading and modifying a sample sheet template following the requirements (see [Sample Sheet Requirements page](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/run-planning/sample-sheet-requirements) for details), then importing it to Illumina Run Manager.
The run set up section of this guide includes specific instructions to plan a run and set up a valid sample sheet for each deployment of DRAGEN TruSight Oncology 500 ctDNA Analysis Software.
# Sample Sheet Requirements
DRAGEN TSO 500 ctDNA Analysis Software has optional and required fields that are required in addition to general sample sheet requirements. Follow the steps below to create a valid samplesheet.
{% hint style="info" %}
TSO 500L Data Section header changes depending on the deployment:
* Standalone DRAGEN Server and BioInsight Platform Core (formerly ICA) with Manual Launch: `TSO500L_Data`
* Platform Core with Auto-launch: `Cloud_TSO500L_Data`
{% endhint %}
### \[TSO500L\_Data] Section
Parameter
Required
Details
Sample_ID
Required
The unique ID to identify a sample. The sample ID is included in the output file names. Sample IDs are not case sensitive. Sample IDs must have the following characteristics: - Unique for the run. - 1–40 characters. - No spaces. - Alphanumeric characters with underscores and dashes. If you use an underscore or dash, enter an alphanumeric character before and after the underscore or dash. eg, Sample1-T5B1_022515. - Cannot be called all, default, none, unknown, undetermined, stats, or reports. - Must match a Sample_ID listed in the BCL Convert Data section. - Each sample must have a unique combination of Lane (if applicable), sample ID, and index ID or the analysis will fail.
Sample_Type
Required
Enter DNA
Sample_Description
Not Required
Sample description must meet the following requirements: - 1–50 characters. - Alphanumeric characters with underscores, dashes and spaces. If you enter a underscore, dash, or space, enter an alphanumeric character before and after. eg, Liquid-Sample_213.
To ensure a successful analysis, follow these guidelines:
1. Avoid any blank lines at the end of the sample sheet; these can cause the analysis to fail.
2. When running local analysis using the command line save the sample sheet in the sequencing run folder with the default name `SampleSheet.csv`, or choose a different name and specify the path in the command-line options.
## BioInsight Platform Core with Auto-launch: Sample Sheet Requirements
Refer to the following requirements to create sample sheets for running the analysis on Platform Core with Auto-launch. For sample sheet requirements common between deployments see [Standard Sample Sheet Requirements](#standard-sample-sheet-requirements). Samples sheets can be created using BaseSpace Run Planning Tool or manually by downloading and editing a sample sheet template
{% hint style="info" %}
To auto-launch analysis from the sequencer run folder, ensure the StartsFromFastq and SampleSheetRequested fields are set to FALSE. To auto-launch analysis from FASTQs after BCL Convert auto-launch, StartsFromFastq and SampleSheet Requested fields must be set to TRUE
{% endhint %}
### **\[Cloud\_TSO500L\_Data] Section**
Refer to [\[TSO500L\_Data\] Section](#tso500l_data-section) for this section's requirements.
### **\[Cloud\_TSO500L\_Settings] Section**
Parameters
Required
Details
SoftwareVersion
Not Required
The TSO500S software version
StartsFromFastq
Required
Set the value to TRUE or FALSE. To auto-launch from BCL files, set to FALSE. To auto-launch from FASTQ files after auto-launch of BCL Convert, set to TRUE.
SampleSheetRequested
Required
Set the value to TRUE or FALSE.
To auto-launch from BCL files, set to FALSE. To auto-launch from FASTQ files after auto-launch of BCL Convert, set to TRUE.
### \[Cloud\_Data] Section
Parameter
Required
Details
Sample_ID
Not Required
The same sample ID used in the Cloud_TSO500L_Data section.
ProjectName
Not Required
The BaseSpace project name.
LibraryName
Not Required
Combination of sample ID and index values in the following format: sampleID_Index_Index2
LibraryPrepKitName
Required
The Library Prep Kit used.
IndexAdapterKitName
Not Required
The Index Adapter Kit used.
### \[Cloud\_Settings] Section
Parameter
Required
Details
GeneratedVersion
Not Required
The cloud GSS version used to create the sample sheet. Optional if manually updating a sample sheet.
CloudWorkflow
Not Required
Ica_workflow_1
Cloud_TSO500L_Pipeline
Required
This value is a universal record number (URN) . The valid value is: urn:ilmn:ica:pipeline:850b4fe6-2a2f-4a85-ae57-cf082dfbefd4#DRAGEN_TruSight_Oncology_500_ctDNA_v2_6_1_4
BCLConvert_Pipeline
Required
The value is a URN in the following format: urn:ilmn:ica:pipeline: <pipeline-ID>#<pipeline-name>
## NovaSeq 6000Dx Analysis Application: Sample Sheet Requirements
This section describes fields specific for sample sheets for NovaSeq 6000Dx Analysis Application. For more information on DRAGEN TSO 500 ctDNA Analysis Software sample sheet requirements, refer to the sections above.
{% hint style="warning" %}
Mismatches between the samples and index primers can cause incorrect results due to loss of positive sample identification. Enter sample IDs and assign indexes in the sample sheet before beginning library preparation. Record sample IDs, indexes, and plate well orientation for reference during library preparation.
{% endhint %}
### \[BCLConvert\_Settings] Section
Parameter Name
Required
SoftwareVersion
Required
Enter the IRM iapp software version 2.6.1-4v2
# Sample Sheet Creation in BaseSpace Run Planning tool
## How to Create TSO 500 ctDNA Sample Sheets in BaseSpace Run Planning tool
The BaseSpace Sequence Hub Run Planning tool is available, and is used to generate a valid sample sheet in v2 format for use on a TSO 500 ctDNA supported sequencer for both BioInsight Platform Core (formerly ICA) and Standalone DRAGEN Server analysis options. Filling out the form on the user interface will produce a exportable sample sheet with the required fields filled in. Refer to [Platform Core Auto-launch Sample Sheet Requirements](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/run-planning/sample-sheet-requirements#ica-with-auto-launch-sample-sheet-requirements) for descriptions of fields that appear in Platform Core sample sheets.
The sections below represent each step in the BaseSpace Run Planning tool.
{% hint style="info" %}
Note that NovaSeq X Series has a different run set up screen than other instrument platforms, as it allows the user to include multiple assay configurations in one run. DRAGEN TSO 500 ctDNA supports multi-assay flow cell analysis starting in version 2.6.3.
For ctDNA v2.6.0 and above, in order to run TSO 500 ctDNA on NovaSeq X Series, enter the appropriate Read 1, Read 2, Index 1 and Index 2 described in the instructions below.
{% endhint %}
{% hint style="warning" %}
BaseSpace Run Planning tool cannot generate a valid sample sheet for the NovaSeq 6000Dx TSO 500 ctDNA Analysis Application on Illumina Run Manager. Refer to [Sample Sheet Requirements page](/dragen-tso-500-guides/dragen-tso-500-v2.6/run-planning/sample-sheet-requirements) to create a valid sample sheet.
{% endhint %}
#### Step 1: Run Settings
| Parameter Name | Required | Description |
| ------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Run Name | Required | Run Name can contain 255 alphanumeric characters, dashes, underscores, periods, and spaces; and must start with an alphanumeric, a dash or an underscore. |
| Run Description | Optional | Run Description can contain 255 characters except square brackets, asterisks, and commas. |
| Instrument Platform | Required |
Choose from TSO 500 ctDNA supported instruments:
NovaSeq 6000/6000Dx
NovaSeq X Series
|
| Secondary Analysis | Required |
BaseSpace/Platform Core (to generate sample sheet for cloud analysis. May also be used for analysis on a DRAGEN server.)
Local (only for analysis onboard the sequencer— not applicable to TSO 500 ctDNA)
None (to generate a sample sheet for analysis on a DRAGEN server. Note that cloud sample sheets may also be used for local analysis.)
|
| Read 1 | Required on Instrument Platform NovaSeq X Series |
Fill with value 151 for TSO 500 ctDNA analysis
|
| Index 1 | Required on Instrument Platform NovaSeq X Series |
Fill with value 10 for TSO 500 ctDNA analysis
|
| Index 2 | Required on Instrument Platform NovaSeq X Series |
Fill with value 10 for TSO 500 ctDNA analysis
|
| Read 2 | Required on Instrument Platform NovaSeq X Series |
Fill with value 151 for TSO 500 ctDNA analysis
|
| Sample Container ID | Optional |
Unique Identifier for the container that holds the sample
|
#### Step 2: Configuration
{% hint style="info" %}
Note: On NovaSeq X Series, this page is called "Configuration 1". The right hand corner of the UI displays the Read 1, Read 2, Index 1 and Index 2 entered on the previous run settings screen.
{% endhint %}
| Parameter Name | Required | Description |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Application | Required |
|
| Description | Optional | Optional text field |
| Library Prep Kit | Required |
TruSight Oncology 500 ctDNA (only for NovaSeq 6000/6000Dx instruments)
TruSight Oncology 500 ctDNA v2
|
| Index Adapter Kit | Required |
TSO 500 ctDNA:
TruSight Oncology 500 ctDNA (NovaSeq6000Dx)
TruSight Oncology 500 ctDNA (NovaSeq6000)
TSO 500 ctDNA v2:
TruSight Oncology 500 ctDNA Index Set A and B (UDP 1-192) (NovaSeq6000Dx, NovaSeqX Series)
TruSight Oncology 500 ctDNA Index Set A and B (UDP 1-192) (NovaSeq6000)
|
#### Step 3: Sample Settings
Users can manually enter sample information, or download a template file to bulk upload sample information. Users can import the completed template or a compatible sample sheet.
| Parameter Name | Required | Description |
| -------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read Lengths: Read 1 and Read 2 |
Required Not applicable on NovaSeq X Series
| Auto filled with the standard values, but can be optionally overwritten. |
| Override Cycles | Required on NovaSeq X Series | Entered based on Run Settings read lengths & index 1 / index 2 |
| Lane Usage | Not applicable on NovaSeq X Series | Checkbox allows users to apply the same lane across samples. |
| Lane | Required if Lane Usage is unchecked | Specify lanes for each sample. The unmarked checkbox at the top of the dropdown selects all lanes. |
| Index ID | Required | Index set ID options are based on selected Index Adapter Kit |
| Project | Optional | Optional field to describe the associated project |
| Starts from Fastq | Required |
True or False
If auto-launching TSO 500 ctDNA from BCL files, set the value to False. If auto-launching TSO 500 ctDNA from FASTQ after auto-launching BCL Convert, set the value to True.
|
|
DNA Barcode Mismatches Index 1
DNA Barcode Mismatches Index 2
| Required on NovaSeq X |
Default value is set to 1.
These fields are required by NovaSeq X and represent BCL Convert settings for index diversity checks when demultiplexing. These values are not used in TSO 500 ctDNA analysis.
|
| Reference Genome | Required starting in v2.6.4 | The genome assembly used as the alignment and analysis reference. Possible values: "hg19" or "hg38". Default value is set to hg19. |
#### Step 4: Run Review
Once all details are captured and pass validation, the user can review the details on the Run Review screen. From here they can choose to edit details in previous screens or export the sample sheet. Once completed, press the Cancel button to finish run planning.
**Note**: once leaving this screen, the run and sample sheet will not be accessible.
For NovaSeqX Plus users, the run can be saved as a draft or as a planned run (via “Save as Draft” and “Save as Planned” buttons respectively). Either selection will save the run to the Planned Runs screen on BaseSpace. There is no option to export the sample sheet on this screen.
### Planned Runs Screen (NovaSeq X Series only)
The Planned Runs screen lists all planned or drafted runs. Users can set drafted runs to planned, export the sample sheet, and edit or delete a run on this screen.
Once the run is saved as Planned, it will appear on the NovaSeq X Series instrument where it can be selected for sequencing.
For more information on run planning, refer to the [BaseSpace Sequence Hub support site page](https://help.basespace.illumina.com/).
### Guided Examples
Please review these guided examples of analysis workflows that include a step of setting up a run in BaseSpace Run Planning tool:
* [NovaSeq 6000Dx: TSO 500 Auto-launch Analysis in Cloud](https://help.connected.illumina.com/cross-product-tutorials/autolaunch-novaseqdx-tso500)
# Multi-Assay Flow Cells
How to plan a run and analyze data with multiple assays loaded individually per lane on one flow cell.
## Introduction
The NovaSeq X platform supports loading samples from different assays into different lanes within a single sequencing run. To ensure compatibility, the DRAGEN TSO 500 ctDNA v2.6.3 and v2.6.4 analysis softwares support sample sheets containing multiple data sections, with one section per assay (for example, TSO500S\_Data and TSO500L\_Data).
This section describes how the software validates and processes multi-assay sample sheets and details the specific rules and logic applied during validation.
## Planning a Run with a Multi-Assay Flow Cell
1. In the BaseSpace Sequence Hub home page, click "Runs" -> "New Run" -> "Run Planning".
2. In the "Create a Run" page, select "NovaSeq X Series" as instrument platform.
3. Provide information for the first assay until the "Run Review" page.
* For TSO 500 or TSO 500 ctDNA assays, to auto-launch multiple pipelines at once, set "[Starts from FASTQ](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/launching-analysis/analysis-launch-on-ica/auto-launch-of-dragen-tso-500-ctdna-analysis-on-ica/auto-launch-with-fastqs-generated-by-standalone-bcl-convert-pipeline-start-from-fastq)" to True
4. In the "Run Review" page, click "Add another configuration" to add the sample prep info for the second assay.
5. A sample sheet containing multiple data sections (one per assay) will be available for exporting at the end of run planning.
## Analyzing Data from a Multi-Assay Flow Cell
### **Sample Sheet Validation**
The sample sheet validator determines which data section(s) to validate based on the active workflow type. The list of samples to process is generated only from the relevant section (for example, Solid or ctDNA). This ensures that only valid samples for the selected workflow are validated.
The workflow’s data section may contain fewer samples than the BCLConvert\_Data section. However, all samples listed in the workflow data section must exist in BCLConvert\_Data section. The downstream pipeline will only process samples found in the workflow-specific data section.
#### **Library Prep Kits**
Multi-assay sample sheets may include multiple library prep kits values separated by semicolons (";").
Validation Logic:
| Workflow Type | Validation Logic | Example of Accepted Values |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| **Solid** | One and only one value must match the predefined Solid kit set: `TSO500`, `TSO500HT`, or `TSO500_v2`. The validation fails if none or more than one valid Solid kit is provided. The validated value will be written into the intermediate sample sheet for baseline selection. | `TSO500HT` |
| **ctDNA** | The library prep kit and the `Sequencing_Settings` section are not required. The library prep kit validation rule is skipped, and the `Sequencing_Settings` section is excluded from the intermediate sample sheet. | *N/A* |
#### **Adapter Reads**
When working with multiple assays, the "AdapterRead" field in the sample sheet may include multiple adapter sequences separated by "+". The adapter read of the selected workflow will be filled in the intermediate sample sheet.
#### **Override Cycles**
Override cycles are determined by the index and read length specified in the "Reads" section of the RunInfo.xml file and assay specifics. For multi-assay flow cells, the index and read length provided in RunInfo.xml should be the longer of the sequencing cycles required by the two assays. Override cycles for assays requiring shorter indexes and read lengths will be padded to match the cycle lengths used in the run.
#### **BCL Convert Settings and Data**
**Starting from BCL:**
* Sample Sheet Validator recalculates and inserts the correct override cycles into the BCLConvert\_Data section of the intermediate sample sheet.
* If index lengths vary, the logic has been enhanced to automatically pad shorter indexes with `"N"` to standardize cycle lengths.
* Sample Sheet Validator also writes in values for: Adapter Reads, MaskShortReads, AdapterBehavior, MinimumTrimmedReadLength. These values are based on the TSO 500 ctDNA library prep kit determined from the input sample sheet.
* The intermediate sample sheet includes only samples relevant to the workflow type (Solid or ctDNA).
* BCL Convert (inside the TSO 500 ctDNA workflow) then generates FASTQ files only for those samples.
**Starting from FASTQ:**
* If users run BCL Convert separately to generate FASTQ files:
* The input sample sheet must already contain valid override cycles, adapter reads, and other BCL Convert Settings.
* The resulting TSO 500 ctDNA workflow run will start from FASTQ input files.
* BCLConvert\_Settings and BCLConvert\_Data sections will be excluded from the intermediate sample sheet created by the TSO 500 ctDNA workflow.
### **BaseSpace Autolaunch**
Analyses of samples in multi-assay flow cells can be launched simultaneously from BaseSpace. As long as "Starts from FASTQ" is set to True in Analysis Settings, all samples from a multi-assay flow cell will be demultiplexed first to generate FASTQ files. Then, the Platform Core pipelines (e.g. DRAGEN TSO 500, DRAGEN TSO 500 ctDNA) will be launched simultaneously to process the samples for each of the assays.
{% hint style="success" %}
For more information about auto-launching BCL Convert before starting TSO 500 analysis from FASTQ, see [Auto-Launch with FASTQs generated by Standalone BCL Convert Pipeline (Start from FASTQ)](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/launching-analysis/analysis-launch-on-ica/auto-launch-of-dragen-tso-500-ctdna-analysis-on-ica/auto-launch-with-fastqs-generated-by-standalone-bcl-convert-pipeline-start-from-fastq)
{% endhint %}
### Summary of Rule Changes
| Component | Update Summary | Effect |
| ------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Sample Index Rule** | Filtered to process samples only from workflow-specific data section | Prevents validation failures for multi-assay sample sheets |
| **Sample Parity Rule** | Enforces that workflow samples exist in BCLConvert\_Data | Ensures downstream consistency |
| **Library Prep Kit Rule** | Supports multiple values separated by `;` | Allows multi-assay sample sheets |
| **Adapter Read Rule** | Supports multiple adapters separated by `+` | Expands flexibility across assays |
| **Override Cycles** | Auto-calculated or user-provided depending on workflow | Maintains correct cycle definitions per sample |
# NovaSeq 6000Dx Run Set Up
The following instructions describe steps to set up a run on NovaSeq 6000Dx Analysis Application.
Use the following steps to configure a TruSight™ Oncology 500 ctDNA run in Illumina Run Manager.
1. Go to the "Runs" section of Illumina Run Manager by selecting "Runs" on the left-hand side.
2. Enter sample data manually or by importing a sample sheet
3. To enter sample data run manually, select “Create Run”.
4. Choose "DRAGEN TruSight™ Oncology 500 ctDNA Analysis Application" from the "Create Run" screen to set-up and analyze runs for TruSight Oncology 500 ctDNA assay.
## Run Settings
1. On the "Run Settings" screen, enter a run name with the following criteria:
1. 1 - 40 characters.
2. Alphanumeric characters, underscores, or dashes only.
3. Unique across all runs on the instrument.
The run name identifies the run from sequencing through analysis.
2. \[Optional] Enter a run description. The run description must have the following criteria:
1. 1 - 50 characters.
2. Alphanumeric characters or spaces only.
3. Spaces must be preceded and followed by an alphanumeric character.
3. Select kit used during library preparation:
1. TruSight Oncology 500 ctDNA
2. TruSight Oncology 500 ctDNA v2
4. Index adapter kit will be automatically selected based on the library prep kit selection
5. \[Optional] Enter a library tube ID.
Depending on the library prep kit selected, additional fields will be populated for run settings and are not editable. Read and index lengths will differ between library prep kit type.
## Sample Data
Use the table on the "Sample Data" screen to enter sample information manually.
Alternately, select Import Samples to upload sample information. Refer to[ NovaSeq 6000Dx Analysis Application: Sample Sheet Requirements](/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/run-planning/sample-sheet-requirements#novaseq-6000dx-analysis-application-sample-sheet-requirements) for sample sheet requirements.
1. Select lane information. Options include one to four, or all lanes.
2. Enter a unique sample ID in the sample ID field with the following criteria:
1. Controls should be added first.
2. 1 - 40 characters.
3. Alphanumeric characters, underscores, or dashes only.
4. Underscores and dashes must be preceded and followed by an alphanumeric character.
3. Select an index set ID for the DNA library prepared from the sample.
4. \[Optional] Enter a library name.
Depending on the options selected for index set ID, additional fields will be auto-populated for sample data and are not editable.
## Sample Settings
Use the table on the "Sample Settings" screen to enter additional sample information.
1. \[Optional] Enter a sample name with the following criteria:
1. 1 - 50 characters.
2. Alphanumeric characters, dashes, underscores, or spaces.
3. Spaces, underscores, and dashes must be preceded and followed by an alphanumeric character.
2. \[Optional] Enter a sample description with the following criteria:
1. 1 - 50 characters.
2. Alphanumeric characters, dashes, underscores, or spaces.
3. Spaces, underscores, and dashes must be preceded and followed by an alphanumeric character.
Additional fields will be auto-populated based on selections made in the Sample Data screen, which are not editable.
Before starting your run, review that the information entered is correct in the “Run Review” page before saving.
---
[Next Page](/llms-full.txt/1)