R/Acoustic.R

In StoXProject/RstoxTempDoc: Temporary package for documenting the RstoxFramework package

#============================================
#============================================
#' Acoustic Density
#' 
#' The AcousticDensity function calculates length distributed densities as number of fish per square nautical mile by vertical layer
#' 
#' @param parameterName Parameter descrption.
#' 
#' @details
#' The AcousticDensity function calculates length distributed densities as number of fish per square nautical mile by vertical layer. Length based density distributions are calculated for each NASC value of the input acoustic data set (MacLennan \emph{et al}, 2002) . Usually, the NASC values have a horizontal resolution at PSU level (e.g. transect). By combining a NASC value with a length distribution (usually a total combined length distribution derived from more than one biotic station) and applying a TS vslength relationship, a corresponding density length distribution can be calculated.
#' 
#'The horizontal resolution (EDSU, PSU or Stratum) of the NASC object determines the horizontal resolution of the densities. The same principal applies for the vertical layer resolution.
#' 
#'To combine a NASC value and a length distribution into a density distribution, the TS vs length relationship for the actual species and acoustic frequency, needs to be known.Constants in the TS vs length formula has to be given. If the vertical layer resolution is channels referred from surface and with a fixed thickness, the mean depth of each channel can be calculated and a depth dependent TS vs length formula may be applied. The calculation of densities by length from a NASC value and a corresponding length distribution (as percentage or proportion) is performed as follows (Ona, 2003, Simmond and MacLennan, 2005, Johnsen \emph{et al}, 2019):
#'
#'\deqn{TS_l = m \log_{10}{(l)}+a + d \log_{10}{(1 + \frac{r_y}{10})}}
#'
#'where:
#'
#'\eqn{TS_l} = target strength (dB re 1 \eqn{m^{2}}) of a fish with length l (cm)
#'
#'\eqn{m} = constant in the TS vs length relationship for the given
#'species
#'
#'\eqn{a} = constant in the TS vs length relationship for the given
#'species
#'
#'\eqn{d} = constant in the TS vs length relationship related to depth
#'dependent TS
#'
#'\eqn{l} = length of the fish (cm). Typically, the center length of a length group
#'
#'\eqn{r_y} = average depth (m) of the NASC channel \eqn{y}
#'
#'\deqn{\sigma_{bs,l} = 10^{  (  \frac{TS_l}{10}  )  }   }
#'
#'where:
#'
#'\eqn{\sigma_{bs,l}} = acoustic backscattering cross-section (\eqn{m^{2}}) for a fish of length \eqn{l}
#'
#'\deqn{NASC_l = NASC \frac{\sigma_{bs,l} p_l}{\sum_l{( \sigma_{bs,l} p_l )} } }
#'
#'where:
#'
#'\eqn{NASC} =  the total NASC which is used to calculate densities by length
#'
#'\eqn{NASC_l} = the proportion of the total \eqn{NASC} which can be attributed to length group \eqn{l}.  The sum of \eqn{NASC_l} for all length groups in the total length distribution is equal to \eqn{NASC}
#'
#'\eqn{p_l} = proportion of fish of length \eqn{l} in the input length distribution. Sum of all \eqn{p_l} is 1.
#'
#'
#'\deqn{\rho_l = \frac{NASC_l}{(4 \pi \sigma_{bs,l})}}
#'
#'where:
#'
#'\eqn{\rho_l} = area density of fish (ind. per sqare nautical mile) in length group \eqn{l}
#'
#'References:
#'
#'Johnsen, E,.Totland, A.,Skaalevik, A., et al., 2019, StoX: An open source software for marine survey analyses. Methods Ecol Evol. 2019;10:1523_1528.  \url{https://doi.org/10.1111/2041-210X.13250}
#'
#'MacLennan, D. N., Fernandes, P. G., and Dalen, J. 2002. A consistent approach to definitions and symbols in fisheries acoustics. ICES Journal of Marine Science, 59: 365_369.
#'
#'Ona, E. 2003, An expanded target strength relationship for herring, ICES Journal of Marine Science, Volume 60, Issue 3, 2003, Pages 493_499, \url{https://doi.org/10.1016/S1054-3139(03)00031-6}
#'
#'Simmonds, J., and MacLennan, D. 2005. Fisheries Acoustics. Theory and Practice, Blackwell Science, Oxford. 437 pp.
#'
#' @return
#' A data.table is returned with awesome stuff.
#' 
#' @examples
#' x <- 1
#' 
#' @seealso \code{\link[roxygen2]{roxygenize}} is used to generate the documentation.
#' 
AcousticDensity <- function(){
  # Use @noRd to prevent rd-files, and @inheritParams runBaseline to inherit parameters (those in common that are not documented) from e.g. getBaseline. Use @section to start a section in e.g. the details. Use @inheritParams runBaseline to inherit parameters from e.g. runBaseline()
}


