Update readme to reflect caching changes

readme.md

@@ -58,13 +58,14 @@ main menu looks like this:
 ```
 --------BiGPairSEQ SIMULATOR--------
 ALPHA/BETA T CELL RECEPTOR MATCHING
-  USING WEIGHTED BIPARTITE GRAPHS
+  USING WEIGHTED BIPARTITE GRAPHS  
 ------------------------------------
 Please select an option:
 1) Generate a population of distinct cells
 2) Generate a sample plate of T cells
 3) Generate CDR3 alpha/beta occupancy data and overlap graph
 4) Simulate bipartite graph CDR3 alpha/beta matching (BiGpairSEQ)
+8) Options
 9) About/Acknowledgments
 0) Exit
 ```
@@ -77,18 +78,20 @@ To run the simulation, the program reads and writes 4 kinds of files:
 * Graph/Data files in binary object serialization format
 * Matching Results files in CSV format
 
-These files are often generated in sequence. To save file I/O time, the most recent instance of each of these four
-files either generated or read from disk is cached in program memory. This is especially important for Graph/Data files,
+These files are often generated in sequence. When entering filenames, it is not necessary to include the file extension
+(.csv or .ser). When reading or writing files, the program will automatically add the correct extension to any filename without one.
+
+To save file I/O time, the most recent instance of each of these four
+files either generated or read from disk can be cached in program memory. This is especially important for Graph/Data files,
 which can be several gigabytes in size. Since some simulations may require running multiple, 
-differntly-configured BiGpairSEQ matchings on the same graph, keeping the most recent graph cached drastically reduces 
-execution time. 
+differently-configured BiGpairSEQ matchings on the same graph, keeping the most recent graph cached can reduce execution time
 
-Subsequent uses of the same data file won't need to be read in again until another file of that type is used or generated.
-The program checks whether it needs to update its cached data by comparing filenames as entered by the user. On 
-encountering a new filename, the program flushes its cache and reads in the new file.
+Subsequent uses of the same data file won't need to be read in again until another file of that type is used or generated,
+or caching is turned off for that file type. The program checks whether it needs to update its cached data by comparing
+filenames as entered by the user. On encountering a new filename, the program flushes its cache and reads in the new file.
 
-When entering filenames, it is not necessary to include the file extension (.csv or .ser). When reading or
-writing files, the program will automatically add the correct extension to any filename without one. 
+The program's caching behavior can be controlled in the Options menu. By default, caching for cell sample and 
+sample plate files is OFF, and caching for graph/data files is ON.
 
 #### Cell Sample Files
 Cell Sample files consist of any number of distinct "T cells." Every cell contains 

src/main/java/BiGpairSEQ.java

