---

gnn_gaussian_noise_input.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_gaussian_noise_input.c
 *  @brief gnn_gaussian_noise Implementation.
 *
 *  @date   : 05-10-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_gaussian_noise_input_doc gnn_gaussian_noise_input : Adds Gaussian Noise to Input Samples.
 * @ingroup gnn_input_doc
 * @brief Adds gaussian noise to input samples.
 *
 * The \ref gnn_gaussian_noise_input samples draws its input samples from
 * an associated \ref gnn_input input device, and adds gaussian noise with
 * mean zero and standard deviation of your choice.
 *
 * \f[ x_i = \overline{x}_i + n(t, \sigma) \f]
 *
 * where the \f$x\f$, is the pattern returned by this device,
 * \f$\overline{x}\f$ is the input sample drawn from the underlying input
 * device, and \f$n(t, \sigma)\f$ is the gaussian noise.
 *
 * A \ref gnn_gaussian_noise_input should be built giving it a pointer to
 * an already existing \ref gnn_input device. The \ref gnn_gaussian_noise_input
 * owns a random number generator that is uses to generate the noise.
 */



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

#include <time.h>
#include <gsl/gsl_rng.h>
#include <gsl/gsl_randist.h>
#include "gnn_gaussian_noise_input.h"



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

/**
 * @brief The datatype for gaussian_noise inputs.
 * @ingroup gnn_gaussian_noise_input_doc
 *
 * This is the datatype for gaussian_noise inputs. It extends the basic
 * \ref gnn_input structure to include the additional pointer
 * to the \ref gnn_input device, a buffer for storing the current pattern
 * that was built, etc.
 */
typedef struct _gnn_gaussian_noise_input gnn_gaussian_noise_input;

struct _gnn_gaussian_noise_input
{
    gnn_input   set;     /**< The underlying \ref gnn_input           */
    gnn_input  *subset;  /**< A pointer to the sub-input patterns.    */
    gsl_vector *buf;     /**< The buffer for evaluations.             */
    gsl_rng    *rng;     /**< Pointer to the random number generator. */
    double      sigma;   /**< The noise deviation \f$\sigma\f$.       */
};

static const gsl_vector *
gnn_gaussian_noise_input_get (gnn_input *set, size_t k);

static void
gnn_gaussian_noise_input_destroy (gnn_input *set);



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

/**
 * @brief The "get" function for a gaussian_noise input set.
 * @ingroup gnn_gaussian_noise_input_doc
 *
 * This function is returns the k-th pattern in the set.
 *
 * @param  set   A pointer to a \ref gnn_gaussian_noise_input.
 * @param  k      The index of the pattern to be retrieved.
 * @return A pointer to the sample vector.
 */
static const gsl_vector *
gnn_gaussian_noise_input_get (gnn_input *set, size_t k)
{
    size_t n;
    size_t P;
    size_t i;
    const gsl_vector *x;
    gnn_gaussian_noise_input *gset;

    assert (set != NULL);

    /* get gaussian_noise dataset view */
    gset = (gnn_gaussian_noise_input *) set;

    /* get sizes */
    n = gnn_input_sample_get_size (set);
    P = gnn_input_get_size (set);

    /* check index */
    if (k < 0 || P <= k)
    {
        GSL_ERROR_VAL ("pattern index out of bounds", GSL_EINVAL, NULL);
    }

    /* build the new pattern, summing gaussian noise to its values. */
    x = gnn_input_get (gset->subset, k);
    
    for (i=0; i<n; ++i)
    {
        double ni;
        double xi;
        double xni;
        
        xi = gsl_vector_get (x, i);
        ni = gsl_ran_gaussian (gset->rng, gset->sigma);
        xni = xi + ni;
        gsl_vector_set (gset->buf, i, xni);
    }

    return gset->buf;
}

/**
 * @brief Destroy function.
 * @ingroup gnn_gaussian_noise_input_doc
 *
 * This is the \ref gnn_gaussian_noise_input destroy function.
 * @param set A pointer to a \ref gnn_gaussian_noise_input dataset.
 */
