00001 // Specimen.h 00002 00003 #ifndef SPECIMEN_H 00004 #define SPECIMEN_H 00005 00006 #include <string> 00007 #include <vector> 00008 #include <list> 00009 00010 #include "Cell.h" 00011 00012 namespace Yosokumo 00013 { 00014 /** 00015 * A row of values. Other terminology that is sometimes used: An 00016 * observation, a record, an example, or an instance. These are 00017 * the primary characteristics of a <code>Specimen</code>: 00018 * 00019 * <ul> 00020 * <li>a key - unsigned integer 00021 * <li>a status - active or inactive 00022 * <li>a weight - positive integer 00023 * <li>a predictand - value for this specimen 00024 * <li>a sequence of zero or more <code>Cells</code> containing the values 00025 * of the row 00026 * </ul> 00027 * 00028 * @author Roger House 00029 * @version 0.9 00030 */ 00031 class Specimen 00032 { 00033 public: 00034 /** 00035 * Provides a logical delete facility. The default value is 00036 * <code>ACTIVE</code>. 00037 */ 00038 enum Status 00039 { 00040 /** 00041 * the specimen is active, i.e., it should be considered when 00042 * constructing the model. 00043 */ 00044 ACTIVE, 00045 /** 00046 * the specimen is inactive, i.e., it should not be considered when 00047 * constructing the model. 00048 */ 00049 INACTIVE 00050 }; 00051 00052 private: 00053 00054 uint64_t key; 00055 Status status; 00056 uint64_t weight; 00057 Value predictand; 00058 00059 // At present the cellSequence list is implemented as a vector<Cell> 00060 // because this implementation has O(1) performance for all three of 00061 // "get", "add", and "next". The latter is used to iterate over the 00062 // list, and thus we do not want it to be expensive. The "add" method 00063 // appends to the end of the list. -- Essentially, we want an array 00064 // which can grow in size. 00065 00066 /** 00067 * A sequence of cells. 00068 */ 00069 std::vector<Cell> cellSequence; 00070 00071 public: 00072 00073 // Constructors 00074 00075 /** 00076 * Initializes a newly created <code>Specimen</code> object with default 00077 * values: 00078 * <ul> 00079 * <li>key - 0 00080 * <li>status - ACTIVE 00081 * <li>weight - 1 00082 * <li>predictand - EmptyValue 00083 * <li>cell sequence - empty 00084 * </ul> 00085 */ 00086 Specimen(); 00087 00088 /** 00089 * Initializes a newly created <code>Specimen</code> object with key 00090 * specified by the input parameter. Other attributes are set to default 00091 * values: 00092 * <ul> 00093 * <li>status - ACTIVE 00094 * <li>weight - 1 00095 * <li>predictand - EmptyValue 00096 * <li>cell sequence - empty 00097 * </ul> 00098 * 00099 * @param key the key of the specimen. 00100 */ 00101 Specimen(uint64_t key); 00102 00103 /** 00104 * Initializes a newly created <code>Specimen</code> object with key and 00105 * cell sequence as specified by the input parameters. Other attributes 00106 * are set to default values: 00107 * <ul> 00108 * <li>status - ACTIVE 00109 * <li>weight - 1 00110 * <li>predictand - EmptyValue 00111 * </ul> 00112 * 00113 * @param key the key of the specimen. 00114 * @param begin an iterator specifying the beginning of a cell vector. 00115 * @param end an iterator specifying the end of a cell vector. 00116 */ 00117 Specimen 00118 ( 00119 uint64_t key, 00120 std::vector<Cell>::iterator begin, 00121 std::vector<Cell>::iterator end 00122 ); 00123 00124 /** 00125 * Initializes a newly created <code>Specimen</code> object with key and 00126 * cell sequence as specified by the input parameters. Other attributes 00127 * are set to default values: 00128 * <ul> 00129 * <li>status - ACTIVE 00130 * <li>weight - 1 00131 * <li>predictand - EmptyValue 00132 * </ul> 00133 * 00134 * @param key the key of the specimen. 00135 * @param begin an iterator specifying the beginning of a cell list. 00136 * @param end an iterator specifying the end of a cell list. 00137 */ 00138 Specimen 00139 ( 00140 uint64_t key, 00141 std::list<Cell>::iterator begin, 00142 std::list<Cell>::iterator end 00143 ); 00144 00145 /** 00146 * Initializes a newly created <code>Specimen</code> object with key, 00147 * predictand, and cell sequence as specified by the input parameters. 00148 * Other attributes are set to default values: 00149 * <ul> 00150 * <li>status - ACTIVE 00151 * <li>weight - 1 00152 * </ul> 00153 * 00154 * @param key the key of the specimen. 00155 * @param predictand the predictand of the specimen. 00156 * @param begin an iterator specifying the beginning of a cell vector. 00157 * @param end an iterator specifying the end of a cell vector. 00158 */ 00159 Specimen 00160 ( 00161 uint64_t key, 00162 Value predictand, 00163 std::vector<Cell>::iterator begin, 00164 std::vector<Cell>::iterator end 00165 ); 00166 00167 /** 00168 * Initializes a newly created <code>Specimen</code> object with key, 00169 * predictand, and cell sequence as specified by the input parameters. 00170 * Other attributes are set to default values: 00171 * <ul> 00172 * <li>status - ACTIVE 00173 * <li>weight - 1 00174 * </ul> 00175 * 00176 * @param key the key of the specimen. 00177 * @param predictand the predictand of the specimen. 00178 * @param begin an iterator specifying the beginning of a cell list. 00179 * @param end an iterator specifying the end of a cell list. 00180 */ 00181 Specimen 00182 ( 00183 uint64_t key, 00184 Value predictand, 00185 std::list<Cell>::iterator begin, 00186 std::list<Cell>::iterator end 00187 ); 00188 00189 /** 00190 * Initializes a newly created <code>Specimen</code> object with 00191 # attributes specified by the input parameters. 00192 * 00193 * @param key the key of the specimen. 00194 * @param status the status of the specimen. 00195 * @param weight the weight of the specimen. 00196 * @param predictand the predictand of the specimen. 00197 * @param begin an iterator specifying the beginning of a cell vector. 00198 * @param end an iterator specifying the end of a cell vector. 00199 */ 00200 Specimen 00201 ( 00202 uint64_t key, 00203 Status status, 00204 uint64_t weight, 00205 Value predictand, 00206 std::vector<Cell>::iterator begin, 00207 std::vector<Cell>::iterator end 00208 ); 00209 00210 /** 00211 * Initializes a newly created <code>Specimen</code> object with 00212 # attributes specified by the input parameters. 00213 * 00214 * @param key the key of the specimen. 00215 * @param status the status of the specimen. 00216 * @param weight the weight of the specimen. 00217 * @param predictand the predictand of the specimen. 00218 * @param begin an iterator specifying the beginning of a cell list. 00219 * @param end an iterator specifying the end of a cell list. 00220 */ 00221 Specimen 00222 ( 00223 uint64_t key, 00224 Status status, 00225 uint64_t weight, 00226 Value predictand, 00227 std::list<Cell>::iterator begin, 00228 std::list<Cell>::iterator end 00229 ); 00230 00231 00232 /** 00233 * Copy constructor - initializes a newly created <code>Specimen</code> 00234 * object with a copy of another <code>Specimen</code> object. 00235 * 00236 * @param rhs the <code>Specimen</code> to make a copy of. 00237 */ 00238 Specimen(const Specimen &rhs); 00239 00240 00241 /** 00242 * Destructor - destroy a <code>Specimen</code> object. 00243 */ 00244 virtual ~Specimen(); 00245 00246 00247 /** 00248 * Assignment operator - assign one <code>Specimen</code> to another. 00249 * 00250 * @param rhs the righthand side of the assignment. 00251 * 00252 * @return a reference to <code>this</code> Specimen. 00253 */ 00254 Specimen& operator=(const Specimen& rhs); 00255 00256 00257 // Setters and getters 00258 00259 /** 00260 * Set the specimen key. 00261 * 00262 * @param key the key to assign to this specimen. This is the 00263 * unique identification of the specimen. It must be positive. 00264 */ 00265 void setSpecimenKey(uint64_t key); 00266 00267 /** 00268 * Return the specimen key. 00269 * 00270 * @return the key of this specimen, which is the unique 00271 * identification of the specimen. 00272 */ 00273 uint64_t getSpecimenKey() const; 00274 00275 00276 /** 00277 * Set the specimen status. 00278 * 00279 * @param s the status to assign to this specimen. 00280 */ 00281 void setStatus(Status s); 00282 00283 /** 00284 * Return the specimen status. 00285 * 00286 * @return the status of this specimen. 00287 */ 00288 Status getStatus() const; 00289 00290 00291 /** 00292 * Set the specimen weight. 00293 * 00294 * @param w the weight to assign to this specimen. 00295 */ 00296 void setWeight(uint64_t w); 00297 00298 /** 00299 * Return the specimen weight. 00300 * 00301 * @return the weight of this specimen. 00302 */ 00303 uint64_t getWeight() const; 00304 00305 00306 /** 00307 * Set the specimen predictand. 00308 * 00309 * @param v the predictand to assign to this specimen. 00310 */ 00311 void setPredictand(Value v); 00312 00313 /** 00314 * Return the specimen predictand. 00315 * 00316 * @return the predictand of this specimen. 00317 */ 00318 Value getPredictand() const; 00319 00320 00321 // Access to the cell sequence 00322 00323 /** 00324 * Add a <code>Cell</code> to the cell sequence. The <code>Cell</code> 00325 * parameter is appended to the end of the cell sequence. 00326 * 00327 * @param cell the <code>Cell</code> to add to the cell sequence. 00328 */ 00329 void addCell(const Cell &cell); 00330 00331 00332 /** 00333 * Add a collection of <code>Cell</code> to the cell sequence. The 00334 * <code>Cells</code> in the vector specified by the parameters are 00335 * appended to the end of the cell sequence. 00336 * 00337 * @param begin an iterator specifying the beginning of the cell 00338 * vector to add to the block. 00339 * @param end an iterator specifying the end of the cell 00340 * vector to add to the block. 00341 * 00342 * @return true if and only if the cell sequence changes. 00343 */ 00344 bool addCells 00345 ( 00346 std::vector<Cell>::iterator begin, 00347 std::vector<Cell>::iterator end 00348 ); 00349 00350 /** 00351 * Add a collection of <code>Cells</code> to the cell sequence. The 00352 * <code>Cells</code> in the list specified by the parameters are 00353 * appended to the end of the cell sequence. 00354 * 00355 * @param begin an iterator specifying the beginning of the cell 00356 * list to add to the block. 00357 * @param end an iterator specifying the end of the cell 00358 * list to add to the block. 00359 * 00360 * @return true if and only if the cell sequence changes. 00361 */ 00362 bool addCells 00363 ( 00364 std::list<Cell>::iterator begin, 00365 std::list<Cell>::iterator end 00366 ); 00367 00368 /** 00369 * Remove cells from the end of the sequence. The specified number of 00370 * cells are removed from the end of the cell sequence. 00371 * 00372 * @param numCellsToRemove is the number of cells to remove from the 00373 * end of the sequence. If this value is zero, no cells are 00374 * removed. If this value exceeds the number of cells in the 00375 * sequence, then all cells are removed. 00376 * 00377 * @return true if and only if the sequence is changed. 00378 */ 00379 bool removeCells(uint64_t numCellsToRemove); 00380 00381 00382 /** 00383 * Return a cell from the cell sequence. This makes it possible to 00384 * iterate over all cells in the sequence like this: 00385 * <pre> 00386 * for (int i = 0; i < cellSequence.size(); ++i) 00387 * { 00388 * Cell c = cellSequence.getCell(i) 00389 * process cell c 00390 * } 00391 * </pre> 00392 * 00393 * @param index specifying which cell of the sequence to return. 0-based. 00394 * 00395 * @return the <code>Cell</code> at the location specified by the index. 00396 */ 00397 Cell getCell(int index) const; 00398 00399 /** 00400 * Remove all cells from the sequence. After a call of this method, 00401 * the sequence is empty, i.e., it contains no cells. 00402 * 00403 */ 00404 void clearCells(); 00405 00406 /** 00407 * Return the number of cells in the sequence. 00408 * 00409 * @return the number of cells in the sequence. 00410 */ 00411 uint64_t size() const; 00412 00413 /** 00414 * Return <code>true</code> if the sequence contains no cells. 00415 * 00416 * @return <code>true</code> if the sequence contains no cells. 00417 * <code>false</code> otherwise. 00418 */ 00419 bool isEmpty() const; 00420 00421 00422 // Utility 00423 00424 /** 00425 * Return a string representation of this <code>Specimen</code>. 00426 * 00427 * @return the string representation of this <code>Specimen</code>. 00428 */ 00429 std::string toString() const; 00430 00431 }; // end class Specimen 00432 00433 } // end namespace Yosokumo 00434 00435 #endif // SPECIMEN_H 00436 00437 // end Specimen.h