yat/classifier/MatrixLookup.h

Code
Comments
Other
Rev Date Author Line
2863 03 Oct 12 peter 1 #ifndef _theplu_yat_classifier_matrix_lookup_
2863 03 Oct 12 peter 2 #define _theplu_yat_classifier_matrix_lookup_
455 16 Dec 05 markus 3
616 31 Aug 06 jari 4 // $Id$
616 31 Aug 06 jari 5
675 10 Oct 06 jari 6 /*
2119 12 Dec 09 peter 7   Copyright (C) 2005 Peter Johansson, Markus Ringnér
2119 12 Dec 09 peter 8   Copyright (C) 2006 Jari Häkkinen, Peter Johansson, Markus Ringnér
2119 12 Dec 09 peter 9   Copyright (C) 2007, 2008 Jari Häkkinen, Peter Johansson
4207 26 Aug 22 peter 10   Copyright (C) 2009, 2010, 2012, 2020, 2022 Peter Johansson
455 16 Dec 05 markus 11
1437 25 Aug 08 peter 12   This file is part of the yat library, http://dev.thep.lu.se/yat
675 10 Oct 06 jari 13
675 10 Oct 06 jari 14   The yat library is free software; you can redistribute it and/or
675 10 Oct 06 jari 15   modify it under the terms of the GNU General Public License as
1486 09 Sep 08 jari 16   published by the Free Software Foundation; either version 3 of the
675 10 Oct 06 jari 17   License, or (at your option) any later version.
675 10 Oct 06 jari 18
675 10 Oct 06 jari 19   The yat library is distributed in the hope that it will be useful,
675 10 Oct 06 jari 20   but WITHOUT ANY WARRANTY; without even the implied warranty of
675 10 Oct 06 jari 21   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
675 10 Oct 06 jari 22   General Public License for more details.
675 10 Oct 06 jari 23
675 10 Oct 06 jari 24   You should have received a copy of the GNU General Public License
1487 10 Sep 08 jari 25   along with yat. If not, see <http://www.gnu.org/licenses/>.
675 10 Oct 06 jari 26 */
675 10 Oct 06 jari 27
1110 19 Feb 08 peter 28 #include "yat/utility/Container2DIterator.h"
2223 19 Mar 10 peter 29 #include "yat/utility/deprecate.h"
1134 23 Feb 08 peter 30 #include "yat/utility/Index.h"
1080 13 Feb 08 peter 31 #include "yat/utility/iterator_traits.h"
1528 24 Sep 08 peter 32 #include "yat/utility/Matrix.h"
675 10 Oct 06 jari 33
1528 24 Sep 08 peter 34 #include <boost/iterator/permutation_iterator.hpp>
1528 24 Sep 08 peter 35
2076 06 Oct 09 peter 36 #include <iosfwd>
4019 06 Nov 20 peter 37 #include <memory>
757 19 Feb 07 jari 38 #include <vector>
455 16 Dec 05 markus 39
455 16 Dec 05 markus 40 namespace theplu {
680 11 Oct 06 jari 41 namespace yat {
2863 03 Oct 12 peter 42 namespace classifier {
455 16 Dec 05 markus 43
455 16 Dec 05 markus 44   ///
1192 29 Feb 08 peter 45   /// @brief General view into utility::Matrix
767 22 Feb 07 peter 46   ///
590 24 Aug 06 peter 47   /// MatrixLookups can be used to create lookups/views into matrices
590 24 Aug 06 peter 48   /// in a more general way than the views supported in the matrix
590 24 Aug 06 peter 49   /// class. The object does not contain any data, but only a pointer
1191 29 Feb 08 peter 50   /// to a utility::Matrix and row and columns incices defining which
590 24 Aug 06 peter 51   /// sub-matrix to look into.  Each row and each column corresponds
1191 29 Feb 08 peter 52   /// to a row and a column in the utility::Matrix, respectively. This design
590 24 Aug 06 peter 53   /// allow for fast creation of sub-matrices, which is a common
826 19 Mar 07 peter 54   /// operation in most traning/validation procedures. The views are
826 19 Mar 07 peter 55   /// const views in the sense that they cannot modify underlying
1191 29 Feb 08 peter 56   /// utility::Matrix.
455 16 Dec 05 markus 57   ///
2863 03 Oct 12 peter 58   /// A MatrixLookup can be created directly from a utility::Matrix or from
1191 29 Feb 08 peter 59   /// another MatrixLookup. In the latter case, the resulting
1191 29 Feb 08 peter 60   /// MatrixLookup is looking directly into the underlying utility::Matrix to
590 24 Aug 06 peter 61   /// avoid multiple lookups.
590 24 Aug 06 peter 62   ///
590 24 Aug 06 peter 63   /// There is a possibility to set the MatrixLookup as owner of the
1191 29 Feb 08 peter 64   /// underlying utility::Matrix. This implies that underlying data is deleted
826 19 Mar 07 peter 65   /// in destructor of MatrixLookup, but only if there is no other
2863 03 Oct 12 peter 66   /// owner of the underlying data.
590 24 Aug 06 peter 67   ///
1192 29 Feb 08 peter 68   /// \see MatrixLookupWeighted
1192 29 Feb 08 peter 69   ///
1170 27 Feb 08 peter 70   class MatrixLookup
455 16 Dec 05 markus 71   {
1063 10 Feb 08 peter 72   public:
1549 06 Oct 08 peter 73     /**
1549 06 Oct 08 peter 74        value_type is double
1549 06 Oct 08 peter 75
1549 06 Oct 08 peter 76        \since New in yat 0.5
1549 06 Oct 08 peter 77      */
1549 06 Oct 08 peter 78     typedef utility::Matrix::value_type value_type;
1549 06 Oct 08 peter 79
1549 06 Oct 08 peter 80     /**
1549 06 Oct 08 peter 81        const_reference type is const double&
1549 06 Oct 08 peter 82
1549 06 Oct 08 peter 83        \since New in yat 0.5
1549 06 Oct 08 peter 84      */
1549 06 Oct 08 peter 85     typedef utility::Matrix::const_reference const_reference;
1549 06 Oct 08 peter 86
1063 10 Feb 08 peter 87     /// 'Read Only' iterator
2863 03 Oct 12 peter 88     typedef utility::Container2DIterator<const MatrixLookup, const double,
1565 10 Oct 08 peter 89                                          const_reference>
1063 10 Feb 08 peter 90     const_iterator;
1062 10 Feb 08 peter 91
1125 22 Feb 08 peter 92     /**
1125 22 Feb 08 peter 93        'Read only' iterator used to iterate over a column
1125 22 Feb 08 peter 94      */
1528 24 Sep 08 peter 95     typedef boost::permutation_iterator<utility::Matrix::const_column_iterator,
2863 03 Oct 12 peter 96                                         utility::Index::const_iterator>
1528 24 Sep 08 peter 97     const_column_iterator;
1125 22 Feb 08 peter 98
1125 22 Feb 08 peter 99     /**
1125 22 Feb 08 peter 100        'Read only' iterator used to iterate over a row
1125 22 Feb 08 peter 101      */
1528 24 Sep 08 peter 102     typedef const_column_iterator const_row_iterator;
1104 18 Feb 08 peter 103
455 16 Dec 05 markus 104     ///
2863 03 Oct 12 peter 105     /// Constructor creating a lookup into the entire @a matrix.
966 11 Oct 07 peter 106     /// \param matrix underlying matrix
658 25 Sep 06 peter 107     /// @param own if true MatrixLookup owns its underlying @a matrix
455 16 Dec 05 markus 108     ///
826 19 Mar 07 peter 109     /// @note If \a own is true and \a matrix is already owned by some
826 19 Mar 07 peter 110     /// other object, this will lead to \a matrix having multiple
826 19 Mar 07 peter 111     /// owners without the owners being aware of each
2863 03 Oct 12 peter 112     /// other. Consequently multiple deletion will occur.
826 19 Mar 07 peter 113     ///
536 03 Mar 06 peter 114     /// @note If @a matrix goes out of scope or is deleted, the
536 03 Mar 06 peter 115     /// MatrixLookup becomes invalid and the result of further use is
536 03 Mar 06 peter 116     /// undefined.
536 03 Mar 06 peter 117     ///
4125 14 Jan 22 peter 118     MatrixLookup(const utility::MatrixBase& matrix, const bool own=false);
455 16 Dec 05 markus 119
590 24 Aug 06 peter 120     ///
590 24 Aug 06 peter 121     /// Constructor creating a lookup into a sub-matrix of @a matrix.
590 24 Aug 06 peter 122     /// The @a row and @a column define what sub-matrix to look into,
590 24 Aug 06 peter 123     /// in other words, the created MatrixLookup will fullfill the
590 24 Aug 06 peter 124     /// following: \f$ MatrixLookup(i,j)=matrix(row[i],column[j])
590 24 Aug 06 peter 125     /// \f$. This also means that number of rows in created
590 24 Aug 06 peter 126     /// MatrixLookup is equal to size of vector @a row, and number of
590 24 Aug 06 peter 127     /// columns is equal to size of vector @a column.
590 24 Aug 06 peter 128     ///
536 03 Mar 06 peter 129     /// @note If @a matrix goes out of scope or is deleted, the
536 03 Mar 06 peter 130     /// MatrixLookup becomes invalid and the result of further use is
536 03 Mar 06 peter 131     /// undefined.
536 03 Mar 06 peter 132     ///
4125 14 Jan 22 peter 133     MatrixLookup(const utility::MatrixBase& matrix, const utility::Index& row,
1134 23 Feb 08 peter 134                  const utility::Index& column);
455 16 Dec 05 markus 135
533 03 Mar 06 peter 136     ///
648 14 Sep 06 peter 137     /// Constructor creating a lookup into a sub-matrix of @a matrix.
590 24 Aug 06 peter 138     ///
656 22 Sep 06 peter 139     /// If @a row_vectors is true the new MatrixLookup will consist
590 24 Aug 06 peter 140     /// of the row vectors defined by @a index. This means that the
590 24 Aug 06 peter 141     /// created MatrixLookup will fullfill:
590 24 Aug 06 peter 142     /// \f$ MatrixLookup(i,j)=matrix(i,index[j]) \f$
590 24 Aug 06 peter 143     ///
590 24 Aug 06 peter 144     /// If @a row_vectors is false the new MatrixLookup will be consist
590 24 Aug 06 peter 145     /// of the rolumn vectors defined by @a index. This means that the
590 24 Aug 06 peter 146     /// created MatrixLookup will fullfill:
590 24 Aug 06 peter 147     /// \f$ MatrixLookup(i,j)=matrix(index[i],j) \f$
590 24 Aug 06 peter 148     ///
536 03 Mar 06 peter 149     /// @note If @a matrix goes out of scope or is deleted, the
536 03 Mar 06 peter 150     /// MatrixLookup becomes invalid and the result of further use is
536 03 Mar 06 peter 151     /// undefined.
536 03 Mar 06 peter 152     ///
2374 12 Dec 10 peter 153     ///  \deprecated Provided for backward compatibility with
2223 19 Mar 10 peter 154     ///  the 0.6 API. Use MatrixLookup(const utility::Matrix&, const
2223 19 Mar 10 peter 155     ///  utility::Index&, const utility::Index&)
2223 19 Mar 10 peter 156     ///
4125 14 Jan 22 peter 157     MatrixLookup(const utility::MatrixBase& matrix,
2863 03 Oct 12 peter 158                  const utility::Index& index,
2223 19 Mar 10 peter 159                  const bool row_vectors) YAT_DEPRECATE;
455 16 Dec 05 markus 160
590 24 Aug 06 peter 161     ///
590 24 Aug 06 peter 162     /// @brief Copy constructor.
590 24 Aug 06 peter 163     ///
826 19 Mar 07 peter 164     /// If \a other is owner of underlying data, constructed
826 19 Mar 07 peter 165     /// MatrixLookup will also be set as owner of underlying data.
826 19 Mar 07 peter 166     ///
536 03 Mar 06 peter 167     /// @note If underlying matrix goes out of scope or is deleted, the
536 03 Mar 06 peter 168     /// MatrixLookup becomes invalid and the result of further use is
536 03 Mar 06 peter 169     /// undefined.
536 03 Mar 06 peter 170     ///
826 19 Mar 07 peter 171     MatrixLookup(const MatrixLookup& other);
455 16 Dec 05 markus 172
590 24 Aug 06 peter 173     ///
2863 03 Oct 12 peter 174     /// @brief Create a sub-MatrixLookup.
826 19 Mar 07 peter 175     ///
826 19 Mar 07 peter 176     /// The Lookup is independent of
590 24 Aug 06 peter 177     /// MatrixLookup @a ml. The MatrixLookup is created to look
590 24 Aug 06 peter 178     /// directly into the underlying matrix to avoid multiple lookups.
590 24 Aug 06 peter 179     ///
826 19 Mar 07 peter 180     /// If \a ml is owner of underlying data, constructed
826 19 Mar 07 peter 181     /// MatrixLookup will also be set as owner of underlying data.
826 19 Mar 07 peter 182     ///
590 24 Aug 06 peter 183     /// The @a row and @a column define what sub-matrix to look into,
590 24 Aug 06 peter 184     /// in other words, the created MatrixLookup will fullfill the
826 19 Mar 07 peter 185     /// following: MatrixLookup(i,j)=ml(row[i],column[j]). This
590 24 Aug 06 peter 186     /// also means that number of rows in created MatrixLookup is
590 24 Aug 06 peter 187     /// equal to size of vector @a row, and number of columns is equal
590 24 Aug 06 peter 188     /// to size of vector @a column.
590 24 Aug 06 peter 189     ///
826 19 Mar 07 peter 190     /// If \a ml is owner of underlying data, constructed
826 19 Mar 07 peter 191     /// MatrixLookup will also be set as owner of underlying data.
826 19 Mar 07 peter 192     ///
536 03 Mar 06 peter 193     /// @note If underlying matrix goes out of scope or is deleted, the
536 03 Mar 06 peter 194     /// MatrixLookup becomes invalid and the result of further use is
536 03 Mar 06 peter 195     /// undefined.
536 03 Mar 06 peter 196     ///
2863 03 Oct 12 peter 197     MatrixLookup(const MatrixLookup& ml, const utility::Index& row,
1134 23 Feb 08 peter 198                  const utility::Index& column);
469 19 Dec 05 peter 199
590 24 Aug 06 peter 200     ///
590 24 Aug 06 peter 201     /// Constructor creating a lookup into a sub-matrix of
590 24 Aug 06 peter 202     /// @a ml. The MatrixLookup is created to look directly into the
590 24 Aug 06 peter 203     /// underlying matrix to avoid multiple lookups.
590 24 Aug 06 peter 204     ///
656 22 Sep 06 peter 205     /// If @a row_vectors is true the new MatrixLookup will consist
590 24 Aug 06 peter 206     /// of the row vectors defined by @a index. This means that the
590 24 Aug 06 peter 207     /// created MatrixLookup will fullfill:
826 19 Mar 07 peter 208     /// MatrixLookup(i,j)=ml(i,index[j])
590 24 Aug 06 peter 209     ///
656 22 Sep 06 peter 210     /// If @a row_vectors is false the new MatrixLookup will consist
590 24 Aug 06 peter 211     /// of the rolumn vectors defined by @a index. This means that the
590 24 Aug 06 peter 212     /// created MatrixLookup will fullfill:
590 24 Aug 06 peter 213     /// \f$ MatrixLookup(i,j) = ml(index[i],j) \f$
590 24 Aug 06 peter 214     ///
826 19 Mar 07 peter 215     /// If \a ml is owner of underlying data, constructed
826 19 Mar 07 peter 216     /// MatrixLookup will also be set as owner of underlying data.
826 19 Mar 07 peter 217     ///
536 03 Mar 06 peter 218     /// @note If underlying matrix goes out of scope or is deleted, the
536 03 Mar 06 peter 219     /// MatrixLookup becomes invalid and the result of further use is
536 03 Mar 06 peter 220     /// undefined.
536 03 Mar 06 peter 221     ///
2223 19 Mar 10 peter 222     ///  \deprecated Provided for backgroundColor compatibility with
2223 19 Mar 10 peter 223     ///  the 0.6 API. Use MatrixLookup(const MatrixLookup&, const
2223 19 Mar 10 peter 224     ///  utility::Index&, const utility::Index&)
2223 19 Mar 10 peter 225     ///
2863 03 Oct 12 peter 226     MatrixLookup(const MatrixLookup& ml, const utility::Index&,
565 16 Mar 06 peter 227                  const bool row_vectors);
469 19 Dec 05 peter 228
455 16 Dec 05 markus 229     ///
537 05 Mar 06 peter 230     /// Constructor creating a MatrixLookup with @a rows rows, @a
537 05 Mar 06 peter 231     /// columns columns, and all values are set to @a value. Created
590 24 Aug 06 peter 232     /// MatrixLookup owns its underlying matrix.
537 05 Mar 06 peter 233     ///
537 05 Mar 06 peter 234     MatrixLookup(const size_t rows, const size_t columns, const double value=0);
537 05 Mar 06 peter 235
537 05 Mar 06 peter 236     ///
590 24 Aug 06 peter 237     /// @brief The istream constructor.
455 16 Dec 05 markus 238     ///
2223 19 Mar 10 peter 239     /// In construction the underlying utility::Matrix is created from
2223 19 Mar 10 peter 240     /// the stream using utility::Matrix(std::istream&). The
2223 19 Mar 10 peter 241     /// constructed MatrixLookup will be owner of the underlying
590 24 Aug 06 peter 242     /// matrix.
590 24 Aug 06 peter 243     ///
2223 19 Mar 10 peter 244     /// @see Matrix(istream&) for details.
590 24 Aug 06 peter 245     ///
590 24 Aug 06 peter 246     MatrixLookup(std::istream&, char sep='\0');
590 24 Aug 06 peter 247
590 24 Aug 06 peter 248     ///
2863 03 Oct 12 peter 249     /// @brief Destructor.
590 24 Aug 06 peter 250     ///
826 19 Mar 07 peter 251     /// If ownership is set true and there is no other owner of
826 19 Mar 07 peter 252     /// underlying data, underlying data is deleted.
826 19 Mar 07 peter 253     ///
537 05 Mar 06 peter 254     virtual ~MatrixLookup();
455 16 Dec 05 markus 255
656 22 Sep 06 peter 256     /**
1066 10 Feb 08 peter 257        Iterator iterates along a row. When end of row is reached it
1066 10 Feb 08 peter 258        jumps to beginning of next row.
1066 10 Feb 08 peter 259
1066 10 Feb 08 peter 260        \return const_iterator pointing to upper-left element.
1062 10 Feb 08 peter 261      */
1062 10 Feb 08 peter 262     const_iterator begin(void) const;
1063 10 Feb 08 peter 263
1063 10 Feb 08 peter 264     /**
1066 10 Feb 08 peter 265        Iterator iterates along a column.
1066 10 Feb 08 peter 266
1066 10 Feb 08 peter 267        \return iterator pointing to first element of column \a i.
1063 10 Feb 08 peter 268      */
1104 18 Feb 08 peter 269     const_column_iterator begin_column(size_t) const;
1062 10 Feb 08 peter 270
1062 10 Feb 08 peter 271     /**
1066 10 Feb 08 peter 272        Iterator iterates along a column.
1066 10 Feb 08 peter 273
1066 10 Feb 08 peter 274        \return const_iterator pointing to first element of column \a i.
1063 10 Feb 08 peter 275      */
1104 18 Feb 08 peter 276     const_row_iterator begin_row(size_t) const;
1063 10 Feb 08 peter 277
1063 10 Feb 08 peter 278     /**
1170 27 Feb 08 peter 279        \return number of columns
1170 27 Feb 08 peter 280     */
1170 27 Feb 08 peter 281     size_t columns(void) const;
1170 27 Feb 08 peter 282
1170 27 Feb 08 peter 283     /**
1066 10 Feb 08 peter 284        \return const_iterator pointing to end of matrix
1063 10 Feb 08 peter 285      */
1063 10 Feb 08 peter 286     const_iterator end(void) const;
1063 10 Feb 08 peter 287
1063 10 Feb 08 peter 288     /**
1066 10 Feb 08 peter 289        \return const_iterator pointing to end of column \a i
1063 10 Feb 08 peter 290      */
1104 18 Feb 08 peter 291     const_column_iterator end_column(size_t) const;
1063 10 Feb 08 peter 292
1063 10 Feb 08 peter 293     /**
1066 10 Feb 08 peter 294        \return const_iterator pointing to end of row \a i
1063 10 Feb 08 peter 295      */
1104 18 Feb 08 peter 296     const_row_iterator end_row(size_t) const;
1063 10 Feb 08 peter 297
1170 27 Feb 08 peter 298     /**
1170 27 Feb 08 peter 299        \return number of rows
1170 27 Feb 08 peter 300     */
1170 27 Feb 08 peter 301     size_t rows(void) const;
1170 27 Feb 08 peter 302
604 29 Aug 06 peter 303     ///
631 05 Sep 06 peter 304     /// @return false
631 05 Sep 06 peter 305     ///
631 05 Sep 06 peter 306     bool weighted(void) const;
631 05 Sep 06 peter 307
631 05 Sep 06 peter 308     ///
482 02 Jan 06 peter 309     /// Access operator
482 02 Jan 06 peter 310     ///
2863 03 Oct 12 peter 311     /// @return element
482 02 Jan 06 peter 312     ///
1788 09 Feb 09 peter 313     const_reference operator()(size_t row, size_t column) const;
455 16 Dec 05 markus 314
556 08 Mar 06 peter 315     ///
556 08 Mar 06 peter 316     /// @brief assigment operator
556 08 Mar 06 peter 317     ///
590 24 Aug 06 peter 318     /// Does only change MatrixLookup not the underlying matrix
826 19 Mar 07 peter 319     /// object. However if the MatrixLookup is owner (and the only owner)
826 19 Mar 07 peter 320     /// of its underlying
590 24 Aug 06 peter 321     /// matrix, that matrix will be deleted here.
590 24 Aug 06 peter 322     ///
556 08 Mar 06 peter 323     const MatrixLookup& operator=(const MatrixLookup&);
2863 03 Oct 12 peter 324
455 16 Dec 05 markus 325   private:
1035 05 Feb 08 peter 326     friend class MatrixLookupWeighted;
1035 05 Feb 08 peter 327
1170 27 Feb 08 peter 328     utility::Index column_index_;
4125 14 Jan 22 peter 329     typedef std::shared_ptr<const utility::MatrixBase> MatrixP;
1169 26 Feb 08 peter 330     MatrixP data_;
1170 27 Feb 08 peter 331     utility::Index row_index_;
1170 27 Feb 08 peter 332
1170 27 Feb 08 peter 333     // for assertions
1170 27 Feb 08 peter 334     bool validate(void) const;
2863 03 Oct 12 peter 335   };
2863 03 Oct 12 peter 336
1169 26 Feb 08 peter 337   ///
1170 27 Feb 08 peter 338   /// The output operator MatrixLookup
1169 26 Feb 08 peter 339   ///
1883 31 Mar 09 peter 340   /// \relates MatrixLookup
1883 31 Mar 09 peter 341   ///
1169 26 Feb 08 peter 342   std::ostream& operator<< (std::ostream& s, const MatrixLookup&);
1169 26 Feb 08 peter 343
680 11 Oct 06 jari 344 }}} // of namespace classifier, yat, and theplu
455 16 Dec 05 markus 345
455 16 Dec 05 markus 346 #endif

Generated on Sat Oct 14 02:22:18 2023 (UTC) by svndigest 0.11.2pre (dev build 1672)