

   CCoonnssttrruucctt ffrreeqquueennccyy ttaabbllee ffrroomm rraaww ddaattaa

        binning(x, breaks, nbins)

   AArrgguummeennttss::

          x: a vector or a matrix with either one or two
             columns.  If `x' is a one-dimentional matrix, this
             is equivalent to a vector.

     breaks: either a vector or a matrix with two columns,
             assigning the division points of the axis, or the
             axes in the matrix case.  If `breaks' is not
             given, it is computed by dividing the range of `x'
             into `nbins' intervals for each of the axes.

      nbins: the number of intervals on the `x' axis (in the
             vector case), or a vector of two elements with the
             number of intervals on each axes of `x' (in the
             marix case).  If `nbins' is not given, a value is
             computed as `round(log(length(x),2)+1)' or using a
             similar expression in the matrix case.

   DDeessccrriippttiioonn::

        Given a vector or a matrix `x', this function con-
        structs a frequency table associated to appropriate
        intervals covering the range of x.

   DDeettaaiillss::

        This function is primarity intended for use in connec-
        tion with `sm.density', to estimate noparametrically a
        density function, when the number of data points is
        high.  To avoid lengthy computations and use of very
        large matrices, the data are tabulated with the use of
        `binning', and the outcome is passed to `sm.density  '
        which computes the estimated density curve, using meth-
        ods described in Chapter 1 of the reference below.

   VVaalluuee::

        in the vector case, this is a list containing the vec-
        tor `midpoints' of the interval midpoints and the fre-
        quecies `freq' associated to them; in the matrix case,
        the returned value is a list with the following ele-
        ments: a two-dimensional matrix `x' with the coordi-
        nates of the midpoints of the two-dimensional bins
        excluding those with 0 frequecies, its associated
        matrix `x.freq' of frequencies, the coodinateds of the
        `midpoints', the division points, and the observed fre-
        quencies `freq.table' in full tabular form.

   RReeffeerreenncceess::

        Bowman, A.W. and Azzalini, A. (1997). Applied Smoothing
        Techniques for Data Analysis: the Kernel Approach with
        S-Plus Illustrations.  Oxford University Press, Oxford.

   SSeeee AAllssoo::

        `sm.density', `cut',`table'

   EExxaammpplleess::

        # example of 1-d use
        x<-rnorm(1000)
        xb<-binning(x)
        sm.density(xb$x,h=hnorm(x),weights=xb$freq)
        # example of 2-d use
        x<-rnorm(1000)
        x<-cbind(x,x+rnorm(1000))
        xb<-binning(x)
        plot(x)
        sm.density(xb$x, h=hnorm(x), weights=xb$x.freq, display="slice", add=T)

