# Hexagonal binning

binstats(cmd0::String="", arg1=nothing; kwargs...)

Reads arbitrarily located (x,y[,z][,w]) points (2-4 columns) and for each node in the specified grid layout determines which points are within the given radius. These point are then used in the calculation of the specified statistic. The results may be presented as is or may be normalized by the circle area to perhaps give density estimates. Alternatively, select hexagonal tiling instead or a rectangular grid layout.

See full GMT (not the GMT.jl one) docs at gmtbinstats

## Parameters

• C | stats | statistic :: [Type => String | NamedTuple]

Choose the statistic that will be computed per node based on the points that are within radius distance of the node.

• I | inc | increment | spacing :: [Type => Str] $Arg = xinc[unit][+e|n][/yinc[unit][+e|n]]]$

x_inc [and optionally y_inc] is the grid spacing. Optionally, append an increment unit.

• E | empty :: [Type => Number]

Set the value assigned to empty nodes [NaN].

• G | save | outgrid | outfile :: [Type => Str]

Output grid file name. Note that this is optional and to be used only when saving the result directly on disk. Otherwise, just use the G = gmtbinstats(....) form.

• N | normalize :: [Type => Bool]

Normalize the resulting grid values by the area represented by the search_radius.

• S | search_radius :: [Type => Number]

Sets the search_radius that determines which data points are considered close to a node. Not compatible with tiling

• R | region | limits :: [Type => Str or list or GMTgrid|image] $Arg = (xmin,xmax,ymin,ymax)$

Specify the region of interest. Set to data minimum BoundinBox if not provided.

• T | tiling | bins :: [Type => String | NamedTuple]

Instead of circular, possibly overlapping areas, select non-overlapping tiling. Choose between rectangular hexagonal binning.

• V | verbose :: [Type => Bool or Str] $Arg = [level]$

Select verbosity level, which will send progress reports to stderr.

• W | weights :: [Type => Bool | String]

Input data have a 4th column containing observation point weights.

• a | aspatial :: [Type => Str] $Arg = [col=]name[…]$

Control how aspatial data are handled in GMT during input and output.

• bi | binary_in :: [Type => Str] $Arg = [ncols][type][w][+L|+B]$

Select native binary format for primary input (secondary inputs are always ASCII).

• di | nodata_in :: [Type => Str or Number] $Arg = nodata$

Examine all input columns and if any item equals nodata we interpret this value as a missing data item and substitute the value NaN.

• e | pattern | find :: [Type => Str] $Arg = [~]”pattern” | -e[~]/regexp/[i]$

Only accept ASCII data records that contains the specified pattern.

• f | geog | colinfo | coltypes | coltype :: [Type => Str] $Arg = [i|o]colinfo$

Specify the data types of input and/or output columns (time or geographical data).

• g | gap :: [Type => Str] $Arg = [a]x|y|d|X|Y|D|[col]z[+|-]gap[u]$

Examine the spacing between consecutive data points in order to impose breaks in the line.

• h | header :: [Type => Str] $Arg = [i|o][n][+c][+d][+rremark][+ttitle]$

Primary input file(s) has header record(s).

• i | incols | incol :: [Type => Str] $Arg = cols[+l][+sscale][+ooffset][,…]$

Select specific data columns for primary input, in arbitrary order.

• q | inrow | inrows :: [Type => Str] $Arg = [i|o][~]rows[+ccol][+a|f|s]$

Select specific data rows to be read (-qi [Default]) or written (-qo) [all].

• r | reg | registration :: [Type => Bool or []]

Force pixel node registration [Default is gridline registration].

• w | wrap | cyclic :: [Type => Str or Number] $Arg = [[-]n]$

Convert input records to a cyclical coordinate.

• yx :: [Type => Str or Bool or []] $Arg = [i|o]$

Swap 1st and 2nd column on input and/or output.

To see the full documentation type: $@? gmtbinstats$

## Binhex

To do hexagonal binning of a random data and counting the number of points inside each hexagon, try:

using GMT
xy = rand(100,2) .* [5 3];
D = binstats(xy, region=(0,5,0,3), inc=1, tiling=:hex, stats=:number);
imshow(D, hexbin=true, ml=0.5, colorbar=true)