JAL-2403 JAL-1483 push 'reverseRange' inside Matrix

[jalview.git] / src / jalview / math / MatrixI.java

diff --git a/src/jalview/math/MatrixI.java b/src/jalview/math/MatrixI.java
index 05fe22f..d7a1b70 100644 (file)
--- a/src/jalview/math/MatrixI.java
+++ b/src/jalview/math/MatrixI.java
@@ -65,12 +65,26 @@ public interface MatrixI
 
   void tred();
 
-  double getMaxValue();
-
   /**
-   * Update each value in the matrix by subtracting it from the given value
+   * Reverses the range of the matrix values, so that the smallest values become
+   * the largest, and the largest become the smallest. This operation supports
+   * using a distance measure as a similarity measure, or vice versa.
+   * <p>
+   * If parameter <code>maxToZero</code> is true, then the maximum value becomes
+   * zero, i.e. all values are subtracted from the maximum. This is consistent
+   * with converting a similarity score to a distance score - the most similar
+   * (identity) corresponds to zero distance. However note that the operation is
+   * not reversible (unless the original minimum value is zero). For example a
+   * range of 10-40 would become 30-0, which would reverse a second time to
+   * 0-30. Also note that a similarity measure (such as BLOSUM) may give
+   * different identity scores for different sequences, so they cannot all
+   * convert to zero distance.
+   * <p>
+   * If parameter <code>maxToZero</code> is false, then the values are reflected
+   * about the average of {min, max} (effectively swapping min and max). This
+   * operation <em>is</em> reversible.
    * 
-   * @param val
+   * @param maxToZero
    */
-  void subtractAllFrom(double val);
+  void reverseRange(boolean maxToZero);
 }