JAL-2616 add documentation for probability analyser
authorTZVanaalten <TZVanaalten@LS30916.ad.lifesci.dundee.ac.uk>
Thu, 20 Jul 2017 11:07:10 +0000 (12:07 +0100)
committerTZVanaalten <TZVanaalten@LS30916.ad.lifesci.dundee.ac.uk>
Thu, 20 Jul 2017 11:07:10 +0000 (12:07 +0100)
src/jalview/util/HMMProbabilityDistributionAnalyser.java
src/jalview/util/ProbabilityAnalyserKickstarter.java
test/jalview/util/HMMProbabilityDistributionAnalyserTest.java [new file with mode: 0644]

index 9d6066d..1fc178a 100644 (file)
@@ -21,6 +21,14 @@ import java.util.Map;
 import java.util.Scanner;
 import java.util.Vector;
 
+/**
+ * Processes probability data. The file indexes used in this program represent
+ * the index of the location of a family or hmm in their respective files,
+ * starting from 0.
+ * 
+ * @author TZVanaalten
+ *
+ */
 public class HMMProbabilityDistributionAnalyser
 {
 
@@ -28,31 +36,54 @@ public class HMMProbabilityDistributionAnalyser
 
   HiddenMarkovModel hmm;
 
+  // contains the raw data produced
   List<ArrayList<Double>> raw = new ArrayList<>();
 
+  // contains binned data
   Map<String, Double> binned = new HashMap<>();
 
+  // location of the family file
   final static String FAMILIES = "C:/Users/TZVanaalten/Pfam-A.full";
 
+  // location of the HMM file
   final static String HMMS = "H:/Desktop/PFAM/HMMs/Pfam-A.hmm";
 
+  // suffix for raw file
   final static String RAW = "/Raw.csv";
 
+  // suffix for binned file
   final static String BINNED = "/Binned.csv";
 
+  // normalisation scale
   final static double SCALE = 100000;
 
+  // current position in file
   int currentFilePosition = 0;
 
   final static String NL = "\n";
 
+  // current directory
   String currentFolder;
 
+  /**
+   * Sets the working directory.
+   * 
+   * @param path
+   */
   public void setFolder(String path)
   {
     currentFolder = path;
   }
 
+  /**
+   * Moves a buffered reader to a specific location in the file, delimited by
+   * '//'.
+   * 
+   * @param index
+   *          The index of the location in the file.
+   * @param br
+   * @throws IOException
+   */
   public void moveToFile(int index, BufferedReader br) throws IOException
   {
     for (int i = 0; i < index; i++)
@@ -65,10 +96,14 @@ public class HMMProbabilityDistributionAnalyser
     }
 
   }
+  
   /**
-   * Analyses probability data
+   * Analyses a specified number of families and then saves the data. Before
+   * analysing the data, the previous saved data will be imported and after
+   * analysing this data is exported back into the file.
    * 
-   * @param args
+   * @param increments
+   *          The number of families to read before saving.
    * @throws IOException
    */
   public void run(int increments) throws IOException
@@ -120,12 +155,24 @@ public class HMMProbabilityDistributionAnalyser
 
   }
 
+  /**
+   * Reads the previous data from both files
+   * 
+   * @param source
+   * @throws IOException
+   */
   public void readPreviousData(String source) throws IOException
   {
     readBinned(source);
     readRaw(source);
   }
 
