1 /*
2 * The baseCode project
3 *
4 * Copyright (c) 2006 University of British Columbia
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 *
18 */
19 package ubic.basecode.dataStructure.matrix;
20
21 import java.util.Iterator;
22 import java.util.List;
23
24 /**
25 * Represents a matrix with index columns and rows. The keys are generic.
26 *
27 * @author Paul Pavlidis
28 *
29 * @see ObjectMatrix for matrix storing objects.
30 */
31 public abstract interface Matrix2D<R, C, V> {
32
33 /**
34 * Add a column name, to the end of the current column names. Useful when building up a matrix in stages.
35 *
36 * @param s Object a column name
37 */
38 public void addColumnName( C s );
39
40 /**
41 * Attempt to coerce the entries into doubles.
42 * <p>
43 * Numeric entries (Double, BigDecimal, Integer, BigInteger) and Strings that can be parsed as doubles are
44 * converted. Booleans are converted to 1 or 0. Dates are converted via Date.getDate(). Null entries are rendered as
45 * Double.NaN. For entries that are other types of objects, the HashCode is used.
46 *
47 * @return
48 */
49 public double[][] asDoubles();
50
51 /**
52 * Set all values in the matrix to the given value.
53 *
54 * @param value
55 */
56 public void assign( V value );
57
58 /**
59 * Get the number of columns the matrix has.
60 *
61 * @return int
62 */
63 public int columns();
64
65 /**
66 * @param columnName
67 * @return
68 */
69 public boolean containsColumnName( C columnName );
70
71 /**
72 * @param rowName
73 * @return
74 */
75 public boolean containsRowName( R rowName );
76
77 /**
78 * @param r
79 * @param c
80 */
81 public V getByKeys( R r, C c );
82
83 /**
84 * Get the index of a column by name.
85 *
86 * @param s Object
87 * @return int
88 */
89 public int getColIndexByName( C s );
90
91 /**
92 * Gte the column name for an index.
93 *
94 * @param i int
95 * @return java.lang.Object
96 */
97 public C getColName( int i );
98
99 /**
100 * @return list of column names. Do not modify this list. Use the addColumnName methods.
101 */
102 public List<C> getColNames();
103
104 /**
105 * @param i
106 * @param j
107 * @return
108 */
109 public V getEntry( int i, int j );
110
111 /**
112 * Get the index of a row by name..
113 *
114 * @param s Object
115 * @return int
116 */
117 public int getRowIndexByName( R s );
118
119 /**
120 * Get the row name for an index
121 *
122 * @param i int
123 * @return java.lang.Object
124 */
125 public R getRowName( int i );
126
127 /**
128 * @return java.util.Iterator
129 */
130 public Iterator<R> getRowNameMapIterator();
131
132 /**
133 * @return
134 */
135 public List<R> getRowNames();
136
137 /**
138 * Check if this matrix has a valid set of column names.
139 *
140 * @return boolean
141 */
142 public boolean hasColNames();
143
144 /**
145 * @param r Object
146 * @return boolean
147 */
148 public boolean hasRow( R r );
149
150 /**
151 * @return boolean
152 */
153 public boolean hasRowNames();
154
155 /**
156 * Check if the value at a given index is missing.
157 *
158 * @param i row
159 * @param j column
160 * @return true if the value is missing, false otherwise.
161 */
162 public boolean isMissing( int i, int j );
163
164 /**
165 * Return the number of missing values in the matrix.
166 *
167 * @return
168 */
169 public int numMissing();
170
171 /**
172 * Get the number of rows the matrix has
173 *
174 * @return int
175 */
176 public int rows();
177
178 /**
179 * @param row
180 * @param column
181 * @param value
182 */
183 public void set( int row, int column, V value );
184
185 /**
186 * @param r
187 * @param c
188 * @param v
189 */
190 public void setByKeys( R r, C c, V v );
191
192 /**
193 * Add a column name associated with an index.
194 *
195 * @param s Object a column name
196 * @param index int the column index associated with this name
197 */
198 public void setColumnName( C s, int index );
199
200 /**
201 * @param v
202 */
203 public void setColumnNames( List<C> v );
204
205 /**
206 * Add a row name associated with a row index.
207 *
208 * @param s Object
209 * @param index int
210 */
211 public void setRowName( R s, int index );
212
213 /**
214 * @param v
215 */
216 public void setRowNames( List<R> v );
217
218 }