BIN2D command

Syntax: | `BIN2D x y xbin ybin mcounts nx ny { xmin xmax ymin ymax } BIN2D\MATRIX mdata mxin myin mout`
Qualifiers: | `\WEIGHTS, \EMPTY, \MATRIX, \XDISCARD, \YDISCARD`
Defaults: | `\-WEIGHTS, \-EMPTY, \-MATRIX, \-XDISCARD, \-YDISCARD, xmin = min(x), xmax = max(x) ymin = min(y), ymax = max(y)`

The `BIN2D` command forms a matrix of bins of data by sorting the vectors `x` and `y` into grids of bins which are returned in vectors `xbin` and `ybin`. The accumulated matrix of total counts per bin is returned in matrix `mcounts`. If the numbers `xmin` and `xmax` are not entered, they default to the minimum and maximum of `x`. Similarly, if the numbers `ymin` and `ymax` are not entered, they default to the minimum and maximum of `y`.

`xbini = xmin+(i-1/2)(xmax-xmin)/nx` for `i=1,2,...,nx`

`ybinj = ymin+(j-1/2)(ymax-ymin)/ny` for `j=1,2,...,ny`

The point `(xk,yk)` will be accumulated in `mcountsi,j`, where

row: | `i = int((yk-ymin)/(ymax-ymin)*ny)+1`
column: | `j = int((xk-xmin)/(xmax-xmin)*nx)+1`

Dimensions

The lengths of `x` and `y` must be equal. If a weight vector, `w`, is supplied, it must also be the same length.

The vectors `xbin` and `ybin` and the matrix `mcounts` will be created. `xbin` will have `nx` elements, `ybin` will have `ny` elements, and matrix `mcounts` will have `nx` columns and `ny` rows.

Extremes

By default, events below `xmin` are placed in the first bin column, events above `xmax` are placed in the last bin column, events below `ymin` are placed in the first bin row, and events above `ymax` are placed in the last bin row. If the `\XDISCARD` qualifier is used, events below `xmin` are discarded, and events above `xmax` are discarded. If the `\YDISCARD` qualifier is used, events below `ymin` are discarded, and events above `ymax` are discarded.

Weights

Syntax: | `BIN2D\WEIGHTS w x y xbin ybin mcounts nx ny { xmin xmax ymin ymax }`

If a vector of weights is entered, you must indicate that it is there by using the `\WEIGHTS` qualifier. The weight `w` must be a vector. The `i`th event causes the bin count to be incremented by `wi`.

Increment only if empty

Syntax: | `BIN2D\EMPTY w x y xbin ybin mcounts nx ny { xmin xmax ymin ymax }`

If the `\EMPTY` qualifier is used, an event is counted in a bin only if that bin is empty. Only the first event encountered for each bin will be counted in that bin. `\EMPTY` cannot be used with `\MATRIX`.

Defined by box corners

Syntax: | `BIN2D\MATRIX mdata mx my mcounts`

The `BIN2D\MATRIX` command calculates the sum of the data points given by matrix `mdata` within a set of boxes. The x-coordinates of the boxes are given in matrix `mx`, the y-coordinates are given in matrix `my`. Matrices `mx` and `my` must be the same size. A data point is taken to be inside a box if it is interior or on an edge. Each data point is considered only once, so a data point is never taken to be in more than one of the boxes. The coordinates of the data points are the row and column indices, for example, `mdata[3,4]` is row 3 and column 4 so it is at `(x,y)` location `(4,3)`. The x and y-coordinates in `mx` and `my` should be in this index space of coordinates. The qualifiers `\EMPTY` and `\WEIGHTS` cannot be used with `\MATRIX`.