disable selection of the scaling integer weight MWM algorithm via the interactive interface

readme.md

@@ -1,31 +1,31 @@
 # BiGpairSEQ SIMULATOR
 
 ## CONTENTS
-1. ABOUT
+1. [ABOUT](#about)
-2. THEORY
+2. [THEORY](#theory)
-3. THE BiGpairSEQ ALGORITHM
+3. [THE BiGpairSEQ ALGORITHM](#the-bigpairseq-algorithm)
-4. USAGE
+4. [USAGE](#usage)
-   1. RUNNING THE PROGRAM
+   1. [RUNNING THE PROGRAM](#running-the-program)
-   2. COMMAND LINE OPTIONS
+   2. [COMMAND LINE OPTIONS](#command-line-options)
-   3. INTERACTIVE INTERFACE
+   3. [INTERACTIVE INTERFACE](#interactive-interface)
-   4. INPUT/OUTPUT
+   4. [INPUT/OUTPUT](#inputoutput)
       1. Cell Sample Files
       2. Sample Plate Files
       3. Graph/Data Files
       4. Matching Results Files
-5. RESULTS
+5. [RESULTS](#results)
    1. SAMPLE PLATES WITH VARYING NUMBERS OF CELLS PER WELL
    2. SIMULATING EXPERIMENTS FROM pairSEQ PAPER
-6. TODO
+6. [TODO](#todo)
-7. CITATIONS
+7. [CITATIONS](#citations)
-8. ACKNOWLEDGEMENTS
+8. [ACKNOWLEDGEMENTS](#acknowledgements)
-9. AUTHOR
+9. [AUTHOR](#author)
-10. DISCLOSURE
+10. [DISCLOSURE](#disclosure)
 
 ## ABOUT
 
 This program simulates BiGpairSEQ (Bipartite Graph pairSEQ), a graph theory-based adaptation
-of the pairSEQ algorithm (Howie, et al. 2015) for pairing T cell receptor sequences.
+of the pairSEQ algorithm ([Howie, et al. 2015](#citations)) for pairing T cell receptor sequences.
 
 ## THEORY
 
@@ -51,17 +51,17 @@ matching (MWM) on a bipartite graph--the subset of vertex-disjoint edges whose w
 
 This is a well-studied combinatorial optimization problem, with many known algorithms that produce 
 provably-optimal solutions. The most theoretically efficient algorithm known to the author for maximum weight matching of a bipartite
-graph with strictly integral weights is from Duan and Su (2012). For a graph with m edges, n vertices per side, 
+graph with strictly integral weights is from [Duan and Su (2012)](#citations). For a graph with m edges, n vertices per side, 
 and maximum integer edge weight N, their algorithm runs in **O(m sqrt(n) log(N))** time. As the graph representation of 
-a pairSEQ experiment is bipartite with integer weights, this algorithm seems ideal for BiGpairSEQ. Unfortunately, it's a 
+a pairSEQ experiment is bipartite with integer weights, this algorithm seems ideal for BiGpairSEQ. Unfortunately, it is not 
-fairly new algorithm, and not yet implemented by the graph theory library used in this simulator (JGraphT), nor has the author had 
+implemented by the graph theory library used in this simulator (JGraphT), and the author has not yet had time to write a
-time to implement it himself.
+full, optimized implementation himself for testing.
 
 So this program instead uses the [Fibonacci heap](https://en.wikipedia.org/wiki/Fibonacci_heap) based algorithm of Fredman and Tarjan (1987) (essentially
-[the Hungarian algorithm](https://en.wikipedia.org/wiki/Hungarian_algorithm) augmented with a more efficeint priority queue) which has a worst-case
+[the Hungarian algorithm](https://en.wikipedia.org/wiki/Hungarian_algorithm) augmented with a more efficient priority queue) which has a worst-case
-runtime of **O(n (n log(n) + m))**. The algorithm is implemented as described in Melhorn and Näher (1999). (The simulator
+runtime of **O(n (n log(n) + m))**. The algorithm is implemented as described in [Melhorn and Näher (1999)](#citations). (The simulator can use either a
-allows the substitution of a [pairing heap](https://en.wikipedia.org/wiki/Pairing_heap) for a Fibonacci heap, though the relative performance difference of the two
+Fibonacci heap or a [pairing heap](https://en.wikipedia.org/wiki/Pairing_heap) as desired. By default, a pairing heap is used,
-has not yet been thoroughly tested.)
+as in practice they often offer superior performance.)
 
 One possible advantage of this less efficient algorithm is that the Hungarian algorithm and its variations work with both the balanced and the unbalanced assignment problem
 (that is, cases where both sides of the bipartite graph have the same number of vertices and those in which they don't.)
@@ -650,6 +650,7 @@ the file of distinct cells may enable better simulated replication of this exper
 * Melhorn, K., Näher, St. [The LEDA Platform of Combinatorial and Geometric Computing.](https://people.mpi-inf.mpg.de/~mehlhorn/LEDAbook.html) Cambridge University Press. Chapter 7, Graph Algorithms; p. 132-162 (1999)
 * Fredman, M., Tarjan, R. ["Fibonacci heaps and their uses in improved network optimization algorithms."](https://www.cl.cam.ac.uk/teaching/1011/AlgorithII/1987-FredmanTar-fibonacci.pdf) J. ACM, 34(3):596–615 (1987))
 * Bertsekas, D., Castañon, D. ["A forward/reverse auction algorithm for asymmetric assignment problems"](https://www.mit.edu/~dimitrib/For_Rev_Asym_Auction.pdf) Computational Optimization and Applications 1, 277-297 (1992)
+* Dimitrios Michail, Joris Kinable, Barak Naveh, and John V. Sichi. 2020. JGraphT—A Java Library for Graph Data Structures and Algorithms. ACM Trans. Math. Softw. 46, 2, Article 16
 
 ## EXTERNAL LIBRARIES USED
 * [JGraphT](https://jgrapht.org) -- Graph theory data structures and algorithms

src/main/java/AlgorithmType.java

@@ -1,4 +1,5 @@
 public enum AlgorithmType {
     HUNGARIAN, //Hungarian algorithm
     AUCTION, //Forward auction algorithm
+    INTEGER_WEIGHT_SCALING, //integer weight scaling algorithm of Duan and Su
 }

src/main/java/BiGpairSEQ.java

@@ -14,7 +14,7 @@ public class BiGpairSEQ {
     private static boolean cachePlate = false;
     private static boolean cacheGraph = false;
     private static AlgorithmType matchingAlgoritmType = AlgorithmType.HUNGARIAN;
-    private static HeapType priorityQueueHeapType = HeapType.FIBONACCI;
+    private static HeapType priorityQueueHeapType = HeapType.PAIRING;
     private static boolean outputBinary = true;
     private static boolean outputGraphML = false;
     private static boolean calculatePValue = false;
@@ -165,6 +165,8 @@ public class BiGpairSEQ {
 
     public static void setHungarianAlgorithm() { matchingAlgoritmType = AlgorithmType.HUNGARIAN; }
 
+    public static void setIntegerWeightScalingAlgorithm() { matchingAlgoritmType = AlgorithmType.INTEGER_WEIGHT_SCALING; }
+
     public static void setAuctionAlgorithm() { matchingAlgoritmType = AlgorithmType.AUCTION; }
 
     public static void setPairingHeap() {

src/main/java/InteractiveInterface.java

@@ -582,29 +582,36 @@ public class InteractiveInterface {
         boolean backToOptions = false;
         while(!backToOptions) {
             System.out.println("\n---------ALGORITHM OPTIONS----------");
-            System.out.println("1) Use scaling algorithm by Duan and Su.");
+            System.out.println("1) Use Hungarian algorithm with Fibonacci heap priority queue");
-            System.out.println("2) Use Hungarian algorithm with Fibonacci heap priority queue");
+            System.out.println("2) Use Hungarian algorithm with pairing heap priority queue");
-            System.out.println("3) Use Hungarian algorithm with pairing heap priority queue");
+            System.out.println("3) Use auction algorithm");
-            System.out.println("4) Use auction algorithm");
+            System.out.println("4) Use integer weight scaling algorithm by Duan and Su. (buggy, not yet fully implemented!)");
             System.out.println("0) Return to Options menu");
             try {
                 input = sc.nextInt();
                 switch (input) {
-                    case 1 -> System.out.println("This option is not yet implemented. Choose another.");
+                    case 1 -> {
-                    case 2 -> {
+                        BiGpairSEQ.setHungarianAlgorithm();
                         BiGpairSEQ.setFibonacciHeap();
                         System.out.println("MWM algorithm set to Hungarian with Fibonacci heap");
                         backToOptions = true;
                     }
-                    case 3 -> {
+                    case 2 -> {
+                        BiGpairSEQ.setHungarianAlgorithm();
                         BiGpairSEQ.setPairingHeap();
                         System.out.println("MWM algorithm set to Hungarian with pairing heap");
                         backToOptions = true;
                     }
-                    case 4 -> {
+                    case 3 -> {
                         BiGpairSEQ.setAuctionAlgorithm();
                         System.out.println("MWM algorithm set to auction");
                     }
+                    case 4 -> {
+                        System.out.println("Scaling integer weight MWM algorithm not yet fully implemented. Sorry.");
+//                        BiGpairSEQ.setIntegerWeightScalingAlgorithm();
+//                        System.out.println("MWM algorithm set to integer weight scaling algorithm of Duan and Su");
+                        backToOptions = true;
+                    }
                     case 0 -> backToOptions = true;
                     default -> System.out.println("Invalid input");
                 }

src/main/java/MaximumIntegerWeightBipartiteAuctionMatching.java

@@ -36,6 +36,7 @@ public class MaximumIntegerWeightBipartiteAuctionMatching<V, E> implements Match
     private final BigDecimal epsilon;
     private final Set<E> matching;
     private BigDecimal matchingWeight;
+
     private boolean swappedPartitions = false;
 
     public MaximumIntegerWeightBipartiteAuctionMatching(Graph<V, E> graph, Set<V> partition1, Set<V> partition2) {

src/main/java/Simulator.java

@@ -193,6 +193,9 @@ public class Simulator implements GraphModificationFunctions {
                 //create a new MaximumIntegerWeightBipartiteAuctionMatching
                 maxWeightMatching = new MaximumIntegerWeightBipartiteAuctionMatching<>(graph, alphas, betas);
             }
+            case INTEGER_WEIGHT_SCALING -> {
+                maxWeightMatching = new MaximumIntegerWeightBipartiteMatching<>(graph, alphas, betas, new BigDecimal(highThreshold));
+            }
             default -> { //HUNGARIAN
                 //use selected heap type for priority queue
                 HeapType heap = BiGpairSEQ.getPriorityQueueHeapType();
@@ -273,6 +276,9 @@ public class Simulator implements GraphModificationFunctions {
             case AUCTION -> {
                 algoType = "Auction algorithm";
             }
+            case INTEGER_WEIGHT_SCALING -> {
+                algoType = "Integer weight scaling algorithm from Duan and Su (not yet perfectly implemented)";
+            }
             default -> { //HUNGARIAN
                 algoType = "Hungarian algorithm with heap: " + BiGpairSEQ.getPriorityQueueHeapType().name();
             }