---

gnn_simple_set.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_simple.c
 *  @brief Simple data set implementation.
 *
 *  @date   : 22/09/03 12:48
 *  @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_simple_set_doc gnn_simple_set : A simple implementation of datasets.
 * @ingroup gnn_dataset_doc
 * @brief Simple dataset implementation.
 *
 * The \ref gnn_simple_set dataset is a simple implementation of a dataset
 * structure. It is built given three input samplers
 * (\ref gnn_input structures): one for inputs, targets and weights.
 *
 * There are two ways for building a simple set:
 *
 * - It is given an input and an target pattern sampler of the same size.
 *   In this case, each weight is assumed to be 1.
 * - It is given an input, target and weight sampler of the same size.
 *
 * The simple set, in order to get the ith-pattern \f$(x^i, t^i, p^i)\f$,
 * retrieves the ith-sample from the input, target and weight source (if any)
 * calling the \ref gnn_input_get function on each of them.
 *
 *
 *
 *
 */



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

#include "gnn_utilities.h"
#include "gnn_simple_set.h"
#include "gnn_memory_input.h"


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

static int
gnn_simple_set_reset (gnn_dataset *set);

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

static void
gnn_simple_set_destroy (gnn_dataset *set);



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

/**
 * @brief The "reset" function for a simple set.
 * @ingroup gnn_simple_set_doc
 *
 * This function resets the \ref gnn_simple_set.
 *
 * @param  set A pointer to a \ref gnn_simple_set.
 * @return 0 if succeeded.
 */
static int
gnn_simple_set_reset (gnn_dataset *set)
{
    gnn_simple_set *sset;
    
    assert (set != NULL);
    
    sset = (gnn_simple_set *) set;
    
    /* reset samplers */
    gnn_input_reset (sset->inputs);
    gnn_input_reset (sset->outputs);
    if (sset->weights != NULL)
        gnn_input_reset (sset->weights);
        
    return 0;
}

/**
 * @brief The "get" function for a simple set.
 * @ingroup gnn_simple_set_doc
 *
 * This function is returns the k-th pattern in the simple set, where the
 * k-th input pattern, output pattern and pattern weight are sampled from
 * the internally installed device samplers.
 *
 * @param  set A pointer to a \ref gnn_simple_set.
 * @param  k   The index of the pattern to be retrieved.
 * @param  x   A reference for the input pattern.
 * @param  t   A reference for the output pattern.
 * @param  p   A pointer to a double for the pattern weight.
 * @return 0 if succeeded.
 */
static int
gnn_simple_set_get (gnn_dataset *set,
                    size_t       k,
                    gsl_vector **x,
                    gsl_vector **t,
                    double      *p)
{
    size_t P;
    gsl_vector *weight;
    gnn_simple_set *sset;
    
    assert (set != NULL);

    /* get size */
    P = gnn_dataset_get_size (set);

    /* get view as a simple set */
    sset = (gnn_simple_set *) set;

    /* check index */
    if (k < 0 || P <= k)
    {
        GSL_ERROR ("pattern index out of bounds", GSL_EINVAL);
    }
    
    /* get pattern views */
    *x = (gsl_vector *) gnn_input_get (sset->inputs, k);
    *t = (gsl_vector *) gnn_input_get (sset->outputs, k);
    if (sset->weights != NULL)
    {
        weight = (gsl_vector *) gnn_input_get (sset->weights, k);
        *p = gsl_vector_get (weight, 0);
    }
    else
        *p = 1.0;
    
    return 0;
}

/**
 * @brief Destroy function.
 * @ingroup gnn_simple_set_doc
 *
 * This is the \ref gnn_simple_set destroy function.
 * @param set A pointer to a \ref gnn_simple_set dataset.
 */
static void
gnn_simple_set_destroy (gnn_dataset *set)
{
    gnn_simple_set *sset;
    
    assert (set != NULL);

    /* get simple set view */
    sset = (gnn_simple_set *) set;

    /* destroy inputs, outputs and weights if any */
    if (sset->inputs  != NULL)
        gnn_input_destroy (sset->inputs);
    if (sset->outputs != NULL)
        gnn_input_destroy (sset->outputs);
    if (sset->weights != NULL)
        gnn_input_destroy (sset->weights);
}



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

/**
 * @brief Builds a new simple set.
 * @ingroup gnn_simple_set_doc
 *
 * This functions creates a new simple set from two or three input samplers.
 * The first two correspond to the input pattern and output pattern samplers,
 * wich should contain the same amount of patterns. The third is the pattern
 * weight sampler, which, if given, should also be of the same size. If omitted
 * (that means it is a \c NULL pointer),
 * then all weights are assumed to be 1.
 *
 * @param  inputs  The input sampler, a \ref gnn_input object.
 * @param  outputs The target sampler, a \ref gnn_input object.
 * @param  weights The weight sampler, a \ref gnn_input object.
 * @return Returns a pointer to a new \ref gnn_simple_set dataset.
 */
