# v_importsii

## PURPOSE

V_IMPORTSII calculates the SII importance function per Hz or per Bark Q=(F,M)

## SYNOPSIS

function q=v_importsii(f,m)

## DESCRIPTION

    V_IMPORTSII calculates the SII importance function per Hz or per Bark Q=(F,M)
     Inputs:
            f(n)   Frequencies to which to calculate importance in Hz
                   or Bark according to 'b' flag.
            m      Mode string with some of the following flags:
                    'b'  Frequencies given in Bark rather than Hz
                    'c'  Calculate cumulative importance for f<f(i)
                    'd'  Calculate importance of n-1 bands: band i is f(i) to f(i+1)
                    'h'  Calculate importance per Hz or per Bark (accoring to 'b' flag)
     Outputs:
            q(n) or q(n-1) gives the importance at each of the f(i) or else,
                   if the 'd' flag is specified, in the band from f(i) to f(i+1).

## CROSS-REFERENCE INFORMATION

This function calls:

- v_frq2bark V_FRQ2BARK Convert Hertz to BARK frequency scale BARK=(FRQ)

This function is called by:

## SOURCE CODE

    0001 function q=v_importsii(f,m)
    0002 %V_IMPORTSII calculates the SII importance function per Hz or per Bark Q=(F,M)
    0003 % Inputs:
    0004 %        f(n)   Frequencies to which to calculate importance in Hz
    0005 %               or Bark according to 'b' flag.
    0006 %        m      Mode string with some of the following flags:
    0007 %                'b'  Frequencies given in Bark rather than Hz
    0008 %                'c'  Calculate cumulative importance for f<f(i)
    0009 %                'd'  Calculate importance of n-1 bands: band i is f(i) to f(i+1)
    0010 %                'h'  Calculate importance per Hz or per Bark (accoring to 'b' flag)
    0011 % Outputs:
    0012 %        q(n) or q(n-1) gives the importance at each of the f(i) or else,
    0013 %               if the 'd' flag is specified, in the band from f(i) to f(i+1).
    0014
    0015 % The importance function is based on the piecewise linear function
    0016 % defined in Fig 3 of [2]. This is integrated to give the cumulative
    0017 % importance function. It is modified slightly from Fig 3 so that the
    0018 % constant portion extends from 4 to 18 Bark (critical bands 5 to 18).
    0019 % we then fit a linear portion at either end to force the correct integral
    0020 % and ensure continuity of the importance at 4 and 18. The importance
    0021 % function is zero outside the range [1.286 21.948] bark or [130.1 9361]
    0022 % Hz.
    0023 %
    0024 % References:
    0025 %  [1]  Methods for the calculation of the speech intelligibility index.
    0026 %       ANSI Standard S3.5-1997 (R2007), American National Standards Institute, 1997.
    0027 %  [2]  C. V. Pavlovic. Derivation of primary parameters and procedures for use in
    0028 %       speech intelligibility predictions. J. Acoust Soc Amer, 82: 413�422, 1987.
    0029
    0030 %       Copyright (C) Mike Brookes 2006
    0031 %      Version: $Id: v_importsii.m 10865 2018-09-21 17:22:45Z dmb $
    0032 %
    0033 %   VOICEBOX is a MATLAB toolbox for speech processing.
    0034 %   Home page: http://www.ee.ic.ac.uk/hp/staff/dmb/voicebox/voicebox.html
    0035 %
    0036 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    0037 %   This program is free software; you can redistribute it and/or modify
    0038 %   it under the terms of the GNU Lesser General Public License as published by
    0039 %   the Free Software Foundation; either version 3 of the License, or
    0040 %   (at your option) any later version.
    0041 %
    0042 %   This program is distributed in the hope that it will be useful,
    0043 %   but WITHOUT ANY WARRANTY; without even the implied warranty of
    0044 %   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    0045 %   GNU Lesser General Public License for more details.
    0046 %
    0047 %   You can obtain a copy of the GNU Lesser General Public License from
    0048 %   https://www.gnu.org/licenses/ .
    0049 %
    0050 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    0051
    0052 persistent mi ci ai bi xi0 xi1
    0053 if isempty(mi)
    0054     % cumulative importance function =  mi*b+c+ai*(b<4)*(b-4)^2-bi*(b>18)*(b-18)^2
    0055     % for x in (xi0,xi1)
    0056     ci4=0.0783;
    0057     ci18=0.8861;
    0058     mi=(ci18-ci4)/14;
    0059     ci=ci4-4*mi;
    0060     ai=mi^2/(4*(4*mi+ci));
    0061     bi=mi^2/(4*(1-18*mi-ci));
    0062     xi0=4-mi/(2*ai);
    0063     xi1=18+mi/(2*bi);
    0064 end
    0065 if nargin<2
    0066     m=' ';
    0067 end
    0068 if any(m=='b')
    0069     b=f;
    0070 else
    0071     [b,d]=v_frq2bark(f);
    0072 end
    0073 if any(m=='c') || any(m=='d')
    0074     q=mi*b+ci+ai*(b<4).*(b-4).^2-bi*(b>18).*(b-18).^2;
    0075     q(b<xi0)=0;
    0076     q(b>xi1)=1;
    0077     if any(m=='d')
    0078         q=q(2:end)-q(1:end-1);
    0079     end
    0080 else
    0081     q=mi+ai*(b<4).*(b-4)-bi*(b>18).*(b-18);
    0082     q(b<xi0)=0;
    0083     q(b>xi1)=0;
    0084     if ~any(m=='b')
    0085         q=q./d;
    0086     end
    0087 end
    0088 if ~nargout
    0089     if any(m=='d')
    0090         ix=(1:2*length(q))/2;
    0091         plot(f(1+floor(ix)),q(ceil(ix)));
    0092     else
    0093         plot(f,q);
    0094     end
    0095     if any(m=='b')
    0096         xlabel('Frequency (Bark)');
    0097     else
    0098         xlabel('Frequency (Hz)');
    0099     end
    0100     ylabel('Importance');
    0101     if any(m=='c')
    0102         title('SII Cumulative Importance');
    0103     elseif any(m=='d')
    0104         title('SII Band Importance');
    0105     else
    0106         title('SII Importance Function');
    0107     end
    0108 end
    0109