---

gnn_dataset.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_dataset.c
 *  @brief Data Sets Implementation.
 *
 *  @date   : 23-08-03 21:12, 22-09-03 02:28
 *  @author : Pedro Ortega C. <peortega@dcc.uchile.cl>
 *  Copyright  2003  Pedro Ortega C.
 ****************************************************************************/
/*
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Library General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */



/**
 * @defgroup gnn_dataset_doc gnn_dataset : Datasets for Training.
 * @ingroup libgnn_dataset
 *
 * The \ref gnn_dataset type defines a common interface for handling pattern
 * sets.
 *
 * In \ref libgnn, a pattern is defined as a triple
 * \f[ (x, t, p) \f]
 * where \f$x \in \mathbb{R}^n\f$ is the input pattern or feature vector,
 * \f$t \in \mathbb{R}^m\f$ is the output pattern or target vector and
 * \f$p \in \mathbb{R}\f$ is the pattern weight or pattern relevance.
 *
 * Datasets are sets of \f$P\f$ training patterns, which could be used for
 * training (as mentioned) or for model validation and testing. To identify
 * a particular pattern, they are indexed by \f$k=0,1, \ldots, P-1\f$ and
 * written as \f$x^k\f$, \f$t^k\f$ and \f$p_k\f$ (note that the vectors
 * are superindexed and the scalar value is subindexed). Schematically,
 * a dataset can be ilustrated by the following figure:
 *
 * <img src="images/gnn_dataset1.png">
 *
 * Patterns are commonly obtained from the observation of the real system
 * to be modelled, e.g. plants or other phenomenon, or sometimes they are
 * artificially constructed. In \ref libgnn, they can be sampled from
 * different sources, like its parts (input, output, weight).
 *
 * The \ref gnn_dataset and its functions provide a common interface, or
 * protocol, for different types of datasets. A dataset can be just a
 * sampler from three different sources (input, output and weight),
 * or a shuffler, or a preprocessor, etc. They just provide a logic
 * view of the underlying sample sources, and they have to manage them
 * without mixing them up.
 *
 * libgnn's design for handling datasets is very simple. A dataset, as an
 * "abstract object", has some properties and can do some things:
 *
 * - Its patterns have a fixed input and output size \f$n\f$ and \f$m\f$
 *   respectivelly.
 * - It contains a fixed, positive amount of patterns \f$(x^k, t^k, p_k)\f$.
 * - It can be reset. This should update its internal structure. What this
 *   means in practice depends on the particular dataset.
 * - It can retrieve a full pattern located at a specific position
 *   (given by its index).
 *
 * <b>What is the purpose of a dataset?</b>
 *
 * Datasets (as an abstraction) do exist because there are many ways to
 * get samples, and there are many possible sources. Per example, there
 * could be a dataset which samples its patterns form a disk, from RAM,
 * serial port, etc. Or even worse, the three sources itself could be
 * heterogeneous. Also, the <i>sampling method</i> could vary.
 *
 * <img src="images/gnn_dataset3.png">
 *
 * Datasets <b>can</b> (but aren't forced to) be made of \ref gnn_input s.
 * As a particular example, \ref gnn_simple_set is built upon three samplers
 * (one for inputs, targets and weights).
 *
 * <b>What does a trainer do in order to sample from a data set?</b>
 *
 * The order in which a trainer calls the functions on a \ref gnn_dataset is
 * the one ilustrated in the following flow diagram:
 *
 * <img src="images/gnn_dataset2.png">
 *
 * The important steps are marked with a bold border.
 *
 * <b>How to implement the gnn_dataset interface with a custom dataset?</b>
 *
 * It's simple. Create a new C datatype, wich should contain a \ref gnn_dataset
 * structure in it:
 *
 \code
 typedef struct _my_dataset my_dataset;

 struct _gnn_simple_set
 {
    gnn_dataset set;     // The underlying gnn_dataset
    
    // Other things your dataset needs...
    ...
 };
 
 \endcode
 *
 * Then, implement the 3 needed functions: reset, get and detroy, conforming
 * to the calling parameter specification:
 *
 \code
 int
 my_dataset_reset (gnn_dataset *set);

 int
 my_dataset_get (gnn_dataset *set,
                     size_t       k,
                     gsl_vector **x,
                     gsl_vector **t,
                     double      *p);

 void
 my_dataset_destroy (gnn_dataset *set);
 \endcode
 *
 * And finally, create a constructor which <b>must call</b> the
 * \ref gnn_dataset_init function:
 *
 \code
 gnn_dataset *
 my_dataset_new ()
 {
   my_datasete *myset; // a pointer to the dataset to be created
   gnn_dataset *set;   // a pointer to the same dataset, but viewed as a
                       // gnn_dataset

   // allocate memory for the dataset
   myset = (my_dataset *) malloc (sizeof (my_dataset));

   // initialize the dataset
   gnn_dataset_init (set, N_OF_PATTERNS, INPUT_SIZE, TARGET_SIZE,
                     my_dataset_reset, my_dataset_get, my_dataset_destroy);

   // do other initialization your dataset might need...
   ...
    
   return myset;
 }
 \endcode
 *
 * That's it!
 */



