Rename and update readme

.idea/artifacts/BiGpairSEQ_Sim_jar.xml

@@ -1,11 +1,11 @@
 <component name="ArtifactManager">
-  <artifact type="jar" name="TCellSim:jar">
+  <artifact type="jar" build-on-make="true" name="BiGpairSEQ_Sim:jar">
-    <output-path>$PROJECT_DIR$/out/artifacts/TCellSim_jar</output-path>
+    <output-path>$PROJECT_DIR$/out/artifacts/BiGpairSEQ_Sim_jar</output-path>
-    <root id="archive" name="TCellSim.jar">
+    <root id="archive" name="BiGpairSEQ_Sim.jar">
       <element id="directory" name="META-INF">
         <element id="file-copy" path="$PROJECT_DIR$/src/main/java/META-INF/MANIFEST.MF" />
       </element>
-      <element id="module-output" name="TCellSim" />
+      <element id="module-output" name="BigPairSEQ" />
       <element id="extracted-dir" path="$MAVEN_REPOSITORY$/org/jgrapht/jgrapht-core/1.5.1/jgrapht-core-1.5.1.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$MAVEN_REPOSITORY$/org/jheaps/jheaps/0.13/jheaps-0.13.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$MAVEN_REPOSITORY$/commons-cli/commons-cli/1.5.0/commons-cli-1.5.0.jar" path-in-jar="/" />

.idea/compiler.xml

@@ -6,7 +6,7 @@
         <sourceOutputDir name="target/generated-sources/annotations" />
         <sourceTestOutputDir name="target/generated-test-sources/test-annotations" />
         <outputRelativeToContentRoot value="true" />
-        <module name="TCellSim" />
+        <module name="BigPairSEQ" />
       </profile>
     </annotationProcessing>
   </component>

out/artifacts/BiGpairSEQ_Sim_jar/readme.md

@@ -0,0 +1,32 @@
+BiGpairSEQ SIMULATOR
+
+ABOUT:
+This program simulates BiGpairSEQ, a graph theory based adaptation
+of the pairSEQ algorithm for pairing T cell receptor sequences.
+
+Unlike pairSEQ, which calculates p-values for every TCR alpha/beta overlap and compares 
+against a null distribution, BiGpairSEQ does not do any statistical calculations 
+directly. Instead, BiGpairSEQ creates a simple bipartite weighted graph representing the sample plate. 
+The distinct TCRA and TCRB sequences form the two sets of vertices. Every TCRA/TCRB pair that share a well 
+are connected by an edge, with the edge weight set to the number of wells in which both sequences appear.
+(Sequences in all wells are filtered out prior to creating the graph, as there is no signal in their occupancy
+The problem of pairing TCRA/TCRB sequences thus reduces to the "assignment problem" of finding a maximum weight 
+matching on a bipartite graph--the subset of vertex-disjoint edges whose weights sum to the maximum possible value.
+
+USAGE
+Released as an executable .jar file with interactive, command line UI
+Usage: java -jar BiGpairSEQ_Sim.jar
+
+Large cell sample or sample plate files may require large amounts of RAM.
+It is often desirable to increase the JVM memory allocation with the -Xmx flag
+For example, to run the program with 32 gigabytes of memory, use command:
+java -Xmx32G -jar BiGpairSEQ_Sim.jar
+
+Requires Java11 or higher (Openjdk-17 recommended)
+
+pairSEQ citation:
+Howie, B., Sherwood, A. M., et. al.
+"High-throughput pairing of T cell receptor alpha and beta sequences."
+Sci. Transl. Med. 7, 301ra131 (2015)
+
+Simulation by Eugene Fischer, 2021-2022

out/artifacts/TCellSim_jar/readme.md

@@ -1,7 +0,0 @@
-Executable .jar file with interactive, command line UI
-Usage: java -jar TCellSim.jar
-To increase memory allocation, use -Xmx flag.
-For example, to give the program 20 gigabytes of memory:
-java -Xmx20G -jar TCellSim.jar
-
-Requires Java11 or higher (Openjdk-17 recommended)

src/main/java/Plate.java

@@ -55,6 +55,7 @@ public class Plate {
                 List<Integer[]> well = new ArrayList<>();
                 for (int j = 0; j < concentrations[section]; j++) {
                     do {
+                        //inverse transform sampling: for random number u in [0,1), x = log(1-u) / (-lambda)
                         m = (Math.log10((1 - rand.nextDouble()))/(-lambda)) * Math.sqrt(cells.size());
                     } while (m >= cells.size() || m < 0);
                     n = (int) Math.floor(m);

src/main/java/UserInterface.java

@@ -269,7 +269,7 @@ public class UserInterface {
                 //Need to re-do the CDR3/CDR1 matching to correspond to new pattern
                 //System.out.println("5) Generate CDR3/CDR1 occupancy graph");
                 //System.out.println("6) Simulate CDR3/CDR1 T cell matching");
-                System.out.println("9) Acknowledgements");
+                System.out.println("9) About/Acknowledgments");
                 System.out.println("0) Exit");
                 try {
                     input = sc.nextInt();
@@ -384,8 +384,8 @@ public class UserInterface {
             System.out.println("1) Poisson");
             System.out.println("2) Gaussian");
             System.out.println("3) Exponential");
-            System.out.println("(Note: approximate distribution in original paper is exponential, lambda = 0.6.)");
+            System.out.println("(Note: approximate distribution in original paper is exponential, lambda = 0.6)");
-            System.out.println("(approximated from slope of log-log graph in figure 4c)");
+            System.out.println("(lambda value approximated from slope of log-log graph in figure 4c)");
             System.out.println("(Note: wider distributions are more memory intensive to match)");
             System.out.print("Enter selection value: ");
             input = sc.nextInt();
@@ -664,6 +664,17 @@ public class UserInterface {
         System.out.println("This program simulates BiGpairSEQ, a graph theory based adaptation");
         System.out.println("of the pairSEQ algorithm for pairing T cell receptor sequences.");
         System.out.println("");
+        System.out.println("Unlike pairSEQ, which calculates p-values for every TCR alpha/beta overlap and compares");
+        System.out.println("against a null distribution, BiGpairSEQ does not do any statistical calculations");
+        System.out.println("directly. Instead, BiGpairSEQ creates a simple bipartite weighted graph representing");
+        System.out.println("the sample plate. The distinct TCRA and TCRB sequences form the two sets of vertices.");
+        System.out.println("Every TCRA/TCRB pair that share a well are connected by an edge, with the edge weight");
+        System.out.println("set to the number of wells in which both sequences appear. (Sequences in all wells are");
+        System.out.println("filtered out prior to creating the graph, as there is no signal in their occupancy");
+        System.out.println("pattern.) The problem of pairing TCRA/TCRB sequences thus reduces to the \"assignment");
+        System.out.println("problem\" of finding a maximum weight matching on a bipartite graph--the subset of");
+        System.out.println("vertex-disjoint edges whose weights sum to the maximum possible value.");
+        System.out.println("");
         System.out.println("pairSEQ citation:");
         System.out.println("Howie, B., Sherwood, A. M., et. al.");
         System.out.println("High-throughput pairing of T cell receptor alpha and beta sequences.");