diff --git a/DESCRIPTION b/DESCRIPTION index 38a7bb2..7adc93a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: ggd Type: Package Title: Gradational Gaussian Distribution Reference Class -Version: 1.0.2 +Version: 1.0.3 Authors@R: c( person( given = "Kimitsuna", family = "Ura", diff --git a/R/cmn.bisection.R b/R/cmn.bisection.R index d0c12da..728c292 100644 --- a/R/cmn.bisection.R +++ b/R/cmn.bisection.R @@ -12,7 +12,7 @@ ################################################################################################ #' [Non-exported] Bisection method #' -#' Solves a equation via bisection method. +#' Solves an equation via bisection method. #' @param f The destination function to solve. #' @param interval A numeric vector of length 2 indicating the range of x value #' on which the solution is to be searched. diff --git a/R/cmn.csv.R b/R/cmn.csv.R index a2baaec..60c93fd 100644 --- a/R/cmn.csv.R +++ b/R/cmn.csv.R @@ -12,18 +12,17 @@ ################################################################################################ #' [Non-exported] Output a table to a file #' -#' Prints the argument \code{x} (it should be a data frame or matrix) -#' to a file or \link[base]{connection} with the CSV format. -#' This function use \link[base]{cat} to output. -#' When outputting real numbers, the precision can be specified with \code{digits} argument. -#' @param x The object to be written, should be a matrix or data frame. +#' Outputs a data frame or a matrix to a file or \link[base]{connection} with the CSV format +#' using \link[base]{cat}. +#' The precision for real numbers can be indicated with \code{digits} argument. +#' @param x The object to be output, should be a matrix or data frame. #' @param file A \link[base]{connection}, #' or a character string naming the file to print to. #' If \code{""} (the default), it prints to the standard output connection, #' the console unless redirected by \link[base]{sink}. #' @param top.text A character string to be output as the first element of the header. -#' @param digits The number of significant digits to print (see \link[base]{signif}). -#' Valid values are integers from 1 to 22 with default 15. +#' @param digits The number of significant digits (see \link[base]{signif}) to print. +#' Integers from \code{1} to \code{22} with default \code{15} are allowed. #' @return An invisible \code{NULL}. #' @examples #' ggd:::cat.table( data.frame( a = 1:6 * pi, b = pi^(1:6) ), top.text = "PI", digits = 10 ) diff --git a/R/cmn.norm.R b/R/cmn.norm.R index d7a929b..6b80d91 100644 --- a/R/cmn.norm.R +++ b/R/cmn.norm.R @@ -12,19 +12,19 @@ ################################################################################################ #' Sigma-unit distance from the mean of a normal distribution #' -#' Calculates how many sigmas are the distances from the mean of a normal distribution -#' to the values of the quantile function for the given probabilities. -#' The mean and standard deviation are not need for this function, because sigma-unit distances -#' do not depend on them. +#' Calculates how many sigmas are the distance from the mean of a normal distribution +#' to the x-coordinate of the quantile which has the indicated probability. +#' The mean and standard deviation are not needed for this function +#' because the sigma-unit distance does not depend on them. #' @export -#' @param p A vector of probabilities. -#' @return A vector of sigma-unit distances from the mean to the quantiles for -#' the probabilities. +#' @param p A vector of the probabilities of the quantiles. +#' @return A vector of sigma-unit distances +#' from the mean to the x-coordinates of the quantiles. #' @importFrom stats qnorm #' @examples -#' sqnorm( 0.5 ) # 0 -#' sqnorm( pnorm( -2, 0, 1 ) ) # -2 -#' sqnorm( seq( 0, 1, 0.1 ) ) # increces from -Inf to Inf +#' sqnorm( 0.5 ) ## 0 +#' sqnorm( pnorm( -2, 0, 1 ) ) ## -2 +#' sqnorm( seq( 0, 1, 0.1 ) ) ## increases from -Inf to Inf ################################################################################################ sqnorm <- function( p ) { @@ -34,8 +34,8 @@ sqnorm <- function( p ) ################################################################################################ #' Standard deviation of a normal distribution #' -#' Calculates the standard deviations of the normal distribution -#' satisfying the given mean and one other quantile. +#' Calculates the standard deviation of the normal distribution +#' which has the indicated mean and passes through one other quantile. #' @export #' @param mean A vector of the mean values of the normal distributions. #' @param x A vector of x-coordinates of the quantiles. @@ -43,11 +43,11 @@ sqnorm <- function( p ) #' @param p A vector of the probabilities for the quantiles. #' In other word, the value of the cumulative distribution function of #' a normal distribution for the \code{x}. The value must not be \code{0.5}. -#' @return The vector of the standard deviations. +#' @return A vector of the standard deviations. #' @examples -#' sd.norm.mxp( 0, qnorm( 0.3, 0, 1 ), 0.3 ) # 1 -#' sd.norm.mxp( rep( 0, 5 ), 1:5, pnorm( 1:5, 0, 1 ) ) # 1 1 1 1 1 -#' sd.norm.mxp( c( -0.1, 0, 0.3 ), c( -0.3, -0.1, 0.4 ), c( 0.38, 0.47, 0.53 ) ) # [2] == [3] +#' sd.norm.mxp( 0, qnorm( 0.3, 0, 1 ), 0.3 ) ## 1 +#' sd.norm.mxp( rep( 0, 5 ), 1:5, pnorm( 1:5, 0, 1 ) ) ## 1 1 1 1 1 +#' sd.norm.mxp( c( -0.1, 0, 0.3 ), c( -0.3, -0.1, 0.4 ), c( 0.38, 0.47, 0.53 ) ) ## [2] == [3] ################################################################################################ sd.norm.mxp <- function( mean, x, p ) { @@ -58,22 +58,22 @@ sd.norm.mxp <- function( mean, x, p ) #' Mean and standard deviation of a normal distribution #' #' Calculates the mean and standard deviation of the normal distribution -#' satisfying the given two quantiles. +#' which passes through the indicated two quantiles. #' This is the body of \code{ggd.trace.q(kind = "Normal Distribution")}. #' @export -#' @param x The x-coordinates of the quantiles. It must be a vector with 2 numerics. +#' @param x The x-coordinates of the quantiles. It must be a vector with 2 elements. #' @param p The probabilities for the quantiles. #' In other word, the values of the cumulative distribution function of -#' a normal distribution for \code{x}. It must be also a vector with 2 numerics. +#' a normal distribution for \code{x}. It must be also a vector with 2 elements. #' @return A list containing components #' \item{mean}{ #' The mean value of the normal distribution.} #' \item{sd}{ #' The standard deviation of the normal distribution.} #' @examples -#' ms.norm.xp( x = c( -1, 1 ), p = pnorm( c( -1, 1 ), 0, 1 ) ) # list( mean = 0, sd = 1 ) -#' ms.norm.xp( x = c( 0, 1 ), p = pnorm( c( 0, 1 ), 0, 2 ) ) # list( mean = 0, sd = 2 ) -#' ms.norm.xp( x = c( -2, 1 ), p = c( 0.3, 0.7 ) ) # list( mean = 0.5, sd = 2.86 ) (about) +#' ms.norm.xp( x = c( -1, 1 ), p = pnorm( c( -1, 1 ), 0, 1 ) ) ## list( mean = 0, sd = 1 ) +#' ms.norm.xp( x = c( 0, 1 ), p = pnorm( c( 0, 1 ), 0, 2 ) ) ## list( mean = 0, sd = 2 ) +#' ms.norm.xp( x = c( -2, 1 ), p = c( 0.3, 0.7 ) ) ## list( mean = -0.5, sd = about 2.86 ) ################################################################################################ ms.norm.xp <- function( x, p ) { diff --git a/R/ggd.1.R b/R/ggd.1.R index 22cd0a7..d2bea3c 100644 --- a/R/ggd.1.R +++ b/R/ggd.1.R @@ -75,33 +75,33 @@ f.t3.p <- list( function( x, m, s ) #' \code{cmp} has 4 rows. #' } #' -#' With \code{mix.type = 1}, the distribution model is not +#' The distribution model of \code{mix.type = 1} is not #' a gradational Gaussian distribution (GGD), but a kind of #' Gaussian mixture model (GMM). #' This is provided for comparing GGD with GMM. #' -#' @field cmp A data frame with 2 numeric columns which shows -#' the normal distributions of the components. +#' @field cmp A data frame with 2 numeric columns which have +#' the parameters of the normal distributions of the components. #' #' \code{mean} column represents the mean values of the components, #' and \code{sd} column represents the standard deviations. #' -#' Where \code{mix.type} is in \code{0:3}, -#' it has 1 to 3 rows named like "\code{n.i}". +#' Where \code{mix.type} is from \code{0} to \code{3}, +#' it has 1 to 3 rows named like \code{"n.i"}. #' Where \code{mix.type = 4}, -#' it has 4 rows named like "\code{n.i.j}". +#' it has 4 rows named like \code{"n.i.j"}. #' #' @field median A numeric; the median of the distribution. #' @field mean A numeric; the mean of the distribution. #' @field sd A numeric; the standard deviation of the distribution. -#' @field lsd A numeric; the semi-standard deviation lower than mean. -#' @field usd A numeric; the semi-standard deviation upper than mean. +#' @field lsd A numeric; the half standard deviation lower than the mean. +#' @field usd A numeric; the half standard deviation upper than the mean. #' @field lsd.abs.error A numeric; #' the estimated modulus of the absolute error for \code{lsd}. #' @field usd.abs.error A numeric; #' the estimated modulus of the absolute error for \code{usd}. #' -#' Where \code{mix.type = 4}, to compute the semi-standard deviations, +#' Where \code{mix.type = 4}, to compute the half standard deviations, #' \code{\link[stats]{integrate}} function is used. #' And the modulus of the absolute errors which #' \code{\link[stats]{integrate}} function has reported @@ -119,7 +119,7 @@ f.t3.p <- list( function( x, m, s ) #' #' The GGD is alike the Gaussian mixture model (GMM) but different. #' The GMM is represented by linear combinations of some normal distributions, -#' and is often used for clustering of mixed data. +#' and it is commonly used for clustering mixed data. #' On the other hand, the GGD is a distribution model of #' which mixes some normal distributions with gradually changing ratio #' along the x-axis or y-axis directions, @@ -133,8 +133,8 @@ f.t3.p <- list( function( x, m, s ) #' where \eqn{h_1} and \eqn{h_2} are the mixing ratio functions defined #' using \eqn{\Phi_1} and \eqn{\Phi_2}, the cumulative distribution functions of #' \eqn{\mathcal{N}_1} and \eqn{\mathcal{N}_2} as -#' \deqn{h_1(x) = 1 - \Phi_1(x), \\ -#' h_2(x) = \Phi_2(x). \quad \ \ \ } +#' \deqn{h_1(x) = 1 - \Phi_1(x), \ \ \\ +#' h_2(x) = \Phi_2(x). \quad \ \ \ \ \ } #' #' Therefore, \eqn{h_1(x)} decreases gradually along x-axis as #' \eqn{x:-\infty \to \infty \ \Rightarrow \ h_1(x):1 \to 0}, @@ -155,8 +155,8 @@ f.t3.p <- list( function( x, m, s ) #' where the mixing ratio functions \eqn{v_1} and \eqn{v_2} are defined #' using \eqn{f_1} and \eqn{f_2}, the probability density functions of #' \eqn{\mathcal{N}_1} and \eqn{\mathcal{N}_2} as -#' \deqn{v_1(x) = 1 - \dfrac{f_1(x)}{f_1(\mu_1)}, \\ -#' v_2(x) = \dfrac{f_2(x)}{f_2(\mu_2)}, \quad \ \ \ } +#' \deqn{v_1(x) = 1 - \dfrac{f_1(x)}{f_1(\mu_1)}, \ \ \\ +#' v_2(x) = \dfrac{f_2(x)}{f_2(\mu_2)}, \quad \ \ \ \ \ } #' where \eqn{\mu_1} and \eqn{\mu_2} are the mean values of #' \eqn{\mathcal{N}_1} and \eqn{\mathcal{N}_2}, respectively. #' @@ -170,8 +170,8 @@ f.t3.p <- list( function( x, m, s ) #' Or, using \eqn{\mu_1} and \eqn{\mu_2}, #' the mean values of \eqn{\mathcal{N}_1} and \eqn{\mathcal{N}_2}, we can write as #' \deqn{x:-\infty \to \mu_1 \ \Rightarrow \ v_1(x):1 \to 0, \ \ \ \ -#' x:\mu_1 \to \infty \ \Rightarrow \ v_1(x):0 \to 1, \\ -#' x:-\infty \to \mu_2 \ \Rightarrow \ v_2(x):0 \to 1, \ \ \ \ +#' x:\mu_1 \to \infty \ \Rightarrow \ v_1(x):0 \to 1,} +#' \deqn{x:-\infty \to \mu_2 \ \Rightarrow \ v_2(x):0 \to 1, \ \ \ \ #' x:\mu_2 \to \infty \ \Rightarrow \ v_2(x):1 \to 0.} #' #' Here, we call \eqn{\mathcal{N}_1} the \bold{tail-side} distribution, @@ -186,7 +186,7 @@ f.t3.p <- list( function( x, m, s ) #' The tops of \eqn{f_1} and \eqn{f_2} could be far apart from each other, #' and moreover, the top of \eqn{\mathcal{G}[\mathcal{N}_1 \uparrow \mathcal{N}_2]} #' could be nearby the top of \eqn{f_1}, instead of \eqn{f_2}. -#' That may be contrary to the intuitive image of the "vertical gradational distribution", +#' That may be contrary to the intuitive image of the 'vertical gradational distribution', #' but it is not prohibited. #' #' About the \bold{3-component vertical gradational Gaussian distribution}, @@ -246,57 +246,50 @@ f.t3.p <- list( function( x, m, s ) #' #' \describe{ #' \item{\code{mix.type = 0} (normal distribution)}{\deqn{ -#' g(x) = f_1(x) \\ -#' \Psi(x) = \Phi_1(x) }} +#' g(x) = f_1(x), \ \ \\ +#' \Psi(x) = \Phi_1(x). \ \ }} #' #' \item{\code{mix.type = 1} (mean of 2 normal distributions; #' a Gaussian mixture model (GMM), not a GGD)}{\deqn{ -#' g(x) = \dfrac{f_1(x) + f_2(x)}{2} \ \\ -#' \Psi(x) = \dfrac{\Phi_1(x) + \Phi_2(x)}{2} }} +#' g(x) = \dfrac{f_1(x) + f_2(x)}{2}, \ \ \\ +#' \Psi(x) = \dfrac{\Phi_1(x) + \Phi_2(x)}{2}. \ }} #' #' \item{\code{mix.type = 2} (horizontal GGD)}{\deqn{ #' g(x) = \left( 1 - \Phi_1(x) \right) f_1(x) -#' + \Phi_2(x) f_2(x) \\ +#' + \Phi_2(x) f_2(x), \ \ \\ #' \ \\ #' \Psi(x) = \Phi_1(x) - \dfrac{\Phi_1(x)^2}{2} + -#' \dfrac{\Phi_2(x)^2}{2} \qquad \ \ }} +#' \dfrac{\Phi_2(x)^2}{2}. \qquad \ \ \ \ }} #' #' \item{\code{mix.type = 3}, \code{grad = "v2"} (2-component vertical GGD)}{\deqn{ #' g(x) = \left( 1 - \dfrac{f_1(x)}{f_1(\mu_1)} \right) f_1(x) + -#' \dfrac{f_2(x)^2}{f_2(\mu_2)} \\ +#' \dfrac{f_2(x)^2}{f_2(\mu_2)}, \ \ \\ #' \ \\ #' \Psi(x) = \Phi_1(x) - \dfrac{\Phi^*_1(x)}{\sqrt{2}} + -#' \dfrac{\Phi^*_2(x)}{\sqrt{2}} \qquad \; \: }} +#' \dfrac{\Phi^*_2(x)}{\sqrt{2}}. \qquad \ \ \; \: }} #' #' \item{\code{mix.type = 3}, \code{grad = "v3"} (3-component vertical GGD)}{\deqn{ -#' g(x) = g_1(x) + g_2(x) + g_3(x) \hspace{14.5em} \\ -#' \ \\ -#' g_1(x) = \left( 1 - \dfrac{f_1(x)}{f_1(\mu_1)} \right) f_1(x) -#' \quad (x \leq \mu_1; \ \mathrm{otherwise} \ 0) \\ -#' \ \\ -#' g_2(x) = \dfrac{f_2(x)^2}{f_2(\mu_2)} \hspace{15.6em} \\ -#' \ \\ -#' g_3(x) = \left( 1 - \dfrac{f_3(x)}{f_3(\mu_3)} \right) f_3(x) -#' \quad (x \geq \mu_3; \ \mathrm{otherwise} \, 0) \\ -#' \ \\ -#' \Psi(x) = \min \left( \Phi_1(x) - \dfrac{\Phi^*_1(x)}{\sqrt{2}}, +#' g(x) = g_1(x) + g_2(x) + g_3(x), \hspace{14.5em} \\ } +#' \deqn{g_1(x) = \left( 1 - \dfrac{f_1(x)}{f_1(\mu_1)} \right) f_1(x) +#' \quad (x \leq \mu_1; \ \mathrm{otherwise} \ 0), \\ } +#' \deqn{g_2(x) = \dfrac{f_2(x)^2}{f_2(\mu_2)}, \hspace{15.6em} \\ } +#' \deqn{g_3(x) = \left( 1 - \dfrac{f_3(x)}{f_3(\mu_3)} \right) f_3(x) +#' \quad (x \geq \mu_3; \ \mathrm{otherwise} \, 0), \\ } +#' \deqn{\Psi(x) = \min \left( \Phi_1(x) - \dfrac{\Phi^*_1(x)}{\sqrt{2}}, #' \ \dfrac{2 - \sqrt{2}}{4} \right) \hspace{10em} \\ #' + \dfrac{\Phi^*_2(x)}{\sqrt{2}} #' + \max \left( 0, \ \Phi_3(x) - \dfrac{\Phi^*_3(x)}{\sqrt{2}} - -#' \dfrac{2 - \sqrt{2}}{4} \right) }} +#' \dfrac{2 - \sqrt{2}}{4} \right). }} #' #' \item{\code{mix.type = 4} (horizontal-vertical GGD)}{\deqn{ -#' g(x) = \left( 1 - \Psi_1(x)\ \right) g_1(x) + \Psi_2(x) g_2(x) -#' \hspace{6em} \ \ \\ -#' \ \\ -#' g_i(x) = \left( 1 - \dfrac{f_{i,1}(x)}{f_{i,1}(\mu_{i,1})} \right) -#' f_{i,1}(x) + \dfrac{f_{i,2}(x)^2}{f_{i,2}(\mu_{i,2})} \\ -#' \ \\ -#' \Psi(x) = \Psi_1(x) - \dfrac{\Psi_1(x)^2}{2} + -#' \dfrac{\Psi_2(x)^2}{2} \hspace{9em} \\ -#' \ \\ -#' \Psi_i(x) = \Phi_{i,1}(x) - \dfrac{\Phi^*_{i,1}(x)}{\sqrt{2}} + -#' \dfrac{\Phi^*_{i,2}(x)}{\sqrt{2}} \hspace{3em} \ }} +#' g(x) = \left( 1 - \Psi_1(x)\ \right) g_1(x) + \Psi_2(x) g_2(x), +#' \hspace{6em} \ \ \\ } +#' \deqn{g_i(x) = \left( 1 - \dfrac{f_{i,1}(x)}{f_{i,1}(\mu_{i,1})} \right) +#' f_{i,1}(x) + \dfrac{f_{i,2}(x)^2}{f_{i,2}(\mu_{i,2}),} \\ } +#' \deqn{\Psi(x) = \Psi_1(x) - \dfrac{\Psi_1(x)^2}{2} + +#' \dfrac{\Psi_2(x)^2}{2}, \hspace{9em} \\ } +#' \deqn{\Psi_i(x) = \Phi_{i,1}(x) - \dfrac{\Phi^*_{i,1}(x)}{\sqrt{2}} + +#' \dfrac{\Phi^*_{i,2}(x)}{\sqrt{2}}. \hspace{3em} \ }} #' } #' #' Where \eqn{f_i} is the probability density function of @@ -304,7 +297,7 @@ f.t3.p <- list( function( x, m, s ) #' \eqn{\Phi_i} and \eqn{\Phi_{i,j}} are the cumulative distribution functions of #' \eqn{\mathcal{N}_i} and \eqn{\mathcal{N}_{i,j}}, #' and \eqn{\mu_i} is the mean value of \eqn{\mathcal{N}_i}, -#' and \eqn{\Phi^*_i} and \eqn{\Phi^*_{i,j}} are the cumulative distribution function +#' and then \eqn{\Phi^*_i} and \eqn{\Phi^*_{i,j}} are the cumulative distribution function #' of the normal distributions \eqn{\mathcal{N}(\mu_i, (\sigma_i / \sqrt{2})^2)} and #' \eqn{\mathcal{N}(\mu_{i,j}, (\sigma_{i,j} / \sqrt{2})^2)}, respectively. #' @@ -332,8 +325,8 @@ GGD <- setRefClass( median = "numeric", # The median value of the distribution. mean = "numeric", # The mean of the distribution. sd = "numeric", # The standard deviation of the distribution. - lsd = "numeric", # The semi-standard deviation lower than mean. - usd = "numeric", # The semi-standard deviation upper than mean. + lsd = "numeric", # The half standard deviation lower than the mean. + usd = "numeric", # The half standard deviation upper than the mean. lsd.abs.error = "numeric", # The estimated modulus of the absolute error for lsd. usd.abs.error = "numeric" # The estimated modulus of the absolute error for usd. ) @@ -432,7 +425,7 @@ GGD$methods( adjust.cmp.rownames = function() { # Using direct string vectors instead of rownames( cmp, prefix = "n." ) - # to avoid creating strange names when the number of the cmp rows is invalid. + # to avoid creating strange names when the number of rows of 'cmp' field is invalid. if ( length( mix.type ) == 0 || is.na( mix.type ) ) { rownames( cmp ) <<- c() @@ -593,17 +586,20 @@ GGD$methods( { if ( is.eq.sd() ) { - # Mean-Differed Sigma-Equaled Horizontal-Vertical Gradational Distribution + # Mean-Differed Sigma-Equaled + # Horizontal-Vertical Gradational Distribution index <- 14L } else if ( is.eq.mean() ) { - # Mean-Equaled Sigma-Differed Horizontal-Vertical Gradational Distribution + # Mean-Equaled Sigma-Differed + # Horizontal-Vertical Gradational Distribution index <- 15L } else { - # Mean-Differed Sigma-Differed Horizontal-Vertical Gradational Distribution + # Mean-Differed Sigma-Differed + # Horizontal-Vertical Gradational Distribution index <- 16L } } @@ -641,10 +637,12 @@ GGD$methods( #' #' Gets index numbers which represent the kinds of distributions. #' @export -#' @param objs A vector or a list of elements indicating the kind of distribution. +#' @param objs A vector or a list of elements indicating the kind of +#' distribution model. +#' #' Each element must be a character string of a regular expression pattern #' matching to an element of \code{ggd:::kinds} or an index number of -#' \code{ggd:::kinds}, or a \code{\link[ggd]{GGD}} object, or a \code{NA}. +#' \code{ggd:::kinds}, or a \code{\link[ggd]{GGD}} object, or an \code{NA}. #' #' If a character string is indicated as an element, #' the string matches only one element of \code{ggd:::kinds} of @@ -652,18 +650,15 @@ GGD$methods( #' \code{ggd:::kinds.match.order} which is #' \code{ c(1L, 4L, 2L, 3L, 7L, 5L, 6L, 10L, 8L, 9L, 13L, 11L, 12L, #' 16L, 14L, 15L)}. -#' -#' The order of \code{ggd:::kinds.match.order} is designed, -#' while \code{ggd:::kinds} is ordered by intuitive degrees of freedom, -#' for practical purposes so that \code{"Mean-Differed Sigma-Differed"} -#' model, which has more degrees of freedom than the others of -#' the same type, can be matched first. +#' The order is designed for practical purposes so that +#' the '\code{Mean-Differed Sigma-Differed}' model, +#' which has more degrees of freedom than the others of the same type, +#' can be matched first. #' #' If an element is \code{NA}, \code{NA_integer_} will be returned for it. #' -#' @param undef.err A logical; -#' If \code{TRUE}, an error occur if a not-\code{NA} element of \code{objs} -#' does not match any element of \code{ggd:::kinds}. +#' @param undef.err A logical. If \code{TRUE}, an error occurs if a not-\code{NA} element +#' of \code{objs} does not match any element of \code{ggd:::kinds}. #' If \code{FALSE}, \code{NA_integer_} will be returned for it. #' #' @return The vector of index numbers (integers) which represent the kinds of distributions. @@ -769,21 +764,13 @@ ggd.kind.index <- function( objs, undef.err = FALSE ) #' #' Gets the strings which represent the kinds of distributions. #' @export -#' @param objs A vector or a list of elements indicating the kind of distribution. +#' @param objs A vector or a list of elements indicating the kind of distribution model. #' Each element must be a character string of a regular expression pattern #' matching to an element of \code{ggd:::kinds} or an index number of -#' \code{ggd:::kinds}, or a \code{\link[ggd]{GGD}} object, or a \code{NA}. +#' \code{ggd:::kinds}, or a \code{\link[ggd]{GGD}} object, or an \code{NA}. #' -#' If character strings are indicated, each string matches only one element of -#' \code{ggd:::kinds} of the first element along with the index order of -#' \code{ggd:::kinds.match.order} which is -#' \code{ c(1L, 4L, 2L, 3L, 7L, 5L, 6L, 10L, 8L, 9L, 13L, 11L, 12L, -#' 16L, 14L, 15L)}. -#' -#' The order is designed, while \code{ggd:::kinds} is ordered by -#' intuitive degrees of freedom, for practical purposes so that -#' the \code{"Mean-Differed Sigma-Differed"} model, which has more degrees of -#' freedom than the others of the same type, can be matched first. +#' The matching method follows that of \code{objs} argument of +#' \code{\link[ggd]{ggd.kind.index}}. #' #' @return The vector of character strings which represent the kinds of distributions, #' which are elements of \code{ggd:::kinds}. @@ -823,8 +810,8 @@ ggd.kind <- function( objs ) #' #' Gets the value for \code{mix.type} field of \code{GGD} object which is appropriate to #' given \code{grad} value. -#' If \code{grad = "default"}, the return value will be the value of \code{mix.type} argument -#' or the value appropriate for \code{kind} argument. +#' If \code{grad} is \code{"default"}, the return value will be the value of +#' \code{mix.type} argument or the value appropriate for \code{kind} argument. #' @export #' @param grad A character string indicating the method of gradation. #' @@ -838,12 +825,12 @@ ggd.kind <- function( objs ) #' #' @param kind A character string or a numeric value or a \code{\link[ggd]{GGD}} object #' which indicates the kind of distribution model. +#' The matching method of \code{kind} follows that of +#' \code{objs} argument of \code{\link[ggd]{ggd.kind.index}}. +#' #' This argument works when the length of \code{mix.type} argument #' is \code{0}, and \code{grad} is \code{"default"}. #' -#' The matching method of this argument follows that of elements of -#' the \code{objs} argument of the \code{\link[ggd]{ggd.kind.index}}. -#' #' If \code{NA} is indicated, \code{NA_integer_} will be returned. #' If indicated character string pattern or index number does not match #' to any element of \code{ggd:::kind}, an error will occur. @@ -999,6 +986,7 @@ ggd.ncmp.for <- function( grad = c( "default", "normal", "h", "v", "v2", "v3", " #' Judge if all mean values are equal #' #' Checks if the mean values of all normal distributions of components are equal. +#' The equality is determined by the '\code{==}' operator. #' @name is.eq.mean #' @aliases is.eq.mean #' @aliases \S4method{is.eq.mean}{GGD} @@ -1010,15 +998,13 @@ ggd.ncmp.for <- function( grad = c( "default", "normal", "h", "v", "v2", "v3", " #' a$kind ## Normal Distribution #' a$is.eq.mean() ## TRUE #' -#' a$trace.q( -#' data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), -#' grad = "v2" ) -#' a$kind ## 2-Mean-Differed Sigma-Differed Vertical Gradational Distribution +#' a$set.cmp( data.frame( mean = c( 0, 1e+8 ), sd = rep( 1.5, 2 ) ) ) +#' a$kind ## Mean-Differed Sigma-Equaled Horizontal Gradational Distribution #' a$is.eq.mean() ## FALSE #' #' a <- GGD$new() -#' a$set.cmp( data.frame( mean = rep( 0, 3 ), sd = c( 1.2, 0.5, 1.3 ) ) ) -#' a$kind ## 3-Mean-Equaled Sigma-Differed Vertical Gradational Distribution +#' a$set.cmp( data.frame( mean = rep( 0.5, 2 ), sd = c( 1, 1 + 1e+8 ) ) ) +#' a$kind ## Mean-Equaled Sigma-Differed Horizontal Gradational Distribution #' a$is.eq.mean() ## TRUE ################################################################################################ NULL @@ -1033,6 +1019,7 @@ GGD$methods( #' Judge if all standard deviations are equal #' #' Checks if the standard deviations of all normal distributions of components are equal. +#' The equality is determined by the '\code{==}' operator. #' @name is.eq.sd #' @aliases is.eq.sd #' @aliases is.eq.sigma @@ -1045,22 +1032,15 @@ GGD$methods( #' @examples #' a <- GGD$new() #' a$kind ## Normal Distribution -#' a$is.eq.sd() ## TRUE -#' a$is.eq.sigma() ## TRUE (This method is just a synonym of is.eq.sd) +#' a$is.eq.sd(); a$is.eq.sigma() ## TRUE; TRUE (is.eq.sigma is just a synonym of is.eq.sd) #' -#' a$trace.q( -#' data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), -#' grad = "v2" ) -#' a$kind ## 2-Mean-Differed Sigma-Differed Vertical Gradational Distribution -#' a$is.eq.sd() ## FALSE -#' a$is.eq.sigma() ## FALSE +#' a$set.cmp( data.frame( mean = rep( 0.5, 2 ), sd = c( 1, 1 + 1e+8 ) ) ) +#' a$kind ## Mean-Equaled Sigma-Differed Horizontal Gradational Distribution +#' a$is.eq.sd(); a$is.eq.sigma() ## FALSE; FALSE #' -#' a$trace.q( -#' data.frame( x = c( -0.67, 0, 0.53 ), p = c( 0.25, 0.5, 0.70 ) ), -#' this.mix.type = 2, eq.sd = TRUE ) -#' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) -#' a$is.eq.sd() ## TRUE -#' a$is.eq.sigma() ## TRUE +#' a$set.cmp( data.frame( mean = c( 0, 1e+8 ), sd = rep( 1.5, 2 ) ) ) +#' a$kind ## Mean-Differed Sigma-Equaled Horizontal Gradational Distribution +#' a$is.eq.sd(); a$is.eq.sigma() ## TRUE; TRUE ################################################################################################ NULL GGD$methods( @@ -1086,7 +1066,7 @@ GGD$methods( #' @aliases is.normal #' @aliases \S4method{is.normal}{GGD} #' @usage \S4method{is.normal}{GGD}() -#' @return \code{TRUE} if the object shows a normal distribution, otherwise \code{FALSE}. +#' @return \code{TRUE} if the object represents a normal distribution, otherwise \code{FALSE}. #' @examples #' a <- GGD$new() #' a$is.normal() ## TRUE @@ -1094,10 +1074,8 @@ GGD$methods( #' a$set.cmp( data.frame( mean = c( 0, 0 ), sd = c( 1.1, 1.1 ) ), this.mix.type = 2 ) #' a$is.normal() ## TRUE #' -#' a$trace.q( -#' data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), -#' grad = "v2" ) -#' a$kind; a$cmp +#' a$set.cmp( data.frame( mean = c( 0, 0 ), sd = c( 1.1, 0.9 ) ), grad = "v2" ) +#' a$kind ## 2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution #' a$is.normal() ## FALSE ################################################################################################ NULL @@ -1126,7 +1104,7 @@ GGD$methods( #' If \code{FALSE}, this function also returns \code{TRUE} #' when the model is a normal distribution. #' -#' @return \code{TRUE} if the object shows a kind of horizontal gradational distribution, +#' @return \code{TRUE} if the object represents a kind of horizontal gradational distribution, #' otherwise \code{FALSE}. #' @examples #' a <- GGD$new() @@ -1135,9 +1113,7 @@ GGD$methods( #' a$set.cmp( data.frame( mean = c( 0, 1 ), sd = c( 1.1, 1.2 ) ), this.mix.type = 2 ) #' a$is.h() ## TRUE #' -#' a$trace.q( -#' data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), -#' grad = "v2" ) +#' a$set.cmp( grad = "v2" ) #' a$kind ## 2-Mean-Differed Sigma-Differed Vertical Gradational Distribution #' a$is.h() ## FALSE #' @@ -1189,7 +1165,7 @@ GGD$methods( #' If \code{FALSE}, this function also returns \code{TRUE} when the model #' is a normal distribution. #' -#' @return \code{TRUE} if the object shows a kind of vertical gradation of +#' @return \code{TRUE} if the object represents a kind of vertical gradation of #' 2 normal distributions, otherwise \code{FALSE}. #' @examples #' a <- GGD$new() @@ -1197,10 +1173,7 @@ GGD$methods( #' a$is.v2() ## TRUE #' a$is.v2( TRUE ) ## FALSE #' -#' a$trace.q( -#' data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), -#' grad = "v2" ) -#' a$kind; a$cmp +#' a$set.cmp( data.frame( mean = c( 0, 0 ), sd = c( 1.1, 0.9 ) ), grad = "v2" ) #' a$is.v2( TRUE ) ## TRUE #' #' a$set.cmp( data.frame( mean = c( 0, 0, 0, 0 ), @@ -1251,13 +1224,13 @@ GGD$methods( #' @param strict If \code{TRUE}, this function returns \code{TRUE} only if #' the distribution is a vertical gradation with different left-tail-side and #' right-tail-side components. -#' Even when the \code{cmp} field has 3 rows with \code{mix.type = 3}, +#' Even when \code{cmp} field has 3 rows with \code{mix.type = 3}, #' if the 1st and the 3rd components are the same, it returns \code{FALSE}. #' #' If \code{FALSE}, this function also returns \code{TRUE} for #' a normal distribution or a vertical gradation of 2 normal distributions. #' -#' @return \code{TRUE} if the object shows a kind of vertical gradation of +#' @return \code{TRUE} if the object represents a kind of vertical gradation of #' 3 normal distributions, otherwise \code{FALSE}. #' @examples #' a <- GGD$new() @@ -1265,17 +1238,14 @@ GGD$methods( #' a$is.v3() ## TRUE #' a$is.v3( strict = TRUE ) ## FALSE #' -#' a$trace.q( -#' data.frame( x = c( -1.92, -0.20, 0.21, 1.98 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), -#' grad = "v3" ) -#' a$kind; a$cmp +#' a$set.cmp( data.frame( mean = c( 0, 0, 0 ), sd = c( 1.1, 0.9, 1.2 ) ), grad = "v3" ) #' a$is.v3() ## TRUE #' a$is.v3( strict = TRUE ) ## TRUE #' #' a$set.cmp( data.frame( mean = c( 0, 0, 0, 0 ), #' sd = c( 1.1, 0.8, 1.2, 0.8 ) ), this.mix.type = 4 ) #' a$mix.type ## 4 -#' a$is.v3() ## FALSE -- see "Note!" at Description +#' a$is.v3() ## FALSE -- see 'Note!' at Description ################################################################################################ NULL GGD$methods( @@ -1311,7 +1281,7 @@ GGD$methods( #' a normal distribution, a horizontal gradational distribution #' and a 2-component vertical gradational distribution. #' -#' @return \code{TRUE} if the object shows a kind of horizontal-vertical gradation of +#' @return \code{TRUE} if the object represents a kind of horizontal-vertical gradation of #' 4 (2x2) normal distributions, otherwise \code{FALSE}. #' @examples #' a <- GGD$new() @@ -1360,22 +1330,20 @@ GGD$methods( #' Referring \code{mix.type} and \code{cmp} field, #' checks if the probability density function is symmetric about the mean. #' -#' This function judges that the distribution model is symmetric if either: +#' This method judges that the distribution model is symmetric if either: #' \enumerate{ #' \item a normal distribution. -#' \item a mean of 2 normal distributions or a horizontal gradational distribution, -#' where the standard deviations of the two normal distributions of the components -#' are equal to each other. -#' \item a mean of 2 normal distributions or a vertical gradational distribution -#' of 2 normal distributions, where the mean values of the two normal distributions -#' of the components are equal to each other. -#' \item a vertical gradational distribution of 3 normal distributions, -#' where the mean of the mean values of the 2 tail-side components is equal to -#' the mean value of the top-side component, and the standard deviations of -#' the both tail-side components are equal to each other. -#' \item a horizontal-vertical gradational distribution, -#' where the two vertical gradational distributions of the components are -#' symmetric about the mean of the distribution. +#' \item a mean of 2 normal distributions or a horizontal gradational distribution +#' where the two components have the same standard deviation. +#' \item a mean of 2 normal distributions or a 2-component vertical gradational +#' distribution where the two components have the same mean value. +#' \item a 3-component vertical gradational distribution +#' where the both tail-side components have the same standard deviation, +#' and the mean value of the top-side component equals the mean of the mean values +#' of the both tail-side components. +#' \item a horizontal-vertical gradational distribution which has +#' two vertical gradational distributions in the components +#' which are symmetrical to each other about the mean of the distribution. #' } #' @name is.symmetric #' @aliases is.symmetric @@ -1428,7 +1396,7 @@ GGD$methods( #' Probability density function #' #' Gets the values of the probability density function for the given x-coordinates. -#' This function works like \code{\link[stats]{dnorm}} for a normal distribution. +#' This method works like \code{\link[stats]{dnorm}} for a normal distribution. #' @name d #' @aliases d #' @aliases \S4method{d}{GGD} @@ -1475,7 +1443,8 @@ GGD$methods( { right.tail.index <- ifelse( is.v2( strict = FALSE ), 1, 3 ) result <- dp.t3( x, c( cmp$mean[1], cmp$mean[2], cmp$mean[right.tail.index] ), - c( cmp$sd[1], cmp$sd[2], cmp$sd[right.tail.index] ), f.t3.d ) + c( cmp$sd[1], cmp$sd[2], cmp$sd[right.tail.index] ), + f.t3.d ) } else if ( mix.type == 2 ) { @@ -1506,13 +1475,14 @@ GGD$methods( #' #' Gets the probabilities of that a value of the random variable is less than or equal to #' the given x-coordinates. -#' This function works like \code{\link[stats]{pnorm}} for a normal distribution. +#' This method works like \code{\link[stats]{pnorm}} for a normal distribution. #' @name p #' @aliases p #' @aliases \S4method{p}{GGD} #' @usage \S4method{p}{GGD}(x) #' @param x A vector of x-coordinates. -#' @return The probabilities of that x is less than or equal to given x-coordinates. +#' @return A vector of the probabilities of that a value of the random variable is less than +#' or equal to given x-coordinates. #' @importFrom stats pnorm #' @examples #' a <- GGD$new() @@ -1526,6 +1496,11 @@ NULL GGD$methods( p = function( x ) { + if ( !( length( mix.type ) == 0 || is.na( mix.type ) || any( mix.type == 0:4 ) ) ) + { + stop( "Error: mix.type is invalid." ) + } + results <- vapply( x, function( x ) { if ( length( mix.type ) == 0 || is.na( mix.type ) ) @@ -1558,15 +1533,11 @@ GGD$methods( p2 <- pnorm( x, cmp$mean[2], cmp$sd[2] ) result <- p1 - ( p1 * p1 - p2 * p2 ) / 2 } - else if ( mix.type == 1 ) + else # if ( mix.type == 1 ) { result <- ( pnorm( x, cmp$mean[1], cmp$sd[1] ) + pnorm( x, cmp$mean[2], cmp$sd[2] ) ) / 2 } - else - { - stop( "Error: mix.type is invalid." ) - } return ( result ) }, 0 ) @@ -1578,17 +1549,17 @@ GGD$methods( ################################################################################################ #' Quantile function #' -#' Gets the x-coordinates at which the value of the cumulative distribution function will be -#' equal to the given probabilities. -#' This function works like \code{\link[stats]{qnorm}} for a normal distribution. +#' Gets the x-coordinates with the cumulative distribution function is equal to +#' the given probabilities (with a tolerance level). +#' This method works like \code{\link[stats]{qnorm}} for a normal distribution. #' @name q #' @aliases q #' @aliases \S4method{q}{GGD} #' @usage \S4method{q}{GGD}(prob, tol = .Machine$double.eps * 16) #' @param prob A vector of probabilities. #' @param tol The tolerance level for the convergence criterion. -#' @return The x-coordinates at which the value of the cumulative distribution function -#' will be equal to the given probabilities. +#' @return A vector of the x-coordinates with the cumulative distribution function +#' is equal to the given probabilities in the tolerance level. #' @importFrom stats qnorm #' @examples #' a <- GGD$new() @@ -1767,7 +1738,8 @@ GGD$methods( #' Random generation #' #' Generates random numbers which follow the distribution model. -#' This function works like \code{\link[stats]{rnorm}} for a normal distribution. +#' This method works like \code{\link[stats]{rnorm}} for a normal distribution. +#' This method calls \code{\link[ggd]{q}} method internally. #' @name r #' @aliases r #' @aliases \S4method{r}{GGD} @@ -1791,3 +1763,45 @@ GGD$methods( return ( q( runif( n, 0, 1 ), tol ) ) } ) + +################################################################################################ +#' [Non-exported] PDF/CDF for mix.type = 3 +#' +#' Calculates the values of the probability density function (PDF) or +#' the cumulative distribution function (CDF) of the GGD model with \code{mix.type = 3}. +#' Both \code{means} and \code{sds} vectors need 3 elements for this function. +#' Where with two components, you must set \code{means[3]} and \code{sds[3]} +#' the same values of \code{means[1]} and \code{sds[1]}. +#' @param x A vector of x-coordinates. +#' @param means The vector of mean values of the 3 components. +#' @param sds The vector of sd values of the 3 components. +#' @param f.t3 A function handle; +#' \code{ggd:::f.t3.d} for PDF or \code{ggd:::f.t3.p} for CDF. +#' @return The vector of values of the probability density function +#' or the cumulative distribution function. +################################################################################################ +dp.t3 <- function( x, means, sds, f.t3 ) +{ + results <- vapply( x, function( x ) + { + result <- f.t3[[2]]( x, means[2], sds[2] ) + + if ( x < means[1] ) + { + result <- result + f.t3[[1]]( x, means[1], sds[1] ) + } + else + { + result <- result + f.t3[[3]] + } + + if ( x > means[3] ) + { + result <- result + f.t3[[1]]( x, means[3], sds[3] ) - f.t3[[3]] + } + + return ( result ) + }, 0 ) + + return ( results ) +} diff --git a/R/ggd.apply.R b/R/ggd.apply.R index 09e272c..a579174 100644 --- a/R/ggd.apply.R +++ b/R/ggd.apply.R @@ -12,7 +12,7 @@ ################################################################################################ #' Apply functions to cmp #' -#' Applies a function to each element in the \code{cmp} field. +#' Applies a function to each element in \code{cmp} field. #' Different functions can be applied to \code{mean} column and \code{sd} column. #' Other fields will be adjusted accordingly. #' @name apply.cmp @@ -23,7 +23,7 @@ #' If \code{NULL}, nothing is applied. #' @param f.sd A function to apply to elements in \code{sd} column. #' If \code{NULL}, nothing is applied. -#' See "Details" for more information. +#' See 'Details' for more information. #' @return The processed \code{\link[ggd]{GGD}} object itself (invisible). #' @seealso \code{\link[ggd]{round.cmp}} #' @details @@ -31,18 +31,18 @@ #' 2 arguments (each argument name is arbitrary): #' \enumerate{ #' \item A vector of the current values of \code{mean} or \code{sd} column. -#' \item The \code{\link[ggd]{GGD}} object itself to be processed. +#' \item The \code{\link[ggd]{GGD}} object itself. #' } #' Therefore, the function for \code{f.mean} or \code{f.cmp} is hoped to be -#' declared with 2 arguments like as "\code{function(mean, obj)}", +#' declared with 2 arguments like as '\code{function(mean, obj)}', #' however, if the function do not need the 2nd argument, #' you can declare with 1 arguments -#' like as "\code{function(mean)}" or "\code{function(sd)}". +#' like as '\code{function(mean)}' or '\code{function(sd)}'. #' For the values of the functions, each function must return a numeric vector #' with the same length of the 1st argument as new values of each column. #' #' After both functions have been processed, the new values are actually -#' set into the \code{cmp} field. Therefore, from within the functions to apply, +#' set into \code{cmp} field. Therefore, from within the functions to apply, #' it is possible to refer to the values of each field before applying, #' but not after. #' @@ -58,22 +58,26 @@ #' (e.g., \code{\link[ggd]{adjust.cmp}}, \code{\link[ggd]{round.cmp}}, etc.) #' for the object of the 2nd argument, since they may update the values of the fields. #' -#' This function does not change the number of rows in \code{cmp} field, +#' This method does not change the number of rows in \code{cmp} field, #' no matter what results are obtained. #' @examples #' a <- ggd.set.cmp( data.frame( mean = c( -0.5, 0, 0.5 ), sd = c( 1, 0.8, 1.2 ) ) ) #' a$cmp; c( a$mean, a$sd ) +#' #' ## +1 to mean. #' a$apply.cmp( function( mean ) mean + 1 ) #' a$cmp; c( a$mean, a$sd ) -#' ## double sd of 2nd component. +#' +#' ## Double sd of 2nd component. #' a$apply.cmp( f.sd = function( sd ) { sd[2] <- sd[2] * 2; sd } ) #' a$cmp; c( a$mean, a$sd ) -#' ## rotate as index+1 for mean and index-1 for sd. +#' +#' ## Rotate as index+1 for mean and index-1 for sd. #' a$apply.cmp( f.mean = function( mean ) mean[c( 2, 3, 1 )], #' f.sd = function( sd ) sd[c( 3, 1, 2 )] ) #' a$cmp; c( a$mean, a$sd ) -#' ## swap mean and sd. +#' +#' ## Swap mean and sd. #' a$apply.cmp( f.mean = function( m, obj ) obj$cmp$sd, #' f.sd = function( s, obj ) obj$cmp$mean ) #' a$cmp; c( a$mean, a$sd ) @@ -103,7 +107,7 @@ GGD$methods( ################################################################################################ #' [Non-exported] Call applying function #' -#' Calls a applying function to get new values of a column of \code{cmp} field. +#' Calls an applying function to get new values of a column of \code{cmp} field. #' @param f A function to apply to elements in a column of \code{cmp} field. #' @param values A vector of current values of the column of \code{cmp} field. #' @param obj The \code{\link[ggd]{GGD}} object which calls this function. @@ -139,12 +143,12 @@ apply.cmp.sub <- function( f, values, obj ) ################################################################################################ #' Rounding values in cmp #' -#' Rounds the values of all elements in the \code{cmp} field and adjusts other fields +#' Rounds the values of all elements in \code{cmp} field and adjusts other fields #' accordingly. #' \code{\link[base]{round}} and \code{\link[base]{signif}} functions can apply. -#' These functions does not change the number of rows in \code{cmp} field, +#' These functions do not change the number of rows in \code{cmp} field, #' no matter what results are obtained. -#' If an error occurs, these functions do not clear the object, but retains the values of +#' If an error occurs, these functions do not clear the object, but retain the values of #' all fields. #' @name round.cmp #' @aliases round.cmp @@ -165,7 +169,7 @@ apply.cmp.sub <- function( f, values, obj ) #' If the length is \code{0} (including \code{NULL}), #' standard deviations will not be rounded. #' See \code{\link[base]{round}} for more information. -#' @return The processed \code{\link[ggd]{GGD}} object itself. +#' @return The processed \code{\link[ggd]{GGD}} object itself (invisible). #' @seealso \code{\link[ggd]{apply.cmp}}, \code{\link[base]{round}} #' @examples #' a <- ggd.set.cmp( data.frame( mean = c( 112.7865, 113.1647 ), @@ -219,7 +223,7 @@ GGD$methods( #' @param dg.mean A vector of integer for the 1st argument of \code{math2.f} #' to be used for \code{mean} column. #' @param dg.sd A vector of integer similar to \code{dg.mean}, for \code{sd} column. -#' @param obj The \code{\link[ggd]{GGD}} object to be processed. +#' @param obj The \code{\link[ggd]{GGD}} object. #' @return A processed \code{\link[ggd]{GGD}} object. #' @seealso \code{\link[ggd]{round.cmp}} ################################################################################################ diff --git a/R/ggd.file.R b/R/ggd.file.R index 03dc804..dd2da45 100644 --- a/R/ggd.file.R +++ b/R/ggd.file.R @@ -12,8 +12,9 @@ ################################################################################################ #' Read a composition #' -#' Reads a CSV file recorded the composition of a \code{\link[ggd]{GGD}} object -#' and generates a \code{\link[ggd]{GGD}} object. +#' Reads a CSV file recorded the composition of a \code{\link[ggd]{GGD}} object. +#' Then \code{ggd.read.csv} function generates a \code{\link[ggd]{GGD}} object, +#' and \code{read.csv} method sets the fields according to the composition. #' @export #' @name read.csv #' @aliases ggd.read.csv @@ -21,21 +22,19 @@ #' @aliases \S4method{read.csv}{GGD} #' @usage ggd.read.csv(file) #' @usage \S4method{read.csv}{GGD}(file) -#' @param file The name of the CSV file which the composition of -#' a \code{\link[ggd]{GGD}} object is to be read from. -#' The \code{file} can be a readable text-mode \link[base]{connection}. +#' @param file The name of the CSV file. +#' The \code{file} can be a readable text-mode \link[base]{connection}. #' -#' The \code{file} must have a header consisting of -#' the value of \code{mix.type}, the character string of "mean" -#' and the character string of "sd". -#' The order of each column is not interchangeable. -#' The second and subsequent rows should be the name of the row -#' (such as \code{"nd.1"}, but not be cared) -#' and the mean value and standard deviation of the each components -#' of the \code{cmp} field. +#' The \code{file} should be a CSV file with 3 columns. +#' The columns are 1:row header, 2:mean value, and 3:standard deviation +#' of the component. The columns cannot be reordered. +#' The \code{file} must have a header row consisting of the value of +#' \code{mix.type}, the character string of \code{"mean"}, and \code{"sd"}. +#' The second and subsequent rows should have the row name (such as \code{"nd.1"}), +#' the mean value, and standard deviation of each component. #' -#' For more information about the properties of this argument, -#' see \code{file} argument of \link[utils]{read.table}. +#' For more information about the properties of this argument, +#' see \code{file} argument of \link[utils]{read.table}. #' #' @return The generated \code{\link[ggd]{GGD}} object (invisible for \code{GGD} method). #' @@ -45,18 +44,17 @@ #' #' @details #' \subsection{Reading empty data}{ -#' If the read file is one which is written with a cleared object, -#' \code{kind}/\code{kind.index} and \code{mix.type} fields of the generated object +#' If the file contains a cleared object (a file with only the header row), +#' the values of \code{kind}, \code{kind.index}, and \code{mix.type} fields #' will be \code{NA}, -#' and \code{median} and \code{mean} and other numeric fields will be \code{NaN}. +#' and then \code{median}, \code{mean}, and other numeric fields will be \code{NaN}. #' } #' \subsection{Illegal format file}{ -#' If the format of the read file was illegal and a \code{\link[ggd]{GGD}} object cannot +#' If the format of the file was illegal and a \code{\link[ggd]{GGD}} object cannot #' be constructed, an error occurs and the \code{\link[ggd]{GGD}} object is cleared. #' -#' If the \code{mix.type} value stored in a file does not match the values for \code{cmp}, -#' an error may occur, or it may happen to work. It is possible to create such a file -#' using \code{ggd:::}\code{\link[ggd]{cat.table}} function which is non-exported. +#' If \code{mix.type} value stored in the file does not match the values for \code{cmp}, +#' an error may occur, or it may happen to work. #' However, it is not recommended to create such a non-conforming file anyway. #' } #' @importFrom utils read.csv @@ -135,13 +133,8 @@ GGD$methods( #' Write the composition #' #' Writes the composition of a \code{\link[ggd]{GGD}} object as a CSV file. -#' Mean values and standard deviations of the components are recorded to a maximum length of -#' the 22nd decimal place. -#' The accuracy is sufficient to reconstruct the original object almost completely -#' (at least the value of each field can be \code{TRUE} with \code{"=="}) -#' in most cases, in most systems. -#' So, this function provides a simple way to export a \code{\link[ggd]{GGD}} object, -#' regardless of the package or R version. +#' This function provides a simple way to export a \code{\link[ggd]{GGD}} object, +#' regardless of the package version or R version. #' @export #' @name write.csv #' @aliases ggd.write.csv @@ -150,10 +143,20 @@ GGD$methods( #' @usage ggd.write.csv(obj, file = "") #' @usage \S4method{write.csv}{GGD}(file = "") #' @param obj The \code{\link[ggd]{GGD}} object to be saved. -#' @param file The name of the file or a \link[base]{connection} for writing -#' the composition of the object. \code{""} indicates output to the console. +#' @param file The name of the file or a \link[base]{connection} open for writing. +#' \code{""} indicates output to the console. #' @return An invisible NULL. #' @seealso \code{\link[ggd]{read.csv}} +#' +#' @details +#' \subsection{Accuracy of saved data}{ +#' Mean values and standard deviations are recorded to a maximum length of +#' the 22nd decimal place. +#' The accuracy is sufficient to reconstruct the original object almost completely +#' (at least the value of each field can be \code{TRUE} with '\code{==}') +#' in most cases, and in most systems. +#' } +#' #' @importFrom utils read.csv #' @examples #' a <- ggd.set.cmp( data.frame( mean = c( 0.223, 0.219 ), sd = c( 2.265, 2.176 ) ), diff --git a/R/ggd.mean.sd.R b/R/ggd.mean.sd.R index 3385315..1dd7d50 100644 --- a/R/ggd.mean.sd.R +++ b/R/ggd.mean.sd.R @@ -12,15 +12,20 @@ ################################################################################################ #' [Non-exported] Mean calculation #' -#' Calculates the mean value of a GGD model. -#' This function does not use \code{\link[stats]{integrate}}, but \code{\link[stats]{pnorm}}, -#' \code{\link[base]{sqrt}} and four arithmetic operations as needed. -#' @param mix.type The value of \code{mix.type}. +#' Calculates the mean value of the distribution model. +#' +#' This function does not use \code{\link[stats]{integrate}} or other tolerance-requiring +#' processes. Therefore, the calculation speed and accuracy will be expected in some degree. +#' However, since \code{\link[base]{sqrt}(pi)} is used where \code{mix.type} is \code{2} +#' or greater, and \code{\link[stats]{pnorm}} is also used where \code{mix_type = 4}, +#' it is expected that there will be calculation errors due to their implementation, +#' in addition to digit losses during arithmetic operations. +#' @param mix.type The value of \code{mix.type}. It allows from \code{1} to \code{4}. #' @param means The vector of the mean values of the normal distributions #' of the components. #' @param sds The vector of the standard deviations of the normal distributions #' of the components. -#' @return The mean value of a gradational Gaussian distribution model. +#' @return The mean value of the distribution model. ################################################################################################ calc.mean <- function( mix.type, means, sds ) { @@ -59,9 +64,9 @@ calc.mean <- function( mix.type, means, sds ) } ################################################################################################ -#' [Non-exported] Sub-function of the mean calculation for mix.type = 4 +#' [Non-exported] Sub-function for mean calculation where mix.type = 4 #' -#' A sub-function which is used for calculating the mean value where \code{mix.type = 4}. +#' A sub-function of \code{\link[ggd]{calc.mean}} where \code{mix.type = 4}. #' It calculates \eqn{\int_{-\infty}^{\infty} x \Psi_i(x) g_i(x) dx}, #' where #' \eqn{\Psi_i(x) = \Phi_{i,1}(x) - \dfrac{1}{\sqrt{2}} \Phi_{i,1}^*(x) + @@ -69,8 +74,12 @@ calc.mean <- function( mix.type, means, sds ) #' \eqn{g_i(x) = ( 1 - f_{i,1}(x) / f_{i,1}(\mu_{i,1}) ) f_{i,1}(x) + #' f_{i,2}(x)^2 / f_{i,2}(\mu_{i,2})} #' \eqn{( i = 1, 2 )}. -#' This function does not use \code{\link[stats]{integrate}}, -#' but \code{\link[stats]{pnorm}}, \code{\link[base]{sqrt}} and four arithmetic operations. +#' +#' This function does not use \code{\link[stats]{integrate}} or other tolerance-requiring +#' processes. Therefore, the calculation speed and accuracy will be expected in some degree. +#' However, since \code{\link[stats]{pnorm}} and \code{\link[base]{sqrt}(pi)} are used, +#' it is expected that there will be calculation errors due to their implementation, +#' in addition to digit losses during arithmetic operations. #' @param means The mean values of two normal distributions #' \eqn{\mathcal{N}_{i,1}, \mathcal{N}_{i,2}}. #' @param sds The standard deviations of two normal distributions @@ -96,21 +105,25 @@ calc.mean.t4.sub <- function( means, sds ) ################################################################################################ #' [Non-exported] Variance calculation #' -#' Calculates the variance or the half variance of a GGD model. -#' This function does not use \code{\link[stats]{integrate}}, -#' but \code{\link[stats]{dnorm}}, \code{\link[stats]{pnorm}}, \code{\link[base]{sqrt}} -#' and four arithmetic operations. +#' Calculates the whole or half variance of the distribution model. +#' +#' This function does not use \code{\link[stats]{integrate}} or other tolerance-requiring +#' processes. Therefore, the calculation speed and accuracy will be expected in some degree. +#' However, since \code{\link[stats]{dnorm}}, \code{\link[stats]{pnorm}} and +#' \code{\link[base]{sqrt}(pi)} are used where \code{mix.type} is \code{2} or greater, +#' it is expected that there will be calculation errors due to their implementation, +#' in addition to digit losses during arithmetic operations. #' #' For \code{mix.type = 4}, the half variance option of #' \code{get.lv = TRUE} or \code{get.uv = TRUE} does not work. The reason is how to calculate #' \eqn{\int_{-\infty}^{\mu} f_{i,1}(x) \Phi_{i,2}(x) dx} without numerical integral function #' is still unknown for us. -#' @param mix.type The value of \code{mix.type} of the \code{\link[ggd]{GGD}} class. +#' @param mix.type The value of \code{mix.type}. It allows from \code{1} to \code{4}. #' @param means The mean values of the normal distributions of the components. #' @param sds The standard deviations of the normal distributions of the components. -#' @param mean The mean of the whole distribution. +#' @param mean The mean of the distribution model. #' @param symmetric If \code{TRUE}, the distribution model is treated as symmetric. -#' This option may help reduce calculation errors. +#' This option may help to reduce calculation errors. #' @param get.lv If \code{TRUE}, this function calculates the lower half variance. #' @param get.uv If \code{TRUE}, this function calculates the upper half variance. #' @@ -118,7 +131,7 @@ calc.mean.t4.sub <- function( means, sds ) #' if both are \code{TRUE}, \code{get.lv} takes priority. #' If both are \code{FALSE} (the default), #' this function calculates the whole variance. -#' @return The value of the whole/half variance. +#' @return The value of the whole or half variance of the distribution model. #' @importFrom stats dnorm pnorm ################################################################################################ calc.v <- function( mix.type, means, sds, @@ -163,7 +176,8 @@ calc.v <- function( mix.type, means, sds, v.half <- ( sds[1]^2 * p[1] + sds[2]^2 * p[2] + ( means[1] - means[2] )^2 * ( p[1] + p[2] ) / 4 - - ( means[1] - means[2] ) * ( sds[1]^2 * d[1] - sds[2]^2 * d[2] ) / 2 ) / 2 + ( means[1] - means[2] ) * + ( sds[1]^2 * d[1] - sds[2]^2 * d[2] ) / 2 ) / 2 if ( get.lv ) { @@ -257,12 +271,12 @@ calc.v <- function( mix.type, means, sds, { if ( get.lv ) { - v <- calc.v.sub( 3, mean, means[1], sds[1], min( mean, means[1] ), k = 1 ) + - calc.v.sub( 3, mean, means[2], sds[2], mean, k = 2 ) + v <- calc.v.sub( 3, mean, means[1], sds[1], min( mean, means[1] ), i = 1 ) + + calc.v.sub( 3, mean, means[2], sds[2], mean, i = 2 ) if ( means[3] < mean ) { - v <- v + calc.v.sub( 3, mean, means[3], sds[3], mean, k = 3 ) - + v <- v + calc.v.sub( 3, mean, means[3], sds[3], mean, i = 3 ) - ( means[3] - mean )^2 * ( 2 - sqrt( 2 ) ) / 4 + ( means[3] - mean ) * sds[3] * sqrt( 2 ) / sqrt( pi ) / 2 - sds[3]^2 * ( 4 - sqrt( 2 ) ) / 8 @@ -272,14 +286,14 @@ calc.v <- function( mix.type, means, sds, { v <- ( means[2] - mean )^2 * sqrt( 2 ) / 2 + sds[2]^2 * sqrt( 2 ) / 4 - - calc.v.sub( 3, mean, means[2], sds[2], mean, k = 2 ) + + calc.v.sub( 3, mean, means[2], sds[2], mean, i = 2 ) + ( means[3] - mean )^2 * ( 2 - sqrt( 2 ) ) / 2 + sds[3]^2 * ( 4 - sqrt( 2 ) ) / 4 - - calc.v.sub( 3, mean, means[3], sds[3], max( mean, means[3] ), k = 3 ) + calc.v.sub( 3, mean, means[3], sds[3], max( mean, means[3] ), i = 3 ) if ( mean < means[1] ) { - v <- v - calc.v.sub( 3, mean, means[1], sds[1], mean, k = 1 ) + + v <- v - calc.v.sub( 3, mean, means[1], sds[1], mean, i = 1 ) + ( means[1] - mean )^2 * ( 2 - sqrt( 2 ) ) / 4 - ( means[1] - mean ) * sds[1] * sqrt( 2 ) / sqrt( pi ) / 2 + sds[1]^2 * ( 4 - sqrt( 2 ) ) / 8 @@ -316,35 +330,40 @@ calc.v <- function( mix.type, means, sds, } ################################################################################################ -#' [Non-exported] Sub-functions for variance calculation for mix.type = 2, 3 +#' [Non-exported] Sub-function for variance calculation where mix.type = 2, 3 #' -#' A sub-function for calculating the variance of a GGD model. -#' The meaning of this function is depend on \code{mix.type} (see "Details"). -#' This function dose not use \code{\link[stats]{integrate}}. -#' @param mix.type The value which represent the way to mix the normal distributions. -#' @param mean The mean of the whole distribution. -#' @param mean.i The mean value of the normal distribution of i-th component. -#' @param sd.i The standard deviation of the normal distribution of i-th component. -#' @param x The upper limit of the integral interval (see formulas in "Details"). +#' A sub-function of \code{\link[ggd]{calc.v}} where \code{mix.type} is \code{2} or \code{3}. +#' The meaning of this function is depend on \code{mix.type} (see 'Details'). +#' @param mix.type The value of \code{mix.type}. It allows \code{2} or \code{3}. +#' @param mean The mean of the distribution model. +#' @param mean.i The mean value of the i-th normal distribution of the component. +#' @param sd.i The standard deviation of the i-th normal distribution of the component. +#' @param x The upper limit of the integral interval (see formulas in 'Details'). #' @param p.sum The sum of the probabilities of two normal distributions of -#' the components. This argument is for \code{mix.type = 2}. -#' @param k The number indicating the normal distribution in the components. +#' the components at \code{x = q}; the lower or upper limit of the domain +#' of the distribution. +#' This argument is for \code{mix.type = 2}. +#' @param i The number indicating which component is operated. #' This argument is for \code{mix.type = 3}. #' @details -#' Depending on the value of mix.type, the following calculations are performed without +#' Depending on the value of \code{mix.type}, the following calculations are performed without #' \code{\link[stats]{integrate}} but with \code{\link[stats]{dnorm}}, #' \code{\link[stats]{pnorm}}, \code{\link[base]{sqrt}} and four arithmetic operations, #' respectively. #' The variance will be expressed with the sums and differences of the outputs of this function -#' and sums or products with some simple terms. +#' and some simple terms. #' #' In the following expressions, -#' \eqn{\mu} is the mean of the whole distribution, +#' \eqn{\mu} is the mean of the distribution model, #' \eqn{f_i(x)} is the probability density function of the normal distribution #' \eqn{\mathcal{N}(\mu_i, \sigma_i^2)}, #' \eqn{\Phi_i(x)} is the cumulative distribution function of #' \eqn{\mathcal{N}(\mu_i, \sigma_i^2)}, and \eqn{\bar \Phi(x)} is the mean of #' two cumulative distribution functions \eqn{\Phi_1(x)} and \eqn{\Phi_2(x)}. +#' The value of \eqn{q} at the expression for \code{mix.type = 2} is the lower or upper limit +#' of the domain of the distribution. +#' In this package, since the domain is over \eqn{(-\infty, \infty)}, +#' \eqn{q = -\infty} or \eqn{\infty}. #' #' \describe{ #' \item{mix.type = 2}{ @@ -352,18 +371,26 @@ calc.v <- function( mix.type, means, sds, #' \int_{-\infty}^x (t - \mu)^2 (\Phi_i(t) - \bar \Phi(q)) f_i(t) \ dt}} #' #' \item{mix.type = 3}{ -#' \deqn{k = 1, 3 \ : -#' \ \displaystyle +#' \deqn{i = 1, 3: \ +#' \displaystyle #' \int_{-\infty}^x (t - \mu)^2 (1 - \dfrac{f_i(t)}{f_i(\mu_i)}) f_i(t) \ dt} #' -#' \deqn{k = 2 \ : -#' \ \displaystyle -#' \int_{-\infty}^x (t - \mu)^2 \dfrac{f_i(t)^2}{f_i(\mu_i)} f_i(t) \ dt}} +#' \deqn{i = 2: \quad \ +#' \displaystyle +#' \int_{-\infty}^x (t - \mu)^2 \dfrac{f_i(t)^2}{f_i(\mu_i)} f_i(t) \ dt +#' \qquad \ \ }} #' } -#' @return Calculated value of the expression shown in "Details". +#' +#' This function does not use \code{\link[stats]{integrate}} or other tolerance-requiring +#' processes. Therefore, the calculation speed and accuracy will be expected in some degree. +#' However, since \code{\link[stats]{dnorm}}, \code{\link[stats]{pnorm}} and +#' \code{\link[base]{sqrt}(pi)} are used, it is expected that there will be calculation errors +#' due to their implementation, in addition to digit losses during arithmetic operations. +#' +#' @return Calculated value of the expression shown in 'Details'. #' @importFrom stats dnorm pnorm ################################################################################################ -calc.v.sub <- function( mix.type, mean, mean.i, sd.i, x, p.sum = 0, k = 0 ) +calc.v.sub <- function( mix.type, mean, mean.i, sd.i, x, p.sum = 0, i = 0 ) { v <- numeric() d.i <- dnorm( x, mean.i, sd.i ) @@ -392,7 +419,7 @@ calc.v.sub <- function( mix.type, mean, mean.i, sd.i, x, p.sum = 0, k = 0 ) mean * ( 2 * mean.i * pstar.i - sd.i^2 * dstar.i ) + mean^2 * pstar.i ) * sqrt( 2 ) / 2 - if ( k == 1 || k == 3 ) + if ( i == 1 || i == 3 ) { v <- ( mean.i^2 + sd.i^2 ) * p.i - ( x + mean.i ) * sd.i^2 * d.i - @@ -405,17 +432,23 @@ calc.v.sub <- function( mix.type, mean, mean.i, sd.i, x, p.sum = 0, k = 0 ) } ################################################################################################ -#' [Non-exported] A sub-function for variance calculation for mix.type = 4 +#' [Non-exported] Sub-function for variance calculation where mix.type = 4 #' -#' A sub-function for calculating the variance of a GGD model where \code{mix.type = 4}. +#' A sub-function of \code{\link[ggd]{calc.v}} where \code{mix.type = 4}. #' This function calculates \eqn{\int_{-\infty}^{\infty} x^2 \Psi_i(x) g_i(x) dx}, #' where #' \eqn{\Psi_i(x) = \Phi_{i,1}(x) - \dfrac{1}{\sqrt{2}} \Phi_{i,1}^*(x) + #' \dfrac{1}{\sqrt{2}} \Phi_{i,2}^*(x)}, #' \eqn{g_i(x) = ( 1 - f_{i,1}(x) / f_{i,1}(\mu_{i,1}) ) f_{i,1}(x) + #' f_{i,2}(x)^2 / f_{i,2}(\mu_{i,2})} -#' with fixing \eqn{i}. This function does not use \code{\link[stats]{integrate}}, -#' but \code{\link[stats]{pnorm}}, \code{\link[base]{sqrt}} and four arithmetic operations. +#' \eqn{( i = 1, 2 )}. +#' +#' +#' This function does not use \code{\link[stats]{integrate}} or other tolerance-requiring +#' processes. Therefore, the calculation speed and accuracy will be expected in some degree. +#' However, since \code{\link[stats]{dnorm}}, \code{\link[stats]{pnorm}} and +#' \code{\link[base]{sqrt}(pi)} are used, it is expected that there will be calculation errors +#' due to their implementation, in addition to digit losses during arithmetic operations. #' @param means The mean values of the normal distributions #' \eqn{\mathcal{N}_{i,1}} and \eqn{\mathcal{N}_{i,2}}. #' @param sds The standard deviations of the normal distributions @@ -443,22 +476,22 @@ calc.v.sub.t4 <- function( means, sds ) } ################################################################################################ -#' [Non-exported] Half variance computation for mix.type = 4 +#' [Non-exported] Half variance computation where mix.type = 4 #' -#' Using \code{\link[stats]{integrate}}, -#' computes the lower/upper half variance for \code{mix.type = 4}. -#' Computing the whole variance with \code{\link[stats]{integrate}} is also enabled. +#' Using \code{\link[stats]{integrate}}, computes the lower or upper half variance +#' of the distribution model where \code{mix.type = 4}. +#' This function can also compute the whole variance using \code{\link[stats]{integrate}}. #' @param means The mean values of the normal distributions of the components. #' @param sds The standard deviations of the normal distributions of the components. -#' @param mean The mean of the whole distribution. +#' @param mean The mean of the distribution model. #' @param get.lv If \code{TRUE}, computes the lower half variance. #' @param get.uv If \code{TRUE}, computes the upper half variance. #' Although it is not recommended to set #' both \code{get.lv} and \code{get.uv} to \code{TRUE}, -#' if both are \code{TRUE}, get.lv takes priority. +#' if both are \code{TRUE}, \code{get.lv} takes priority. #' If both are \code{FALSE}, computes the whole variance. #' @return A list of the output of \code{\link[stats]{integrate}} -#' as the result of the half/whole variance computation. +#' as the result of the half or whole variance computation. #' @importFrom stats dnorm pnorm integrate ################################################################################################ calc.v.t4.via.integrate <- function( means, sds, mean = calc.mean( 4, means, sds ), @@ -499,11 +532,11 @@ calc.v.t4.via.integrate <- function( means, sds, mean = calc.mean( 4, means, sds } ################################################################################################ -#' Adjust median, mean and sd fields +#' Adjust median, mean, and sd fields #' -#' Calculates the median, the mean and the standard deviation of the distribution model and -#' sets those values into the fields. -#' Before calling this method, you must set \code{cmp} field and \code{mix.type} field. +#' Calculates the median, the mean, and the standard deviation of the distribution model and +#' then sets those values into the fields. +#' Before calling this method, you must set \code{cmp} and \code{mix.type} fields. #' Normally, users of this class don't need to call this method directly. #' @name adjust.median.mean.sd #' @aliases adjust.median.mean.sd diff --git a/R/ggd.nls.freq.R b/R/ggd.nls.freq.R index 384614b..91835cc 100644 --- a/R/ggd.nls.freq.R +++ b/R/ggd.nls.freq.R @@ -14,8 +14,11 @@ #' #' With the non-linear least squares (\code{\link[stats]{nls}}), #' constructs a \code{\link[ggd]{GGD}} object which (locally) most closely approximates -#' the given frequency distribution. "Locally" means that if the start value is modified, -#' more closely approximating model may be generated. +#' the given frequency distribution. +#' Then \code{ggd.nls.freq} function generates a \code{\link[ggd]{GGD}} object, +#' and \code{nls.freq} method sets the fields according to the result. +#' 'Locally' means that if the start value is modified, more closely approximating model +#' may be constructed. #' The outliers of the frequency distribution will not be excluded in this function. #' If necessary, outliers should be excluded by preprocessing. #' @export @@ -40,22 +43,21 @@ #' It must contain at least 2 numeric columns for \code{x} and \code{freq}. #' #' Column \bold{\code{x}} is for the x-coordinates. -#' Each value expected to be a numeric value which represents the cell of -#' the frequency distribution, the x-coordinate at the center of a cell -#' of the frequency distribution. +#' Each value is expected to be a numeric value which represents a cell of +#' the frequency distribution +#' as the x-coordinate at the center of the cell. #' The values must be arranged in ascending order, and not be duplicated. #' #' Column \bold{\code{freq}} is for the frequencies following \code{x}. -#' The values of frequencies must be positive. +#' The values of frequencies should not be negative. #' Both integers and real numbers are allowed for the values. #' #' Rows which contain \code{NA} or \code{NaN} for \code{x} or \code{freq} -#' are ignored. The number of rows should be large enough; -#' it is recommended that there are more than 8 valid rows. -#' At least, 3 valid rows must be contained. +#' are ignored. For fine approximation, the number of rows should be +#' large enough; it is recommended that there are more than 8 valid rows. #' #' Column names and column numbers for \code{x} and \code{freq} -#' are flexible. You can specify them with next two arguments. +#' are flexible. You can indicate them with next two arguments. #' #' @param x The column name or column number for x-coordinates in \code{data}. #' @@ -69,37 +71,18 @@ #' is used for it. #' #' @param kind A character string or a numeric value or a \code{\link[ggd]{GGD}} object -#' which indicates the kind of distribution model for approximating -#' the frequency distribution. -#' -#' The matching method of this argument follows that of elements of -#' the \code{objs} argument of the \code{\link[ggd]{ggd.kind.index}}. +#' which indicates the kind of distribution model to be generated. +#' The matching method of \code{kind} follows that of +#' \code{objs} argument of \code{\link[ggd]{ggd.kind.index}}. #' #' This argument gives the conditions of #' the value of \code{mix.type} field, -#' and of whether the mean values and standard deviations of the components -#' should be aligned to the same value. -#' -#' Indicating \code{mix.type} argument or -#' indicating other than \code{"default"} for \code{grad} argument -#' or \code{TRUE}/\code{FALSE} for \code{eq.mean} or \code{eq.sd} -#' can overwrite the conditions of this argument. -#' -#' @param this.kind A string or a numeric value or a \code{\link[ggd]{GGD}} object -#' which indicates the kind of distribution model for approximating -#' the frequency distribution. +#' and of whether the mean values or standard deviations of the components +#' should be aligned to the same value or not. #' -#' This argument will work as same as \code{kind} argument -#' of the generator function (signature '\code{NULL}'). -#' -#' When this method is called without \code{this.kind} argument -#' or other conditions, it attempt to retain the value of -#' \code{mix.type} field as much as possible, but not the value of -#' \code{kind} field, i.e., the condition whether the mean value or -#' standard deviation of each component is aligned may not be retained. -#' If you want to retain these conditions as well, -#' indicate the object itself to \code{this.kind} argument like as -#' \code{obj$nls.freq(data, this.kind = obj)}. +#' Indicating \code{mix.type} or \code{grad} other than \code{"default"}, +#' or \code{eq.mean} and \code{eq.sd} other than \code{logical(0)} +#' can overwrite the condition of this argument. #' #' @param mix.type A numeric value to set into \code{mix.type} field of #' the \code{\link[ggd]{GGD}} object as an integer. @@ -110,26 +93,18 @@ #' \item 0: Normal distribution. #' \item 1: Mean of 2 normal distributions. #' \item 2: Horizontal gradation of 2 normal distributions. -#' \item 3: Vertical gradation of 2 or 3 normal distributions. -#' The 2-component model has priority. +#' \item 3: Vertical gradation of 2 (or 3) normal distributions. #' \item 4: Horizontal-Vertical gradation #' with 4 (2x2) normal distributions. #' } #' +#' Where \code{mix.type = 3} is indicated, +#' \code{ggd.nls.freq} function generates a 2-component model. +#' If you want to generate a 3-component model, use \code{grad = "v3"}. +#' #' If other than \code{"default"} for \code{grad} argument is indicated, #' this argument will be ignored. #' -#' @param this.mix.type A numeric value to set into \code{mix.type} field as an integer. -#' This argument will work as same as \code{mix.type} of -#' the generator function (signature '\code{NULL}'). -#' -#' If both of \code{this.kind} and \code{this.mix.type} are not given -#' and \code{grad} argument is \code{"default"}, -#' the current value of \code{mix.type} field will be retained, -#' and number of components will also. -#' But furthermore, the object has been cleared, -#' the \code{mix.type} field will be set to \code{2}, the initial value. -#' #' @param grad A character string indicating the method of gradation. #' #' \code{"h"} for horizontal, \code{"v"} for vertical, @@ -149,8 +124,8 @@ #' are forced to be equal. #' #' If \code{FALSE} or \code{logical(0)}, -#' the mean values of the components can be different to each other, -#' and may be equal in very rare cases. +#' the mean values are not bound, +#' and mean-equaled components will be rarely constructed. #' #' \code{TRUE} and \code{FALSE} can overwrite the condition indicated by #' \code{kind} or \code{this.kind} argument. @@ -159,62 +134,64 @@ #' the components are forced to be equal. #' #' If \code{FALSE} or \code{logical(0)}, -#' the standard deviation of the components can be different to -#' each other, and may be equal in very rare cases. +#' the standard deviations are not bound, +#' and sigma-equaled components will be rarely constructed. #' #' If both \code{eq.mean} and \code{eq.sd} are \code{TRUE}, -#' a normal distribution will be generated. +#' a normal distribution will be constructed. #' #' \code{TRUE} and \code{FALSE} can overwrite the condition indicated by #' \code{kind} or \code{this.kind} argument. #' #' @param start.level A numeric value of integer in from \code{0} to \code{3} or \code{100} -#' with default \code{100}; the level at which to guess the initial -#' \code{start} parameters of \code{\link[stats]{nls}}. +#' with default \code{100}; the level of initial guessing +#' for \code{start} argument of \code{\link[stats]{nls}}. #' -#' Details for each level are as: +#' The detail of each level is: #' \itemize{ #' \item \code{0}: #' The mean and the standard deviation of the frequency distribution -#' are used as initial values. +#' are used as the start values. #' \item \code{1}: -#' In addition to level \code{0}, if it is likely to be better guess, -#' it computes the mean values or standard deviations in ranges of -#' local x-coordinates where the effect of each of components is likely -#' to be heavy, and uses them as initial values. +#' In addition to level \code{0}, it computes the local mean values +#' and local standard deviations of the frequency distribution +#' in ranges of x-coordinates where the effect of each of components is +#' likely to be heavy, and uses them for guessing the start values +#' if they are likely to be better guesses. #' \item \code{2}: -#' In addition to level \code{0}, if it is likely to be better guess, -#' it uses the mean values or standard deviations of normal distributions -#' tracing two of quantiles which are generated with -#' the frequency distribution as initial values. +#' In addition to level \code{0}, at first it computes some quantiles +#' from the frequency distribution, then it finds normal distributions +#' tracing two of the quantiles, and uses the mean values and +#' standard deviations of them for guessing the start values +#' if they are likely to be better guesses. #' \item \code{3}: -#' It uses the mean values and standard deviations of the components -#' of a \code{\link[ggd]{GGD}} object tracing some (2, 3 or 5) quantiles -#' which are generated with the frequency distribution as initial values. -#' If tracing fails, level \code{2} is used instead. +#' It generates a \code{\link[ggd]{GGD}} object tracing +#' some (2, 3 or 5) quantiles computed from the frequency distribution, +#' and uses the mean values and standard deviations of the components +#' of the object as the start values. +#' If the generating fails, level \code{2} is used instead. #' \item \code{100}: -#' Try all of above levels and adopt the result with the highest +#' Try all of above levels and adopt the result of the highest #' \code{\link[stats]{cor}} value. #' } #' -#' The higher the level in the range of from \code{0} to \code{3}, -#' the more likely it is that the initial values will model -#' the frequency distribution in closer, -#' but the accuracy of the result may not along with the level. +#' As the level increases within the range of \code{0} to \code{3}, +#' the initial model will tend to be closer to the frequency distribution. +#' However, the accuracy of the result may not along with the level. #' It is possible that \code{\link[stats]{nls}} will succeed at level \code{1} #' and fail at level \code{3} for the same data. #' -#' @param start A list of \code{start} argument for \code{\link[stats]{nls}}. +#' @param start A list for \code{start} argument of \code{\link[stats]{nls}}. #' #' You can provide your own \code{start} for \code{\link[stats]{nls}}, -#' the mean values -#' (names are like: \code{mean}, \code{mean.i} or \code{mean.i.j}) +#' the mean values (parameters are like: \code{mean}, \code{mean.i}, +#' or \code{mean.i.j}) #' and the \bold{square root} of the standard deviations -#' (names are like: \code{sqrt.sd}, \code{sqrt.sd.i} or \code{sqrt.sd.i.j}) -#' of the normal distributions of the components. +#' (parameters are like: \code{sqrt.sd}, \code{sqrt.sd.i}, +#' or \code{sqrt.sd.i.j}) of the normal distributions of the components. #' #' Depending on the kind of the distribution model, -#' the name of the parameters are different. +#' the names of the parameters are different. #' You can use \code{\link[ggd]{ggd.start.template}} #' to get the template of the list and know the names of the parameters. #' @@ -226,7 +203,7 @@ #' #' @param not.use.nls A logical. #' If \code{TRUE}, this function does not use \code{\link[stats]{nls}} and -#' it outputs an object having the initial values in the \code{cmp} field +#' it outputs an object having the start values in \code{cmp} field #' as the result. #' If \code{FALSE}, this function uses \code{\link[stats]{nls}}. #' @@ -234,46 +211,77 @@ #' other than \code{100}. A warning will occur if \code{TRUE} #' when \code{start.level} is \code{100}. #' -#' You can use \code{not.use.nls = TRUE} to check the initial values -#' when an error has occurred at this function. +#' You can use \code{not.use.nls = TRUE} to check +#' whether the start values are appropriate +#' when you have obtained an undesirable result from this function. #' #' @param cor.method The \code{method} argument for \code{\link[stats]{cor}}. -#' It represents the correlation coefficient method. -#' This argument is used only if \code{start.level = 100}. +#' It is a character string indicating which correlation coefficient +#' (or covariance) is to be computed in order to compare the results +#' between levels when \code{start.level = 100}. #' If \code{NULL}, it uses the default method of \code{\link[stats]{cor}}. +#' This argument works only if \code{start.level = 100}. #' See \code{\link[stats]{cor}} for more information. #' #' @param ... Each argument for \code{\link[stats]{nls}} can be indicated. -#' See "Arguments" of \code{\link[stats]{nls}} for more information. +#' See 'Arguments' of \code{\link[stats]{nls}} for more information. +#' +#' @param this.kind A character string or a numeric value or a \code{\link[ggd]{GGD}} object +#' which indicates the kind of distribution model to be constructed. +#' It is equivalent to \code{kind} argument of \code{ggd.nls.freq}. +#' +#' When this method is called without \code{this.kind} argument +#' or other conditions, it attempt to retain the value of +#' \code{mix.type} field as much as possible except for \code{kind} field, +#' i.e., the condition whether the mean value and standard deviation of +#' each component are aligned to same values or not may not be retained. +#' If you want to retain these conditions as well, +#' indicate the object itself to \code{this.kind} argument like as +#' \code{obj$nls.freq(data, this.kind = obj)}. +#' +#' @param this.mix.type A numeric value to set into \code{mix.type} field as an integer. +#' It is equivalent to \code{mix.type} argument of +#' \code{ggd.nls.freq}. +#' +#' Where \code{this.mix.type = 3} is indicated, +#' \code{nls.freq} method constructs 2- or 3- component model +#' according to the number of current components. +#' +#' If both of \code{this.kind} and \code{this.mix.type} are not given +#' and \code{grad} argument is \code{"default"}, +#' the current value of \code{mix.type} field will be retained, +#' and number of components will also. +#' However, if the object has been cleared when this method is called, +#' \code{mix.type} field will be \code{2}, the start value. #' #' @return A list containing components (invisible for \code{GGD} method) #' \item{obj}{ #' Generated \code{\link[ggd]{GGD}} object which most (at least locally) #' closely approximates the given frequency distribution. #' If \code{\link[stats]{nls}} has failed, it will be a cleared object. -#' For \code{\link[ggd]{GGD}} method, the \code{\link[ggd]{GGD}} object itself.} +#' For \code{\link[ggd]{GGD}} method, +#' the \code{\link[ggd]{GGD}} object itself.} #' \item{nls.out}{ #' The list of the output of \code{\link[stats]{nls}}. #' If \code{\link[stats]{nls}} has not been used, \code{NULL} will be set. -#' See "Value" of \code{\link[stats]{nls}} for more information.} +#' See 'Value' of \code{\link[stats]{nls}} for more information.} #' \item{start.level}{ -#' The initial guessing level which is used actually to gain \code{obj}. +#' The initial guessing level which is used actually to obtain \code{obj}. #' If \code{start.level = 100} is indicated, #' the level for the best result will be set. #' When \code{start.level = 3} is indicated #' and if initial guessing has failed, \code{2} will be set. -#' If \code{start} argument (not-\code{NULL}) is indicated, -#' \code{NA} will be set.} +#' If you indicate \code{start} argument a not-\code{NULL} list, +#' \code{start.level} will be \code{NA}.} #' \item{start}{ -#' The used \code{start} argument for the initial values -#' for \code{\link[stats]{nls}}.} +#' The used \code{start} argument of \code{\link[stats]{nls}}.} #' \item{start.obj}{ -#' A \code{\link[ggd]{GGD}} object corresponding to the initial values. +#' A \code{\link[ggd]{GGD}} object corresponding to the start values. #' That is, a \code{\link[ggd]{GGD}} object in which -#' values of the above \code{start} are set directly to the \code{cmp} field.} +#' values of the above \code{start} are set directly to \code{cmp} field.} #' \item{cor}{ #' The vector of the correlation coefficient of between the result for -#' each level of initial guessing in from \code{0} to \code{3} +#' each initial guessing level in the range of \code{0} to \code{3} #' and the frequency distribution. #' This component is given only if \code{start.level = 100}.} #' \item{errors}{ @@ -281,15 +289,16 @@ #' This component is given only if \code{start.level = 100}. #' Each element in the list contains: #' \itemize{ -#' \item level: The level of initial guessing when the error has occurred. +#' \item level: The initial guessing level when the error has occurred. #' \item message: The error message. #' }} #' \item{warnings}{ #' A list of information about warnings occurred in \code{\link[stats]{nls}}. #' This component is given only if \code{start.level = 100}. -#' The composition of each element is as same as for \code{errors}.} +#' The composition of each element is same as \code{errors}.} #' -#' For \code{GGD} method: If an error occur, the object will be cleared in most cases. +#' For \code{GGD} method: If an error occurs, all fields of the object will be cleared +#' in most cases. #' #' @importFrom methods new #' @importFrom stats complete.cases @@ -297,27 +306,30 @@ #' \code{\link[ggd]{ggd.nls.freq.all}}, \code{\link[ggd]{ggd.start.template}} #' #' @details -#' \subsection{Why the standard deviations for "start" are square-rooted?}{ -#' You know a standard deviation must be a non-zero positive value. +#' \subsection{Why the standard deviations for 'start' are square-rooted?}{ +#' You know a standard deviation must be a positive value. #' But if you use standard deviations directly in the formula for \code{\link[stats]{nls}}, -#' they will sometimes drop into negative values while the Gauss-Newton algorithm is running +#' they sometimes drop into negative values while the Gauss-Newton algorithm is running #' and the algorithm will fail, even if it can reach convergence if done better. #' -#' So, to avoid such failures, we use square roots of standard deviations and +#' Therefore, to avoid such failures, we use square roots of standard deviations and #' take squares of them in the formula for \code{\link[stats]{nls}}. #' } #' #' @examples -#' ## Preparing -#' df <- data.frame( x = seq( -2, 2, 0.2 ), -#' freq = c( 1517, 2292, 2513, 2763, 3724, 4046, 4713, -#' 7947, 10997, 11824, 11133, 7868, 4692, 4103, -#' 3698, 2740, 2549, 2284, 1499, 1147, 918 ), -#' x.2 = seq( -20, 20, 2 ), -#' freq.2 = c( .000974, .003797, .008523, .023142, .045017, .081743, .120990, -#' .142527, .124627, .106294, .078625, .059378, .045690, .042958, -#' .035760, .030938, .015675, .012516, .008139, .005114, .003582 ) ) -#' +#' ## Preparing: +#' df <- data.frame( +#' x = seq( -2, 2, 0.2 ), +#' freq = c( 1517, 2292, 2513, 2763, 3724, 4046, 4713, +#' 7947, 10997, 11824, 11133, 7868, 4692, 4103, +#' 3698, 2740, 2549, 2284, 1499, 1147, 918 ), +#' x.2 = seq( -20, 20, 2 ), +#' freq.2 = c( .000974, .003797, .008523, .023142, .045017, .081743, .120990, +#' .142527, .124627, .106294, .078625, .059378, .045690, .042958, +#' .035760, .030938, .015675, .012516, .008139, .005114, .003582 ) ) +#' +#' ## This function plots probability densities obtained from the frequency distribution +#' ## and the probability density function of a GGD object. #' plot.freq.and.d <- function( obj, x, freq ) #' { #' xlim <- c( min( x ), max( x ) ) @@ -328,28 +340,24 @@ #' type = "l", xlim = xlim, ylim = ylim ) #' } #' -#' ## Examples -#' ggd.nls.freq( df, grad = "normal" ) -#' a <- ggd.nls.freq( df, grad = "no" )$obj -#' plot.freq.and.d( a, df$x, df$freq ) +#' ## Examples: +#' result <- ggd.nls.freq( df, mix.type = 0 ) +#' result +#' plot.freq.and.d( result$obj, df$x, df$freq ) #' -#' ## "start.level" can be omitted (and you should omit to gain better results), -#' ## but is indicated here for processing speed. -#' a$nls.freq( df, this.mix.type = 1, start.level = 2 ) +#' ## You should not indicate 'start.level' to obtain good quality results, +#' ## but it is indicated here to make the process faster. +#' a <- GGD$new() +#' a$nls.freq( df, this.kind = "2.*Sigma-Equaled Vertical", start.level = 2 ) #' a #' plot.freq.and.d( a, df$x, df$freq ) #' -#' a$nls.freq( df, start.level = 2, -#' this.kind = "2-Mean-Differed Sigma-Equaled Vertical Gradational Distribution" ) -#' a -#' plot.freq.and.d( a, df$x, df$freq ) -#' -#' ## overwriting "Sigma-Differed" after "kind = a" -#' b <- ggd.nls.freq( df, kind = a, eq.sd = FALSE, start.level = 2 ) -#' b -#' plot.freq.and.d( b$obj, df$x, df$freq ) +#' ## Overwriting 'Sigma-Differed' with 'eq.sd = FALSE' after 'kind = a'. +#' b <- ggd.nls.freq( df, kind = a, eq.sd = FALSE, start.level = 2 )$obj +#' a$kind; b$kind ## "... Sigma-Equaled ..."; "... Sigma-Differed ..." +#' plot.freq.and.d( b, df$x, df$freq ) #' -#' ## You can set start parameters if you want. +#' ## You can specify start values with 'start' argument. #' start.list <- ggd.start.template( 14 ) #' start.list #' @@ -357,28 +365,74 @@ #' start.list$mean.1.2 <- -0.198 #' start.list$mean.2.1 <- 0.293 #' start.list$mean.2.2 <- -0.198 -#' start.list$sqrt.sd <- sqrt( 0.640 ) ## sqrt.sd is the sqrt of the standard deviation. +#' start.list$sqrt.sd <- sqrt( 0.640 ) ## 'sqrt.sd' is the sqrt of the standard deviation. #' -#' ## "start.level" is ignored when you have indicated start parameters. -#' a$nls.freq( df, this.kind = 14, start.level = 1, start = start.list ) -#' a +#' ## You can check the start values with 'not.use.nls = TRUE' before approximating. +#' a$nls.freq( df, this.kind = 14, start = start.list, not.use.nls = TRUE ) +#' a$cmp +#' plot.freq.and.d( a, df$x, df$freq ) +#' +#' ## When you indicate 'start' argument, 'start.level' argument is ignored. +#' result <- a$nls.freq( df, this.kind = 14, start.level = 1, start = start.list ) +#' result$start.level ## NA +#' result$start.obj$cmp ## Verify start values. +#' a$cmp ## results #' plot.freq.and.d( a, df$x, df$freq ) #' -#' ## When you use a GGD object consecutively, -#' ## the field values set to the object in the previous session are retained -#' ## (if no error has occurred). +#' ## When you call nls.freq method of a GGD object consecutively, +#' ## the conditions saved in the fields are retained (if no error has occurred). #' a$nls.freq( df, grad = "hv", eq.mean = TRUE, start.level = 2 ) -#' a +#' a$mix.type; a$is.eq.mean() ## 4; TRUE #' plot.freq.and.d( a, df$x, df$freq ) #' -#' a$nls.freq( df, eq.mean = FALSE, start.level = 2 ) ## grad = "hv" is retained. -#' a +#' a$nls.freq( df, eq.mean = FALSE, start.level = 2 ) ## 'grad = "hv"' is retained. +#' a$mix.type; a$is.eq.mean() ## 4; FALSE #' plot.freq.and.d( a, df$x, df$freq ) #' #' ## Using "x.2" for x and "freq.2" for freq. -#' a <- ggd.nls.freq( df, x = "x.2", freq = "freq.2", start.level = 2 )$obj -#' a ## default value of mix.type is 2 -#' plot.freq.and.d( a, df$x.2, df$freq.2 ) +#' b <- ggd.nls.freq( df, x = "x.2", freq = "freq.2", start.level = 2 )$obj +#' b +#' plot.freq.and.d( b, df$x.2, df$freq.2 ) +#' +#'\dontrun{ +#' ## Using the default 'start.level' (100) is the best way to obtain a good quality result, +#' ## but the process is slow to demonstrate as a running example. So, it is not run here. +#' ## +#' ## The following results written in comments are +#' ## obtained on a Windows 11 64-bit environment using ggd v1.0.3 package. +#' result <- a$nls.freq( df, grad = "v" ) +#' result$cor +#' ## level.0 level.1 level.2 level.3 +#' ## 0.9867103 0.9867102 0.9867103 0.9867102 +#' result$start.level +#' ## 2 +#' a$cmp +#' ## mean sd +#' ## n.1 -0.1841741 1.039255 +#' ## n.2 -0.1973208 0.648003 +#' +#' ## 'cor.method' argument is available for 'start.level = 100' +#' ## but the default value is recommended (see 'Details' at the manual of cor). +#' result <- a$nls.freq( df, cor.method = "kendall" ) +#' result$cor +#' ## level.0 level.1 level.2 level.3 +#' ## 0.9428571 0.9428571 0.9428571 0.9428571 ## All values were equal. +#' result$start.level +#' ## 0 +#' a$cmp +#' ## mean sd +#' ## n.1 -0.1841703 1.039255 +#' ## n.2 -0.1973202 0.648003 +#' +#' ## 'start.level = 3' does not always generate good start values. +#' ## This execution may cause an error in nls due to strange start values. +#' a$nls.freq( df, grad = "hv", start.level = 3 ) +#' ## If run, an error may occur as: 'nls has failed. Message: Error in nls...' +#' +#' ## To get a result even if an error occurs in nls, +#' ## you can indicate 'warnOnly = TRUE' in 'control' option. +#' a$nls.freq( df, grad = "hv", start.level = 3, control = list( warnOnly = TRUE ) ) +#' ## If run, a warning may occur (a singular gradient).} ################################################################################################ ggd.nls.freq <- function( data, x = "x", freq = "freq", total = NULL, kind = NULL, mix.type = NULL, @@ -413,20 +467,20 @@ GGD$methods( not.use.nls = FALSE, cor.method = NULL, ...) { # Note: - # In this function, when a error occur, - # we clear the fields as possible as we can. + # In this function, when an error occurs, + # we clear all fields as much as possible. # # Because this function does not directly set specified values to the fields, # if the fields are not cleared and contain some normal values, # users may let the subsequent processes take place without noticing the error. # During the development phase, the developer actually experienced such mistakes. + on.exit( clear() ) result <- list( obj = NULL, nls.out = NULL, start.level = NULL, start = NULL, start.obj = NULL ) # Check errors of data frame and discard NA and NaN. - data.ext <- withCallingHandlers( extract.freq.data( data, x, freq ), - error = function( e ) clear() ) + data.ext <- extract.freq.data( data, x, freq ) # Get total. if ( is.null( total ) ) @@ -436,13 +490,12 @@ GGD$methods( else if ( length( total ) != 1 || !is.numeric( total ) || is.na( total ) || is.infinite( total ) || total <= 0 ) { - clear() stop( "Error: total should be positive finite single value." ) } ################################################################ # Check options and get new mix.type according to the priority. - grad <- withCallingHandlers( match.arg( grad ), error = function( e ) clear() ) + grad <- match.arg( grad ) if ( grad == "v" ) { grad <- "v2" @@ -450,30 +503,24 @@ GGD$methods( if ( !is.null( this.kind ) ) { - this.kind.index <- withCallingHandlers( - ggd.kind.index( this.kind, undef.err = TRUE ), - error = function( e ) clear() ) + this.kind.index <- ggd.kind.index( this.kind, undef.err = TRUE ) if ( length( this.kind.index ) > 1 ) { - clear() stop( "Error: kind should be valid single value or a GGD object." ) } else if ( length( this.kind.index ) == 1 && !is.na( this.kind.index ) ) { - if ( is.null( this.mix.type ) ) + # Set "v2" or "v3" to grad by this.kind + # (but if this.mix.type is indicated, it takes priority) + if ( grad == "default" && is.null( this.mix.type ) ) { - this.mix.type <- ggd.mix.type.for.kind.index( this.kind.index ) - - if ( grad == "default" ) + if ( any( this.kind.index == 8:10 ) ) { - if ( any( this.kind.index == 8:10 ) ) - { - grad <- "v2" - } - else if ( any( this.kind.index == 11:13 ) ) - { - grad <- "v3" - } + grad <- "v2" + } + else if ( any( this.kind.index == 11:13 ) ) + { + grad <- "v3" } } @@ -513,14 +560,10 @@ GGD$methods( } } - new.mix.type <- withCallingHandlers( - ggd.mix.type.for( grad, - kind = this.kind, mix.type = this.mix.type ), - error = function( e ) clear() ) + new.mix.type <- ggd.mix.type.for( grad, kind = this.kind, mix.type = this.mix.type ) if ( length( new.mix.type ) != 1 || is.na( new.mix.type ) || !any( new.mix.type == 0:4 ) ) { - clear() if ( !is.null( this.kind ) ) { # This code will run if this.kind = character( 0 ). @@ -557,14 +600,14 @@ GGD$methods( if ( length( start.level ) != 1 || !is.numeric( start.level ) || is.na( start.level ) || !any( start.level == c( 0:3, 100 ) ) ) { - clear() stop( "Error: start.level should be single integer in 0:3 or 100." ) } } if ( isTRUE( not.use.nls ) && !is.na( start.level ) && start.level == 100 ) { - warning( paste( "Warning: not.use.nls does not work with start.level is default 100." ) ) + warning( paste( "Warning: not.use.nls does not work with", + "start.level is default 100." ) ) not.use.nls <- FALSE } @@ -578,7 +621,6 @@ GGD$methods( silent = TRUE ) if ( inherits( result, "try-error" ) ) { - clear() stop( result ) } @@ -589,11 +631,11 @@ GGD$methods( else { ################################################################ - # Get start paramaters for nls. + # Get start parameters for nls. params <- get.nls.params( data.ext$x, data.ext$freq, total, new.mix.type, grad, eq.mean, eq.sd, start.level ) - # Output start paramaters. + # Output start parameters. result$start.level <- as.integer( params$start.level ) if ( is.null( start ) ) { @@ -613,7 +655,7 @@ GGD$methods( result.cmp <- NULL if ( isTRUE( not.use.nls ) ) { - # Output using start paramaters directly without nls. + # Output using start parameters directly without nls. result.cmp <- result$start.obj$cmp } else @@ -629,7 +671,6 @@ GGD$methods( control = control, ... ), silent = TRUE ) if ( inherits( result$nls.out, "try-error" ) ) { - clear() stop( paste( "nls has failed. Message:", result$nls.out ) ) } else @@ -646,6 +687,7 @@ GGD$methods( result$obj <- .self } + on.exit() return ( invisible( result ) ) } ) @@ -653,17 +695,16 @@ GGD$methods( ################################################################################################ #' [Non-exported] Loop nls for start.level = 100 #' -#' Execute a loop of \code{\link[stats]{nls}} with changing the level of initial guessing. +#' Executes a loop of \code{\link[stats]{nls}} with changing initial guessing levels. #' This is the main process of \code{\link[ggd]{nls.freq}} with \code{start.level = 100}. #' @param data A data frame which represents the frequency distribution. -#' It must contain 2 numeric columns named \code{x} and \code{freq}. +#' It must contain 2 numeric columns named \code{"x"} and \code{"freq"}. #' @param total Total value of the frequencies. #' @param kind An object indicating the \code{kind} of \code{\link[ggd]{GGD}} object. #' @param mix.type A numeric value to set into \code{mix.type} field of #' the \code{\link[ggd]{GGD}} object as an integer. #' It is an integer from \code{0} to \code{4} or \code{NULL}. #' @param grad A character string indicating the method of gradation. -#' See \code{\link[ggd]{nls.freq}} for more information. #' @param eq.mean A logical. If \code{TRUE}, all of the mean values of of the components #' are forced to be equal. #' @param eq.sd A logical. If \code{TRUE}, all of the standard deviations of @@ -672,7 +713,7 @@ GGD$methods( #' See \code{\link[stats]{nls.control}} for more information. #' @param cor.method The \code{method} argument for \code{\link[stats]{cor}}. #' @param ... Each argument for \code{\link[stats]{nls}} can be indicated. -#' See "Arguments" of \code{\link[stats]{nls}} for more information. +#' See 'Arguments' of \code{\link[stats]{nls}} for more information. #' @return A list conforming the return value of \code{\link[ggd]{nls.freq}}. #' @seealso \code{\link[ggd]{nls.freq}} ################################################################################################ @@ -698,13 +739,15 @@ nls.freq.level.100 <- function( data, total, kind, mix.type, control = control, ... ), warning = function( w ) { - wrnl <<- append( wrnl, list( list( level = level, - message = conditionMessage( w ) ) ) ) + wrnl <<- append( wrnl, + list( list( level = level, + message = conditionMessage( w ) ) ) ) } ), error = function( e ) { - errl <<- append( errl, list( list( level = level, - message = conditionMessage( e ) ) ) ) + errl <<- append( errl, + list( list( level = level, + message = conditionMessage( e ) ) ) ) } ) ) ) } ) @@ -768,26 +811,26 @@ nls.freq.level.100 <- function( data, total, kind, mix.type, #' \item Mean-Equaled Sigma-Differed Horizontal-Vertical Gradational Distribution #' \item Mean-Differed Sigma-Differed Horizontal-Vertical Gradational Distribution #' } -#' Each index numbers of above list are -#' also used for \code{kind.index} field of \code{\link[ggd]{GGD}} class. +#' Each index number of above list is +#' also set into \code{kind.index} field of each \code{\link[ggd]{GGD}} object. #' #' This function generates 16 \code{\link[ggd]{GGD}} objects and #' calls \code{\link[ggd]{nls.freq}} method 16 times. #' By default, \code{\link[ggd]{nls.freq}} is called with \code{warnOnly = TRUE}, #' so \code{\link[ggd]{nls.freq}} does not generate errors, but generates warnings often. #' When a warning occur, this function generates another warning like -#' "\code{Warning for kind = xx :}" to inform which \code{kind.index} gets a poor result +#' '\code{Warning for kind = xx :}' to inform which \code{kind.index} gets a poor result #' (poor, but may be accurate enough). #' So when one warning has occurred, two warnings will occur eventually. #' #' If you indicate \code{warnOnly = FALSE} in \code{control} argument #' and overwrite \code{warnOnly} option, \code{\link[ggd]{nls.freq}} can generate errors. -#' If an error occur in one of \code{\link[ggd]{nls.freq}} processes, -#' this function throws messages like "\code{Error for kind = xx :}" and "\code{Error in ...}" -#' instead of throwing error and does not stop, +#' If an error occurs in one of \code{\link[ggd]{nls.freq}} processes, +#' this function throws messages like '\code{Error for kind = xx :}' and '\code{Error in ...}' +#' instead of throwing an error and skips the process, #' then tries other \code{\link[ggd]{nls.freq}} processes. #' For the result of error-occurred \code{kind.index}, a cleared \code{\link[ggd]{GGD}} object -#' will be got as an element of \code{obj} (see "Value"). +#' will be got as the element of \code{obj} (see 'Value'). #' #' @export #' @param data A data frame which represents the frequency distribution. @@ -795,7 +838,7 @@ nls.freq.level.100 <- function( data, total, kind, mix.type, #' See \code{\link[ggd]{nls.freq}} for more information. #' #' Column names and indexes for \code{x} and \code{freq} are flexible. -#' You can specify them with next two arguments. +#' You can indicate them with next two arguments. #' #' @param x The column name or index number for the column of x-coordinates #' in \code{data}. @@ -807,20 +850,18 @@ nls.freq.level.100 <- function( data, total, kind, mix.type, #' See \code{\link[ggd]{nls.freq}} for more information. #' #' @param start.level A numeric value of integer in from \code{0} to \code{3} or \code{100} -#' with default \code{100}; -#' the level at which to guess the initial \code{start} parameters -#' of \code{\link[stats]{nls}}. +#' with default \code{100}; the level of guessing the start values +#' for \code{start} argument of \code{\link[stats]{nls}}. #' See \code{\link[ggd]{nls.freq}} for more information. #' #' @param start A \bold{list of lists} with the length of 16 -#' for each of the \code{start} arguments for \code{\link[stats]{nls}} -#' as initial values. -#' Each element (a list) will give to the \code{start} argument of +#' for each of \code{start} arguments of \code{\link[stats]{nls}} +#' as start values. +#' Each element (a list) will give to \code{start} argument of #' \code{\link[stats]{nls}} one by one. #' -#' For initial values for which \code{NULL} is indicated as the list -#' in the \code{start} argument, internally computed initial values -#' depending on \code{start.level} are used. +#' For cases where \code{NULL} is indicated in this argument, +#' internally computed start values depending on \code{start.level} are used. #' #' As an auxiliary tool for making a list of 16 lists, #' you can use \code{\link[ggd]{ggd.init.start}} function @@ -831,14 +872,14 @@ nls.freq.level.100 <- function( data, total, kind, mix.type, #' In addition, \code{\link[ggd]{ggd.kind}} and #' \code{\link[ggd]{ggd.kind.index}} functions may help you whether #' each index number of \code{start} represents what kind of distribution. -#' See "Examples" for usages of these tools. +#' See 'Examples' for usages of these tools. #' #' @param control The \code{control} argument for \code{\link[stats]{nls}}. #' See \code{\link[stats]{nls.control}} for more information. #' #' @param not.use.nls A logical. #' If \code{TRUE}, this function does not use \code{\link[stats]{nls}} -#' and it outputs objects having the initial values in the \code{cmp} field +#' and it outputs objects having the start values in \code{cmp} field #' as the results. #' If \code{FALSE}, this function uses \code{\link[stats]{nls}}. #' @@ -846,23 +887,24 @@ nls.freq.level.100 <- function( data, total, kind, mix.type, #' other than \code{100}. #' A warning will occur if \code{TRUE} when \code{start.level} is \code{100}. #' -#' You can use \code{not.use.nls = TRUE} to check the initial values -#' when an error has occurred at this function. +#' You can use \code{not.use.nls = TRUE} to check whether the start values +#' are appropriate when obtained an undesirable result from this function. #' #' @param cor.method The \code{method} argument for \code{\link[stats]{cor}}. -#' It represents the correlation coefficient method. +#' It is a character string indicating which correlation coefficient +#' (or covariance) is to be computed. #' If \code{NULL}, it uses the default method of \code{\link[stats]{cor}}. #' See \code{\link[stats]{cor}} for more information. #' #' @param ... Each argument for \code{\link[stats]{nls}} can be indicated. -#' See "Arguments" of \code{\link[stats]{nls}} for more information. +#' See 'Arguments' of \code{\link[stats]{nls}} for more information. #' -#' @return A list containing components (invisible for \code{GGD} method) +#' @return A list containing components #' \item{best}{ #' The \code{\link[ggd]{GGD}} object which has got #' the highest correlation coefficient. -#' That is, the most approximate to the given frequency distribution -#' in all of the supported distribution models. +#' That is, it would be the most approximate to +#' the given frequency distribution in all of the supported models. #' If there are some models which have got the same highest correlation #' coefficient, the object with the earlier \code{kind.index} is #' given priority.} @@ -873,26 +915,34 @@ nls.freq.level.100 <- function( data, total, kind, mix.type, #' #' \item{obj}{ #' The list of 16 \code{\link[ggd]{GGD}} objects -#' ordered by \code{kind.index}; the index number in \code{ggd:::kinds}. +#' ordered along with \code{ggd:::kinds}. #' If an error has occurred, the element will be a cleared object.} #' #' \item{cor}{ -#' The vector of the correlation coefficient of +#' The vector of the correlation coefficients #' between the result of each model and the frequency distribution. #' \code{NA} will be given for an error case or an extremely bad result.} #' #' \item{detail}{ -#' The list of 16 elements of outputs of \code{\link[ggd]{nls.freq}}. +#' The list of 16 results of \code{\link[ggd]{nls.freq}}. #' Normally, each element is a list of the output of -#' \code{\link[ggd]{nls.freq}}, -#' but if an error has occurred, the element will be an error condition. -#' See "Value" of \code{\link[ggd]{nls.freq}} for more information.} +#' \code{\link[ggd]{nls.freq}}. +#' But if an error has occurred, the element will be an error condition. +#' See 'Value' of \code{\link[ggd]{nls.freq}} for more information.} #' #' @importFrom methods new #' @seealso \code{\link[ggd]{nls.freq}}, \code{\link[stats]{cor}}, #' \code{\link[ggd]{ggd.init.start}}, \code{\link[ggd]{ggd.start.template}} #' @examples -#' ## Preparing. +#' ## Preparing: +#' df <- data.frame( +#' x = seq( -2, 2, 0.2 ), +#' freq = c( 1517, 2292, 2513, 2763, 3724, 4046, 4713, +#' 7947, 10997, 11824, 11133, 7868, 4692, 4103, +#' 3698, 2740, 2549, 2284, 1499, 1147, 918 ) ) +#' +#' ## This function plots probability densities obtained from the frequency distribution +#' ## and the probability density function of a GGD object. #' plot.freq.and.d <- function( obj, x, freq ) #' { #' xlim <- c( min( x ), max( x ) ) @@ -903,32 +953,31 @@ nls.freq.level.100 <- function( data, total, kind, mix.type, #' type = "l", xlim = xlim, ylim = ylim ) #' } #' -#' df <- data.frame( -#' x = seq( -2, 2, 0.2 ), -#' freq = c( 1517, 2292, 2513, 2763, 3724, 4046, 4713, -#' 7947, 10997, 11824, 11133, 7868, 4692, 4103, -#' 3698, 2740, 2549, 2284, 1499, 1147, 918 ) ) -#' -#' ## Try ggd.nls.freq.all. -#' ## Here, "start.level = 1" is specified to get less-than-ideal results -#' ## to explain how to use "start" argument. +#' ## Examples: +#' ## We specify 'start.level = 1' here in order to obtain less-than-ideal results purposely +#' ## to explain how to use 'start' argument using the results. #' result <- ggd.nls.freq.all( df, start.level = 1 ) #' #' ## Show the results. #' result$cor -#' result$best.cor -#' result$best +#' result$best.cor; result$best$kind.index #' -#' ## Check that the value of cor for kind = 14 is very low. +#' ## Check that the value of 'cor' for kind = 14 is very low. #' result$cor[[14]] #' -#' ## Let's try to increase the value of cor by changing the initial values. +#'\dontrun{ +#' ## If you want to ignore warning cases at ggd.nls.freq.all, +#' ## indicate 'warnOnly = FALSE' in 'control' option. +#' ## This option turns warnings into errors, and cases which cause errors are skipped. +#' result <- ggd.nls.freq.all( df, start.level = 1, control = list( warnOnly = FALSE ) )} +#' +#' ## Let's try to increase the value of 'cor' by changing the start values. #' ## -#' ## There is an easy and good way to solve this problem, -#' ## that is to remove "start.level = 1". -#' ## But here, we use "start" argument with remaining "start.level" for explaining. +#' ## There is an easy and good way to increase the value of 'cor', +#' ## that is to remove 'start.level = 1'. +#' ## But here, we keep 'start.level = 1' and use 'start' argument for explaining. #' ## -#' ## First, to see what kind = 14 is, display the kind. +#' ## First, to see what 'kind = 14' is, display the kind. #' result$obj[[14]]$kind #' #' ## Also, using ggd.kind, you can get the character string for the index. @@ -937,33 +986,56 @@ nls.freq.level.100 <- function( data, total, kind, mix.type, #' ## Inversely, using ggd.kind.index, you can get index for each kind. #' ggd.kind.index( "Mean-Differed Sigma-Equaled Horizontal-Vertical" ) #' -#' ## Show the cmp field of kind = 14 and plots. +#' ## Show the 'cmp' field and plot the probability density function. #' result$obj[[14]]$cmp #' plot.freq.and.d( result$obj[[14]], df$x, df$freq ) #' -#' ## Now, for the initial values, we are going to use the result of -#' ## kind = "2-Mean-Differed Sigma-Equaled Vertical Gradational Distribution". +#' ## Now, for the start values, we are going to use the result of +#' ## '2-Mean-Differed Sigma-Equaled Vertical Gradational Distribution'. #' ggd.kind.index( "2-Mean-Differed Sigma-Equaled Vertical" ) ## 8 +#' result$cor[[8]] #' result$obj[[8]]$cmp #' -#' ## Display the parameters for the initial values for kind = 14. +#' ## Display the parameters for the start values for kind = 14. #' ggd.start.template( 14 ) #' -#' ## Set the initial values for kind = 14. +#' ## Specify the start values for kind = 14. #' start.list <- ggd.init.start() #' start.list[[14]] <- ggd.start.template( 14 ) #' start.list[[14]]$mean.1.1 <- result$obj[[8]]$cmp$mean[1] #' start.list[[14]]$mean.1.2 <- result$obj[[8]]$cmp$mean[2] #' start.list[[14]]$mean.2.1 <- result$obj[[8]]$cmp$mean[1] #' start.list[[14]]$mean.2.2 <- result$obj[[8]]$cmp$mean[2] -#' start.list[[14]]$sqrt.sd <- sqrt( result$obj[[8]]$cmp$sd[1] ) ## Set sqrt for SD. +#' start.list[[14]]$sqrt.sd <- sqrt( result$obj[[8]]$cmp$sd[1] ) ## Take sqrt for SD. #' #' ## Retry ggd.nls.freq.all. #' result <- ggd.nls.freq.all( df, start.level = 1, start = start.list ) -#' result$cor #' result$cor[[14]] #' result$obj[[14]]$cmp #' plot.freq.and.d( result$obj[[14]], df$x, df$freq ) +#' +#' ## On the other hand, you can check the start values with 'not.use.nls = TRUE'. +#' start <- ggd.nls.freq.all( df, start.level = 1, not.use.nls = TRUE ) +#' start$cor +#' start$best.cor; start$best$kind.index +#' start$obj[[14]]$cmp +#' plot.freq.and.d( start$obj[[14]], df$x, df$freq ) +#' +#' ## You will find that 'start.level = 2' can generate reasonable start values basically. +#' start <- ggd.nls.freq.all( df, start.level = 2, not.use.nls = TRUE ) +#' start$cor +#' start$best.cor; start$best$kind.index ## 14 +#' start$obj[[14]]$cmp +#' plot.freq.and.d( start$obj[[14]], df$x, df$freq ) +#' +#' ## Using 'cor.method' argument, +#' ## you can evaluate the correlations with nonparametric methods. +#' start <- ggd.nls.freq.all( df, start.level = 2, not.use.nls = TRUE, +#' cor.method = "kendall" ) +#' start$cor +#' start$best.cor; start$best$kind.index ## 2 +#' start$obj[[2]]$cmp +#' plot.freq.and.d( start$obj[[2]], df$x, df$freq ) ################################################################################################ ggd.nls.freq.all <- function( data, x = "x", freq = "freq", total = NULL, start.level = 100, start = NULL, @@ -993,7 +1065,8 @@ ggd.nls.freq.all <- function( data, x = "x", freq = "freq", total = NULL, if ( isTRUE( not.use.nls ) && start.level == 100 ) { - warning( paste( "Warning: not.use.nls does not work with start.level is default 100." ) ) + warning( paste( "Warning: not.use.nls does not work", + "with start.level is default 100." ) ) not.use.nls <- FALSE } @@ -1016,12 +1089,12 @@ ggd.nls.freq.all <- function( data, x = "x", freq = "freq", total = NULL, control <- append( control, list( warnOnly = TRUE ) ) } - # Execule nls. - # If an error occuer, the error message is displayed but other processes continue. + # Execute nls. + # If an error occurs, the error message is displayed but other processes continue. results <- lapply( 1:length( kinds ), function( i ) { - # Remark if an error occur at nls.freq, obj will be a cleared object (not NULL). + # Remark if an error occurs at nls.freq, obj will be a cleared object (not NULL). obj <- GGD$new() result <- withCallingHandlers( try( obj$nls.freq( data = data.ext, @@ -1144,17 +1217,15 @@ extract.freq.data <- function( data, x, freq ) #' @param x A vector of x-coordinates. Duplicate values are not allowed. #' #' @param freq A vector of frequencies following \code{x}. -#' The values of frequencies must be positive. #' Both integers and real numbers are allowed for the values. #' #' @param total Total value of the frequencies. #' #' If \code{NULL} (the default), -#' the total of \code{freq}, i.e., \code{\link[base]{sum}(data[[freq]])} -#' (on \code{\link[stats]{complete.cases}} of \code{x} and \code{freq}) +#' the total of \code{freq}, i.e., \code{\link[base]{sum}(freq)} #' is used for it. #' -#' @return The vector of expected probability density value at each of x-coordinates. +#' @return The vector of expected probability density values following the x-coordinates. #' @examples #' x <- seq( -2, 2, 0.2 ) #' freq <- c( 1517, 2292, 2513, 2763, 3724, 4046, 4713, @@ -1241,8 +1312,6 @@ get.p.freq <- function( freq, total ) #' @param total Total value of the frequencies. #' @param mix.type The value for \code{mix.type} field. #' @param grad A character string indicating the method of gradation. -#' If \code{"v3"}, constructing with 3 components is enforcedly, -#' even if it is possible to construct with 2 components. #' #' In this function, \code{grad} argument have no priority #' over \code{mix.type} argument. @@ -1250,23 +1319,26 @@ get.p.freq <- function( freq, total ) #' \code{mix.type = 3} is indicated. #' And if \code{mix.type = 3} is indicated, #' either \code{grad = "v2"} or \code{"v3"} must be indicated. +#' If \code{"v3"}, the number of components will forced to be 3. #' #' @param eq.mean A logical; the flag whether to make all of the mean values of #' the normal distributions of the components to be equal. #' @param eq.sd A logical; the flag whether to make all of the standard deviations of #' the normal distributions of the components to be equal. #' @param start.level An integer from \code{0} to \code{3} or \code{NA}; -#' the level at which to guess -#' the initial \code{start} parameters of \code{\link[stats]{nls}}. +#' the desired level at which to guess +#' the initial \code{start} parameters for \code{\link[stats]{nls}}. #' -#' Details for each level are as: +#' The detail of each level is: #' \itemize{ #' \item from \code{0} to \code{3}: #' Same as \code{start.level} in arguments of \code{\link[ggd]{nls.freq}}. -#' \item \code{NA}: All values of \code{start} will be set to \code{NA}. +#' \item \code{NA}: All elements in \code{start} will be \code{NA}. #' } -#' @return A list containing \code{formula} and \code{start} for the arguments of -#' \code{\link[stats]{nls}} and adopted \code{start.level} value. +#' @return A list containing \code{formula} and \code{start} for \code{\link[stats]{nls}} +#' and adopted \code{start.level}. +#' The value of \code{start.level} may be different from the argument value +#' if initial guessing has failed at the desired level. #' @importFrom stats dnorm pnorm ################################################################################################ get.nls.params <- function( x, freq, total, mix.type, grad, eq.mean, eq.sd, start.level ) @@ -1278,13 +1350,13 @@ get.nls.params <- function( x, freq, total, mix.type, grad, eq.mean, eq.sd, star data.mean <- sum( x * freq ) / total data.sd <- sqrt( sum( ( data.mean - x )^2 * freq ) / total ) - # Exclude data with 0 or extremely small frequency on both edges of + # Exclude data with 0 or extremely small frequencies on both edges of # the range of the x-coordinates. x.freq <- exclude.freq.edge( x, freq ) - # Quarter the vectors of the frequency distribution and get initial values. + # Quarter the vectors of the frequency distribution and get start values. # - # The initial values are as: + # The start values are as: # means, sqrt.sds: # The mean values and sqrt of standard deviations corresponding to each of the four # quarterings of the range of the frequency distribution in ascending order of x. @@ -1312,7 +1384,7 @@ get.nls.params <- function( x, freq, total, mix.type, grad, eq.mean, eq.sd, star } else if ( start.level == 0 ) { - # Level 0: use global mean value and standard deviation for all initial values. + # Level 0: use global mean value and standard deviation for all start values. means <- rep( data.mean, 4 ) sqrt.sds <- rep( sqrt( data.sd ), 4 ) @@ -1325,7 +1397,7 @@ get.nls.params <- function( x, freq, total, mix.type, grad, eq.mean, eq.sd, star else if ( start.level == 1 ) { # Level 1: compute local mean values and standard deviations. - sep <- separate.data.quarter( x.freq$x, x.freq$freq, data.mean ) + sep <- divide.data.quarter( x.freq$x, x.freq$freq, data.mean ) mean.lower <- sum( sep$x.lower * sep$data.lower ) / sum( sep$data.lower ) mean.upper <- sum( sep$x.upper * sep$data.upper ) / sum( sep$data.upper ) @@ -1358,7 +1430,7 @@ get.nls.params <- function( x, freq, total, mix.type, grad, eq.mean, eq.sd, star { # Level 2: pick up 2 quantiles for each component. freq.ps <- get.p.freq( x.freq$freq, total ) - sep <- separate.data.quarter( x.freq$x, freq.ps, data.mean ) + sep <- divide.data.quarter( x.freq$x, freq.ps, data.mean ) lengths <- vapply( 1:4, function( i ) length( sep$x[[i]] ), 0 ) ms <- lapply( 1:4, function( i ) @@ -1475,21 +1547,24 @@ get.nls.params <- function( x, freq, total, mix.type, grad, eq.mean, eq.sd, star # via Mean of 2 Normal Distributions if ( eq.sd ) { - fm <- d ~ ( dnorm( x, mean.1, sqrt.sd^2 ) + dnorm( x, mean.2, sqrt.sd^2 ) ) / 2 + fm <- d ~ ( dnorm( x, mean.1, sqrt.sd^2 ) + + dnorm( x, mean.2, sqrt.sd^2 ) ) / 2 start <- list( mean.1 = mean.lower, mean.2 = mean.upper, sqrt.sd = sqrt.sds.mid ) } else if ( eq.mean ) { - fm <- d ~ ( dnorm( x, mean, sqrt.sd.1^2 ) + dnorm( x, mean, sqrt.sd.2^2 ) ) / 2 + fm <- d ~ ( dnorm( x, mean, sqrt.sd.1^2 ) + + dnorm( x, mean, sqrt.sd.2^2 ) ) / 2 start <- list( mean = means.mid[1], sqrt.sd.1 = sqrt.sd.outer, sqrt.sd.2 = sqrt.sd.inner ) } else { - fm <- d ~ ( dnorm( x, mean.1, sqrt.sd.1^2 ) + dnorm( x, mean.2, sqrt.sd.2^2 ) ) / 2 + fm <- d ~ ( dnorm( x, mean.1, sqrt.sd.1^2 ) + + dnorm( x, mean.2, sqrt.sd.2^2 ) ) / 2 start <- list( mean.1 = means.mid[1], mean.2 = means.mid[2], sqrt.sd.1 = sqrt.sd.outer, @@ -1666,9 +1741,9 @@ get.nls.params <- function( x, freq, total, mix.type, grad, eq.mean, eq.sd, star } ################################################################################################ -#' [Non-exported] Exclude small frequencies of edges +#' [Non-exported] Exclude small frequencies on edges #' -#' Excludes data with \code{0} or extremely small frequency on both edges of the range of +#' Excludes data with \code{0} or extremely small frequencies on both edges of the range of #' the x-coordinates from data of a frequency distribution. #' @usage exclude.freq.edge(x, freq) #' @param x A vector of x-coordinates of a frequency distribution. @@ -1694,10 +1769,10 @@ exclude.freq.edge <- function( x, freq ) #' at first, it divides the data into two groups by the mean of the data, #' and next, divides each data into two groups so that the number of elements are equal to #' each other. -#' If there is an x-coordinate that is exactly equal to the mean, -#' put that element in both the 2nd and 3rd part. -#' If the first dividing makes a group with odd number of elements, put the element at -#' the dividing point in both the lower and upper x-coordinate groups after second dividing. +#' If there is an x-coordinate equal to the mean, +#' the element is included in both of the 2nd and 3rd groups. +#' In the second division, if the original group has an odd number of elements, +#' the element at the dividing point is included in both divided groups. #' @param x A vector of x-coordinates arranged in ascending order #' and non-duplicated. #' @param data A vector of numeric values of the data with respect to x-coordinates. @@ -1717,7 +1792,7 @@ exclude.freq.edge <- function( x, freq ) #' The vector of x-coordinates or data integrated the inner-side 2 groups.} #' @importFrom utils head tail ################################################################################################ -separate.data.quarter <- function( x, data, data.mean ) +divide.data.quarter <- function( x, data, data.mean ) { xl <- dl <- list( numeric(), numeric(), numeric(), numeric() ) @@ -1766,8 +1841,6 @@ separate.data.quarter <- function( x, data, data.mean ) #' with the result of \code{\link[stats]{nls}}. #' @param mix.type The value for \code{mix.type} field. #' @param grad A character string indicating the method of gradation. -#' If \code{"v3"}, constructing with 3 components is enforcedly, -#' even if it is possible to construct with 2 components. #' #' In this function, \code{grad} argument has no priority over #' \code{mix.type} argument. @@ -1775,6 +1848,8 @@ separate.data.quarter <- function( x, data, data.mean ) #' only if \code{mix.type = 3} is indicated. #' And if \code{mix.type = 3} is indicated, #' either \code{grad = "v2"} or \code{"v3"} must be indicated. +#' If \code{"v3"}, the number of components will forced to be 3, +#' even if the values in \code{coefs} represent a 2-component model. #' #' @param eq.mean A logical; the flag whether to make all of the mean values of #' the normal distributions of the components to be equal. @@ -1895,11 +1970,12 @@ get.cmp.with.nls.coef <- function( coefs, mix.type, grad, eq.mean, eq.sd ) #' @param freq The vector of the frequencies of the frequency distribution. #' @param total Total value of the frequencies. #' @param cor.method The \code{method} argument for \code{\link[stats]{cor}}. -#' It represents the correlation coefficient method. -#' If \code{NULL}, it uses the default method of \code{\link[stats]{cor}}. +#' It is a character string indicating which correlation coefficient +#' (or covariance) is to be computed. +#' If \code{NULL}, it uses the default \code{method}. #' See \code{\link[stats]{cor}} for more information. #' @return A vector of correlation coefficients. -#' Its order follows the order of the elements of the \code{objs} argument. +#' Its order follows the order of the elements in \code{objs} argument. #' If \code{cmp} field of an \code{\link[ggd]{GGD}} object in \code{objs} has no rows, #' \code{NA} will be set to the element. #' @importFrom stats cor @@ -1908,12 +1984,11 @@ get.cmp.with.nls.coef <- function( coefs, mix.type, grad, eq.mean, eq.sd ) #' freq = c( 1517, 2292, 2513, 2763, 3724, 4046, 4713, #' 7947, 10997, 11824, 11133, 7868, 4692, 4103, #' 3698, 2740, 2549, 2284, 1499, 1147, 918 ) ) -#' a <- ggd.nls.freq( df, kind = "Mean-Eq.*Vertical" )$obj -#' ggd.cor.vs.freq( a, df$x, df$freq ) -#' #' objs <- list( ggd.nls.freq( df, kind = "Mean-Eq.*Vertical" )$obj, #' ggd.nls.freq( df, kind = "Sigma-Eq.*Vertical" )$obj, -#' ggd.nls.freq( df, kind = "Mean-Diff.*Sigma-Diff.*Vertical" )$obj ) +#' ggd.nls.freq( df, kind = "Vertical" )$obj ) +#' +#' ggd.cor.vs.freq( objs[[1]], df$x, df$freq ) #' ggd.cor.vs.freq( objs, df$x, df$freq ) ################################################################################################ ggd.cor.vs.freq <- function( objs, x, freq, total = sum( freq ), cor.method = NULL ) @@ -1951,22 +2026,15 @@ ggd.cor.vs.freq <- function( objs, x, freq, total = sum( freq ), cor.method = NU ################################################################################################ #' Initialize start for ggd.nls.freq.all #' -#' Generates a list of 16 (= \code{length(ggd:::kinds)}) \code{NULL} lists. -#' -#' If you want to indicate some \code{start} lists for \code{\link[ggd]{ggd.nls.freq.all}} -#' by yourself, you can give the lists to the elements of the returned list of this function, -#' and give it to \code{\link[ggd]{ggd.nls.freq.all}} as \code{start} argument. -#' -#' You don't have to set all elements of the returned list by yourself, -#' since internally calculated default values will be used for \code{start} of -#' \code{\link[stats]{nls}} where the elements of the list are \code{NULL}. -#' -#' The format of each element can be got with \code{\link[ggd]{ggd.start.template}}. -#' In addition, \code{\link[ggd]{ggd.kind}} and \code{\link[ggd]{ggd.kind.index}} functions -#' may help you to know the kind of distribution which the index number represents. +#' Generates a list of 16 \code{NULL} lists. +#' If you want to indicate some start values for \code{\link[ggd]{ggd.nls.freq.all}}, +#' insert a list of the start values instead of \code{NULL} at some elements of +#' the 16-\code{NULL} list and use it as \code{start} argument. +#' For more information about the format of each element and other details, +#' see \code{\link[ggd]{ggd.start.template}} and \code{\link[ggd]{ggd.nls.freq.all}}. #' @export #' @return An all-\code{NULL} list with the length of 16 (= \code{length(ggd:::kinds)}). -#' @seealso \code{\link[ggd]{ggd.nls.freq.all}}, \code{\link[ggd]{ggd.start.template}} +#' @seealso \code{\link[ggd]{ggd.start.template}}, \code{\link[ggd]{ggd.nls.freq.all}} #' @examples #' ## Let's approximate this frequency distribution. #' df <- data.frame( @@ -1975,21 +2043,21 @@ ggd.cor.vs.freq <- function( objs, x, freq, total = sum( freq ), cor.method = NU #' 7947, 10997, 11824, 11133, 7868, 4692, 4103, #' 3698, 2740, 2549, 2284, 1499, 1147, 918 ) ) #' -#' ## get the initial list +#' ## Get the initial list. #' start.list <- ggd.init.start() #' start.list #' -#' ## check the parameters for ggd:::kinds[14]. +#' ## Check the parameters for ggd:::kinds[14]. #' ggd.start.template( 14 ) #' -#' ## set the start parameters of ggd:::kinds[14] to get better result +#' ## Set the start values of ggd:::kinds[14] to get better result. #' start.list[[14]]$mean.1.1 <- 0.426831 #' start.list[[14]]$mean.1.2 <- -0.130757 #' start.list[[14]]$mean.2.1 <- 0.426831 #' start.list[[14]]$mean.2.2 <- -0.130757 #' start.list[[14]]$sqrt.sd <- sqrt( 0.812744 ) #' -#' ## try ggd.nls.freq.all (the result of ggd:::kinds[14] will be better than ggd:::kinds[8]) +#' ## Run ggd.nls.freq.all (the result of ggd:::kinds[14] will be better than ggd:::kinds[8]). #' result <- ggd.nls.freq.all( df, start.level = 1, start = start.list ) #' result$cor[8] #' result$cor[14] @@ -2002,63 +2070,66 @@ ggd.init.start <- function() ################################################################################################ #' Template for start of nls #' -#' Gets the template for start list for \code{\link[stats]{nls}} -#' when you want to provide your own \code{start} parameters for \code{\link[ggd]{nls.freq}} -#' or \code{\link[ggd]{ggd.nls.freq.all}}. -#' This function can output only one template list at once. -#' So if you want to get several templates for different distribution kinds, -#' call this function one by one for each distribution kind. +#' Gets a template list for \code{start} argument of \code{\link[ggd]{nls.freq}} +#' or for an element of \code{start} argument of \code{\link[ggd]{ggd.nls.freq.all}}. +#' This function can output only one template at a time. +#' So if you want to obtain two or more templates, +#' you should call this function one by one for each one. #' @export -#' @param target A variable that identifies the kind of distribution to which -#' the template applies. The length should be 1. -#' The type of the variable is valid for \code{\link[ggd]{GGD}} object, -#' the string of an element of \code{ggd:::kinds}, or its index number. +#' @param kind A character string or a numeric value or a \code{\link[ggd]{GGD}} object +#' which indicates the kind of distribution model for which the template will +#' be output. The length should be 1. +#' +#' The matching method of \code{kind} follows that of +#' \code{objs} argument of \code{\link[ggd]{ggd.kind.index}}. +#' If it matches to two or more distribution models, +#' this function returns only one template for the first matched model. #' @return A list containing components any of #' \item{mean}{ -#' The start value for mean values common to all normal distributions -#' of the components. 0 is preset.} +#' The start value for the mean value shared by all components. 0 is preset.} #' \item{mean.i}{ -#' The start value for the mean value of i-th normal distribution. +#' The start value for the mean value of the i-th component. #' 0 is preset.} #' \item{mean.i.j}{ -#' The start value for mean value of i,j-th normal distribution +#' The start value for the mean value of the i,j-th component #' in the 2x2 components. 0 is preset.} #' \item{sqrt.sd}{ -#' The sqrt of the start value for standard deviations common to -#' all normal distributions of the components. 1 is preset.} +#' The start value for the square root of the standard deviation shared +#' by all components. 1 is preset.} #' \item{sqrt.sd.i}{ -#' The sqrt of the start values for the standard deviation of -#' i-th normal distribution. 1 is preset.} +#' The start value for the square root of the standard deviation of +#' the i-th component. 1 is preset.} #' \item{sqrt.sd.i.j}{ -#' The sqrt of the start values for the standard deviation of -#' i,j-th normal distribution in the 2x2 components. 1 is preset.} +#' The start value for the square root of the standard deviation of +#' the i,j-th component in the 2x2 components. 1 is preset.} #' -#' If \code{target} represents unsupported distribution kind, \code{NULL} is returned. +#' If \code{kind} represents an unsupported distribution model, +#' \code{NULL} will be returned. #' @seealso \code{\link[ggd]{nls.freq}}, \code{\link[ggd]{ggd.nls.freq.all}}, #' \code{\link[ggd]{ggd.init.start}} #' @examples -#' ## preparing +#' ## Preparing: #' x <- seq( -2, 2, 0.2 ) #' freq <- c( 1517, 2292, 2513, 2763, 3724, 4046, 4713, #' 7947, 10997, 11824, 11133, 7868, 4692, 4103, #' 3698, 2740, 2549, 2284, 1499, 1147, 918 ) #' -#' ## set the start parameters +#' ## Set the start values. #' start <- ggd.start.template( 14 ) -#' start ## check the parameters for the start of ggd:::kinds[14] +#' start ## Check the parameters for the 'start' of ggd:::kinds[14]. #' #' start$mean.1.1 <- -0.671 #' start$mean.1.2 <- -0.198 #' start$mean.2.1 <- 0.293 #' start$mean.2.2 <- -0.198 -#' start$sqrt.sd <- sqrt( 0.640 ) ## sqrt.sd is the square root of the standard deviation. +#' start$sqrt.sd <- sqrt( 0.640 ) ## 'sqrt.sd' is the square root of the standard deviation. #' -#' ## try ggd.nls.freq +#' ## Run ggd.nls.freq. #' ggd.nls.freq( data.frame( x, freq ), start = start, kind = 14 )$obj ################################################################################################ -ggd.start.template <- function( target ) +ggd.start.template <- function( kind ) { - kind.index <- ggd.kind.index( target, undef.err = FALSE )[1] + kind.index <- ggd.kind.index( kind, undef.err = FALSE )[1] if ( is.na( kind.index ) || is.null( kind.index ) ) { return ( NULL ) diff --git a/R/ggd.set.cmp.R b/R/ggd.set.cmp.R index 5442503..2f69232 100644 --- a/R/ggd.set.cmp.R +++ b/R/ggd.set.cmp.R @@ -12,10 +12,11 @@ ################################################################################################ #' Setting components #' -#' Sets the normal distributions of the components to the \code{cmp} field. -#' All fields of the \code{\link[ggd]{GGD}} object will be set as appropriate according to -#' given components and other arguments, respectively. -#' You should never set any values into the \code{cmp} field directly without using this method. +#' Generates a \code{\link[ggd]{GGD}} object according to indicated values of \code{cmp} field +#' (\code{ggd.set.cmp}), or sets the values in \code{cmp} field and all of other fields +#' accordingly (\code{set.cmp}). +#' Whenever you want to set values in \code{cmp} field, it is strongly recommended to use +#' this method. #' @export #' @name set.cmp #' @aliases ggd.set.cmp @@ -27,9 +28,9 @@ #' this.kind = NULL, this.mix.type = NULL, #' grad = c("default", "normal", "h", "v", "v2", "v3", "hv")) #' -#' @param cmp A data frame for setting into the \code{cmp} field. +#' @param cmp A data frame for \code{cmp} field. #' -#' It must have just 2 columns named "\code{mean}" and "\code{sd}", +#' It must have just 2 columns named \code{"mean"} and \code{"sd"}, #' and its rows must be less than or equals to 4. #' Row names are not required. #' @@ -43,10 +44,10 @@ #' but indicating \code{NULL} or having no columns is not allowed. #' #' @param kind A character string or a numeric value or a \code{\link[ggd]{GGD}} object -#' which indicates the kind of the distribution model to create. +#' which indicates the kind of distribution model to be generated. #' -#' The matching method of this argument follows that of elements of -#' the \code{objs} argument of the \code{\link[ggd]{ggd.kind.index}}. +#' The matching method of \code{kind} follows that of +#' \code{objs} argument of \code{\link[ggd]{ggd.kind.index}}. #' \code{NA} is allowed when \code{cmp} has no rows. #' #' If \code{mix.type} argument or other than \code{"default"} for @@ -55,10 +56,10 @@ #' @param mix.type A numeric value represents how to mix the normal distributions. #' #' The type of the distribution model and the number of rows in \code{cmp} -#' will be represented with \code{mix.type} value as follows: +#' follow \code{mix.type} as: #' \itemize{ #' \item \code{0} : Normal distribution. \code{cmp} has only 1 row. -#' \item \code{1} : Mean of 2 normal distributions (not a GGD). +#' \item \code{1} : Mean of 2 normal distributions. #' \code{cmp} has 2 rows. #' \item \code{2} : Horizontal gradational distribution. #' \code{cmp} has 2 rows. @@ -69,13 +70,13 @@ #' } #' #' If the number of rows in \code{cmp} argument is different from -#' the number shown above, the \code{cmp} field will be +#' the number shown above, \code{cmp} field will be #' redundant/simplified to have the number of rows as above, #' if possible. If not possible, an error will occur. #' #' You can indicate \code{mix.type = NA} only if \code{cmp} has no rows. #' -#' If other than \code{"default"} for \code{grad} argument is indicated, +#' If \code{grad} argument other than \code{"default"} is indicated, #' this argument will be ignored. #' #' @param grad A character string indicating the method of gradation. @@ -86,55 +87,54 @@ #' Numberless \code{"v"} is an alias for \code{"v2"}. #' #' \code{"normal"} is for a normal distribution, -#' then also, \code{'grad = "no"'} can be read as "no gradation". +#' then also, \code{'grad = "no"'} can be read as 'no gradation'. #' #' \code{"default"} is, if \code{kind} or \code{mix.type} argument #' is given, follows it, otherwise it depends on the number of columns -#' in the \code{cmp} argument. If the number of columns in cmp is \code{2}, +#' in \code{cmp} argument. If the number of columns in cmp is \code{2}, #' the current \code{mix.type} is retained or horizontal (default) is used. #' -#' @param this.cmp A data frame for setting into the \code{cmp} field. -#' It is equivalent to \code{cmp} argument for \code{ggd.set.cmp}. +#' @param this.cmp A data frame for setting into \code{cmp} field. +#' It is equivalent to \code{cmp} argument of \code{ggd.set.cmp}. #' #' @param this.kind A string or a numeric value or a \code{\link[ggd]{GGD}} object -#' which indicates the kind of the distribution model. -#' It is equivalent to \code{kind} argument for \code{ggd.set.cmp}. +#' which indicates the kind of distribution model to be constructed. +#' It is equivalent to \code{kind} argument of \code{ggd.set.cmp}. #' #' @param this.mix.type A numeric value represents how to mix the normal distributions. -#' It is equivalent to \code{mix.type} argument for \code{ggd.set.cmp}. +#' It is equivalent to \code{mix.type} argument of \code{ggd.set.cmp}. #' #' @return The \code{\link[ggd]{GGD}} object itself (invisible for \code{GGD} method). #' -#' For \code{GGD} method: If an error occur, each value of field will not be changed. +#' For \code{GGD} method: If an error occurs, each value of field will not be changed. #' #' @importFrom methods new #' #' @details -#' \subsection{About "kind" and "mix.type"}{ -#' In this function, \code{[this.]kind} argument is, unlike \code{\link[ggd]{trace.q}} -#' and \code{\link[ggd]{nls.freq}} methods, used only to determine how to mix -#' the normal distributions of the components. -#' That is, \code{[this.]kind} argument is used only to determine the new value of -#' \code{mix.type} field, and has no effect on the unification of the mean values and -#' the standard deviations of the components. -#' -#' So, the new value of \code{kind} field of the object may not be matched with -#' the indicated value of \code{[this.]kind} argument. +#' \subsection{About 'kind' and 'mix.type'}{ +#' In this function, +#' unlike \code{\link[ggd]{trace.q}} and \code{\link[ggd]{nls.freq}} methods, +#' \code{[this.]kind} argument is only used to determine \code{mix.type} value, +#' which represents how to mix the normal distributions of the components. +#' That is, \code{[this.]kind} argument has no effect to align the mean values or +#' standard deviations of the components to be equal. +#' +#' So, a regular expression indicated as \code{[this.]kind} argument may not match +#' the new value of \code{[this.]kind} field. #' For example, if you indicate \code{[this.]kind = "Mean-Eq.*Horizontal"} and #' \code{[this.]cmp = data.frame(mean = c(0, 1), sd = c(0.8, 1.2))}, #' the new \code{kind} field will be #' \code{"Mean-Differed Sigma-Differed Horizontal Gradational Distribution"}, -#' which is not matched with \code{"Mean-Eq.*Horizontal"}. +#' which is not matched with indicated regular expression. +#' In such a case, a warning will occur. #' -#' In such a case, i.e. if indicated \code{[this.]kind} does not match -#' to the new value of \code{kind} field, a warning will occur. -#' But when a \code{\link[ggd]{GGD}} object is indicated for \code{[this.]kind}, -#' no warning will occur if the unification of the mean values and standard deviations of -#' the components are different between the indicated object and the result. -#' Indicated object is regarded as just for specifying new \code{mix.type}. +#' On the other hand, when a \code{\link[ggd]{GGD}} object is +#' indicated as \code{[this.]kind}, no warning will occur if the new \code{kind} field +#' is different from that of the indicated object. +#' Indicated object is regarded as just for specifying \code{mix.type} value. #' -#' It is not recommended but if you indicate both of -#' \code{[this.]kind} and \code{[this.]mix.type} at once with not-\code{NULL} values, +#' It is not recommended but if you indicate not-\code{NULL} values for both of +#' \code{[this.]kind} and \code{[this.]mix.type} at once, #' \code{[this.]kind} will be ignored. #' #' If both \code{[this.]kind} and \code{[this.]mix.type} arguments are \code{NULL} @@ -155,77 +155,91 @@ #' @examples #' ## Normal Distribution #' a <- ggd.set.cmp( data.frame( mean = 0, sd = 1.5 ) ) -#' a$mix.type; a$cmp +#' a$kind; a$mix.type; a$cmp #' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) #' -#' ## "normal" for "grad" argument is allowed, though, it does little work in this function. +#' ## Indicating "normal" for 'grad' argument is allowed. However, in this function, +#' ## it works only to assert that 'cmp' represents a normal distribution. #' a <- ggd.set.cmp( data.frame( mean = 1, sd = 2 ), grad = "normal" ) -#' a$mix.type; a$cmp +#' a$kind; a$mix.type; a$cmp +#' +#' ## Where the number of rows in the 'cmp' argument is 2, +#' ## it is recommended to indicate 'grad' or 'mix.type' or 'kind' to avoid confusing. #' -#' ## Where the number of the cmp field rows is 2, -#' ## it is recommended to indicate "grad" or "mix.type" or "kind" to avoid confusing. +#' ## Mean of 2 normal distributions (mix.type = 1) +#' ## is not a gradational Gaussian distribution (GDD), +#' ## but a kind of Gaussian mixture model (GMM). #' rm( a ) #' a <- ggd.set.cmp( data.frame( mean = c( 0, 0 ), sd = c( 1.2, 0.8 ) ), -#' kind = "Mean of Mean-Equaled Sigma-Differed 2 Normal Distributions" ) -#' a$mix.type; a$cmp +#' kind = "Mean of.*2 Normal Distributions" ) +#' a$kind; a$mix.type; a$cmp #' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) #' #' ## Changing to mix.type = 2 : Horizontal Gradational Distribution -#' a$set.cmp( a$cmp, this.mix.type = 2 ) -#' a$mix.type; a$cmp +#' ## while retaining 'cmp' field. +#' a$set.cmp( this.mix.type = 2 ) +#' a$kind; a$mix.type; a$cmp #' #' ## You can also write as: -#' a$set.cmp( a$cmp, grad = "h" ) -#' a$mix.type; a$cmp +#' a$set.cmp( grad = "h" ) +#' a$kind; a$mix.type; a$cmp #' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) #' -#' ## kind.index = 9 : 2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution -#' a$set.cmp( a$cmp, this.kind = 9 ) -#' a$mix.type; a$cmp +#' ## kind = 9 : '2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution' +#' ## +#' ## You can also write as 'this.kind = "2.*Vertical"' or 'this.mix.type = 3' or 'grad = "v2"' +#' ## instead of 'this.kind = 9'. +#' a$set.cmp( this.kind = 9 ) +#' a$kind; a$mix.type; a$cmp #' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) #' -#' ## 3-Mean-Differed Sigma-Differed Vertical Gradational Distribution +#' ## You can generate a same kind object with indicating a GGD object for 'kind' argument. +#' b <- ggd.set.cmp( data.frame( mean = c( -1, -1 ), sd = c( 1.2, 0.4 ) ), kind = a ) +#' b$kind; b$mix.type; b$cmp +#' plot( seq( -3, 3, 0.01 ), b$d( seq( -3, 3, 0.01 ) ), type = "l" ) +#' +#' ## Indicating 3 components generates a vertical gradation normally. +#' a$clear() #' a$set.cmp( data.frame( mean = c( -0.5, 0, 0.5 ), sd = c( 1.2, 0.8, 1.2 ) ) ) -#' a$mix.type; a$cmp +#' a$kind; a$mix.type; a$cmp #' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) #' -#' ## Mean-Equaled Sigma-Differed Horizontal-Vertical Gradational Distribution +#' ## Indicating 4 components generates a horizontal-vertical gradation normally. #' a$set.cmp( data.frame( mean = c( 0, 0, 0, 0 ), sd = c( 0.7, 0.5, 2.0, 1.5 ) ) ) -#' a$mix.type; a$cmp +#' a$kind; a$mix.type; a$cmp #' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) #' -#' ## If "cmp" field can be simplified, "mix.type" field may be set to lower type. +#' ## If 'cmp' field can be simplified, the number of components is automatically reduced, +#' ## and 'mix.type' field follows the reduction. #' a$set.cmp( data.frame( mean = c( 0, 0, 0, 0 ), sd = c( 1, 0.7, 1, 0.7 ) ) ) +#' a$kind ## '2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution' #' a$mix.type ## 3 (not 4) #' a$cmp ## with 2 rows #' -#' ## If you want not to simplify "mix.type" and "cmp" fields, -#' ## indicate "mix.type" / "this.mix.type" or one of other arguments for the condition. -#' +#' ## If you want not to simplify 'cmp' field, +#' ## indicate '[this.]kind' or '[this.]mix.type' or 'grad' argument for the condition. #' a$set.cmp( data.frame( mean = c( 0, 0, 0, 0 ), sd = c( 1, 0.7, 1, 0.7 ) ), #' this.mix.type = 4 ) +#' a$kind ## '2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution' #' a$mix.type ## 4 #' a$cmp ## with 4 rows #' #' ## You can also write as: #' a$set.cmp( data.frame( mean = c( 0, 0, 0, 0 ), sd = c( 1, 0.7, 1, 0.7 ) ), #' grad = "hv" ) -#' a$mix.type; a$cmp +#' a$kind; a$mix.type; a$cmp #' -#' ## The "kind" / "this.kind" argument can also indicate -#' ## how to mix the normal distributions of the components. +#' ## You can also use '[this.]kind' argument to avoid simplifying. +#' ## However, if the indicated regular expression for '[this.]kind' argument does not match +#' ## the resulting 'kind' field, a warning will occur. +#' ## For avoiding confusing, using '[this.]mix.type' or 'grad' argument is recommended. #' ## -#' ## However, if the components indicated by "cmp" or "this.cmp" are inconsistent -#' ## with the value of "kind" / "this.kind" argument, -#' ## the "kind" and "kind.index" fields will be set to different values with a warning. -#' ## For avoiding confusing, you should use "mix.type" / "this.mix.type" or "grad" instead. -#' -#' ## This sample will work with a warning. +#' ## This sample will work with a warning; +#' ## because 'this.kind' argument does not match the resulting 'kind' field. #' a$set.cmp( #' this.cmp = data.frame( mean = c( 0, 0, 0, 0 ), sd = c( 1, 0.7, 1, 0.7 ) ), -#' this.kind = "Mean-Equaled Sigma-Differed Horizontal-Vertical" ) -#' a$mix.type ## 4 -#' a$kind ## "2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution" +#' this.kind = "Horizontal-Vertical" ) +#' a$kind; a$mix.type; a$cmp ################################################################################################ ggd.set.cmp <- function( cmp, kind = NULL, mix.type = NULL, grad = c( "default", "normal", "h", "v", "v2", "v3", "hv" ) ) @@ -245,7 +259,7 @@ GGD$methods( # Error-check for this.cmp. # # This process must be executed before initializing the fields - # for safty of the data copy process + # for safety of the data copy process # (strictly, some processes using this.cmp must be executed before initializing). if ( !is.data.frame( this.cmp ) ) { @@ -298,6 +312,22 @@ GGD$methods( { stop( paste( "Error: kind should be valid single value or a GGD object." ) ) } + else if ( length( this.kind.index ) == 1 && !is.na( this.kind.index ) ) + { + # Set "v2" or "v3" to grad by this.kind + # (but if this.mix.type is indicated, it takes priority) + if ( grad == "default" && is.null( this.mix.type ) ) + { + if ( any( this.kind.index == 8:10 ) ) + { + grad <- "v2" + } + else if ( any( this.kind.index == 11:13 ) ) + { + grad <- "v3" + } + } + } } # Check this.mix.type @@ -351,11 +381,11 @@ GGD$methods( backup <- copy() # backup for rollback - # Fix current mix.type field and set indicated cmp field. + # Fix current 'mix.type' field and set indicated 'cmp' field. mix.type <<- tent.mix.type cmp <<- this.cmp - # Adjust mix.type and cmp fields. + # Adjust 'mix.type' and 'cmp' fields. result <- try( adjust.cmp( new.mix.type, grad ), silent = TRUE ) if ( inherits( result, "try-error" ) ) { @@ -387,7 +417,7 @@ GGD$methods( ( is.character( this.kind[[1]] ) && length( grep( this.kind[[1]], kind ) ) == 0 ) ) ) { - warning( paste( "Warning: Indicated kind does not match to the result." ) ) + warning( paste( "Warning: Indicated kind does not match the result." ) ) } # Set median, mean, sd and its family. @@ -451,20 +481,20 @@ GGD$methods( #' } #' #' @examples -#' ## Usually the cmp field is simplified automatically, +#' ## Usually 'cmp' field is simplified automatically, #' ## so you do not have to call adjust.cmp by your own. #' ## For example, in this case, #' ## the number of components is simplified to 1 automatically. #' a <- ggd.set.cmp( data.frame( mean = c( 0, 0 ), sd = c( 1.1, 1.1 ) ) ) -#' a$kind; a$mix.type; a$cmp ## mix.type = 0 represents a Normal Distribution. +#' a$kind; a$mix.type; a$cmp ## mix.type = 0: a Normal Distribution #' #' ## GGD$new() makes 2 components of normal distributions for convenience. -#' ## You can use adjust.cmp in order to adjust the cmp field of a new object to 1 component. +#' ## You can use adjust.cmp in order to adjust 'cmp' field of a new object to 1 component. #' a <- GGD$new() -#' a$kind; a$mix.type; a$cmp ## mix.type = 2 represents a Horizontal Gradational Model. +#' a$kind; a$mix.type; a$cmp ## mix.type = 2: Horizontal Gradational Distribution #' #' a$adjust.cmp() -#' a$kind; a$mix.type; a$cmp ## mix.type = 0 represents a Normal Distribution. +#' a$kind; a$mix.type; a$cmp ## mix.type = 0: Normal Distribution #' #' ## You can also write as: #' a <- GGD$new()$adjust.cmp() @@ -473,15 +503,15 @@ GGD$methods( #' ## If you want to give redundancy to the components, you can also use adjust.cmp. #' ## Normal Distribution with 2 components. #' a$adjust.cmp( this.mix.type = 1 ) -#' a$kind; a$mix.type; a$cmp ## mix.type = 1 represents a Gaussian Mixture Model. +#' a$kind; a$mix.type; a$cmp ## mix.type = 1: Mean of 2 Normal Distributions #' #' ## Normal Distribution with 3 components. #' a$adjust.cmp( grad = "v3" ) -#' a$kind; a$mix.type; a$cmp ## mix.type = 3 represents a Vertical Gradational Model. +#' a$kind; a$mix.type; a$cmp ## mix.type = 3: Vertical Gradational Distribution #' #' ## Normal Distribution with 4 components. #' a$adjust.cmp( grad = "hv" ) -#' a$kind; a$mix.type; a$cmp ## mix.type = 4 represents a H-V Gradational Model. +#' a$kind; a$mix.type; a$cmp ## mix.type = 4: H-V Gradational Distribution ################################################################################################ NULL GGD$methods( @@ -522,7 +552,7 @@ GGD$methods( "cmp has no rows." ) ) } - # First, optimize the components of the "cmp" field. + # First, optimize the components of cmp field. current.mix.type <- integer() # current essential mix type; the distribution model cmp.rows <- nrow( cmp ) means <- cmp$mean @@ -530,7 +560,7 @@ GGD$methods( if ( cmp.rows > 4 ) { - # 5 and more rows in "cmp" field are not allowed. + # 5 and more rows in cmp field are not allowed. warning( paste( "Warning: The number of the cmp field rows is too large.", "5th and after rows are discarded." ) ) cmp.rows <- 4 @@ -582,12 +612,13 @@ GGD$methods( else # if ( cmp.rows == 2 ) { # When nrow( cmp ) == 2 and not a normal distribution, - # if current mix.type is strange, an error occur + # if the current mix.type is strange, an error occurs # even if a valid this.mix.type is indicated. # - # Because it may affect to the substance of the distribution - # to set the valid mix.type. - if ( length( mix.type ) == 0 || is.na( mix.type ) || !any( mix.type == 1:3 ) ) + # Because setting a valid value to mix.type field + # may affect the substance of the distribution. + if ( length( mix.type ) == 0 || is.na( mix.type ) || + !any( mix.type == 1:3 ) ) { stop( "Error: Cannot identify current mix.type." ) } @@ -598,14 +629,14 @@ GGD$methods( new.mix.type <- current.mix.type # the new value for mix.type - # Second, give redundancy to the "cmp" if this.mix.type or grad argument is given. + # Second, give redundancy to cmp if this.mix.type or grad argument is given. if ( length( this.mix.type ) > 0 ) { # new.ncmp: number of cmp rows to have new.ncmp <- ggd.ncmp.for( grad, mix.type = this.mix.type ) - # The normal distribution can enhanse to any other type. - # On the other hand, that of mix.type = 1 cannot enhanse to any other type. + # The normal distribution can enhance to any other type. + # On the other hand, that of mix.type = 1 cannot enhance to any other type. if ( current.mix.type == 0 ) { new.mix.type <- as.integer( this.mix.type ) diff --git a/R/ggd.tex.R b/R/ggd.tex.R index 1ec8601..f742df0 100644 --- a/R/ggd.tex.R +++ b/R/ggd.tex.R @@ -114,19 +114,19 @@ tex.p.sub <- list ( list( # 2 components and common c( paste0( "\\Phi_i(x) &= \\dfrac{1}{\\sqrt{2 \\pi \\sigma_i^2}} ", - "\\int_{-\\infty}^{x} ", - "\\exp \\left( -\\dfrac{(t - \\mu_i)^2}{2 \\sigma_i^2} \\right) ", - "dt;\\\\" ), + "\\int_{-\\infty}^{x} ", + "\\exp \\left( -\\dfrac{(t - \\mu_i)^2}{2 \\sigma_i^2} \\right) ", + "dt;\\\\" ), paste0( "\\Phi^\\ast_i(x) &= \\dfrac{1}", - "{\\sqrt{2 \\pi \\left( ", - "%begin-frac-env%\\dfrac{\\sigma_i}{\\sqrt{2}} ", - "%end-frac-env%\\right)^2}} ", - "\\int_{-\\infty}^{x} ", - "\\exp \\left( %begin-frac-env%-\\dfrac{(t - \\mu_i)^2}", - "{2 \\left( %begin-frac-env%\\dfrac{\\sigma_i}", - "{\\sqrt{2}} %end-frac-env%\\right)^2} %end-frac-env%", - "\\right) dt;\\\\" ) ), + "{\\sqrt{2 \\pi \\left( ", + "%begin-frac-env%\\dfrac{\\sigma_i}{\\sqrt{2}} ", + "%end-frac-env%\\right)^2}} ", + "\\int_{-\\infty}^{x} ", + "\\exp \\left( %begin-frac-env%-\\dfrac{(t - \\mu_i)^2}", + "{2 \\left( %begin-frac-env%\\dfrac{\\sigma_i}", + "{\\sqrt{2}} %end-frac-env%\\right)^2} %end-frac-env%", + "\\right) dt;\\\\" ) ), # 3 components only c( paste0( "\\Psi_1(x) &= \\mathrm{min} \\left( ", @@ -205,9 +205,9 @@ tex.end.frac.env = c( "array" = "\\\\end{array} ", ################################################################################################ #' Output TeX format #' -#' Outputs the TeX-formatted texts of the formulas for the probability density function +#' Outputs the TeX-formatted texts of the formulas of the probability density function #' \eqn{g(x)} and the cumulative distribution function \eqn{\Psi(x)} -#' with \code{\link[base]{writeLines}}. +#' using \code{\link[base]{writeLines}}. #' @name tex #' @aliases tex #' @aliases tex.d @@ -224,59 +224,43 @@ tex.end.frac.env = c( "array" = "\\\\end{array} ", #' @usage \S4method{tex.p}{GGD}(con = stdout(), sep = "\n", comma = TRUE, #' format.num = function(x) format(x), #' frac.env = c("array", "aligned", "gathered", "default")) -#' @param con A \code{\link[base]{connection}} object or a character to indicate -#' the output destination. -#' See "Details" at \code{\link[base]{writeLines}} +#' @param con A \code{\link[base]{connection}} object or a character string +#' to indicate the output destination. +#' See 'Details' at \code{\link[base]{writeLines}} #' for more information. -#' @param sep A string to be written to the connection after each line of text. -#' See "Details" at \code{\link[base]{writeLines}} +#' @param sep A character string to be written to the connection after each line +#' of text. See 'Details' at \code{\link[base]{writeLines}} #' for more information. -#' @param comma A logical. If \code{TRUE}, this method writes "," as a separator -#' between each expression and "." at the end of output. -#' If \code{FALSE}, "," for the separator of expressions -#' and the final "." are not written. -#' @param format.num A function to format each number of value of a parameter; -#' mean value and standard deviation. -#' It should be a function with one argument for the number +#' @param comma A logical. If \code{TRUE}, this method writes a ',' (comma) +#' as a separator between each expression and a '.' (period) +#' at the end of the output. +#' If \code{FALSE}, those ',' and '.' will not be written. +#' @param format.num A function to format each numeric value of mean values and +#' standard deviations. +#' It should be a function with one argument for the value #' to be displayed and returning a character string. -#' @param frac.env The TeX environment for formatting fractions with different heights +#' @param frac.env The TeX environment to format fractions with different heights #' of numerator and denominator. -#' If \code{"default"}, such fractions will be formatted as default of TeX -#' (usually not so beautiful). Which environment is the most beautiful -#' form will depend on the TeX execution environment. +#' If \code{"default"}, such fractions will be formatted +#' in the default style of TeX, but their appearance is usually poor. +#' The environment which produces the most beautiful form +#' will depend on the TeX execution environment. #' @return An invisible \code{NULL}. #' @seealso \code{\link[ggd]{adjust.cmp}}, \code{\link[ggd]{tex.d}}, \code{\link[ggd]{tex.p}} #' @details #' \subsection{Composition of outputs}{ -#' \code{tex} outputs the formulas of both probability density function +#' \code{tex} method outputs the formulas of both probability density function #' and cumulative distribution function. #' -#' Where \code{mix.type} field is from \code{0} to \code{3}, -#' this function outputs 3 parts divided with one empty line as: -#' \itemize{ -#' \item Formulas of the probability density function \eqn{g(x)} -#' and the cumulative distribution function \eqn{\Psi(x)} of the model. -#' \item Formulas of the probability density function \eqn{f_i(x)} -#' and the cumulative distribution function \eqn{\Phi_i(x)} of the components. -#' \item Values of parameters of the mean values \eqn{\mu_i} and -#' the standard deviations \eqn{\sigma_i} of the components. -#' } +#' \code{tex.d} method outputs the formulas of probability density function only. #' -#' Where \code{mix.type = 4}, -#' the formulas of \eqn{g(x)} and \eqn{\Psi(x)} are divided into 2 parts in addition, -#' and subscripts for \eqn{f(x)}, \eqn{\Phi(x)} and parameters are 2 like \eqn{f_{i,j}(x)}. -#' -#' \code{tex.d} outputs the formulas of probability density function only. -#' -#' \code{tex.p} outputs the formulas of cumulative distribution function only. +#' \code{tex.p} method outputs the formulas of cumulative distribution function only. #' #' In these methods, the formulas are output according to \code{mix.type} #' and the number of components in \code{cmp} field, not \code{kind} or \code{kind.index}. #' That is, for example, if the \code{kind} is \code{"Normal Distribution"} #' and \code{mix.type = 2}, #' \code{tex} outputs formulas of a horizontal gradational distribution. -#' In such a case, if you want to display a normal distribution formula, -#' you should simplify \code{mix.type} with \code{\link[ggd]{adjust.cmp}} in advance. #' #' If \code{cmp} field has no rows, nothing is output. #' } @@ -284,17 +268,17 @@ tex.end.frac.env = c( "array" = "\\\\end{array} ", #' \subsection{Equaled mean values or standard deviations}{ #' For clarity, when all mean values or standard deviations of components are equal #' (i.e., when \code{\link[ggd]{is.eq.mean}} or \code{\link[ggd]{is.eq.sd}} method -#' returns \code{TRUE}), they are displayed with "\eqn{=}" to the 1st component parameter, -#' like as "\eqn{\sigma_2 = \sigma_1}". +#' returns \code{TRUE}), they are displayed with '\eqn{=}' to the 1st parameter, +#' like as '\eqn{\sigma_2 = \sigma_1}'. #' #' If only the values of some parameters are equal (e.g., only \eqn{\sigma_2} and #' \eqn{\sigma_3} are equal and \eqn{\sigma_1} is different), -#' they are not displayed as "\eqn{\sigma_3 = \sigma_2}", but displayed with values -#' to avoid misreading the subscripts. +#' each value is displayed as '\eqn{\sigma_2 = x, \sigma_3 = x}' +#' instead of '\eqn{\sigma_3 = \sigma_2}' to avoid misreading. #' #' Note that if the difference between the values of parameters is smaller than -#' displayable number of decimal places, "\eqn{\sigma_2 = \sigma_1}" may not be displayed, -#' but the same number may be displayed for each. +#' displayable number of decimal places, '\eqn{\sigma_2 = \sigma_1}' will not be displayed, +#' but the same number will be displayed for each. #' } #' @examples #' a <- GGD$new() @@ -503,14 +487,14 @@ GGD$methods( ) ################################################################################################ -#' [Non-exported] TeX format for mean and standard deviation +#' [Non-exported] TeX format for mean values and standard deviations #' -#' Gets the TeX-formatted texts to represent the mean values and standard deviations of +#' Gets the TeX-formatted texts representing the mean values and standard deviations of #' the normal distributions of the components. #' @param obj A \code{\link[ggd]{GGD}} object. -#' @param format.num A function to format each number of value of a parameter; -#' mean value and standard deviation. See \code{\link[ggd]{tex}}. -#' @return TeX-formatted texts to represent the mean values and standard deviations of +#' @param format.num A function to format each numeric value of mean values and +#' standard deviations. See \code{\link[ggd]{tex}}. +#' @return TeX-formatted texts representing the mean values and standard deviations of #' the normal distributions of the components. ################################################################################################ get.cmp.tex <- function( obj, format.num ) diff --git a/R/ggd.trace.q.R b/R/ggd.trace.q.R index 13bde87..e4d002e 100644 --- a/R/ggd.trace.q.R +++ b/R/ggd.trace.q.R @@ -14,6 +14,8 @@ #' #' Constructs a \code{\link[ggd]{GGD}} object which traces all of the given quantiles #' accurately with its cumulative distribution function. +#' Then \code{ggd.trace.q} function generates a \code{\link[ggd]{GGD}} object, +#' and \code{trace.q} method sets the fields according to the result. #' @export #' @name trace.q #' @aliases ggd.trace.q @@ -34,9 +36,8 @@ #' and column \bold{\code{p}} is for the probabilities of the quantiles. #' #' Rows which contain \code{NA} or \code{NaN} are ignored. -#' The value of each row must not duplicated -#' (except for \code{NA} or \code{NaN}), -#' and must be valid as a set of quantiles. +#' The set of complete cases must be valid as a set of quantiles +#' and each row of them must not be duplicated. #' You do not have to sort the order of quantiles. #' The number of valid rows must be in range of from 2 to 8. #' @@ -44,42 +45,25 @@ #' \code{data.frame(x = c(0, -2, 2.3), p = c(0.5, 0.25, 0.75))}. #' #' Column names and column numbers for \code{x} and \code{p} are flexible. -#' You can specify them with next two arguments. +#' You can indicate them with next two arguments. #' #' @param x The column name or column number for x-coordinates in \code{quantiles}. #' #' @param p The column name or column number for probabilities in \code{quantiles}. #' #' @param kind A character string or a numeric value or a \code{\link[ggd]{GGD}} object -#' which indicates the kind of the distribution model. -#' -#' The matching method of this argument follows that of elements of -#' the \code{objs} argument of the \code{\link[ggd]{ggd.kind.index}}. +#' which indicates the kind of distribution model to be generated. +#' The matching method of \code{kind} follows that of +#' \code{objs} argument of \code{\link[ggd]{ggd.kind.index}}. #' #' This argument gives the conditions of #' the value of \code{mix.type} field, -#' and of whether the mean values and standard deviations of the components +#' and of whether the mean values or standard deviations of the components #' should be aligned to the same value. #' -#' Indicating \code{mix.type} argument or -#' indicating other than \code{"default"} for \code{grad} argument -#' or \code{TRUE}/\code{FALSE} for \code{eq.mean} or \code{eq.sd} -#' can overwrite the conditions of this argument. -#' -#' @param this.kind A string or a numeric value or a \code{\link[ggd]{GGD}} object -#' which indicates the kind of distribution model to construct. -#' -#' This argument will work as same as \code{kind} argument -#' of the generator function (signature '\code{NULL}'). -#' -#' If this method is called without \code{this.kind} argument, -#' \code{grad}, or other conditions, it attempt to retain the value of -#' \code{mix.type} field as much as possible, but not the value of -#' \code{kind} field, i.e., the condition whether the mean value or -#' standard deviation of each component is aligned may not be retained. -#' If you want to retain the conditions as well, -#' indicate the object itself to \code{this.kind} argument like as -#' \code{obj$trace.q(quantiles, this.kind = obj)}. +#' Indicating \code{mix.type} or \code{grad} other than \code{"default"}, +#' or \code{eq.mean} and \code{eq.sd} other than \code{logical(0)} +#' can overwrite the condition of this argument. #' #' @param mix.type A numeric value to set into \code{mix.type} field as an integer. #' It should be an integer from \code{0} to \code{4} or \code{NULL}. @@ -87,32 +71,22 @@ #' Each value represents the following type of distribution: #' \itemize{ #' \item \code{0} : Normal distribution. -#' \item \code{1} : Mean of 2 normal distributions (not a GGD). +#' \item \code{1} : Mean of 2 normal distributions. #' \item \code{2} : Horizontal gradation of 2 normal distributions. #' \item \code{3} : Vertical gradation of 2 or 3 normal distributions. #' The 2-component model has priority. #' \item \code{4} : Horizontal-Vertical gradation #' with 4 (2x2) normal distributions. #' } -#' If \code{NULL} (and if \code{kind} and \code{grad = "default"}), +#' If \code{NULL} +#' (and \code{kind} is also \code{NULL}, and \code{grad = "default"}), #' it tries to trace the quantiles with changing -#' the \code{mix.type} according to the priority sequence: -#' 2 > 4 > 3 (2 components) > 3 (3 components) > 1 > 0. +#' \code{mix.type} according to the priority sequence: +#' 2 > 4 > 3 (2 components > 3 components) > 1 > 0. #' -#' If other than \code{"defaule"} for \code{grad} argument is indicated, +#' If \code{grad} argument other than \code{"default"} is indicated, #' this argument will be ignored. #' -#' @param this.mix.type A numeric value to set into \code{mix.type} field as an integer. -#' It should be an integer from \code{0} to \code{4} or \code{NULL}. -#' -#' If \code{NULL}, the current \code{mix.type} field will be retained -#' (and number of components, too) if it could trace the quantiles. -#' But if could not, it tries to trace the quantiles -#' with changing \code{mix.type} as same as the generator function -#' (signature '\code{NULL}'). -#' Thus, the priority sequence of \code{mix.type} is -#' current > 2 > 4 > 3 (2 components) > 3 (3 components) > 1 > 0. -#' #' @param grad A character string indicating the method of gradation. #' #' \code{"h"} for horizontal, \code{"v"} for vertical, @@ -124,74 +98,101 @@ #' \code{"default"} is for depending on other arguments. #' #' If other than \code{"default"} is indicated, -#' this function constructs a distribution model -#' according to this argument with ignoring \code{[this.]mix.type} argument -#' and overwriting the type indicated by \code{[this.]kind} argument. +#' this function ignores \code{[this.]mix.type} argument +#' and overwrites the condition indicated by \code{[this.]kind} argument. #' -#' @param eq.mean A logical. It works when \code{mix.type} is not 0. +#' @param eq.mean A logical. It works when \code{mix.type} is other than \code{0}. #' #' If \code{TRUE}, it forces all of the mean values of the components #' to be equal. #' This condition reduces the degrees of freedom, #' so allowed number of quantiles will be restricted. -#' See "Details" for more information. +#' See 'Details' for more information. #' -#' If \code{FALSE}, it constructs mean-differed components. -#' In this case, mean-equaled components are rarely constructed. +#' If \code{FALSE}, the mean values are not bound, +#' and mean-equaled components will be rarely constructed. #' #' If \code{logical(0)} (the default), -#' Normally, as \code{FALSE}, it constructs mean-differed components. -#' But if that fails, it tries to construct mean-equaled components -#' as \code{TRUE} (especially, when the median is specified as a quantile -#' to trace with a vertical gradational distribution). +#' Normally, the mean values are not bound same as \code{FALSE}. +#' But if it has failed to trace without binding, +#' it tries to trace with binding mean values as \code{TRUE}. +#' In some cases, reducing degrees of freedom helps to reach convergence. #' #' \code{TRUE} and \code{FALSE} can overwrite the condition indicated by -#' \code{kind} or \code{this.kind} argument. +#' \code{[this.]kind} argument. #' -#' @param eq.sd A logical. It works when \code{mix.type} is not 0. +#' @param eq.sd A logical. It works when \code{mix.type} is other than \code{0}. #' #' If \code{TRUE}, it forces all of the standard deviations of #' the components to be equal. #' This condition reduces the degrees of freedom, #' so allowed number of quantiles will be restricted. -#' See "Details" for more information. +#' See 'Details' for more information. #' #' If \code{FALSE} or \code{logical(0)}, -#' it constructs sigma-differed components. -#' In this case, sigma-equaled components are rarely constructed. +#' the standard deviations are not bound, +#' and sigma-equaled components will be rarely constructed. #' #' \code{TRUE} and \code{FALSE} can overwrite the condition indicated by -#' \code{kind} or \code{this.kind} argument. +#' \code{[this.]kind} argument. #' #' @param control A list of \code{control} option for \code{\link[nleqslv]{nleqslv}}. #' See the "Control options" at \code{\link[nleqslv]{nleqslv}} #' for more information. #' -#' By default, this list is empty, but if there is a high probability -#' of a "Jacobian is singular" error due to the condition of the quantiles, +#' By default, this list is empty normally. +#' But if the convergence appears to be difficult due to +#' an insufficient number of quantiles compared to the degrees of freedom, #' \code{allowSingular = TRUE} is set implicitly. -#' However, if \code{allowSingular} is given to this argument, -#' the given option takes priority. +#' If \code{allowSingular} is given to this argument, +#' the given value takes priority. +#' +#' @param this.kind A character string or a numeric value or a \code{\link[ggd]{GGD}} object +#' which indicates the kind of distribution model to be constructed. +#' It is equivalent to \code{kind} argument of \code{ggd.trace.q}. +#' +#' In this method, the value of \code{kind} field will be not +#' necessarily retained without indicating any conditions, +#' whereas the value of \code{mix.type} field will be retained +#' as long as possible. +#' That is, the condition of aligning the mean values or +#' standard deviations of the component to be equal will not be retained. +#' If you want to retain the condition as well, +#' indicate the object itself to \code{this.kind} argument like as +#' \code{obj$trace.q(quantiles, this.kind = obj)}. +#' +#' @param this.mix.type A numeric value to set into \code{mix.type} field as an integer. +#' It should be an integer from \code{0} to \code{4} or \code{NULL}. +#' It is equivalent to \code{mix.type} argument of \code{ggd.trace.q}. +#' +#' If \code{NULL}, the current \code{mix.type} field will be retained +#' (and number of components, too) if it can trace the quantiles. +#' But if could not, it tries to trace the quantiles +#' with changing \code{mix.type} as same as \code{ggd.trace.q}. +#' The priority sequence of \code{mix.type} is +#' current > 2 > 4 > 3 (2 components > 3 components) > 1 > 0. #' #' @return A list containing components (invisible for \code{GGD} method) #' \item{obj}{ #' The \code{\link[ggd]{GGD}} object which traces the quantiles. -#' For \code{\link[ggd]{GGD}} method, the \code{\link[ggd]{GGD}} object itself.} +#' For \code{\link[ggd]{GGD}} method, +#' the \code{\link[ggd]{GGD}} object itself.} #' \item{nleqslv.out}{ #' The list of the output of \code{\link[nleqslv]{nleqslv}} #' which has succeeded to solve tracing quantiles.} #' -#' For \code{GGD} method: If an error occur, the object will be cleared in most cases. +#' For \code{GGD} method: If an error occurs, all fields of the object will be cleared +#' in most cases. #' #' @importFrom methods new #' @seealso \code{\link[ggd]{nls.freq}} #' #' @details #' \subsection{Allowed number of quantiles}{ -#' The allowed numbers of quantiles depends on the value of \code{mix.type} argument/field. -#' Because the value determines the number of components in \code{cmd} field, -#' and also determines the degrees of freedom of the distribution model. -#' The allowed numbers of quantiles are as follows: +#' The allowed numbers of quantiles depends on the value of \code{mix.type}. +#' Because \code{mix.type} determines the number of components in \code{cmd} field, +#' and the degrees of freedom follows it. +#' In this package, the allowed numbers of quantiles are: #' \itemize{ #' \item \code{mix.type = 0} : 2 quantiles only. #' \item \code{mix.type = 1} : 3 or 4 quantiles. @@ -200,17 +201,16 @@ #' \item \code{mix.type = 4} : 5 to 8 quantiles. #' } #' About \code{mix.type = 3}, -#' if \code{grad = "v2"}, 3 or 4 quantiles are allowed. +#' if \code{grad = "v2"}, only 3 or 4 quantiles are allowed. #' If \code{grad = "v3"}, 3 to 6 quantiles are allowed. -#' -#' Note, if \code{mix.type = 3} is indicated with \code{grad = "default"}, +#' If \code{grad = "default"} is indicated with \code{mix.type = 3}, #' it tries both \code{grad = "v2"} and \code{"v3"} cases -#' and give priority to \code{"v2"}. +#' with giving priority to \code{"v2"}. #' } #' \subsection{Tightening with eq.mean / eq.sd}{ -#' If either \code{eq.mean = TRUE} or \code{eq.sd = TRUE} is indicated, -#' as each of them reduces the degrees of freedom, -#' the number of quantiles is restricted as follows: +#' Indicating \code{TRUE} for either \code{eq.mean} or \code{eq.sd} +#' reduces the degrees of freedom. +#' In this case, the number of quantiles is restricted as: #' \itemize{ #' \item \code{mix.type = 1} : 3 quantiles only. #' \item \code{mix.type = 2} : 3 quantiles only. @@ -222,86 +222,75 @@ #' With \code{grad = "v3"}, it works for 3 or 4 quantiles. #' #' If both \code{eq.mean} and \code{eq.sd} are \code{TRUE}, -#' a normal distribution will be constructed and number of quantiles must be 2. +#' a normal distribution will be generated. +#' In this case, number of quantiles must be 2. #' } #' #' @examples -#' ## Mean of 2 Normal Distributions Example: -#' ## If mix.type = 1, it constructs a mean of 2 normal distributions. -#' ## This model is not a gradational Gaussian distribution (GDD), -#' ## but a kind of Gaussian mixture model (GMM). +#' ## Preparing: +#' ## This function shows 1) the cumulative distribution function with plotting the quantiles +#' ## and 2) the probability density function. +#' plot.p.qt.d <- function( obj, x, p, xlim, ylim ) +#' { +#' layout( matrix( c( 1, 0, 2, 0 ), 2, 2, byrow = TRUE ) ) +#' plot( x, p, xlim = xlim, ylim = c( 0, 1 ), xlab = "", ylab = "" ) +#' par( new = TRUE ) +#' plot( seq( xlim[1], xlim[2], 0.1 ), obj$p( seq( xlim[1], xlim[2], 0.1 ) ), +#' type = "l", xlim = xlim, ylim = c( 0, 1 ), xlab = "", ylab = "" ) +#' par( new = FALSE ) +#' plot( seq( xlim[1], xlim[2], 0.1 ), obj$d( seq( xlim[1], xlim[2], 0.1 ) ), +#' type = "l", xlim = xlim, ylim = ylim, xlab = "", ylab = "" ) +#' } +#' +#' ## Horizontal gradation: +#' ## If mix.type = 2 or grad = "h", it generates a horizontal gradational distribution. #' ## The number of quantiles must be 3 or 4. -#' result <- ggd.trace.q( data.frame( -#' x = c( qnorm( 0.1, 0, 1 ), 0, qnorm( 0.6, 0, 0.75 ) ), -#' p = c( 0.1, 0.5, 0.6 ) ), -#' mix.type = 1 ) +#' qt <- data.frame( x = c( -0.67, 0, 0.53 ), p = c( 0.25, 0.5, 0.75 ) ) +#' result <- ggd.trace.q( qt, mix.type = 2 ) #' result -#' plot( seq( -3, 3, 0.01 ), result$obj$d( seq( -3, 3, 0.01 ) ), type = "l" ) -#' -#' ## Horizontal Gradational Example: -#' ## If mix.type = 2 or grad = "h", -#' ## it constructs a horizontal gradational distribution. -#' ## The number of p of the quantiles must be 3 or 4. -#' a <- ggd.trace.q( data.frame( x = c( -0.67, 0, 0.53 ), p = c( 0.25, 0.5, 0.75 ) ), -#' mix.type = 2 )$obj -#' a -#' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) +#' plot.p.qt.d( result$obj, qt$x, qt$p, c( -3, 3 ), c( 0, 0.5 ) ) #' -#' ## eq.sd Example: -#' ## If eq.sd = TRUE, it constructs a distribution model with components of which -#' ## the standard deviations are all equal. -#' a$trace.q( -#' data.frame( x = c( -0.64, -0.25, 0 ), p = c( 0.25, 0.4, 0.5 ) ), -#' this.mix.type = 2, eq.sd = TRUE ) -#' a$cmp -#' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) -#' -#' ## Vertical Gradational Example: -#' ## If grad = "v2", it constructs a vertical gradation of 2 normal distributions. +#' ## 2-component vertical gradation: +#' ## If grad = "v" or "v2", it generates a 2-component vertical gradational distribution. #' ## The number of quantiles must be 3 or 4. -#' a$trace.q( -#' data.frame( x = c( -1.28, -0.23, 0 ), p = c( 0.1, 0.4, 0.5 ) ), -#' grad = "v2" ) -#' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) +#' qt <- data.frame( x.1 = c( -1.28, -0.42, 0 ), x.2 = c( -1.14, -0.51, 0 ), +#' p = c( 0.1, 0.3, 0.5 ) ) +#' a <- GGD$new() +#' a$trace.q( qt, x = "x.1", grad = "v2" ) +#' a$kind; a$cmp; a$is.symmetric() ## FALSE +#' plot.p.qt.d( a, qt$x.1, qt$p, c( -3, 3 ), c( 0, 0.52 ) ) #' -#' ## eq.mean Example: -#' ## If eq.mean = TRUE, it constructs a mean-equaled distribution model. +#' ## eq.mean: +#' ## If eq.mean = TRUE, it generates a mean-equaled distribution model. +#' a$trace.q( qt, x = "x.1", eq.mean = TRUE ) +#' a$kind; a$cmp; a$is.symmetric() ## TRUE +#' plot.p.qt.d( a, qt$x.1, qt$p, c( -3, 3 ), c( 0, 0.52 ) ) #' -#' a$trace.q( -#' data.frame( x = c( -1.28, -0.42, 0 ), p = c( 0.1, 0.3, 0.5 ) ), -#' grad = "v2", eq.mean = TRUE ) -#' a$cmp -#' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) +#' ## eq.sd: +#' ## If eq.sd = TRUE, it generates a distribution model with components of which +#' ## the standard deviations are all equal. +#' a$trace.q( qt, x = "x.2", this.kind = "Horizontal", eq.sd = TRUE ) +#' a$kind; a$cmp; a$is.symmetric() ## TRUE +#' plot.p.qt.d( a, qt$x.2, qt$p, c( -3, 3 ), c( 0, 0.4 ) ) #' -#' ## 3-Mean/Sigma-Differed Vertical Gradational Example: -#' ## If grad = "v3", it constructs a vertical gradational distribution +#' ## 3-component vertical gradation: +#' ## If grad = "v3", it generates a vertical gradational distribution #' ## with different components for left-tail side and right-tail side. #' ## The number of quantiles must be from 3 to 6. -#' a <- ggd.trace.q( -#' data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), -#' grad = "v3" )$obj -#' a -#' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) +#' qt <- data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ) +#' a$trace.q( qt, grad = "v3" ) +#' a$kind; a$cmp +#' plot.p.qt.d( a, qt$x, qt$p, c( -3, 3 ), c( 0, 0.52 ) ) #' -#' ## Horizontal-Vertical Gradational Examples: +#' ## Horizontal-vertical gradation: #' ## If mix.type = 4 or grad = "hv", -#' ## it constructs a horizontal-vertical gradational distribution. +#' ## it generates a horizontal-vertical gradational distribution. #' ## The number of quantiles must be from 5 to 8. -#' a <- ggd.trace.q( -#' data.frame( -#' x = c( -1.38, -0.76, -0.28, 0.02, 0.36, 1.10, 2.79 ), -#' p = c( 0.1, 0.25, 0.4, 0.5, 0.6, 0.75, 0.9 ) ), -#' mix.type = 4 )$obj -#' a -#' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) -#' -#' a$trace.q( -#' data.frame( -#' x = c( -1.40, -0.96, -0.61, -0.30, 0.32, 0.72, 1.23, 2.21 ), -#' p = c( 0.1, 0.2, 0.3, 0.4, 0.6, 0.7, 0.8, 0.9 ) ), -#' grad = "hv" ) -#' a -#' plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) +#' qt <- data.frame( x.coor = c( -1.40, -0.96, -0.61, -0.30, 0.32, 0.72, 1.23, 2.21 ), +#' prob = c( 0.1, 0.2, 0.3, 0.4, 0.6, 0.7, 0.8, 0.9 ) ) +#' a$trace.q( qt, x = "x.coor", p = "prob", grad = "hv" ) +#' a$kind; a$cmp +#' plot.p.qt.d( a, qt$x, qt$p, c( -3, 3 ), c( 0, 0.35 ) ) ################################################################################################ ggd.trace.q <- function( quantiles, x = "x", p = "p", kind = NULL, mix.type = NULL, @@ -334,24 +323,23 @@ GGD$methods( # Check arguments # Note: - # In this function, when a error occur, - # we clear the fields as possible as we can. + # In this function, when an error occurs, + # we clear all fields as much as possible. # # Because this function does not directly set specified values to the fields, # if the fields are not cleared and contain some normal values, # users may let the subsequent processes take place without noticing the error # (during the development phase, the author actually experienced such mistakes). + on.exit( clear() ) # Check data frame. if ( !is.data.frame( quantiles ) ) { - clear() stop( "Error: quantiles must be a data frame." ) } if ( length( x ) != 1 || ( !is.numeric( x ) && !is.character( x ) ) || is.na( x ) ) { - clear() stop( "Error: Argument x must be a column name or an index number." ) } else if ( is.numeric( x ) ) @@ -359,14 +347,12 @@ GGD$methods( x <- as.integer( x ) if ( !any( x == 1:ncol( quantiles ) ) ) { - clear() stop( "Error: Illegal column number for x." ) } } if ( length( p ) != 1 || ( !is.numeric( p ) && !is.character( p ) ) || is.na( p ) ) { - clear() stop( "Error: Argument p must be a column name or an index number." ) } else if ( is.numeric( p ) ) @@ -374,20 +360,18 @@ GGD$methods( p <- as.integer( p ) if ( !any( p == 1:ncol( quantiles ) ) ) { - clear() stop( "Error: Illegal column number for p." ) } } if ( is.null( quantiles[[x]] ) || is.null( quantiles[[p]] ) ) { - clear() stop( paste0( "Error: Column '", ifelse( is.null( quantiles[[x]] ), x, p ), "' is undefined." ) ) } - grad <- withCallingHandlers( match.arg( grad ), error = function( e ) clear() ) + grad <- match.arg( grad ) if ( grad == "v" ) { grad <- "v2" @@ -398,12 +382,10 @@ GGD$methods( if ( nrow( qt ) == 0 ) { - clear() stop( "Error: No valid rows in quantiles." ) } else if ( nrow( qt ) < 2 ) { - clear() stop( "Error: Illegal number of quantiles." ) } @@ -437,7 +419,6 @@ GGD$methods( if ( any( qt$p[qt.order[1:( nrow( qt ) - 1 )]] >= qt$p[qt.order[2:nrow( qt )]] ) || any( qt$x[qt.order[1:( nrow( qt ) - 1 )]] >= qt$x[qt.order[2:nrow( qt )]] ) ) { - clear() stop( paste( "Error: Order of", x, "and", p, "must be along,", "and", x, "and", p, "must not duplicated." ) ) } @@ -455,7 +436,6 @@ GGD$methods( qt.num <- nrow( qt.with.median ) # the number of quantiles if ( qt.num < 2 || qt.num > 8 ) { - clear() stop( "Error: Illegal number of valid quantiles." ) } @@ -472,25 +452,19 @@ GGD$methods( ################################################################ # Deciding the new mix.type. - # Get grad value needed for tracing processes with this.kind. + # Get grad value needed for tracing processes according to this.kind. if ( !is.null( this.kind ) ) { - this.kind.index <- withCallingHandlers( - ggd.kind.index( this.kind, undef.err = TRUE ), - error = function( e ) clear() ) + this.kind.index <- ggd.kind.index( this.kind, undef.err = TRUE ) if ( length( this.kind.index ) > 1 ) { - clear() stop( "Error: kind should be valid single value or a GGD object." ) } - else if ( length( this.kind.index ) == 0 ) + else if ( length( this.kind.index ) == 1 && !is.na( this.kind.index ) ) { - this.kind.index <- NA_integer_ - } - - if ( !is.na( this.kind.index ) ) - { - if ( grad == "default" ) + # Set "v2" or "v3" to grad by this.kind + # (but if this.mix.type is indicated, it takes priority) + if ( grad == "default" && is.null( this.mix.type ) ) { if ( any( this.kind.index == 8:10 ) ) { @@ -501,6 +475,7 @@ GGD$methods( grad <- "v3" } } + if ( length( eq.mean ) == 0 ) { eq.mean <- ( this.kind.index %% 3 == 0 ) @@ -535,13 +510,11 @@ GGD$methods( { if ( !is.null( this.mix.type ) ) { - clear() stop( "Error: mix.type should be single integer from 0 to 4." ) } else if ( !is.null( this.kind ) ) { # This code will run if this.kind = character( 0 ). - clear() stop( "Error: kind should be valid single value or a GGD object." ) } else @@ -565,12 +538,12 @@ GGD$methods( # Sequential tracing with changing mix.type if ( qt.num < 5 ) { - # mix.type = 4 and 0 are skipped because error shall occur always. + # mix.type = 4 and 0 are skipped because error shall occur. mix.type.seq <- c( 2, 3, 1 ) } else # if ( qt.num in 5:8 ) { - # mix.type = 2, 1 and 0 are skipped because error shall occur always. + # mix.type = 2, 1, and 0 are skipped because error shall occur. mix.type.seq <- c( 4, 3 ) } @@ -581,8 +554,8 @@ GGD$methods( mix.type.seq <- c( mix.type, mix.type.seq[mix.type.seq != mix.type] ) - # In order to attempt to retain number of rows in cmp field when mix.type = 3, - # make sequences of values to set grad values. + # In order to attempt to retain number of rows in cmp field + # when mix.type = 3, make sequences of grad values. if ( mix.type == 3 && nrow( cmp ) == 2 ) { grad.seq <- c( "v2", rep( "default", length( mix.type.seq - 1 ) ) ) @@ -637,11 +610,11 @@ GGD$methods( } if ( inherits( result, "try-error" ) ) { - clear() stop( result ) } else { + on.exit() return ( invisible( result ) ) } } @@ -655,7 +628,6 @@ GGD$methods( { if ( !qt.num == 3 ) { - clear() stop( paste( "Error: Illegal number of quantiles for grad = \"v2\"", "and either eq.mean or eq.sd is TRUE." ) ) } @@ -666,7 +638,6 @@ GGD$methods( ( new.mix.type == 3 && any( qt.num == 3:4 ) ) || ( new.mix.type == 4 && qt.num == 5 ) ) ) { - clear() stop( paste( "Error: Illegal number of quantiles for mix.type =", new.mix.type, "and either eq.mean or eq.sd is TRUE." ) ) } @@ -677,7 +648,6 @@ GGD$methods( { if ( !any( qt.num == 3:4 ) ) { - clear() stop( "Error: Illegal number of quantiles for grad = \"v2\"." ) } } @@ -687,7 +657,6 @@ GGD$methods( ( new.mix.type == 3 && any( qt.num == 3:6 ) ) || ( new.mix.type == 4 && any( qt.num == 5:8 ) ) ) ) { - clear() stop( paste( "Error: Illegal number of quantiles for mix.type =", paste0( new.mix.type, "." ) ) ) } @@ -695,12 +664,13 @@ GGD$methods( ################################################################ # If new.mix.type = 0, - # culculate the mean and the standard deviation directly. + # calculate the mean and the standard deviation directly. if ( new.mix.type == 0 ) { result <- ms.norm.xp( qt.with.median$x, qt.with.median$p ) set.cmp( data.frame( result ), this.mix.type = new.mix.type ) + on.exit() return ( invisible( list( obj = .self, nleqslv.out = NULL ) ) ) } @@ -777,7 +747,7 @@ GGD$methods( qt <- qt.no.median # the condition of quantiles for nleqslv # Define the initial values and the objective function of nleqslv. - # In the folloing code, + # In the following code, # mean.i and sd.i (i = 1,2,...) are index number of x, # which is the input vector of f and also output vector of nleqslv. if ( new.mix.type == 1 ) @@ -1046,7 +1016,7 @@ GGD$methods( # new.mix.type = 3, 2 components if ( eq.sd ) { - # Set start values for mean values and the standard deviaton + # Set start values for mean values and the standard deviations # by 2 quantiles other than median. pseudo <- ms.norm.xp( qt$x[1:2], qt$p[1:2] ) @@ -1071,7 +1041,7 @@ GGD$methods( if ( is.set.median ) { # Median is specified: - # Unify mean values to the median and seek standard deviations. + # Unify mean values to the median, and then seek standard deviations. x.0 <- c( 1, 1 ) mean.1 <- mean.2 <- 0 @@ -1081,7 +1051,7 @@ GGD$methods( else { # Median is not specified: - # Seek the mean value to align and standard deviations. + # Seek the common mean value and uncommon standard deviations. pseudo <- ms.norm.xp( qt$x[c( 1, 3 )], qt$p[c( 1, 3 )] ) x.0 <- c( pseudo$mean, sqrt( pseudo$sd ), sqrt( pseudo$sd ) ) @@ -1124,7 +1094,6 @@ GGD$methods( as.character( attr( l, "condition" ) ) ) ) == 0 ) { # Critical or programming error. - clear() stop( l ) } @@ -1144,12 +1113,10 @@ GGD$methods( if ( qt.num == 3 && isFALSE( eq.mean ) ) { message( "Crossover-tracing has failed." ) - clear() stop( l ) } else if ( qt.num == 4 ) { - clear() stop( l ) } @@ -1163,7 +1130,7 @@ GGD$methods( } else { - # Retry with 3 mean-differed componetnts. + # Retry with 3 mean-differed components. # # Note: Twice retrying with eq.mean = TRUE # (with 2 components and 3 components) will be done @@ -1265,7 +1232,7 @@ GGD$methods( # ( #lower, #upper ) = ( 2, 0 ), ( 0, 2 ), ( 2, 1 ) or ( 1, 2 ) # Get the SDs of the normal distributions - # through both quantles on the side with 2 quantiles. + # passing through both quantiles in the 2-quantiles side. # # Here, we use 2 variables for indexes of qt, # and 2 variables for indexes of vector x of @@ -1296,7 +1263,8 @@ GGD$methods( p.a1 <- pnorm( qt.x, median, x[xi.outer]^2 * sqrt( 2 ) / 2 ) p.a2 <- pnorm( qt.x, median, x[xi.inner]^2 * sqrt( 2 ) / 2 ) - return ( p - p.a1 * sqrt( 2 ) / 2 + p.a2 * sqrt( 2 ) / 2 - qt.p ) + return ( p - p.a1 * sqrt( 2 ) / 2 + p.a2 * sqrt( 2 ) / 2 - + qt.p ) } get.cmp.result <- function( result ) @@ -1483,7 +1451,6 @@ GGD$methods( } else { - clear() stop( l ) } } @@ -1559,7 +1526,7 @@ GGD$methods( # Get start values for means and standard deviations # of the left-side and right-side distributions # via ggd.trace.q with new.mix.type = 3. - # Here, we don't give "control" to ggd.trace.q intentionally. + # Here, we don't give 'control' to ggd.trace.q intentionally. # Substring of the failed message for initial guessing msg.sub <- "mean-differed" @@ -1644,7 +1611,8 @@ GGD$methods( if ( inherits( d.2, "try-error" ) ) { message( paste( "Message: Initial guessing with 3-quantile-tracing", - "for right-side", msg.sub, "components has failed.", + "for right-side", + msg.sub, "components has failed.", "2-quantile-tracing has used instead." ) ) rows <- nrow( qt.with.median ) if ( isTRUE( eq.mean ) && is.set.median ) @@ -1788,7 +1756,7 @@ GGD$methods( # In these v2-ggd.trace.q processes, # it tends to reduce the success rate to give 4 quantiles for the conditions, # so we give 3 quantiles here. - # If failed, the normal distributions through 2 of the given quantiles + # If failed, the normal distributions passing through 2 of the given quantiles # are taken for initial guesses. qt.x <- c( qt.with.median$x[1:3], @@ -1883,7 +1851,6 @@ GGD$methods( result <- try( nleqslv( x.0, f, control = control ), silent = TRUE ) if ( inherits( result, "try-error" ) ) { - clear() stop( paste( "Error: Critical error at nleqslv:\n", attr( result, "condition" ) ) ) } @@ -1943,66 +1910,23 @@ GGD$methods( else { message( paste( "nleqslv has failed. Message:", result$message ) ) - clear() stop( "Error: Failed to construct components." ) } } } } + on.exit() return ( invisible( list( obj = .self, nleqslv.out = result ) ) ) } ) ################################################################################################ -#' [Non-exported] PDF/CDF for mix.type = 3 -#' -#' Calculates the values of the probability density function or -#' the cumulative distribution function of the GGD model with \code{mix.type = 3}. -#' Both \code{means} and \code{sds} vectors need 3 elements for this function. -#' Where with two components, you must set \code{means[3]} and \code{sds[3]} -#' the same values of \code{means[1]} and \code{sds[1]}. -#' @param x A vector of x-coordinates. -#' @param means The vector of mean values of the 3 components. -#' @param sds The vector of sd values of the 3 components. -#' @param f.t3 A function handle, -#' \code{ggd:::f.t3.d} for PDF or \code{ggd:::f.t3.p} for CDF. -#' @return The vector of values of the probability density function -#' or the cumulative distribution function. -################################################################################################ -dp.t3 <- function( x, means, sds, f.t3 ) -{ - results <- vapply( x, function( x ) - { - result <- f.t3[[2]]( x, means[2], sds[2] ) - - if ( x < means[1] ) - { - result <- result + f.t3[[1]]( x, means[1], sds[1] ) - } - else - { - result <- result + f.t3[[3]] - } - - if ( x > means[3] ) - { - result <- result + f.t3[[1]]( x, means[3], sds[3] ) - f.t3[[3]] - } - - return ( result ) - }, 0 ) - - return ( results ) -} - -################################################################################################ -#' [Non-exported] Crossover-tracing (3 quantiles, vertical gradation of 2 normal distributions) +#' [Non-exported] Crossover-tracing (3 quantiles, v2) #' -#' Gets the data frame for \code{cmp} field where \code{mix.type = 3} and tracing 3 quantiles -#' with mean-differed 2 normal distributions of the components by crossover-tracing. -#' @param qt A data frame; the quantiles to be traced, -#' If the median is specified, median must be included. +#' Tracing 3 quantiles by crossover-tracing, makes a data frame for \code{cmp} field +#' for a mean-differed 2-component vertical gradational distribution. +#' @param qt A data frame; the quantiles to be traced. #' @param control The \code{control} option for \code{\link[nleqslv]{nleqslv}}. #' @return A list containing components #' \item{cmp}{ @@ -2012,7 +1936,7 @@ dp.t3 <- function( x, means, sds, f.t3 ) #' @details #' \subsection{Crossover-tracing}{ #' Let cumulative distribution functions of 2 mean-differed normal distributions -#' crossover at one of quantiles (except for median), +#' crossover at one of the quantiles (except for the median), #' and seek the mean values and standard deviations as tracing the other 2 quantiles. #' } #' @importFrom stats pnorm @@ -2095,13 +2019,13 @@ v2.crossover <- function( qt, control ) } ################################################################################################ -#' [Non-exported] Gets cmp field (4 quantiles, vertical gradation of 2 normal distributions) +#' [Non-exported] Gets cmp field (4 quantiles, v2) #' -#' Gets the data frame for \code{cmp} field where \code{mix.type = 3} and tracing 4 quantiles -#' with 2 normal distributions of the components. +#' Tracing 4 quantiles with 2 normal distributions, makes a data frame for \code{cmp} field +#' where \code{mix.type = 3}. #' @param qt A data frame; the quantiles to be traced. #' @param control The \code{control} option for \code{\link[nleqslv]{nleqslv}}. -#' @param retriable A logical; the flag if retrying is enable. +#' @param retryable A logical; the flag if retrying is enable. #' @return A list containing components #' \item{cmp}{ #' The data frame for \code{cmp} field.} @@ -2110,7 +2034,7 @@ v2.crossover <- function( qt, control ) #' @importFrom stats pnorm #' @importFrom nleqslv nleqslv ################################################################################################ -v2.qt4.cmp <- function( qt, control, retriable ) +v2.qt4.cmp <- function( qt, control, retryable ) { if ( nrow( qt ) != 4 ) { @@ -2122,15 +2046,15 @@ v2.qt4.cmp <- function( qt, control, retriable ) # # Sort the quantiles in order of closeness to the median, # then calculate mean values and standard deviations of the components - # through the 2 quantiles farther/closer to the median, respectively. + # passing through the 2 quantiles farther/closer to the median, respectively. qt <- data.frame( x = qt$x[order( abs( qt$p - 0.5 ) )], p = qt$p[order( abs( qt$p - 0.5 ) )] ) if ( qt$p[1] == qt$p[2] ) { # If there are 2 same quantiles of the nearest to the median in qt, - # we use normal distributions through quantiles of the nearest and the farthest - # and through the quantiles of the nearest and the mid-distance. + # we use a normal distribution passing through the nearest and the farthest quantiles + # and the other one passing through the nearest and the mid-distance quantiles. # # This can be the case when 3 quantiles are specified. pseudo.far <- ms.norm.xp( qt$x[c( 2, 4 )], qt$p[c( 2, 4 )] ) @@ -2169,7 +2093,7 @@ v2.qt4.cmp <- function( qt, control, retriable ) } else { - if ( retriable ) + if ( retryable ) { message( paste( "nleqslv has once failed. Message:", result$message ) ) } @@ -2184,18 +2108,18 @@ v2.qt4.cmp <- function( qt, control, retriable ) } ################################################################################################ -#' [Non-exported] Gets cmp field (4 quantiles, vertical gradation of 3 normal distributions) +#' [Non-exported] Gets cmp field (4 quantiles, v3) #' -#' Gets the data frame for \code{cmp} field where \code{mix.type = 3} and tracing 4 quantiles -#' with 3 normal distributions of the components. +#' Tracing 4 quantiles with 3 normal distributions, makes a data frame for \code{cmp} field +#' where \code{mix.type = 3}. #' @param qt A data frame; the quantiles to be traced. #' @param eq.mean A logical; the flag to be equal all of the mean values. #' @param eq.sd A logical; the flag to be equal all of the standard deviations. #' @param grad A character string indicating the method of gradation. -#' If \code{"v3"}, constructing with 3 components is enforcedly, +#' If \code{"v3"}, the number of components will forced to be 3, #' even if it is possible to construct with 2 components. #' @param control The \code{control} option for \code{\link[nleqslv]{nleqslv}}. -#' @param retriable A logical; the flag if retrying is enable. +#' @param retryable A logical; the flag if retrying is enable. #' @return A list containing components #' \item{cmp}{ #' The data frame for \code{cmp} field.} @@ -2203,7 +2127,7 @@ v2.qt4.cmp <- function( qt, control, retriable ) #' The output of \code{\link[nleqslv]{nleqslv}}.} #' @importFrom nleqslv nleqslv ################################################################################################ -v3.qt4.cmp <- function( qt, eq.mean, eq.sd, control, retriable, grad ) +v3.qt4.cmp <- function( qt, eq.mean, eq.sd, control, retryable, grad ) { if ( nrow( qt ) != 4 ) { @@ -2214,15 +2138,15 @@ v3.qt4.cmp <- function( qt, eq.mean, eq.sd, control, retriable, grad ) # # Sort the quantiles in order of closeness to the median, # then calculate mean values and standard deviations of the normal distributions - # through the 2 quantiles farther/closer to the median, respectively. + # passing through the 2 quantiles farther/closer to the median, respectively. qt <- data.frame( x = qt$x[order( abs( qt$p - 0.5 ) )], p = qt$p[order( abs( qt$p - 0.5 ) )] ) if ( qt$p[1] == qt$p[2] ) { # If there are 2 same quantiles of the nearest to the median in qt, - # we use normal distributions through quantiles of the nearest and the farthest - # and through the quantiles of the nearest and the mid-distance. + # we use normal distributions passing through the nearest and the farthest quantiles + # and passing through the nearest and the mid-distance quantiles. # # This can be the case when 3 quantiles are specified. pseudos <- list( ms.norm.xp( qt$x[c( 1, 3 )], qt$p[c( 1, 3 )] ), @@ -2301,7 +2225,7 @@ v3.qt4.cmp <- function( qt, eq.mean, eq.sd, control, retriable, grad ) } else { - if ( retriable ) + if ( retryable ) { message( paste( "nleqslv has once failed. Message:", result$message ) ) } @@ -2320,7 +2244,7 @@ v3.qt4.cmp <- function( qt, eq.mean, eq.sd, control, retriable, grad ) #' #' Gets a data frame for \code{cmp} field for \code{mix.type = 3}. #' Each of \code{means} and \code{sds} arguments must has 3 elements in order of -#' \code{[1]} left-tail side, \code{[2]} top side and \code{[3]} right-tail side. +#' \code{[1]} left-tail side, \code{[2]} top side, and \code{[3]} right-tail side. #' @export #' @param means A vector of mean values of the 3 normal distributions of the components. #' @param sds A vector of standard deviations of the 3 normal distributions of @@ -2330,11 +2254,11 @@ v3.qt4.cmp <- function( qt, eq.mean, eq.sd, control, retriable, grad ) #' @return The data frame for \code{cmp} field. #' @examples #' means <- c( 0.2, 0, 0.2 ); sds <- c( 1.2, 0.9, 1.2 ) -#' ggd.get.t3.cmp( means, sds ) # 2 components -#' ggd.get.t3.cmp( means, sds, grad = "v3" ) # 3 components +#' ggd.get.t3.cmp( means, sds ) ## 2 components +#' ggd.get.t3.cmp( means, sds, grad = "v3" ) ## 3 components #' #' means <- rep( 0.5, 3 ); sds <- rep( 2.5, 3 ) -#' ggd.get.t3.cmp( means, sds ) # 2 components even if normal distribution +#' ggd.get.t3.cmp( means, sds ) ## 2 components even if normal distribution ################################################################################################ ggd.get.t3.cmp <- function( means, sds, grad = c( "default", "v2", "v3" ) ) { diff --git a/cran-comments.md b/cran-comments.md index 25225ae..e7da1ed 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,14 +1,14 @@ -── R CMD check results ─────────────────────────────── ggd 1.0.2 ──── -Duration: 16m 4.6s +── R CMD check results ────────────────────────────────────── ggd 1.0.3 ──── +Duration: 16m 23.2s 0 errors ✔ | 0 warnings ✔ | 0 notes ✔ -── ggd 1.0.2: NOTE +── ggd 1.0.3: NOTE - Build ID: ggd_1.0.2.tar.gz-9d7128aae7ec4518843c9e66b3186d41 + Build ID: ggd_1.0.3.tar.gz-3f4268ebdde1490d81f021c940310135 Platform: Windows Server 2022, R-devel, 64 bit - Submitted: 47m 50.5s ago - Build time: 30m 21.8s + Submitted: 2h 10m 2.7s ago + Build time: 30m 52.7s ❯ checking CRAN incoming feasibility ... NOTE Maintainer: 'Kimitsuna Ura ' @@ -28,30 +28,40 @@ Duration: 16m 4.6s 0 errors ✔ | 0 warnings ✔ | 4 notes ✖ -── ggd 1.0.2: NOTE +── ggd 1.0.3: NOTE - Build ID: ggd_1.0.2.tar.gz-6cc10ab775894ac9b324ce8825dfac5f + Build ID: ggd_1.0.3.tar.gz-de5e1af3d4a6471e9125682a94a1d72e Platform: Ubuntu Linux 20.04.1 LTS, R-release, GCC - Submitted: 47m 50.5s ago - Build time: 36m 44.5s + Submitted: 2h 10m 2.8s ago + Build time: 40m 21.4s -❯ checking CRAN incoming feasibility ... [6s/16s] NOTE +❯ checking CRAN incoming feasibility ... [6s/23s] NOTE Maintainer: ‘Kimitsuna Ura ’ New submission -0 errors ✔ | 0 warnings ✔ | 1 note ✖ +❯ checking examples ... [13s/34s] NOTE + Examples with CPU (user + system) or elapsed time > 5s + user system elapsed + ggd.nls.freq.all 3.128 0.004 8.376 -── ggd 1.0.2: NOTE +0 errors ✔ | 0 warnings ✔ | 2 notes ✖ - Build ID: ggd_1.0.2.tar.gz-1656b971e4eb45e5bb4a7d465c518026 +── ggd 1.0.3: NOTE + + Build ID: ggd_1.0.3.tar.gz-e0135eb74fab4cc6a60d64951a924881 Platform: Fedora Linux, R-devel, clang, gfortran - Submitted: 47m 50.6s ago - Build time: 36m 33.4s + Submitted: 2h 10m 2.8s ago + Build time: 39m 49.1s -❯ checking CRAN incoming feasibility ... [6s/20s] NOTE +❯ checking CRAN incoming feasibility ... [6s/25s] NOTE Maintainer: ‘Kimitsuna Ura ’ New submission -0 errors ✔ | 0 warnings ✔ | 1 note ✖ +❯ checking examples ... [14s/37s] NOTE + Examples with CPU (user + system) or elapsed time > 5s + user system elapsed + ggd.nls.freq.all 3.281 0.007 9.271 + +0 errors ✔ | 0 warnings ✔ | 2 notes ✖ diff --git a/man/GGD-class.Rd b/man/GGD-class.Rd index 46ade7c..70d720d 100644 --- a/man/GGD-class.Rd +++ b/man/GGD-class.Rd @@ -16,7 +16,7 @@ The class provides the Gradational Gaussian Distribution. The GGD is alike the Gaussian mixture model (GMM) but different. The GMM is represented by linear combinations of some normal distributions, - and is often used for clustering of mixed data. + and it is commonly used for clustering mixed data. On the other hand, the GGD is a distribution model of which mixes some normal distributions with gradually changing ratio along the x-axis or y-axis directions, @@ -30,8 +30,8 @@ The class provides the Gradational Gaussian Distribution. where \eqn{h_1} and \eqn{h_2} are the mixing ratio functions defined using \eqn{\Phi_1} and \eqn{\Phi_2}, the cumulative distribution functions of \eqn{\mathcal{N}_1} and \eqn{\mathcal{N}_2} as - \deqn{h_1(x) = 1 - \Phi_1(x), \\ - h_2(x) = \Phi_2(x). \quad \ \ \ } + \deqn{h_1(x) = 1 - \Phi_1(x), \ \ \\ + h_2(x) = \Phi_2(x). \quad \ \ \ \ \ } Therefore, \eqn{h_1(x)} decreases gradually along x-axis as \eqn{x:-\infty \to \infty \ \Rightarrow \ h_1(x):1 \to 0}, @@ -52,8 +52,8 @@ The class provides the Gradational Gaussian Distribution. where the mixing ratio functions \eqn{v_1} and \eqn{v_2} are defined using \eqn{f_1} and \eqn{f_2}, the probability density functions of \eqn{\mathcal{N}_1} and \eqn{\mathcal{N}_2} as - \deqn{v_1(x) = 1 - \dfrac{f_1(x)}{f_1(\mu_1)}, \\ - v_2(x) = \dfrac{f_2(x)}{f_2(\mu_2)}, \quad \ \ \ } + \deqn{v_1(x) = 1 - \dfrac{f_1(x)}{f_1(\mu_1)}, \ \ \\ + v_2(x) = \dfrac{f_2(x)}{f_2(\mu_2)}, \quad \ \ \ \ \ } where \eqn{\mu_1} and \eqn{\mu_2} are the mean values of \eqn{\mathcal{N}_1} and \eqn{\mathcal{N}_2}, respectively. @@ -67,8 +67,8 @@ The class provides the Gradational Gaussian Distribution. Or, using \eqn{\mu_1} and \eqn{\mu_2}, the mean values of \eqn{\mathcal{N}_1} and \eqn{\mathcal{N}_2}, we can write as \deqn{x:-\infty \to \mu_1 \ \Rightarrow \ v_1(x):1 \to 0, \ \ \ \ - x:\mu_1 \to \infty \ \Rightarrow \ v_1(x):0 \to 1, \\ - x:-\infty \to \mu_2 \ \Rightarrow \ v_2(x):0 \to 1, \ \ \ \ + x:\mu_1 \to \infty \ \Rightarrow \ v_1(x):0 \to 1,} + \deqn{x:-\infty \to \mu_2 \ \Rightarrow \ v_2(x):0 \to 1, \ \ \ \ x:\mu_2 \to \infty \ \Rightarrow \ v_2(x):1 \to 0.} Here, we call \eqn{\mathcal{N}_1} the \bold{tail-side} distribution, @@ -83,7 +83,7 @@ The class provides the Gradational Gaussian Distribution. The tops of \eqn{f_1} and \eqn{f_2} could be far apart from each other, and moreover, the top of \eqn{\mathcal{G}[\mathcal{N}_1 \uparrow \mathcal{N}_2]} could be nearby the top of \eqn{f_1}, instead of \eqn{f_2}. - That may be contrary to the intuitive image of the "vertical gradational distribution", + That may be contrary to the intuitive image of the 'vertical gradational distribution', but it is not prohibited. About the \bold{3-component vertical gradational Gaussian distribution}, @@ -143,57 +143,50 @@ The class provides the Gradational Gaussian Distribution. \describe{ \item{\code{mix.type = 0} (normal distribution)}{\deqn{ - g(x) = f_1(x) \\ - \Psi(x) = \Phi_1(x) }} + g(x) = f_1(x), \ \ \\ + \Psi(x) = \Phi_1(x). \ \ }} \item{\code{mix.type = 1} (mean of 2 normal distributions; a Gaussian mixture model (GMM), not a GGD)}{\deqn{ - g(x) = \dfrac{f_1(x) + f_2(x)}{2} \ \\ - \Psi(x) = \dfrac{\Phi_1(x) + \Phi_2(x)}{2} }} + g(x) = \dfrac{f_1(x) + f_2(x)}{2}, \ \ \\ + \Psi(x) = \dfrac{\Phi_1(x) + \Phi_2(x)}{2}. \ }} \item{\code{mix.type = 2} (horizontal GGD)}{\deqn{ g(x) = \left( 1 - \Phi_1(x) \right) f_1(x) - + \Phi_2(x) f_2(x) \\ + + \Phi_2(x) f_2(x), \ \ \\ \ \\ \Psi(x) = \Phi_1(x) - \dfrac{\Phi_1(x)^2}{2} + - \dfrac{\Phi_2(x)^2}{2} \qquad \ \ }} + \dfrac{\Phi_2(x)^2}{2}. \qquad \ \ \ \ }} \item{\code{mix.type = 3}, \code{grad = "v2"} (2-component vertical GGD)}{\deqn{ g(x) = \left( 1 - \dfrac{f_1(x)}{f_1(\mu_1)} \right) f_1(x) + - \dfrac{f_2(x)^2}{f_2(\mu_2)} \\ + \dfrac{f_2(x)^2}{f_2(\mu_2)}, \ \ \\ \ \\ \Psi(x) = \Phi_1(x) - \dfrac{\Phi^*_1(x)}{\sqrt{2}} + - \dfrac{\Phi^*_2(x)}{\sqrt{2}} \qquad \; \: }} + \dfrac{\Phi^*_2(x)}{\sqrt{2}}. \qquad \ \ \; \: }} \item{\code{mix.type = 3}, \code{grad = "v3"} (3-component vertical GGD)}{\deqn{ - g(x) = g_1(x) + g_2(x) + g_3(x) \hspace{14.5em} \\ - \ \\ - g_1(x) = \left( 1 - \dfrac{f_1(x)}{f_1(\mu_1)} \right) f_1(x) - \quad (x \leq \mu_1; \ \mathrm{otherwise} \ 0) \\ - \ \\ - g_2(x) = \dfrac{f_2(x)^2}{f_2(\mu_2)} \hspace{15.6em} \\ - \ \\ - g_3(x) = \left( 1 - \dfrac{f_3(x)}{f_3(\mu_3)} \right) f_3(x) - \quad (x \geq \mu_3; \ \mathrm{otherwise} \, 0) \\ - \ \\ - \Psi(x) = \min \left( \Phi_1(x) - \dfrac{\Phi^*_1(x)}{\sqrt{2}}, + g(x) = g_1(x) + g_2(x) + g_3(x), \hspace{14.5em} \\ } + \deqn{g_1(x) = \left( 1 - \dfrac{f_1(x)}{f_1(\mu_1)} \right) f_1(x) + \quad (x \leq \mu_1; \ \mathrm{otherwise} \ 0), \\ } + \deqn{g_2(x) = \dfrac{f_2(x)^2}{f_2(\mu_2)}, \hspace{15.6em} \\ } + \deqn{g_3(x) = \left( 1 - \dfrac{f_3(x)}{f_3(\mu_3)} \right) f_3(x) + \quad (x \geq \mu_3; \ \mathrm{otherwise} \, 0), \\ } + \deqn{\Psi(x) = \min \left( \Phi_1(x) - \dfrac{\Phi^*_1(x)}{\sqrt{2}}, \ \dfrac{2 - \sqrt{2}}{4} \right) \hspace{10em} \\ + \dfrac{\Phi^*_2(x)}{\sqrt{2}} + \max \left( 0, \ \Phi_3(x) - \dfrac{\Phi^*_3(x)}{\sqrt{2}} - - \dfrac{2 - \sqrt{2}}{4} \right) }} + \dfrac{2 - \sqrt{2}}{4} \right). }} \item{\code{mix.type = 4} (horizontal-vertical GGD)}{\deqn{ - g(x) = \left( 1 - \Psi_1(x)\ \right) g_1(x) + \Psi_2(x) g_2(x) - \hspace{6em} \ \ \\ - \ \\ - g_i(x) = \left( 1 - \dfrac{f_{i,1}(x)}{f_{i,1}(\mu_{i,1})} \right) - f_{i,1}(x) + \dfrac{f_{i,2}(x)^2}{f_{i,2}(\mu_{i,2})} \\ - \ \\ - \Psi(x) = \Psi_1(x) - \dfrac{\Psi_1(x)^2}{2} + - \dfrac{\Psi_2(x)^2}{2} \hspace{9em} \\ - \ \\ - \Psi_i(x) = \Phi_{i,1}(x) - \dfrac{\Phi^*_{i,1}(x)}{\sqrt{2}} + - \dfrac{\Phi^*_{i,2}(x)}{\sqrt{2}} \hspace{3em} \ }} + g(x) = \left( 1 - \Psi_1(x)\ \right) g_1(x) + \Psi_2(x) g_2(x), + \hspace{6em} \ \ \\ } + \deqn{g_i(x) = \left( 1 - \dfrac{f_{i,1}(x)}{f_{i,1}(\mu_{i,1})} \right) + f_{i,1}(x) + \dfrac{f_{i,2}(x)^2}{f_{i,2}(\mu_{i,2}),} \\ } + \deqn{\Psi(x) = \Psi_1(x) - \dfrac{\Psi_1(x)^2}{2} + + \dfrac{\Psi_2(x)^2}{2}, \hspace{9em} \\ } + \deqn{\Psi_i(x) = \Phi_{i,1}(x) - \dfrac{\Phi^*_{i,1}(x)}{\sqrt{2}} + + \dfrac{\Phi^*_{i,2}(x)}{\sqrt{2}}. \hspace{3em} \ }} } Where \eqn{f_i} is the probability density function of @@ -201,7 +194,7 @@ The class provides the Gradational Gaussian Distribution. \eqn{\Phi_i} and \eqn{\Phi_{i,j}} are the cumulative distribution functions of \eqn{\mathcal{N}_i} and \eqn{\mathcal{N}_{i,j}}, and \eqn{\mu_i} is the mean value of \eqn{\mathcal{N}_i}, - and \eqn{\Phi^*_i} and \eqn{\Phi^*_{i,j}} are the cumulative distribution function + and then \eqn{\Phi^*_i} and \eqn{\Phi^*_{i,j}} are the cumulative distribution function of the normal distributions \eqn{\mathcal{N}(\mu_i, (\sigma_i / \sqrt{2})^2)} and \eqn{\mathcal{N}(\mu_{i,j}, (\sigma_{i,j} / \sqrt{2})^2)}, respectively. @@ -239,21 +232,21 @@ The class provides the Gradational Gaussian Distribution. \code{cmp} has 4 rows. } - With \code{mix.type = 1}, the distribution model is not + The distribution model of \code{mix.type = 1} is not a gradational Gaussian distribution (GGD), but a kind of Gaussian mixture model (GMM). This is provided for comparing GGD with GMM.} -\item{\code{cmp}}{A data frame with 2 numeric columns which shows - the normal distributions of the components. +\item{\code{cmp}}{A data frame with 2 numeric columns which have + the parameters of the normal distributions of the components. \code{mean} column represents the mean values of the components, and \code{sd} column represents the standard deviations. - Where \code{mix.type} is in \code{0:3}, - it has 1 to 3 rows named like "\code{n.i}". + Where \code{mix.type} is from \code{0} to \code{3}, + it has 1 to 3 rows named like \code{"n.i"}. Where \code{mix.type = 4}, - it has 4 rows named like "\code{n.i.j}".} + it has 4 rows named like \code{"n.i.j"}.} \item{\code{median}}{A numeric; the median of the distribution.} @@ -261,9 +254,9 @@ The class provides the Gradational Gaussian Distribution. \item{\code{sd}}{A numeric; the standard deviation of the distribution.} -\item{\code{lsd}}{A numeric; the semi-standard deviation lower than mean.} +\item{\code{lsd}}{A numeric; the half standard deviation lower than the mean.} -\item{\code{usd}}{A numeric; the semi-standard deviation upper than mean.} +\item{\code{usd}}{A numeric; the half standard deviation upper than the mean.} \item{\code{lsd.abs.error}}{A numeric; the estimated modulus of the absolute error for \code{lsd}.} @@ -271,7 +264,7 @@ the estimated modulus of the absolute error for \code{lsd}.} \item{\code{usd.abs.error}}{A numeric; the estimated modulus of the absolute error for \code{usd}. - Where \code{mix.type = 4}, to compute the semi-standard deviations, + Where \code{mix.type = 4}, to compute the half standard deviations, \code{\link[stats]{integrate}} function is used. And the modulus of the absolute errors which \code{\link[stats]{integrate}} function has reported diff --git a/man/adjust.cmp.Rd b/man/adjust.cmp.Rd index ed4f1a1..d83951d 100644 --- a/man/adjust.cmp.Rd +++ b/man/adjust.cmp.Rd @@ -57,20 +57,20 @@ The \code{mix.type} field will be change accordingly. } } \examples{ - ## Usually the cmp field is simplified automatically, + ## Usually 'cmp' field is simplified automatically, ## so you do not have to call adjust.cmp by your own. ## For example, in this case, ## the number of components is simplified to 1 automatically. a <- ggd.set.cmp( data.frame( mean = c( 0, 0 ), sd = c( 1.1, 1.1 ) ) ) - a$kind; a$mix.type; a$cmp ## mix.type = 0 represents a Normal Distribution. + a$kind; a$mix.type; a$cmp ## mix.type = 0: a Normal Distribution ## GGD$new() makes 2 components of normal distributions for convenience. - ## You can use adjust.cmp in order to adjust the cmp field of a new object to 1 component. + ## You can use adjust.cmp in order to adjust 'cmp' field of a new object to 1 component. a <- GGD$new() - a$kind; a$mix.type; a$cmp ## mix.type = 2 represents a Horizontal Gradational Model. + a$kind; a$mix.type; a$cmp ## mix.type = 2: Horizontal Gradational Distribution a$adjust.cmp() - a$kind; a$mix.type; a$cmp ## mix.type = 0 represents a Normal Distribution. + a$kind; a$mix.type; a$cmp ## mix.type = 0: Normal Distribution ## You can also write as: a <- GGD$new()$adjust.cmp() @@ -79,15 +79,15 @@ The \code{mix.type} field will be change accordingly. ## If you want to give redundancy to the components, you can also use adjust.cmp. ## Normal Distribution with 2 components. a$adjust.cmp( this.mix.type = 1 ) - a$kind; a$mix.type; a$cmp ## mix.type = 1 represents a Gaussian Mixture Model. + a$kind; a$mix.type; a$cmp ## mix.type = 1: Mean of 2 Normal Distributions ## Normal Distribution with 3 components. a$adjust.cmp( grad = "v3" ) - a$kind; a$mix.type; a$cmp ## mix.type = 3 represents a Vertical Gradational Model. + a$kind; a$mix.type; a$cmp ## mix.type = 3: Vertical Gradational Distribution ## Normal Distribution with 4 components. a$adjust.cmp( grad = "hv" ) - a$kind; a$mix.type; a$cmp ## mix.type = 4 represents a H-V Gradational Model. + a$kind; a$mix.type; a$cmp ## mix.type = 4: H-V Gradational Distribution } \seealso{ \code{\link[ggd]{set.cmp}} diff --git a/man/adjust.median.mean.sd.Rd b/man/adjust.median.mean.sd.Rd index 0fe61e8..ab2a012 100644 --- a/man/adjust.median.mean.sd.Rd +++ b/man/adjust.median.mean.sd.Rd @@ -3,7 +3,7 @@ \name{adjust.median.mean.sd} \alias{adjust.median.mean.sd} \alias{\S4method{adjust.median.mean.sd}{GGD}} -\title{Adjust median, mean and sd fields} +\title{Adjust median, mean, and sd fields} \usage{ \S4method{adjust.median.mean.sd}{GGD}() } @@ -11,8 +11,8 @@ The \code{\link[ggd]{GGD}} object itself (invisible). } \description{ -Calculates the median, the mean and the standard deviation of the distribution model and -sets those values into the fields. -Before calling this method, you must set \code{cmp} field and \code{mix.type} field. +Calculates the median, the mean, and the standard deviation of the distribution model and +then sets those values into the fields. +Before calling this method, you must set \code{cmp} and \code{mix.type} fields. Normally, users of this class don't need to call this method directly. } diff --git a/man/apply.cmp.Rd b/man/apply.cmp.Rd index d474aab..a0ae096 100644 --- a/man/apply.cmp.Rd +++ b/man/apply.cmp.Rd @@ -13,13 +13,13 @@ If \code{NULL}, nothing is applied.} \item{f.sd}{A function to apply to elements in \code{sd} column. If \code{NULL}, nothing is applied. -See "Details" for more information.} +See 'Details' for more information.} } \value{ The processed \code{\link[ggd]{GGD}} object itself (invisible). } \description{ -Applies a function to each element in the \code{cmp} field. +Applies a function to each element in \code{cmp} field. Different functions can be applied to \code{mean} column and \code{sd} column. Other fields will be adjusted accordingly. } @@ -28,18 +28,18 @@ Each function indicated with \code{f.mean} or \code{f.sd} can receive 2 arguments (each argument name is arbitrary): \enumerate{ \item A vector of the current values of \code{mean} or \code{sd} column. - \item The \code{\link[ggd]{GGD}} object itself to be processed. + \item The \code{\link[ggd]{GGD}} object itself. } Therefore, the function for \code{f.mean} or \code{f.cmp} is hoped to be - declared with 2 arguments like as "\code{function(mean, obj)}", + declared with 2 arguments like as '\code{function(mean, obj)}', however, if the function do not need the 2nd argument, you can declare with 1 arguments - like as "\code{function(mean)}" or "\code{function(sd)}". + like as '\code{function(mean)}' or '\code{function(sd)}'. For the values of the functions, each function must return a numeric vector with the same length of the 1st argument as new values of each column. After both functions have been processed, the new values are actually - set into the \code{cmp} field. Therefore, from within the functions to apply, + set into \code{cmp} field. Therefore, from within the functions to apply, it is possible to refer to the values of each field before applying, but not after. @@ -55,23 +55,27 @@ Each function indicated with \code{f.mean} or \code{f.sd} can receive (e.g., \code{\link[ggd]{adjust.cmp}}, \code{\link[ggd]{round.cmp}}, etc.) for the object of the 2nd argument, since they may update the values of the fields. - This function does not change the number of rows in \code{cmp} field, + This method does not change the number of rows in \code{cmp} field, no matter what results are obtained. } \examples{ a <- ggd.set.cmp( data.frame( mean = c( -0.5, 0, 0.5 ), sd = c( 1, 0.8, 1.2 ) ) ) a$cmp; c( a$mean, a$sd ) + ## +1 to mean. a$apply.cmp( function( mean ) mean + 1 ) a$cmp; c( a$mean, a$sd ) - ## double sd of 2nd component. + + ## Double sd of 2nd component. a$apply.cmp( f.sd = function( sd ) { sd[2] <- sd[2] * 2; sd } ) a$cmp; c( a$mean, a$sd ) - ## rotate as index+1 for mean and index-1 for sd. + + ## Rotate as index+1 for mean and index-1 for sd. a$apply.cmp( f.mean = function( mean ) mean[c( 2, 3, 1 )], f.sd = function( sd ) sd[c( 3, 1, 2 )] ) a$cmp; c( a$mean, a$sd ) - ## swap mean and sd. + + ## Swap mean and sd. a$apply.cmp( f.mean = function( m, obj ) obj$cmp$sd, f.sd = function( s, obj ) obj$cmp$mean ) a$cmp; c( a$mean, a$sd ) diff --git a/man/apply.cmp.sub.Rd b/man/apply.cmp.sub.Rd index c70ffaf..a94e3d0 100644 --- a/man/apply.cmp.sub.Rd +++ b/man/apply.cmp.sub.Rd @@ -17,7 +17,7 @@ apply.cmp.sub(f, values, obj) A vector of new values of the column of \code{cmp} field. } \description{ -Calls a applying function to get new values of a column of \code{cmp} field. +Calls an applying function to get new values of a column of \code{cmp} field. } \seealso{ \code{\link[ggd]{apply.cmp}} diff --git a/man/apply.math2.cmp.Rd b/man/apply.math2.cmp.Rd index dc0e5b8..a12e274 100644 --- a/man/apply.math2.cmp.Rd +++ b/man/apply.math2.cmp.Rd @@ -14,7 +14,7 @@ to be used for \code{mean} column.} \item{dg.sd}{A vector of integer similar to \code{dg.mean}, for \code{sd} column.} -\item{obj}{The \code{\link[ggd]{GGD}} object to be processed.} +\item{obj}{The \code{\link[ggd]{GGD}} object.} } \value{ A processed \code{\link[ggd]{GGD}} object. diff --git a/man/bisection.Rd b/man/bisection.Rd index 315bcb2..2637cde 100644 --- a/man/bisection.Rd +++ b/man/bisection.Rd @@ -24,5 +24,5 @@ the convergence is declared.} Solution of the equation f = 0 with tolerances. } \description{ -Solves a equation via bisection method. +Solves an equation via bisection method. } diff --git a/man/calc.mean.Rd b/man/calc.mean.Rd index da73b59..ce0870d 100644 --- a/man/calc.mean.Rd +++ b/man/calc.mean.Rd @@ -7,7 +7,7 @@ calc.mean(mix.type, means, sds) } \arguments{ -\item{mix.type}{The value of \code{mix.type}.} +\item{mix.type}{The value of \code{mix.type}. It allows from \code{1} to \code{4}.} \item{means}{The vector of the mean values of the normal distributions of the components.} @@ -16,10 +16,16 @@ of the components.} of the components.} } \value{ -The mean value of a gradational Gaussian distribution model. +The mean value of the distribution model. } \description{ -Calculates the mean value of a GGD model. -This function does not use \code{\link[stats]{integrate}}, but \code{\link[stats]{pnorm}}, -\code{\link[base]{sqrt}} and four arithmetic operations as needed. +Calculates the mean value of the distribution model. +} +\details{ +This function does not use \code{\link[stats]{integrate}} or other tolerance-requiring +processes. Therefore, the calculation speed and accuracy will be expected in some degree. +However, since \code{\link[base]{sqrt}(pi)} is used where \code{mix.type} is \code{2} +or greater, and \code{\link[stats]{pnorm}} is also used where \code{mix_type = 4}, +it is expected that there will be calculation errors due to their implementation, +in addition to digit losses during arithmetic operations. } diff --git a/man/calc.mean.t4.sub.Rd b/man/calc.mean.t4.sub.Rd index df05b76..8e59878 100644 --- a/man/calc.mean.t4.sub.Rd +++ b/man/calc.mean.t4.sub.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/ggd.mean.sd.R \name{calc.mean.t4.sub} \alias{calc.mean.t4.sub} -\title{[Non-exported] Sub-function of the mean calculation for mix.type = 4} +\title{[Non-exported] Sub-function for mean calculation where mix.type = 4} \usage{ calc.mean.t4.sub(means, sds) } @@ -17,7 +17,7 @@ calc.mean.t4.sub(means, sds) The value of \eqn{\int_{-\infty}^{\infty} x \Psi_i(x) g_i(x) dx}. } \description{ -A sub-function which is used for calculating the mean value where \code{mix.type = 4}. +A sub-function of \code{\link[ggd]{calc.mean}} where \code{mix.type = 4}. It calculates \eqn{\int_{-\infty}^{\infty} x \Psi_i(x) g_i(x) dx}, where \eqn{\Psi_i(x) = \Phi_{i,1}(x) - \dfrac{1}{\sqrt{2}} \Phi_{i,1}^*(x) + @@ -25,6 +25,11 @@ where \eqn{g_i(x) = ( 1 - f_{i,1}(x) / f_{i,1}(\mu_{i,1}) ) f_{i,1}(x) + f_{i,2}(x)^2 / f_{i,2}(\mu_{i,2})} \eqn{( i = 1, 2 )}. -This function does not use \code{\link[stats]{integrate}}, -but \code{\link[stats]{pnorm}}, \code{\link[base]{sqrt}} and four arithmetic operations. +} +\details{ +This function does not use \code{\link[stats]{integrate}} or other tolerance-requiring +processes. Therefore, the calculation speed and accuracy will be expected in some degree. +However, since \code{\link[stats]{pnorm}} and \code{\link[base]{sqrt}(pi)} are used, +it is expected that there will be calculation errors due to their implementation, +in addition to digit losses during arithmetic operations. } diff --git a/man/calc.v.Rd b/man/calc.v.Rd index 8a879c0..9dcac39 100644 --- a/man/calc.v.Rd +++ b/man/calc.v.Rd @@ -15,16 +15,16 @@ calc.v( ) } \arguments{ -\item{mix.type}{The value of \code{mix.type} of the \code{\link[ggd]{GGD}} class.} +\item{mix.type}{The value of \code{mix.type}. It allows from \code{1} to \code{4}.} \item{means}{The mean values of the normal distributions of the components.} \item{sds}{The standard deviations of the normal distributions of the components.} -\item{mean}{The mean of the whole distribution.} +\item{mean}{The mean of the distribution model.} \item{symmetric}{If \code{TRUE}, the distribution model is treated as symmetric. -This option may help reduce calculation errors.} +This option may help to reduce calculation errors.} \item{get.lv}{If \code{TRUE}, this function calculates the lower half variance.} @@ -36,15 +36,19 @@ This option may help reduce calculation errors.} this function calculates the whole variance.} } \value{ -The value of the whole/half variance. +The value of the whole or half variance of the distribution model. } \description{ -Calculates the variance or the half variance of a GGD model. -This function does not use \code{\link[stats]{integrate}}, -but \code{\link[stats]{dnorm}}, \code{\link[stats]{pnorm}}, \code{\link[base]{sqrt}} -and four arithmetic operations. +Calculates the whole or half variance of the distribution model. } \details{ +This function does not use \code{\link[stats]{integrate}} or other tolerance-requiring +processes. Therefore, the calculation speed and accuracy will be expected in some degree. +However, since \code{\link[stats]{dnorm}}, \code{\link[stats]{pnorm}} and +\code{\link[base]{sqrt}(pi)} are used where \code{mix.type} is \code{2} or greater, +it is expected that there will be calculation errors due to their implementation, +in addition to digit losses during arithmetic operations. + For \code{mix.type = 4}, the half variance option of \code{get.lv = TRUE} or \code{get.uv = TRUE} does not work. The reason is how to calculate \eqn{\int_{-\infty}^{\mu} f_{i,1}(x) \Phi_{i,2}(x) dx} without numerical integral function diff --git a/man/calc.v.sub.Rd b/man/calc.v.sub.Rd index bdc39c7..e70114f 100644 --- a/man/calc.v.sub.Rd +++ b/man/calc.v.sub.Rd @@ -2,50 +2,55 @@ % Please edit documentation in R/ggd.mean.sd.R \name{calc.v.sub} \alias{calc.v.sub} -\title{[Non-exported] Sub-functions for variance calculation for mix.type = 2, 3} +\title{[Non-exported] Sub-function for variance calculation where mix.type = 2, 3} \usage{ -calc.v.sub(mix.type, mean, mean.i, sd.i, x, p.sum = 0, k = 0) +calc.v.sub(mix.type, mean, mean.i, sd.i, x, p.sum = 0, i = 0) } \arguments{ -\item{mix.type}{The value which represent the way to mix the normal distributions.} +\item{mix.type}{The value of \code{mix.type}. It allows \code{2} or \code{3}.} -\item{mean}{The mean of the whole distribution.} +\item{mean}{The mean of the distribution model.} -\item{mean.i}{The mean value of the normal distribution of i-th component.} +\item{mean.i}{The mean value of the i-th normal distribution of the component.} -\item{sd.i}{The standard deviation of the normal distribution of i-th component.} +\item{sd.i}{The standard deviation of the i-th normal distribution of the component.} -\item{x}{The upper limit of the integral interval (see formulas in "Details").} +\item{x}{The upper limit of the integral interval (see formulas in 'Details').} \item{p.sum}{The sum of the probabilities of two normal distributions of -the components. This argument is for \code{mix.type = 2}.} +the components at \code{x = q}; the lower or upper limit of the domain +of the distribution. +This argument is for \code{mix.type = 2}.} -\item{k}{The number indicating the normal distribution in the components. +\item{i}{The number indicating which component is operated. This argument is for \code{mix.type = 3}.} } \value{ -Calculated value of the expression shown in "Details". +Calculated value of the expression shown in 'Details'. } \description{ -A sub-function for calculating the variance of a GGD model. -The meaning of this function is depend on \code{mix.type} (see "Details"). -This function dose not use \code{\link[stats]{integrate}}. +A sub-function of \code{\link[ggd]{calc.v}} where \code{mix.type} is \code{2} or \code{3}. +The meaning of this function is depend on \code{mix.type} (see 'Details'). } \details{ -Depending on the value of mix.type, the following calculations are performed without +Depending on the value of \code{mix.type}, the following calculations are performed without \code{\link[stats]{integrate}} but with \code{\link[stats]{dnorm}}, \code{\link[stats]{pnorm}}, \code{\link[base]{sqrt}} and four arithmetic operations, respectively. The variance will be expressed with the sums and differences of the outputs of this function - and sums or products with some simple terms. + and some simple terms. In the following expressions, - \eqn{\mu} is the mean of the whole distribution, + \eqn{\mu} is the mean of the distribution model, \eqn{f_i(x)} is the probability density function of the normal distribution \eqn{\mathcal{N}(\mu_i, \sigma_i^2)}, \eqn{\Phi_i(x)} is the cumulative distribution function of \eqn{\mathcal{N}(\mu_i, \sigma_i^2)}, and \eqn{\bar \Phi(x)} is the mean of two cumulative distribution functions \eqn{\Phi_1(x)} and \eqn{\Phi_2(x)}. + The value of \eqn{q} at the expression for \code{mix.type = 2} is the lower or upper limit + of the domain of the distribution. + In this package, since the domain is over \eqn{(-\infty, \infty)}, + \eqn{q = -\infty} or \eqn{\infty}. \describe{ \item{mix.type = 2}{ @@ -53,12 +58,19 @@ Depending on the value of mix.type, the following calculations are performed wit \int_{-\infty}^x (t - \mu)^2 (\Phi_i(t) - \bar \Phi(q)) f_i(t) \ dt}} \item{mix.type = 3}{ - \deqn{k = 1, 3 \ : - \ \displaystyle + \deqn{i = 1, 3: \ + \displaystyle \int_{-\infty}^x (t - \mu)^2 (1 - \dfrac{f_i(t)}{f_i(\mu_i)}) f_i(t) \ dt} - \deqn{k = 2 \ : - \ \displaystyle - \int_{-\infty}^x (t - \mu)^2 \dfrac{f_i(t)^2}{f_i(\mu_i)} f_i(t) \ dt}} + \deqn{i = 2: \quad \ + \displaystyle + \int_{-\infty}^x (t - \mu)^2 \dfrac{f_i(t)^2}{f_i(\mu_i)} f_i(t) \ dt + \qquad \ \ }} } + + This function does not use \code{\link[stats]{integrate}} or other tolerance-requiring + processes. Therefore, the calculation speed and accuracy will be expected in some degree. + However, since \code{\link[stats]{dnorm}}, \code{\link[stats]{pnorm}} and + \code{\link[base]{sqrt}(pi)} are used, it is expected that there will be calculation errors + due to their implementation, in addition to digit losses during arithmetic operations. } diff --git a/man/calc.v.sub.t4.Rd b/man/calc.v.sub.t4.Rd index 94e2dfc..67e5d4e 100644 --- a/man/calc.v.sub.t4.Rd +++ b/man/calc.v.sub.t4.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/ggd.mean.sd.R \name{calc.v.sub.t4} \alias{calc.v.sub.t4} -\title{[Non-exported] A sub-function for variance calculation for mix.type = 4} +\title{[Non-exported] Sub-function for variance calculation where mix.type = 4} \usage{ calc.v.sub.t4(means, sds) } @@ -17,13 +17,19 @@ calc.v.sub.t4(means, sds) The value of \eqn{\int_{-\infty}^{\infty} x^2 \Psi_i(x) g_i(x) dx}. } \description{ -A sub-function for calculating the variance of a GGD model where \code{mix.type = 4}. +A sub-function of \code{\link[ggd]{calc.v}} where \code{mix.type = 4}. This function calculates \eqn{\int_{-\infty}^{\infty} x^2 \Psi_i(x) g_i(x) dx}, where \eqn{\Psi_i(x) = \Phi_{i,1}(x) - \dfrac{1}{\sqrt{2}} \Phi_{i,1}^*(x) + \dfrac{1}{\sqrt{2}} \Phi_{i,2}^*(x)}, \eqn{g_i(x) = ( 1 - f_{i,1}(x) / f_{i,1}(\mu_{i,1}) ) f_{i,1}(x) + f_{i,2}(x)^2 / f_{i,2}(\mu_{i,2})} -with fixing \eqn{i}. This function does not use \code{\link[stats]{integrate}}, -but \code{\link[stats]{pnorm}}, \code{\link[base]{sqrt}} and four arithmetic operations. +\eqn{( i = 1, 2 )}. +} +\details{ +This function does not use \code{\link[stats]{integrate}} or other tolerance-requiring +processes. Therefore, the calculation speed and accuracy will be expected in some degree. +However, since \code{\link[stats]{dnorm}}, \code{\link[stats]{pnorm}} and +\code{\link[base]{sqrt}(pi)} are used, it is expected that there will be calculation errors +due to their implementation, in addition to digit losses during arithmetic operations. } diff --git a/man/calc.v.t4.via.integrate.Rd b/man/calc.v.t4.via.integrate.Rd index a8f9d84..927b92f 100644 --- a/man/calc.v.t4.via.integrate.Rd +++ b/man/calc.v.t4.via.integrate.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/ggd.mean.sd.R \name{calc.v.t4.via.integrate} \alias{calc.v.t4.via.integrate} -\title{[Non-exported] Half variance computation for mix.type = 4} +\title{[Non-exported] Half variance computation where mix.type = 4} \usage{ calc.v.t4.via.integrate( means, @@ -17,22 +17,22 @@ calc.v.t4.via.integrate( \item{sds}{The standard deviations of the normal distributions of the components.} -\item{mean}{The mean of the whole distribution.} +\item{mean}{The mean of the distribution model.} \item{get.lv}{If \code{TRUE}, computes the lower half variance.} \item{get.uv}{If \code{TRUE}, computes the upper half variance. Although it is not recommended to set both \code{get.lv} and \code{get.uv} to \code{TRUE}, -if both are \code{TRUE}, get.lv takes priority. +if both are \code{TRUE}, \code{get.lv} takes priority. If both are \code{FALSE}, computes the whole variance.} } \value{ A list of the output of \code{\link[stats]{integrate}} - as the result of the half/whole variance computation. + as the result of the half or whole variance computation. } \description{ -Using \code{\link[stats]{integrate}}, -computes the lower/upper half variance for \code{mix.type = 4}. -Computing the whole variance with \code{\link[stats]{integrate}} is also enabled. +Using \code{\link[stats]{integrate}}, computes the lower or upper half variance +of the distribution model where \code{mix.type = 4}. +This function can also compute the whole variance using \code{\link[stats]{integrate}}. } diff --git a/man/cat.table.Rd b/man/cat.table.Rd index 5cbef7b..bd14072 100644 --- a/man/cat.table.Rd +++ b/man/cat.table.Rd @@ -7,7 +7,7 @@ cat.table(x, file = "", top.text = "", digits = 15) } \arguments{ -\item{x}{The object to be written, should be a matrix or data frame.} +\item{x}{The object to be output, should be a matrix or data frame.} \item{file}{A \link[base]{connection}, or a character string naming the file to print to. @@ -16,17 +16,16 @@ the console unless redirected by \link[base]{sink}.} \item{top.text}{A character string to be output as the first element of the header.} -\item{digits}{The number of significant digits to print (see \link[base]{signif}). -Valid values are integers from 1 to 22 with default 15.} +\item{digits}{The number of significant digits (see \link[base]{signif}) to print. +Integers from \code{1} to \code{22} with default \code{15} are allowed.} } \value{ An invisible \code{NULL}. } \description{ -Prints the argument \code{x} (it should be a data frame or matrix) -to a file or \link[base]{connection} with the CSV format. -This function use \link[base]{cat} to output. -When outputting real numbers, the precision can be specified with \code{digits} argument. +Outputs a data frame or a matrix to a file or \link[base]{connection} with the CSV format +using \link[base]{cat}. +The precision for real numbers can be indicated with \code{digits} argument. } \examples{ ggd:::cat.table( data.frame( a = 1:6 * pi, b = pi^(1:6) ), top.text = "PI", digits = 10 ) diff --git a/man/d.Rd b/man/d.Rd index 780a917..a5a3623 100644 --- a/man/d.Rd +++ b/man/d.Rd @@ -15,7 +15,7 @@ The values of the probability density function for the given x-coordinates. } \description{ Gets the values of the probability density function for the given x-coordinates. -This function works like \code{\link[stats]{dnorm}} for a normal distribution. +This method works like \code{\link[stats]{dnorm}} for a normal distribution. } \examples{ a <- GGD$new() diff --git a/man/separate.data.quarter.Rd b/man/divide.data.quarter.Rd similarity index 76% rename from man/separate.data.quarter.Rd rename to man/divide.data.quarter.Rd index 2b947ff..ff3378f 100644 --- a/man/separate.data.quarter.Rd +++ b/man/divide.data.quarter.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/ggd.nls.freq.R -\name{separate.data.quarter} -\alias{separate.data.quarter} +\name{divide.data.quarter} +\alias{divide.data.quarter} \title{[Non-exported] Quartering data} \usage{ -separate.data.quarter(x, data, data.mean) +divide.data.quarter(x, data, data.mean) } \arguments{ \item{x}{A vector of x-coordinates arranged in ascending order @@ -34,8 +34,8 @@ Divides numeric data into 4 groups as: at first, it divides the data into two groups by the mean of the data, and next, divides each data into two groups so that the number of elements are equal to each other. -If there is an x-coordinate that is exactly equal to the mean, -put that element in both the 2nd and 3rd part. -If the first dividing makes a group with odd number of elements, put the element at -the dividing point in both the lower and upper x-coordinate groups after second dividing. +If there is an x-coordinate equal to the mean, +the element is included in both of the 2nd and 3rd groups. +In the second division, if the original group has an odd number of elements, +the element at the dividing point is included in both divided groups. } diff --git a/man/dp.t3.Rd b/man/dp.t3.Rd index aaca8e6..eb38896 100644 --- a/man/dp.t3.Rd +++ b/man/dp.t3.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/ggd.trace.q.R +% Please edit documentation in R/ggd.1.R \name{dp.t3} \alias{dp.t3} \title{[Non-exported] PDF/CDF for mix.type = 3} @@ -13,7 +13,7 @@ dp.t3(x, means, sds, f.t3) \item{sds}{The vector of sd values of the 3 components.} -\item{f.t3}{A function handle, +\item{f.t3}{A function handle; \code{ggd:::f.t3.d} for PDF or \code{ggd:::f.t3.p} for CDF.} } \value{ @@ -21,8 +21,8 @@ The vector of values of the probability density function or the cumulative distribution function. } \description{ -Calculates the values of the probability density function or -the cumulative distribution function of the GGD model with \code{mix.type = 3}. +Calculates the values of the probability density function (PDF) or +the cumulative distribution function (CDF) of the GGD model with \code{mix.type = 3}. Both \code{means} and \code{sds} vectors need 3 elements for this function. Where with two components, you must set \code{means[3]} and \code{sds[3]} the same values of \code{means[1]} and \code{sds[1]}. diff --git a/man/exclude.freq.edge.Rd b/man/exclude.freq.edge.Rd index 021c9bc..9d480bb 100644 --- a/man/exclude.freq.edge.Rd +++ b/man/exclude.freq.edge.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/ggd.nls.freq.R \name{exclude.freq.edge} \alias{exclude.freq.edge} -\title{[Non-exported] Exclude small frequencies of edges} +\title{[Non-exported] Exclude small frequencies on edges} \usage{ exclude.freq.edge(x, freq) } @@ -19,6 +19,6 @@ A list containing components The vectors of frequencies after excluding.} } \description{ -Excludes data with \code{0} or extremely small frequency on both edges of the range of +Excludes data with \code{0} or extremely small frequencies on both edges of the range of the x-coordinates from data of a frequency distribution. } diff --git a/man/get.cmp.tex.Rd b/man/get.cmp.tex.Rd index 3a1ef82..240f73d 100644 --- a/man/get.cmp.tex.Rd +++ b/man/get.cmp.tex.Rd @@ -2,21 +2,21 @@ % Please edit documentation in R/ggd.tex.R \name{get.cmp.tex} \alias{get.cmp.tex} -\title{[Non-exported] TeX format for mean and standard deviation} +\title{[Non-exported] TeX format for mean values and standard deviations} \usage{ get.cmp.tex(obj, format.num) } \arguments{ \item{obj}{A \code{\link[ggd]{GGD}} object.} -\item{format.num}{A function to format each number of value of a parameter; -mean value and standard deviation. See \code{\link[ggd]{tex}}.} +\item{format.num}{A function to format each numeric value of mean values and +standard deviations. See \code{\link[ggd]{tex}}.} } \value{ -TeX-formatted texts to represent the mean values and standard deviations of +TeX-formatted texts representing the mean values and standard deviations of the normal distributions of the components. } \description{ -Gets the TeX-formatted texts to represent the mean values and standard deviations of +Gets the TeX-formatted texts representing the mean values and standard deviations of the normal distributions of the components. } diff --git a/man/get.cmp.with.nls.coef.Rd b/man/get.cmp.with.nls.coef.Rd index 4440ca1..ed1ee6c 100644 --- a/man/get.cmp.with.nls.coef.Rd +++ b/man/get.cmp.with.nls.coef.Rd @@ -13,15 +13,15 @@ with the result of \code{\link[stats]{nls}}.} \item{mix.type}{The value for \code{mix.type} field.} \item{grad}{A character string indicating the method of gradation. - If \code{"v3"}, constructing with 3 components is enforcedly, - even if it is possible to construct with 2 components. In this function, \code{grad} argument has no priority over \code{mix.type} argument. Therefore, \code{grad = "v2"} or \code{"v3"} works only if \code{mix.type = 3} is indicated. And if \code{mix.type = 3} is indicated, - either \code{grad = "v2"} or \code{"v3"} must be indicated.} + either \code{grad = "v2"} or \code{"v3"} must be indicated. + If \code{"v3"}, the number of components will forced to be 3, + even if the values in \code{coefs} represent a 2-component model.} \item{eq.mean}{A logical; the flag whether to make all of the mean values of the normal distributions of the components to be equal.} diff --git a/man/get.d.freq.Rd b/man/get.d.freq.Rd index d30089c..8e4cd7d 100644 --- a/man/get.d.freq.Rd +++ b/man/get.d.freq.Rd @@ -10,18 +10,16 @@ get.d.freq(x, freq, total = sum(freq)) \item{x}{A vector of x-coordinates. Duplicate values are not allowed.} \item{freq}{A vector of frequencies following \code{x}. -The values of frequencies must be positive. Both integers and real numbers are allowed for the values.} \item{total}{Total value of the frequencies. If \code{NULL} (the default), - the total of \code{freq}, i.e., \code{\link[base]{sum}(data[[freq]])} - (on \code{\link[stats]{complete.cases}} of \code{x} and \code{freq}) + the total of \code{freq}, i.e., \code{\link[base]{sum}(freq)} is used for it.} } \value{ -The vector of expected probability density value at each of x-coordinates. +The vector of expected probability density values following the x-coordinates. } \description{ Gets the probability density value at each of the x-coordinates based on diff --git a/man/get.nls.params.Rd b/man/get.nls.params.Rd index c812a12..ce16b4b 100644 --- a/man/get.nls.params.Rd +++ b/man/get.nls.params.Rd @@ -17,15 +17,14 @@ and non-duplicated.} \item{mix.type}{The value for \code{mix.type} field.} \item{grad}{A character string indicating the method of gradation. - If \code{"v3"}, constructing with 3 components is enforcedly, - even if it is possible to construct with 2 components. In this function, \code{grad} argument have no priority over \code{mix.type} argument. Therefore, \code{grad = "v2"} or \code{"v3"} works only if \code{mix.type = 3} is indicated. And if \code{mix.type = 3} is indicated, - either \code{grad = "v2"} or \code{"v3"} must be indicated.} + either \code{grad = "v2"} or \code{"v3"} must be indicated. + If \code{"v3"}, the number of components will forced to be 3.} \item{eq.mean}{A logical; the flag whether to make all of the mean values of the normal distributions of the components to be equal.} @@ -34,19 +33,21 @@ the normal distributions of the components to be equal.} the normal distributions of the components to be equal.} \item{start.level}{An integer from \code{0} to \code{3} or \code{NA}; - the level at which to guess - the initial \code{start} parameters of \code{\link[stats]{nls}}. + the desired level at which to guess + the initial \code{start} parameters for \code{\link[stats]{nls}}. - Details for each level are as: + The detail of each level is: \itemize{ \item from \code{0} to \code{3}: Same as \code{start.level} in arguments of \code{\link[ggd]{nls.freq}}. - \item \code{NA}: All values of \code{start} will be set to \code{NA}. + \item \code{NA}: All elements in \code{start} will be \code{NA}. }} } \value{ -A list containing \code{formula} and \code{start} for the arguments of - \code{\link[stats]{nls}} and adopted \code{start.level} value. +A list containing \code{formula} and \code{start} for \code{\link[stats]{nls}} + and adopted \code{start.level}. + The value of \code{start.level} may be different from the argument value + if initial guessing has failed at the desired level. } \description{ Gets a list of main arguments for \code{\link[stats]{nls}} (except for \code{data}), diff --git a/man/ggd.cor.vs.freq.Rd b/man/ggd.cor.vs.freq.Rd index 140cb00..9ff1e39 100644 --- a/man/ggd.cor.vs.freq.Rd +++ b/man/ggd.cor.vs.freq.Rd @@ -17,13 +17,14 @@ ggd.cor.vs.freq(objs, x, freq, total = sum(freq), cor.method = NULL) \item{total}{Total value of the frequencies.} \item{cor.method}{The \code{method} argument for \code{\link[stats]{cor}}. -It represents the correlation coefficient method. -If \code{NULL}, it uses the default method of \code{\link[stats]{cor}}. +It is a character string indicating which correlation coefficient +(or covariance) is to be computed. +If \code{NULL}, it uses the default \code{method}. See \code{\link[stats]{cor}} for more information.} } \value{ A vector of correlation coefficients. - Its order follows the order of the elements of the \code{objs} argument. + Its order follows the order of the elements in \code{objs} argument. If \code{cmp} field of an \code{\link[ggd]{GGD}} object in \code{objs} has no rows, \code{NA} will be set to the element. } @@ -38,11 +39,10 @@ two numeric vectors like as other non-exported functions, not a data frame. freq = c( 1517, 2292, 2513, 2763, 3724, 4046, 4713, 7947, 10997, 11824, 11133, 7868, 4692, 4103, 3698, 2740, 2549, 2284, 1499, 1147, 918 ) ) - a <- ggd.nls.freq( df, kind = "Mean-Eq.*Vertical" )$obj - ggd.cor.vs.freq( a, df$x, df$freq ) - objs <- list( ggd.nls.freq( df, kind = "Mean-Eq.*Vertical" )$obj, ggd.nls.freq( df, kind = "Sigma-Eq.*Vertical" )$obj, - ggd.nls.freq( df, kind = "Mean-Diff.*Sigma-Diff.*Vertical" )$obj ) + ggd.nls.freq( df, kind = "Vertical" )$obj ) + + ggd.cor.vs.freq( objs[[1]], df$x, df$freq ) ggd.cor.vs.freq( objs, df$x, df$freq ) } diff --git a/man/ggd.get.t3.cmp.Rd b/man/ggd.get.t3.cmp.Rd index 26ad4e7..fdc532c 100644 --- a/man/ggd.get.t3.cmp.Rd +++ b/man/ggd.get.t3.cmp.Rd @@ -21,13 +21,13 @@ The data frame for \code{cmp} field. \description{ Gets a data frame for \code{cmp} field for \code{mix.type = 3}. Each of \code{means} and \code{sds} arguments must has 3 elements in order of -\code{[1]} left-tail side, \code{[2]} top side and \code{[3]} right-tail side. +\code{[1]} left-tail side, \code{[2]} top side, and \code{[3]} right-tail side. } \examples{ means <- c( 0.2, 0, 0.2 ); sds <- c( 1.2, 0.9, 1.2 ) - ggd.get.t3.cmp( means, sds ) # 2 components - ggd.get.t3.cmp( means, sds, grad = "v3" ) # 3 components + ggd.get.t3.cmp( means, sds ) ## 2 components + ggd.get.t3.cmp( means, sds, grad = "v3" ) ## 3 components means <- rep( 0.5, 3 ); sds <- rep( 2.5, 3 ) - ggd.get.t3.cmp( means, sds ) # 2 components even if normal distribution + ggd.get.t3.cmp( means, sds ) ## 2 components even if normal distribution } diff --git a/man/ggd.init.start.Rd b/man/ggd.init.start.Rd index 5db4c39..8fc416a 100644 --- a/man/ggd.init.start.Rd +++ b/man/ggd.init.start.Rd @@ -10,20 +10,12 @@ ggd.init.start() An all-\code{NULL} list with the length of 16 (= \code{length(ggd:::kinds)}). } \description{ -Generates a list of 16 (= \code{length(ggd:::kinds)}) \code{NULL} lists. -} -\details{ -If you want to indicate some \code{start} lists for \code{\link[ggd]{ggd.nls.freq.all}} -by yourself, you can give the lists to the elements of the returned list of this function, -and give it to \code{\link[ggd]{ggd.nls.freq.all}} as \code{start} argument. - -You don't have to set all elements of the returned list by yourself, -since internally calculated default values will be used for \code{start} of -\code{\link[stats]{nls}} where the elements of the list are \code{NULL}. - -The format of each element can be got with \code{\link[ggd]{ggd.start.template}}. -In addition, \code{\link[ggd]{ggd.kind}} and \code{\link[ggd]{ggd.kind.index}} functions -may help you to know the kind of distribution which the index number represents. +Generates a list of 16 \code{NULL} lists. +If you want to indicate some start values for \code{\link[ggd]{ggd.nls.freq.all}}, +insert a list of the start values instead of \code{NULL} at some elements of +the 16-\code{NULL} list and use it as \code{start} argument. +For more information about the format of each element and other details, +see \code{\link[ggd]{ggd.start.template}} and \code{\link[ggd]{ggd.nls.freq.all}}. } \examples{ ## Let's approximate this frequency distribution. @@ -33,25 +25,25 @@ may help you to know the kind of distribution which the index number represents. 7947, 10997, 11824, 11133, 7868, 4692, 4103, 3698, 2740, 2549, 2284, 1499, 1147, 918 ) ) - ## get the initial list + ## Get the initial list. start.list <- ggd.init.start() start.list - ## check the parameters for ggd:::kinds[14]. + ## Check the parameters for ggd:::kinds[14]. ggd.start.template( 14 ) - ## set the start parameters of ggd:::kinds[14] to get better result + ## Set the start values of ggd:::kinds[14] to get better result. start.list[[14]]$mean.1.1 <- 0.426831 start.list[[14]]$mean.1.2 <- -0.130757 start.list[[14]]$mean.2.1 <- 0.426831 start.list[[14]]$mean.2.2 <- -0.130757 start.list[[14]]$sqrt.sd <- sqrt( 0.812744 ) - ## try ggd.nls.freq.all (the result of ggd:::kinds[14] will be better than ggd:::kinds[8]) + ## Run ggd.nls.freq.all (the result of ggd:::kinds[14] will be better than ggd:::kinds[8]). result <- ggd.nls.freq.all( df, start.level = 1, start = start.list ) result$cor[8] result$cor[14] } \seealso{ -\code{\link[ggd]{ggd.nls.freq.all}}, \code{\link[ggd]{ggd.start.template}} +\code{\link[ggd]{ggd.start.template}}, \code{\link[ggd]{ggd.nls.freq.all}} } diff --git a/man/ggd.kind.Rd b/man/ggd.kind.Rd index 613784c..92ad921 100644 --- a/man/ggd.kind.Rd +++ b/man/ggd.kind.Rd @@ -7,21 +7,13 @@ ggd.kind(objs) } \arguments{ -\item{objs}{A vector or a list of elements indicating the kind of distribution. +\item{objs}{A vector or a list of elements indicating the kind of distribution model. Each element must be a character string of a regular expression pattern matching to an element of \code{ggd:::kinds} or an index number of - \code{ggd:::kinds}, or a \code{\link[ggd]{GGD}} object, or a \code{NA}. + \code{ggd:::kinds}, or a \code{\link[ggd]{GGD}} object, or an \code{NA}. - If character strings are indicated, each string matches only one element of - \code{ggd:::kinds} of the first element along with the index order of - \code{ggd:::kinds.match.order} which is - \code{ c(1L, 4L, 2L, 3L, 7L, 5L, 6L, 10L, 8L, 9L, 13L, 11L, 12L, - 16L, 14L, 15L)}. - - The order is designed, while \code{ggd:::kinds} is ordered by - intuitive degrees of freedom, for practical purposes so that - the \code{"Mean-Differed Sigma-Differed"} model, which has more degrees of - freedom than the others of the same type, can be matched first.} + The matching method follows that of \code{objs} argument of + \code{\link[ggd]{ggd.kind.index}}.} } \value{ The vector of character strings which represent the kinds of distributions, diff --git a/man/ggd.kind.index.Rd b/man/ggd.kind.index.Rd index 4b5b39c..866cc56 100644 --- a/man/ggd.kind.index.Rd +++ b/man/ggd.kind.index.Rd @@ -7,10 +7,12 @@ ggd.kind.index(objs, undef.err = FALSE) } \arguments{ -\item{objs}{A vector or a list of elements indicating the kind of distribution. +\item{objs}{A vector or a list of elements indicating the kind of + distribution model. + Each element must be a character string of a regular expression pattern matching to an element of \code{ggd:::kinds} or an index number of - \code{ggd:::kinds}, or a \code{\link[ggd]{GGD}} object, or a \code{NA}. + \code{ggd:::kinds}, or a \code{\link[ggd]{GGD}} object, or an \code{NA}. If a character string is indicated as an element, the string matches only one element of \code{ggd:::kinds} of @@ -18,18 +20,15 @@ ggd.kind.index(objs, undef.err = FALSE) \code{ggd:::kinds.match.order} which is \code{ c(1L, 4L, 2L, 3L, 7L, 5L, 6L, 10L, 8L, 9L, 13L, 11L, 12L, 16L, 14L, 15L)}. - - The order of \code{ggd:::kinds.match.order} is designed, - while \code{ggd:::kinds} is ordered by intuitive degrees of freedom, - for practical purposes so that \code{"Mean-Differed Sigma-Differed"} - model, which has more degrees of freedom than the others of - the same type, can be matched first. + The order is designed for practical purposes so that + the '\code{Mean-Differed Sigma-Differed}' model, + which has more degrees of freedom than the others of the same type, + can be matched first. If an element is \code{NA}, \code{NA_integer_} will be returned for it.} -\item{undef.err}{A logical; -If \code{TRUE}, an error occur if a not-\code{NA} element of \code{objs} -does not match any element of \code{ggd:::kinds}. +\item{undef.err}{A logical. If \code{TRUE}, an error occurs if a not-\code{NA} element +of \code{objs} does not match any element of \code{ggd:::kinds}. If \code{FALSE}, \code{NA_integer_} will be returned for it.} } \value{ diff --git a/man/ggd.mix.type.for.Rd b/man/ggd.mix.type.for.Rd index c0a66a4..0306ec3 100644 --- a/man/ggd.mix.type.for.Rd +++ b/man/ggd.mix.type.for.Rd @@ -23,12 +23,12 @@ ggd.mix.type.for( \item{kind}{A character string or a numeric value or a \code{\link[ggd]{GGD}} object which indicates the kind of distribution model. + The matching method of \code{kind} follows that of + \code{objs} argument of \code{\link[ggd]{ggd.kind.index}}. + This argument works when the length of \code{mix.type} argument is \code{0}, and \code{grad} is \code{"default"}. - The matching method of this argument follows that of elements of - the \code{objs} argument of the \code{\link[ggd]{ggd.kind.index}}. - If \code{NA} is indicated, \code{NA_integer_} will be returned. If indicated character string pattern or index number does not match to any element of \code{ggd:::kind}, an error will occur.} @@ -52,8 +52,8 @@ An integer of \code{mix.type} value appropriate for a distribution model \description{ Gets the value for \code{mix.type} field of \code{GGD} object which is appropriate to given \code{grad} value. -If \code{grad = "default"}, the return value will be the value of \code{mix.type} argument -or the value appropriate for \code{kind} argument. +If \code{grad} is \code{"default"}, the return value will be the value of +\code{mix.type} argument or the value appropriate for \code{kind} argument. } \examples{ ggd.mix.type.for( grad = "normal" ) ## 0 diff --git a/man/ggd.nls.freq.all.Rd b/man/ggd.nls.freq.all.Rd index e60d1fc..18debd8 100644 --- a/man/ggd.nls.freq.all.Rd +++ b/man/ggd.nls.freq.all.Rd @@ -23,7 +23,7 @@ ggd.nls.freq.all( See \code{\link[ggd]{nls.freq}} for more information. Column names and indexes for \code{x} and \code{freq} are flexible. - You can specify them with next two arguments.} + You can indicate them with next two arguments.} \item{x}{The column name or index number for the column of x-coordinates in \code{data}.} @@ -35,20 +35,18 @@ in \code{data}.} See \code{\link[ggd]{nls.freq}} for more information.} \item{start.level}{A numeric value of integer in from \code{0} to \code{3} or \code{100} -with default \code{100}; -the level at which to guess the initial \code{start} parameters -of \code{\link[stats]{nls}}. +with default \code{100}; the level of guessing the start values +for \code{start} argument of \code{\link[stats]{nls}}. See \code{\link[ggd]{nls.freq}} for more information.} \item{start}{A \bold{list of lists} with the length of 16 - for each of the \code{start} arguments for \code{\link[stats]{nls}} - as initial values. - Each element (a list) will give to the \code{start} argument of + for each of \code{start} arguments of \code{\link[stats]{nls}} + as start values. + Each element (a list) will give to \code{start} argument of \code{\link[stats]{nls}} one by one. - For initial values for which \code{NULL} is indicated as the list - in the \code{start} argument, internally computed initial values - depending on \code{start.level} are used. + For cases where \code{NULL} is indicated in this argument, + internally computed start values depending on \code{start.level} are used. As an auxiliary tool for making a list of 16 lists, you can use \code{\link[ggd]{ggd.init.start}} function @@ -59,14 +57,14 @@ See \code{\link[ggd]{nls.freq}} for more information.} In addition, \code{\link[ggd]{ggd.kind}} and \code{\link[ggd]{ggd.kind.index}} functions may help you whether each index number of \code{start} represents what kind of distribution. - See "Examples" for usages of these tools.} + See 'Examples' for usages of these tools.} \item{control}{The \code{control} argument for \code{\link[stats]{nls}}. See \code{\link[stats]{nls.control}} for more information.} \item{not.use.nls}{A logical. If \code{TRUE}, this function does not use \code{\link[stats]{nls}} - and it outputs objects having the initial values in the \code{cmp} field + and it outputs objects having the start values in \code{cmp} field as the results. If \code{FALSE}, this function uses \code{\link[stats]{nls}}. @@ -74,24 +72,25 @@ See \code{\link[stats]{nls.control}} for more information.} other than \code{100}. A warning will occur if \code{TRUE} when \code{start.level} is \code{100}. - You can use \code{not.use.nls = TRUE} to check the initial values - when an error has occurred at this function.} + You can use \code{not.use.nls = TRUE} to check whether the start values + are appropriate when obtained an undesirable result from this function.} \item{cor.method}{The \code{method} argument for \code{\link[stats]{cor}}. -It represents the correlation coefficient method. +It is a character string indicating which correlation coefficient +(or covariance) is to be computed. If \code{NULL}, it uses the default method of \code{\link[stats]{cor}}. See \code{\link[stats]{cor}} for more information.} \item{...}{Each argument for \code{\link[stats]{nls}} can be indicated. -See "Arguments" of \code{\link[stats]{nls}} for more information.} +See 'Arguments' of \code{\link[stats]{nls}} for more information.} } \value{ -A list containing components (invisible for \code{GGD} method) +A list containing components \item{best}{ The \code{\link[ggd]{GGD}} object which has got the highest correlation coefficient. - That is, the most approximate to the given frequency distribution - in all of the supported distribution models. + That is, it would be the most approximate to + the given frequency distribution in all of the supported models. If there are some models which have got the same highest correlation coefficient, the object with the earlier \code{kind.index} is given priority.} @@ -102,20 +101,20 @@ A list containing components (invisible for \code{GGD} method) \item{obj}{ The list of 16 \code{\link[ggd]{GGD}} objects - ordered by \code{kind.index}; the index number in \code{ggd:::kinds}. + ordered along with \code{ggd:::kinds}. If an error has occurred, the element will be a cleared object.} \item{cor}{ - The vector of the correlation coefficient of + The vector of the correlation coefficients between the result of each model and the frequency distribution. \code{NA} will be given for an error case or an extremely bad result.} \item{detail}{ - The list of 16 elements of outputs of \code{\link[ggd]{nls.freq}}. + The list of 16 results of \code{\link[ggd]{nls.freq}}. Normally, each element is a list of the output of - \code{\link[ggd]{nls.freq}}, - but if an error has occurred, the element will be an error condition. - See "Value" of \code{\link[ggd]{nls.freq}} for more information.} + \code{\link[ggd]{nls.freq}}. + But if an error has occurred, the element will be an error condition. + See 'Value' of \code{\link[ggd]{nls.freq}} for more information.} } \description{ Approximates the given frequency distribution with all of distribution models @@ -143,29 +142,37 @@ The output lists are ordered by \code{ggd:::kinds} as: \item Mean-Equaled Sigma-Differed Horizontal-Vertical Gradational Distribution \item Mean-Differed Sigma-Differed Horizontal-Vertical Gradational Distribution } -Each index numbers of above list are -also used for \code{kind.index} field of \code{\link[ggd]{GGD}} class. +Each index number of above list is +also set into \code{kind.index} field of each \code{\link[ggd]{GGD}} object. This function generates 16 \code{\link[ggd]{GGD}} objects and calls \code{\link[ggd]{nls.freq}} method 16 times. By default, \code{\link[ggd]{nls.freq}} is called with \code{warnOnly = TRUE}, so \code{\link[ggd]{nls.freq}} does not generate errors, but generates warnings often. When a warning occur, this function generates another warning like -"\code{Warning for kind = xx :}" to inform which \code{kind.index} gets a poor result +'\code{Warning for kind = xx :}' to inform which \code{kind.index} gets a poor result (poor, but may be accurate enough). So when one warning has occurred, two warnings will occur eventually. If you indicate \code{warnOnly = FALSE} in \code{control} argument and overwrite \code{warnOnly} option, \code{\link[ggd]{nls.freq}} can generate errors. -If an error occur in one of \code{\link[ggd]{nls.freq}} processes, -this function throws messages like "\code{Error for kind = xx :}" and "\code{Error in ...}" -instead of throwing error and does not stop, +If an error occurs in one of \code{\link[ggd]{nls.freq}} processes, +this function throws messages like '\code{Error for kind = xx :}' and '\code{Error in ...}' +instead of throwing an error and skips the process, then tries other \code{\link[ggd]{nls.freq}} processes. For the result of error-occurred \code{kind.index}, a cleared \code{\link[ggd]{GGD}} object -will be got as an element of \code{obj} (see "Value"). +will be got as the element of \code{obj} (see 'Value'). } \examples{ - ## Preparing. + ## Preparing: + df <- data.frame( + x = seq( -2, 2, 0.2 ), + freq = c( 1517, 2292, 2513, 2763, 3724, 4046, 4713, + 7947, 10997, 11824, 11133, 7868, 4692, 4103, + 3698, 2740, 2549, 2284, 1499, 1147, 918 ) ) + + ## This function plots probability densities obtained from the frequency distribution + ## and the probability density function of a GGD object. plot.freq.and.d <- function( obj, x, freq ) { xlim <- c( min( x ), max( x ) ) @@ -176,32 +183,31 @@ will be got as an element of \code{obj} (see "Value"). type = "l", xlim = xlim, ylim = ylim ) } - df <- data.frame( - x = seq( -2, 2, 0.2 ), - freq = c( 1517, 2292, 2513, 2763, 3724, 4046, 4713, - 7947, 10997, 11824, 11133, 7868, 4692, 4103, - 3698, 2740, 2549, 2284, 1499, 1147, 918 ) ) - - ## Try ggd.nls.freq.all. - ## Here, "start.level = 1" is specified to get less-than-ideal results - ## to explain how to use "start" argument. + ## Examples: + ## We specify 'start.level = 1' here in order to obtain less-than-ideal results purposely + ## to explain how to use 'start' argument using the results. result <- ggd.nls.freq.all( df, start.level = 1 ) ## Show the results. result$cor - result$best.cor - result$best + result$best.cor; result$best$kind.index - ## Check that the value of cor for kind = 14 is very low. + ## Check that the value of 'cor' for kind = 14 is very low. result$cor[[14]] - ## Let's try to increase the value of cor by changing the initial values. +\dontrun{ + ## If you want to ignore warning cases at ggd.nls.freq.all, + ## indicate 'warnOnly = FALSE' in 'control' option. + ## This option turns warnings into errors, and cases which cause errors are skipped. + result <- ggd.nls.freq.all( df, start.level = 1, control = list( warnOnly = FALSE ) )} + + ## Let's try to increase the value of 'cor' by changing the start values. ## - ## There is an easy and good way to solve this problem, - ## that is to remove "start.level = 1". - ## But here, we use "start" argument with remaining "start.level" for explaining. + ## There is an easy and good way to increase the value of 'cor', + ## that is to remove 'start.level = 1'. + ## But here, we keep 'start.level = 1' and use 'start' argument for explaining. ## - ## First, to see what kind = 14 is, display the kind. + ## First, to see what 'kind = 14' is, display the kind. result$obj[[14]]$kind ## Also, using ggd.kind, you can get the character string for the index. @@ -210,33 +216,56 @@ will be got as an element of \code{obj} (see "Value"). ## Inversely, using ggd.kind.index, you can get index for each kind. ggd.kind.index( "Mean-Differed Sigma-Equaled Horizontal-Vertical" ) - ## Show the cmp field of kind = 14 and plots. + ## Show the 'cmp' field and plot the probability density function. result$obj[[14]]$cmp plot.freq.and.d( result$obj[[14]], df$x, df$freq ) - ## Now, for the initial values, we are going to use the result of - ## kind = "2-Mean-Differed Sigma-Equaled Vertical Gradational Distribution". + ## Now, for the start values, we are going to use the result of + ## '2-Mean-Differed Sigma-Equaled Vertical Gradational Distribution'. ggd.kind.index( "2-Mean-Differed Sigma-Equaled Vertical" ) ## 8 + result$cor[[8]] result$obj[[8]]$cmp - ## Display the parameters for the initial values for kind = 14. + ## Display the parameters for the start values for kind = 14. ggd.start.template( 14 ) - ## Set the initial values for kind = 14. + ## Specify the start values for kind = 14. start.list <- ggd.init.start() start.list[[14]] <- ggd.start.template( 14 ) start.list[[14]]$mean.1.1 <- result$obj[[8]]$cmp$mean[1] start.list[[14]]$mean.1.2 <- result$obj[[8]]$cmp$mean[2] start.list[[14]]$mean.2.1 <- result$obj[[8]]$cmp$mean[1] start.list[[14]]$mean.2.2 <- result$obj[[8]]$cmp$mean[2] - start.list[[14]]$sqrt.sd <- sqrt( result$obj[[8]]$cmp$sd[1] ) ## Set sqrt for SD. + start.list[[14]]$sqrt.sd <- sqrt( result$obj[[8]]$cmp$sd[1] ) ## Take sqrt for SD. ## Retry ggd.nls.freq.all. result <- ggd.nls.freq.all( df, start.level = 1, start = start.list ) - result$cor result$cor[[14]] result$obj[[14]]$cmp plot.freq.and.d( result$obj[[14]], df$x, df$freq ) + + ## On the other hand, you can check the start values with 'not.use.nls = TRUE'. + start <- ggd.nls.freq.all( df, start.level = 1, not.use.nls = TRUE ) + start$cor + start$best.cor; start$best$kind.index + start$obj[[14]]$cmp + plot.freq.and.d( start$obj[[14]], df$x, df$freq ) + + ## You will find that 'start.level = 2' can generate reasonable start values basically. + start <- ggd.nls.freq.all( df, start.level = 2, not.use.nls = TRUE ) + start$cor + start$best.cor; start$best$kind.index ## 14 + start$obj[[14]]$cmp + plot.freq.and.d( start$obj[[14]], df$x, df$freq ) + + ## Using 'cor.method' argument, + ## you can evaluate the correlations with nonparametric methods. + start <- ggd.nls.freq.all( df, start.level = 2, not.use.nls = TRUE, + cor.method = "kendall" ) + start$cor + start$best.cor; start$best$kind.index ## 2 + start$obj[[2]]$cmp + plot.freq.and.d( start$obj[[2]], df$x, df$freq ) } \seealso{ \code{\link[ggd]{nls.freq}}, \code{\link[stats]{cor}}, diff --git a/man/ggd.start.template.Rd b/man/ggd.start.template.Rd index e72297e..358d5e8 100644 --- a/man/ggd.start.template.Rd +++ b/man/ggd.start.template.Rd @@ -4,63 +4,66 @@ \alias{ggd.start.template} \title{Template for start of nls} \usage{ -ggd.start.template(target) +ggd.start.template(kind) } \arguments{ -\item{target}{A variable that identifies the kind of distribution to which -the template applies. The length should be 1. -The type of the variable is valid for \code{\link[ggd]{GGD}} object, -the string of an element of \code{ggd:::kinds}, or its index number.} +\item{kind}{A character string or a numeric value or a \code{\link[ggd]{GGD}} object + which indicates the kind of distribution model for which the template will + be output. The length should be 1. + + The matching method of \code{kind} follows that of + \code{objs} argument of \code{\link[ggd]{ggd.kind.index}}. + If it matches to two or more distribution models, + this function returns only one template for the first matched model.} } \value{ A list containing components any of \item{mean}{ - The start value for mean values common to all normal distributions - of the components. 0 is preset.} + The start value for the mean value shared by all components. 0 is preset.} \item{mean.i}{ - The start value for the mean value of i-th normal distribution. + The start value for the mean value of the i-th component. 0 is preset.} \item{mean.i.j}{ - The start value for mean value of i,j-th normal distribution + The start value for the mean value of the i,j-th component in the 2x2 components. 0 is preset.} \item{sqrt.sd}{ - The sqrt of the start value for standard deviations common to - all normal distributions of the components. 1 is preset.} + The start value for the square root of the standard deviation shared + by all components. 1 is preset.} \item{sqrt.sd.i}{ - The sqrt of the start values for the standard deviation of - i-th normal distribution. 1 is preset.} + The start value for the square root of the standard deviation of + the i-th component. 1 is preset.} \item{sqrt.sd.i.j}{ - The sqrt of the start values for the standard deviation of - i,j-th normal distribution in the 2x2 components. 1 is preset.} + The start value for the square root of the standard deviation of + the i,j-th component in the 2x2 components. 1 is preset.} - If \code{target} represents unsupported distribution kind, \code{NULL} is returned. + If \code{kind} represents an unsupported distribution model, + \code{NULL} will be returned. } \description{ -Gets the template for start list for \code{\link[stats]{nls}} -when you want to provide your own \code{start} parameters for \code{\link[ggd]{nls.freq}} -or \code{\link[ggd]{ggd.nls.freq.all}}. -This function can output only one template list at once. -So if you want to get several templates for different distribution kinds, -call this function one by one for each distribution kind. +Gets a template list for \code{start} argument of \code{\link[ggd]{nls.freq}} +or for an element of \code{start} argument of \code{\link[ggd]{ggd.nls.freq.all}}. +This function can output only one template at a time. +So if you want to obtain two or more templates, +you should call this function one by one for each one. } \examples{ - ## preparing + ## Preparing: x <- seq( -2, 2, 0.2 ) freq <- c( 1517, 2292, 2513, 2763, 3724, 4046, 4713, 7947, 10997, 11824, 11133, 7868, 4692, 4103, 3698, 2740, 2549, 2284, 1499, 1147, 918 ) - ## set the start parameters + ## Set the start values. start <- ggd.start.template( 14 ) - start ## check the parameters for the start of ggd:::kinds[14] + start ## Check the parameters for the 'start' of ggd:::kinds[14]. start$mean.1.1 <- -0.671 start$mean.1.2 <- -0.198 start$mean.2.1 <- 0.293 start$mean.2.2 <- -0.198 - start$sqrt.sd <- sqrt( 0.640 ) ## sqrt.sd is the square root of the standard deviation. + start$sqrt.sd <- sqrt( 0.640 ) ## 'sqrt.sd' is the square root of the standard deviation. - ## try ggd.nls.freq + ## Run ggd.nls.freq. ggd.nls.freq( data.frame( x, freq ), start = start, kind = 14 )$obj } \seealso{ diff --git a/man/is.eq.mean.Rd b/man/is.eq.mean.Rd index a117c0a..26868f6 100644 --- a/man/is.eq.mean.Rd +++ b/man/is.eq.mean.Rd @@ -13,20 +13,19 @@ } \description{ Checks if the mean values of all normal distributions of components are equal. +The equality is determined by the '\code{==}' operator. } \examples{ a <- GGD$new() a$kind ## Normal Distribution a$is.eq.mean() ## TRUE - a$trace.q( - data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), - grad = "v2" ) - a$kind ## 2-Mean-Differed Sigma-Differed Vertical Gradational Distribution + a$set.cmp( data.frame( mean = c( 0, 1e+8 ), sd = rep( 1.5, 2 ) ) ) + a$kind ## Mean-Differed Sigma-Equaled Horizontal Gradational Distribution a$is.eq.mean() ## FALSE a <- GGD$new() - a$set.cmp( data.frame( mean = rep( 0, 3 ), sd = c( 1.2, 0.5, 1.3 ) ) ) - a$kind ## 3-Mean-Equaled Sigma-Differed Vertical Gradational Distribution + a$set.cmp( data.frame( mean = rep( 0.5, 2 ), sd = c( 1, 1 + 1e+8 ) ) ) + a$kind ## Mean-Equaled Sigma-Differed Horizontal Gradational Distribution a$is.eq.mean() ## TRUE } diff --git a/man/is.eq.sd.Rd b/man/is.eq.sd.Rd index e008b0c..6813ad1 100644 --- a/man/is.eq.sd.Rd +++ b/man/is.eq.sd.Rd @@ -17,24 +17,18 @@ } \description{ Checks if the standard deviations of all normal distributions of components are equal. +The equality is determined by the '\code{==}' operator. } \examples{ a <- GGD$new() a$kind ## Normal Distribution - a$is.eq.sd() ## TRUE - a$is.eq.sigma() ## TRUE (This method is just a synonym of is.eq.sd) + a$is.eq.sd(); a$is.eq.sigma() ## TRUE; TRUE (is.eq.sigma is just a synonym of is.eq.sd) - a$trace.q( - data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), - grad = "v2" ) - a$kind ## 2-Mean-Differed Sigma-Differed Vertical Gradational Distribution - a$is.eq.sd() ## FALSE - a$is.eq.sigma() ## FALSE + a$set.cmp( data.frame( mean = rep( 0.5, 2 ), sd = c( 1, 1 + 1e+8 ) ) ) + a$kind ## Mean-Equaled Sigma-Differed Horizontal Gradational Distribution + a$is.eq.sd(); a$is.eq.sigma() ## FALSE; FALSE - a$trace.q( - data.frame( x = c( -0.67, 0, 0.53 ), p = c( 0.25, 0.5, 0.70 ) ), - this.mix.type = 2, eq.sd = TRUE ) - plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) - a$is.eq.sd() ## TRUE - a$is.eq.sigma() ## TRUE + a$set.cmp( data.frame( mean = c( 0, 1e+8 ), sd = rep( 1.5, 2 ) ) ) + a$kind ## Mean-Differed Sigma-Equaled Horizontal Gradational Distribution + a$is.eq.sd(); a$is.eq.sigma() ## TRUE; TRUE } diff --git a/man/is.h.Rd b/man/is.h.Rd index 9f29a54..49fa26f 100644 --- a/man/is.h.Rd +++ b/man/is.h.Rd @@ -15,7 +15,7 @@ when the model is a normal distribution.} } \value{ -\code{TRUE} if the object shows a kind of horizontal gradational distribution, +\code{TRUE} if the object represents a kind of horizontal gradational distribution, otherwise \code{FALSE}. } \description{ @@ -32,9 +32,7 @@ Note, this function does not check \code{kind} and \code{kind.index} fields. a$set.cmp( data.frame( mean = c( 0, 1 ), sd = c( 1.1, 1.2 ) ), this.mix.type = 2 ) a$is.h() ## TRUE - a$trace.q( - data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), - grad = "v2" ) + a$set.cmp( grad = "v2" ) a$kind ## 2-Mean-Differed Sigma-Differed Vertical Gradational Distribution a$is.h() ## FALSE diff --git a/man/is.hv.Rd b/man/is.hv.Rd index 19899fd..5145ae2 100644 --- a/man/is.hv.Rd +++ b/man/is.hv.Rd @@ -17,7 +17,7 @@ and a 2-component vertical gradational distribution.} } \value{ -\code{TRUE} if the object shows a kind of horizontal-vertical gradation of +\code{TRUE} if the object represents a kind of horizontal-vertical gradation of 4 (2x2) normal distributions, otherwise \code{FALSE}. } \description{ diff --git a/man/is.normal.Rd b/man/is.normal.Rd index 12c57a1..e369d96 100644 --- a/man/is.normal.Rd +++ b/man/is.normal.Rd @@ -8,7 +8,7 @@ \S4method{is.normal}{GGD}() } \value{ -\code{TRUE} if the object shows a normal distribution, otherwise \code{FALSE}. +\code{TRUE} if the object represents a normal distribution, otherwise \code{FALSE}. } \description{ Referring \code{cmp} field, checks if the distribution is essentially a normal distribution. @@ -21,9 +21,7 @@ Note, this function does not check \code{kind} and \code{kind.index} fields. a$set.cmp( data.frame( mean = c( 0, 0 ), sd = c( 1.1, 1.1 ) ), this.mix.type = 2 ) a$is.normal() ## TRUE - a$trace.q( - data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), - grad = "v2" ) - a$kind; a$cmp + a$set.cmp( data.frame( mean = c( 0, 0 ), sd = c( 1.1, 0.9 ) ), grad = "v2" ) + a$kind ## 2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution a$is.normal() ## FALSE } diff --git a/man/is.symmetric.Rd b/man/is.symmetric.Rd index 0bfd309..0b2f8a0 100644 --- a/man/is.symmetric.Rd +++ b/man/is.symmetric.Rd @@ -16,22 +16,20 @@ Referring \code{mix.type} and \code{cmp} field, checks if the probability density function is symmetric about the mean. } \details{ -This function judges that the distribution model is symmetric if either: +This method judges that the distribution model is symmetric if either: \enumerate{ \item a normal distribution. - \item a mean of 2 normal distributions or a horizontal gradational distribution, - where the standard deviations of the two normal distributions of the components - are equal to each other. - \item a mean of 2 normal distributions or a vertical gradational distribution - of 2 normal distributions, where the mean values of the two normal distributions - of the components are equal to each other. - \item a vertical gradational distribution of 3 normal distributions, - where the mean of the mean values of the 2 tail-side components is equal to - the mean value of the top-side component, and the standard deviations of - the both tail-side components are equal to each other. - \item a horizontal-vertical gradational distribution, - where the two vertical gradational distributions of the components are - symmetric about the mean of the distribution. + \item a mean of 2 normal distributions or a horizontal gradational distribution + where the two components have the same standard deviation. + \item a mean of 2 normal distributions or a 2-component vertical gradational + distribution where the two components have the same mean value. + \item a 3-component vertical gradational distribution + where the both tail-side components have the same standard deviation, + and the mean value of the top-side component equals the mean of the mean values + of the both tail-side components. + \item a horizontal-vertical gradational distribution which has + two vertical gradational distributions in the components + which are symmetrical to each other about the mean of the distribution. } } \examples{ diff --git a/man/is.v2.Rd b/man/is.v2.Rd index 8ba44f2..4ef1ca9 100644 --- a/man/is.v2.Rd +++ b/man/is.v2.Rd @@ -15,7 +15,7 @@ is a normal distribution.} } \value{ -\code{TRUE} if the object shows a kind of vertical gradation of +\code{TRUE} if the object represents a kind of vertical gradation of 2 normal distributions, otherwise \code{FALSE}. } \description{ @@ -35,10 +35,7 @@ Note, this function does not check \code{kind} and \code{kind.index} fields. a$is.v2() ## TRUE a$is.v2( TRUE ) ## FALSE - a$trace.q( - data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), - grad = "v2" ) - a$kind; a$cmp + a$set.cmp( data.frame( mean = c( 0, 0 ), sd = c( 1.1, 0.9 ) ), grad = "v2" ) a$is.v2( TRUE ) ## TRUE a$set.cmp( data.frame( mean = c( 0, 0, 0, 0 ), diff --git a/man/is.v3.Rd b/man/is.v3.Rd index 03ea665..f7b712f 100644 --- a/man/is.v3.Rd +++ b/man/is.v3.Rd @@ -11,14 +11,14 @@ \item{strict}{If \code{TRUE}, this function returns \code{TRUE} only if the distribution is a vertical gradation with different left-tail-side and right-tail-side components. - Even when the \code{cmp} field has 3 rows with \code{mix.type = 3}, + Even when \code{cmp} field has 3 rows with \code{mix.type = 3}, if the 1st and the 3rd components are the same, it returns \code{FALSE}. If \code{FALSE}, this function also returns \code{TRUE} for a normal distribution or a vertical gradation of 2 normal distributions.} } \value{ -\code{TRUE} if the object shows a kind of vertical gradation of +\code{TRUE} if the object represents a kind of vertical gradation of 3 normal distributions, otherwise \code{FALSE}. } \description{ @@ -38,15 +38,12 @@ Note, this function does not check \code{kind} and \code{kind.index} fields. a$is.v3() ## TRUE a$is.v3( strict = TRUE ) ## FALSE - a$trace.q( - data.frame( x = c( -1.92, -0.20, 0.21, 1.98 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), - grad = "v3" ) - a$kind; a$cmp + a$set.cmp( data.frame( mean = c( 0, 0, 0 ), sd = c( 1.1, 0.9, 1.2 ) ), grad = "v3" ) a$is.v3() ## TRUE a$is.v3( strict = TRUE ) ## TRUE a$set.cmp( data.frame( mean = c( 0, 0, 0, 0 ), sd = c( 1.1, 0.8, 1.2, 0.8 ) ), this.mix.type = 4 ) a$mix.type ## 4 - a$is.v3() ## FALSE -- see "Note!" at Description + a$is.v3() ## FALSE -- see 'Note!' at Description } diff --git a/man/ms.norm.xp.Rd b/man/ms.norm.xp.Rd index ca2bc3b..a8f77e1 100644 --- a/man/ms.norm.xp.Rd +++ b/man/ms.norm.xp.Rd @@ -7,11 +7,11 @@ ms.norm.xp(x, p) } \arguments{ -\item{x}{The x-coordinates of the quantiles. It must be a vector with 2 numerics.} +\item{x}{The x-coordinates of the quantiles. It must be a vector with 2 elements.} \item{p}{The probabilities for the quantiles. In other word, the values of the cumulative distribution function of -a normal distribution for \code{x}. It must be also a vector with 2 numerics.} +a normal distribution for \code{x}. It must be also a vector with 2 elements.} } \value{ A list containing components @@ -22,11 +22,11 @@ A list containing components } \description{ Calculates the mean and standard deviation of the normal distribution -satisfying the given two quantiles. +which passes through the indicated two quantiles. This is the body of \code{ggd.trace.q(kind = "Normal Distribution")}. } \examples{ - ms.norm.xp( x = c( -1, 1 ), p = pnorm( c( -1, 1 ), 0, 1 ) ) # list( mean = 0, sd = 1 ) - ms.norm.xp( x = c( 0, 1 ), p = pnorm( c( 0, 1 ), 0, 2 ) ) # list( mean = 0, sd = 2 ) - ms.norm.xp( x = c( -2, 1 ), p = c( 0.3, 0.7 ) ) # list( mean = 0.5, sd = 2.86 ) (about) + ms.norm.xp( x = c( -1, 1 ), p = pnorm( c( -1, 1 ), 0, 1 ) ) ## list( mean = 0, sd = 1 ) + ms.norm.xp( x = c( 0, 1 ), p = pnorm( c( 0, 1 ), 0, 2 ) ) ## list( mean = 0, sd = 2 ) + ms.norm.xp( x = c( -2, 1 ), p = c( 0.3, 0.7 ) ) ## list( mean = -0.5, sd = about 2.86 ) } diff --git a/man/nls.freq.Rd b/man/nls.freq.Rd index a2ff948..3208b56 100644 --- a/man/nls.freq.Rd +++ b/man/nls.freq.Rd @@ -25,22 +25,21 @@ ggd.nls.freq(data, x = "x", freq = "freq", total = NULL, It must contain at least 2 numeric columns for \code{x} and \code{freq}. Column \bold{\code{x}} is for the x-coordinates. - Each value expected to be a numeric value which represents the cell of - the frequency distribution, the x-coordinate at the center of a cell - of the frequency distribution. + Each value is expected to be a numeric value which represents a cell of + the frequency distribution + as the x-coordinate at the center of the cell. The values must be arranged in ascending order, and not be duplicated. Column \bold{\code{freq}} is for the frequencies following \code{x}. - The values of frequencies must be positive. + The values of frequencies should not be negative. Both integers and real numbers are allowed for the values. Rows which contain \code{NA} or \code{NaN} for \code{x} or \code{freq} - are ignored. The number of rows should be large enough; - it is recommended that there are more than 8 valid rows. - At least, 3 valid rows must be contained. + are ignored. For fine approximation, the number of rows should be + large enough; it is recommended that there are more than 8 valid rows. Column names and column numbers for \code{x} and \code{freq} - are flexible. You can specify them with next two arguments.} + are flexible. You can indicate them with next two arguments.} \item{x}{The column name or column number for x-coordinates in \code{data}.} @@ -54,21 +53,18 @@ ggd.nls.freq(data, x = "x", freq = "freq", total = NULL, is used for it.} \item{kind}{A character string or a numeric value or a \code{\link[ggd]{GGD}} object - which indicates the kind of distribution model for approximating - the frequency distribution. - - The matching method of this argument follows that of elements of - the \code{objs} argument of the \code{\link[ggd]{ggd.kind.index}}. + which indicates the kind of distribution model to be generated. + The matching method of \code{kind} follows that of + \code{objs} argument of \code{\link[ggd]{ggd.kind.index}}. This argument gives the conditions of the value of \code{mix.type} field, - and of whether the mean values and standard deviations of the components - should be aligned to the same value. + and of whether the mean values or standard deviations of the components + should be aligned to the same value or not. - Indicating \code{mix.type} argument or - indicating other than \code{"default"} for \code{grad} argument - or \code{TRUE}/\code{FALSE} for \code{eq.mean} or \code{eq.sd} - can overwrite the conditions of this argument.} + Indicating \code{mix.type} or \code{grad} other than \code{"default"}, + or \code{eq.mean} and \code{eq.sd} other than \code{logical(0)} + can overwrite the condition of this argument.} \item{mix.type}{A numeric value to set into \code{mix.type} field of the \code{\link[ggd]{GGD}} object as an integer. @@ -79,12 +75,15 @@ ggd.nls.freq(data, x = "x", freq = "freq", total = NULL, \item 0: Normal distribution. \item 1: Mean of 2 normal distributions. \item 2: Horizontal gradation of 2 normal distributions. - \item 3: Vertical gradation of 2 or 3 normal distributions. - The 2-component model has priority. + \item 3: Vertical gradation of 2 (or 3) normal distributions. \item 4: Horizontal-Vertical gradation with 4 (2x2) normal distributions. } + Where \code{mix.type = 3} is indicated, + \code{ggd.nls.freq} function generates a 2-component model. + If you want to generate a 3-component model, use \code{grad = "v3"}. + If other than \code{"default"} for \code{grad} argument is indicated, this argument will be ignored.} @@ -107,8 +106,8 @@ ggd.nls.freq(data, x = "x", freq = "freq", total = NULL, are forced to be equal. If \code{FALSE} or \code{logical(0)}, - the mean values of the components can be different to each other, - and may be equal in very rare cases. + the mean values are not bound, + and mean-equaled components will be rarely constructed. \code{TRUE} and \code{FALSE} can overwrite the condition indicated by \code{kind} or \code{this.kind} argument.} @@ -117,62 +116,64 @@ ggd.nls.freq(data, x = "x", freq = "freq", total = NULL, the components are forced to be equal. If \code{FALSE} or \code{logical(0)}, - the standard deviation of the components can be different to - each other, and may be equal in very rare cases. + the standard deviations are not bound, + and sigma-equaled components will be rarely constructed. If both \code{eq.mean} and \code{eq.sd} are \code{TRUE}, - a normal distribution will be generated. + a normal distribution will be constructed. \code{TRUE} and \code{FALSE} can overwrite the condition indicated by \code{kind} or \code{this.kind} argument.} \item{start.level}{A numeric value of integer in from \code{0} to \code{3} or \code{100} - with default \code{100}; the level at which to guess the initial - \code{start} parameters of \code{\link[stats]{nls}}. + with default \code{100}; the level of initial guessing + for \code{start} argument of \code{\link[stats]{nls}}. - Details for each level are as: + The detail of each level is: \itemize{ \item \code{0}: The mean and the standard deviation of the frequency distribution - are used as initial values. + are used as the start values. \item \code{1}: - In addition to level \code{0}, if it is likely to be better guess, - it computes the mean values or standard deviations in ranges of - local x-coordinates where the effect of each of components is likely - to be heavy, and uses them as initial values. + In addition to level \code{0}, it computes the local mean values + and local standard deviations of the frequency distribution + in ranges of x-coordinates where the effect of each of components is + likely to be heavy, and uses them for guessing the start values + if they are likely to be better guesses. \item \code{2}: - In addition to level \code{0}, if it is likely to be better guess, - it uses the mean values or standard deviations of normal distributions - tracing two of quantiles which are generated with - the frequency distribution as initial values. + In addition to level \code{0}, at first it computes some quantiles + from the frequency distribution, then it finds normal distributions + tracing two of the quantiles, and uses the mean values and + standard deviations of them for guessing the start values + if they are likely to be better guesses. \item \code{3}: - It uses the mean values and standard deviations of the components - of a \code{\link[ggd]{GGD}} object tracing some (2, 3 or 5) quantiles - which are generated with the frequency distribution as initial values. - If tracing fails, level \code{2} is used instead. + It generates a \code{\link[ggd]{GGD}} object tracing + some (2, 3 or 5) quantiles computed from the frequency distribution, + and uses the mean values and standard deviations of the components + of the object as the start values. + If the generating fails, level \code{2} is used instead. \item \code{100}: - Try all of above levels and adopt the result with the highest + Try all of above levels and adopt the result of the highest \code{\link[stats]{cor}} value. } - The higher the level in the range of from \code{0} to \code{3}, - the more likely it is that the initial values will model - the frequency distribution in closer, - but the accuracy of the result may not along with the level. + As the level increases within the range of \code{0} to \code{3}, + the initial model will tend to be closer to the frequency distribution. + However, the accuracy of the result may not along with the level. It is possible that \code{\link[stats]{nls}} will succeed at level \code{1} and fail at level \code{3} for the same data.} -\item{start}{A list of \code{start} argument for \code{\link[stats]{nls}}. +\item{start}{A list for \code{start} argument of \code{\link[stats]{nls}}. You can provide your own \code{start} for \code{\link[stats]{nls}}, - the mean values - (names are like: \code{mean}, \code{mean.i} or \code{mean.i.j}) + the mean values (parameters are like: \code{mean}, \code{mean.i}, + or \code{mean.i.j}) and the \bold{square root} of the standard deviations - (names are like: \code{sqrt.sd}, \code{sqrt.sd.i} or \code{sqrt.sd.i.j}) - of the normal distributions of the components. + (parameters are like: \code{sqrt.sd}, \code{sqrt.sd.i}, + or \code{sqrt.sd.i.j}) of the normal distributions of the components. Depending on the kind of the distribution model, - the name of the parameters are different. + the names of the parameters are different. You can use \code{\link[ggd]{ggd.start.template}} to get the template of the list and know the names of the parameters. @@ -184,7 +185,7 @@ See \code{\link[stats]{nls.control}} for more information.} \item{not.use.nls}{A logical. If \code{TRUE}, this function does not use \code{\link[stats]{nls}} and - it outputs an object having the initial values in the \code{cmp} field + it outputs an object having the start values in \code{cmp} field as the result. If \code{FALSE}, this function uses \code{\link[stats]{nls}}. @@ -192,44 +193,48 @@ See \code{\link[stats]{nls.control}} for more information.} other than \code{100}. A warning will occur if \code{TRUE} when \code{start.level} is \code{100}. - You can use \code{not.use.nls = TRUE} to check the initial values - when an error has occurred at this function.} + You can use \code{not.use.nls = TRUE} to check + whether the start values are appropriate + when you have obtained an undesirable result from this function.} \item{cor.method}{The \code{method} argument for \code{\link[stats]{cor}}. -It represents the correlation coefficient method. -This argument is used only if \code{start.level = 100}. +It is a character string indicating which correlation coefficient +(or covariance) is to be computed in order to compare the results +between levels when \code{start.level = 100}. If \code{NULL}, it uses the default method of \code{\link[stats]{cor}}. +This argument works only if \code{start.level = 100}. See \code{\link[stats]{cor}} for more information.} \item{...}{Each argument for \code{\link[stats]{nls}} can be indicated. -See "Arguments" of \code{\link[stats]{nls}} for more information.} +See 'Arguments' of \code{\link[stats]{nls}} for more information.} -\item{this.kind}{A string or a numeric value or a \code{\link[ggd]{GGD}} object - which indicates the kind of distribution model for approximating - the frequency distribution. - - This argument will work as same as \code{kind} argument - of the generator function (signature '\code{NULL}'). +\item{this.kind}{A character string or a numeric value or a \code{\link[ggd]{GGD}} object + which indicates the kind of distribution model to be constructed. + It is equivalent to \code{kind} argument of \code{ggd.nls.freq}. When this method is called without \code{this.kind} argument or other conditions, it attempt to retain the value of - \code{mix.type} field as much as possible, but not the value of - \code{kind} field, i.e., the condition whether the mean value or - standard deviation of each component is aligned may not be retained. + \code{mix.type} field as much as possible except for \code{kind} field, + i.e., the condition whether the mean value and standard deviation of + each component are aligned to same values or not may not be retained. If you want to retain these conditions as well, indicate the object itself to \code{this.kind} argument like as \code{obj$nls.freq(data, this.kind = obj)}.} \item{this.mix.type}{A numeric value to set into \code{mix.type} field as an integer. - This argument will work as same as \code{mix.type} of - the generator function (signature '\code{NULL}'). + It is equivalent to \code{mix.type} argument of + \code{ggd.nls.freq}. + + Where \code{this.mix.type = 3} is indicated, + \code{nls.freq} method constructs 2- or 3- component model + according to the number of current components. If both of \code{this.kind} and \code{this.mix.type} are not given and \code{grad} argument is \code{"default"}, the current value of \code{mix.type} field will be retained, and number of components will also. - But furthermore, the object has been cleared, - the \code{mix.type} field will be set to \code{2}, the initial value.} + However, if the object has been cleared when this method is called, + \code{mix.type} field will be \code{2}, the start value.} } \value{ A list containing components (invisible for \code{GGD} method) @@ -237,29 +242,29 @@ A list containing components (invisible for \code{GGD} method) Generated \code{\link[ggd]{GGD}} object which most (at least locally) closely approximates the given frequency distribution. If \code{\link[stats]{nls}} has failed, it will be a cleared object. - For \code{\link[ggd]{GGD}} method, the \code{\link[ggd]{GGD}} object itself.} + For \code{\link[ggd]{GGD}} method, + the \code{\link[ggd]{GGD}} object itself.} \item{nls.out}{ The list of the output of \code{\link[stats]{nls}}. If \code{\link[stats]{nls}} has not been used, \code{NULL} will be set. - See "Value" of \code{\link[stats]{nls}} for more information.} + See 'Value' of \code{\link[stats]{nls}} for more information.} \item{start.level}{ - The initial guessing level which is used actually to gain \code{obj}. + The initial guessing level which is used actually to obtain \code{obj}. If \code{start.level = 100} is indicated, the level for the best result will be set. When \code{start.level = 3} is indicated and if initial guessing has failed, \code{2} will be set. - If \code{start} argument (not-\code{NULL}) is indicated, - \code{NA} will be set.} + If you indicate \code{start} argument a not-\code{NULL} list, + \code{start.level} will be \code{NA}.} \item{start}{ - The used \code{start} argument for the initial values - for \code{\link[stats]{nls}}.} + The used \code{start} argument of \code{\link[stats]{nls}}.} \item{start.obj}{ - A \code{\link[ggd]{GGD}} object corresponding to the initial values. + A \code{\link[ggd]{GGD}} object corresponding to the start values. That is, a \code{\link[ggd]{GGD}} object in which - values of the above \code{start} are set directly to the \code{cmp} field.} + values of the above \code{start} are set directly to \code{cmp} field.} \item{cor}{ The vector of the correlation coefficient of between the result for - each level of initial guessing in from \code{0} to \code{3} + each initial guessing level in the range of \code{0} to \code{3} and the frequency distribution. This component is given only if \code{start.level = 100}.} \item{errors}{ @@ -267,46 +272,53 @@ A list containing components (invisible for \code{GGD} method) This component is given only if \code{start.level = 100}. Each element in the list contains: \itemize{ - \item level: The level of initial guessing when the error has occurred. + \item level: The initial guessing level when the error has occurred. \item message: The error message. }} \item{warnings}{ A list of information about warnings occurred in \code{\link[stats]{nls}}. This component is given only if \code{start.level = 100}. - The composition of each element is as same as for \code{errors}.} + The composition of each element is same as \code{errors}.} - For \code{GGD} method: If an error occur, the object will be cleared in most cases. + For \code{GGD} method: If an error occurs, all fields of the object will be cleared + in most cases. } \description{ With the non-linear least squares (\code{\link[stats]{nls}}), constructs a \code{\link[ggd]{GGD}} object which (locally) most closely approximates -the given frequency distribution. "Locally" means that if the start value is modified, -more closely approximating model may be generated. +the given frequency distribution. +Then \code{ggd.nls.freq} function generates a \code{\link[ggd]{GGD}} object, +and \code{nls.freq} method sets the fields according to the result. +'Locally' means that if the start value is modified, more closely approximating model +may be constructed. The outliers of the frequency distribution will not be excluded in this function. If necessary, outliers should be excluded by preprocessing. } \details{ -\subsection{Why the standard deviations for "start" are square-rooted?}{ - You know a standard deviation must be a non-zero positive value. +\subsection{Why the standard deviations for 'start' are square-rooted?}{ + You know a standard deviation must be a positive value. But if you use standard deviations directly in the formula for \code{\link[stats]{nls}}, - they will sometimes drop into negative values while the Gauss-Newton algorithm is running + they sometimes drop into negative values while the Gauss-Newton algorithm is running and the algorithm will fail, even if it can reach convergence if done better. - So, to avoid such failures, we use square roots of standard deviations and + Therefore, to avoid such failures, we use square roots of standard deviations and take squares of them in the formula for \code{\link[stats]{nls}}. } } \examples{ - ## Preparing - df <- data.frame( x = seq( -2, 2, 0.2 ), - freq = c( 1517, 2292, 2513, 2763, 3724, 4046, 4713, - 7947, 10997, 11824, 11133, 7868, 4692, 4103, - 3698, 2740, 2549, 2284, 1499, 1147, 918 ), - x.2 = seq( -20, 20, 2 ), - freq.2 = c( .000974, .003797, .008523, .023142, .045017, .081743, .120990, - .142527, .124627, .106294, .078625, .059378, .045690, .042958, - .035760, .030938, .015675, .012516, .008139, .005114, .003582 ) ) - + ## Preparing: + df <- data.frame( + x = seq( -2, 2, 0.2 ), + freq = c( 1517, 2292, 2513, 2763, 3724, 4046, 4713, + 7947, 10997, 11824, 11133, 7868, 4692, 4103, + 3698, 2740, 2549, 2284, 1499, 1147, 918 ), + x.2 = seq( -20, 20, 2 ), + freq.2 = c( .000974, .003797, .008523, .023142, .045017, .081743, .120990, + .142527, .124627, .106294, .078625, .059378, .045690, .042958, + .035760, .030938, .015675, .012516, .008139, .005114, .003582 ) ) + + ## This function plots probability densities obtained from the frequency distribution + ## and the probability density function of a GGD object. plot.freq.and.d <- function( obj, x, freq ) { xlim <- c( min( x ), max( x ) ) @@ -317,28 +329,24 @@ If necessary, outliers should be excluded by preprocessing. type = "l", xlim = xlim, ylim = ylim ) } - ## Examples - ggd.nls.freq( df, grad = "normal" ) - a <- ggd.nls.freq( df, grad = "no" )$obj - plot.freq.and.d( a, df$x, df$freq ) - - ## "start.level" can be omitted (and you should omit to gain better results), - ## but is indicated here for processing speed. - a$nls.freq( df, this.mix.type = 1, start.level = 2 ) - a - plot.freq.and.d( a, df$x, df$freq ) + ## Examples: + result <- ggd.nls.freq( df, mix.type = 0 ) + result + plot.freq.and.d( result$obj, df$x, df$freq ) - a$nls.freq( df, start.level = 2, - this.kind = "2-Mean-Differed Sigma-Equaled Vertical Gradational Distribution" ) + ## You should not indicate 'start.level' to obtain good quality results, + ## but it is indicated here to make the process faster. + a <- GGD$new() + a$nls.freq( df, this.kind = "2.*Sigma-Equaled Vertical", start.level = 2 ) a plot.freq.and.d( a, df$x, df$freq ) - ## overwriting "Sigma-Differed" after "kind = a" - b <- ggd.nls.freq( df, kind = a, eq.sd = FALSE, start.level = 2 ) - b - plot.freq.and.d( b$obj, df$x, df$freq ) + ## Overwriting 'Sigma-Differed' with 'eq.sd = FALSE' after 'kind = a'. + b <- ggd.nls.freq( df, kind = a, eq.sd = FALSE, start.level = 2 )$obj + a$kind; b$kind ## "... Sigma-Equaled ..."; "... Sigma-Differed ..." + plot.freq.and.d( b, df$x, df$freq ) - ## You can set start parameters if you want. + ## You can specify start values with 'start' argument. start.list <- ggd.start.template( 14 ) start.list @@ -346,28 +354,74 @@ If necessary, outliers should be excluded by preprocessing. start.list$mean.1.2 <- -0.198 start.list$mean.2.1 <- 0.293 start.list$mean.2.2 <- -0.198 - start.list$sqrt.sd <- sqrt( 0.640 ) ## sqrt.sd is the sqrt of the standard deviation. + start.list$sqrt.sd <- sqrt( 0.640 ) ## 'sqrt.sd' is the sqrt of the standard deviation. - ## "start.level" is ignored when you have indicated start parameters. - a$nls.freq( df, this.kind = 14, start.level = 1, start = start.list ) - a + ## You can check the start values with 'not.use.nls = TRUE' before approximating. + a$nls.freq( df, this.kind = 14, start = start.list, not.use.nls = TRUE ) + a$cmp + plot.freq.and.d( a, df$x, df$freq ) + + ## When you indicate 'start' argument, 'start.level' argument is ignored. + result <- a$nls.freq( df, this.kind = 14, start.level = 1, start = start.list ) + result$start.level ## NA + result$start.obj$cmp ## Verify start values. + a$cmp ## results plot.freq.and.d( a, df$x, df$freq ) - ## When you use a GGD object consecutively, - ## the field values set to the object in the previous session are retained - ## (if no error has occurred). + ## When you call nls.freq method of a GGD object consecutively, + ## the conditions saved in the fields are retained (if no error has occurred). a$nls.freq( df, grad = "hv", eq.mean = TRUE, start.level = 2 ) - a + a$mix.type; a$is.eq.mean() ## 4; TRUE plot.freq.and.d( a, df$x, df$freq ) - a$nls.freq( df, eq.mean = FALSE, start.level = 2 ) ## grad = "hv" is retained. - a + a$nls.freq( df, eq.mean = FALSE, start.level = 2 ) ## 'grad = "hv"' is retained. + a$mix.type; a$is.eq.mean() ## 4; FALSE plot.freq.and.d( a, df$x, df$freq ) ## Using "x.2" for x and "freq.2" for freq. - a <- ggd.nls.freq( df, x = "x.2", freq = "freq.2", start.level = 2 )$obj - a ## default value of mix.type is 2 - plot.freq.and.d( a, df$x.2, df$freq.2 ) + b <- ggd.nls.freq( df, x = "x.2", freq = "freq.2", start.level = 2 )$obj + b + plot.freq.and.d( b, df$x.2, df$freq.2 ) + +\dontrun{ + ## Using the default 'start.level' (100) is the best way to obtain a good quality result, + ## but the process is slow to demonstrate as a running example. So, it is not run here. + ## + ## The following results written in comments are + ## obtained on a Windows 11 64-bit environment using ggd v1.0.3 package. + result <- a$nls.freq( df, grad = "v" ) + result$cor + ## level.0 level.1 level.2 level.3 + ## 0.9867103 0.9867102 0.9867103 0.9867102 + result$start.level + ## 2 + a$cmp + ## mean sd + ## n.1 -0.1841741 1.039255 + ## n.2 -0.1973208 0.648003 + + ## 'cor.method' argument is available for 'start.level = 100' + ## but the default value is recommended (see 'Details' at the manual of cor). + result <- a$nls.freq( df, cor.method = "kendall" ) + result$cor + ## level.0 level.1 level.2 level.3 + ## 0.9428571 0.9428571 0.9428571 0.9428571 ## All values were equal. + result$start.level + ## 0 + a$cmp + ## mean sd + ## n.1 -0.1841703 1.039255 + ## n.2 -0.1973202 0.648003 + + ## 'start.level = 3' does not always generate good start values. + ## This execution may cause an error in nls due to strange start values. + a$nls.freq( df, grad = "hv", start.level = 3 ) + ## If run, an error may occur as: 'nls has failed. Message: Error in nls...' + + ## To get a result even if an error occurs in nls, + ## you can indicate 'warnOnly = TRUE' in 'control' option. + a$nls.freq( df, grad = "hv", start.level = 3, control = list( warnOnly = TRUE ) ) + ## If run, a warning may occur (a singular gradient).} } \seealso{ \code{\link[stats]{nls}}, \code{\link[stats]{nls.control}}, diff --git a/man/nls.freq.level.100.Rd b/man/nls.freq.level.100.Rd index 4fcbc8e..49a6dee 100644 --- a/man/nls.freq.level.100.Rd +++ b/man/nls.freq.level.100.Rd @@ -19,7 +19,7 @@ nls.freq.level.100( } \arguments{ \item{data}{A data frame which represents the frequency distribution. -It must contain 2 numeric columns named \code{x} and \code{freq}.} +It must contain 2 numeric columns named \code{"x"} and \code{"freq"}.} \item{total}{Total value of the frequencies.} @@ -29,8 +29,7 @@ It must contain 2 numeric columns named \code{x} and \code{freq}.} the \code{\link[ggd]{GGD}} object as an integer. It is an integer from \code{0} to \code{4} or \code{NULL}.} -\item{grad}{A character string indicating the method of gradation. -See \code{\link[ggd]{nls.freq}} for more information.} +\item{grad}{A character string indicating the method of gradation.} \item{eq.mean}{A logical. If \code{TRUE}, all of the mean values of of the components are forced to be equal.} @@ -44,13 +43,13 @@ See \code{\link[stats]{nls.control}} for more information.} \item{cor.method}{The \code{method} argument for \code{\link[stats]{cor}}.} \item{...}{Each argument for \code{\link[stats]{nls}} can be indicated. -See "Arguments" of \code{\link[stats]{nls}} for more information.} +See 'Arguments' of \code{\link[stats]{nls}} for more information.} } \value{ A list conforming the return value of \code{\link[ggd]{nls.freq}}. } \description{ -Execute a loop of \code{\link[stats]{nls}} with changing the level of initial guessing. +Executes a loop of \code{\link[stats]{nls}} with changing initial guessing levels. This is the main process of \code{\link[ggd]{nls.freq}} with \code{start.level = 100}. } \seealso{ diff --git a/man/p.Rd b/man/p.Rd index 0cb1dcf..e30a12c 100644 --- a/man/p.Rd +++ b/man/p.Rd @@ -11,12 +11,13 @@ \item{x}{A vector of x-coordinates.} } \value{ -The probabilities of that x is less than or equal to given x-coordinates. +A vector of the probabilities of that a value of the random variable is less than + or equal to given x-coordinates. } \description{ Gets the probabilities of that a value of the random variable is less than or equal to the given x-coordinates. -This function works like \code{\link[stats]{pnorm}} for a normal distribution. +This method works like \code{\link[stats]{pnorm}} for a normal distribution. } \examples{ a <- GGD$new() diff --git a/man/q.Rd b/man/q.Rd index c5f35b9..520f489 100644 --- a/man/q.Rd +++ b/man/q.Rd @@ -13,13 +13,13 @@ \item{tol}{The tolerance level for the convergence criterion.} } \value{ -The x-coordinates at which the value of the cumulative distribution function - will be equal to the given probabilities. +A vector of the x-coordinates with the cumulative distribution function + is equal to the given probabilities in the tolerance level. } \description{ -Gets the x-coordinates at which the value of the cumulative distribution function will be -equal to the given probabilities. -This function works like \code{\link[stats]{qnorm}} for a normal distribution. +Gets the x-coordinates with the cumulative distribution function is equal to +the given probabilities (with a tolerance level). +This method works like \code{\link[stats]{qnorm}} for a normal distribution. } \examples{ a <- GGD$new() diff --git a/man/r.Rd b/man/r.Rd index ec5d8ee..d782172 100644 --- a/man/r.Rd +++ b/man/r.Rd @@ -19,7 +19,8 @@ A vector of random numbers. } \description{ Generates random numbers which follow the distribution model. -This function works like \code{\link[stats]{rnorm}} for a normal distribution. +This method works like \code{\link[stats]{rnorm}} for a normal distribution. +This method calls \code{\link[ggd]{q}} method internally. } \examples{ a <- GGD$new() diff --git a/man/read.csv.Rd b/man/read.csv.Rd index ad8d8b5..79102e6 100644 --- a/man/read.csv.Rd +++ b/man/read.csv.Rd @@ -11,21 +11,19 @@ ggd.read.csv(file) \S4method{read.csv}{GGD}(file) } \arguments{ -\item{file}{The name of the CSV file which the composition of - a \code{\link[ggd]{GGD}} object is to be read from. - The \code{file} can be a readable text-mode \link[base]{connection}. +\item{file}{The name of the CSV file. + The \code{file} can be a readable text-mode \link[base]{connection}. - The \code{file} must have a header consisting of - the value of \code{mix.type}, the character string of "mean" - and the character string of "sd". - The order of each column is not interchangeable. - The second and subsequent rows should be the name of the row - (such as \code{"nd.1"}, but not be cared) - and the mean value and standard deviation of the each components - of the \code{cmp} field. + The \code{file} should be a CSV file with 3 columns. + The columns are 1:row header, 2:mean value, and 3:standard deviation + of the component. The columns cannot be reordered. + The \code{file} must have a header row consisting of the value of + \code{mix.type}, the character string of \code{"mean"}, and \code{"sd"}. + The second and subsequent rows should have the row name (such as \code{"nd.1"}), + the mean value, and standard deviation of each component. - For more information about the properties of this argument, - see \code{file} argument of \link[utils]{read.table}.} + For more information about the properties of this argument, + see \code{file} argument of \link[utils]{read.table}.} } \value{ The generated \code{\link[ggd]{GGD}} object (invisible for \code{GGD} method). @@ -33,23 +31,23 @@ The generated \code{\link[ggd]{GGD}} object (invisible for \code{GGD} method). For \code{GGD} method: If failed to read, the object will be cleared. } \description{ -Reads a CSV file recorded the composition of a \code{\link[ggd]{GGD}} object -and generates a \code{\link[ggd]{GGD}} object. +Reads a CSV file recorded the composition of a \code{\link[ggd]{GGD}} object. +Then \code{ggd.read.csv} function generates a \code{\link[ggd]{GGD}} object, +and \code{read.csv} method sets the fields according to the composition. } \details{ \subsection{Reading empty data}{ - If the read file is one which is written with a cleared object, - \code{kind}/\code{kind.index} and \code{mix.type} fields of the generated object + If the file contains a cleared object (a file with only the header row), + the values of \code{kind}, \code{kind.index}, and \code{mix.type} fields will be \code{NA}, - and \code{median} and \code{mean} and other numeric fields will be \code{NaN}. + and then \code{median}, \code{mean}, and other numeric fields will be \code{NaN}. } \subsection{Illegal format file}{ - If the format of the read file was illegal and a \code{\link[ggd]{GGD}} object cannot + If the format of the file was illegal and a \code{\link[ggd]{GGD}} object cannot be constructed, an error occurs and the \code{\link[ggd]{GGD}} object is cleared. - If the \code{mix.type} value stored in a file does not match the values for \code{cmp}, - an error may occur, or it may happen to work. It is possible to create such a file - using \code{ggd:::}\code{\link[ggd]{cat.table}} function which is non-exported. + If \code{mix.type} value stored in the file does not match the values for \code{cmp}, + an error may occur, or it may happen to work. However, it is not recommended to create such a non-conforming file anyway. } } diff --git a/man/round.cmp.Rd b/man/round.cmp.Rd index 4ad5754..e4dc92f 100644 --- a/man/round.cmp.Rd +++ b/man/round.cmp.Rd @@ -27,15 +27,15 @@ standard deviations will not be rounded. See \code{\link[base]{round}} for more information.} } \value{ -The processed \code{\link[ggd]{GGD}} object itself. +The processed \code{\link[ggd]{GGD}} object itself (invisible). } \description{ -Rounds the values of all elements in the \code{cmp} field and adjusts other fields +Rounds the values of all elements in \code{cmp} field and adjusts other fields accordingly. \code{\link[base]{round}} and \code{\link[base]{signif}} functions can apply. -These functions does not change the number of rows in \code{cmp} field, +These functions do not change the number of rows in \code{cmp} field, no matter what results are obtained. -If an error occurs, these functions do not clear the object, but retains the values of +If an error occurs, these functions do not clear the object, but retain the values of all fields. } \examples{ diff --git a/man/sd.norm.mxp.Rd b/man/sd.norm.mxp.Rd index 25ed6d9..e5cb3b7 100644 --- a/man/sd.norm.mxp.Rd +++ b/man/sd.norm.mxp.Rd @@ -17,14 +17,14 @@ In other word, the value of the cumulative distribution function of a normal distribution for the \code{x}. The value must not be \code{0.5}.} } \value{ -The vector of the standard deviations. +A vector of the standard deviations. } \description{ -Calculates the standard deviations of the normal distribution -satisfying the given mean and one other quantile. +Calculates the standard deviation of the normal distribution +which has the indicated mean and passes through one other quantile. } \examples{ - sd.norm.mxp( 0, qnorm( 0.3, 0, 1 ), 0.3 ) # 1 - sd.norm.mxp( rep( 0, 5 ), 1:5, pnorm( 1:5, 0, 1 ) ) # 1 1 1 1 1 - sd.norm.mxp( c( -0.1, 0, 0.3 ), c( -0.3, -0.1, 0.4 ), c( 0.38, 0.47, 0.53 ) ) # [2] == [3] + sd.norm.mxp( 0, qnorm( 0.3, 0, 1 ), 0.3 ) ## 1 + sd.norm.mxp( rep( 0, 5 ), 1:5, pnorm( 1:5, 0, 1 ) ) ## 1 1 1 1 1 + sd.norm.mxp( c( -0.1, 0, 0.3 ), c( -0.3, -0.1, 0.4 ), c( 0.38, 0.47, 0.53 ) ) ## [2] == [3] } diff --git a/man/set.cmp.Rd b/man/set.cmp.Rd index b0778e9..a0c9170 100644 --- a/man/set.cmp.Rd +++ b/man/set.cmp.Rd @@ -14,9 +14,9 @@ ggd.set.cmp(cmp, kind = NULL, mix.type = NULL, grad = c("default", "normal", "h", "v", "v2", "v3", "hv")) } \arguments{ -\item{cmp}{A data frame for setting into the \code{cmp} field. +\item{cmp}{A data frame for \code{cmp} field. - It must have just 2 columns named "\code{mean}" and "\code{sd}", + It must have just 2 columns named \code{"mean"} and \code{"sd"}, and its rows must be less than or equals to 4. Row names are not required. @@ -30,10 +30,10 @@ ggd.set.cmp(cmp, kind = NULL, mix.type = NULL, but indicating \code{NULL} or having no columns is not allowed.} \item{kind}{A character string or a numeric value or a \code{\link[ggd]{GGD}} object - which indicates the kind of the distribution model to create. + which indicates the kind of distribution model to be generated. - The matching method of this argument follows that of elements of - the \code{objs} argument of the \code{\link[ggd]{ggd.kind.index}}. + The matching method of \code{kind} follows that of + \code{objs} argument of \code{\link[ggd]{ggd.kind.index}}. \code{NA} is allowed when \code{cmp} has no rows. If \code{mix.type} argument or other than \code{"default"} for @@ -42,10 +42,10 @@ ggd.set.cmp(cmp, kind = NULL, mix.type = NULL, \item{mix.type}{A numeric value represents how to mix the normal distributions. The type of the distribution model and the number of rows in \code{cmp} - will be represented with \code{mix.type} value as follows: + follow \code{mix.type} as: \itemize{ \item \code{0} : Normal distribution. \code{cmp} has only 1 row. - \item \code{1} : Mean of 2 normal distributions (not a GGD). + \item \code{1} : Mean of 2 normal distributions. \code{cmp} has 2 rows. \item \code{2} : Horizontal gradational distribution. \code{cmp} has 2 rows. @@ -56,13 +56,13 @@ ggd.set.cmp(cmp, kind = NULL, mix.type = NULL, } If the number of rows in \code{cmp} argument is different from - the number shown above, the \code{cmp} field will be + the number shown above, \code{cmp} field will be redundant/simplified to have the number of rows as above, if possible. If not possible, an error will occur. You can indicate \code{mix.type = NA} only if \code{cmp} has no rows. - If other than \code{"default"} for \code{grad} argument is indicated, + If \code{grad} argument other than \code{"default"} is indicated, this argument will be ignored.} \item{grad}{A character string indicating the method of gradation. @@ -73,60 +73,60 @@ ggd.set.cmp(cmp, kind = NULL, mix.type = NULL, Numberless \code{"v"} is an alias for \code{"v2"}. \code{"normal"} is for a normal distribution, - then also, \code{'grad = "no"'} can be read as "no gradation". + then also, \code{'grad = "no"'} can be read as 'no gradation'. \code{"default"} is, if \code{kind} or \code{mix.type} argument is given, follows it, otherwise it depends on the number of columns - in the \code{cmp} argument. If the number of columns in cmp is \code{2}, + in \code{cmp} argument. If the number of columns in cmp is \code{2}, the current \code{mix.type} is retained or horizontal (default) is used.} -\item{this.cmp}{A data frame for setting into the \code{cmp} field. -It is equivalent to \code{cmp} argument for \code{ggd.set.cmp}.} +\item{this.cmp}{A data frame for setting into \code{cmp} field. +It is equivalent to \code{cmp} argument of \code{ggd.set.cmp}.} \item{this.kind}{A string or a numeric value or a \code{\link[ggd]{GGD}} object -which indicates the kind of the distribution model. -It is equivalent to \code{kind} argument for \code{ggd.set.cmp}.} +which indicates the kind of distribution model to be constructed. +It is equivalent to \code{kind} argument of \code{ggd.set.cmp}.} \item{this.mix.type}{A numeric value represents how to mix the normal distributions. -It is equivalent to \code{mix.type} argument for \code{ggd.set.cmp}.} +It is equivalent to \code{mix.type} argument of \code{ggd.set.cmp}.} } \value{ The \code{\link[ggd]{GGD}} object itself (invisible for \code{GGD} method). - For \code{GGD} method: If an error occur, each value of field will not be changed. + For \code{GGD} method: If an error occurs, each value of field will not be changed. } \description{ -Sets the normal distributions of the components to the \code{cmp} field. -All fields of the \code{\link[ggd]{GGD}} object will be set as appropriate according to -given components and other arguments, respectively. -You should never set any values into the \code{cmp} field directly without using this method. +Generates a \code{\link[ggd]{GGD}} object according to indicated values of \code{cmp} field +(\code{ggd.set.cmp}), or sets the values in \code{cmp} field and all of other fields +accordingly (\code{set.cmp}). +Whenever you want to set values in \code{cmp} field, it is strongly recommended to use +this method. } \details{ -\subsection{About "kind" and "mix.type"}{ - In this function, \code{[this.]kind} argument is, unlike \code{\link[ggd]{trace.q}} - and \code{\link[ggd]{nls.freq}} methods, used only to determine how to mix - the normal distributions of the components. - That is, \code{[this.]kind} argument is used only to determine the new value of - \code{mix.type} field, and has no effect on the unification of the mean values and - the standard deviations of the components. - - So, the new value of \code{kind} field of the object may not be matched with - the indicated value of \code{[this.]kind} argument. +\subsection{About 'kind' and 'mix.type'}{ + In this function, + unlike \code{\link[ggd]{trace.q}} and \code{\link[ggd]{nls.freq}} methods, + \code{[this.]kind} argument is only used to determine \code{mix.type} value, + which represents how to mix the normal distributions of the components. + That is, \code{[this.]kind} argument has no effect to align the mean values or + standard deviations of the components to be equal. + + So, a regular expression indicated as \code{[this.]kind} argument may not match + the new value of \code{[this.]kind} field. For example, if you indicate \code{[this.]kind = "Mean-Eq.*Horizontal"} and \code{[this.]cmp = data.frame(mean = c(0, 1), sd = c(0.8, 1.2))}, the new \code{kind} field will be \code{"Mean-Differed Sigma-Differed Horizontal Gradational Distribution"}, - which is not matched with \code{"Mean-Eq.*Horizontal"}. + which is not matched with indicated regular expression. + In such a case, a warning will occur. - In such a case, i.e. if indicated \code{[this.]kind} does not match - to the new value of \code{kind} field, a warning will occur. - But when a \code{\link[ggd]{GGD}} object is indicated for \code{[this.]kind}, - no warning will occur if the unification of the mean values and standard deviations of - the components are different between the indicated object and the result. - Indicated object is regarded as just for specifying new \code{mix.type}. + On the other hand, when a \code{\link[ggd]{GGD}} object is + indicated as \code{[this.]kind}, no warning will occur if the new \code{kind} field + is different from that of the indicated object. + Indicated object is regarded as just for specifying \code{mix.type} value. - It is not recommended but if you indicate both of - \code{[this.]kind} and \code{[this.]mix.type} at once with not-\code{NULL} values, + It is not recommended but if you indicate not-\code{NULL} values for both of + \code{[this.]kind} and \code{[this.]mix.type} at once, \code{[this.]kind} will be ignored. If both \code{[this.]kind} and \code{[this.]mix.type} arguments are \code{NULL} @@ -147,75 +147,89 @@ You should never set any values into the \code{cmp} field directly without using \examples{ ## Normal Distribution a <- ggd.set.cmp( data.frame( mean = 0, sd = 1.5 ) ) - a$mix.type; a$cmp + a$kind; a$mix.type; a$cmp plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) - ## "normal" for "grad" argument is allowed, though, it does little work in this function. + ## Indicating "normal" for 'grad' argument is allowed. However, in this function, + ## it works only to assert that 'cmp' represents a normal distribution. a <- ggd.set.cmp( data.frame( mean = 1, sd = 2 ), grad = "normal" ) - a$mix.type; a$cmp + a$kind; a$mix.type; a$cmp - ## Where the number of the cmp field rows is 2, - ## it is recommended to indicate "grad" or "mix.type" or "kind" to avoid confusing. + ## Where the number of rows in the 'cmp' argument is 2, + ## it is recommended to indicate 'grad' or 'mix.type' or 'kind' to avoid confusing. + + ## Mean of 2 normal distributions (mix.type = 1) + ## is not a gradational Gaussian distribution (GDD), + ## but a kind of Gaussian mixture model (GMM). rm( a ) a <- ggd.set.cmp( data.frame( mean = c( 0, 0 ), sd = c( 1.2, 0.8 ) ), - kind = "Mean of Mean-Equaled Sigma-Differed 2 Normal Distributions" ) - a$mix.type; a$cmp + kind = "Mean of.*2 Normal Distributions" ) + a$kind; a$mix.type; a$cmp plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) ## Changing to mix.type = 2 : Horizontal Gradational Distribution - a$set.cmp( a$cmp, this.mix.type = 2 ) - a$mix.type; a$cmp + ## while retaining 'cmp' field. + a$set.cmp( this.mix.type = 2 ) + a$kind; a$mix.type; a$cmp ## You can also write as: - a$set.cmp( a$cmp, grad = "h" ) - a$mix.type; a$cmp + a$set.cmp( grad = "h" ) + a$kind; a$mix.type; a$cmp plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) - ## kind.index = 9 : 2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution - a$set.cmp( a$cmp, this.kind = 9 ) - a$mix.type; a$cmp + ## kind = 9 : '2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution' + ## + ## You can also write as 'this.kind = "2.*Vertical"' or 'this.mix.type = 3' or 'grad = "v2"' + ## instead of 'this.kind = 9'. + a$set.cmp( this.kind = 9 ) + a$kind; a$mix.type; a$cmp plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) - ## 3-Mean-Differed Sigma-Differed Vertical Gradational Distribution + ## You can generate a same kind object with indicating a GGD object for 'kind' argument. + b <- ggd.set.cmp( data.frame( mean = c( -1, -1 ), sd = c( 1.2, 0.4 ) ), kind = a ) + b$kind; b$mix.type; b$cmp + plot( seq( -3, 3, 0.01 ), b$d( seq( -3, 3, 0.01 ) ), type = "l" ) + + ## Indicating 3 components generates a vertical gradation normally. + a$clear() a$set.cmp( data.frame( mean = c( -0.5, 0, 0.5 ), sd = c( 1.2, 0.8, 1.2 ) ) ) - a$mix.type; a$cmp + a$kind; a$mix.type; a$cmp plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) - ## Mean-Equaled Sigma-Differed Horizontal-Vertical Gradational Distribution + ## Indicating 4 components generates a horizontal-vertical gradation normally. a$set.cmp( data.frame( mean = c( 0, 0, 0, 0 ), sd = c( 0.7, 0.5, 2.0, 1.5 ) ) ) - a$mix.type; a$cmp + a$kind; a$mix.type; a$cmp plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) - ## If "cmp" field can be simplified, "mix.type" field may be set to lower type. + ## If 'cmp' field can be simplified, the number of components is automatically reduced, + ## and 'mix.type' field follows the reduction. a$set.cmp( data.frame( mean = c( 0, 0, 0, 0 ), sd = c( 1, 0.7, 1, 0.7 ) ) ) + a$kind ## '2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution' a$mix.type ## 3 (not 4) a$cmp ## with 2 rows - ## If you want not to simplify "mix.type" and "cmp" fields, - ## indicate "mix.type" / "this.mix.type" or one of other arguments for the condition. - + ## If you want not to simplify 'cmp' field, + ## indicate '[this.]kind' or '[this.]mix.type' or 'grad' argument for the condition. a$set.cmp( data.frame( mean = c( 0, 0, 0, 0 ), sd = c( 1, 0.7, 1, 0.7 ) ), this.mix.type = 4 ) + a$kind ## '2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution' a$mix.type ## 4 a$cmp ## with 4 rows ## You can also write as: a$set.cmp( data.frame( mean = c( 0, 0, 0, 0 ), sd = c( 1, 0.7, 1, 0.7 ) ), grad = "hv" ) - a$mix.type; a$cmp + a$kind; a$mix.type; a$cmp - ## The "kind" / "this.kind" argument can also indicate - ## how to mix the normal distributions of the components. + ## You can also use '[this.]kind' argument to avoid simplifying. + ## However, if the indicated regular expression for '[this.]kind' argument does not match + ## the resulting 'kind' field, a warning will occur. + ## For avoiding confusing, using '[this.]mix.type' or 'grad' argument is recommended. ## - ## However, if the components indicated by "cmp" or "this.cmp" are inconsistent - ## with the value of "kind" / "this.kind" argument, - ## the "kind" and "kind.index" fields will be set to different values with a warning. - ## For avoiding confusing, you should use "mix.type" / "this.mix.type" or "grad" instead. - - ## This sample will work with a warning. + ## This sample will work with a warning; + ## because 'this.kind' argument does not match the resulting 'kind' field. a$set.cmp( this.cmp = data.frame( mean = c( 0, 0, 0, 0 ), sd = c( 1, 0.7, 1, 0.7 ) ), - this.kind = "Mean-Equaled Sigma-Differed Horizontal-Vertical" ) - a$mix.type ## 4 - a$kind ## "2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution" + this.kind = "Horizontal-Vertical" ) + a$kind; a$mix.type; a$cmp } diff --git a/man/sqnorm.Rd b/man/sqnorm.Rd index 8964b98..75a6d6d 100644 --- a/man/sqnorm.Rd +++ b/man/sqnorm.Rd @@ -7,20 +7,20 @@ sqnorm(p) } \arguments{ -\item{p}{A vector of probabilities.} +\item{p}{A vector of the probabilities of the quantiles.} } \value{ -A vector of sigma-unit distances from the mean to the quantiles for - the probabilities. +A vector of sigma-unit distances + from the mean to the x-coordinates of the quantiles. } \description{ -Calculates how many sigmas are the distances from the mean of a normal distribution -to the values of the quantile function for the given probabilities. -The mean and standard deviation are not need for this function, because sigma-unit distances -do not depend on them. +Calculates how many sigmas are the distance from the mean of a normal distribution +to the x-coordinate of the quantile which has the indicated probability. +The mean and standard deviation are not needed for this function +because the sigma-unit distance does not depend on them. } \examples{ - sqnorm( 0.5 ) # 0 - sqnorm( pnorm( -2, 0, 1 ) ) # -2 - sqnorm( seq( 0, 1, 0.1 ) ) # increces from -Inf to Inf + sqnorm( 0.5 ) ## 0 + sqnorm( pnorm( -2, 0, 1 ) ) ## -2 + sqnorm( seq( 0, 1, 0.1 ) ) ## increases from -Inf to Inf } diff --git a/man/tex.Rd b/man/tex.Rd index bf907fd..b9bb57e 100644 --- a/man/tex.Rd +++ b/man/tex.Rd @@ -22,70 +22,54 @@ frac.env = c("array", "aligned", "gathered", "default")) } \arguments{ -\item{con}{A \code{\link[base]{connection}} object or a character to indicate -the output destination. -See "Details" at \code{\link[base]{writeLines}} +\item{con}{A \code{\link[base]{connection}} object or a character string +to indicate the output destination. +See 'Details' at \code{\link[base]{writeLines}} for more information.} -\item{sep}{A string to be written to the connection after each line of text. -See "Details" at \code{\link[base]{writeLines}} +\item{sep}{A character string to be written to the connection after each line +of text. See 'Details' at \code{\link[base]{writeLines}} for more information.} -\item{comma}{A logical. If \code{TRUE}, this method writes "," as a separator -between each expression and "." at the end of output. -If \code{FALSE}, "," for the separator of expressions -and the final "." are not written.} +\item{comma}{A logical. If \code{TRUE}, this method writes a ',' (comma) +as a separator between each expression and a '.' (period) +at the end of the output. +If \code{FALSE}, those ',' and '.' will not be written.} -\item{format.num}{A function to format each number of value of a parameter; -mean value and standard deviation. -It should be a function with one argument for the number +\item{format.num}{A function to format each numeric value of mean values and +standard deviations. +It should be a function with one argument for the value to be displayed and returning a character string.} -\item{frac.env}{The TeX environment for formatting fractions with different heights +\item{frac.env}{The TeX environment to format fractions with different heights of numerator and denominator. -If \code{"default"}, such fractions will be formatted as default of TeX -(usually not so beautiful). Which environment is the most beautiful -form will depend on the TeX execution environment.} +If \code{"default"}, such fractions will be formatted +in the default style of TeX, but their appearance is usually poor. +The environment which produces the most beautiful form +will depend on the TeX execution environment.} } \value{ An invisible \code{NULL}. } \description{ -Outputs the TeX-formatted texts of the formulas for the probability density function +Outputs the TeX-formatted texts of the formulas of the probability density function \eqn{g(x)} and the cumulative distribution function \eqn{\Psi(x)} -with \code{\link[base]{writeLines}}. +using \code{\link[base]{writeLines}}. } \details{ \subsection{Composition of outputs}{ - \code{tex} outputs the formulas of both probability density function + \code{tex} method outputs the formulas of both probability density function and cumulative distribution function. - Where \code{mix.type} field is from \code{0} to \code{3}, - this function outputs 3 parts divided with one empty line as: - \itemize{ - \item Formulas of the probability density function \eqn{g(x)} - and the cumulative distribution function \eqn{\Psi(x)} of the model. - \item Formulas of the probability density function \eqn{f_i(x)} - and the cumulative distribution function \eqn{\Phi_i(x)} of the components. - \item Values of parameters of the mean values \eqn{\mu_i} and - the standard deviations \eqn{\sigma_i} of the components. - } + \code{tex.d} method outputs the formulas of probability density function only. - Where \code{mix.type = 4}, - the formulas of \eqn{g(x)} and \eqn{\Psi(x)} are divided into 2 parts in addition, - and subscripts for \eqn{f(x)}, \eqn{\Phi(x)} and parameters are 2 like \eqn{f_{i,j}(x)}. - - \code{tex.d} outputs the formulas of probability density function only. - - \code{tex.p} outputs the formulas of cumulative distribution function only. + \code{tex.p} method outputs the formulas of cumulative distribution function only. In these methods, the formulas are output according to \code{mix.type} and the number of components in \code{cmp} field, not \code{kind} or \code{kind.index}. That is, for example, if the \code{kind} is \code{"Normal Distribution"} and \code{mix.type = 2}, \code{tex} outputs formulas of a horizontal gradational distribution. - In such a case, if you want to display a normal distribution formula, - you should simplify \code{mix.type} with \code{\link[ggd]{adjust.cmp}} in advance. If \code{cmp} field has no rows, nothing is output. } @@ -93,17 +77,17 @@ with \code{\link[base]{writeLines}}. \subsection{Equaled mean values or standard deviations}{ For clarity, when all mean values or standard deviations of components are equal (i.e., when \code{\link[ggd]{is.eq.mean}} or \code{\link[ggd]{is.eq.sd}} method - returns \code{TRUE}), they are displayed with "\eqn{=}" to the 1st component parameter, - like as "\eqn{\sigma_2 = \sigma_1}". + returns \code{TRUE}), they are displayed with '\eqn{=}' to the 1st parameter, + like as '\eqn{\sigma_2 = \sigma_1}'. If only the values of some parameters are equal (e.g., only \eqn{\sigma_2} and \eqn{\sigma_3} are equal and \eqn{\sigma_1} is different), - they are not displayed as "\eqn{\sigma_3 = \sigma_2}", but displayed with values - to avoid misreading the subscripts. + each value is displayed as '\eqn{\sigma_2 = x, \sigma_3 = x}' + instead of '\eqn{\sigma_3 = \sigma_2}' to avoid misreading. Note that if the difference between the values of parameters is smaller than - displayable number of decimal places, "\eqn{\sigma_2 = \sigma_1}" may not be displayed, - but the same number may be displayed for each. + displayable number of decimal places, '\eqn{\sigma_2 = \sigma_1}' will not be displayed, + but the same number will be displayed for each. } } \examples{ diff --git a/man/trace.q.Rd b/man/trace.q.Rd index 7f9f9b9..cbb7847 100644 --- a/man/trace.q.Rd +++ b/man/trace.q.Rd @@ -24,9 +24,8 @@ ggd.trace.q(quantiles, x = "x", p = "p", and column \bold{\code{p}} is for the probabilities of the quantiles. Rows which contain \code{NA} or \code{NaN} are ignored. - The value of each row must not duplicated - (except for \code{NA} or \code{NaN}), - and must be valid as a set of quantiles. + The set of complete cases must be valid as a set of quantiles + and each row of them must not be duplicated. You do not have to sort the order of quantiles. The number of valid rows must be in range of from 2 to 8. @@ -34,27 +33,25 @@ ggd.trace.q(quantiles, x = "x", p = "p", \code{data.frame(x = c(0, -2, 2.3), p = c(0.5, 0.25, 0.75))}. Column names and column numbers for \code{x} and \code{p} are flexible. - You can specify them with next two arguments.} + You can indicate them with next two arguments.} \item{x}{The column name or column number for x-coordinates in \code{quantiles}.} \item{p}{The column name or column number for probabilities in \code{quantiles}.} \item{kind}{A character string or a numeric value or a \code{\link[ggd]{GGD}} object - which indicates the kind of the distribution model. - - The matching method of this argument follows that of elements of - the \code{objs} argument of the \code{\link[ggd]{ggd.kind.index}}. + which indicates the kind of distribution model to be generated. + The matching method of \code{kind} follows that of + \code{objs} argument of \code{\link[ggd]{ggd.kind.index}}. This argument gives the conditions of the value of \code{mix.type} field, - and of whether the mean values and standard deviations of the components + and of whether the mean values or standard deviations of the components should be aligned to the same value. - Indicating \code{mix.type} argument or - indicating other than \code{"default"} for \code{grad} argument - or \code{TRUE}/\code{FALSE} for \code{eq.mean} or \code{eq.sd} - can overwrite the conditions of this argument.} + Indicating \code{mix.type} or \code{grad} other than \code{"default"}, + or \code{eq.mean} and \code{eq.sd} other than \code{logical(0)} + can overwrite the condition of this argument.} \item{mix.type}{A numeric value to set into \code{mix.type} field as an integer. It should be an integer from \code{0} to \code{4} or \code{NULL}. @@ -62,19 +59,20 @@ ggd.trace.q(quantiles, x = "x", p = "p", Each value represents the following type of distribution: \itemize{ \item \code{0} : Normal distribution. - \item \code{1} : Mean of 2 normal distributions (not a GGD). + \item \code{1} : Mean of 2 normal distributions. \item \code{2} : Horizontal gradation of 2 normal distributions. \item \code{3} : Vertical gradation of 2 or 3 normal distributions. The 2-component model has priority. \item \code{4} : Horizontal-Vertical gradation with 4 (2x2) normal distributions. } - If \code{NULL} (and if \code{kind} and \code{grad = "default"}), + If \code{NULL} + (and \code{kind} is also \code{NULL}, and \code{grad = "default"}), it tries to trace the quantiles with changing - the \code{mix.type} according to the priority sequence: - 2 > 4 > 3 (2 components) > 3 (3 components) > 1 > 0. + \code{mix.type} according to the priority sequence: + 2 > 4 > 3 (2 components > 3 components) > 1 > 0. - If other than \code{"defaule"} for \code{grad} argument is indicated, + If \code{grad} argument other than \code{"default"} is indicated, this argument will be ignored.} \item{grad}{A character string indicating the method of gradation. @@ -88,102 +86,105 @@ ggd.trace.q(quantiles, x = "x", p = "p", \code{"default"} is for depending on other arguments. If other than \code{"default"} is indicated, - this function constructs a distribution model - according to this argument with ignoring \code{[this.]mix.type} argument - and overwriting the type indicated by \code{[this.]kind} argument.} + this function ignores \code{[this.]mix.type} argument + and overwrites the condition indicated by \code{[this.]kind} argument.} -\item{eq.mean}{A logical. It works when \code{mix.type} is not 0. +\item{eq.mean}{A logical. It works when \code{mix.type} is other than \code{0}. If \code{TRUE}, it forces all of the mean values of the components to be equal. This condition reduces the degrees of freedom, so allowed number of quantiles will be restricted. - See "Details" for more information. + See 'Details' for more information. - If \code{FALSE}, it constructs mean-differed components. - In this case, mean-equaled components are rarely constructed. + If \code{FALSE}, the mean values are not bound, + and mean-equaled components will be rarely constructed. If \code{logical(0)} (the default), - Normally, as \code{FALSE}, it constructs mean-differed components. - But if that fails, it tries to construct mean-equaled components - as \code{TRUE} (especially, when the median is specified as a quantile - to trace with a vertical gradational distribution). + Normally, the mean values are not bound same as \code{FALSE}. + But if it has failed to trace without binding, + it tries to trace with binding mean values as \code{TRUE}. + In some cases, reducing degrees of freedom helps to reach convergence. \code{TRUE} and \code{FALSE} can overwrite the condition indicated by - \code{kind} or \code{this.kind} argument.} + \code{[this.]kind} argument.} -\item{eq.sd}{A logical. It works when \code{mix.type} is not 0. +\item{eq.sd}{A logical. It works when \code{mix.type} is other than \code{0}. If \code{TRUE}, it forces all of the standard deviations of the components to be equal. This condition reduces the degrees of freedom, so allowed number of quantiles will be restricted. - See "Details" for more information. + See 'Details' for more information. If \code{FALSE} or \code{logical(0)}, - it constructs sigma-differed components. - In this case, sigma-equaled components are rarely constructed. + the standard deviations are not bound, + and sigma-equaled components will be rarely constructed. \code{TRUE} and \code{FALSE} can overwrite the condition indicated by - \code{kind} or \code{this.kind} argument.} + \code{[this.]kind} argument.} \item{control}{A list of \code{control} option for \code{\link[nleqslv]{nleqslv}}. See the "Control options" at \code{\link[nleqslv]{nleqslv}} for more information. - By default, this list is empty, but if there is a high probability - of a "Jacobian is singular" error due to the condition of the quantiles, + By default, this list is empty normally. + But if the convergence appears to be difficult due to + an insufficient number of quantiles compared to the degrees of freedom, \code{allowSingular = TRUE} is set implicitly. - However, if \code{allowSingular} is given to this argument, - the given option takes priority.} - -\item{this.kind}{A string or a numeric value or a \code{\link[ggd]{GGD}} object - which indicates the kind of distribution model to construct. - - This argument will work as same as \code{kind} argument - of the generator function (signature '\code{NULL}'). - - If this method is called without \code{this.kind} argument, - \code{grad}, or other conditions, it attempt to retain the value of - \code{mix.type} field as much as possible, but not the value of - \code{kind} field, i.e., the condition whether the mean value or - standard deviation of each component is aligned may not be retained. - If you want to retain the conditions as well, + If \code{allowSingular} is given to this argument, + the given value takes priority.} + +\item{this.kind}{A character string or a numeric value or a \code{\link[ggd]{GGD}} object + which indicates the kind of distribution model to be constructed. + It is equivalent to \code{kind} argument of \code{ggd.trace.q}. + + In this method, the value of \code{kind} field will be not + necessarily retained without indicating any conditions, + whereas the value of \code{mix.type} field will be retained + as long as possible. + That is, the condition of aligning the mean values or + standard deviations of the component to be equal will not be retained. + If you want to retain the condition as well, indicate the object itself to \code{this.kind} argument like as \code{obj$trace.q(quantiles, this.kind = obj)}.} \item{this.mix.type}{A numeric value to set into \code{mix.type} field as an integer. It should be an integer from \code{0} to \code{4} or \code{NULL}. + It is equivalent to \code{mix.type} argument of \code{ggd.trace.q}. If \code{NULL}, the current \code{mix.type} field will be retained - (and number of components, too) if it could trace the quantiles. + (and number of components, too) if it can trace the quantiles. But if could not, it tries to trace the quantiles - with changing \code{mix.type} as same as the generator function - (signature '\code{NULL}'). - Thus, the priority sequence of \code{mix.type} is - current > 2 > 4 > 3 (2 components) > 3 (3 components) > 1 > 0.} + with changing \code{mix.type} as same as \code{ggd.trace.q}. + The priority sequence of \code{mix.type} is + current > 2 > 4 > 3 (2 components > 3 components) > 1 > 0.} } \value{ A list containing components (invisible for \code{GGD} method) \item{obj}{ The \code{\link[ggd]{GGD}} object which traces the quantiles. - For \code{\link[ggd]{GGD}} method, the \code{\link[ggd]{GGD}} object itself.} + For \code{\link[ggd]{GGD}} method, + the \code{\link[ggd]{GGD}} object itself.} \item{nleqslv.out}{ The list of the output of \code{\link[nleqslv]{nleqslv}} which has succeeded to solve tracing quantiles.} - For \code{GGD} method: If an error occur, the object will be cleared in most cases. + For \code{GGD} method: If an error occurs, all fields of the object will be cleared + in most cases. } \description{ Constructs a \code{\link[ggd]{GGD}} object which traces all of the given quantiles accurately with its cumulative distribution function. +Then \code{ggd.trace.q} function generates a \code{\link[ggd]{GGD}} object, +and \code{trace.q} method sets the fields according to the result. } \details{ \subsection{Allowed number of quantiles}{ - The allowed numbers of quantiles depends on the value of \code{mix.type} argument/field. - Because the value determines the number of components in \code{cmd} field, - and also determines the degrees of freedom of the distribution model. - The allowed numbers of quantiles are as follows: + The allowed numbers of quantiles depends on the value of \code{mix.type}. + Because \code{mix.type} determines the number of components in \code{cmd} field, + and the degrees of freedom follows it. + In this package, the allowed numbers of quantiles are: \itemize{ \item \code{mix.type = 0} : 2 quantiles only. \item \code{mix.type = 1} : 3 or 4 quantiles. @@ -192,17 +193,16 @@ accurately with its cumulative distribution function. \item \code{mix.type = 4} : 5 to 8 quantiles. } About \code{mix.type = 3}, - if \code{grad = "v2"}, 3 or 4 quantiles are allowed. + if \code{grad = "v2"}, only 3 or 4 quantiles are allowed. If \code{grad = "v3"}, 3 to 6 quantiles are allowed. - - Note, if \code{mix.type = 3} is indicated with \code{grad = "default"}, + If \code{grad = "default"} is indicated with \code{mix.type = 3}, it tries both \code{grad = "v2"} and \code{"v3"} cases - and give priority to \code{"v2"}. + with giving priority to \code{"v2"}. } \subsection{Tightening with eq.mean / eq.sd}{ - If either \code{eq.mean = TRUE} or \code{eq.sd = TRUE} is indicated, - as each of them reduces the degrees of freedom, - the number of quantiles is restricted as follows: + Indicating \code{TRUE} for either \code{eq.mean} or \code{eq.sd} + reduces the degrees of freedom. + In this case, the number of quantiles is restricted as: \itemize{ \item \code{mix.type = 1} : 3 quantiles only. \item \code{mix.type = 2} : 3 quantiles only. @@ -214,86 +214,75 @@ accurately with its cumulative distribution function. With \code{grad = "v3"}, it works for 3 or 4 quantiles. If both \code{eq.mean} and \code{eq.sd} are \code{TRUE}, - a normal distribution will be constructed and number of quantiles must be 2. + a normal distribution will be generated. + In this case, number of quantiles must be 2. } } \examples{ - ## Mean of 2 Normal Distributions Example: - ## If mix.type = 1, it constructs a mean of 2 normal distributions. - ## This model is not a gradational Gaussian distribution (GDD), - ## but a kind of Gaussian mixture model (GMM). + ## Preparing: + ## This function shows 1) the cumulative distribution function with plotting the quantiles + ## and 2) the probability density function. + plot.p.qt.d <- function( obj, x, p, xlim, ylim ) + { + layout( matrix( c( 1, 0, 2, 0 ), 2, 2, byrow = TRUE ) ) + plot( x, p, xlim = xlim, ylim = c( 0, 1 ), xlab = "", ylab = "" ) + par( new = TRUE ) + plot( seq( xlim[1], xlim[2], 0.1 ), obj$p( seq( xlim[1], xlim[2], 0.1 ) ), + type = "l", xlim = xlim, ylim = c( 0, 1 ), xlab = "", ylab = "" ) + par( new = FALSE ) + plot( seq( xlim[1], xlim[2], 0.1 ), obj$d( seq( xlim[1], xlim[2], 0.1 ) ), + type = "l", xlim = xlim, ylim = ylim, xlab = "", ylab = "" ) + } + + ## Horizontal gradation: + ## If mix.type = 2 or grad = "h", it generates a horizontal gradational distribution. ## The number of quantiles must be 3 or 4. - result <- ggd.trace.q( data.frame( - x = c( qnorm( 0.1, 0, 1 ), 0, qnorm( 0.6, 0, 0.75 ) ), - p = c( 0.1, 0.5, 0.6 ) ), - mix.type = 1 ) + qt <- data.frame( x = c( -0.67, 0, 0.53 ), p = c( 0.25, 0.5, 0.75 ) ) + result <- ggd.trace.q( qt, mix.type = 2 ) result - plot( seq( -3, 3, 0.01 ), result$obj$d( seq( -3, 3, 0.01 ) ), type = "l" ) - - ## Horizontal Gradational Example: - ## If mix.type = 2 or grad = "h", - ## it constructs a horizontal gradational distribution. - ## The number of p of the quantiles must be 3 or 4. - a <- ggd.trace.q( data.frame( x = c( -0.67, 0, 0.53 ), p = c( 0.25, 0.5, 0.75 ) ), - mix.type = 2 )$obj - a - plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) - - ## eq.sd Example: - ## If eq.sd = TRUE, it constructs a distribution model with components of which - ## the standard deviations are all equal. - a$trace.q( - data.frame( x = c( -0.64, -0.25, 0 ), p = c( 0.25, 0.4, 0.5 ) ), - this.mix.type = 2, eq.sd = TRUE ) - a$cmp - plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) - - ## Vertical Gradational Example: - ## If grad = "v2", it constructs a vertical gradation of 2 normal distributions. + plot.p.qt.d( result$obj, qt$x, qt$p, c( -3, 3 ), c( 0, 0.5 ) ) + + ## 2-component vertical gradation: + ## If grad = "v" or "v2", it generates a 2-component vertical gradational distribution. ## The number of quantiles must be 3 or 4. - a$trace.q( - data.frame( x = c( -1.28, -0.23, 0 ), p = c( 0.1, 0.4, 0.5 ) ), - grad = "v2" ) - plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) - - ## eq.mean Example: - ## If eq.mean = TRUE, it constructs a mean-equaled distribution model. - - a$trace.q( - data.frame( x = c( -1.28, -0.42, 0 ), p = c( 0.1, 0.3, 0.5 ) ), - grad = "v2", eq.mean = TRUE ) - a$cmp - plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) - - ## 3-Mean/Sigma-Differed Vertical Gradational Example: - ## If grad = "v3", it constructs a vertical gradational distribution + qt <- data.frame( x.1 = c( -1.28, -0.42, 0 ), x.2 = c( -1.14, -0.51, 0 ), + p = c( 0.1, 0.3, 0.5 ) ) + a <- GGD$new() + a$trace.q( qt, x = "x.1", grad = "v2" ) + a$kind; a$cmp; a$is.symmetric() ## FALSE + plot.p.qt.d( a, qt$x.1, qt$p, c( -3, 3 ), c( 0, 0.52 ) ) + + ## eq.mean: + ## If eq.mean = TRUE, it generates a mean-equaled distribution model. + a$trace.q( qt, x = "x.1", eq.mean = TRUE ) + a$kind; a$cmp; a$is.symmetric() ## TRUE + plot.p.qt.d( a, qt$x.1, qt$p, c( -3, 3 ), c( 0, 0.52 ) ) + + ## eq.sd: + ## If eq.sd = TRUE, it generates a distribution model with components of which + ## the standard deviations are all equal. + a$trace.q( qt, x = "x.2", this.kind = "Horizontal", eq.sd = TRUE ) + a$kind; a$cmp; a$is.symmetric() ## TRUE + plot.p.qt.d( a, qt$x.2, qt$p, c( -3, 3 ), c( 0, 0.4 ) ) + + ## 3-component vertical gradation: + ## If grad = "v3", it generates a vertical gradational distribution ## with different components for left-tail side and right-tail side. ## The number of quantiles must be from 3 to 6. - a <- ggd.trace.q( - data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ), - grad = "v3" )$obj - a - plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) + qt <- data.frame( x = c( -1.92, -0.20, 0.20, 1.92 ), p = c( 0.1, 0.4, 0.6, 0.9 ) ) + a$trace.q( qt, grad = "v3" ) + a$kind; a$cmp + plot.p.qt.d( a, qt$x, qt$p, c( -3, 3 ), c( 0, 0.52 ) ) - ## Horizontal-Vertical Gradational Examples: + ## Horizontal-vertical gradation: ## If mix.type = 4 or grad = "hv", - ## it constructs a horizontal-vertical gradational distribution. + ## it generates a horizontal-vertical gradational distribution. ## The number of quantiles must be from 5 to 8. - a <- ggd.trace.q( - data.frame( - x = c( -1.38, -0.76, -0.28, 0.02, 0.36, 1.10, 2.79 ), - p = c( 0.1, 0.25, 0.4, 0.5, 0.6, 0.75, 0.9 ) ), - mix.type = 4 )$obj - a - plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) - - a$trace.q( - data.frame( - x = c( -1.40, -0.96, -0.61, -0.30, 0.32, 0.72, 1.23, 2.21 ), - p = c( 0.1, 0.2, 0.3, 0.4, 0.6, 0.7, 0.8, 0.9 ) ), - grad = "hv" ) - a - plot( seq( -3, 3, 0.01 ), a$d( seq( -3, 3, 0.01 ) ), type = "l" ) + qt <- data.frame( x.coor = c( -1.40, -0.96, -0.61, -0.30, 0.32, 0.72, 1.23, 2.21 ), + prob = c( 0.1, 0.2, 0.3, 0.4, 0.6, 0.7, 0.8, 0.9 ) ) + a$trace.q( qt, x = "x.coor", p = "prob", grad = "hv" ) + a$kind; a$cmp + plot.p.qt.d( a, qt$x, qt$p, c( -3, 3 ), c( 0, 0.35 ) ) } \seealso{ \code{\link[ggd]{nls.freq}} diff --git a/man/v2.crossover.Rd b/man/v2.crossover.Rd index 887e4fa..921ece5 100644 --- a/man/v2.crossover.Rd +++ b/man/v2.crossover.Rd @@ -2,13 +2,12 @@ % Please edit documentation in R/ggd.trace.q.R \name{v2.crossover} \alias{v2.crossover} -\title{[Non-exported] Crossover-tracing (3 quantiles, vertical gradation of 2 normal distributions)} +\title{[Non-exported] Crossover-tracing (3 quantiles, v2)} \usage{ v2.crossover(qt, control) } \arguments{ -\item{qt}{A data frame; the quantiles to be traced, -If the median is specified, median must be included.} +\item{qt}{A data frame; the quantiles to be traced.} \item{control}{The \code{control} option for \code{\link[nleqslv]{nleqslv}}.} } @@ -20,13 +19,13 @@ A list containing components The output of \code{\link[nleqslv]{nleqslv}}.} } \description{ -Gets the data frame for \code{cmp} field where \code{mix.type = 3} and tracing 3 quantiles -with mean-differed 2 normal distributions of the components by crossover-tracing. +Tracing 3 quantiles by crossover-tracing, makes a data frame for \code{cmp} field +for a mean-differed 2-component vertical gradational distribution. } \details{ \subsection{Crossover-tracing}{ Let cumulative distribution functions of 2 mean-differed normal distributions - crossover at one of quantiles (except for median), + crossover at one of the quantiles (except for the median), and seek the mean values and standard deviations as tracing the other 2 quantiles. } } diff --git a/man/v2.qt4.cmp.Rd b/man/v2.qt4.cmp.Rd index a80fe06..ffbf56f 100644 --- a/man/v2.qt4.cmp.Rd +++ b/man/v2.qt4.cmp.Rd @@ -2,16 +2,16 @@ % Please edit documentation in R/ggd.trace.q.R \name{v2.qt4.cmp} \alias{v2.qt4.cmp} -\title{[Non-exported] Gets cmp field (4 quantiles, vertical gradation of 2 normal distributions)} +\title{[Non-exported] Gets cmp field (4 quantiles, v2)} \usage{ -v2.qt4.cmp(qt, control, retriable) +v2.qt4.cmp(qt, control, retryable) } \arguments{ \item{qt}{A data frame; the quantiles to be traced.} \item{control}{The \code{control} option for \code{\link[nleqslv]{nleqslv}}.} -\item{retriable}{A logical; the flag if retrying is enable.} +\item{retryable}{A logical; the flag if retrying is enable.} } \value{ A list containing components @@ -21,6 +21,6 @@ A list containing components The output of \code{\link[nleqslv]{nleqslv}}.} } \description{ -Gets the data frame for \code{cmp} field where \code{mix.type = 3} and tracing 4 quantiles -with 2 normal distributions of the components. +Tracing 4 quantiles with 2 normal distributions, makes a data frame for \code{cmp} field +where \code{mix.type = 3}. } diff --git a/man/v3.qt4.cmp.Rd b/man/v3.qt4.cmp.Rd index deb1baa..a5c52c5 100644 --- a/man/v3.qt4.cmp.Rd +++ b/man/v3.qt4.cmp.Rd @@ -2,9 +2,9 @@ % Please edit documentation in R/ggd.trace.q.R \name{v3.qt4.cmp} \alias{v3.qt4.cmp} -\title{[Non-exported] Gets cmp field (4 quantiles, vertical gradation of 3 normal distributions)} +\title{[Non-exported] Gets cmp field (4 quantiles, v3)} \usage{ -v3.qt4.cmp(qt, eq.mean, eq.sd, control, retriable, grad) +v3.qt4.cmp(qt, eq.mean, eq.sd, control, retryable, grad) } \arguments{ \item{qt}{A data frame; the quantiles to be traced.} @@ -15,10 +15,10 @@ v3.qt4.cmp(qt, eq.mean, eq.sd, control, retriable, grad) \item{control}{The \code{control} option for \code{\link[nleqslv]{nleqslv}}.} -\item{retriable}{A logical; the flag if retrying is enable.} +\item{retryable}{A logical; the flag if retrying is enable.} \item{grad}{A character string indicating the method of gradation. -If \code{"v3"}, constructing with 3 components is enforcedly, +If \code{"v3"}, the number of components will forced to be 3, even if it is possible to construct with 2 components.} } \value{ @@ -29,6 +29,6 @@ A list containing components The output of \code{\link[nleqslv]{nleqslv}}.} } \description{ -Gets the data frame for \code{cmp} field where \code{mix.type = 3} and tracing 4 quantiles -with 3 normal distributions of the components. +Tracing 4 quantiles with 3 normal distributions, makes a data frame for \code{cmp} field +where \code{mix.type = 3}. } diff --git a/man/write.csv.Rd b/man/write.csv.Rd index 730aaa5..01f971e 100644 --- a/man/write.csv.Rd +++ b/man/write.csv.Rd @@ -13,21 +13,25 @@ ggd.write.csv(obj, file = "") \arguments{ \item{obj}{The \code{\link[ggd]{GGD}} object to be saved.} -\item{file}{The name of the file or a \link[base]{connection} for writing -the composition of the object. \code{""} indicates output to the console.} +\item{file}{The name of the file or a \link[base]{connection} open for writing. +\code{""} indicates output to the console.} } \value{ An invisible NULL. } \description{ Writes the composition of a \code{\link[ggd]{GGD}} object as a CSV file. -Mean values and standard deviations of the components are recorded to a maximum length of -the 22nd decimal place. -The accuracy is sufficient to reconstruct the original object almost completely -(at least the value of each field can be \code{TRUE} with \code{"=="}) -in most cases, in most systems. -So, this function provides a simple way to export a \code{\link[ggd]{GGD}} object, -regardless of the package or R version. +This function provides a simple way to export a \code{\link[ggd]{GGD}} object, +regardless of the package version or R version. +} +\details{ +\subsection{Accuracy of saved data}{ + Mean values and standard deviations are recorded to a maximum length of + the 22nd decimal place. + The accuracy is sufficient to reconstruct the original object almost completely + (at least the value of each field can be \code{TRUE} with '\code{==}') + in most cases, and in most systems. +} } \examples{ a <- ggd.set.cmp( data.frame( mean = c( 0.223, 0.219 ), sd = c( 2.265, 2.176 ) ), diff --git a/tests/testthat/test.integ.R b/tests/testthat/test.integ.R index 78d0c53..09cfd10 100644 --- a/tests/testthat/test.integ.R +++ b/tests/testthat/test.integ.R @@ -1437,17 +1437,17 @@ lv.t3.sub <- function( k, mean, mean.k, sd.k ) { if ( k == 1 ) { - ggd:::calc.v.sub( 3, mean, mean.k, sd.k, min( mean, mean.k ), k = k ) + ggd:::calc.v.sub( 3, mean, mean.k, sd.k, min( mean, mean.k ), i = k ) } else if ( k == 2 ) { - ggd:::calc.v.sub( 3, mean, mean.k, sd.k, mean, k = k ) + ggd:::calc.v.sub( 3, mean, mean.k, sd.k, mean, i = k ) } else if ( k == 3 ) { if ( mean.k < mean ) { - ggd:::calc.v.sub( 3, mean, mean.k, sd.k, mean, k = k ) - + ggd:::calc.v.sub( 3, mean, mean.k, sd.k, mean, i = k ) - ( mean.k - mean )^2 * ( 2 - sqrt( 2 ) ) / 4 + ( mean.k - mean ) * sd.k * sqrt( 2 ) / sqrt( pi ) / 2 - sd.k^2 * ( 4 - sqrt( 2 ) ) / 8 @@ -1543,7 +1543,7 @@ uv.t3.sub <- function( k, mean, mean.k, sd.k ) ( mean.k - mean )^2 * ( 2 - sqrt( 2 ) ) / 4 - ( mean.k - mean ) * sd.k * sqrt( 2 ) / sqrt( pi ) / 2 + sd.k^2 * ( 4 - sqrt( 2 ) ) / 8 - - ggd:::calc.v.sub( 3, mean, mean.k, sd.k, mean, k = k ) + ggd:::calc.v.sub( 3, mean, mean.k, sd.k, mean, i = k ) } else { @@ -1554,13 +1554,13 @@ uv.t3.sub <- function( k, mean, mean.k, sd.k ) { ( mean.k - mean )^2 * sqrt( 2 ) / 2 + sd.k^2 * sqrt( 2 ) / 4 - - ggd:::calc.v.sub( 3, mean, mean.k, sd.k, mean, k = k ) + ggd:::calc.v.sub( 3, mean, mean.k, sd.k, mean, i = k ) } else if ( k == 3 ) { ( mean.k - mean )^2 * ( 2 - sqrt( 2 ) ) / 2 + sd.k^2 * ( 4 - sqrt( 2 ) ) / 4 - - ggd:::calc.v.sub( 3, mean, mean.k, sd.k, max( mean, mean.k ), k = k ) + ggd:::calc.v.sub( 3, mean, mean.k, sd.k, max( mean, mean.k ), i = k ) } } diff --git a/tests/testthat/test.set.cmp.R b/tests/testthat/test.set.cmp.R index d098553..bb16962 100644 --- a/tests/testthat/test.set.cmp.R +++ b/tests/testthat/test.set.cmp.R @@ -90,14 +90,23 @@ expect_equal( a$cmp$sd, c( 1, 2 ) ) expect_warning( a$set.cmp( data.frame( mean = c( -0.5, 0.5 ), sd = c( 1, 2 ) ), this.kind = "Horizontal", this.mix.type = 3 ), - "Indicated kind does not match to the result." ) + "Indicated kind does not match the result." ) expect_identical( a$mix.type, 3L ) expect_equal( a$cmp$mean, c( -0.5, 0.5 ) ) expect_equal( a$cmp$sd, c( 1, 2 ) ) +a$clear() +expect_warning( a$set.cmp( data.frame( mean = c( -0.5, 0.5 ), sd = c( 1, 2 ) ), + this.kind = "Vertical", + this.mix.type = 2 ), + "Indicated kind does not match the result." ) +expect_identical( a$mix.type, 2L ) +expect_equal( a$cmp$mean, c( -0.5, 0.5 ) ) +expect_equal( a$cmp$sd, c( 1, 2 ) ) + expect_warning( a <- ggd.set.cmp( data.frame( mean = c( -0.5, 0.5 ), sd = c( 1, 1 ) ), kind = "Mean-Differed Sigma-Differed Horizontal" ), - "Indicated kind does not match to the result" ) + "Indicated kind does not match the result" ) expect_identical( a$mix.type, 2L ) expect_equal( a$kind, "Mean-Differed Sigma-Equaled Horizontal Gradational Distribution" ) expect_equal( a$cmp$mean, c( -0.5, 0.5 ) ) @@ -110,9 +119,30 @@ expect_equal( a$kind, "Mean-Differed Sigma-Equaled Horizontal Gradational Distri expect_equal( a$cmp$mean, c( -0.5, 0.5 ) ) expect_equal( a$cmp$sd, c( 1, 1 ) ) +expect_no_warning( a <- ggd.set.cmp( data.frame( mean = c( 0.5, 0.5 ), sd = c( 2, 1 ) ), + kind = "Vertical" ) ) +expect_identical( a$mix.type, 3L ) +expect_equal( a$kind, "2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution" ) +expect_equal( a$cmp$mean, c( 0.5, 0.5 ) ) +expect_equal( a$cmp$sd, c( 2, 1 ) ) + +expect_warning( a$set.cmp( this.kind = "3-.*Vertical" ), + "Indicated kind does not match the result" ) +expect_identical( a$mix.type, 3L ) +expect_equal( a$kind, "2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution" ) +expect_equal( a$cmp$mean, c( 0.5, 0.5, 0.5 ) ) +expect_equal( a$cmp$sd, c( 2, 1, 2 ) ) + +expect_warning( a$set.cmp( this.kind = "H.*Vertical" ), + "Indicated kind does not match the result" ) +expect_identical( a$mix.type, 4L ) +expect_equal( a$kind, "2-Mean-Equaled Sigma-Differed Vertical Gradational Distribution" ) +expect_equal( a$cmp$mean, rep( 0.5, 4 ) ) +expect_equal( a$cmp$sd, c( 2, 1, 2, 1 ) ) + expect_warning( a <- ggd.set.cmp( data.frame( mean = c( 0.5, 0.5 ), sd = c( 1, 1.5 ) ), kind = 10 ), - "Indicated kind does not match to the result" ) + "Indicated kind does not match the result" ) expect_identical( a$mix.type, 3L ) expect_identical( a$kind.index, 9L ) expect_identical( a$mix.type, 3L ) @@ -267,7 +297,7 @@ expect_warning( a$set.cmp( data.frame( mean = c( -0.5, 0.5 ), sd = c( 1, 2 ) ), grad = "v2", this.kind = 7, this.mix.type = 4 ), - "Indicated kind does not match to the result" ) + "Indicated kind does not match the result" ) expect_identical( a$mix.type, 3L ) expect_equal( nrow( a$cmp ), 2 ) diff --git a/tests/testthat/test.trace.q.R b/tests/testthat/test.trace.q.R index 7db3850..6246b3d 100644 --- a/tests/testthat/test.trace.q.R +++ b/tests/testthat/test.trace.q.R @@ -6605,6 +6605,28 @@ expect_equal( a$is.v2( TRUE ), TRUE ) expect_equal( a$is.eq.mean(), TRUE ) expect_equal( a$is.eq.sd(), FALSE ) +# normal test +a$clear() +a$trace.q( + data.frame( + p = c( 0.1, 0.5, 0.7 ), + x = xs ), + this.kind = "Vertical", this.mix.type = 2 ) +expect_equal( a$is.h( TRUE ), TRUE ) +expect_equal( a$is.eq.mean(), FALSE ) +expect_equal( a$is.eq.sd(), FALSE ) + +# normal test +a$clear() +a$trace.q( + data.frame( + p = c( 0.1, 0.5, 0.7 ), + x = xs ), + this.kind = "Horizontal", this.mix.type = 3 ) +expect_equal( a$is.v2( TRUE ), TRUE ) +expect_equal( a$is.eq.mean(), FALSE ) +expect_equal( a$is.eq.sd(), FALSE ) + # normal test a$clear() a$trace.q(