/******************************************/
/* Include Files                          */
/******************************************/

#include "gnn_dataset.h"
#include "gnn_utilities.h"



/******************************************/
/* Static Declaration                     */
/******************************************/

static int
gnn_dataset_default_reset (gnn_dataset *set);

static int
gnn_dataset_default_get (gnn_dataset *set,
                         size_t       i,
                         gsl_vector **x,
                         gsl_vector **t,
                         double      *p);

void
gnn_dataset_default_destroy (gnn_dataset *set);



/******************************************/
/* Static Implementation                  */
/******************************************/

/**
 * @brief Default "reset" function for a dataset.
 * @ingroup gnn_dataset_doc
 *
 * This function is the default "reset" function for a dataset. It does nothing.
 *
 * @param  set A pointer to a \ref gnn_dataset.
 * @return 0 if succeeded.
 */
static int
gnn_dataset_default_reset (gnn_dataset *set)
{
    assert (set != NULL);
    
    return 0;
}

/**
 * @brief Default "destroy" function for a dataset.
 * @ingroup gnn_dataset_doc
 *
 * This function is the default "destroy" function for a dataset. It assumes
 * that there isn't any additional data for the specific dataset type, so
 * it actually just returns.
 *
 * @param  set A pointer to a \ref gnn_dataset.
 */
void
gnn_dataset_default_destroy (gnn_dataset *set)
{
    return;
}



/******************************************/
/* Public Interface                       */
/******************************************/

/**
 * @brief Initializes a \ref gnn_dataset.
 * @ingroup gnn_dataset_doc
 *
 * This function initializes a given dataset, setting its properties and
 * installing its functions.
 *
 * If the reset or destroy functions aren't provided, then the default
 * functions \ref gnn_dataset_default_reset
 * and \ref gnn_dataset_default_destroy are installed respectively. The
 * "get" function is mandatory and can't be omitted.
 *
 * As an example, suppose that you have made your own extension to the
 * \ref gnn_dataset datatype, which you called "my_dataset_type". Also,
 * suppose you have already coded the appropiate "reset", "get" and "destroy"
 * functions for your special dataset. Then,
 * \code
   my_dataset_type *myset; // a pointer to the dataset to be created
   gnn_dataset     *set;   // a pointer to the same dataset, but viewed as a
                           //     gnn_dataset
   
   // allocate memory for the dataset
   myset = (my_dataset_type *) malloc (sizeof (my_dataset_type));
 
   // initialize the dataset
   gnn_dataset_init (set, 100, 5, 2,
                     my_dataset_reset, my_dataset_get, my_dataset_destroy);
 * \endcode
 * would initialize your dataset for 100 patterns, whose inputs and outputs
 * are of size 5 and 2 respectivelly.
 *
 * @param  set   A pointer to a \ref gnn_dataset.
 * @param  size  The number of patterns that it contains.
 * @param  n     The size of the inputs.
 * @param  m     The size of the outputs.
 * @param  reset   A pointer to the dataset's "reset" function.
 * @param  get     A pointer to the dataset's "get" function.
 * @param  destroy A pointer to the dataset's "destroy" function.
 * @return 0 if succeeded.
 */
