[SciPy-dev] DCT naming conventions ?

[David Cournapeau]

On Mon, Jan 19, 2009 at 4:46 AM, Tom Grydeland <tom.grydeland at gmail.com> wrote:
> On Sun, Jan 18, 2009 at 6:04 PM, william ratcliff
> <william.ratcliff at gmail.com> wrote:
>> I like your arguments idea,
>> dct(...,type=number)
>> idct(...,type=number).
>
> +1
>
>> maybe the type could default to 2 for dct and idct (with the implementation
>> of idct for type 2 being dct of type3).  This would make life easier for
>> users.
>
> +1
>
> Also, this naming makes it possible to give the 2D and
> higher-dimensionality DCTs names analogously to the FFT functions.
>

Ok, I implemented the above scheme for DCT I/II/III, the docstring is:

def dct(x, type=2, n=None, axis=-1, norm=None):
    """
    Return the Discrete Cosine Transform of arbitrary type sequence x.

    Parameters
    ----------
    x : array-like
        input array.
    type : {1, 2, 3}
        type of the DCT (see Notes).
    n : int, optional
        Length of the transform.
    axis : int, optional
        axis over which to compute the transform.
    norm : {None, 'ortho'}
        normalization mode (see Notes).

    Returns
    -------
    y : real ndarray

    Notes
    -----
    For a single dimension array x, dct(x, norm='ortho') is equal to matlab
    dct(x).

    There are theoretically 8 types of the DCT, only the first 3 types are
    implemented in scipy. 'The' DCT generally refers to DCT type 2, and 'the'
    Inverse DCT generally refers to DCT type 3.

    type I
    ~~~~~~
    There are several definitions of the DCT-I; we use the following (for
    norm=None):

    for 0 <= k < N,

                                           N-1
        y[k] = x[0] + (-1)**k x[N-1] + 2 * sum x[n]*cos(pi*k*n/(N-1))
                                           n=0

    type II
    ~~~~~~~
    There are several definitions of the DCT-II; we use the following (for
    norm=None):

                  N-1
        y[k] = 2* sum x[n]*cos(pi*k*(2n+1)/(2*N)), 0 <= k < N.
                  n=0

    If norm='ortho', y[k] is multiplied by a scaling factor f:

        f = sqrt(1/(4*N)) if k = 0
        f = sqrt(1/(2*N)) otherwise

    Which makes the corresponding matrix of coefficients orthonormal (OO' = Id).

    type III
    ~~~~~~~~
    There are several definitions, we use the following (norm=None):

                          N-1
        y[k] = x[0] + 2 * sum x[n]*cos(pi*(k+0.5)*n/N), 0 <= k < N.
                          n=0

    Or (norm='ortho'), for 0 <= k < N:

                                            N-1
        y[k] = x[0] / sqrt(N) + sqrt(1/N) * sum x[n]*cos(pi*(k+0.5)*n/N)
                                            n=0

    The (unnormalized) DCT-III is the inverse of the (unnormalized) DCT-II, up
    to a factor 2*N. The orthonormalized DCT-III is exactly the inverse of the
    orthonormalized DCT-II.

    References
    ----------

    http://en.wikipedia.org/wiki/Discrete_cosine_transform

    'A Fast Cosine Transform in One and Two Dimensions', by J. Makhoul, in IEEE
    Transactions on acoustics, speech and signal processing.