The bcl2Fastq software converts basecalls from Illumina High Throughput Sequencing (HTS) machines to fastQ files containing sequence information ready for further analysis.
The conversion of basecalls using the bcl2Fastq software requires multiple input files and parameters which allow the software to correctly basecall as well as demultiplex data into relevant samples by any index information contained within the data.
For detailed information on the latest version of bcl2Fastq software, its’ installation, its’ required input files and generated output files visit the Illumina software’s website here.
The bcl2Fastq software converts basecalls generated by Illumina’s Real Time Analysis (RTA) software to fastQ files. The output from RTA is presented in the directory structure below alongside the required input files runParameters.xml and a user generated SampleSheet.csv.
runParameters.xml - The runParameters.xml is generated by the RTA software during basecalling. This XML file contains information including RTA version, HTS machine used, specification of reads and indexes and number of cycles per read/index.
SampleSheet.csv - A user generated sample sheet , by default to be named SampleSheet.csv, may be present at the top level of directory structure to allow for specification of indexes to Sample IDs/Names. For bcl2Fastq versions >= 2.1.7, this SampleSheet.csv must contain set column names defining samples and their indexes ( Lane, Sample_ID, Sample_Name, Sample_Project, Index, Index2). For more details of sample sheet generation see the Illumina manual.
Alongside generated fastQ files from basecalls, bcl2Fastq produces several output files containing metrics describing the sequencing run. The ConversionStats.xml and DemultiplexingStats.xml files are provided under the Stats folder in the user specified output directory.
ConversionStats.xml - This XML contains information on basecalling per tile including the Cluster count, Yield, YieldQ30 and QualityScoreSum.
DemultiplexingStats.xml - This XML contains information on the demultiplexing of samples including the total, perfectmatch and mismatched barcode counts.
The basecallQC package provides a set of tools to streamline basecalling and demultiplexing using the Illumina bcl2fastq software (versions >= 2.1.7).
The basecallQC package includes functions to:-
The Illumina bcl2fastq program needs a sample sheet to dictate sample names/IDs, indexes and parameters for basecalling and demultiplexing.
The construction of sample sheets for basecalling and demultiplexing requires specific column names,valid Sample names/IDs and correct indexes. The complexity of working with Illumina sample sheets is compounded by the use of different sample sheet specifications before and after version 1.8.9 of the bcl2fastq program.
The basecallQC package uses the validateBCLSheet() function to both “clean” sample sheets to have valid column and sample names as well as to update sample sheets for versions <= 1.8.9 to be compatable with version >= 2.1.7
To update or clean a sample sheet, first the parameters for the Run must be captured using the BCL2FastQparams() function. The resulting BCL2FastQparams object contains information on the Run parsed from the runParameters.xml file such as the actual index length (often required to correct the sample sheet specified lengths).
Once the BCL2FastQparams object has been created, a sample sheet file name can be passed to validateBCLSheet() function alongside the BCL2FastQparams object to create a valid sample sheet data.frame, which may then be written to file.
In this first example we use the validateBCLSheet function to clean a sample sheet to be valid with bcl2Fastq versions >= 2.1.7.
library(basecallQC)
fileLocations <- system.file("extdata",package="basecallQC")
config <- dir(fileLocations,pattern="config.ini",full.names=TRUE)
fileLocations <- system.file(file.path("extdata","testSampleSheets"),package="basecallQC")
runXML <- dir(fileLocations,pattern="runParameters.xml",full.names=TRUE)
sampleSheet <- dir(fileLocations,pattern="*\\.csv",full.names=TRUE)
read.delim(sampleSheet[1],sep=",",header = TRUE,comment.char = "[")
## Sample_Project Lane Sample_ID Name index index2
## 1 EMP 1 A 1 A 1 CGATGT
## 2 EMP 1 B 1 B 1 TGACCA
## 3 EMP 1 C 1 C 1 ACAGTG
## 4 CC 6 08.HDOX37 08.HDOX37 AAGGAGTA CTCTCTAC
## 5 CC 6 08.HDOX39 08.HDOX39 AAGGAGTA GCTACGCT
## 6 CC 6 08.HDOXPC 08.HDOXPC AAGGAGTA AAGAGGCA
## 7 CT 8 PS:N4 PS:N4 CCGTCCCG
## 8 CT 8 CS*N1 CS*N1 GTCCGCAC
## 9 CT 8 CSN3 CSN3 GTGAAACG
This sample sheet contains invalid Sample names e.g. A 1 (whitespace) and 08.HDOX37 (starts with numeric) as well as invalid column headers such as “Name”.
bcl2fastqparams <- BCL2FastQparams(runXML,config,runDir=getwd(),verbose=FALSE)
cleanedSampleSheet <- validateBCLSheet(sampleSheet[1],param=bcl2fastqparams)
head(cleanedSampleSheet)
## # A tibble: 6 × 6
## Sample_Project Lane Sample_ID Sample_Name Index Index2
## <chr> <int> <chr> <chr> <chr> <chr>
## 1 EMP 1 A_1 A_1 CGATGT ""
## 2 EMP 1 B_1 B_1 TGACCA ""
## 3 EMP 1 C_1 C_1 ACAGTG ""
## 4 CC 6 Sample_08_HDOX37 Sample_08_HDOX37 AAGGAGTA "CTCTCTAC"
## 5 CC 6 Sample_08_HDOX39 Sample_08_HDOX39 AAGGAGTA "GCTACGCT"
## 6 CC 6 Sample_08_HDOXPC Sample_08_HDOXPC AAGGAGTA "AAGAGGCA"
In the cleaned samplesheet the column headers have been corrected and invalid Sample IDs converted to valid IDs e.g. 08.HDOX37 has been converted to Sample_HDOX37
Updating a sample sheet from those used with versions <= 1.8.9 to one compatable with versions >= 2.1.7 is done following the same procedure as cleaning a sample sheet.
library(basecallQC)
fileLocations <- system.file("extdata",package="basecallQC")
config <- dir(fileLocations,pattern="config.ini",full.names=TRUE)
fileLocations <- system.file(file.path("extdata","testSampleSheets"),package="basecallQC")
runXML <- dir(fileLocations,pattern="runParameters.xml",full.names=TRUE)
sampleSheet <- dir(fileLocations,pattern="*\\.csv",full.names=TRUE)
read.delim(sampleSheet[2],sep=",",header = TRUE,comment.char = "[")
## FCID Lane SampleID SampleRef Index Description Control
## 1 CADMGANXX 1 A1 A1 CGATGT NA NA
## 2 CADMGANXX 1 B1 B1 TGACCA NA NA
## 3 CADMGANXX 1 C1 C1 ACAGTG NA NA
## 4 CADMGANXX 6 DOX37_08H DOX37_08H CTCTCTAC-AAGGAGTA NA NA
## 5 CADMGANXX 6 DOX39_08H DOX39_08H GCTACGCT-AAGGAGTA NA NA
## 6 CADMGANXX 6 DOXPC_08H DOXPC_08H AAGGAGTA-AAGAGGCA NA NA
## 7 CADMGANXX 8 PSN4 PSN4 CCGTCCCG NA NA
## 8 CADMGANXX 8 CSN1 CSN1 GTCCGCAC NA NA
## 9 CADMGANXX 8 CSN3 CSN3 GTGAAACG NA NA
## Recipe Operator Project
## 1 NA NA EMP
## 2 NA NA EMP
## 3 NA NA EMP
## 4 NA NA CC
## 5 NA NA CC
## 6 NA NA CC
## 7 NA NA CT
## 8 NA NA CT
## 9 NA NA CT
The sample sheet from versions <= 1.8.9 contains many headers which will need to be updated to those used in versions >= 2.1.7 as well as unrequired headers which are maintained as metadata.
The specification of indexes in sample sheets from versions <= 1.8.9 were in a single column with indexes separated by a hyphon. This specification has changed to the explicit inclusion of an Index2 column when using dual indexes, so this to must be updated too.
bcl2fastqparams <- BCL2FastQparams(runXML,config,runDir=getwd(),verbose=FALSE)
cleanedSampleSheet <- validateBCLSheet(sampleSheet[2],param=bcl2fastqparams)
head(cleanedSampleSheet)
## # A tibble: 6 × 11
## Sample_Project Lane Sample_ID Sample_Name Index Index2 FCID Description
## <chr> <int> <chr> <chr> <chr> <chr> <chr> <lgl>
## 1 EMP 1 A1 A1 CGATGT "" CADM… NA
## 2 EMP 1 B1 B1 TGACCA "" CADM… NA
## 3 EMP 1 C1 C1 ACAGTG "" CADM… NA
## 4 CC 6 DOX37_08H DOX37_08H CTCTCTAC "AAGGAG… CADM… NA
## 5 CC 6 DOX39_08H DOX39_08H GCTACGCT "AAGGAG… CADM… NA
## 6 CC 6 DOXPC_08H DOXPC_08H AAGGAGTA "AAGAGG… CADM… NA
## # ℹ 3 more variables: Control <lgl>, Recipe <lgl>, Operator <lgl>
In the resulting updated sample sheet we can see column names have been updated e.g. “SampleID” to “Sample_ID”, and the index column has been automatically split into Index and Index2 columns.
The basecallQC package can also provide the base masks and basecalling/demultiplexing command for bcl2fastq versions >= 2.1.7 from the cleaned sample sheet and the BCL2FastQparams object.
The createBaseMasks() function creates a data.frame of basemasks per lane from a cleaned sample sheet,as generated by the validateBCLsheet() function, and a BCL2FastQparams object.
fileLocations <- system.file("extdata",package="basecallQC")
runXML <- dir(fileLocations,pattern="runParameters.xml",full.names=TRUE)
config <- dir(fileLocations,pattern="config.ini",full.names=TRUE)
sampleSheet <- dir(fileLocations,pattern="*\\.csv",full.names=TRUE)
bcl2fastqparams <- BCL2FastQparams(runXML,config,runDir=getwd(),verbose=FALSE)
cleanedSampleSheet <- validateBCLSheet(sampleSheet,param=bcl2fastqparams)
baseMasks <- createBasemasks(cleanedSampleSheet,param=bcl2fastqparams)
baseMasks$index1Mask
## [1] "IIIIIIIIN" "IIIIIIIIN" "IIIIIIIIN" "IIIIIINNN" "IIIIIINNN" "IIIIIIIIN"
## [7] "IIIIIINNN" "IIIIIINNN"
Following the creation of a base masks data.frame, the createBCLcommand function takes the cleaned sample sheet, a BCL2FastQparams object and the base masks data.frame to create the command to be used for Illumina basecalling/demultiplexing using bcl2fastq versions >= 2.1.7.
The command is returned as a character string to allow the user to control submission of the command to best fit the user’s system.
## [1] "/usr/local/bcl2fastq/bin/bcl2fastq --output-dir /tmp/RtmpJspG9J/Rbuild18d04a6251bd/basecallQC/vignettes/C7JE1ANXX --sample-sheet /tmp/RtmpJspG9J/Rbuild18d04a6251bd/basecallQC/vignettes/C7JE1ANXX.csv --use-bases-mask 1:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN,IIIIIIIIN,YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN --use-bases-mask 2:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN,IIIIIIIIN,YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN --use-bases-mask 3:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN,IIIIIIIIN,YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN --use-bases-mask 4:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN,IIIIIINNN,YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN --use-bases-mask 5:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN,IIIIIINNN,YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN --use-bases-mask 6:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN,IIIIIIIIN,YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN --use-bases-mask 7:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN,IIIIIINNN,YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN --use-bases-mask 8:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN,IIIIIINNN,YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYN"
Alongside generating fastQ from basecalls, the bcl2fastq software (versions >= 2.1.7) produces a number of basecalling and demultiplexing metric outputs in differing file types. The basecallQC package retrieves information from basecalling and demultiplexing XML files, ConversionStats.xml and DemultiplexingStats.xml respectively.
The baseCallMetrics() function accepts the BCL2FastQparams object for the Run and retrieve metrics from the ConversionStats.xml file.
## Project Sample Lane Tile Filter ReadNumber Yield Yield30
## 1 default Undetermined 1 2201 Raw Read_1 2062800 1241066
## 2 default Undetermined 1 2201 Raw Read_2 2062800 906623
## 3 default Undetermined 1 2201 Pf Read_1 1220300 1063657
## 4 default Undetermined 1 2201 Pf Read_2 1220300 801579
## 5 default Undetermined 1 1108 Raw Read_1 1705200 977058
## 6 default Undetermined 1 1108 Raw Read_2 1705200 739370
## QualityScoreSum ClusterCount
## 1 54066553 20628
## 2 41324426 20628
## 3 40915399 12203
## 4 31764167 12203
## 5 43532066 17052
## 6 34183713 17052
The baseCallMetrics() function returns a list where the first element contains the full unsummarised basecalling metrics from the ConversionStats.xml file. The second element contains these metrics summarised by Sample, Lane and Tile.
In the same way, the demultiplexMetrics() function accepts the BCL2FastQparams object for the Run and retrieve metrics from the DemultiplexingStats.xml file.
## Project Sample Barcode BarcodeStat Lane Count
## 1 default Undetermined unknown BarcodeCount Lane1 973835
## 2 default Undetermined unknown PerfectBarcodeCount Lane1 973835
## 3 default all all BarcodeCount Lane1 973835
## 4 default all all PerfectBarcodeCount Lane1 973835
## 5 KGAK ALDIAGNCD138NEG ATTACTCG BarcodeCount Lane1 63414244
## 6 KGAK ALDIAGNCD138NEG ATTACTCG PerfectBarcodeCount Lane1 63161421
Again the demultiplexMetrics() function returns a list where the first element contains the full unsummarised demultiplexing metrics from the DemultiplexingStats.xml file. The second element contains these metrics filtered to sample information.
The lists objects generated by demultiplexMetrics() and baseCallMetrics() functions may then be used by plotting and table reporting functions shown in Section 3.
The basecallQC package provides a pipeline function, basecallQC(), to allow the user to clean/convert the samplesheet, create the bcl2fastq command and parse any basecalling/demultiplexing results. The resulting basecallQC object can then be used to produce summary tables, plots and a report.
The basecallQC() function takes a BCL2FastQparams object for the Run, a sample sheet and any Run metadata that the user wishes to attach to their experiment and returns a basecallQC object.
The resulting basecallQC object can be used with basecallQC’s plotting and reporting functions.
fileLocations <- system.file("extdata",package="basecallQC")
runXML <- dir(fileLocations,pattern="runParameters.xml",full.names=TRUE)
config <- dir(fileLocations,pattern="config.ini",full.names=TRUE)
sampleSheet <- dir(fileLocations,pattern="*\\.csv",full.names=TRUE)
outDir <- file.path(fileLocations,"Runs/161105_D00467_0205_AC9L0AANXX/C9L0AANXX/")
bcl2fastqparams <- BCL2FastQparams(runXML,config,runDir=getwd(),outDir,verbose=FALSE)
bclQC <- basecallQC(bcl2fastqparams,RunMetaData=NULL,sampleSheet)
class(bclQC)
## [1] "basecallQC"
## attr(,"package")
## [1] "basecallQC"
The basecallQC object and the lists returned from baseCallMetrics()/demultiplexMetrics() functions contain metrics on basecalling and/or demultiplexing for the Run. The objects can be used for both plotting and table reporting using the basecallQC functions seen in this section. In this following section we will demonstrate plotting from a basecallQC object.
Summary HTML tables from demultiplexing and basecalling results can be generated using the summaryDemuxTable and summaryConvStatsTable respectively. The output argument can be set to “static” or “html” to allow for tables for use in non-interactive and interactive modes.
The user may also visualise the results using basecallQC’s plotting functions for basecalling and demultiplexing summary metrics.
The passFilterBar function produces a bar plot of yields per sample. The metric to plot and how to summarise data for plotting are controlled by the metricToPlot and groupBy arguments.
The passFilterTilePlot produces a plot of the specified metric across the Lanes and Tiles of the investigated Run.
## $PassFilter
##
## $FailFilter
The demuxBarplot function produces a bar plot of yield from demultiplexing. For demultiplexing statistics only the groupBy arguments can be used.
The basecallQC package allows the user to generate a report per Illumina Run from the basecallQC object containing the most important demultiplexing and basecalling metrics using the reportBCL() function.
This report may be customised and the resulting RMD passed to the reportBCL() function’s reportRMDfile argument. This RMD will then be used in place of the standard basecallQC report.
## R version 4.4.2 (2024-10-31)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.1 LTS
##
## Matrix products: default
## BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so; LAPACK version 3.12.0
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_US.UTF-8 LC_COLLATE=C
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## time zone: Etc/UTC
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] basecallQC_1.31.0 yaml_2.3.10 prettydoc_0.4.1 knitr_1.49
## [5] rmarkdown_2.29 BiocStyle_2.35.0
##
## loaded via a namespace (and not attached):
## [1] tidyselect_1.2.1 farver_2.1.2
## [3] dplyr_1.1.4 Biostrings_2.75.1
## [5] bitops_1.0-9 fastmap_1.2.0
## [7] lazyeval_0.2.2 GenomicAlignments_1.43.0
## [9] XML_3.99-0.17 digest_0.6.37
## [11] lifecycle_1.0.4 pwalign_1.3.0
## [13] terra_1.7-83 magrittr_2.0.3
## [15] compiler_4.4.2 rlang_1.1.4
## [17] sass_0.4.9 tools_4.4.2
## [19] utf8_1.2.4 data.table_1.16.2
## [21] labeling_0.4.3 S4Arrays_1.7.1
## [23] htmlwidgets_1.6.4 interp_1.1-6
## [25] sp_2.1-4 DelayedArray_0.33.2
## [27] RColorBrewer_1.1-3 ShortRead_1.65.0
## [29] abind_1.4-8 BiocParallel_1.41.0
## [31] withr_3.0.2 purrr_1.0.2
## [33] hwriter_1.3.2.1 BiocGenerics_0.53.3
## [35] sys_3.4.3 grid_4.4.2
## [37] stats4_4.4.2 fansi_1.0.6
## [39] latticeExtra_0.6-30 colorspace_2.1-1
## [41] ggplot2_3.5.1 scales_1.3.0
## [43] SummarizedExperiment_1.37.0 cli_3.6.3
## [45] crayon_1.5.3 generics_0.1.3
## [47] httr_1.4.7 cachem_1.1.0
## [49] stringr_1.5.1 zlibbioc_1.52.0
## [51] parallel_4.4.2 BiocManager_1.30.25
## [53] XVector_0.47.0 matrixStats_1.4.1
## [55] vctrs_0.6.5 Matrix_1.7-1
## [57] jsonlite_1.8.9 IRanges_2.41.1
## [59] S4Vectors_0.45.2 crosstalk_1.2.1
## [61] jpeg_0.1-10 maketools_1.3.1
## [63] tidyr_1.3.1 jquerylib_0.1.4
## [65] glue_1.8.0 codetools_0.2-20
## [67] DT_0.33 stringi_1.8.4
## [69] gtable_0.3.6 deldir_2.0-4
## [71] GenomeInfoDb_1.43.2 raster_3.6-30
## [73] GenomicRanges_1.59.1 UCSC.utils_1.3.0
## [75] munsell_0.5.1 tibble_3.2.1
## [77] pillar_1.9.0 htmltools_0.5.8.1
## [79] GenomeInfoDbData_1.2.13 R6_2.5.1
## [81] evaluate_1.0.1 lattice_0.22-6
## [83] Biobase_2.67.0 png_0.1-8
## [85] Rsamtools_2.23.1 bslib_0.8.0
## [87] Rcpp_1.0.13-1 SparseArray_1.7.2
## [89] xfun_0.49 MatrixGenerics_1.19.0
## [91] buildtools_1.0.0 pkgconfig_2.0.3