int
gnn_dataset_init (gnn_dataset *set,
                  size_t       size,
                  size_t       n,
                  size_t       m,
                  gnn_dataset_reset_type   reset,
                  gnn_dataset_get_type     get,
                  gnn_dataset_destroy_type destroy)
{
    assert (set != NULL);
    assert (get != NULL);

    /* check sizes */
    if (n < 1 || m < 1 || size < 0)
    {
        GSL_ERROR ("datasets should have stricly positive number of"
                   "patterns, input and output sizes", GSL_EINVAL);
    }
    
    /* set fields */
    set->size    = size;
    set->n       = n;
    set->m       = m;
    set->reset   = gnn_dataset_default_reset;
    set->get     = get;
    set->destroy = gnn_dataset_default_destroy;

    /* install functions */
    if (reset != NULL)
        set->reset = reset;
    if (destroy != NULL)
        set->destroy = destroy;
        
    return 0;
}


/**
 * @brief Destroy a dataset.
 * @ingroup gnn_dataset_doc
 *
 * This function destroys the dataset.
 *
 * @param set A pointer to a \ref gnn_dataset.
 */
void
gnn_dataset_destroy (gnn_dataset *set)
{
    assert (set != NULL);
    
    set->destroy (set);
    free (set);
}

/**
 * @brief Reset a dataset.
 * @ingroup gnn_dataset_doc
 *
 * This function resets the dataset.
 *
 * @param  set   A pointer to a \ref gnn_dataset.
 * @return 0 if succeeded.
 */
int
gnn_dataset_reset (gnn_dataset *set)
{
    assert (set != NULL);
    
    set->reset (set);
}

/**
 * @brief Gets the i-th pattern.
 * @ingroup gnn_dataset_doc
 *
 * This function returns pointers to the pattern located atstores the dataset's i-th pattern into the buffers "x" and "t"
 * (which should be both gsl_vector of the correct size) and its corresponding
 * weight into the location pointed by "weight".
 *
 * Note that what "the i-th pattern" means depends on the underlying
 * implementation. Also, i should be within 0 and the dataset's size.
 *
 * @param  set    A pointer to a \ref gnn_dataset.
 * @param  i      The index of the pattern to be retrieved.
 * @param  x      A pointer to the gsl_vector where the input pattern should
 *                be placed in.
 * @param  t      A pointer to the gsl_vector where the output pattern should
 *                be placed in.
 * @param  weight A pointer to a double where the pattern's weight should be
 *                placed in.
 * @return 0 if succeeded.
 */
int
gnn_dataset_get (gnn_dataset *set,
                 size_t       k,
                 gsl_vector **x,
                 gsl_vector **t,
                 double      *weight)
{
    assert (set != NULL);
    
    set->get (set, k, x, t, weight);
}

/**
 * @brief Gets the size of the dataset.
 * @ingroup gnn_dataset_doc
 *
 * This function returns the dataset's size.
 *
 * @param  set A pointer to a \ref gnn_dataset.
 * @return Returns the size.
 */
size_t
gnn_dataset_get_size (gnn_dataset *set)
{
    assert (set != NULL);
    
    return set->size;
}

/**
 * @brief Gets the input size of the dataset.
 * @ingroup gnn_dataset_doc
 *
 * This function returns the size of the pattern's input vector size.
 *
 * @param  set A pointer to a \ref gnn_dataset.
 * @return Returns the size.
 */
size_t
gnn_dataset_input_get_size (gnn_dataset *set)
{
    assert (set != NULL);
    
    return set->n;
}

/**
 * @brief Gets the output size of the dataset.
 * @ingroup gnn_dataset_doc
 *
 * This function returns the size of the pattern's output vector size.
 *
 * @param  set A pointer to a \ref gnn_dataset.
 * @return Returns the size.
 */
size_t
gnn_dataset_output_get_size (gnn_dataset *set)
{
    assert (set != NULL);
    
    return set->m;
}

---