This document gives an overview of the DNABarcodeCompatibility R package with a brief description of the set of tools that it contains. The package includes six main functions that are briefly described below with examples. These functions allow one to load a list of DNA barcodes (such as the Illumina TruSeq small RNA kits), to filter these barcodes according to distance and nucleotide content criteria, to generate sets of compatible barcode combinations out of the filtered barcode list, and finally to generate an optimized selection of barcode combinations for multiplex sequencing experiments. In particular, the package provides an optimizer function to favour the selection of compatible barcode combinations with least heterogeneity in the frequencies of DNA barcodes, and allows one to keep barcodes that are robust against substitution and insertion/deletion errors, thereby facilitating the demultiplexing step.
The DNABarcodeCompatibility package also contains:
experiment_design() allowing one to perform all steps
in one go.IlluminaIndexesRaw and IlluminaIndexes for running
and testing examples.The package deals with the three existing sequencing-by-synthesis chemistries from Illumina:
library("DNABarcodeCompatibility")# This function is created for the purpose of the documentation
export_dataset_to_file =
function(dataset = DNABarcodeCompatibility::IlluminaIndexesRaw) {
if ("data.frame" %in% is(dataset)) {
write.table(dataset,
textfile <- tempfile(),
row.names = FALSE, col.names = FALSE, quote=FALSE)
return(textfile)
} else print(paste("The input dataset isn't a data.frame:",
"NOT exported into file"))
}The function experiment_design() uses a Shannon-entropy maximization approach
to identify a set of compatible barcode combinations in which the frequencies
of occurrences of the various DNA barcodes are as uniform as possible.
The optimization can be performed in the contexts of single and dual barcoding.
It performs either an exhaustive or a random search of compatible DNA-barcode
combinations, depending on the size of the DNA-barcode set used, and on the
number of samples to be multiplexed.
txtfile <- export_dataset_to_file (
dataset = DNABarcodeCompatibility::IlluminaIndexesRaw
)
experiment_design(file1=txtfile,
sample_number=12,
mplex_level=3,
platform=4)
## [1] "Theoretical max entropy: 2.48491"
## [1] "Entropy of the optimized set: 2.48491"
## sample Lane Id sequence
## 1 1 1 RPI06 GCCAAT
## 2 2 1 RPI12 CTTGTA
## 3 3 1 RPI24 GGTAGC
## 4 4 2 RPI17 GTAGAG
## 5 5 2 RPI26 ATGAGC
## 6 6 2 RPI36 CCAACA
## 7 7 3 RPI19 GTGAAA
## 8 8 3 RPI30 CACCGG
## 9 9 3 RPI35 CATTTT
## 10 10 4 RPI02 CGATGT
## 11 11 4 RPI22 CGTACG
## 12 12 4 RPI43 TACAGCtxtfile <- export_dataset_to_file (
dataset = DNABarcodeCompatibility::IlluminaIndexesRaw
)
experiment_design(file1=txtfile,
sample_number=12,
mplex_level=3,
platform=2)
## [1] "Theoretical max entropy: 2.48491"
## [1] "Entropy of the optimized set: 2.48491"
## sample Lane Id sequence
## 1 1 1 RPI22 CGTACG
## 2 2 1 RPI41 GACGAC
## 3 3 1 RPI46 TCCCGA
## 4 4 2 RPI04 TGACCA
## 5 5 2 RPI25 ACTGAT
## 6 6 2 RPI26 ATGAGC
## 7 7 3 RPI05 ACAGTG
## 8 8 3 RPI29 CAACTA
## 9 9 3 RPI42 TAATCG
## 10 10 4 RPI27 ATTCCT
## 11 11 4 RPI28 CAAAAG
## 12 12 4 RPI36 CCAACAtxtfile <- export_dataset_to_file (
dataset = DNABarcodeCompatibility::IlluminaIndexesRaw
)
experiment_design(file1=txtfile,
sample_number=12,
mplex_level=3,
platform=1)
## [1] "Theoretical max entropy: 2.48491"
## [1] "Entropy of the optimized set: 2.48491"
## sample Lane Id sequence
## 1 1 1 RPI06 GCCAAT
## 2 2 1 RPI34 CATGGC
## 3 3 1 RPI42 TAATCG
## 4 4 2 RPI05 ACAGTG
## 5 5 2 RPI13 AGTCAA
## 6 6 2 RPI44 TATAAT
## 7 7 3 RPI04 TGACCA
## 8 8 3 RPI31 CACGAT
## 9 9 3 RPI45 TCATTC
## 10 10 4 RPI25 ACTGAT
## 11 11 4 RPI29 CAACTA
## 12 12 4 RPI32 CACTCAtxtfile <- export_dataset_to_file (
dataset = DNABarcodeCompatibility::IlluminaIndexesRaw
)
experiment_design(file1=txtfile,
sample_number=12,
mplex_level=3,
platform=4,
metric = "hamming",
d = 3)
## [1] "Theoretical max entropy: 2.48491"
## [1] "Entropy of the optimized set: 2.48491"
## sample Lane Id sequence
## 1 1 1 RPI15 ATGTCA
## 2 2 1 RPI43 TACAGC
## 3 3 1 RPI44 TATAAT
## 4 4 2 RPI19 GTGAAA
## 5 5 2 RPI26 ATGAGC
## 6 6 2 RPI42 TAATCG
## 7 7 3 RPI01 ATCACG
## 8 8 3 RPI21 GTTTCG
## 9 9 3 RPI45 TCATTC
## 10 10 4 RPI03 TTAGGC
## 11 11 4 RPI25 ACTGAT
## 12 12 4 RPI36 CCAACA# Select the first half of barcodes from the dataset
txtfile1 <- export_dataset_to_file (
DNABarcodeCompatibility::IlluminaIndexesRaw[1:24,]
)
# Select the second half of barcodes from the dataset
txtfile2 <- export_dataset_to_file (
DNABarcodeCompatibility::IlluminaIndexesRaw[25:48,]
)
# Get compatibles combinations of least redundant barcodes
experiment_design(file1=txtfile1,
sample_number=12,
mplex_level=3,
platform=4,
file2=txtfile2)
## [1] "Theoretical max entropy: 2.48491"
## [1] "Entropy of the optimized set: 2.48491"
## Id Lane
## 1 RPI01 1
## 2 RPI16 1
## 3 RPI18 1
## 4 RPI04 2
## 5 RPI08 2
## 6 RPI23 2
## 7 RPI05 3
## 8 RPI07 3
## 9 RPI20 3
## 10 RPI06 4
## 11 RPI09 4
## 12 RPI12 4
## [1] "Theoretical max entropy: 2.48491"
## [1] "Entropy of the optimized set: 2.48491"
## Id Lane
## 1 RPI35 1
## 2 RPI39 1
## 3 RPI43 1
## 4 RPI27 2
## 5 RPI34 2
## 6 RPI42 2
## 7 RPI32 3
## 8 RPI37 3
## 9 RPI46 3
## 10 RPI26 4
## 11 RPI38 4
## 12 RPI44 4
## Id Lane sequence
## 1 RPI01 1 ATCACG
## 2 RPI16 1 CCGTCC
## 3 RPI18 1 GTCCGC
## 4 RPI04 2 TGACCA
## 5 RPI08 2 ACTTGA
## 6 RPI23 2 GAGTGG
## 7 RPI05 3 ACAGTG
## 8 RPI07 3 CAGATC
## 9 RPI20 3 GTGGCC
## 10 RPI06 4 GCCAAT
## 11 RPI09 4 GATCAG
## 12 RPI12 4 CTTGTA
## Id Lane sequence
## 1 RPI35 1 CATTTT
## 2 RPI39 1 CTATAC
## 3 RPI43 1 TACAGC
## 4 RPI27 2 ATTCCT
## 5 RPI34 2 CATGGC
## 6 RPI42 2 TAATCG
## 7 RPI32 3 CACTCA
## 8 RPI37 3 CGGAAT
## 9 RPI46 3 TCCCGA
## 10 RPI26 4 ATGAGC
## 11 RPI38 4 CTAGCT
## 12 RPI44 4 TATAAT
## sample Lane Id1 sequence1 Id2 sequence2
## 1 1 1 RPI01 ATCACG RPI35 CATTTT
## 2 2 1 RPI16 CCGTCC RPI39 CTATAC
## 3 3 1 RPI18 GTCCGC RPI43 TACAGC
## 4 4 2 RPI04 TGACCA RPI27 ATTCCT
## 5 5 2 RPI08 ACTTGA RPI34 CATGGC
## 6 6 2 RPI23 GAGTGG RPI42 TAATCG
## 7 7 3 RPI05 ACAGTG RPI32 CACTCA
## 8 8 3 RPI07 CAGATC RPI37 CGGAAT
## 9 9 3 RPI20 GTGGCC RPI46 TCCCGA
## 10 10 4 RPI06 GCCAAT RPI26 ATGAGC
## 11 11 4 RPI09 GATCAG RPI38 CTAGCT
## 12 12 4 RPI12 CTTGTA RPI44 TATAAT# Select the first half of barcodes from the dataset
txtfile1 <- export_dataset_to_file (
DNABarcodeCompatibility::IlluminaIndexesRaw[1:24,]
)
# Select the second half of barcodes from the dataset
txtfile2 <- export_dataset_to_file (
DNABarcodeCompatibility::IlluminaIndexesRaw[25:48,]
)
# Get compatibles combinations of least redundant barcodes
experiment_design(file1=txtfile1, sample_number=12, mplex_level=3, platform=4,
file2=txtfile2, metric="hamming", d=3)
## [1] "Theoretical max entropy: 2.48491"
## [1] "Entropy of the optimized set: 2.48491"
## Id Lane
## 1 RPI07 1
## 2 RPI09 1
## 3 RPI17 1
## 4 RPI04 2
## 5 RPI13 2
## 6 RPI23 2
## 7 RPI01 3
## 8 RPI06 3
## 9 RPI12 3
## 10 RPI05 4
## 11 RPI18 4
## 12 RPI22 4
## [1] "Theoretical max entropy: 2.48491"
## [1] "Entropy of the optimized set: 2.48491"
## Id Lane
## 1 RPI27 1
## 2 RPI34 1
## 3 RPI41 1
## 4 RPI38 2
## 5 RPI43 2
## 6 RPI47 2
## 7 RPI26 3
## 8 RPI39 3
## 9 RPI42 3
## 10 RPI37 4
## 11 RPI44 4
## 12 RPI45 4
## Id Lane sequence
## 1 RPI07 1 CAGATC
## 2 RPI09 1 GATCAG
## 3 RPI17 1 GTAGAG
## 4 RPI04 2 TGACCA
## 5 RPI13 2 AGTCAA
## 6 RPI23 2 GAGTGG
## 7 RPI01 3 ATCACG
## 8 RPI06 3 GCCAAT
## 9 RPI12 3 CTTGTA
## 10 RPI05 4 ACAGTG
## 11 RPI18 4 GTCCGC
## 12 RPI22 4 CGTACG
## Id Lane sequence
## 1 RPI27 1 ATTCCT
## 2 RPI34 1 CATGGC
## 3 RPI41 1 GACGAC
## 4 RPI38 2 CTAGCT
## 5 RPI43 2 TACAGC
## 6 RPI47 2 TCGAAG
## 7 RPI26 3 ATGAGC
## 8 RPI39 3 CTATAC
## 9 RPI42 3 TAATCG
## 10 RPI37 4 CGGAAT
## 11 RPI44 4 TATAAT
## 12 RPI45 4 TCATTC
## sample Lane Id1 sequence1 Id2 sequence2
## 1 1 1 RPI07 CAGATC RPI27 ATTCCT
## 2 2 1 RPI09 GATCAG RPI34 CATGGC
## 3 3 1 RPI17 GTAGAG RPI41 GACGAC
## 4 4 2 RPI04 TGACCA RPI38 CTAGCT
## 5 5 2 RPI13 AGTCAA RPI43 TACAGC
## 6 6 2 RPI23 GAGTGG RPI47 TCGAAG
## 7 7 3 RPI01 ATCACG RPI26 ATGAGC
## 8 8 3 RPI06 GCCAAT RPI39 CTATAC
## 9 9 3 RPI12 CTTGTA RPI42 TAATCG
## 10 10 4 RPI05 ACAGTG RPI37 CGGAAT
## 11 11 4 RPI18 GTCCGC RPI44 TATAAT
## 12 12 4 RPI22 CGTACG RPI45 TCATTCThis section guides you through the detailed API of the package with the aim to
help you build your own workflow. The package is designed to be flexible and
should be easily adaptable to most experimental contexts, using the
experiment_design() function as a template, or building your own workflow
from scratch.
The file_loading_and_checking() function loads the file containing the DNA
barcodes set and analyzes its content. In particular, it checks that each
barcode in the set is unique and uniquely identified (removing any repetition
that occurs). It also checks the homogeneity of size of the barcodes,
calculates their GC content and detects the presence of homopolymers of
length >= 3.
file_loading_and_checking(
file = export_dataset_to_file(
dataset = DNABarcodeCompatibility::IlluminaIndexesRaw
)
)
## Id sequence GC_content homopolymer
## 1 RPI01 ATCACG 50.00 FALSE
## 2 RPI02 CGATGT 50.00 FALSE
## 3 RPI03 TTAGGC 50.00 FALSE
## 4 RPI04 TGACCA 50.00 FALSE
## 5 RPI05 ACAGTG 50.00 FALSE
## 6 RPI06 GCCAAT 50.00 FALSE
## 7 RPI07 CAGATC 50.00 FALSE
## 8 RPI08 ACTTGA 33.33 FALSE
## 9 RPI09 GATCAG 50.00 FALSE
## 10 RPI10 TAGCTT 33.33 FALSE
## 11 RPI11 GGCTAC 66.67 FALSE
## 12 RPI12 CTTGTA 33.33 FALSE
## 13 RPI13 AGTCAA 33.33 FALSE
## 14 RPI14 AGTTCC 50.00 FALSE
## 15 RPI15 ATGTCA 33.33 FALSE
## 16 RPI16 CCGTCC 83.33 FALSE
## 17 RPI17 GTAGAG 50.00 FALSE
## 18 RPI18 GTCCGC 83.33 FALSE
## 19 RPI19 GTGAAA 33.33 TRUE
## 20 RPI20 GTGGCC 83.33 FALSE
## 21 RPI21 GTTTCG 50.00 TRUE
## 22 RPI22 CGTACG 66.67 FALSE
## 23 RPI23 GAGTGG 66.67 FALSE
## 24 RPI24 GGTAGC 66.67 FALSE
## 25 RPI25 ACTGAT 33.33 FALSE
## 26 RPI26 ATGAGC 50.00 FALSE
## 27 RPI27 ATTCCT 33.33 FALSE
## 28 RPI28 CAAAAG 33.33 TRUE
## 29 RPI29 CAACTA 33.33 FALSE
## 30 RPI30 CACCGG 83.33 FALSE
## 31 RPI31 CACGAT 50.00 FALSE
## 32 RPI32 CACTCA 50.00 FALSE
## 33 RPI33 CAGGCG 83.33 FALSE
## 34 RPI34 CATGGC 66.67 FALSE
## 35 RPI35 CATTTT 16.67 TRUE
## 36 RPI36 CCAACA 50.00 FALSE
## 37 RPI37 CGGAAT 50.00 FALSE
## 38 RPI38 CTAGCT 50.00 FALSE
## 39 RPI39 CTATAC 33.33 FALSE
## 40 RPI40 CTCAGA 50.00 FALSE
## 41 RPI41 GACGAC 66.67 FALSE
## 42 RPI42 TAATCG 33.33 FALSE
## 43 RPI43 TACAGC 50.00 FALSE
## 44 RPI44 TATAAT 0.00 FALSE
## 45 RPI45 TCATTC 33.33 FALSE
## 46 RPI46 TCCCGA 66.67 TRUE
## 47 RPI47 TCGAAG 50.00 FALSE
## 48 RPI48 TCGGCA 66.67 FALSEThe total number of combinations depends on the number of available barcodes
and of the multiplex level. For 48 barcodes and a multiplex level of 3, the
total number of combinations (compatible or not) can be calculated using
choose(48,3), which gives 17296 combinations. In many
cases the total number of combinations can become much larger (even gigantic),
and one cannot perform an exhaustive search
(see get_random_combinations() below).
# Total number of combinations
choose(48,2)
## [1] 1128
# Load barcodes
barcodes <- DNABarcodeCompatibility::IlluminaIndexes
# Time for an exhaustive search
system.time(m <- get_all_combinations(index_df = barcodes,
mplex_level = 2,
platform = 4))
## user system elapsed
## 0.301 0.000 0.301
# Each line represents a compatible combination of barcodes
head(m)
## [,1] [,2]
## [1,] "RPI04" "RPI35"
## [2,] "RPI05" "RPI19"
## [3,] "RPI06" "RPI12"
## [4,] "RPI07" "RPI17"
## [5,] "RPI10" "RPI39"
## [6,] "RPI18" "RPI25"# Total number of combinations
choose(48,3)
## [1] 17296
# Load barcodes
barcodes <- DNABarcodeCompatibility::IlluminaIndexes
# Time for an exhaustive search
system.time(m <- get_all_combinations(index_df = barcodes,
mplex_level = 3,
platform = 4))
## user system elapsed
## 6.393 0.008 6.402
# Each line represents a compatible combination of barcodes
head(m)
## [,1] [,2] [,3]
## [1,] "RPI01" "RPI02" "RPI48"
## [2,] "RPI01" "RPI03" "RPI07"
## [3,] "RPI01" "RPI03" "RPI08"
## [4,] "RPI01" "RPI03" "RPI09"
## [5,] "RPI01" "RPI03" "RPI10"
## [6,] "RPI01" "RPI03" "RPI16"When the total number of combinations is too high, it is recommended to pick combinations at random and then select those that are compatible.
# Total number of combinations
choose(48,3)
## [1] 17296
# Load barcodes
barcodes <- DNABarcodeCompatibility::IlluminaIndexes
# Time for a random search
system.time(m <- get_random_combinations(index_df = barcodes,
mplex_level = 2,
platform = 4))
## user system elapsed
## 0.237 0.000 0.237
# Each line represents a compatible combination of barcodes
head(m)
## [,1] [,2]
## [1,] "RPI05" "RPI19"
## [2,] "RPI06" "RPI12"
## [3,] "RPI07" "RPI17"
## [4,] "RPI10" "RPI39"
## [5,] "RPI18" "RPI33"
## [6,] "RPI20" "RPI30"# Total number of combinations
choose(48,4)
## [1] 194580
# Load barcodes
barcodes <- DNABarcodeCompatibility::IlluminaIndexes
# Time for a random search
system.time(m <- get_random_combinations(index_df = barcodes,
mplex_level = 4,
platform = 4))
## user system elapsed
## 1.418 0.000 1.418
# Each line represents a compatible combination of barcodes
head(m)
## [,1] [,2] [,3] [,4]
## [1,] "RPI01" "RPI19" "RPI23" "RPI37"
## [2,] "RPI01" "RPI18" "RPI20" "RPI41"
## [3,] "RPI01" "RPI08" "RPI09" "RPI11"
## [4,] "RPI01" "RPI17" "RPI30" "RPI34"
## [5,] "RPI01" "RPI24" "RPI25" "RPI42"
## [6,] "RPI01" "RPI23" "RPI39" "RPI46"# Total number of combinations
choose(48,6)
## [1] 12271512
# Load barcodes
barcodes <- DNABarcodeCompatibility::IlluminaIndexes
# Time for a random search
system.time(m <- get_random_combinations(index_df = barcodes,
mplex_level = 6,
platform = 4))
## user system elapsed
## 2.764 0.004 2.768
# Each line represents a compatible combination of barcodes
head(m)
## [,1] [,2] [,3] [,4] [,5] [,6]
## [1,] "RPI01" "RPI09" "RPI34" "RPI37" "RPI45" "RPI47"
## [2,] "RPI01" "RPI07" "RPI19" "RPI29" "RPI35" "RPI43"
## [3,] "RPI01" "RPI02" "RPI08" "RPI23" "RPI26" "RPI41"
## [4,] "RPI01" "RPI08" "RPI11" "RPI19" "RPI23" "RPI31"
## [5,] "RPI01" "RPI03" "RPI05" "RPI08" "RPI29" "RPI41"
## [6,] "RPI01" "RPI02" "RPI10" "RPI27" "RPI39" "RPI48"# Load barcodes
barcodes <- DNABarcodeCompatibility::IlluminaIndexes
# Perform a random search of compatible combinations
m <- get_random_combinations(index_df = barcodes,
mplex_level = 3,
platform = 4)
# Keep barcodes that are robust against one substitution error
filtered_m <- distance_filter(index_df = barcodes,
combinations_m = m,
metric = "hamming",
d = 3)
# Each line represents a compatible combination of barcodes
head(filtered_m)
## V1 V2 V3
## [1,] "RPI01" "RPI06" "RPI12"
## [2,] "RPI01" "RPI10" "RPI48"
## [3,] "RPI01" "RPI03" "RPI34"
## [4,] "RPI01" "RPI04" "RPI35"
## [5,] "RPI01" "RPI10" "RPI32"
## [6,] "RPI01" "RPI34" "RPI47"# Keep set of compatible barcodes that are robust against one substitution
# error
filtered_m <- distance_filter(
index_df = DNABarcodeCompatibility::IlluminaIndexes,
combinations_m = get_random_combinations(index_df = barcodes,
mplex_level = 3,
platform = 4),
metric = "hamming", d = 3)
# Use a Shannon-entropy maximization approach to reduce barcode redundancy
df <- optimize_combinations(combination_m = filtered_m,
nb_lane = 12,
index_number = 48)
## [1] "Theoretical max entropy: 3.58352"
## [1] "Entropy of the optimized set: 3.58352"
# Each line represents a compatible combination of barcodes and each row a lane
# of the flow cell
df
## V1 V2 V3
## [1,] "RPI07" "RPI21" "RPI30"
## [2,] "RPI04" "RPI08" "RPI09"
## [3,] "RPI11" "RPI35" "RPI44"
## [4,] "RPI02" "RPI45" "RPI47"
## [5,] "RPI24" "RPI28" "RPI41"
## [6,] "RPI03" "RPI22" "RPI36"
## [7,] "RPI17" "RPI25" "RPI46"
## [8,] "RPI10" "RPI13" "RPI38"
## [9,] "RPI20" "RPI26" "RPI31"
## [10,] "RPI06" "RPI14" "RPI40"
## [11,] "RPI01" "RPI05" "RPI48"
## [12,] "RPI16" "RPI18" "RPI42"# Keep set of compatible barcodes that are robust against multiple substitution
# and insertion/deletion errors
filtered_m <- distance_filter(
index_df = DNABarcodeCompatibility::IlluminaIndexes,
combinations_m = get_random_combinations(index_df = barcodes,
mplex_level = 3,
platform = 4),
metric = "seqlev", d = 4)
# Use a Shannon-entropy maximization approach to reduce barcode redundancy
df <- optimize_combinations(combination_m = filtered_m,
nb_lane = 12,
index_number = 48)
## [1] "Theoretical max entropy: 3.58352"
## [1] "Entropy of the optimized set: 3.06838"
# Each line represents a compatible combination of barcodes and each row a
# lane of the flow cell
df
## V1 V2 V3
## [1,] "RPI24" "RPI28" "RPI45"
## [2,] "RPI02" "RPI10" "RPI36"
## [3,] "RPI06" "RPI12" "RPI43"
## [4,] "RPI03" "RPI23" "RPI36"
## [5,] "RPI24" "RPI28" "RPI45"
## [6,] "RPI18" "RPI34" "RPI44"
## [7,] "RPI18" "RPI34" "RPI44"
## [8,] "RPI03" "RPI23" "RPI36"
## [9,] "RPI14" "RPI17" "RPI30"
## [10,] "RPI15" "RPI30" "RPI47"
## [11,] "RPI17" "RPI27" "RPI29"
## [12,] "RPI13" "RPI21" "RPI43"