---

gnn_random_order.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_random_order.c
 *  @brief Random order for datasets implementation.
 *
 *  @date   : 30-05-04 18:14
 *  @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_random_order_doc gnn_random_order : A random order sampler.
 * @ingroup gnn_dataset_doc
 * @brief Random order sampler for datasets implementation.
 *
 * The \ref gnn_random_order is a \ref gnn_dataset that acts as an intermediary
 * between an opaque dataset and a sampling client, like a \ref gnn_trainer.
 *
 * On every call on \ref gnn_dataset_reset, the \ref gnn_random_order sampler
 * generates a new permutation (a new sampling order) for the underlying
 * \ref gnn_dataset. That is, the \ref gnn_random_order's ith-pattern
 * \f$(x^i, t^i, p^i)\f$, corresponds to the pattern
 * \f$(x^{P(i)}, t^{P(i)}, p^{P(i)})\f$ of the underlying \ref gnn_dataset
 * structure, where \f$P(\cdot): \{0,\ldots,P\} \rightarrow \{0,\ldots,P\}\f$
 * is the random permutation.
 *
 * When building a \ref gnn_random_order upon a given \ref gnn_dataset, the
 * \ref gnn_random_order structure will <b>own</b> the source-dataset. That
 * means that if you destroy the \ref gnn_random_order structure, the
 * underlying \ref gnn_dataset will be destroyed too.
 */



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

#include "gnn_random_order.h"
#include "gnn_simple_set.h"


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

static int
gnn_random_order_reset (gnn_dataset *set);

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

static void
gnn_random_order_destroy (gnn_dataset *set);



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

/**
 * @brief The "reset" function for a gnn_random_order.
 * @ingroup gnn_random_order_doc
 *
 * This function resets the \ref gnn_random_order.
 *
 * @param  set A pointer to a \ref gnn_random_order.
 * @return 0 if succeeded.
 */
static int
gnn_random_order_reset (gnn_dataset *set)
{
    gnn_random_order *rset;

    assert (set != NULL);

    rset = (gnn_random_order *) set;

    /* reset samplers */
    gnn_dataset_reset (rset->data);
    gsl_ran_shuffle (gnn_get_rng (), rset->perm->data,
                           gnn_dataset_get_size (set), sizeof(size_t));

    return 0;
}

/**
 * @brief The "get" function for a simple set.
 * @ingroup gnn_random_order_doc
 *
 * This function is returns the k-th pattern in the random order sampler,
 * where the k-th pattern is drawn in a random order from the internal
 * \ref gnn_dataset.
 *
 * @param  set A pointer to a \ref gnn_random_order.
 * @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_random_order_get (gnn_dataset *set,
                      size_t       k,
                      gsl_vector **x,
                      gsl_vector **t,
                      double      *p)
{
    gnn_random_order *rset;

    assert (set != NULL);

    /* get view as a random order sampler */
    rset = (gnn_random_order *) set;
    
    return gnn_dataset_get (rset->data, k, x, t, p);
}

/**
 * @brief Destroy function.
 * @ingroup gnn_random_order_doc
 *
 * This is the \ref gnn_random_order destroy function.
 * @param set A pointer to a \ref gnn_random_order dataset.
 */
static void
gnn_random_order_destroy (gnn_dataset *set)
{
    gnn_random_order *rset;

    assert (set != NULL);

    /* get random order sampler view */
    rset = (gnn_random_order *) set;

    /* destroy internal dataset */
    if (rset->data != NULL)
        gnn_dataset_destroy (rset->data);
    if (rset->perm != NULL)
        gsl_permutation_free (rset->perm);
}



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

/**
 * @brief Builds a new random order sampler.
 * @ingroup gnn_random_order_doc
 *
 * This functions creates a new random order sampler from a given dataset.
 * It will create a new random sampling permutation (i.e. it will shuffle)
 * on each call on \ref gnn_dataset_reset, so that a sequential pattern
 * retrieval from pattern \f$i=0,\ldots,P\f$ will return them in a random
 * order.
 *
 * @param  data The \ref gnn_dataset which should serve as pattern source.
 * @return Returns a pointer to a new \ref gnn_random_order dataset.
 */
gnn_dataset *
gnn_random_order_new (gnn_dataset *data)
{
    size_t size;
    size_t n;
    size_t m;
    size_t P;
    int    status;
    gnn_dataset *set;
    gnn_random_order *rset;

    assert (data != NULL);

    /* get sizes */
    P = gnn_dataset_get_size (data);
    n = gnn_dataset_input_get_size (data);
    m = gnn_dataset_output_get_size (data);

    /* alloc memory for dataset */
    rset = (gnn_random_order *) malloc (sizeof (gnn_random_order));
    if (rset == NULL)
    {
        GSL_ERROR_VAL ("couldn't allocate memory for "
                       "gnn_random_order structure",
                       GSL_ENOMEM, NULL);
    }

    /* get memory dataset view */
    set = (gnn_dataset *) rset;

    /* initialize */
    status = gnn_dataset_init (set,
                               P,
                               n,
                               m,
                               gnn_random_order_reset,
                               gnn_random_order_get,
                               gnn_random_order_destroy);
    if (status)
    {
        GSL_ERROR_VAL ("could not initialize gnn_random_order",
                       GSL_EINVAL, NULL);
    }

    /* set fields */
    rset->data = data;
    rset->perm = gsl_permutation_calloc (P);
    if (rset->perm == NULL)
    {
        GSL_ERROR_VAL ("couldn't allocate memory for the gnn_random_order's "
                       "random permutation", GSL_ENOMEM, NULL);
    }
    gsl_permutation_init (rset->perm);
    gsl_ran_shuffle (gnn_get_rng (), rset->perm->data, P, sizeof(size_t));

    return set;
}



/**
 * @brief Builds a new random sampler from gnn_inputs.
 * @ingroup gnn_random_order_doc
 *
 * This functions creates a new random order sampler 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.
 *
 * @note Internally, a \ref gnn_random_order sampler created this way
 *       contains a \ref gnn_simple_set dataset.
 *
 * @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_random_order dataset.
 */
gnn_dataset *
gnn_random_order_from_inputs_new (gnn_input *inputs,
                                  gnn_input *outputs,
                                  gnn_input *weights)
{
    return gnn_random_order_new (gnn_simple_set_new (inputs, outputs, weights));
}



/**
 * @brief Builds a new random order sampler from text files.
 * @ingroup gnn_random_order_doc
 *
 * This functions creates a new random order sampler 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_random_order dataset.
 */
gnn_dataset *
gnn_random_order_from_file_new (const char *inputsFile,
                                const char *outputsFile,
                                const char *weightsFile)
{
    return gnn_random_order_new (
        gnn_simple_set_from_files_new (inputsFile, outputsFile, weightsFile));
}



/**
 * @brief Returns a pointer to the internal gnn_dataset.
 * @ingroup gnn_random_order_doc
 *
 * This function returns a pointer to the internal \ref gnn_dataset structure,
 * which is used as source.
 *
 * @param set A pointer to a \ref gnn_random_order dataset.
 * @return Returns a pointer to the internal dataset.
 */
gnn_dataset *
gnn_random_order_get_dataset (gnn_dataset *set)
{
    gnn_random_order *rset;

    assert (set != NULL);

    rset = (gnn_random_order *) set;
    return rset->data;
}

---