R/Biotic.R

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

#============================================
#============================================
#' 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.
#' 
Catchability <- 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.
#' 
LengthWeightRelationship <- 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()
}

#============================================
#============================================
#' Regroup length distribution
#' 
#' The \emph{RegroupLengthDistribution} function is used to set a common length group resolution for one or all SpeciesCategories throughout the output length distribution dataset
#' 
#' @param parameterName Parameter descrption.
#' 
#' @details
#'The \emph{RegroupLengthDistribution} function is used to set a common length group resolution for one or all SpeciesCategories throughout the length distributions in the output dataset and across all Hauls. A parameter \emph{SpeciesCategory} is used to choose either All or one SpeciesCategory from the input LengthDistribution data set. A dropdown list of available SpeciesCategories in the input data is available for the selection. The parameter \emph{LengthInterval} is used to set the desired output length interval in centimeters.  The new length interval can never have finer resolution than the coarsest resolution found in the data that are due to be regrouped. A least common multiple of the length group intervals in the input is calculated. This value is the highest resolution possible. If the user chooses a finer resolution than this for the parameter LengthInterval, a warning will be given, and the least common multiple will be applied for the output LengthDistribution dataset from the process.
#' 
#' @return
#' A data.table is returned with awesome stuff.
#' 
#' @examples
#' x <- 1
#' 
#' @seealso \code{\link[roxygen2]{roxygenize}} is used to generate the documentation.
#' 
RegroupLengthDist <- 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.
#' 

RelLengthDist <- 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()
}

#============================================
#============================================
#' Station length distribution
#' 
#' The \emph{StationLengthDistribution} function produces length frequency distributions for each biotic station by SpeciesCategory, either as percentage or as count, optionally normalized by towing distance
#' 
#' @param parameterName Parameter descrption.
#' 
#' @details
#' The \emph{StationLengthDistribution} function produces length frequency distributions for each biotic station or Haul by SpeciesCategory. A SpeciesCategory is usually a taxonomic species, but the categorization may follow other criteria.The catch of one SpeciesCategory is often split into one or more CatchFractions. If the catch of a species consists of several distinct size ranges, it is common to perform such splitting. For each CatchFraction, a CatchFractionWeight has been calculated and raised to Haul level. The sum of all CatchFractionWeights for a SpeciesCategory is therefore equal to the total catch weight of the trawl Haul. A CatchFractionCount is calculated in the same manner.
#' 
#' From each CatchFraction, a Sample is usually taken. Various types of individual characteristics or population parameters are measures. The most common parameters are individual length followed by weight. Other parameters are age, sex, maturity etc. The Sample weight and number is recorded. From the CatchFractionWeight and the SampleWeight, a raising factor (\emph{r}) is calculated as:
#' 
#' \deqn{r = \frac{CatchFractionWeight}{SampleWeight}}
#' 
#' alternatively, the raising factor r can be calculated as:
#' 
#' \deqn{r = \frac{CatchFractionCount}{SampleCount}}
#' 
#' A \emph{RaisingOrder} parameter determines whether to make the first attempt on calculating the raising factor by weight or count variables. If the initial attempt fails due to lack of data, a new attempt is done using the alternative variables.
#' 
#' To produce a length frequency distribution for the Haul by SpeciesCategory, each Sample length distribution is first multiplied with the raising factor of the Sample. A total length distribution for the entire catch, is produced by adding the adjusted length distributions from all the Samples into one common length distribution for the SpeciesCategory in a Haul.
#' 
#' The Samples may have different length group intervals. If this is the case and the intervals overlap between Samples, the least common multiple is used as the length interval for the combined total length distribution.The combination of length frequencies from all Samples of a SpeciesCategory can be expressed as:
#' 
#'   
#' \deqn{d_s = \displaystyle\sum_{i=1}^{n} r_{s,i} \times d_{s,i}}
#' 
#' where  
#' 
#'\eqn{d_s}    is the resultant length distribution for the station or Haul \eqn{s},
#' 
#'\eqn{d_{s,i}}  is the length distribution of Sample no \eqn{i} at Haul \eqn{s}, 
#' 
#'\eqn{r_{s,i}}   is a raising factor for Sample no \eqn{i} at Haul \eqn{s},
#' 
#'\eqn{n}     is the number of Samples
#' 
#' The StationLengthDistribution function can generate three different distributions types:
#' 
#'1) \strong{LengthDistribution}
#' 
#' A calculated length distribution as if every individual of the SpeciesCategory in the Haul had been length measured. This is mainly done as described above. A raising factor for each Sample will be attempted calculated using either CatchFractionWeight and SampleWeight or CatchFractionCount and SampleCount. If both attempts to calculate a raising factor for one or more Samples fail, no LengthDistribution can be created for the SpeciesCategory in this Haul.