@@ -10,6 +10,9 @@ public class BiGpairSEQ {
     private static String plateFilename = null;
     private static GraphWithMapData graphInMemory = null;
     private static String graphFilename = null;
+    private static boolean cacheCells = false;
+    private static boolean cachePlate = false;
+    private static boolean cacheGraph = true;
 
     public static void main(String[] args) {
         if (args.length == 0) {
@@ -30,66 +33,122 @@ public class BiGpairSEQ {
         return cellSampleInMemory;
     }
 
-    public static void setCellSampleInMemory(CellSample cellSampleInMemory) {
-        BiGpairSEQ.cellSampleInMemory = cellSampleInMemory;
+    public static void setCellSampleInMemory(CellSample cellSample, String filename) {
+        if(cellSampleInMemory != null) {
+            clearCellSampleInMemory();
+        }
+        cellSampleInMemory = cellSample;
+        cellFilename = filename;
+        System.out.println("Cell sample file " + filename + " cached.");
     }
 
     public static void clearCellSampleInMemory() {
         cellSampleInMemory = null;
+        cellFilename = null;
         System.gc();
+        System.out.println("Cell sample file cache cleared.");
+
     }
 
     public static String getCellFilename() {
         return cellFilename;
     }
 
-    public static void setCellFilename(String cellFilename) {
-        BiGpairSEQ.cellFilename = cellFilename;
-    }
-
     public static Plate getPlateInMemory() {
         return plateInMemory;
     }
 
-    public static void setPlateInMemory(Plate plateInMemory) {
-        BiGpairSEQ.plateInMemory = plateInMemory;
+    public static void setPlateInMemory(Plate plate, String filename) {
+        if(plateInMemory != null) {
+            clearPlateInMemory();
+        }
+        plateInMemory = plate;
+        plateFilename = filename;
+        System.out.println("Sample plate file " + filename + " cached.");
     }
 
     public static void clearPlateInMemory() {
         plateInMemory = null;
+        plateFilename = null;
         System.gc();
+        System.out.println("Sample plate file cache cleared.");
+
     }
 
     public static String getPlateFilename() {
         return plateFilename;
     }
 
-    public static void setPlateFilename(String plateFilename) {
-        BiGpairSEQ.plateFilename = plateFilename;
+
+    public static GraphWithMapData getGraphInMemory() {return graphInMemory;
     }
 
-    public static GraphWithMapData getGraphInMemory() {
-        return graphInMemory;
-    }
-
-    public static void setGraphInMemory(GraphWithMapData g) {
+    public static void setGraphInMemory(GraphWithMapData g, String filename) {
         if (graphInMemory != null) {
             clearGraphInMemory();
         }
         graphInMemory = g;
+        graphFilename = filename;
+        System.out.println("Graph and data file " + filename + " cached.");
     }
 
     public static void clearGraphInMemory() {
         graphInMemory = null;
+        graphFilename = null;
         System.gc();
+        System.out.println("Graph and data file cache cleared.");
     }
 
     public static String getGraphFilename() {
         return graphFilename;
     }
 
-    public static void setGraphFilename(String filename) {
-        graphFilename = filename;
+
+    public static boolean cacheCells() {
+        return cacheCells;
     }
 
+    public static void setCacheCells(boolean cacheCells) {
+        //if not caching, clear the memory
+        if(!cacheCells){
+            BiGpairSEQ.clearCellSampleInMemory();
+            System.out.println("Cell sample file caching: OFF.");
+        }
+        else {
+            System.out.println("Cell sample file caching: ON.");
+        }
+        BiGpairSEQ.cacheCells = cacheCells;
+    }
+
+    public static boolean cachePlate() {
+        return cachePlate;
+    }
+
+    public static void setCachePlate(boolean cachePlate) {
+        //if not caching, clear the memory
+        if(!cachePlate) {
+            BiGpairSEQ.clearPlateInMemory();
+            System.out.println("Sample plate file caching: OFF.");
+        }
+        else {
+            System.out.println("Sample plate file caching: ON.");
+        }
+        BiGpairSEQ.cachePlate = cachePlate;
+    }
+
+    public static boolean cacheGraph() {
+        return cacheGraph;
+    }
+
+    public static void setCacheGraph(boolean cacheGraph) {
+        //if not caching, clear the memory
+        if(!cacheGraph) {
+            BiGpairSEQ.clearGraphInMemory();
+            System.out.println("Graph/data file caching: OFF.");
+        }
+        else {
+            System.out.println("Graph/data file caching: ON.");
+        }
+        BiGpairSEQ.cacheGraph = cacheGraph;
+    }
 }

src/main/java/InteractiveInterface.java

@@ -27,6 +27,7 @@ public class InteractiveInterface {
                 //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("8) Options");
                 System.out.println("9) About/Acknowledgments");
                 System.out.println("0) Exit");
                 try {
@@ -37,6 +38,7 @@ public class InteractiveInterface {
                         case 3 -> makeCDR3Graph();
                         case 4 -> matchCDR3s();
                         //case 6 -> matchCellsCDR1();
+                        case 8 -> options();
                         case 9 -> acknowledge();
                         case 0 -> quit = true;
                         default -> throw new InputMismatchException("Invalid input.");
@@ -78,11 +80,9 @@ public class InteractiveInterface {
         CellFileWriter writer = new CellFileWriter(filename, sample);
         writer.writeCellsToFile();
         System.out.println("Cell sample written to: " + filename);
-        if(BiGpairSEQ.getCellSampleInMemory() != null) {
-            BiGpairSEQ.clearCellSampleInMemory();
+        if(BiGpairSEQ.cacheCells()) {
+            BiGpairSEQ.setCellSampleInMemory(sample, filename);
         }
-        BiGpairSEQ.setCellSampleInMemory(sample);
-        BiGpairSEQ.setCellFilename(filename);
     }
 
     //Output a CSV of sample plate
@@ -219,9 +219,9 @@ public class InteractiveInterface {
             System.out.println("Reading Cell Sample file: " + cellFile);
             CellFileReader cellReader = new CellFileReader(cellFile);
             cells = cellReader.getCellSample();
-            BiGpairSEQ.clearCellSampleInMemory();
-            BiGpairSEQ.setCellSampleInMemory(cells);
-            BiGpairSEQ.setCellFilename(cellFile);
+            if(BiGpairSEQ.cacheCells()) {
+                BiGpairSEQ.setCellSampleInMemory(cells, cellFile);
+            }
         }
         assert filename != null;
         Plate samplePlate;
@@ -242,8 +242,9 @@ public class InteractiveInterface {
         System.out.println("Writing Sample Plate to file");
         writer.writePlateFile();
         System.out.println("Sample Plate written to file: " + filename);
-        BiGpairSEQ.setPlateInMemory(samplePlate);
-        BiGpairSEQ.setPlateFilename(filename);
+        if(BiGpairSEQ.cachePlate()) {
+            BiGpairSEQ.setPlateInMemory(samplePlate, filename);
+        }
     }
 
     //Output serialized binary of GraphAndMapData object
@@ -271,16 +272,16 @@ public class InteractiveInterface {
         assert cellFile != null;
         CellSample cellSample;
         //check if cells are already in memory
-        if(cellFile.equals(BiGpairSEQ.getCellFilename())) {
+        if(cellFile.equals(BiGpairSEQ.getCellFilename()) && BiGpairSEQ.getCellSampleInMemory() != null) {
             cellSample = BiGpairSEQ.getCellSampleInMemory();
         }
         else {
-            BiGpairSEQ.clearCellSampleInMemory();
             System.out.println("Reading Cell Sample file: " + cellFile);
             CellFileReader cellReader = new CellFileReader(cellFile);
             cellSample = cellReader.getCellSample();
-            BiGpairSEQ.setCellSampleInMemory(cellSample);
-            BiGpairSEQ.setCellFilename(cellFile);
+            if(BiGpairSEQ.cacheCells()) {
+                BiGpairSEQ.setCellSampleInMemory(cellSample, cellFile);
+            }
         }
 
         assert plateFile != null;
@@ -290,12 +291,12 @@ public class InteractiveInterface {
             plate = BiGpairSEQ.getPlateInMemory();
         }
         else {
-            BiGpairSEQ.clearPlateInMemory();
             System.out.println("Reading Sample Plate file: " + plateFile);
             PlateFileReader plateReader = new PlateFileReader(plateFile);
             plate = new Plate(plateReader.getFilename(), plateReader.getWells());
-            BiGpairSEQ.setPlateInMemory(plate);
-            BiGpairSEQ.setPlateFilename(plateFile);
+            if(BiGpairSEQ.cachePlate()) {
+                BiGpairSEQ.setPlateInMemory(plate, plateFile);
+            }
         }
         if (cellSample.getCells().size() == 0){
             System.out.println("No cell sample found.");
@@ -312,9 +313,10 @@ public class InteractiveInterface {
             GraphDataObjectWriter dataWriter = new GraphDataObjectWriter(filename, data);
             dataWriter.writeDataToFile();
             System.out.println("Graph and Data file written to: " + filename);
-            BiGpairSEQ.setGraphInMemory(data);
-            BiGpairSEQ.setGraphFilename(filename);
-            System.out.println("Graph and Data file " + filename + " cached.");
+            if(BiGpairSEQ.cacheGraph()) {
+                BiGpairSEQ.setGraphInMemory(data, filename);
+
+            }
         }
     }
 
@@ -366,17 +368,15 @@ public class InteractiveInterface {
         assert graphFilename != null;
         //check if this is the same graph we already have in memory.
         GraphWithMapData data;
-        if(!(graphFilename.equals(BiGpairSEQ.getGraphFilename())) || BiGpairSEQ.getGraphInMemory() == null) {
-            BiGpairSEQ.clearGraphInMemory();
-            //read object data from file
-            GraphDataObjectReader dataReader = new GraphDataObjectReader(graphFilename);
-            data = dataReader.getData();
-            //set new graph in memory and new filename
-            BiGpairSEQ.setGraphInMemory(data);
-            BiGpairSEQ.setGraphFilename(graphFilename);
+        if(graphFilename.equals(BiGpairSEQ.getGraphFilename())) {
+            data = BiGpairSEQ.getGraphInMemory();
         }
         else {
-            data = BiGpairSEQ.getGraphInMemory();
+            GraphDataObjectReader dataReader = new GraphDataObjectReader(graphFilename);
+            data = dataReader.getData();
+            if(BiGpairSEQ.cacheGraph()) {
+                BiGpairSEQ.setGraphInMemory(data, graphFilename);
+            }
         }
         //simulate matching
         MatchingResult results = Simulator.matchCDR3s(data, graphFilename, lowThreshold, highThreshold, maxOccupancyDiff,
@@ -493,6 +493,35 @@ public class InteractiveInterface {
 //        }
 //    }
 
+    private static void options(){
+        boolean backToMain = false;
+        while(!backToMain) {
+            System.out.println("\n--------------OPTIONS---------------");
+            System.out.println("1) Turn " + getOnOff(!BiGpairSEQ.cacheCells()) + " cell sample file caching");
+            System.out.println("2) Turn " + getOnOff(!BiGpairSEQ.cachePlate()) + " plate file caching");
+            System.out.println("3) Turn " + getOnOff(!BiGpairSEQ.cacheGraph()) + " graph/data file caching");
+            System.out.println("0) Return to main menu");
+            try {
+                input = sc.nextInt();
+                switch (input) {
+                    case 1 -> BiGpairSEQ.setCacheCells(!BiGpairSEQ.cacheCells());
+                    case 2 -> BiGpairSEQ.setCachePlate(!BiGpairSEQ.cachePlate());
+                    case 3 -> BiGpairSEQ.setCacheGraph(!BiGpairSEQ.cacheGraph());
+                    case 0 -> backToMain = true;
+                    default -> throw new InputMismatchException("Invalid input.");
+                }
+            } catch (InputMismatchException ex) {
+                System.out.println(ex);
+                sc.next();
+            }
+        }
+    }
+
+    private static String getOnOff(boolean b) {
+        if (b) { return "on";}
+        else { return "off"; }
+    }
+
     private static void acknowledge(){
         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.");