From 2bf2a9f5f7de304f3a34b2227429c2af62207dc8 Mon Sep 17 00:00:00 2001
From: eugenefischer <66030419+eugenefischer@users.noreply.github.com>
Date: Tue, 27 Sep 2022 11:51:51 -0500
Subject: [PATCH] Add comments

---
 src/main/java/Plate.java | 32 +++++++++++++++++++++-----------
 1 file changed, 21 insertions(+), 11 deletions(-)

diff --git a/src/main/java/Plate.java b/src/main/java/Plate.java
index 8f071e2..68ebe8c 100644
--- a/src/main/java/Plate.java
+++ b/src/main/java/Plate.java
@@ -178,7 +178,7 @@ public class Plate {
         }
     }
 
-    //returns a map of the counts of the sequence at cell index sIndex, in a specific of wells
+    //returns a map of the counts of the sequence at cell index sIndex, in all wells
     //Simulates read depth and read errors, counts the number of reads of a unique sequence into the given map.
     public void assayWellsSequenceSWithReadDepth(Map<String, Integer> misreadCounts, Map<String, Integer> occupancyMap, Map<String, Integer> readCountMap,
                                                  int readDepth, double readErrorProb, double errorCollisionProb, int... sIndices) {
@@ -203,16 +203,26 @@ public class Plate {
             }
         }
     }
+
     //For the sequences at cell indices sIndices, counts number of unique sequences in the given well into the given map
     //Simulates read depth and read errors, counts the number of reads of a unique sequence into the given map.
+    //NOTE: this function changes the content of the well, adding spurious cells to contain the misread sequences
+    //(this is necessary because, in the simulation, the plate is read multiple times, but random misreads can only
+    //be simulated once).
+    //(Possibly I should refactor all of this to only require a single plate assay, to speed things up. Or at least
+    //to see if it would speed things up.)
     private void countSequencesWithReadDepth(Map<String, Integer> distinctMisreadCounts, Map<String, Integer> occupancyMap, Map<String, Integer> readCountMap,
                                              int readDepth, double readErrorProb, double errorCollisionProb,
                                              List<String[]> well, int... sIndices) {
+        //list of spurious cells to add to well after counting
         List<String[]> spuriousCells = new ArrayList<>();
         for(String[] cell : well) {
+            //new potential spurious cell for each cell that gets read
             String[] spuriousCell = new String[SequenceType.values().length];
+            //initialize spurious cell with all dropout sequences
             Arrays.fill(spuriousCell, "-1");
-            Boolean readError = false;
+            //has a read error occurred?
+            boolean readError = false;
             for(int sIndex: sIndices){
                 //skip dropout sequences, which have value "-1"
                 if(!"-1".equals(cell[sIndex])){
@@ -220,21 +230,26 @@ public class Plate {
                     for(int i = 0; i < readDepth; i++) {
                         if (rand.nextDouble() <= readErrorProb) {
                             readError = true;
+                            //Read errors are represented by appending "*"s to the end of the sequence some number of times
                             StringBuilder spurious = new StringBuilder(cell[sIndex]);
+                            //if this sequence hasn't been misread before, or the read error is unique,
+                            //append one more "*" than has been appended before
                             if (!distinctMisreadCounts.containsKey(cell[sIndex]) || rand.nextDouble() > errorCollisionProb) {
                                 distinctMisreadCounts.merge(cell[sIndex], 1, (oldValue, newValue) -> oldValue + newValue);
                                 for (int j = 0; j < distinctMisreadCounts.get(cell[sIndex]); j++) {
                                     spurious.append("*");
                                 }
                             }
+                            //if this is a read error collision, randomly choose a number of "*"s that has been appended before
                             else {
                                 int starCount = rand.nextInt(distinctMisreadCounts.get(cell[sIndex]));
                                 for (int j = 0; j < starCount; j++) {
                                     spurious.append("*");
                                 }
                             }
-                                sequencesWithReadCounts.merge(spurious.toString(), 1, (oldValue, newValue) -> oldValue + newValue);
-                                spuriousCell[sIndex] = spurious.toString();
+                            sequencesWithReadCounts.merge(spurious.toString(), 1, (oldValue, newValue) -> oldValue + newValue);
+                            //add spurious sequence to spurious cell
+                            spuriousCell[sIndex] = spurious.toString();
                         }
                         else {
                             sequencesWithReadCounts.merge(cell[sIndex], 1, (oldValue, newValue) -> oldValue + newValue);
@@ -246,19 +261,14 @@ public class Plate {
                     }
                 }
             }
-            if (readError) {
+            if (readError) { //only add a new spurious cell if there was a read error
                 spuriousCells.add(spuriousCell);
             }
         }
+        //add all spurious cells to the well
         well.addAll(spuriousCells);
     }
 
-    private String getRandomErrorKeyFromMap(Map<String, Integer> map) {
-        //Only want to choose from index 1 to n, since index 0 is not an error sequence
-        int index = rand.nextInt(map.size() - 1);
-        return (String) map.keySet().toArray()[index + 1];
-    }
-
     public String getSourceFileName() {
         return sourceFile;
     }