added function to wrap an Examples object around given raw matrix of samples features and labels

cbaselib/Example.cpp

@@ -191,5 +191,28 @@ void Examples::clean ()
 		Example & example = i->second;
 		example.clean();
 	}
-	clear();
+    clear();
+}
+
+bool Examples::wrapExamplesAroundFeatureMatrix(const Matrix &p_MatFeaturesColumWiseSamples, const Vector &p_VecLabels, Examples &p_Examples)
+{
+    size_t t_iNumSamples  = p_MatFeaturesColumWiseSamples.cols();
+    size_t t_iNumFeatures = p_MatFeaturesColumWiseSamples.rows();
+
+    if(p_VecLabels.size() != t_iNumSamples) // for every columnwise sample there need to be a label
+        return false;
+
+    p_Examples.reserve( t_iNumSamples );
+
+    const double *pDataPtr = p_MatFeaturesColumWiseSamples.getDataPointer();
+    for (size_t i = 0; i < t_iNumSamples; i++, pDataPtr+= t_iNumFeatures )
+    {
+        NICE::Vector *t_pVecTrainData = new NICE::Vector( pDataPtr , t_iNumFeatures);
+        OBJREC::Example t_Example;
+        t_Example.vec = t_pVecTrainData;
+
+        p_Examples.push_back( std::pair<int, OBJREC::Example>( (int)p_VecLabels[i], t_Example ) );
+    }
+
+    return true;
 }

cbaselib/Example.h

@@ -130,6 +130,27 @@ class Examples : public std::vector< std::pair<int, Example> >
     /** delete all data associated with all examples
         (sparse vector, vector, cached example, etc.) */
     void clean ();
+
+    /**
+     * @brief Create an Examples object from a given full matrix of features and a vector of sample labels.
+     *
+     * The Examples object consists of individual Example objects containing the label and a pointer to the provided raw feature data (stored in variable Example::vec).
+     * Note: No feature data is copied - an Example only contains a pointer to the raw double data.
+     * An NICE::Vector is created as an wrapper around this raw double pointer using it, but not copying it.
+     * You need to take care to delete these wrapper vectors once you're finished working with the Examples object, otherwise you generate a memory leak.
+     * Calling Examples::clean() handles this.
+     *
+     * Note: memory layout needs to be transposed into rows x column: features x samples
+     * features must lay next to each other in memory, so that each feature vector can
+     * be adressed by a starting pointer and the number of feature dimensions to come.
+     *
+     * @param p_MatFeaturesColumWiseSamples matrix containing the features (dimension M) of N samples ( M x N matrix )
+     * @param p_VecLabels matrix containing the labels for N samples (1xN)
+     * @param p_Examples created Examples object (vector of N Example object with each Example containing a valid vec-ptr to the feature data [uncopied] )
+     * @return true for successful Examples creation
+     * @author Johannes Ruehle
+     */
+    static bool wrapExamplesAroundFeatureMatrix(const NICE::Matrix &p_MatFeaturesColumWiseSamples, const NICE::Vector &p_VecLabels, Examples &p_Examples);
 };