#============================================
#============================================
#' NASC
#' 
#'The NASC function creates an acoustic output data set containing NASC values by acoustic category, frequency, vertical Channel resolution and horizontal EDSU resolution.
#' 
#' @param parameterName Parameter descrption.
#' 
#' @details
#'The NASC function creates an acoustic output data set containing NASC values by acoustic category, frequency, and a set of variables for vertical (Channel or Layer) and horizontal (Stratum, PSU or EDSU) resolution. The function represents the initial data preparation towards creating an acoustic NASC dataset with calculation cells for densities.
#'The NASC function requires input data of type \emph{StoXAcousticData} (LINK) and produces an output of data type \emph{NASCData} (LINK) where the vertical resolution is always at Channel level and horizontal resolution at EDSU level.  
#' 
#' The horizontal resolution is defined by the combination of the variables Stratum, PSU and EDSU where one or more of these variables may contain no value (NaN).
#' The parameter \emph{AcousticPSU} is optional, and is used to define input data linking Stratum to PSUs, and PSU to EDSUs and fill in values for Stratum and PSU in the output NASCData. If this option is applied, the horizontal resolution hierarchy is completed for the output NASCData.
#' 
#' The vertical resolution is defined by the combination of the variables Layer and Channel where one of these variables may contain no value (NaN).
#' The parameter \emph{AcousticLayer} is optional, and is used to define input data linking Layer to Channels and fill in values for Layer in the output NASCData. In addition, the AcousticLayer input data contains variable ChannelReference which refers to either the surface or the seabed. The ChannelReference variable of the output is updated with the value from AcousticLayer and an error message is given if more than one ChannelReference exist in the input StoXAcousticData. If the optional AcousticLayer is applied, the vertical resolution hierarchy is completed for the output NASCData.
#' 
#'The NASC values of the output are defined by the vertical resolution which again is associated with a vertical range (variables MinRange and MaxRange), and the horizontal resolution which is associated with a NASCWeight (the total log distance of the sample). Channels refer to either the surface or the seabed through variable ChannelReference.
#'
#' \strong{References:}
#' 
#'   MacLennan, D. N., Fernandes, P. G., and Dalen, J. 2002. A consistent approach to definitions and symbols in fisheries acoustics. ICES Journal of Marine Science, 59: 365_369.
#'   
#'   Simmonds, J., and MacLennan, D. 2005. Fisheries Acoustics. Theory and Practice, Blackwell Science, Oxford. 437 pp.
#' 
#' @return
#' A data.table is returned with awesome stuff.
#' 
#' @examples
#' x <- 1
#' 
#' @seealso \code{\link[roxygen2]{roxygenize}} is used to generate the documentation.
#' 
NASC <- function(){
  # Use @noRd to prevent rd-files, and @inheritParams runBaseline to inherit parameters (those in common that are not documented) from e.g. getBaseline. Use @section to start a section in e.g. the details. Use @inheritParams runBaseline to inherit parameters from e.g. runBaseline()
}



#============================================
#============================================
#' Some title
#' 
#' Some description
#' 
#' @param parameterName Parameter descrption.
#' 
#' @details
#' This function is awesome and does excellent stuff.
#' 
#' @return
#' A data.table is returned with awesome stuff.
#' 
#' @examples
#' x <- 1
#' 
#' @seealso \code{\link[roxygen2]{roxygenize}} is used to generate the documentation.
#' 
CombineNASC <- function(){
  # Use @noRd to prevent rd-files, and @inheritParams runBaseline to inherit parameters (those in common that are not documented) from e.g. getBaseline. Use @section to start a section in e.g. the details. Use @inheritParams runBaseline to inherit parameters from e.g. runBaseline()
}


#============================================
#============================================
#' Mean NASC
#' 
#' The MeanNASC function aggregates input data of type NASCData horizontally into an output data set of PSU or Stratum resolution.
#' 
#' @param parameterName Parameter descrption.
#' 
#' @details
#' The MeanNASC function aggregates input data of type \emph{NASCData} (LINK) horizontally into an output NASCData set of PSU or Stratum resolution. PSU resolution is equal to the horizontal calculation cell resolution used for density estimation in other functions.
#' 
#' The NASCData input source is given through the NASCData parameter. The aggregation variables PSU and Stratum may have values in the input data. If not, the optional parameter \emph{AcousticPSU} is used to define the input data linking PSU and Stratum to EDSU and fill in values for PSU and Layer prior to aggregating. The aggregation is calculated as a weighted mean of NASC over PSU or Stratum by vertical record. Variable NASCWeight in the input data is used as the weighting variable. The NASCWeight variable is updated in the output data to represent the sum of NASCWeight over the horizontal aggregation interval. NASCWeight is the total log distance a record represents.
#' 
#' \strong{References:}
#' 
#' MacLennan, D. N., Fernandes, P. G., and Dalen, J. 2002. A consistent approach to definitions and symbols in fisheries acoustics. ICES Journal of Marine Science, 59: 365_369.
#' 
#' Simmonds, J., and MacLennan, D. 2005. Fisheries Acoustics. Theory and Practice, Blackwell Science, Oxford. 437 pp.
#' 
#' @return
#' A data.table is returned with awesome stuff.
#' 
#' @examples
#' x <- 1
#' 
#' @seealso \code{\link[roxygen2]{roxygenize}} is used to generate the documentation.
#' 
MeanNASC <- function(){
  # Use @noRd to prevent rd-files, and @inheritParams runBaseline to inherit parameters (those in common that are not documented) from e.g. getBaseline. Use @section to start a section in e.g. the details. Use @inheritParams runBaseline to inherit parameters from e.g. runBaseline()
}


