/*****************************************************************************
*                                                                            *
*   DOWNSAMPLE.SPL Copyright (C) 2012 DSP Development Corporation            *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:        Randy Race                                                *
*                                                                            *
*   Synopsis:      Decimates a series for post FIR downsampling              *
*                                                                            *
*   Revisions:      2 Oct 2012  RRR  Creation                                *
*                                                                            *
*****************************************************************************/


#if @HELP_DOWNSAMPLE

    DOWNSAMPLE

    Purpose: Deletes every Nth sample for FIR downsampling.

    Syntax:  DOWNSAMPLE(s, n, offset)

                   s - A series, the input data.

                   n - An integer, the rate factor. Deletes N-1 samples
                       between each sample, decreasing the sample rate
                       by a factor of N. Defaults to 1, no rate change.

              offset - Optional. An integer, the starting offset for the
                       decimation. Defaults to 0, start decimation
                       after the first sample.

    Returns: A series, the decimated result.

    Example:
             W1: 1..5
             W2: downsample(w1, 2)

             W2 == {1, 3, 5}

             rate(w1) == 1
             rate(w2) == 0.5

    Example:
             W3: 1..5
             W4: downsample(w1, 3)

             W4 == {1, 4}

             rate(w3) == 1
             rate(w4) == 1/3

    Example:
             W1: 1..5
             W2: downsample(w1, 3, 1)

             W2 == {2, 5}

             rate(w1) == 1
             rate(w2) == 1/3

    Remarks:
             DOWNSAMPLE decreases the sample rate of the input series by a
             factor of N by removing N-1 samples between each sample.

             A downsampled series can be decimated by filtering
             the result with a low pass filter with a cut off frequency
             of (Fs / 2) / N where Fs is the original sample rate. The
             band limited frequency content of the original series is
             preserved.

             See DECILP to perform bandlimited decimation. 

    See Also:
             Decilp
             Decimate
             Remove
             Resample
             Upsample
#endif


/* downsample by a factor using decimation */
downsample(s, n, offset)
{
        local y;

        if (argc < 3)
        {
                if (argc < 2)
                {
                        if (argc < 1) error("downsample - input series required");

                        n = 1;
                }

                offset = 0;
        }

        /* decimate */
        y = decimate(s, n, offset + 1);

        return(y);
}