Class |
Line # |
Actions |
|||
---|---|---|---|---|---|
MatrixI | 29 | 0 | 0 |
1 | /* | |
2 | * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$) | |
3 | * Copyright (C) $$Year-Rel$$ The Jalview Authors | |
4 | * | |
5 | * This file is part of Jalview. | |
6 | * | |
7 | * Jalview is free software: you can redistribute it and/or | |
8 | * modify it under the terms of the GNU General Public License | |
9 | * as published by the Free Software Foundation, either version 3 | |
10 | * of the License, or (at your option) any later version. | |
11 | * | |
12 | * Jalview is distributed in the hope that it will be useful, but | |
13 | * WITHOUT ANY WARRANTY; without even the implied warranty | |
14 | * of MERCHANTABILITY or FITNESS FOR A PARTICULAR | |
15 | * PURPOSE. See the GNU General Public License for more details. | |
16 | * | |
17 | * You should have received a copy of the GNU General Public License | |
18 | * along with Jalview. If not, see <http://www.gnu.org/licenses/>. | |
19 | * The Jalview Authors are detailed in the 'AUTHORS' file. | |
20 | */ | |
21 | package jalview.math; | |
22 | ||
23 | import java.io.PrintStream; | |
24 | ||
25 | /** | |
26 | * An interface that describes a rectangular matrix of double values and | |
27 | * operations on it | |
28 | */ | |
29 | public interface MatrixI | |
30 | { | |
31 | /** | |
32 | * Answers the number of columns | |
33 | * | |
34 | * @return | |
35 | */ | |
36 | int width(); | |
37 | ||
38 | /** | |
39 | * Answers the number of rows | |
40 | * | |
41 | * @return | |
42 | */ | |
43 | int height(); | |
44 | ||
45 | /** | |
46 | * Answers the value at row i, column j | |
47 | * | |
48 | * @param i | |
49 | * @param j | |
50 | * @return | |
51 | */ | |
52 | double getValue(int i, int j); | |
53 | ||
54 | /** | |
55 | * Sets the value at row i, colum j | |
56 | * | |
57 | * @param i | |
58 | * @param j | |
59 | * @param d | |
60 | */ | |
61 | void setValue(int i, int j, double d); | |
62 | ||
63 | /** | |
64 | * Returns the matrix as a double[][] array | |
65 | * | |
66 | * @return | |
67 | */ | |
68 | double[][] asArray(); | |
69 | ||
70 | /** | |
71 | * Answers a copy of the values in the i'th row | |
72 | * | |
73 | * @return | |
74 | */ | |
75 | double[] getRow(int i); | |
76 | ||
77 | /** | |
78 | * Answers a copy of the values in the i'th column | |
79 | * | |
80 | * @return | |
81 | */ | |
82 | double[] getColumn(int i); | |
83 | ||
84 | /** | |
85 | * Answers a new matrix with a copy of the values in this one | |
86 | * | |
87 | * @return | |
88 | */ | |
89 | MatrixI copy(); | |
90 | ||
91 | /** | |
92 | * Returns a new matrix which is the transpose of this one | |
93 | * | |
94 | * @return | |
95 | */ | |
96 | MatrixI transpose(); | |
97 | ||
98 | /** | |
99 | * Returns a new matrix which is the result of premultiplying this matrix by | |
100 | * the supplied argument. If this of size AxB (A rows and B columns), and the | |
101 | * argument is CxA (C rows and A columns), the result is of size CxB. | |
102 | * | |
103 | * @param in | |
104 | * | |
105 | * @return | |
106 | * @throws IllegalArgumentException | |
107 | * if the number of columns in the pre-multiplier is not equal to | |
108 | * the number of rows in the multiplicand (this) | |
109 | */ | |
110 | MatrixI preMultiply(MatrixI m); | |
111 | ||
112 | /** | |
113 | * Returns a new matrix which is the result of postmultiplying this matrix by | |
114 | * the supplied argument. If this of size AxB (A rows and B columns), and the | |
115 | * argument is BxC (B rows and C columns), the result is of size AxC. | |
116 | * <p> | |
117 | * This method simply returns the result of in.preMultiply(this) | |
118 | * | |
119 | * @param in | |
120 | * | |
121 | * @return | |
122 | * @throws IllegalArgumentException | |
123 | * if the number of rows in the post-multiplier is not equal to the | |
124 | * number of columns in the multiplicand (this) | |
125 | * @see #preMultiply(Matrix) | |
126 | */ | |
127 | MatrixI postMultiply(MatrixI m); | |
128 | ||
129 | double[] getD(); | |
130 | ||
131 | double[] getE(); | |
132 | ||
133 | void setD(double[] v); | |
134 | ||
135 | void setE(double[] v); | |
136 | ||
137 | void print(PrintStream ps, String format); | |
138 | ||
139 | void printD(PrintStream ps, String format); | |
140 | ||
141 | void printE(PrintStream ps, String format); | |
142 | ||
143 | void tqli() throws Exception; | |
144 | ||
145 | void tred(); | |
146 | ||
147 | /** | |
148 | * Reverses the range of the matrix values, so that the smallest values become | |
149 | * the largest, and the largest become the smallest. This operation supports | |
150 | * using a distance measure as a similarity measure, or vice versa. | |
151 | * <p> | |
152 | * If parameter <code>maxToZero</code> is true, then the maximum value becomes | |
153 | * zero, i.e. all values are subtracted from the maximum. This is consistent | |
154 | * with converting an identity similarity score to a distance score - the most | |
155 | * similar (identity) corresponds to zero distance. However note that the | |
156 | * operation is not reversible (unless the original minimum value is zero). | |
157 | * For example a range of 10-40 would become 30-0, which would reverse a | |
158 | * second time to 0-30. Also note that a general similarity measure (such as | |
159 | * BLOSUM) may give different 'identity' scores for different sequences, so | |
160 | * they cannot all convert to zero distance. | |
161 | * <p> | |
162 | * If parameter <code>maxToZero</code> is false, then the values are reflected | |
163 | * about the average of {min, max} (effectively swapping min and max). This | |
164 | * operation <em>is</em> reversible. | |
165 | * | |
166 | * @param maxToZero | |
167 | */ | |
168 | void reverseRange(boolean maxToZero); | |
169 | ||
170 | /** | |
171 | * Multiply all entries by the given value | |
172 | * | |
173 | * @param d | |
174 | */ | |
175 | void multiply(double d); | |
176 | ||
177 | /** | |
178 | * Add d to all entries of this matrix | |
179 | * | |
180 | * @param d | |
181 | * ~ value to add | |
182 | */ | |
183 | void add(double d); | |
184 | ||
185 | /** | |
186 | * Answers true if the two matrices have the same dimensions, and | |
187 | * corresponding values all differ by no more than delta (which should be a | |
188 | * positive value), else false | |
189 | * | |
190 | * @param m2 | |
191 | * @param delta | |
192 | * @return | |
193 | */ | |
194 | boolean equals(MatrixI m2, double delta); | |
195 | ||
196 | /** | |
197 | * Returns a copy in which every value in the matrix is its absolute | |
198 | */ | |
199 | MatrixI absolute(); | |
200 | ||
201 | /** | |
202 | * Returns the mean of each row | |
203 | */ | |
204 | double[] meanRow(); | |
205 | ||
206 | /** | |
207 | * Returns the mean of each column | |
208 | */ | |
209 | double[] meanCol(); | |
210 | ||
211 | /** | |
212 | * Returns a flattened matrix containing the sum of each column | |
213 | * | |
214 | * @return | |
215 | */ | |
216 | double[] sumCol(); | |
217 | ||
218 | /** | |
219 | * returns the mean value of the complete matrix | |
220 | */ | |
221 | double mean(); | |
222 | ||
223 | /** | |
224 | * fills up a diagonal matrix with its transposed copy !other side should be | |
225 | * filled with either 0 or Double.NaN | |
226 | */ | |
227 | void fillDiagonal(); | |
228 | ||
229 | /** | |
230 | * counts the number of Double.NaN in the matrix | |
231 | * | |
232 | * @return | |
233 | */ | |
234 | int countNaN(); | |
235 | ||
236 | /** | |
237 | * performs an element-wise addition of this matrix by another matrix | |
238 | * !matrices have to be the same size | |
239 | * | |
240 | * @param m | |
241 | * ~ other matrix | |
242 | * | |
243 | * @return | |
244 | * @throws IllegalArgumentException | |
245 | * if this and m do not have the same dimensions | |
246 | */ | |
247 | MatrixI add(MatrixI m); | |
248 | ||
249 | /** | |
250 | * performs an element-wise subtraction of this matrix by another matrix | |
251 | * !matrices have to be the same size | |
252 | * | |
253 | * @param m | |
254 | * ~ other matrix | |
255 | * | |
256 | * @return | |
257 | * @throws IllegalArgumentException | |
258 | * if this and m do not have the same dimensions | |
259 | */ | |
260 | MatrixI subtract(MatrixI m); | |
261 | ||
262 | /** | |
263 | * performs an element-wise multiplication of this matrix by another matrix ~ | |
264 | * this * m !matrices have to be the same size | |
265 | * | |
266 | * @param m | |
267 | * ~ other matrix | |
268 | * | |
269 | * @return | |
270 | * @throws IllegalArgumentException | |
271 | * if this and m do not have the same dimensions | |
272 | */ | |
273 | MatrixI elementwiseMultiply(MatrixI m); | |
274 | ||
275 | /** | |
276 | * performs an element-wise division of this matrix by another matrix ~ this / | |
277 | * m !matrices have to be the same size | |
278 | * | |
279 | * @param m | |
280 | * ~ other matrix | |
281 | * | |
282 | * @return | |
283 | * @throws IllegalArgumentException | |
284 | * if this and m do not have the same dimensions | |
285 | */ | |
286 | MatrixI elementwiseDivide(MatrixI m); | |
287 | ||
288 | /** | |
289 | * calculates the root-mean-square for two matrices | |
290 | * | |
291 | * @param m | |
292 | * ~ other matrix | |
293 | * | |
294 | * @return | |
295 | */ | |
296 | double rmsd(MatrixI m); | |
297 | ||
298 | /** | |
299 | * calculates the Frobenius norm of this matrix | |
300 | * | |
301 | * @return | |
302 | */ | |
303 | double norm(); | |
304 | ||
305 | /** | |
306 | * returns the sum of all values in this matrix | |
307 | * | |
308 | * @return | |
309 | */ | |
310 | double sum(); | |
311 | ||
312 | /** | |
313 | * returns the sum-product of this matrix with vector v | |
314 | * | |
315 | * @param v | |
316 | * ~ vector | |
317 | * | |
318 | * @return | |
319 | * @throws IllegalArgumentException | |
320 | * if this.cols and v do not have the same length | |
321 | */ | |
322 | double[] sumProduct(double[] v); | |
323 | ||
324 | /** | |
325 | * mirrors the columns of this matrix | |
326 | * | |
327 | * @return | |
328 | */ | |
329 | MatrixI mirrorCol(); | |
330 | } |