documentation TODOs which I collected recently :)

shogun-toolbox · Apr 24, 2012 · ba984fc · ba984fc
1 parent b7f2f31
commit ba984fc
Show file tree

Hide file tree

Showing 7 changed files with 85 additions and 39 deletions.
diff --git a/src/shogun/base/Parameter.h b/src/shogun/base/Parameter.h
@@ -102,7 +102,8 @@ struct TParameter
 	 * default */
 	bool m_delete_data;
 
-	/** TODO */
+	/** @return true if data was not allocated by a class which registered
+	 * its parameter, but from scratch using allocate_data_from_scratch */
 	bool m_was_allocated_from_scratch;
 
 private:

diff --git a/src/shogun/evaluation/CrossValidation.h b/src/shogun/evaluation/CrossValidation.h
@@ -78,7 +78,10 @@ class CrossValidationResult
  * studies: Pitfalls in classifier performance measurement. Technical report,
  * HP Laboratories.] for details on this subject.
  *
- * TODO say something about locking and custom kernel
+ * Cross validation tries to lock underlying machines if that is possible to
+ * speed up computations. Can be turned off by the set_autolock()  method.
+ * Locking in general may speed up things (eg for kernel machines the kernel
+ * matrix is precomputed), however, it is not always supported.
  */
 class CCrossValidation: public CSGObject
 {

diff --git a/src/shogun/features/SimpleFeatures.cpp b/src/shogun/features/SimpleFeatures.cpp
@@ -550,7 +550,6 @@ template<class ST> void CSimpleFeatures<ST>::add_to_dense_vec(float64_t alpha, i
 
 template<class ST> int32_t CSimpleFeatures<ST>::get_nnz_features_for_vector(int32_t num)
 {
-	/* H.Strathmann: TODO fix according to Soerens mail */
 	return num_features;
 }
 

diff --git a/src/shogun/features/SparseFeatures.cpp b/src/shogun/features/SparseFeatures.cpp
@@ -1100,7 +1100,7 @@ template<class ST> CFeatures* CSparseFeatures<ST>::copy_subset(const SGVector<in
 		/* index to copy */
 		index_t index=indices.vector[i];
 
-		/* copy sparse vector TODO THINK ABOUT VECTOR INDEX (i or vec.index*/
+		/* copy sparse vector */
 		SGSparseVector<ST> current=get_sparse_feature_vector(index);
 		matrix_copy.sparse_matrix[i]=SGSparseVector<ST>(
 			current.num_feat_entries, current.vec_index);

diff --git a/src/shogun/kernel/CustomKernel.h b/src/shogun/kernel/CustomKernel.h
@@ -26,7 +26,8 @@ namespace shogun
  * is or can be internally converted into (or directly given in) upper triangle
  * representation. Also note that values are stored as 32bit floats.
  *
- * TODO say something about the row/col subsets
+ * The custom kernel supports subsets each on the rows and the columns.
+ *
  *
  */
 class CCustomKernel: public CKernel
@@ -299,47 +300,39 @@ class CCustomKernel: public CKernel
 			return true;
 		}
 
-		// TODO
-		/** adds a subset of indices on top of the current subsets (possibly
+		/** adds a row subset of indices on top of the current subsets (possibly
 		 * subset o subset. Calls subset_changed_post() afterwards
 		 *
 		 * @param subset subset of indices to add
 		 * */
 		virtual void add_row_subset(SGVector<index_t> subset);
 
-		// TODO
-		/** removes that last added subset from subset stack, if existing
+		/** removes that last added row subset from subset stack, if existing
 		 * Calls subset_changed_post() afterwards */
 		virtual void remove_row_subset();
 
-		// TODO
-		/** removes all subsets
+		/** removes all row subsets
 		 * Calls subset_changed_post() afterwards */
 		virtual void remove_all_row_subsets();
 
-		// TODO
 		/** method may be overwritten to update things that depend on subset */
 		virtual void row_subset_changed_post();
 
-		// TODO
-		/** adds a subset of indices on top of the current subsets (possibly
+		/** adds a col subset of indices on top of the current subsets (possibly
 		 * subset o subset. Calls subset_changed_post() afterwards
 		 *
 		 * @param subset subset of indices to add
 		 * */
 		virtual void add_col_subset(SGVector<index_t> subset);
 
-		// TODO
-		/** removes that last added subset from subset stack, if existing
+		/** removes that last added col subset from subset stack, if existing
 		 * Calls subset_changed_post() afterwards */
 		virtual void remove_col_subset();
 
-		// TODO
-		/** removes all subsets
+		/** removes all col subsets
 		 * Calls subset_changed_post() afterwards */
 		virtual void remove_all_col_subsets();
 
-		// TODO
 		/** method may be overwritten to update things that depend on subset */
 		virtual void col_subset_changed_post();
 
@@ -378,7 +371,10 @@ class CCustomKernel: public CKernel
 			return (get_num_vec_lhs()>0) && (get_num_vec_rhs()>0);
 		}
 
-		/** TODO */
+		/** prints the kernel matrix
+		 *
+		 * @param prefix prefix for every line
+		 */
 		void print_kernel_matrix(const char* prefix="") const;
 
 		/** returns kernel matrix as is

diff --git a/src/shogun/machine/KernelMachine.h b/src/shogun/machine/KernelMachine.h
@@ -42,7 +42,10 @@ class CKernel;
  * Using an a-priori choosen kernel, the \f$\alpha_i\f$ and bias are determined
  * in a training procedure.
  *
- * TODO say something about locking
+ * Kernel machines support locking. This means that given some data, the machine
+ * can be locked. When this is done, the kernel matrix is computed and stored in
+ * a custom kernel. Speeds up cross-validation. Only train_locked and
+ * apply_locked are available when locked.
  */
 class CKernelMachine : public CMachine
 {
@@ -228,21 +231,35 @@ class CKernelMachine : public CMachine
 		 */
 		static void* apply_helper(void* p);
 
-		/** train being locked
-		 * @param indices train with indices
+		/** Trains a locked machine on a set of indices. Error if machine is
+		 * not locked
+		 *
+		 * @indices index vector (of locked features) that is used for training
+		 * @return whether training was successful
 		 */
 		virtual bool train_locked(const SGVector<index_t>& indices);
-		/** apply being locked
-		 * @param indices apply with indices
+
+		/** Applies a locked machine on a set of indices. Error if machine is
+		 * not locked
+		 *
+		 * @indices index vector (of locked features) that is predicted
 		 */
 		virtual CLabels* apply_locked(const SGVector<index_t>& indices);
 
-		/** TODO */
+		/** Locks the machine on given labels and data. After this call, only
+		 * train_locked and apply_locked may be called.
+		 *
+		 * Computes kernel matrix to speed up train/apply calls
+		 *
+		 * @param labs labels used for locking
+		 * @param features features used for locking
+		 */
 		virtual void data_lock(CLabels* labs, CFeatures* features=NULL);
 
-		/** TODO */
+		/** Unlocks a locked machine and restores previous state */
 		virtual void data_unlock();
 
+		/** @return whether machine supports locking */
 		virtual bool supports_locking() const { return true; }
 
 	protected:
@@ -255,22 +272,28 @@ class CKernelMachine : public CMachine
 		virtual void store_model_features();
 
     private:
-        /** register parameters and do misc init */
-        void init();
+		/** register parameters and do misc init */
+		void init();
 
 	protected:
 		/** kernel */
 		CKernel* kernel;
-		/** TODO data lock custom kernel */
+
+		/** is filled with pre-computed custom kernel on data lock */
 		CCustomKernel* m_custom_kernel;
-		/** TODO */
+
+		/** old kernel is stored here on data lock */
 		CKernel* m_kernel_backup;
+
 		/** if batch computation is enabled */
 		bool use_batch_computation;
+
 		/** if linadd is enabled */
 		bool use_linadd;
+
 		/** if bias shall be used */
 		bool use_bias;
+
 		/**  bias term b */
 		float64_t m_bias;
 

diff --git a/src/shogun/machine/Machine.h b/src/shogun/machine/Machine.h
@@ -99,7 +99,11 @@ enum ESolverType
  * the functions apply(idx) (optionally apply() to predict on the
  * whole set of examples) and the load and save routines.
  *
- * TODO say something about locking
+ * Machines may support locking. This means that given some data, the machine
+ * can be locked on this data to speed up computations. E.g. a kernel machine
+ * may precompute its kernel. Only train_locked and apply_locked are available
+ * when locked. There are methods for checking whether a machine supports
+ * locking.
  *
  */
 class CMachine : public CSGObject
@@ -218,32 +222,52 @@ class CMachine : public CSGObject
 		 */
 		virtual void set_store_model_features(bool store_model);
 
-		/** TODO */
+		/** Trains a locked machine on a set of indices. Error if machine is
+		 * not locked
+		 *
+		 * NOT IMPLEMENTED
+		 *
+		 * @indices index vector (of locked features) that is used for training
+		 * @return whether training was successful
+		 */
 		virtual bool train_locked(const SGVector<index_t>& indices)
 		{
 			SG_ERROR("train_locked(SGVector<index_t>) is not yet implemented "
 					"for %s\n", get_name());
 			return false;
 		}
 
-		/** TODO doc */
+		/** Applies a locked machine on a set of indices. Error if machine is
+		 * not locked
+		 *
+		 * NOT IMPLEMENTED
+		 *
+		 * @indices index vector (of locked features) that is predicted
+		 */
 		virtual CLabels* apply_locked(const SGVector<index_t>& indices)
 		{
 			SG_ERROR("apply_locked(SGVector<index_t>) is not yet implemented "
 					"for %s\n", get_name());
 			return NULL;
 		}
 
-		/** TODO */
+		/** Locks the machine on given labels and data. After this call, only
+		 * train_locked and apply_locked may be called
+		 *
+		 * Only possible if supports_locking() returns true
+		 *
+		 * @param labs labels used for locking
+		 * @param features features used for locking
+		 */
 		virtual void data_lock(CLabels* labs, CFeatures* features);
 
-		/** TODO */
+		/** Unlocks a locked machine and restores previous state */
 		virtual void data_unlock();
 
-		/** TODO */
+		/** @return whether this machine supports locking */
 		virtual bool supports_locking() const { return false; }
 
-		/** TODO */
+		/** @return whether this machine is locked */
 		bool is_data_locked() const { return m_data_locked; }
 
 	protected:
@@ -294,7 +318,7 @@ class CMachine : public CSGObject
 		/** whether model features should be stored after training */
 		bool m_store_model_features;
 
-		/** TODO */
+		/** whether data is locked */
 		bool m_data_locked;
 };
 }