#' 
#' 2) \strong{NormLengthDist}
#' 
#' Normalized length distribution to one nautical mile towing distance. This distribution shows the length distribution as if the towing distance had been one nautical mile long and the entire catch had been length measured. The length distributions LengthDist is used together with the towing distance of the trawl station, to calculate this distribution. The number of fish from LengthDist in each length group is divided by the towing distance. It is worth noting that length distributions of type NormLengthDist from several stations may be compared since they are independent of effort (towing distance). Each of the length distributions reflects the CPUE of the trawl hauls. They are in other words implicitly weighted by CPUE. If towing distance is lacking for a station, length distributions of type NormLengthDist cannot be made.
#' 
#'3) \strong{PercentLengthDist}
#' 
#'Length distribution in percent. Length distributions of this type reflects the shape of the length distribution and contains therefore no implicit weighting.The calculation of percent length distributions is done as follows:
#'
#'A) If a SpeciesCategory at a station only have one Sample, the percent distribution is generated directly from the Sample length distribution. There is no need for knowing the raising factor.
#'
#'B) If a SpeciesCategory in a Hauls have more than one Sample, the percent distributions are generated by converting the LengthDistribution into percent distribution. This implies that distributions with more than one Sample and with missing raising factors will not be generated as no LengthDistribution exist for these.
#'   
#'\strong{General comments on the function}
#'   
#'The length group interval used in length distributions may vary within a Haul length distribution for one SpeciesCategory, between SpeciesCategories in the same Haul and between Hauls. However, different length intervals within one distribution cannot overlap. If they do, a least common multiple is calculated and used for the output length distribution.
#'Also note that some StoX models require one specific LengthDistributionType as output from the process and as input to other processes in the model.
#' 
#' @return
#' A data.table is returned with awesome stuff.
#' 
#' @examples
#' x <- 1
#' 
#' @seealso \code{\link[roxygen2]{roxygenize}} is used to generate the documentation.
#' 
StationLengthDist <- 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 description
#'  
#' @param parameterName Parameter descrption.
#' 
#' @details
#' 
#' @return
#' A data.table is returned with awesome stuff.
#' 
#' @examples
#' x <- 1
#' 
#' @seealso \code{\link[roxygen2]{roxygenize}} is used to generate the documentation.
#' 

StationSpecCatDensity <- 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.
#' 
SweptAreaDensity <- 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()
}


#============================================
#============================================
#' Total Length Distribution
#' 
#' Calculate total length distribution from a set of station length distributions and their corresponding weighting variables
#' 
#' @param parameterName Parameter descrption.
#' 
#' @details
#' The purpose of the TotalLengthDist function is to produces one total length distribution for each unique combination (identified by an AssignmentID) of assigned biotic stations with corresponding weighting variables. 
#'The unique combinations of assigned biotic stations and their weighting variables is a result of a previous biotic assignment function and a biotic assignment weighting function.
#'
#'If the biotic station length distributions which shall make up the total length distribution is of type \emph{LengthDist} (length distribution as if the complete catch on deck was measured), this will give an \emph{implicit weighting by catch as well as towing distance}.
#'
#'If the biotic station length distributions which shall make up the total length distribution is of type \emph{NormLengthDist} (length distribution as if the complete catch on deck was measured and as if the towing distance had been 1 nautical mile), this will give an \emph{implicit weighting by catch}.
#'
#'If the biotic station length distributions which shall make up the total length distribution is of type \emph{Percent} (sum of percentages for all length groups in the distribution is 100 and the shape of the distribution is the aim), this will give \emph{NO implicit weighting}.
#'
#'One total length distribution (one AssignmentID) is calculated as follows:
#'
#'1)	For each biotic station a weighting factor for each station is calculated from the weight variables of the assigned stations:
#'
#'\deqn{W_s = \frac{w_s}{\sum_{y=1}^{n} w_y}}
#'
#'where
#'
#'\eqn{W_s} 		= weighting factor for station \eqn{s}
#'
#'\eqn{n}		    = number of trawl stations to be combined
#'
#'\eqn{w_s}  		= the value of the weight variable for station \eqn{s}
#'
#'\eqn{w_y} 		= the value of the weight variable for station \eqn{y}
#'
#'
#'2)	For each length distribution by biotic station (\eqn{d_s}), the number or percentage value in each length group is multiplied by \eqn{W_s}:
#'
#'\deqn{dw_s = W_s \times d_s}
#'
#'3)	The total length distribution \eqn{d_t} is finally calculated by adding the numbers in each length interval for all stations where \eqn{n} is the number of stations to be combined:
#'
#'\deqn{d_t = \displaystyle\sum_{y=1}^{n} dw_y}
#'
#'\eqn{d_t} is the total length distribution for one AssignmentID.
#'
#' @return
#' A data.table is returned with awesome stuff.
#' 
#' @examples
#' x <- 1
#' 
#' @seealso \code{\link[roxygen2]{roxygenize}} is used to generate the documentation.
#' 
TotalLengthDist <- 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()
}