+  /**
+   * Reads the previous data from the binned file.
+   * 
+   * @param source
+   * @throws IOException
+   */
   public void readBinned(String source) throws IOException
   {
     BufferedReader input = new BufferedReader(
@@ -144,6 +191,12 @@ public class HMMProbabilityDistributionAnalyser
     input.close();
   }
 
+  /**
+   * Reads the previous data from the raw file.
+   * 
+   * @param source
+   * @throws IOException
+   */
   public void readRaw(String source) throws IOException
   {
     BufferedReader input = new BufferedReader(new FileReader(source + RAW));
@@ -188,6 +241,11 @@ public class HMMProbabilityDistributionAnalyser
     input.close();
   }
 
+  /**
+   * Counts the number of valid residues in the sequence.
+   * 
+   * @return
+   */
   public int countValidResidues()
   {
     int count = 0;
@@ -212,6 +270,11 @@ public class HMMProbabilityDistributionAnalyser
     return count;
   }
 
+  /**
+   * Processes data, and stores it in both a raw and binned format.
+   * 
+   * @param count
+   */
   public void processData(int count)
   {
 
@@ -260,6 +323,12 @@ public class HMMProbabilityDistributionAnalyser
   }
 
 
+  /**
+   * Reads in the sequence data from a Stockholm file.
+   * 
+   * @param source
+   * @throws IOException
+   */
   public void readStockholm(FileParse source) throws IOException
   {
     StockholmFile file = new StockholmFile(source);
@@ -267,6 +336,12 @@ public class HMMProbabilityDistributionAnalyser
     sequences = file.getSeqs();
   }
 
+  /**
+   * Reads in the HMM data from a HMMer file.
+   * 
+   * @param source
+   * @throws IOException
+   */
   public void readHMM(FileParse source) throws IOException
   {
 
@@ -276,6 +351,12 @@ public class HMMProbabilityDistributionAnalyser
 
   }
 
+  /**
+   * Exports both the binned and raw data into separate files.
+   * 
+   * @param location
+   * @throws FileNotFoundException
+   */
   public void exportData(String location) throws FileNotFoundException
   {
     PrintWriter writerBin = new PrintWriter(new File(location + BINNED));
@@ -321,6 +402,12 @@ public class HMMProbabilityDistributionAnalyser
 
   }
 
+  /**
+   * Prints the specified family on the console.
+   * 
+   * @param index
+   * @throws IOException
+   */
   public void printFam(int index) throws IOException
   {
     BufferedReader br = new BufferedReader(new FileReader(FAMILIES));
@@ -339,6 +426,12 @@ public class HMMProbabilityDistributionAnalyser
 
   }
 
+  /**
+   * Prints the specified HMM on the console.
+   * 
+   * @param index
+   * @throws IOException
+   */
   public void printHMM(int index) throws IOException
   {
     BufferedReader br = new BufferedReader(new FileReader(HMMS));
@@ -357,6 +450,12 @@ public class HMMProbabilityDistributionAnalyser
 
   }
 
+  /**
+   * Prints the specified family to a .sto file in the current directory.
+   * 
+   * @param index
+   * @throws IOException
+   */
   public void printFamToFile(int index) throws IOException
   {
     String name;
@@ -392,6 +491,12 @@ public class HMMProbabilityDistributionAnalyser
 
   }
 
+  /**
+   * Prints the specified family to a .hmm file in the current directory.
+   * 
+   * @param index
+   * @throws IOException
+   */
   public void printHMMToFile(int index) throws IOException
   {
 
@@ -427,6 +532,11 @@ public class HMMProbabilityDistributionAnalyser
 
   }
   
+  /**
+   * Clears all raw, binned and current position data in the current directory.
+   * 
+   * @throws FileNotFoundException
+   */
   public void clear() throws FileNotFoundException
   {
     PrintWriter pos = new PrintWriter(
index fd83e3a..9eea470 100644 (file)
@@ -3,6 +3,14 @@ package jalview.util;
 import java.io.IOException;
 import java.util.Scanner;
 
+/**
+ * This class contains the brain of the analyser program, and contains a number
+ * of commands for the processing of data.
+ * 
+ * @author TZVanaalten
+ *
+ */
+
 public class ProbabilityAnalyserKickstarter
 {
 
@@ -10,6 +18,7 @@ public class ProbabilityAnalyserKickstarter
           throws IOException, InterruptedException
   {
 
+    // this does all of the processing
     HMMProbabilityDistributionAnalyser analyser = new HMMProbabilityDistributionAnalyser();
 
     boolean running = true;
@@ -20,6 +29,7 @@ public class ProbabilityAnalyserKickstarter
       String command = keyboard.nextLine();
 
       Scanner inputScanner = new Scanner(command);
+      // prints family to console. Syntax is printFam <index>
       if (command.indexOf("printFam") > -1)
       {
         inputScanner.next();
@@ -27,7 +37,7 @@ public class ProbabilityAnalyserKickstarter
         analyser.printFam(index);
         continue;
       }
-
+      // prints HMM to console. Syntax is printHMM <index>
       if (command.indexOf("printHMM") > -1)
       {
 
@@ -36,7 +46,7 @@ public class ProbabilityAnalyserKickstarter
         analyser.printHMM(index);
         continue;
       }
-
+      // prints family to file in current folder. Syntax is exportFam <index>.
       if (command.indexOf("exportFam") > -1)
       {
 
@@ -46,7 +56,7 @@ public class ProbabilityAnalyserKickstarter
         analyser.printFamToFile(index);
         continue;
       }
-
+      // prints HMM to file in current folder. Syntax is exportHMM <index>.
       if (command.indexOf("exportHMM") > -1)
       {
 
@@ -56,7 +66,12 @@ public class ProbabilityAnalyserKickstarter
         analyser.printHMMToFile(index);
         continue;
       }
-
+      // Processes data. Syntax is run <number of loops> <increments>. The
+      // number loops specifies the number of increments the program will run.
+      // After each increment, the data stored currently in the program is
+      // exported and re-read back into the program. This is to ensure that the
+      // program can be terminated without losing a large quantity of data. The
+      // increment is the number of families read per 'save'.
       if (command.indexOf("run") > -1)
       {
         inputScanner.next();
@@ -70,19 +85,20 @@ public class ProbabilityAnalyserKickstarter
         }
         continue;
       }
-
+      // terminates program. Syntax is terminate.
       if (command.indexOf("terminate") > -1)
       {
         running = false;
         continue;
       }
-
+      // clears files in current directory (Only a specific set of files).
+      // Syntax is clear.
       if (command.indexOf("clear") > -1)
       {
         analyser.clear();
         continue;
       }
-
+      // changes current directory. Syntax is cd <directory>
       if (command.indexOf("cd") > -1)
       {
         inputScanner.next();
diff --git a/test/jalview/util/HMMProbabilityDistributionAnalyserTest.java b/test/jalview/util/HMMProbabilityDistributionAnalyserTest.java
new file mode 100644 (file)
index 0000000..04c7890
--- /dev/null
@@ -0,0 +1,9 @@
+package jalview.util;
+
+import org.testng.annotations.Test;
+
+public class HMMProbabilityDistributionAnalyserTest {
+  @Test
+  public void f() {
+  }
+}