# v_rangelim

## PURPOSE

V_RANGELIM limit the range of matrix elements: Y=(X,R,M)

## SYNOPSIS

function y=v_rangelim(x,r,m)

## DESCRIPTION

    V_RANGELIM  limit the range of matrix elements: Y=(X,R,M)

      Usage: (1) y=v_rangelim(x,[a b]);        % limit x to the range [a,b]
             (2) y=v_rangelim(x,[a b],'n');    % set values outside range to NaN
             (3) y=v_rangelim(x,r);            % limit x to the range max(x(:))+[-r,0]
             (4) y=v_rangelim(x,r,'r');        % limit x to the range max(x(:)).*[1/r,1]

      Inputs: x    Input data (scalar or matrix)
              r    desired range as [min max], max-min, max/min or 20*log10(max/min) (see options below)
              m    mode string containing any reasonable combination of:

                       'd' range r gives range in dB: 20*log10(max(y)/min(y))
                       'r' range r gives max(y)/min(y) ratio
                       'l' range r gives max(y)-min(y) difference [default]

                       'p' max(x) is top of range [default]
                       't' min(x) is bottom of range
                       'g' geometric mean is centre of range
                       'u' mean is centre of range
                       'm' median is centre of range

                       'c' clip out of range values to limit [default]
                       'n' set out of range values to NaN

     Outputs: y    Output data (same size as x)

          Copyright (C) Mike Brookes 2024
          Version: $Id:  $

       VOICEBOX is a MATLAB toolbox for speech processing.
       Home page: http://www.ee.ic.ac.uk/hp/staff/dmb/voicebox/voicebox.html

    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
       This program is free software; you can redistribute it and/or modify
       it under the terms of the GNU Lesser General Public License as published by
       the Free Software Foundation; either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU Lesser General Public License for more details.

       You can obtain a copy of the GNU Lesser General Public License from
       https://www.gnu.org/licenses/ .

    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

## CROSS-REFERENCE INFORMATION

This function calls:

This function is called by:

## SOURCE CODE

    0001 function y=v_rangelim(x,r,m)
    0002 %V_RANGELIM  limit the range of matrix elements: Y=(X,R,M)
    0003 %
    0004 %  Usage: (1) y=v_rangelim(x,[a b]);        % limit x to the range [a,b]
    0005 %         (2) y=v_rangelim(x,[a b],'n');    % set values outside range to NaN
    0006 %         (3) y=v_rangelim(x,r);            % limit x to the range max(x(:))+[-r,0]
    0007 %         (4) y=v_rangelim(x,r,'r');        % limit x to the range max(x(:)).*[1/r,1]
    0008 %
    0009 %  Inputs: x    Input data (scalar or matrix)
    0010 %          r    desired range as [min max], max-min, max/min or 20*log10(max/min) (see options below)
    0011 %          m    mode string containing any reasonable combination of:
    0012 %
    0013 %                   'd' range r gives range in dB: 20*log10(max(y)/min(y))
    0014 %                   'r' range r gives max(y)/min(y) ratio
    0015 %                   'l' range r gives max(y)-min(y) difference [default]
    0016 %
    0017 %                   'p' max(x) is top of range [default]
    0018 %                   't' min(x) is bottom of range
    0019 %                   'g' geometric mean is centre of range
    0020 %                   'u' mean is centre of range
    0021 %                   'm' median is centre of range
    0022 %
    0023 %                   'c' clip out of range values to limit [default]
    0024 %                   'n' set out of range values to NaN
    0025 %
    0026 % Outputs: y    Output data (same size as x)
    0027 %
    0028 %
    0029 %      Copyright (C) Mike Brookes 2024
    0030 %      Version: $Id:  $
    0031 %
    0032 %   VOICEBOX is a MATLAB toolbox for speech processing.
    0033 %   Home page: http://www.ee.ic.ac.uk/hp/staff/dmb/voicebox/voicebox.html
    0034 %
    0035 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    0036 %   This program is free software; you can redistribute it and/or modify
    0037 %   it under the terms of the GNU Lesser General Public License as published by
    0038 %   the Free Software Foundation; either version 3 of the License, or
    0039 %   (at your option) any later version.
    0040 %
    0041 %   This program is distributed in the hope that it will be useful,
    0042 %   but WITHOUT ANY WARRANTY; without even the implied warranty of
    0043 %   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    0044 %   GNU Lesser General Public License for more details.
    0045 %
    0046 %   You can obtain a copy of the GNU Lesser General Public License from
    0047 %   https://www.gnu.org/licenses/ .
    0048 %
    0049 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    0050 if nargin<3 || ~length(m)
    0051     m='lp';
    0052 end
    0053 nm=length(m);
    0054
    0055 id=find([any(repmat(m',1,4)==repmat('gumt',nm,1),1) 1].*(1:5),1);
    0056 if length(r)>1                          % r specifies explicit limits
    0057     p=r(1);
    0058     q=r(2);
    0059 else                                    % r specifies max/min or max-min
    0060     ir=find([any(repmat(m',1,2)==repmat('dr',nm,1),1) 1].*(1:3),1);
    0061 if ir==1                                % ratio in dB
    0062     r=10^(0.05*r);                      % convert to actual ratio
    0063 end
    0064 if ir==3                                % 'l' denotes a linear range specification
    0065     switch id                           % switch according to reference value
    0066         case 5                          % 'p': peak of x(:)
    0067             q=max(x(:));                % ... upper limit
    0068             p=q-r;                      % ... lower limit
    0069         case 4                          % 't': trough of x(:)
    0070             p=min(x(:));                % ... lower limit
    0071             q=p+r;                      % ... upper limit
    0072         case 3                          % 'm': median of x(:)
    0073             p=median(x(:))-0.5*r;       % ... lower limit
    0074             q=p+r;                      % ... upper limit
    0075         case 2                          % 'u': mean of x(:)
    0076             p=mean(x(:))-0.5*r;         % ... lower limit
    0077             q=p+r;                      % ... upper limit
    0078         case 1                          % 'g': geometric mean of x(:)
    0079             p=exp(mean(log(x(:))))-0.5*r; % ... lower limit
    0080             q=p+r;                      % ... upper limit
    0081     end
    0082 else                                    % 'r' or 'd' denotes a ratio range specification
    0083     switch id                           % switch according to reference value
    0084         case 5                          % 'p': peak of x(:)
    0085             q=max(x(:));                % ... upper limit
    0086             p=q/r;                      % ... lower limit
    0087         case 4                          % 't': trough of x(:)
    0088             p=min(x(:));                % ... lower limit
    0089             q=p*r;                      % ... upper limit
    0090         case 3                          % 'm': median of x(:)
    0091             p=median(x(:))/sqrt(r);     % ... lower limit
    0092             q=p*r;                      % ... upper limit
    0093         case 2                          % 'u': mean of x(:)
    0094             p=mean(x(:))/sqrt(r);       % ... lower limit
    0095             q=p*r;                      % ... upper limit
    0096         case 1                          % 'g': geometric mean of x(:)
    0097             p=exp(mean(log(x(:))))/sqrt(r); % ... lower limit
    0098             q=p*r;                      % ... upper limit
    0099     end
    0100 end
    0101 end
    0102 y=x;                                    % initialize y output
    0103 if any(m=='n')
    0104     y(x<p | x>q)=NaN;                   % set out-of-range elements to NaN
    0105 else
    0106     y(x<p)=p;                           % clip low out-of-range elements
    0107     y(x>q)=q;                           % clip high out-of-range elements
    0108 end