static void
gnn_gaussian_noise_input_destroy (gnn_input *set)
{
    gnn_gaussian_noise_input *gset;

    assert (set != NULL);

    /* get gaussian_noise set view */
    gset = (gnn_gaussian_noise_input *) set;

    /* free buffer vector and the random number generator */
    if (gset->buf != NULL)
        gsl_vector_free (gset->buf);
    if (gset->rng != NULL)
        gsl_rng_free (gset->rng);
}



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

/**
 * @brief Builds a gaussian noise device.
 * @ingroup gnn_gaussian_noise_input_doc
 *
 * This function creates a new \ref gnn_gaussian_noise_input from a given
 * \ref gnn_input device \a input. The noises' deviation \f$\sigma\f$
 * is given by \a sigma.
 *
 * @param input The input device whose input samples should be contaminated
 *              with gaussian noise.
 * @param sigma The gaussian's standard deviation \f$\sigma\f$.
 * @return Returns a pointer to a new \ref gnn_gaussian_noise_input set.
 */
gnn_input *
gnn_gaussian_noise_new (gnn_input *input, double sigma)
{
    size_t P;
    size_t n;
    int    status;
    gnn_input *set;
    gnn_gaussian_noise_input *gset;

    assert (input != NULL);

    /* alloc gaussian_noise for input set */
    gset =
        (gnn_gaussian_noise_input *) malloc (sizeof (gnn_gaussian_noise_input));

    /* get view as a input set */
    set = (gnn_input *) gset;

    /* get sizes */
    P = gnn_input_get_size (input);
    n = gnn_input_sample_get_size (input);

    /* initialize */
    status = gnn_input_init (set,
                             P,
                             n,
                             NULL,
                             gnn_gaussian_noise_input_get,
                             gnn_gaussian_noise_input_destroy);
    if (status)
    {
        gnn_input_destroy (set);
        GSL_ERROR_VAL ("could not initialize gnn_gaussian_noise_input",
                       GSL_EFAILED, NULL);
    }

    /* set fields */
    gset->subset = input;
    gset->sigma  = sigma;
    gset->buf    = gsl_vector_alloc (n);
    
    if (gset->buf == NULL)
    {
        gnn_input_destroy (set);
        GSL_ERROR_VAL ("couldn't allocate memory for "
                       "gnn_gaussian_noise_input's buffer", GSL_ENOMEM, NULL);
    }

    /* create the own random number generator */
    gset->rng = gsl_rng_alloc (GNN_GAUSSIAN_NOISE_INPUT_RNG);
    if (gset->rng == NULL)
    {
        gnn_input_destroy (set);
        GSL_ERROR_VAL ("couldn't allocate the random number generator for "
                       "gnn_gaussian_noise_input", GSL_ENOMEM, NULL);
    }
    
    /* initialize the random number generator */
    gsl_rng_set (gset->rng, time (NULL));

    return set;
}

/**
 * @brief Sets a new \f$\sigma\f$ for the gaussian noise.
 * @ingroup gnn_gaussian_noise_input_doc
 *
 * @param input A pointer to the \ref gnn_gaussian_noise_input device.
 * @param sigma A positive real number.
 * @return Returns 0 if succeeded.
 */
int
gnn_gaussian_noise_set_sigma (gnn_input *input, double sigma)
{
    gnn_gaussian_noise_input *gset;

    assert (input != NULL);

    /* check for positive sigma */
    if (sigma < 0.0)
    {
        GSL_ERROR ("deviation sigma should be positive", GSL_EINVAL);
    }

    /* get view as a gaussian noise set */
    gset = (gnn_gaussian_noise_input *) input;
    
    /* set the new noise deviation's value */
    gset->sigma = sigma;

    return 0;
}

/**
 * @brief Returns the current \f$\sigma\f$.
 * @ingroup gnn_gaussian_noise_input_doc
 *
 * @param input A pointer to the \ref gnn_gaussian_noise_input device.
 * @return Returns the current value for \f$\sigma\f$.
 */
double
gnn_gaussian_noise_get_sigma (gnn_input *input)
{
    gnn_gaussian_noise_input *gset;

    assert (input != NULL);

    /* get view as a gaussian noise set */
    gset = (gnn_gaussian_noise_input *) input;
    
    return gset->sigma;
}

---