# v_interval

## PURPOSE

V_INTERVAL Classify X values into a set of contiguous intervals with boundaries from Y [I,F]=(X,Y,M)

## SYNOPSIS

function [i,f]=v_interval(x,y,m)

## DESCRIPTION

    V_INTERVAL Classify X values into a set of contiguous intervals with boundaries from Y [I,F]=(X,Y,M)

     Usage:    x=[1.6 2 3.8 0 6.5];    % test values (not necessarily monotonic)
               y=[1 2 3 5 6];          % define boundaries of four unequal intervals (y must be increasing)
           [i,f]=v_interval(x,y);      % classify into intervals using default options 'eE'
                                       %    i=[1 2 3 1 4] and f=[0.6 0 0.4 -1 1.5]

      Inputs:  x(nx)   Vector of test values
               y(ny)   Vector of monotonically increasing interval boundaries: interval i is [ y(i) , y(i+1) )
               m(nx)   string of mode options
                       if x(j)<y(1)
                           'e' extrapolate: set i(j)=1 and f(j)<0 [default]
                           'c' clip: set i(j)=1 and f(j)=0
                           'n' NaN: set i(j)=f(j)=NaN
                           'z' zero: set i(j)=0 and f(j)<0
                       if x(j)>=y(ny)
                           'E' set i(j)=ny-1 and f(j)>1 [default]
                           'C' set i(j)=ny-1 and f(j)=1
                           'N' set i(j)=f(j)=NaNj
                           'Z' set i(j)=ny and f(j)>1

     Outputs:  i(nx)   Input x(j) lies in the interval  [y(i(j)),y(i(j)+1)]
               f(nx)   f(j)=(x(j)-y(i(j)))/(y(i(j)+1))-y(i(j))) is the fractional position of x(j) within the interval.
                       Note that f(j) lies in the range [0,1) provided that y(1) <= x(j) < y(ny)

## CROSS-REFERENCE INFORMATION

This function calls:

- v_sort V_SORT Sort in ascending or descending order including an inverse index.

This function is called by:

## SOURCE CODE

    0001 function [i,f]=v_interval(x,y,m)
    0002 %V_INTERVAL Classify X values into a set of contiguous intervals with boundaries from Y [I,F]=(X,Y,M)
    0003 %
    0004 % Usage:    x=[1.6 2 3.8 0 6.5];    % test values (not necessarily monotonic)
    0005 %           y=[1 2 3 5 6];          % define boundaries of four unequal intervals (y must be increasing)
    0006 %       [i,f]=v_interval(x,y);      % classify into intervals using default options 'eE'
    0007 %                                   %    i=[1 2 3 1 4] and f=[0.6 0 0.4 -1 1.5]
    0008 %
    0009 %  Inputs:  x(nx)   Vector of test values
    0010 %           y(ny)   Vector of monotonically increasing interval boundaries: interval i is [ y(i) , y(i+1) )
    0011 %           m(nx)   string of mode options
    0012 %                   if x(j)<y(1)
    0013 %                       'e' extrapolate: set i(j)=1 and f(j)<0 [default]
    0014 %                       'c' clip: set i(j)=1 and f(j)=0
    0015 %                       'n' NaN: set i(j)=f(j)=NaN
    0016 %                       'z' zero: set i(j)=0 and f(j)<0
    0017 %                   if x(j)>=y(ny)
    0018 %                       'E' set i(j)=ny-1 and f(j)>1 [default]
    0019 %                       'C' set i(j)=ny-1 and f(j)=1
    0020 %                       'N' set i(j)=f(j)=NaNj
    0021 %                       'Z' set i(j)=ny and f(j)>1
    0022 %
    0023 % Outputs:  i(nx)   Input x(j) lies in the interval  [y(i(j)),y(i(j)+1)]
    0024 %           f(nx)   f(j)=(x(j)-y(i(j)))/(y(i(j)+1))-y(i(j))) is the fractional position of x(j) within the interval.
    0025 %                   Note that f(j) lies in the range [0,1) provided that y(1) <= x(j) < y(ny)
    0026 %
    0027 if nargin<3
    0028     m='';
    0029 end
    0030 [d,e,r]=v_sort([x(:)']);        % find order of x values
    0031 [d,e,j]=v_sort([y(:)' x(:)']);
    0032 ny=numel(y);
    0033 k=j(ny+1:end)-r;                % next lower element of y for each x (in range [0,ny])
    0034 i=max(min(k,ny-1),1);           % force to lie in range [1,ny-1]
    0035 f=(x-y(i))./(y(i+1)-y(i));      % fractional position within the interval
    0036 klo=k<1;
    0037 if any(klo)
    0038     if any(m=='c')
    0039         f(klo)=0;
    0040     elseif any(m=='n')
    0041         i(klo)=NaN;
    0042         f(klo)=NaN;
    0043     elseif any(m=='z')
    0044         i(klo)=0;
    0045     end
    0046 end
    0047 khi=k>=ny;
    0048 if any(khi)
    0049     if any(m=='C')
    0050         f(khi)=1;
    0051     elseif any(m=='N')
    0052         i(khi)=NaN;
    0053         f(khi)=NaN;
    0054     elseif any(m=='Z')
    0055         i(khi)=ny;
    0056     end
    0057 end
    0058 i=reshape(i,size(x));           % force shape to match x
    0059 f=reshape(f,size(x));           % force shape to match x