LCOV - code coverage report
Current view: top level - defines - keywords.hpp (source / functions) Hit Total Coverage
Test: clean.info Lines: 31 31 100.0 %
Date: 2013-05-24 Functions: 37 37 100.0 %
Branches: 63 126 50.0 %

           Branch data     Line data    Source code
       1                 :            : /* This software is distributed under BSD 3-clause license (see LICENSE file).
       2                 :            :  *
       3                 :            :  * Copyright (c) 2012-2013 Sergey Lisitsyn
       4                 :            :  */
       5                 :            : 
       6                 :            : #ifndef TAPKEE_DEFINES_KEYWORDS_H_
       7                 :            : #define TAPKEE_DEFINES_KEYWORDS_H_
       8                 :            : 
       9                 :            : /* Tapkee includes */
      10                 :            : #include <tapkee/defines/types.hpp>
      11                 :            : /* End of Tapkee includes */
      12                 :            : 
      13                 :            : namespace tapkee
      14                 :            : {
      15                 :            :         //! The namespace that contains keywords for all parameters
      16                 :            :         namespace keywords
      17                 :            :         {
      18                 :            :                 //! The namespace that contains implementations for the keywords
      19                 :            :                 namespace keywords_internal
      20                 :            :                 {
      21                 :            :                         /** DefaultValue instance is useful 
      22                 :            :                          * to set a parameter its default value.
      23                 :            :                          *
      24                 :            :                          * Once assigned to a keyword it produces a parameter
      25                 :            :                          * with the default value assigned to the keyword.
      26                 :            :                          */
      27                 :            :                         struct DefaultValue
      28                 :            :                         {
      29                 :          4 :                                 DefaultValue() { }
      30                 :            :                         };
      31                 :            : 
      32                 :            :                         /** ParameterKeyword instance is used to represent
      33                 :            :                          * a keyword that is assigned to some value. Such
      34                 :            :                          * an assignment results to instance of @ref Parameter
      35                 :            :                          * class which can be later checked and casted back 
      36                 :            :                          * to the value it represents.
      37                 :            :                          *
      38                 :            :                          * Usage is 
      39                 :            :                          * @code
      40                 :            :                          *      ParameterKeyword<int> keyword;
      41                 :            :                          *      Parameter p = (keyword = 5);
      42                 :            :                          *      int p_value = p;
      43                 :            :                          * @endcode
      44                 :            :                          */
      45                 :            :                         template <typename T> 
      46                 :         84 :                         struct ParameterKeyword
      47                 :            :                         {
      48                 :            :                                 typedef std::string Name;
      49                 :            : 
      50                 :         84 :                                 ParameterKeyword(const Name& n, const T& dv) : name(n), default_value(dv) { }
      51                 :            :                                 ParameterKeyword(const ParameterKeyword& pk);
      52                 :            :                                 ParameterKeyword operator=(const ParameterKeyword& pk); 
      53                 :            : 
      54                 :        123 :                                 Parameter operator=(const T& value) const
      55                 :            :                                 {
      56                 :        123 :                                         return Parameter::create(name,value);
      57                 :            :                                 }
      58                 :         80 :                                 Parameter operator=(const DefaultValue&) const
      59                 :            :                                 {
      60                 :         80 :                                         return Parameter::create(name,default_value);
      61                 :            :                                 }
      62                 :        823 :                                 operator Name() const
      63                 :            :                                 {
      64                 :        823 :                                         return name;
      65                 :            :                                 }
      66                 :            : 
      67                 :            :                                 Name name;
      68                 :            :                                 T default_value;
      69                 :            :                         };
      70                 :            :                 }
      71                 :            :                 using keywords_internal::ParameterKeyword;
      72                 :            :                 using keywords_internal::DefaultValue;
      73                 :            : 
      74                 :            :                 namespace {
      75                 :            :                         /** The keyword for the value that stands for the dimension reduction 
      76                 :            :                          * method to be used.
      77                 :            :                          *
      78                 :            :                          * Should always be set with a value (no default value is provided).
      79                 :            :                          *
      80                 :            :                          * The corresponding value should be of type @ref tapkee::DimensionReductionMethod. 
      81                 :            :                          */
      82                 :            :                         const ParameterKeyword<DimensionReductionMethod>
      83 [ +  - ][ +  - ]:          4 :                                 method("dimension reduction method", PassThru);
                 [ +  - ]
      84                 :            : 
      85                 :            :                         /** The keyword for the value that stands for the eigendecomposition
      86                 :            :                          * method to be used.
      87                 :            :                          * 
      88                 :            :                          * Used by the following eigendecomposition-based methods:
      89                 :            :                          *
      90                 :            :                          * - @ref tapkee::KernelLocallyLinearEmbedding
      91                 :            :                          * - @ref tapkee::NeighborhoodPreservingEmbedding
      92                 :            :                          * - @ref tapkee::KernelLocalTangentSpaceAlignment
      93                 :            :                          * - @ref tapkee::LinearLocalTangentSpaceAlignment
      94                 :            :                          * - @ref tapkee::HessianLocallyLinearEmbedding
      95                 :            :                          * - @ref tapkee::LaplacianEigenmaps
      96                 :            :                          * - @ref tapkee::LocalityPreservingProjections
      97                 :            :                          * - @ref tapkee::DiffusionMap
      98                 :            :                          * - @ref tapkee::Isomap
      99                 :            :                          * - @ref tapkee::LandmarkIsomap
     100                 :            :                          * - @ref tapkee::MultidimensionalScaling
     101                 :            :                          * - @ref tapkee::LandmarkMultidimensionalScaling
     102                 :            :                          * - @ref tapkee::KernelPCA
     103                 :            :                          * - @ref tapkee::PCA
     104                 :            :                          *
     105                 :            :                          * Default value is @ref tapkee::Arpack if available, @ref tapkee::Dense otherwise.
     106                 :            :                          *
     107                 :            :                          * The corresponding value should have type 
     108                 :            :                          * @ref tapkee::EigenMethod. 
     109                 :            :                          */
     110                 :            :                         const ParameterKeyword<EigenMethod>
     111 [ +  - ][ +  - ]:          4 :                                 eigen_method("eigendecomposition method", default_eigen_method);
                 [ +  - ]
     112                 :            : 
     113                 :            :                         /** The keyword for the value that stands for the neighbors
     114                 :            :                          * finding method to be used.
     115                 :            :                          * 
     116                 :            :                          * Used by the following local methods:
     117                 :            :                          * 
     118                 :            :                          * - @ref tapkee::KernelLocallyLinearEmbedding
     119                 :            :                          * - @ref tapkee::NeighborhoodPreservingEmbedding
     120                 :            :                          * - @ref tapkee::KernelLocalTangentSpaceAlignment
     121                 :            :                          * - @ref tapkee::LinearLocalTangentSpaceAlignment
     122                 :            :                          * - @ref tapkee::HessianLocallyLinearEmbedding
     123                 :            :                          * - @ref tapkee::LaplacianEigenmaps
     124                 :            :                          * - @ref tapkee::LocalityPreservingProjections
     125                 :            :                          * - @ref tapkee::Isomap
     126                 :            :                          * - @ref tapkee::LandmarkIsomap
     127                 :            :                          * - @ref tapkee::StochasticProximityEmbedding (with local strategy, i.e. 
     128                 :            :                          *        when @ref tapkee::keywords::spe_global_strategy is set to false)
     129                 :            :                          * - @ref tapkee::ManifoldSculpting
     130                 :            :                          *
     131                 :            :                          * Default value is @ref tapkee::CoverTree if available, @ref tapkee::Brute otherwise.
     132                 :            :                          *
     133                 :            :                          * The corresponding value should have type
     134                 :            :                          * @ref tapkee::NeighborsMethod.
     135                 :            :                          */
     136                 :            :                         const ParameterKeyword<NeighborsMethod> 
     137 [ +  - ][ +  - ]:          4 :                                 neighbors_method("nearest neighbors method", default_neighbors_method);
                 [ +  - ]
     138                 :            : 
     139                 :            :                         /** The keyword for the value that stores the number of neighbors.
     140                 :            :                          *
     141                 :            :                          * Used by all local methods such as:
     142                 :            :                          * 
     143                 :            :                          * - @ref tapkee::KernelLocallyLinearEmbedding
     144                 :            :                          * - @ref tapkee::NeighborhoodPreservingEmbedding
     145                 :            :                          * - @ref tapkee::KernelLocalTangentSpaceAlignment
     146                 :            :                          * - @ref tapkee::LinearLocalTangentSpaceAlignment
     147                 :            :                          * - @ref tapkee::HessianLocallyLinearEmbedding
     148                 :            :                          * - @ref tapkee::LaplacianEigenmaps
     149                 :            :                          * - @ref tapkee::LocalityPreservingProjections
     150                 :            :                          * - @ref tapkee::Isomap
     151                 :            :                          * - @ref tapkee::LandmarkIsomap
     152                 :            :                          * - @ref tapkee::StochasticProximityEmbedding (with local strategy, i.e. 
     153                 :            :                          *        when @ref tapkee::keywords::spe_global_strategy is set to false)
     154                 :            :                          * - @ref tapkee::ManifoldSculpting
     155                 :            :                          *
     156                 :            :                          * Default value is 5.
     157                 :            :                          *
     158                 :            :                          * The corresponding value should be of type @ref tapkee::IndexType, 
     159                 :            :                          * greater than 3 and less than the total number of vectors. 
     160                 :            :                          */
     161                 :            :                         const ParameterKeyword<IndexType>
     162 [ +  - ][ +  - ]:          4 :                                 num_neighbors("number of neighbors", 5);
                 [ +  - ]
     163                 :            : 
     164                 :            :                         /** The keyword for the value that stores the target dimension.
     165                 :            :                          *
     166                 :            :                          * It is used by all the implemented methods. 
     167                 :            :                          *
     168                 :            :                          * Default value is 2.
     169                 :            :                          * 
     170                 :            :                          * The corresponding value should have type 
     171                 :            :                          * @ref tapkee::IndexType and be greater than 
     172                 :            :                          * 1 and less than the minimum of the total number 
     173                 :            :                          * of vectors and the current dimension. 
     174                 :            :                          */
     175                 :            :                         const ParameterKeyword<IndexType> 
     176 [ +  - ][ +  - ]:          4 :                                 target_dimension("target dimension", 2);
                 [ +  - ]
     177                 :            : 
     178                 :            :                         /** The keyword for the value that stores the number of
     179                 :            :                          * timesteps in the diffusion map model.
     180                 :            :                          * 
     181                 :            :                          * Used by @ref tapkee::DiffusionMap.
     182                 :            :                          *
     183                 :            :                          * Default value is 3.
     184                 :            :                          * 
     185                 :            :                          * The corresponding value should have type @ref tapkee::IndexType.
     186                 :            :                          */
     187                 :            :                         const ParameterKeyword<IndexType>
     188 [ +  - ][ +  - ]:          4 :                                 diffusion_map_timesteps("diffusion map timesteps", 3);
                 [ +  - ]
     189                 :            : 
     190                 :            :                         /** The keyword for the value that stores the width of
     191                 :            :                          * the gaussian kernel.
     192                 :            :                          *
     193                 :            :                          * Used by the following methods:
     194                 :            :                          *
     195                 :            :                          * - @ref tapkee::LaplacianEigenmaps
     196                 :            :                          * - @ref tapkee::LocalityPreservingProjections
     197                 :            :                          * - @ref tapkee::DiffusionMap
     198                 :            :                          *
     199                 :            :                          * Default value is 1.0.
     200                 :            :                          *
     201                 :            :                          * The corresponding value should have type @ref tapkee::ScalarType.
     202                 :            :                          */
     203                 :            :                         const ParameterKeyword<ScalarType>
     204 [ +  - ][ +  - ]:          4 :                                 gaussian_kernel_width("the width of the gaussian kernel", 1.0);
                 [ +  - ]
     205                 :            : 
     206                 :            :                         /** The keyword for the value that stores the maximal 
     207                 :            :                          * iteration that could be reached.
     208                 :            :                          *
     209                 :            :                          * Used by the following iterative methods:
     210                 :            :                          * - @ref tapkee::StochasticProximityEmbedding
     211                 :            :                          * - @ref tapkee::FactorAnalysis
     212                 :            :                          * - @ref tapkee::ManifoldSculpting
     213                 :            :                          * 
     214                 :            :                          * Default value is 100.
     215                 :            :                          *
     216                 :            :                          * The corresponding value should have type @ref tapkee::IndexType.
     217                 :            :                          */
     218                 :            :                         const ParameterKeyword<IndexType>
     219 [ +  - ][ +  - ]:          4 :                                 max_iteration("maximal iteration", 100);
                 [ +  - ]
     220                 :            : 
     221                 :            :                         /** The keyword for the value that indicates
     222                 :            :                          * whether global strategy of SPE should be used.
     223                 :            :                          *
     224                 :            :                          * Used by @ref tapkee::StochasticProximityEmbedding.
     225                 :            :                          *
     226                 :            :                          * Default value is true.
     227                 :            :                          *
     228                 :            :                          * The corresponding value should have type bool.
     229                 :            :                          */
     230                 :            :                         const ParameterKeyword<bool>
     231 [ +  - ][ +  - ]:          4 :                                 spe_global_strategy("SPE global strategy", true);
                 [ +  - ]
     232                 :            : 
     233                 :            :                         /** The keyword for the value that stores the number of
     234                 :            :                          * updates to be done in SPE.
     235                 :            :                          *
     236                 :            :                          * Used by @ref tapkee::StochasticProximityEmbedding.
     237                 :            :                          *
     238                 :            :                          * Default value is 100.
     239                 :            :                          *
     240                 :            :                          * The corresponding value should have type @ref tapkee::IndexType.
     241                 :            :                          */
     242                 :            :                         const ParameterKeyword<IndexType>
     243 [ +  - ][ +  - ]:          4 :                                 spe_num_updates("SPE number of updates", 100);
                 [ +  - ]
     244                 :            : 
     245                 :            :                         /** The keyword for the value that stores the tolerance of
     246                 :            :                          * the SPE algorithm. 
     247                 :            :                          * 
     248                 :            :                          * Used by @ref tapkee::StochasticProximityEmbedding.
     249                 :            :                          *
     250                 :            :                          * Default value is 1e-9.
     251                 :            :                          *
     252                 :            :                          * The corresponding value should have type @ref tapkee::ScalarType.
     253                 :            :                          */
     254                 :            :                         const ParameterKeyword<ScalarType>
     255 [ +  - ][ +  - ]:          4 :                                 spe_tolerance("SPE tolerance", 1e-9);
                 [ +  - ]
     256                 :            : 
     257                 :            :                         /** The keyword for the value that stores the ratio
     258                 :            :                          * of landmark points to be used (1.0 means all
     259                 :            :                          * points are landmarks and the reciprocal of the
     260                 :            :                          * number of vectors means only one landmark).
     261                 :            :                          *
     262                 :            :                          * Used by the following landmark methods:
     263                 :            :                          *
     264                 :            :                          * - @ref tapkee::LandmarkIsomap
     265                 :            :                          * - @ref tapkee::LandmarkMultidimensionalScaling
     266                 :            :                          *
     267                 :            :                          * Default is 0.5.
     268                 :            :                          *  
     269                 :            :                          * The corresponding value should have type @ref tapkee::ScalarType
     270                 :            :                          * and be in [0,1] range.
     271                 :            :                          */
     272                 :            :                         const ParameterKeyword<ScalarType>
     273 [ +  - ][ +  - ]:          4 :                                 landmark_ratio("ratio of landmark points", 0.5);
                 [ +  - ]
     274                 :            : 
     275                 :            :                         /** The keyword for the value that stores 
     276                 :            :                          * the diagonal shift regularizer for
     277                 :            :                          * eigenproblems.
     278                 :            :                          *
     279                 :            :                          * Default is 1e-9.
     280                 :            :                          *
     281                 :            :                          * Used by the following methods:
     282                 :            :                          *
     283                 :            :                          * - @ref tapkee::KernelLocallyLinearEmbedding
     284                 :            :                          * - @ref tapkee::NeighborhoodPreservingEmbedding
     285                 :            :                          * - @ref tapkee::KernelLocalTangentSpaceAlignment
     286                 :            :                          * - @ref tapkee::LinearLocalTangentSpaceAlignment
     287                 :            :                          * - @ref tapkee::HessianLocallyLinearEmbedding
     288                 :            :                          * - @ref tapkee::LocalityPreservingProjections
     289                 :            :                          *
     290                 :            :                          * The corresponding value should have type @ref tapkee::ScalarType and
     291                 :            :                          * be quite close to zero.
     292                 :            :                          */
     293                 :            :                         const ParameterKeyword<ScalarType>
     294 [ +  - ][ +  - ]:          4 :                                 nullspace_shift("diagonal shift of nullspace", 1e-9);
                 [ +  - ]
     295                 :            : 
     296                 :            :                         /** The keyword for the value that stores
     297                 :            :                          * the regularization shift of the locally linear embedding
     298                 :            :                          * algorithm weights computation problem.
     299                 :            :                          *
     300                 :            :                          * Used by @ref tapkee::KernelLocallyLinearEmbedding.
     301                 :            :                          *
     302                 :            :                          * Default is 1e-3.
     303                 :            :                          *
     304                 :            :                          * The corresponding value should have type @ref tapkee::ScalarType and
     305                 :            :                          * be quite close to zero.
     306                 :            :                          */
     307                 :            :                         const ParameterKeyword<ScalarType>
     308 [ +  - ][ +  - ]:          4 :                                 klle_shift("KLLE regularizer", 1e-3);
                 [ +  - ]
     309                 :            : 
     310                 :            :                         /** The keyword for the value that indicates
     311                 :            :                          * whether graph connectivity check should be done.
     312                 :            :                          *
     313                 :            :                          * Used by the following local methods:
     314                 :            :                          * 
     315                 :            :                          * - @ref tapkee::KernelLocallyLinearEmbedding
     316                 :            :                          * - @ref tapkee::NeighborhoodPreservingEmbedding
     317                 :            :                          * - @ref tapkee::KernelLocalTangentSpaceAlignment
     318                 :            :                          * - @ref tapkee::LinearLocalTangentSpaceAlignment
     319                 :            :                          * - @ref tapkee::HessianLocallyLinearEmbedding
     320                 :            :                          * - @ref tapkee::LaplacianEigenmaps
     321                 :            :                          * - @ref tapkee::LocalityPreservingProjections
     322                 :            :                          * - @ref tapkee::Isomap
     323                 :            :                          * - @ref tapkee::LandmarkIsomap
     324                 :            :                          * - @ref tapkee::StochasticProximityEmbedding (with local strategy, i.e. 
     325                 :            :                          *        when @ref tapkee::keywords::spe_global_strategy is set to false)
     326                 :            :                          * - @ref tapkee::ManifoldSculpting
     327                 :            :                          *
     328                 :            :                          * Default is true. 
     329                 :            :                          *
     330                 :            :                          * The corresponding value should have type bool.
     331                 :            :                          */
     332                 :            :                         const ParameterKeyword<bool>
     333 [ +  - ][ +  - ]:          4 :                                 check_connectivity("check connectivity", true);
                 [ +  - ]
     334                 :            : 
     335                 :            :                         /** The keyword for the value that stores the epsilon
     336                 :            :                          * parameter of the Factor Analysis algorithm.
     337                 :            :                          * 
     338                 :            :                          * Used by @ref tapkee::FactorAnalysis.
     339                 :            :                          *
     340                 :            :                          * Default is 1e-9.
     341                 :            :                          *
     342                 :            :                          * The corresponding value should have type @ref tapkee::ScalarType.
     343                 :            :                          */
     344                 :            :                         const ParameterKeyword<ScalarType>
     345 [ +  - ][ +  - ]:          4 :                                 fa_epsilon("epsilon of FA", 1e-9);
                 [ +  - ]
     346                 :            : 
     347                 :            :                         /** The keyword for the value that stores a pointer
     348                 :            :                          * to the function which could be called to indicate progress
     349                 :            :                          * that has been made (it is called with an argument in range [0,1],
     350                 :            :                          * where 0 means 0% progress and 1 means 100% progress).
     351                 :            :                          *
     352                 :            :                          * Is not supported yet thus won't be used.
     353                 :            :                          *
     354                 :            :                          * The corresponding value should have type 
     355                 :            :                          * @code void (*)(double) @endcode 
     356                 :            :                          * (i.e. a pointer to some function that takes
     357                 :            :                          *  double argument and returns nothing).
     358                 :            :                          */
     359                 :            :                         const ParameterKeyword<void (*)(double)>  
     360 [ +  - ][ +  - ]:          4 :                                 progress_function("progress function", NULL);
                 [ +  - ]
     361                 :            : 
     362                 :            :                         /** The keyword for the value that stores a pointer 
     363                 :            :                          * to the function which could be called to check whether
     364                 :            :                          * computations were cancelled (the function should return 
     365                 :            :                          * true if computations were cancelled).
     366                 :            :                          *
     367                 :            :                          * Currently, it is called only once when 
     368                 :            :                          * method is starting to work.
     369                 :            :                          * 
     370                 :            :                          * If function returns true the library immediately 
     371                 :            :                          * throws @ref tapkee::cancelled_exception.
     372                 :            :                          *
     373                 :            :                          * The corresponding value should have type
     374                 :            :                          * @code bool (*)() @endcode 
     375                 :            :                          * (i.e. a pointer to some function that takes
     376                 :            :                          *  nothing and returns boolean).
     377                 :            :                          */
     378                 :            :                         const ParameterKeyword<bool (*)()>
     379 [ +  - ][ +  - ]:          4 :                                 cancel_function("cancel function", NULL);
                 [ +  - ]
     380                 :            : 
     381                 :            :                         /** The keyword for the value that stores perplelixity
     382                 :            :                          * parameter of t-SNE.
     383                 :            :                          *
     384                 :            :                          * Used by @ref tapkee::tDistributedStochasticNeighborEmbedding.
     385                 :            :                          *
     386                 :            :                          * Default value is 30.0;
     387                 :            :                          *
     388                 :            :                          * The corresponding value should have type @ref tapkee::ScalarType.
     389                 :            :                          */
     390 [ +  - ][ +  - ]:          4 :                         const ParameterKeyword<ScalarType> sne_perplexity("SNE perplexity", 30.0);
                 [ +  - ]
     391                 :            : 
     392                 :            :                         /** The keyword for the value that stores the theta 
     393                 :            :                          * parameter of the t-SNE algorithm.
     394                 :            :                          *
     395                 :            :                          * Used by @ref tapkee::tDistributedStochasticNeighborEmbedding.
     396                 :            :                          *
     397                 :            :                          * Default value is 0.5.
     398                 :            :                          * 
     399                 :            :                          * The corresponding value should have type @ref tapkee::ScalarType.
     400                 :            :                          */
     401 [ +  - ][ +  - ]:          4 :                         const ParameterKeyword<ScalarType> sne_theta("SNE theta", 0.5);
                 [ +  - ]
     402                 :            : 
     403                 :            :                         /** The keyword for the value that stores the squishingRate 
     404                 :            :                          * parameter of the Manifold Sculpting algorithm.
     405                 :            :                          *
     406                 :            :                          * Used by @ref tapkee::ManifoldSculpting.
     407                 :            :                          *
     408                 :            :                          * Default value is 0.99.
     409                 :            :                          * 
     410                 :            :                          * The corresponding value should have type @ref tapkee::ScalarType.
     411                 :            :                          */
     412 [ +  - ][ +  - ]:          4 :                         const ParameterKeyword<ScalarType> squishing_rate("squishing rate", 0.99);
                 [ +  - ]
     413                 :            : 
     414                 :            :                         /** The default value - assigning any keyword to this
     415                 :            :                          * static struct produces a parameter with its default value.
     416                 :            :                          */
     417                 :          4 :                         const DefaultValue by_default;
     418                 :            :                 }
     419                 :            :         }
     420                 :            : }
     421                 :            : 
     422                 :            : #endif

Generated by: LCOV version 1.9