---

gnn_dataset_view.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_dataset_view.c
 *  @brief Dataset view implementation.
 *
 *  @date   : 30-05-04 22:57
 *  @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_view_doc gnn_dataset_view : A view for datasets.
 * @ingroup gnn_dataset_doc
 * @brief View for datasets implementation.
 *
 * The \ref gnn_dataset_view is a \ref gnn_dataset that provides a transparent
 * view for a slice of a ref gnn_dataset, acting as it where a normal dataset.
 *
 * A \ref gnn_subset can be built upon an arbitrary \ref gnn_dataset. It
 * provides a view of a slice of the underlying dataset. For example,
 * a subrange of another dataset can be described with a view, or two
 * views can be made which provide access to the even and odd patterns
 * of a dataset.
 *
 * A view consist of a <i>starting index</i> \f$I\f$, a <i>stride</i> \f$S\f$
 * and a the <i>number of patterns</i> \f$P\f$. So, the <i>i</i>th-pattern
 * of the dataset view corresponds to the underlying dataset's pattern
 * with index
 *
 * \f[ i_{\textrm{real}} = I + S i_{\textrm{view}} \f]
 *
 * When building a \ref gnn_dataset_view upon a given \ref gnn_dataset, the
 * \ref gnn_dataset_view structure <b>won't own</b> the source-dataset. That
 * means that if you destroy the \ref gnn_dataset_view structure, the
 * underlying \ref gnn_dataset won't be destroyed. It should be destroyed
 * manually.
 */



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

#include "gnn_dataset_view.h"



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

static int
gnn_dataset_view_reset (gnn_dataset *set);

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

static void
gnn_dataset_view_destroy (gnn_dataset *set);



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

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

    assert (set != NULL);

    vset = (gnn_dataset_view *) set;

    /* reset samplers */
    gnn_dataset_reset (vset->data);

    return 0;
}

/**
 * @brief The "get" function for a gnn_dataset_view.
 * @ingroup gnn_dataset_view_doc
 *
 * This function is returns the k-th pattern in the dataset view.
 *
 * @param  set A pointer to a \ref gnn_dataset_view.
 * @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_dataset_view_get (gnn_dataset *set,
                      size_t       k,
                      gsl_vector **x,
                      gsl_vector **t,
                      double      *p)
{
    size_t kp;
    gnn_dataset_view *vset;

    assert (set != NULL);

    /* get view as a dataset view */
    vset = (gnn_dataset_view *) set;

    /* compute new index */
    kp = vset->start + vset->stride * k;

    return gnn_dataset_get (vset->data, kp, x, t, p);
}

/**
 * @brief Destroy function.
 * @ingroup gnn_dataset_view_doc
 *
 * This is the \ref gnn_dataset_view destroy function.
 * @param set A pointer to a \ref gnn_dataset_view dataset.
 */
static void
gnn_dataset_view_destroy (gnn_dataset *set)
{
    gnn_dataset_view *vset;

    assert (set != NULL);

    /* get view as a dataset view */
    vset = (gnn_dataset_view *) set;

    /* DO NOT DO ANYTHING :-) */
}



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

/**
 * @brief Builds a new dataset view.
 * @ingroup gnn_dataset_view_doc
 *
 * This functions creates a new view for a given dataset.
 *
 * @param  data   The \ref gnn_dataset which should serve as pattern source.
 * @param  start  The starting index.
 * @param  stride The stride for each element.
 * @param  size   The amount of patterns in the new dataset.
 * @return Returns a pointer to a new \ref gnn_dataset_view.
 */
gnn_dataset *
gnn_dataset_view_with_stride_new (gnn_dataset *data,
                                       size_t start, size_t stride, size_t size)
{
    size_t n;
    size_t m;
    size_t P;
    int    status;
    gnn_dataset *set;
    gnn_dataset_view *vset;

    assert (data != NULL);
    assert (start >= 0);
    assert (stride > 0);
    assert (size > 0);

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

    /* check maximum index */
    if (start + stride * (size - 1) >= P)
    {
        GSL_ERROR_VAL ("the gnn_dataset_view's size exceeds the source "
                       "dataset's size",
                       GSL_EINVAL, NULL);
    }

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

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

    /* initialize */
    status = gnn_dataset_init (set,
                               size,
                               n,
                               m,
                               gnn_dataset_view_reset,
                               gnn_dataset_view_get,
                               gnn_dataset_view_destroy);
    if (status)
    {
        GSL_ERROR_VAL ("could not initialize gnn_dataset_view",
                       GSL_EINVAL, NULL);
    }

    /* set fields */
    vset->data   = data;
    vset->start  = start;
    vset->stride = stride;
    vset->size   = size;

    return set;
}

/**
 * @brief Builds a new dataset view.
 * @ingroup gnn_dataset_view_doc
 *
 * This functions creates a new view for a given dataset. The stride is
 * assumed to be 1.
 *
 * @param  data   The \ref gnn_dataset which should serve as pattern source.
 * @param  start  The starting index.
 * @param  size   The amount of patterns in the new dataset.
 * @return Returns a pointer to a new \ref gnn_dataset_view.
 */
gnn_dataset *
gnn_dataset_view_new (gnn_dataset *data, size_t start, size_t size)
{
    return gnn_dataset_view_with_stride_new (data, start, 1, size);
}

/**
 * @brief Returns a pointer to the internal gnn_dataset.
 * @ingroup gnn_dataset_view_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_dataset_view dataset.
 * @return Returns a pointer to the internal dataset.
 */
gnn_dataset *
gnn_dataset_view_get_dataset (gnn_dataset *set)
{
    gnn_dataset_view *vset;

    assert (set != NULL);

    vset = (gnn_dataset_view *) set;
    return vset->data;
}

---