XMM-Newton Science Analysis System


ssclib (ssclib-4.36.1) [xmmsas_20230412_1735-21.0.0]

Allocate real to a bin

  function getBinNumber(xBinEdges, x) result(binNum) 
    real(single), intent(in) :: xBinEdges(:), x
    integer(int32)           :: binNum
  end function

In a commonly encountered situation, one has a set of bins defined by a vector of bin edges xBinEdges, plus a real number x, and it is desired to know into which bin x falls. The present function accomplishes this calculation and returns the index of the bin. The bin edges should occur in increasing order, with no two values the same, but they don't have to be equidistant. The returned value obeys in general the rule

$$xBinEdges(i) \le x < xBinEdges(i+1) \Rightarrow binNum = i$$

However note the following limiting or pathological cases:

• $x < xBinEdges(1) \Rightarrow binNum = 0$, ie 1 under the lower limit, is returned. It is up to the calling routine to catch these instances if it is necessary to prevent this return value from occurring.
• If $x = xBinEdges(size(xBinEdges))$ it is judged to fall within the last bin and $binNum = size(xBinEdges)-1$ is returned.
• $x > xBinEdges(size(xBinEdges)) \Rightarrow binNum = size(xBinEdges)$, ie 1 over the upper limit, is returned. It is up to the calling routine to catch these instances if it is necessary to prevent this return value from occurring.