Merge pull request #157 from statgenlmu/doc_corrections

Doc corrections

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: coala
-Version: 0.3.9005
+Version: 0.4.0
 License: MIT + file LICENSE
 Title: A Framework for Coalescent Simulation
 Authors@R: c(

NEWS.md

@@ -1,16 +1,16 @@
-coala 0.4.0 (in development)
+coala 0.4.0
 ===========
 
 * Adds the `create_abc_param` and `create_abc_sumstat` functions for converting 
   the simulation results into the format needed for abc::abc function (#151).
-* Improves the documenation and adds more examples and links to similar
+* Improves the documentation significantly and adds more examples and links to
   help pages (#150).
 * Changes name of `get_population_indiviuals` to `get_population_individuals`
   (#150).
 * Adds an option to `active_msms()` to download msms' jar file (#153).
 * Adds support for partial models. Now, arbitrary sets of features, loci,
   parameters and summary statistics can be combined via `+` and then be
-  added to one or more models later.
+  added to one or more models later (#155).
 
 
 

R/RcppExports.R

@@ -23,7 +23,7 @@ generate_trio_trees <- function(trees, llm) {
 #' @param positions A numeric vector indicating the relative positions of each
 #'   SNP on the locus (see Details).
 #' @param trio_locus If the locus consists of a locus trio (see Details).
-#' @param check Whether non-segregating sites are remove from the segregating
+#' @param check Whether non-segregating sites are removed from the segregating
 #'   sites (\code{TRUE}) or not (\code{FALSE}).
 #' @export
 #'

R/feature_growth.R

@@ -20,9 +20,6 @@ growth_class <- R6Class("growth", inherit = feature_class,
 #' backwards in time or grow forwards in time. For a negative value of
 #' \eqn{\alpha} it will decline (forward in time).
 #'
-#' If you want to add an ,
-#' then use
-#'
 #' @param rate The growth rate. Can be a numeric or a \code{\link{parameter}}.
 #'        See \code{Details} for an explanation how the rate affects the
 #'        population size.

R/feature_ignore_singletons.R

@@ -9,8 +9,9 @@ ign_singletons_class <- R6Class("ign_singletons", inherit = feature_class)
 #' singletons from the simulated data before the summary statistics are
 #' calculated.
 #'
-#' For this function, a singleton is a mutation for which the derived allele is
-#' observed exactly once in all populations.
+#' This function assumes that a singleton is a mutation for which the derived
+#' allele is observed exactly once in all sequences, regardless of the
+#' population structure.
 #'
 #' @return The feature, which can be added to a model using `+`.
 #' @export

R/feature_mutation.R

@@ -96,7 +96,7 @@ mutation_class <- R6Class("mutation", inherit = feature_class,
 #' @section Mutation Models:
 #' The infinite sites mutation (\strong{IFS}) model is a frequently used simplification
 #' in population genetics. It assumes that each locus consists of infinitely
-#' many sites at which mutations can occure, and each mutation hits a new site.
+#' many sites at which mutations can occur, and each mutation hits a new site.
 #' Consequently, there are no back-mutations with this model. It does not
 #' generate DNA sequences, but rather only 0/1 coded data, were 0 denotes the
 #' ancestral state of the site, and 1 the derived state created by a mutation.

R/feature_pop_merge.R

@@ -18,7 +18,7 @@ pop_merge_class <- R6Class("pop_merge", inherit = feature_class,
 #' Backwards in time, this feature merges one population into another.
 #' Forwards in time, this corresponds to a speciation event.
 #'
-#' Additionally to the merge, all migration rates from and the growth rate of
+#' In addition to the merge, the growth rate of and all migration rates from
 #' the source population will be set to 0 at the time of the merge to mimic
 #' a speciation event forwards in time. Technically, \code{pop_source} is
 #' still present in the model, but not used unless migration to the population

R/feature_recombination.R

@@ -12,7 +12,8 @@ recombination_class <- R6Class("recombination", inherit = feature_class,
 #' for \link[=locus]{unlinked loci} and per trio for linked
 #' \link[=locus_trio]{locus trios}. By default, the same recombination rate is used
 #' for all loci, but it is possible to change this with \code{\link{par_variation}}
-#' and \code{\link{par_zero_inflation}}.
+#' and \code{\link{par_zero_inflation}}. Coala assumes that recombination events
+#' can occur between all neighboring bases.
 #'
 #' @param rate The recombination rate. Can be a numeric or a
 #'        \code{\link{parameter}}. The rate is equal to

R/feature_selection.R

@@ -75,7 +75,7 @@ selection_class <- R6Class("selection", inherit = feature_class,
 #'   be \code{all} for all population, or the number of a population.
 #' @param time The time at which the selection starts if \code{start == TRUE}
 #'   (looking forwards in time), or the time at which the selection strength
-#'   changes if \code{start == FALSE}. The new strength applies for to the time
+#'   changes if \code{start == FALSE}. The new strength applies for the time
 #'   period further into the past in this case.
 #' @param strength_AA The selection strength for the selected homozygote.
 #'   The parameter is valid for the chosen population and the time further
@@ -84,11 +84,11 @@ selection_class <- R6Class("selection", inherit = feature_class,
 #'   \code{strength_A}.
 #' @param strength_Aa The selection strength for the heterozygote.
 #' @param strength_aa The selection strength for the recessive homozygote.
-#' @param strength_A This sets the strength for the selected allele in an
+#' @param strength_A This sets the strength for the selected allele in a
 #'   haploid model or a diploid model with additive selection.
 #'   \code{strength_AA}, \code{strength_Aa}, \code{strength_aa}
 #'   are ignored when this is argument is given.
-#' @param start Whether selection should start at this time point. At this time
+#' @param start Whether selection should start at this time point. At this time,
 #'   the selected allele is introduced in the population with an initial
 #'   starting frequency. This must be set to \code{TRUE} for exactly one
 #'   selection feature in the model. The values of \code{start_frequency},
@@ -97,7 +97,7 @@ selection_class <- R6Class("selection", inherit = feature_class,
 #'   selection strength for more demes or change it at different time points,
 #'   but these need to have \code{start = FALSE}.
 #' @param start_frequency The start frequency at which the selected allele is
-#'   introduced at time \code{time}. If the model has multiple population, this
+#'   introduced at \code{time}. If the model has multiple population, this
 #'   can either be a numeric vector that contains the initial frequency for each
 #'   population or a single number. In the latter case, the value is used for
 #'   all population specified with \code{populations}, and 0 is used for all

R/interface_abc.R

@@ -1,6 +1,6 @@
 #' Convert Simulation Results to abc's Parameter Format
 #'
-#' This functions creates an object compatible with the \code{param}
+#' This function creates an object compatible with the \code{param}
 #' argument of the \code{\link[abc]{abc}} function from coala's simulation
 #' results.
 #'
@@ -36,7 +36,7 @@ create_abc_param <- function(sim_results, model) {
 
 #' Convert Simulation Results to abc's Summary Statistic Format
 #'
-#' This functions creates an object compatible with the \code{sumstat}
+#' This function creates an object compatible with the \code{sumstat}
 #' argument of the \code{\link[abc]{abc}} function from coala's simulation
 #' results. It converts all summary statistics that are in the simulation
 #' results and expects that each of them is a numeric vector.

R/locus.R

@@ -46,7 +46,7 @@ is.locus <- function(locus) any("locus" == class(locus))
 #'
 #' This functions adds one or more loci to a model. A locus is a continuous
 #' stretch of DNA of a given length. All loci are simulated independently of each
-#' other, and are in particular genetically unlinked. A model can contain a
+#' other, and are genetically unlinked. A model can contain a
 #' large number of different loci created with \code{locus_single}. This will,
 #' however, slow down the simulation. For performance reasons, it is
 #' better to add the same number of loci with averaged length using

R/model_check.R

@@ -4,7 +4,7 @@
 #' simulate a given model. It also states the problems for the ones that
 #' are incompatible with the model.
 #'
-#' @param model The model that is checked
+#' @param model The model which is checked
 #' @export
 #' @seealso Do view the priority of the simulators: \code{\link{list_simulators}}
 #' @examples

R/parameter.R

@@ -186,8 +186,8 @@ is.ranged_par <- function(par) inherits(par, "range_par")
 #'  \pkg{jaatha}.
 #'
 #' @export
-#' @param lower A numeric. The lower boundary of the parameter"s range.
-#' @param upper A numeric. The upper boundary of the parameter"s range.
+#' @param lower A numeric. The lower boundary of the parameter's range.
+#' @param upper A numeric. The upper boundary of the parameter's range.
 par_range <- function(name, lower, upper) {
   range_par_class$new(lower, upper, name)
 }

R/segsites.R

@@ -1,13 +1,13 @@
 #' Segregating Sites
 #'
-#' This functions allow the creation and modification of segregating sites
+#' These functions create and modify segregating sites
 #' objects, which are one of the basic intermediary statistics that is
 #' calculated in coala. Segregating sites consist primarily of a SNP matrix that
 #' contains all SNPs for one locus, with some additional information attached.
 #' The parts of the S3 class are detailed below.
 #'
 #' A segregating sites object contains all SNPs for one genetic locus. Each
-#' object consists of tree parts: A SNP matrix, a vector of SNP positons and
+#' object consists of three parts: A SNP matrix, a vector of SNP positons and
 #' a vector that states which transcript a SNP belong to, if the locus
 #' consists of multiple transscripts ('locus trio').
 #'

R/simulator_ms.R

@@ -115,7 +115,7 @@ has_ms <- function() !is.null(simulators[["ms"]])
 #'
 #' This function adds the simulator 'ms' to the list of available simulators.
 #' In order to use 'ms', you need to install the CRAN package \pkg{phyclust}.
-#' By default, 'scrm' will be prefered to 'ms'. Raise the priority of 'ms'
+#' By default, 'scrm' will be preferred over 'ms'. Raise the priority of 'ms'
 #' to change this behavior.
 #'
 #' @references

R/sumstat.R

@@ -153,7 +153,7 @@ calc_sumstats_from_sim <- function(seg_sites, trees, files, model,
 #'   summary statistics is locus in the provided data that corresponds to the
 #'   number. If three numbers are provided, the locus for calculation is created
 #'   by combining the corresponding three loci from the given data.
-#' @param ... Additional arguments that will be pass to
+#' @param ... Additional arguments that will be passed to
 #'   \code{\link{as.segsites}}.
 #' @export
 #' @examples

R/sumstat_jsfs.R

@@ -39,7 +39,7 @@ stat_jsfs_class <- R6Class("stat_jsfs", inherit = sumstat_class,
 #' @inheritParams sumstat_four_gamete
 #' @param populations An integer vector containing the populations for which
 #'        the JSFS is generated.
-#' @param per_locus If \code{TRUE}, the JSFS is return for each locus instead
+#' @param per_locus If \code{TRUE}, the JSFS is returned for each locus instead
 #'   of globally. In this case, the result is a list, where each entry is the
 #'   JSFS for the corresponding locus.
 #' @return The JSFS, given as an array. The dimensions correspond to the

R/sumstat_omega.R

@@ -111,7 +111,7 @@ stat_omega_class <- R6Class("stat_omega", inherit = sumstat_class,
 #'
 #' Calculates the Omega Statistic introduced by
 #' Kim & Nielsen (2004) from the simulated data. The statistic is sensitive for
-#' for hard selective sweeps. To calculate
+#' hard selective sweeps. To calculate
 #' the statistic, coala relies on the command line program
 #' \href{http://sco.h-its.org/exelixis/web/software/omegaplus/index.html}{OmegaPlus},
 #' which needs to be downloaded and compiled manually in order to use the