#============================================
#============================================
#' Sum NASC
#' 
#' The SumNASC function aggregates input data of type NASCData vertically, into an output data set with Layer resolution.
#' 
#' @param parameterName Parameter descrption.
#' 
#' @details
#' The SumNASC function aggregates input data of type \emph{NASCData} (LINK) vertically, into an output NASCData set with Layer resolution. Layer resolution is equal to the vertical calculation cell resolution used for density estimations in other functions.
#' 
#' The NASCData input source is given through the NASCData parameter. The aggregation variable Layer may have values in the input data. If not, the optional parameter \emph{AcousticLayer} is used to define the input data linking Layer to Channels and fill in values for Layer prior to aggregating. The aggregation is simply the sum of NASC over Layers by horizontal record. The variables MinRange and MaxRange are updated to represent the ranges of each Layer.
#' 
#'\strong{References:}
#' 
#'MacLennan, D. N., Fernandes, P. G., and Dalen, J. 2002. A consistent approach to definitions and symbols in fisheries acoustics. ICES Journal of Marine Science, 59: 365_369.
#' 
#'Simmonds, J., and MacLennan, D. 2005. Fisheries Acoustics. Theory and Practice, Blackwell Science, Oxford. 437 pp.
#' 
#' @return
#' A data.table is returned with awesome stuff.
#' 
#' @examples
#' x <- 1
#' 
#' @seealso \code{\link[roxygen2]{roxygenize}} is used to generate the documentation.
#' 
SumNASC <- function(){
  # Use @noRd to prevent rd-files, and @inheritParams runBaseline to inherit parameters (those in common that are not documented) from e.g. getBaseline. Use @section to start a section in e.g. the details. Use @inheritParams runBaseline to inherit parameters from e.g. runBaseline()
}


#============================================
#============================================
#' Some title
#' 
#' Some description
#' 
#' @param parameterName Parameter descrption.
#' 
#' @details
#' This function is awesome and does excellent stuff.
#' 
#' @return
#' A data.table is returned with awesome stuff.
#' 
#' @examples
#' x <- 1
#' 
#' @seealso \code{\link[roxygen2]{roxygenize}} is used to generate the documentation.
#' 
NASCToAcousticData <- function(){
  # Use @noRd to prevent rd-files, and @inheritParams runBaseline to inherit parameters (those in common that are not documented) from e.g. getBaseline. Use @section to start a section in e.g. the details. Use @inheritParams runBaseline to inherit parameters from e.g. runBaseline()
}


#============================================
#============================================
#' Some title
#' 
#' Some description
#' 
#' @param parameterName Parameter descrption.
#' 
#' @details
#' This function is awesome and does excellent stuff.
#' 
#' @return
#' A data.table is returned with awesome stuff.
#' 
#' @examples
#' x <- 1
#' 
#' @seealso \code{\link[roxygen2]{roxygenize}} is used to generate the documentation.
#' 
SplitNASC <- function(){
  # Use @noRd to prevent rd-files, and @inheritParams runBaseline to inherit parameters (those in common that are not documented) from e.g. getBaseline. Use @section to start a section in e.g. the details. Use @inheritParams runBaseline to inherit parameters from e.g. runBaseline()
}


#============================================
#============================================
#' Some title
#' 
#' Some description
#' 
#' @param parameterName Parameter descrption.
#' 
#' @details
#' This function is awesome and does excellent stuff.
#' 
#' @return
#' A data.table is returned with awesome stuff.
#' 
#' @examples
#' x <- 1
#' 
#' @seealso \code{\link[roxygen2]{roxygenize}} is used to generate the documentation.
#' 
SplitNASCAssignment <- function(){
  # Use @noRd to prevent rd-files, and @inheritParams runBaseline to inherit parameters (those in common that are not documented) from e.g. getBaseline. Use @section to start a section in e.g. the details. Use @inheritParams runBaseline to inherit parameters from e.g. runBaseline()
}