[R-gregmisc-users] SF.net SVN: r-gregmisc: [1289] trunk/SII
Brought to you by:
warnes
Menu
▾
▴
[R-gregmisc-users] SF.net SVN: r-gregmisc: [1289] trunk/SII
|
From: <wa...@us...> - 2008-06-12 05:56:50
|
Revision: 1289
http://r-gregmisc.svn.sourceforge.net/r-gregmisc/?rev=1289&view=rev
Author: warnes
Date: 2008-06-11 22:56:39 -0700 (Wed, 11 Jun 2008)
Log Message:
-----------
More documentation, and some code cleanup
Modified Paths:
--------------
trunk/SII/DESCRIPTION
trunk/SII/NAMESPACE
trunk/SII/R/summary.SII.R
trunk/SII/data/sic.octave.rda
trunk/SII/man/SII-package.Rd
trunk/SII/man/critical.Rd
trunk/SII/man/sii.Rd
Added Paths:
-----------
trunk/SII/man/sic.critical.Rd
Removed Paths:
-------------
trunk/SII/R/sii.constants.Rd
trunk/SII/man/plot.SII.Rd
trunk/SII/man/print.SII.Rd
trunk/SII/man/sii.excel.Rd
Modified: trunk/SII/DESCRIPTION
===================================================================
--- trunk/SII/DESCRIPTION 2008-06-12 00:29:28 UTC (rev 1288)
+++ trunk/SII/DESCRIPTION 2008-06-12 05:56:39 UTC (rev 1289)
@@ -1,12 +1,12 @@
Package: SII
Type: Package
-Title: Calcluate ANSI S3.5-1997 Speech Intelligibility Index
+Title: Calculate ANSI S3.5-1997 Speech Intelligibility Index
Version: 0.1.0
Date: 2008-06-07
Author: Gregory R. Warnes
Maintainer: Gregory R. Warnes <su...@ra...>
Description:
- This package calculates ANSI S3.5-199 Speech Intelligibility Index
+ This package calculates ANSI S3.5-1997 Speech Intelligibility Index
(SII), which is a standard method for computing the intelligibility
of speeck from acoustical measurments of speech and noise. This
package includes data frames corresponding to Tables 1 - 4 in the ANSI
@@ -15,6 +15,9 @@
compute the SII score.
--
The intial purpose of this package is to support use of SII as a
- standard measure of the impact age-related of hearing loss.
+ standard measure of severity of presbycusis (age-related of hearing
+ loss).
+Depends:
+Recommands: splines, gdata
License: GPLv2
LazyLoad: yes
Modified: trunk/SII/NAMESPACE
===================================================================
--- trunk/SII/NAMESPACE 2008-06-12 00:29:28 UTC (rev 1288)
+++ trunk/SII/NAMESPACE 2008-06-12 05:56:39 UTC (rev 1289)
@@ -1,7 +1,10 @@
export(
- sii
+ sii,
+ plot.SII,
+ print.SII,
+ summary.SII
)
-s3method(plot, SII)
-s3method(print, SII)
-s3method(summary, SII)
+S3method(plot, SII)
+S3method(print, SII)
+S3method(summary, SII)
Deleted: trunk/SII/R/sii.constants.Rd
===================================================================
--- trunk/SII/R/sii.constants.Rd 2008-06-12 00:29:28 UTC (rev 1288)
+++ trunk/SII/R/sii.constants.Rd 2008-06-12 05:56:39 UTC (rev 1289)
@@ -1,39 +0,0 @@
-\name{sii.constants}
-\alias{sii.constants}
-\docType{data}
-\title{ ~~ data name/kind ... ~~}
-\description{
- ~~ A concise (1-5 lines) description of the dataset. ~~
-}
-\usage{data(sii.constants)}
-\format{
- A data frame with 21 observations on the following 12 variables.
- \describe{
- \item{\code{.NFreqLin}}{a numeric vector}
- \item{\code{.NFreqLog}}{a numeric vector}
- \item{\code{I.BandImp}}{a numeric vector}
- \item{\code{Ti'.THDN}}{a numeric vector}
- \item{\code{Ei.Raised}}{a numeric vector}
- \item{\code{Xi.Ref.Int.Nz}}{a numeric vector}
- \item{\code{Xi'.Int.Noise}}{a numeric vector}
- \item{\code{Di.Equiv.Dist}}{a numeric vector}
- \item{\code{Li.Distortion}}{a numeric vector}
- \item{\code{ki.Temp.Var}}{a numeric vector}
- \item{\code{Ai.BandAud}}{a numeric vector}
- \item{\code{Si.SII.band.}}{a numeric vector}
- }
-}
-\details{
- ~~ If necessary, more details than the __description__ above ~~
-}
-\source{
- ~~ reference to a publication or URL from which the data were obtained ~~
-}
-\references{
- ~~ possibly secondary sources and usages ~~
-}
-\examples{
-data(sii.constants)
-## maybe str(sii.constants) ; plot(sii.constants) ...
-}
-\keyword{datasets}
Modified: trunk/SII/R/summary.SII.R
===================================================================
--- trunk/SII/R/summary.SII.R 2008-06-12 00:29:28 UTC (rev 1288)
+++ trunk/SII/R/summary.SII.R 2008-06-12 05:56:39 UTC (rev 1289)
@@ -1,5 +1,5 @@
`summary.SII` <-
-function (x, digits = 2, ...)
+function (object, digits = 2, ...)
{
cat("\n")
cat("Speech Intellibility Index\n")
@@ -7,9 +7,9 @@
cat("\n")
cat("Call:\n")
cat("\n")
- print(x$call)
+ print(object$call)
cat("\n")
- methodStr <- switch(x$method,
+ methodStr <- switch(object$method,
"interpolate"="Interpolation + Critical Band",
"critical"="Critical band SII procedure",
"equal-contributing"="Equally-contrlbutlng (17 band) critical-band SII procedure ",
@@ -21,10 +21,10 @@
cat("\n")
cat("Calculation table:\n")
cat("\n")
- print(round(x$table, digits=digits))
+ print(object$table, digits=digits)
cat("\n")
- cat("SII:", round(x$sii, digits), "\n")
+ cat("SII:", round(object$sii, digits), "\n")
cat("\n")
- invisible(x)
+ invisible(object)
}
Modified: trunk/SII/data/sic.octave.rda
===================================================================
(Binary files differ)
Modified: trunk/SII/man/SII-package.Rd
===================================================================
--- trunk/SII/man/SII-package.Rd 2008-06-12 00:29:28 UTC (rev 1288)
+++ trunk/SII/man/SII-package.Rd 2008-06-12 05:56:39 UTC (rev 1289)
@@ -3,41 +3,46 @@
\alias{SII}
\docType{package}
\title{
-What the package does (short line)
-~~ package title ~~
+ Calculate ANSI S3.5-1997 Speech Intelligibility Index
}
\description{
-More about what it does (maybe more than one line)
-~~ A concise (1-5 lines) description of the package ~~
+This package calculates ANSI S3.5-199 Speech Intelligibility Index
+(SII), which is a standard method for computing the intelligibility
+of speeck from acoustical measurments of speech and noise. This
+package includes data frames corresponding to Tables 1 - 4 in the ANSI
+standard as well as a function utlilizing these tables and
+user-provided hearing threshold and noise level measurments to
+compute the SII score.
+
+
+The intial purpose of this package is to support use of SII as a
+standard measure of the impact age-related of hearing loss.
}
\details{
-\tabular{ll}{
-Package: \tab SII\cr
-Type: \tab Package\cr
-Version: \tab 1.0\cr
-Date: \tab 2008-06-07\cr
-License: \tab What license is it under?\cr
-LazyLoad: \tab yes\cr
}
-~~ An overview of how to use the package, including the most important ~~
-~~ functions ~~
-}
\author{
-Who wrote it
-
-Maintainer: Who to complain to <you...@so...>
-~~ The author and/or maintainer of the package ~~
+ Gregory R. Warnes \email{su...@ra...}
}
\references{
-~~ Literature or other references for background information ~~
+ANSI S3.5-1997, "American National Standard Methods for
+Calculation of the Speech Intelligibility Index" American National Stan-
+dards Institute, New York.
+
+Other software programs for calculating SII are available from
+\url{http://www.sii.to/html/programs.html}.
}
-~~ Optionally other standard keywords, one per line, from file KEYWORDS in ~~
-~~ the R documentation directory ~~
\keyword{ package }
-\seealso{
-~~ Optional links to other man pages, e.g. ~~
-~~ \code{\link[<pkg>:<pkg>-package]{<pkg>}} ~~
-}
\examples{
-~~ simple examples of the most important functions ~~
+## Example C.1 from ANSI S3.5-1997 Annex C
+sii.C1 <- sii(
+ speech = c(50.0, 40.0, 40.0, 30.0, 20.0, 0.0),
+ noise = c(70.0, 65.0, 45.0, 25.0, 1.0,-15.0),
+ threshold= c( 0.0, 0.0, 0.0, 0.0, 0.0, 0.0),
+ method="octave"
+ )
+sii.C1 # rounded to 2 digits by default
+print(sii.C1$sii, digits=20) # full precision
+summary(sii.C1) # full details
+plot(sii.C1) # plot
+## The value given in the Standard is $0.504$.
}
Modified: trunk/SII/man/critical.Rd
===================================================================
--- trunk/SII/man/critical.Rd 2008-06-12 00:29:28 UTC (rev 1288)
+++ trunk/SII/man/critical.Rd 2008-06-12 05:56:39 UTC (rev 1289)
@@ -4,37 +4,77 @@
\alias{onethird}
\alias{octave}
\docType{data}
-\title{ ~~ data name/kind ... ~~}
+\title{Constants Tables for ANSI S3.5-1997 Speech Intelligibility Index
+ (SII)}
\description{
- ~~ A concise (1-5 lines) description of the dataset. ~~
+ Tables of constants for ANSI S3.5-1997 Speech Intelligibility Index
+ (SII)
}
-\usage{data(critical)}
+\usage{
+data(critical)
+data(equal)
+data(onethird)
+data(octave)
+data(overall.spl)
+}
+
\format{
- A data frame with 21 observations on the following 10 variables.
+ Each data frames has 6-21 observations and a subset of the following
+ variables:
\describe{
- \item{\code{fi}}{a numeric vector}
- \item{\code{li}}{a numeric vector}
- \item{\code{hi}}{a numeric vector}
- \item{\code{Ii}}{a numeric vector}
- \item{\code{normal}}{a numeric vector}
- \item{\code{raised}}{a numeric vector}
- \item{\code{loud}}{a numeric vector}
- \item{\code{shout}}{a numeric vector}
- \item{\code{Xi}}{a numeric vector}
- \item{\code{Fi}}{a numeric vector}
+ \item{\code{fi}}{Center frequency of SII band, Hz}
+ \item{\code{li}}{Lower limit of frequency band, Hz}
+ \item{\code{hi}}{Upper limit of frequency band, Hz}
+ \item{\code{Deltai}}{Band width adjustment, dB}
+ \item{\code{Ii}}{Band importance function}
+ \item{\code{normal}, \code{raised}, \code{loud} and
+ \code{shout}}{Standard spectrum levels for vocal effort levels
+ "normal", "raised", "loud", and "shout", respectively, dB}
+ \item{\code{Xi}}{Spectrum level of internal noise, dB}
+ \item{\code{Fi}}{Band importance function (weight)}
}
}
\details{
- ~~ If necessary, more details than the __description__ above ~~
+ These data objects provide constant tables 1 -- 4 from the ANSI
+ S3.5-1997.
+ \describe{
+ \item{\code{critical}}{Table 1: Critical band SII procedure
+ constants}
+ \item{\code{equal}}{Table 2:Equally contributing (17 band) critical
+ band SII}
+ \item{\code{onethird}}{Table 3: One-third octave band SII procedure
+ constants}
+ \item{\code{octave}}{Table 4: Octave band SII procedure constants}
+ \item{\code{overall.spl}}{Overall sound pressure level (SPL) for the
+ for vocal effort levels "normal", "raised", "loud", and "shout",
+ in dB}
+ }
}
\source{
- ~~ reference to a publication or URL from which the data were obtained ~~
+ANSI S3.5-1997, "American National Standard Methods for
+Calculation of the Speech Intelligibility Index" American National
+Standards Institute, New York.
}
\references{
- ~~ possibly secondary sources and usages ~~
+ANSI S3.5-1997, "American National Standard Methods for
+Calculation of the Speech Intelligibility Index" American National
+Standards Institute, New York.
}
\examples{
data(critical)
-## maybe str(critical) ; plot(critical) ...
+critical # show entire table
+
+data(equal)
+names(equal)
+equal$fi # extract just the frequency band centers
+
+data(onethird)
+barplot(onethird$Ii) # plot band importance function (weights)
+
+data(octave)
+round(octave, digits=2) # just 2 digits
+
+data(overall.spl)
+overall.spl
}
\keyword{datasets}
Deleted: trunk/SII/man/plot.SII.Rd
===================================================================
--- trunk/SII/man/plot.SII.Rd 2008-06-12 00:29:28 UTC (rev 1288)
+++ trunk/SII/man/plot.SII.Rd 2008-06-12 05:56:39 UTC (rev 1289)
@@ -1,63 +0,0 @@
-\name{plot.SII}
-\alias{plot.SII}
-%- Also NEED an '\alias' for EACH other topic documented here.
-\title{ ~~function to do ... ~~ }
-\description{
- ~~ A concise (1-5 lines) description of what the function does. ~~
-}
-\usage{
-plot.SII(x, matlab, title, ...)
-}
-%- maybe also 'usage' for other objects documented here.
-\arguments{
- \item{x}{ ~~Describe \code{x} here~~ }
- \item{matlab}{ ~~Describe \code{matlab} here~~ }
- \item{title}{ ~~Describe \code{title} here~~ }
- \item{\dots}{ ~~Describe \code{\dots} here~~ }
-}
-\details{
- ~~ If necessary, more details than the description above ~~
-}
-\value{
- ~Describe the value returned
- If it is a LIST, use
- \item{comp1 }{Description of 'comp1'}
- \item{comp2 }{Description of 'comp2'}
- ...
-}
-\references{ ~put references to the literature/web site here ~ }
-\author{ ~~who you are~~ }
-\note{ ~~further notes~~
-
- ~Make other sections like Warning with \section{Warning }{....} ~
-}
-\seealso{ ~~objects to See Also as \code{\link{help}}, ~~~ }
-\examples{
-##---- Should be DIRECTLY executable !! ----
-##-- ==> Define data, use random,
-##-- or do help(data=index) for the standard data sets.
-
-## The function is currently defined as
-function (x, matlab, title, ...)
-{
- plot(x = x$freq.orig, y = x$x.orig, col = "black", cex = 2,
- log = "x", xlab = "Frequency (Herz)", ylab = "Threshhold of Detection (dB)",
- ylim = c(1, 80), xlim = c(100, 8500))
- if (!missing(matlab))
- lines(sii.constants[, 1], matlab, type = "l", col = "red",
- lwd = 3)
- lines(x = sii.constants[, 1], y = x$table[, "T'i"], col = "blue",
- lwd = 2)
- abline(v = sii.constants[, 1], lty = 2)
- legend("topleft", legend = c("Measured data", "Matlab INTERP1(X, Y, XI, 'spline', 'extrap')",
- "R's approx(X,Y, XI, xout=XI,\n method='linear', rule=2)"),
- col = c("black", "red", "blue", "green", "orange", "magenta"),
- pch = c(1, NA, NA, NA, NA, NA), lty = c(NA, 1, 1, 1,
- 1, 1), lwd = c(NA, 3, 2, 2, 2, 2), bg = "white")
- title(title)
- }
-}
-% Add one or more standard keywords, see file 'KEYWORDS' in the
-% R documentation directory.
-\keyword{ ~kwd1 }
-\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line
Deleted: trunk/SII/man/print.SII.Rd
===================================================================
--- trunk/SII/man/print.SII.Rd 2008-06-12 00:29:28 UTC (rev 1288)
+++ trunk/SII/man/print.SII.Rd 2008-06-12 05:56:39 UTC (rev 1289)
@@ -1,48 +0,0 @@
-\name{print.SII}
-\alias{print.SII}
-%- Also NEED an '\alias' for EACH other topic documented here.
-\title{ ~~function to do ... ~~ }
-\description{
- ~~ A concise (1-5 lines) description of what the function does. ~~
-}
-\usage{
-print.SII(x, digits = 2, ...)
-}
-%- maybe also 'usage' for other objects documented here.
-\arguments{
- \item{x}{ ~~Describe \code{x} here~~ }
- \item{digits}{ ~~Describe \code{digits} here~~ }
- \item{\dots}{ ~~Describe \code{\dots} here~~ }
-}
-\details{
- ~~ If necessary, more details than the description above ~~
-}
-\value{
- ~Describe the value returned
- If it is a LIST, use
- \item{comp1 }{Description of 'comp1'}
- \item{comp2 }{Description of 'comp2'}
- ...
-}
-\references{ ~put references to the literature/web site here ~ }
-\author{ ~~who you are~~ }
-\note{ ~~further notes~~
-
- ~Make other sections like Warning with \section{Warning }{....} ~
-}
-\seealso{ ~~objects to See Also as \code{\link{help}}, ~~~ }
-\examples{
-##---- Should be DIRECTLY executable !! ----
-##-- ==> Define data, use random,
-##-- or do help(data=index) for the standard data sets.
-
-## The function is currently defined as
-function (x, digits = 2, ...)
-{
- print(unclass(round(x$sii, digits)))
- }
-}
-% Add one or more standard keywords, see file 'KEYWORDS' in the
-% R documentation directory.
-\keyword{ ~kwd1 }
-\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line
Added: trunk/SII/man/sic.critical.Rd
===================================================================
--- trunk/SII/man/sic.critical.Rd (rev 0)
+++ trunk/SII/man/sic.critical.Rd 2008-06-12 05:56:39 UTC (rev 1289)
@@ -0,0 +1,83 @@
+\name{sic.critical}
+\alias{sic.critical}
+\alias{sic.threeoctave}
+\alias{sic.octave}
+\docType{data}
+\title{Alternative ANSI S3.5-1997 SII Transfer Function Weights}
+\description{
+ Alternative ANSI S3.5-1997 Speech Intelligibility Index (SII) transfer
+ function weights for for various types of speech material.
+}
+\usage{
+data(sic.critical)
+data(sic.threeoctave)
+data(sic.octave)
+}
+\format{
+ Each data frame contains the following 8 variables, each
+ corresponding the the transfer function weights for a specific type of
+ speech material:
+ \describe{
+ \item{\code{fi}}{Center frequency, Hz}
+ \item{\code{NNS}}{NNS (various nonsense syllable tessz where
+ most of the English phonems occur equally often)}
+ \item{\code{CID22}}{CID-W22 (PB-words)}
+ \item{\code{NU6}}{NU6 monosyllables}
+ \item{\code{DRT}}{DRT (Diagnostic Rhyme Test)}
+ \item{\code{ShortPassage}}{short passages of easy reading material}
+ \item{\code{SPIN}}{SPIN monosyllables}
+ \item{\code{CST}}{Connected Speech Test}
+ }
+}
+\details{
+ \describe{
+ \item{\code{sic.critical}}{provides alternative weights for the
+ critical band SII procedure.}
+ \item{\code{sic.threeoctave}}{provides alternative weights for the
+ one-third octave frequency band SII procedure.}
+ \item{\code{octave}}{provides alternative weights for the
+ octave frequency band SII procedure.}
+ }
+}
+\section{note}{There is no table of alternative weights for the
+ equally-weighted SII band procedure as the weights for this method are
+ (by definition) constant across all bands.
+ }
+\source{
+ All values except the \code{CST} columns are from:
+
+ ANSI S3.5-1997, "American National Standard Methods for
+ Calculation of the Speech Intelligibility Index" American National
+ Standards Institute, New York.
+
+ Values in the \code{CST} columns are from:
+ \url{http://www.sii.to/CSTdata.txt}
+}
+\references{
+ ANSI S3.5-1997, "American National Standard Methods for
+ Calculation of the Speech Intelligibility Index" American National
+ Standards Institute, New York.
+}
+\examples{
+## Load the alternative weights for the critical band method
+data(sic.critical)
+
+## display the weights
+round(sic.critical,3)
+
+## draw a comparison plot
+matplot(x=sic.critical[,1], y=sic.critical[,-1], type="o",
+ xlab="Frequency, Hz", ylab="Weight",
+ log="x")
+legend(
+ "topright",
+ legend=names(sic.critical)[-1],
+ pch=1:ncol(sic.critical),
+ lty=1:ncol(sic.critical),
+ col=1:ncol(sic.critical)
+ )
+
+data(threeoctave)
+data(octave)
+}
+\keyword{datasets}
Modified: trunk/SII/man/sii.Rd
===================================================================
--- trunk/SII/man/sii.Rd 2008-06-12 00:29:28 UTC (rev 1288)
+++ trunk/SII/man/sii.Rd 2008-06-12 05:56:39 UTC (rev 1289)
@@ -1,172 +1,207 @@
\name{sii}
\alias{sii}
-%- Also NEED an '\alias' for EACH other topic documented here.
-\title{ ~~function to do ... ~~ }
+\alias{print.SII}
+\alias{plot.SII}
+\alias{summary.SII}
+\title{Compute ANSI S3.5-1997 Speech Intelligibility Index (SII)}
\description{
- ~~ A concise (1-5 lines) description of what the function does. ~~
+ Compute the Speech Intelligibility Index (SII) described by ANSI
+ specification S3.5-1997, including extensions for conductive
+ hearing loss.
}
\usage{
-sii(x, freq, noise, method = c("interpolate", "critical", "one-third octave", "equal-contributing", "octave"), voice = c("raised", "normal", "loud", "shout"))
+sii(speech = c("normal", "raised", "loud", "shout"),
+ noise, threshold, loss, freq,
+ method = c("interpolate", "critical", "equal-contributing",
+ "one-third octave", "octave"),
+ importance = c("SII", "NNS", "CID22", "NU6", "DRT",
+ "ShortPassage", "SPIN", "CST"))
+\method{print}{SII}(x, digits=2, ...)
+\method{plot}{SII}(x, ...)
+\method{summary}{SII}(object, digits=2, ...)
}
-%- maybe also 'usage' for other objects documented here.
\arguments{
- \item{x}{ ~~Describe \code{x} here~~ }
- \item{freq}{ ~~Describe \code{freq} here~~ }
- \item{noise}{ ~~Describe \code{noise} here~~ }
- \item{method}{ ~~Describe \code{method} here~~ }
- \item{voice}{ ~~Describe \code{voice} here~~ }
+ \item{speech}{Either a numeric vector providing $E'_i$, the equivalent
+ speech spectrum level (in dB) at each frequency, or a character
+ string indicating the stated vocal effort corresponding to one of
+ the standard standard speech spectrum levels ("normal", "raised",
+ "loud", "shout"). Defaults to \code{speech="normal"} correspoding to
+ the normal level of stated vocal effort. }
+ \item{noise}{A numeric vector providing $N'_i$, the equivalent
+ noise spectrum level (in dB) at each frequency. If missing,
+ defaults to -50 dB for each frequency.}
+ \item{threshold}{A numeric vector providing $T'_i$, the equivalent
+ hearing threshold level (in dB) at each frequency. If missing,
+ defaults to 0 dB for each frequency.}
+ \item{loss}{A numeric vector providing $J'_i$, the conductive hearing
+ loss level (in dB) at each frequency. If missing,
+ defaults to 0 dB for each frequency.}
+ \item{freq}{Vector of frequencies for which \code{speech},
+ \code{noise}, \code{threshold}, and/or \code{loss} are specified.
+ If \code{method="interpolate"}, \code{freq} must be specified.
+ Otherwise, it must either match the required value for SII
+ calculation method given by argument \code{method}, or be missing,
+ in which case it will default to the values required for the
+ specified method.}
+ \item{method}{A character string specifying the SII calculation
+ method ("critical", "one-third octave", "equal-contributing",
+ "octave"), or \code{"interpolate"} in which case the critical-band
+ method will be applied, with interpolation from the provided
+ frequencies to the required 21 frequency values.}
+ \item{importance}{Either a numeric vector providing $F_i$, the
+ transfer function (importance weights) at each frequency, or a character
+ string indicating which transfer function to employ ("SII", "NNS",
+ "CID22", "NU6", "DRT", "ShortPassage", "SPIN", "CST"). Defaults to
+ the standard SII transfer function, \code{importance="SII"}.}
+ \item{object,x}{SII object}
+ \item{digits}{Number of digits to display}
+ \item{...}{Optional arguments to \code{print}, \code{summary}, and
+ \code{plot} methods}
}
\details{
- ~~ If necessary, more details than the description above ~~
+ American National Standard ANSI S3.5-1997 ("Methods for Calculation of
+ the Speech Intelligibility Index") defines a method for computing a
+ physical measure that is highly correlated with the intelligibility
+ of speech as evaluated by speech perception tests given a group of
+ talkers and listeners. This measure is called the Speech
+ Intelligibility Index, or SII. The SII is calculated from acoustical
+ measurements of speech and noise.
+
+ The \code{sii} function implements ANSI S3.5-1997 as described in
+ the standard, without any attempt to optimize the performance. The
+ implementation does, however, include the extension for handling
+ conductive hearing loss from Annex A (utilizing the optional
+ \code{loss} argument, and for utilizing alternative band weights
+ (i.e. transfer function) appropriate for differing message contents
+ (e.g. types of speech) as described in Annex B or user-specified
+ band weights (utilizing the optional argument \code{importance}).
+
+ Further, this implementation provides a mechanism for
+ interpolating/extrapolating available measurements to those required
+ for calculating the critical band procedure (via the argument
+ \code{method="interpolate"}). Interpolation is accomplished using
+ linear interpolation (on log-scaled data) to the frequencies
+ required for the critical-band SII procedure. Interpolation is
+ performed (if necessary) for \code{noise}, \code{threshold}, and
+ \code{loss}.
+
}
\value{
- ~Describe the value returned
- If it is a LIST, use
- \item{comp1 }{Description of 'comp1'}
- \item{comp2 }{Description of 'comp2'}
- ...
+ The return value is an object of class SII, containing the following
+ components:
+ \item{call}{Function call used to generate the SII object}
+ \item{orig}{List containing original (pre-extrapolation) values for
+ \code{freq}, \code{speech}, \code{noise}, \code{threshold}, and
+ \code{loss}.}
+ \item{speech, noise, threshold, loss, and freq}{Values used in
+ calculations (extrapolated if necessary)}
+ \item{table}{SII calculation worksheet, containing columns
+ corresponding to both Table C.1 and C.2 in Annex C of the
+ standard. Table columns are
+ \describe{
+ \item{Fi}{Center frequency of SII band, Hz}
+ \item{E'i}{Spectrum level of equivalent speech, dB}
+ \item{N'i}{Spectrum level of equivalent noise, dB}
+ \item{T'i}{Equivalent hearing threshold level, dB}
+ \item{Vi}{Spectrum level for self-speech masking, dB}
+ \item{Bi}{Larger of the specrum levels for equivalent noise and
+ self-speech masking, dB}
+ \item{Ci}{Slope per octave (doubling of frequency) of the upward
+ spread of masking, dB/octave}
+ \item{Zi}{Spectrum level for equivalent masking, dB}
+ \item{Xi}{Spectrum level of internal noise, dB}
+ \item{X'i}{Spectrum level of equivalent internal noise, dB}
+ \item{Di}{Spectrum level for equivalent disturbance, dB}
+ \item{Ui}{Spectrum level of standard speech for normal vocal
+ effort, dB}
+ \item{Ji}{Equivalent hearing threshold due to conductive hearing
+ loss, dB}
+ \item{Li}{Speech level distortion factor, dB}
+ \item{Ki}{Temporary variable used in the calculation of the band
+ auditability function}
+ \item{Ai}{Band auditability function}
+ \item{Ii}{Band importance function}
+ \item{IiAi}{Product of the band importance function (Ii), and band
+ auditability function(Ai)}
+ }
+ }
+ \item{sii}{Calculated SII value}
}
-\references{ ~put references to the literature/web site here ~ }
-\author{ ~~who you are~~ }
-\note{ ~~further notes~~
+\references{
+ANSI S3.5-1997, "American National Standard Methods for
+Calculation of the Speech Intelligibility Index" American National
+Standards Institute, New York.
- ~Make other sections like Warning with \section{Warning }{....} ~
+Other software programs for calculating SII are available from
+\url{http://www.sii.to/html/programs.html}.
+
}
-\seealso{ ~~objects to See Also as \code{\link{help}}, ~~~ }
+\author{Gregory R. Warnes \email{gr...@ra...}}
+\seealso{ SII Constants: \code{\link{critical}}, and
+ \code{\link{sic.critical}} }
\examples{
-##---- Should be DIRECTLY executable !! ----
-##-- ==> Define data, use random,
-##-- or do help(data=index) for the standard data sets.
-## The function is currently defined as
-function (x, freq, noise, method = c("interpolate", "critical",
- "one-third octave", "equal-contributing", "octave"), voice = c("raised",
- "normal", "loud", "shout"))
-{
- if (!(is.matrix(x) || is.data.frame(x)))
- x <- matrix(x, nrow = 1)
- method = match.arg(method)
- voice = match.arg(voice)
- if (method == "interpolate")
- data.name = "critical"
- else data.name = method
- table <- read.csv("SII_Table1.csv", skip = 3, header = TRUE,
- nrows = 21, check.names = FALSE)
- if (method == "interpolate") {
- if (missing(freq) || length(freq) != ncol(x))
- stop("`freq' must contain the frequencies corresponding to the measurements in `x'.")
- }
- else {
- if (missing(freq))
- freq <- table[, "fi"]
- else if (freq != table[, "fi"])
- stop("`freq' does not match frequencies specified in table ",
- data.name, ".")
- }
- if (missing(noise))
- noise <- rep(0, length(freq))
- nas <- is.na(x)
- if (any(nas)) {
- if (method == "interpolate") {
- x <- x[!nas]
- freq <- freq[!nas]
- noise <- noise[!nas]
- }
- else stop("NA's only permitted for method 'interpolate'")
- }
- ord <- order(freq)
- x <- x[ord]
- freq <- freq[ord]
- noise <- noise[ord]
- retval <- list()
- retval$call <- match.call()
- retval$x.orig <- x
- retval$freq.orig <- freq
- retval$noise.orig <- noise
- if (method == "interpolate") {
- approx.l <- function(x, y, xout, ...) {
- retval <- approx(log(x), y, log(xout), ...)
- retval$x <- xout
- retval
- }
- sii.freqs <- table[, "fi"]
- THDI <- approx.l(x = freq, y = x, method = "linear",
- xout = sii.freqs, rule = 2)$y
- noise <- approx.l(x = freq, y = noise, method = "linear",
- xout = sii.freqs, rule = 2)$y
- freq <- sii.freqs
- x <- THDI
- }
- col.names <- c("Fi", "E'i", "N'i", "T'i", "Vi", "Bi", "Ci",
- "Z'i", "Xi", "X'i", "Di", "Ui", "Li", "Ki", "Ai", "Ii",
- "IiAi")
- sii.tab <- matrix(nrow = length(freq), ncol = length(col.names))
- colnames(sii.tab) <- col.names
- rownames(sii.tab) <- 1:nrow(sii.tab)
- sii.tab[, "Fi"] <- freq
- sii.tab[, "E'i"] <- table[, voice]
- sii.tab[, "N'i"] <- noise
- sii.tab[, "T'i"] <- x
- if (method == "octave")
- sii.tab[, "Zi"] <- sii.tab[, "N'i"]
- else {
- sii.tab[, "Vi"] <- sii.tab[, "E'i"] - 24
- sii.tab[, "Bi"] <- pmax(sii.tab[, "N'i"], sii.tab[, "Vi"])
- if (method == "critical" || method == "interpolate" ||
- method == "equal-contributing") {
- sii.tab[, "Ci"] = -80 + 0.6 * (sii.tab[, "Bi"] +
- 10 * log10(table[, "fi.high"] - table[, "fi.low"]))
- Zifun <- function(i) {
- if (i > 1)
- inner <- sum(10^(0.1 * sii.tab[1:(i - 1), "Bi"] +
- 3.32 * sii.tab[1:(i - 1), "Ci"] * log10(table[i,
- "Fi"]/table[1:(i - 1), "Fi.high"])))
- else inner <- 0
- 10 * log10(10^(0.1 * sii.tab[i, "N'i"]) + inner)
- }
- sii.tab[, "Z'i"] = sapply(1:nrow(sii.tab), Zifun)
- }
- else {
- sii.tab[, "Ci"] = -80 + 0.6 * (sii.tab[, "Bi"] +
- 10 * log10(sii.tab[, "Fi"]) - 6.353)
- Zifun <- function(i) {
- if (i > 1)
- inner <- sum(10^(0.1 * sii.tab[1:(i - 1), "Bi"] +
- 3.32 * sii.tab[1:(i - 1), "Ci"] * log10(0.89 *
- table[i, "Fi"]/table[1:(i - 1), "Fi.high"])))
- else inner <- 0
- 10 * log10(10^(0.1 * sii.tab[i, "N'i"]) + inner)
- }
- sii.tab[, "Z'i"] = sapply(1:nrow(sii.tab), Zifun)
- }
- sii.tab[1, "Z'i"] <- sii.tab[1, "Bi"]
- }
- sii.tab[, "Xi"] <- table[, "Xi"]
- sii.tab[, "X'i"] <- sii.tab[, "T'i"] + sii.tab[, "Xi"]
- sii.tab[, "Di"] <- max(sii.tab[, "Z'i"], sii.tab[, "X'i"])
- sii.tab[, "Ui"] <- table[, "normal"]
- enforce.range <- function(x) {
- x[x < 0] <- 0
- x[x > 1] <- 1
- x
- }
- sii.tab[, "Li"] <- enforce.range(1 - (sii.tab[, "E'i"] -
- sii.tab[, "Ui"] - 10)/160)
- sii.tab[, "Ki"] <- enforce.range((sii.tab[, "E'i"] - sii.tab[,
- "Di"] + 15)/30)
- sii.tab[, "Ai"] <- sii.tab[, "Li"] * sii.tab[, "Ki"]
- sii.tab[, "Ii"] <- table[, "Ii"]
- sii.tab[, "IiAi"] <- table[, "Ii"] * sii.tab[, "Ai"]
- sii.val <- sum(sii.tab[, "IiAi"])
- retval$THDN <- x
- retval$freq <- freq
- retval$sii <- sii.val
- retval$table <- sii.tab
- class(retval) <- "SII"
- retval
- }
+## Example C.1 from ANSI S3.5-1997 Annex C
+sii.C1 <- sii(
+ speech = c(50.0, 40.0, 40.0, 30.0, 20.0, 0.0),
+ noise = c(70.0, 65.0, 45.0, 25.0, 1.0,-15.0),
+ threshold= c( 0.0, 0.0, 0.0, 0.0, 0.0, 0.0),
+ method="octave"
+ )
+sii.C1 # rounded to 2 digits by default
+print(sii.C1$sii, digits=20) # full precision
+summary(sii.C1) # full details
+plot(sii.C1) # plot
+## The value given in the Standard is $0.504$.
+
+
+
+## Same calculation, but manually specify the frequencies
+## and importance function, and use default for threshold
+
+sii.C1 <- sii(
+ speech = c(50.0, 40.0, 40.0, 30.0, 20.0, 0.0),
+ noise = c(70.0, 65.0, 45.0, 25.0, 1.0,-15.0),
+ method="octave",
+ freq=c(250, 500, 1000, 2000, 4000, 8000),
+ importance=c(0.0617, 0.1671, 0.2373, 0.2648, 0.2142, 0.0549)
+ )
+sii.C1
+
+## Now perform the calculation using frequency weights for the Connected
+## Speech Test (CST)
+sii.CST <- sii(
+ speech = c(50.0, 40.0, 40.0, 30.0, 20.0, 0.0),
+ noise = c(70.0, 65.0, 45.0, 25.0, 1.0,-15.0),
+ method="octave",
+ importance="CST"
+ )
+round(sii.CST$table[,-c(5:7,13)],2)
+sii.CST$sii
+
+## Example C.2 from ANSI S3.5-1997 Annex C
+
+sii.C2 <- sii(
+ speech = rep(54.0, 18),
+ noise = c(40.0, 30.0, 20.0, rep(0, 18-3) ),
+ threshold= rep(0.0, 18),
+ method="one-third"
+ )
+sii.C2$table[1:3,1:8]
+sii.C2
+
+## Interpolation example, for 8 frequencies using NU6 importance
+## weight, default values for noise.
+sii.left <- sii(
+ speech="raised",
+ threshold=c(25,25,30,35,45,45,55,60),
+ freq=c(250, 500, 1000, 2000, 3000, 4000, 6000, 8000),
+ importance="NU6"
+ )
+sii.left
+
+
}
-% Add one or more standard keywords, see file 'KEYWORDS' in the
-% R documentation directory.
-\keyword{ ~kwd1 }
-\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line
+
+\keyword{math}
+
Deleted: trunk/SII/man/sii.excel.Rd
===================================================================
--- trunk/SII/man/sii.excel.Rd 2008-06-12 00:29:28 UTC (rev 1288)
+++ trunk/SII/man/sii.excel.Rd 2008-06-12 05:56:39 UTC (rev 1289)
@@ -1,80 +0,0 @@
-\name{sii.excel}
-\alias{sii.excel}
-%- Also NEED an '\alias' for EACH other topic documented here.
-\title{ ~~function to do ... ~~ }
-\description{
- ~~ A concise (1-5 lines) description of what the function does. ~~
-}
-\usage{
-sii.excel(THDI = c(25, 25, 30, 35, 45, 45, 55, 60), freq = c(250, 500, 1000, 2000, 3000, 4000, 6000, 8000), matlab.spline = TRUE)
-}
-%- maybe also 'usage' for other objects documented here.
-\arguments{
- \item{THDI}{ ~~Describe \code{THDI} here~~ }
- \item{freq}{ ~~Describe \code{freq} here~~ }
- \item{matlab.spline}{ ~~Describe \code{matlab.spline} here~~ }
-}
-\details{
- ~~ If necessary, more details than the description above ~~
-}
-\value{
- ~Describe the value returned
- If it is a LIST, use
- \item{comp1 }{Description of 'comp1'}
- \item{comp2 }{Description of 'comp2'}
- ...
-}
-\references{ ~put references to the literature/web site here ~ }
-\author{ ~~who you are~~ }
-\note{ ~~further notes~~
-
- ~Make other sections like Warning with \section{Warning }{....} ~
-}
-\seealso{ ~~objects to See Also as \code{\link{help}}, ~~~ }
-\examples{
-##---- Should be DIRECTLY executable !! ----
-##-- ==> Define data, use random,
-##-- or do help(data=index) for the standard data sets.
-
-## The function is currently defined as
-function (THDI = c(25, 25, 30, 35, 45, 45, 55, 60), freq = c(250,
- 500, 1000, 2000, 3000, 4000, 6000, 8000), matlab.spline = TRUE)
-{
- if (length(THDI) != length(freq))
- stop("THDI must have the same length as freq")
- sii.freqs <- sii.constants[, 1]
- if (matlab.spline) {
- ispl <- interpSpline(THDI ~ freq)
- THDI <- predict(ispl, sii.freqs)$y
- }
- else {
- approx.l <- function(x, y, xout, ...) {
- retval <- approx(log(x), y, log(xout), ...)
- retval$x <- xout
- retval
- }
- THDI <- approx.l(x = freq, y = THDI, method = "linear",
- xout = sii.freqs, rule = 2)$y
- }
- sii.tab <- sii.constants
- sii.tab[, c("Ti'.THDN", "Xi'.Int.Noise", "Di.Equiv.Dist",
- "ki.Temp.Var", "Ai.BandAud", "Si.SII.band.")] <- NA
- sii.tab[, "Ti'.THDN"] <- THDI
- sii.tab[, "Xi'.Int.Noise"] <- sii.tab[, "Ti'.THDN"] + sii.tab[,
- "Xi.Ref.Int.Nz"]
- sii.tab[, "Di.Equiv.Dist"] <- sii.tab[, "Xi'.Int.Noise"]
- sii.tab[, "ki.Temp.Var"] <- ifelse((sii.tab[, "Ei.Raised"] -
- sii.tab[, "Di.Equiv.Dist"] + 15)/30 > 1, 1, 0)
- sii.tab[, "Ai.BandAud"] <- sii.tab[, "ki.Temp.Var"]
- sii.tab[, "Si.SII.band."] <- sii.tab[, "I.BandImp"] * sii.tab[,
- "Ai.BandAud"]
- sii.val <- sum(sii.tab[, "Si.SII.band."])
- ret <- list(THDN = THDI, freq = freq, sii = sii.val, table = sii.tab)
- class(ret) <- "SII"
- ret
- }
-}
-% Add one or more standard keywords, see file 'KEYWORDS' in the
-% R documentation directory.
-\keyword{ ~kwd1 }
-\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