gnn_dataset *
gnn_simple_set_new (gnn_input *inputs, gnn_input *outputs, gnn_input *weights)
{
    size_t size;
    size_t n;
    size_t m;
    size_t P;
    int    status;
    gnn_dataset *set;
    gnn_simple_set *sset;

    assert (inputs != NULL);
    assert (outputs != NULL);

    /* get sizes */
    P = gnn_input_get_size (inputs);
    n = gnn_input_sample_get_size (inputs);
    m = gnn_input_sample_get_size (outputs);

    /* check sizes */
    if (P != gnn_input_get_size (outputs))
    {
        GSL_ERROR_VAL ("input and output samplers should have the same "
                       "number of patterns",
                       GSL_EINVAL, NULL);
    }
    if ( (weights != NULL) && (P != gnn_input_get_size (weights)) )
    {
        GSL_ERROR_VAL ("the input pattern, output pattern and pattern weight "
                       "samplers should have the same number of patterns",
                       GSL_EINVAL, NULL);
    }

    /* alloc memory for dataset */
    sset = (gnn_simple_set *) malloc (sizeof (gnn_simple_set));
    
    /* get memory dataset view */
    set = (gnn_dataset *) sset;

    /* initialize */
    status = gnn_dataset_init (set,
                               P,
                               n,
                               m,
                               gnn_simple_set_reset,
                               gnn_simple_set_get,
                               gnn_simple_set_destroy);
    if (status)
    {
        GSL_ERROR_VAL ("could not initialize gnn_simple_set",
                       GSL_EINVAL, NULL);
    }
    
    /* set fields */
    sset->inputs  = inputs;
    sset->outputs = outputs;
    sset->weights = weights;

    return set;
}



/**
 * @brief Builds a new simple set from text files.
 * @ingroup gnn_simple_set_doc
 *
 * This functions creates a new simple set from two or three text files
 * containing the patterns.
 *
 * The text files should be ASCII-formatted, and should contain matrices
 * where the number of columns corresponds to the size of the vectors, and
 * the row number to the number of patterns. Obviously, it is illegal to
 * provide matrices of different row sizes. Also, the weights file should
 * have <b>only one<b> column.
 *
 * If the weights file is omitted (i.e. it is a pointer to \c NULL), the
 * the weights are assumed to be 1.
 *
 * It is basically a shorthand for building the dataset from \ref gnn_input
 * structures which themselves should be built from text files.
 *
 * @param  inputs  The name of the file containing the input examples.
 * @param  outputs The name of the file containing the output examples
 *                 (targets).
 * @param  weights The name of the file containing the vector with the
 *                 weights for each pattern, or NULL if they should all be 1.
 * @return Returns a pointer to a new \ref gnn_simple_set dataset.
 */
gnn_dataset *
gnn_simple_set_from_files_new (const char *inputsFile,
                               const char *outputsFile,
                               const char *weightsFile)
{
    assert (inputsFile != NULL);
    assert (outputsFile != NULL);
    
    if (weightsFile != NULL)
    {
        return gnn_simple_set_new (
                    gnn_memory_input_new_from_file (inputsFile),
                    gnn_memory_input_new_from_file (outputsFile),
                    gnn_memory_input_new_from_file (weightsFile)
                );
    }
    else
    {
        return gnn_simple_set_new (
                    gnn_memory_input_new_from_file (inputsFile),
                    gnn_memory_input_new_from_file (outputsFile),
                    NULL
                );
    }
}



/**
 * @brief Returns a pointer to the inputs.
 * @ingroup gnn_simple_set_doc
 *
 * This function returns a pointer to the inputs, which are of the
 * \ref gnn_input type.
 * @param set A pointer to a \ref gnn_simple_set dataset.
 * @return Returns a pointer to the internal input device.
 */
gnn_input *
gnn_simple_set_get_inputs (gnn_dataset *set)
{
    gnn_simple_set *sset;

    assert (set != NULL);

    sset = (gnn_simple_set *) set;
    return sset->inputs;
}

/**
 * @brief Returns a pointer to the target vector input device.
 * @ingroup gnn_simple_set_doc
 *
 * This function returns a pointer to the outputs, which are of the
 * \ref gnn_input type.
 * @param set A pointer to a \ref gnn_simple_set dataset.
 * @return Returns a pointer to the internal target vector input device.
 */
gnn_input *
gnn_simple_set_get_outputs (gnn_dataset *set)
{
    gnn_simple_set *sset;

    assert (set != NULL);

    sset = (gnn_simple_set *) set;
    return sset->outputs;
}

/**
 * @brief Returns a pointer to the inputs.
 * @ingroup gnn_simple_set_doc
 *
 * This function returns a pointer to the weights input device,
 * which are of the \ref gnn_input type or NULL if not available.
 *
 * @param set A pointer to a \ref gnn_simple_set dataset.
 * @return Returns a pointer to the internal weight input device or NULL.
 */
gnn_input *
gnn_simple_set_get_weights (gnn_dataset *set)
{
    gnn_simple_set *sset;

    assert (set != NULL);

    sset = (gnn_simple_set *) set;
    return sset->weights;
}

---