Prev Next histo

Histogram of Data Matrix
Syntax y = histo(xdata,xends) (no centers return)
Syntax y = histo(xdata,xends,xcenters) (centers return)
Include: include spt\histo.oms
See Also

ARGUMENTS:
   INPUTS:
      xdata    = MATRIX, any numerical type, coerced to DOUBLE for
                 internal processing. Represents data to be
                 histogrammed arranged in columns.
      xends    = VECTOR, COLUMN, any numerical type, coerced to DOUBLE
                 for internal processing. Represents the endpoints of
                 the partition for the histogram.
      xcenters = OPTIONAL, any numerical type, coerced to DOUBLE for
                 internal processing. Used to return center points
                 of the input partition.
   RETURN: MATRIX, DOUBLE, histogram of input data on a column-by-column basis.

Description

Return a histogram of input data matrix.

Data to be histogrammed is input through matrix 'xdata'. Each column of the input is considered as a vector of data values. Each column is histogrammed independently of all other columns.

The endpoints of the partioning that forms the basis for the histogram are passed in through column vector 'xends'. These endpoints are sorted in ascending order before processing. This same partion is applied to all columns of the data input matrix. The number of intervals tested is therefore equal to [coldim(xends)-1]. Intervals are interpretted as being contiguous, i.e., there is no open space between any two intervals. The endpoints need not be evenly spaced. If the same endpoint is cited twice in the 'xends' vector an interval of zero width results. Each interval is half-open on its upper end. This means that the upper endpoint of the highest interval is not included in that interval. At least two endpoints must be specified.

The optional argument 'xcenters' may be used to return a column vector of the computed center points of each of the histogram intervals. Its type may be of any kind but will be returned as a DOUBLE column vector of [coldim(xends)-1] elements. This vector may be used to plot the columns of the returned histogram.

The returned histogram is normalized such that the sum of each column is equal to unity.

Example

Do a histogram of normally distributed noise data. Make several columns of input data, average them, and plot the averaged histogram to verify the typical gaussian "bell curve".

include spt\spthead.oms

#--- Create AWGN distributed random data ---
mean   =  0d0;  # Zero-mean
sigma  =  1d0;  # STD = 1.0
Nsamp  = 2048;  # Samples of data per column
Ncol   =  128;  # Number of columns of data
ranseed;        # Randomize the noise generator
xdata  = awgn(mean,sigma,Nsamp,Ncol); # Make the noise

#--- Define x-axis partition ---
Nends  =    51; # Number of interval endpoints
xstart =  -4d0; # Starting amplitude
xinc   = .16d0; # Increment per interval
xends  = xstart + (seq(Nends)-1) * xinc; # Vector of endpoints

#--- Do the histogram ---
xcenters = novalue; # Declare return for center points
H        = histo(xdata,xends,xcenters); # Make the histogram
Havg     = rowsum(H);       # Add columns together for averaging
Havg     = Havg/max(Havg);  # Normalize to Peak = 1.0 for plotting

 Reference