Implement HVR sequence alignment

.gitignore

@@ -1 +1,3 @@
+*.csv
+*.fasta
 *.fastq

README.org

@@ -1,56 +1,3 @@
 * locigenesis
 
-locigenesis is a tool that generates a human T-cell receptor (TCR), runs it through a sequence reader simulation tool and extracts CDR3.
+locigenesis is a tool that generates an immune repertoire and runs it through a sequence reader simulation tool, to generate sequencing errors.
-
-The goal of this project is to generate both HVR sequences with and without sequencing errors, in order to create datasets for a Machine Learning algorithm.
-
-** Technologies
-
-- [[https://github.com/GreiffLab/immuneSIM/][immuneSIM]]: in silico generation of human and mouse BCR and TCR repertoires
-- [[http://www.pegase-biosciences.com/curesim-a-customized-read-simulator/][CuReSim]]: read simulator that mimics Ion Torrent sequencing
-
-** Installation
-
-This project uses [[https://nixos.org/][Nix]] to ensure reproducible builds.
-
-1. Install Nix (compatible with MacOS, Linux and [[https://docs.microsoft.com/en-us/windows/wsl/about][WSL]]):
-
-#+begin_src shell
-curl -L https://nixos.org/nix/install | sh
-#+end_src
-
-1. Clone the repository:
-
-#+begin_src shell
-git clone https://git.coolneng.duckdns.org/coolneng/locigenesis
-#+end_src
-
-3. Change the working directory to the project:
-
-#+begin_src shell
-cd locigenesis
-#+end_src
-
-4. Enter the nix-shell:
-
-#+begin_src shell
-nix-shell
-#+end_src
-
-After running these commands, you will find yourself in a shell that contains all the needed dependencies.
-
-** Usage
-
-An execution script that accepts 2 parameters is provided, the following command invokes it:
-
-#+begin_src shell
-./generation.sh <number of sequences> <number of reads>
-#+end_src
-
-- <number of sequences>: an integer that specifies the number of different sequences to generate
-- <number of reads>: an integer that specifies the number of reads to perform on each sequence
-
-The script will generate 2 files under the data directory:
-
-| HVR.fastq         | Contains the original CDR3 sequence                             |
-| CuReSim-HVR.fastq | Contains CDR3 after the read simulation, with sequencing errors |

docs/notebook.org

@@ -0,0 +1,46 @@
+#+TITLE: locigenesis
+#+AUTHOR: Amin Kasrou Aouam
+#+DATE: 2021-03-10
+* Sequence alignment
+
+Our generated sequences contain the full VJ region, but we are only interested in the CDR3 (Complementarity-determining region). We will proceed by delimiting CDR3, using the known sequences of V and J.
+
+#+begin_src R :results value silent
+v_segments <- readRDS("data/v_segments.rds")
+j_segments <- readRDS("data/j_segments_phe.rds")
+#+end_src
+
+#+begin_src R
+print(v_segments)
+print(j_segments)
+#+end_src
+
+#+RESULTS:
+#+begin_example
+  A DNAStringSet instance of length 147
+      width seq                                             names
+  [1]   326 GATACTGGAATTACCCAGACAC...ATCTCTGCACCAGCAGCCAAGA TRBV1*01_P
+  [2]   326 GATGCTGAAATCACCCAGAGCC...ATTTCTGCGCCAGCAGTGAGTC TRBV10-1*01_F
+  [3]   326 GATGCTGAAATCACCCAGAGCC...ATTTCTGCGCCAGCAGTGAGTC TRBV10-1*02_F
+  [4]   326 GATGCTGGAATCACCCAGAGCC...ATTTCTGCGCCAGCAGTGAGTC TRBV10-2*01_F
+  [5]   326 GATGCTGGAATCACCCAGAGCC...ATTTCTGCGCCAGCAGTGAGTC TRBV10-2*02_F
+  ...   ... ...
+[143]   324 GATACTGGAGTCTCCCAGAACC...GTATCTCTGTGCCAGCACGTTG TRBV7-9*06_(F)
+[144]   323 .........................TGTATCTCTGTGCCAGCAGCAG TRBV7-9*07_(F)
+[145]   325 GATTCTGGAGTCACACAAACCC...TATTTCTGTGCCAGCAGCGTAG TRBV9*01_F
+[146]   325 GATTCTGGAGTCACACAAACCC...TATTTCTGTGCCAGCAGCGTAG TRBV9*02_F
+[147]   321 GATTCTGGAGTCACACAAACCC...TTTGTATTTCTGTGCCAGCAGC TRBV9*03_(F)
+  A DNAStringSet instance of length 16
+     width seq                                              names
+ [1]    32 TGGGCGTCTGGGCGGAGGACTCCTGGTTCTGG                 TRBJ2-2P*01_ORF
+ [2]    31 TTTGGAGAGGGAAGTTGGCTCACTGTTGTAG                  TRBJ1-3*01_F
+ [3]    31 TTTGGTGATGGGACTCGACTCTCCATCCTAG                  TRBJ1-5*01_F
+ [4]    31 TTTGGCAGTGGAACCCAGCTCTCTGTCTTGG                  TRBJ1-4*01_F
+ [5]    31 TTCGGTTCGGGGACCAGGTTAACCGTTGTAG                  TRBJ1-2*01_F
+ ...   ... ...
+[12]    31 TTTGGCCCAGGCACCCGGCTGACAGTGCTCG                  TRBJ2-3*01_F
+[13]    31 TTCGGGCCAGGCACGCGGCTCCTGGTGCTCG                  TRBJ2-5*01_F
+[14]    31 TTCGGGCCAGGGACACGGCTCACCGTGCTAG                  TRBJ2-1*01_F
+[15]    31 TTCGGGCCGGGCACCAGGCTCACGGTCACAG                  TRBJ2-7*01_F
+[16]    31 GTCGGGCCGGGCACCAGGCTCACGGTCACAG                  TRBJ2-7*02_ORF
+#+end_example

generation.sh

@@ -1,7 +1,7 @@
 #!/bin/sh
 
 usage() {
-	echo "usage: generation.sh <number of sequences> <number of reads>"
+	echo "usage: generation.sh <number of sequences> <sequencing runs>"
 	exit 1
 }
 
@@ -10,13 +10,15 @@ if [ $# != 2 ]; then
 fi
 
 sequences=$1
-number_of_reads=$2
+sequencing_runs=$2
+read_mean_size=350
+read_variance_size=0.0
 data_directory="data/"
+fasta=".fasta"
 fastq=".fastq"
 filename="sequence"
 prefix="curesim_"
 
-Rscript src/repertoire.r "$sequences" "$number_of_reads" &&
+Rscript src/repertoire.r "$sequences" "$sequencing_runs"
-	CuReSim -f "$data_directory$filename$fastq" -o "$data_directory$prefix$filename$fastq"
+java -jar tools/CuReSim.jar -m "$read_mean_size" -sd "$read_variance_size" -f "$data_directory$filename$fasta" -o "$data_directory$prefix$filename$fastq"
-Rscript src/alignment.r
 rm "$data_directory/log.txt"

nix/sources.json

@@ -17,10 +17,10 @@
         "homepage": "",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "a565a2165ab6e195d7c105a8416b8f4b4d0349a4",
+        "rev": "6f1ce38d0c0b1b25727d86637fd2f3baf7b0f1f6",
-        "sha256": "1x90qm533lh8xh172rqfcj3pwg8imyx650xgr41rqppmm6fli4w1",
+        "sha256": "16da722vqn96k1scls8mr8l909hl66r7y4ik6sad4ms3vmxbkbb3",
         "type": "tarball",
-        "url": "https://github.com/NixOS/nixpkgs/archive/a565a2165ab6e195d7c105a8416b8f4b4d0349a4.tar.gz",
+        "url": "https://github.com/NixOS/nixpkgs/archive/6f1ce38d0c0b1b25727d86637fd2f3baf7b0f1f6.tar.gz",
         "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz"
     }
 }

shell.nix

@@ -2,29 +2,14 @@
 
 with pkgs;
 
-let
+mkShell {
-  CuReSim = stdenv.mkDerivation rec {
+  buildInputs = [
-    name = "CuReSim";
+    R
-    version = "1.3";
+    rPackages.immuneSIM
-    src = fetchzip {
+    rPackages.Biostrings
-      url =
+    jdk
-        "http://www.pegase-biosciences.com/wp-content/uploads/2015/08/${name}${version}.zip";
+    # Development tools
-      sha256 = "1hvlpgy4haqgqq52mkxhcl9i1fx67kgwi6f1mijvqzk0xff77hkp";
+    rPackages.languageserver
-      stripRoot = true;
+    rPackages.lintr
-      extraPostFetch = ''
+  ];
-        chmod go-w $out
-      '';
-    };
-
-    nativeBuildInputs = [ makeWrapper ];
-
-    installPhase = ''
-      mkdir -pv $out/share/java $out/bin
-      cp -r ${src} $out/share/java/${name}
-      makeWrapper ${jre}/bin/java $out/bin/CuReSim --add-flags "-jar $out/share/java/${name}/${name}.jar"
-    '';
-  };
-in mkShell {
-  buildInputs =
-    [ R rPackages.immuneSIM rPackages.Biostrings rPackages.stringr CuReSim ];
 }

src/alignment.r

@@ -1,148 +1,45 @@
 library(Biostrings)
 library(parallel)
 
-#' Import and process the TCR and VJ sequences
+construct_dataframe <- function(data) {
-#'
+  vdj_string_set <- lapply(data, FUN = Biostrings::DNAStringSet)
-#' @param file A file path with the sequences after applying a read simulator
+  vdj_dataframe <- as.data.frame(vdj_string_set)
-#' @return A \code{list} with the TCR sequences and VJ sequences
+  vdj_dataframe$hvr_region <- paste(vdj_dataframe$v_sequence,
-parse_data <- function(file) {
+    vdj_dataframe$d_sequence,
-  reversed_sequences <- Biostrings::readQualityScaledDNAStringSet(file)
+    vdj_dataframe$j_sequence,
+    sep = ""
+  )
+  return(vdj_dataframe)
+}
+
+parse_data <- function(files) {
+  reversed_sequences <- Biostrings::readQualityScaledDNAStringSet(files[1])
   sequences <- Biostrings::reverseComplement(reversed_sequences)
-  vj_segments <- union(
+  vdj_alignment <- read.csv(files[2])
-    readRDS("data/v_segments.rds"),
+  vdj_dataframe <- construct_dataframe(vdj_alignment)
-    readRDS("data/j_segments_phe.rds")
+  return(list(sequences, vdj_dataframe))
-  )
-  return(list(sequences, vj_segments))
 }
 
-#' Extracts the VJ metadata from the sequences read identifier
-#'
-#' @param metadata The read identifier of a sequence
-#' @return A \code{list} with the V and J gene identifier
-parse_metadata <- function(metadata) {
-  id_elements <- unlist(strsplit(metadata, split = " "))
-  v_identifier <- id_elements[2]
-  j_identifier <- id_elements[3]
-  return(list(v_id = v_identifier, j_id = j_identifier))
-}
-
-#' Fetches the sequence that matches the VJ gene identifier
-#'
-#' @param names The names of the VJ sequences
-#' @param vdj_segments A \code{DNAStringSet} containing the VJ sequences
-#' @param id The read identifier of a sequence
-#' @return A \code{character} containing the gene sequence
-match_id_sequence <- function(names, vdj_segments, id) {
-  matches <- grep(names, pattern = id)
-  row <- matches[1]
-  return(as.character(vdj_segments[row]))
-}
-
-#' Gets the V and J sequences for a particular read identifier
-#'
-#' @param metadata The read identifier of a sequence
-#' @param names The names of the VJ sequences
-#' @param vdj_segments A \code{DNAStringSet} containing the VJ sequences
-#' @return A \code{list} with the V and J sequences
-get_vj_sequence <- function(metadata, names, vdj_segments) {
-  identifiers <- parse_metadata(metadata)
-  v_sequence <- match_id_sequence(names, vdj_segments, id = identifiers["v_id"])
-  j_sequence <- match_id_sequence(names, vdj_segments, id = identifiers["j_id"])
-  return(list(v_seq = v_sequence, j_seq = j_sequence))
-}
-
-#' Obtains the VJ sequences for all the TCR sequences
-#'
-#' @param sequences A \code{QualityScaledDNAStringSet} with the TCR sequences
-#' @param vdj_segments A \code{DNAStringSet} containing the VJ sequences
-#' @return A \code{data.frame} with the V and J sequences
-fetch_vj_sequences <- function(sequences, vdj_segments) {
-  vj_sequences <- sapply(names(sequences),
-    names(vdj_segments),
-    vdj_segments,
-    FUN = get_vj_sequence
-  )
-  results <- data.frame(t(vj_sequences))
-  return(results)
-}
-
-#' Perform a pairwise alignment of a sequence with the canonical V or J sequence
-#'
-#' @param sequence A \code{DNAString} containing the TCR sequences
-#' @param vdj_segment A \code{DNAString} containing the V or J sequence
-#' @return A \code{PairwiseAlignments}
 align_sequence <- function(sequence, vdj_segment) {
   return(Biostrings::pairwiseAlignment(
-    subject = sequence,
+    pattern = sequence,
-    pattern = vdj_segment,
+    subject = vdj_segment,
     type = "global-local",
     gapOpening = 1
   ))
 }
 
-#' Computes the coordinate shift of the Cysteine due to indels
-#'
-#' @param insertion An \code{IRanges} containing the insertions
-#' @param deletion An \code{IRanges} containing the deletions
-#' @param cys A \code{list} with the Cysteine coordinates
-#' @param alignment A \code{PairwiseAlignments}
-#' @return A \code{list} with the delta of the Cysteine coordinates
-handle_indels <- function(insertion, deletion, cys, alignment) {
-  ins_start <- sum(Biostrings::width(deletion[start(deletion) <= cys$start]))
-  ins_end <- sum(Biostrings::width(deletion[end(deletion) <= cys$end]))
-  shift_num <- c(0, cumsum(Biostrings::width(insertion))[-length(ins_start)])
-  shifted_ins <- IRanges::shift(insertion, shift_num)
-  gaps <- sum(width(shifted_ins[end(shifted_ins) < cys$start + ins_start])) +
-    nchar(stringr::str_extract(alignedSubject(alignment), "^-*"))
-  return(list("start" = ins_start - gaps, "end" = ins_end - gaps))
-}
 
-#' Find the coordinates of the first Cysteine of the HVR
+perform_alignment <- function(sequences, vdj_segments) {
-#'
+  sequence_alignment <- mcmapply(sequences,
-#' @param alignment A \code{PairwiseAlignments}
+    vdj_segments$hvr_region,
-#' @return A \code{list} with the Cysteine coordinates
-get_cys_coordinates <- function(alignment) {
-  cys <- list("start" = 310, "end" = 312)
-  insertion <- unlist(Biostrings::insertion(alignment))
-  deletion <- unlist(Biostrings::deletion(alignment))
-  delta_coordinates <- handle_indels(insertion, deletion, cys, alignment)
-  cys_start <- cys$start + delta_coordinates$start
-  cys_end <- cys$end + delta_coordinates$end
-  return(list("start" = cys_start, "end" = cys_end))
-}
-
-#' Delimit the hypervariable region (HVR) for each TCR sequence
-#'
-#' @param sequences A \code{QualityScaledDNAStringSet} with the TCR sequences
-#' @param vdj_segments A \code{DNAStringSet} containing the VJ sequences
-#' @param cores Number of cores to apply multiprocessing
-#' @return A \code{QualityScaledDNAStringSet} containing the HVR
-get_hvr_sequences <- function(sequences, vdj_segments, cores = detectCores()) {
-  df <- fetch_vj_sequences(sequences, vdj_segments)
-  v_alignment <- parallel::mcmapply(sequences,
-    df$v_seq,
     FUN = align_sequence,
-    mc.cores = cores
+    mc.cores = 4
   )
-  cys_coordinates <- parallel::mclapply(v_alignment, FUN = get_cys_coordinates)
+  return(sequence_alignment)
-  cys_df <- as.data.frame(do.call(rbind, cys_coordinates))
-  remaining <- Biostrings::subseq(sequences, start = unlist(cys_df$end))
-  j_alignment <- parallel::mcmapply(remaining,
-    df$j_seq,
-    FUN = align_sequence,
-    mc.cores = cores
-  )
-  j_start <- parallel::mclapply(
-    j_alignment,
-    function(x) start(Biostrings::Views(x)),
-    mc.cores = cores
-  )
-  hvr_start <- unlist(cys_df$start)
-  hvr_end <- unlist(cys_df$start) + unlist(j_start) + 2
-  hvr <- Biostrings::subseq(sequences, start = hvr_start, end = hvr_end)
-  return(hvr)
 }
 
-data <- parse_data(file = "data/curesim_sequence.fastq")
+input_files <- c("data/curesim_sequence.fastq", "data/vdj_alignment.csv")
-hvr <- get_hvr_sequences(sequences = data[[1]], vdj_segments = data[[2]])
+data <- parse_data(input_files)
-Biostrings::writeXStringSet(hvr, "data/CuReSim-HVR.fastq", format = "fastq")
+alignment <- perform_alignment(sequences = data[[1]], vdj_segments = data[[2]])
+print(alignment)

src/repertoire.r

@@ -1,10 +1,6 @@
 library(immuneSIM)
 library(Biostrings)
 
-#' Generate the beta chain of a human T-cell receptor (TCR)
-#'
-#' @param number_of_sequences Number of different sequences to generate
-#' @return A \code{data.frame} with the sequences, V and J genes and CDR3
 generate_repertoire <- function(number_of_sequences) {
   return(immuneSIM(
     number_of_seqs = number_of_sequences,
@@ -14,44 +10,44 @@ generate_repertoire <- function(number_of_sequences) {
   ))
 }
 
-#' Saves the sequences and CDR3 to FASTQ files
+amplify_rows <- function(data, column, factor) {
-#'
+  if (column == "sequence") {
-#' @param data A \code{data.frame} with the preprocessed TCR sequences and CDR3
+    dna_string <- Biostrings::DNAStringSet(data)
+    reverse_complement <- Biostrings::reverseComplement(dna_string)
+    return(rep(reverse_complement, factor))
+  }
+  return(rep(data, factor))
+}
+
 save_data <- function(data) {
-  Biostrings::writeXStringSet(data$sequence,
+  Biostrings::writeXStringSet(data$sequence, "data/sequence.fasta")
-    "data/sequence.fastq",
+  vdj_sequences <- data[-1]
-    format = "fastq"
+  write.csv(vdj_sequences, "data/vdj_alignment.csv", row.names = FALSE)
+}
+
+process_data <- function(repertoire, sequencing_runs) {
+  columns <- c(
+    "sequence", "v_sequence_alignment",
+    "d_sequence_alignment", "j_sequence_alignment"
   )
-  Biostrings::writeXStringSet(data$junction, "data/HVR.fastq", format = "fastq")
+  data <- repertoire[, columns]
+  amplified_data <- mapply(data, names(data),
+    sequencing_runs,
+    FUN = amplify_rows
+  )
+  save_data(amplified_data)
 }
 
-#' Applies the reverse complement and amplifies the number of sequences
+parse_cli_arguments <- function(args) {
-#'
-#' @param data A \code{data.frame} containing the TCR sequences and CDR3
-#' @param reads Number of times to amplify each sequence
-#' @return A \code{data.frame} with reverse complement sequences and VJ metadata
-process_data <- function(data, reads) {
-  dna_sequence <- Biostrings::DNAStringSet(data$sequence)
-  data$sequence <- Biostrings::reverseComplement(dna_sequence)
-  names(data$sequence) <- paste(rownames(data), data$v_call, data$j_call, " ")
-  data$junction <- Biostrings::DNAStringSet(data$junction)
-  names(data$junction) <- rownames(data)
-  amplified_data <- data[rep(seq_len(nrow(data)), reads), ]
-  return(amplified_data)
-}
-
-#' Checks the number of command line arguments and captures them
-#'
-#' @return A \code{vector} containing the command line arguments
-parse_cli_arguments <- function() {
-  args <- commandArgs(trailingOnly = TRUE)
   if (length(args) != 2) {
-    stop("usage: repertoire.r <number of sequences> <number of reads>")
+    stop("usage: repertoire.r <number of sequences> <sequencing_runs>")
   }
-  return(args)
+  return(c(args[1], args[2]))
 }
 
-args <- parse_cli_arguments()
+args <- commandArgs(trailingOnly = TRUE)
-repertoire <- generate_repertoire(number_of_sequences = as.integer(args[1]))
+arguments <- parse_cli_arguments(args)
-data <- process_data(data = repertoire, reads = args[2])
+number_of_sequences <- as.integer(arguments[1])
-save_data(data)
+sequencing_runs <- as.integer(arguments[2])
+repertoire <- generate_repertoire(number_of_sequences)
+process_data(repertoire, sequencing_runs)