ClaraHapp / MFPCA

# Compare  7788185 ... +10 ... 9c50ac8 

### No flags found

Use flags to group coverage reports by test type, project and/or folders.
Then setup custom commit statuses and notifications for each flag.

e.g., #unittest #integration

#production #enterprise

#frontend #backend

Showing 4 of 17 files from the diff.
R/UMPCA.R changed.
R/univPCA.R changed.
Other files ignored by Codecov
DESCRIPTION has changed.
man/MFPCA.Rd has changed.
man/PACE.Rd has changed.
man/umpcaBasis.Rd has changed.
man/givenBasis.Rd has changed.
man/fpcaBasis.Rd has changed.
NEWS.md has changed.
configure.ac has changed.
man/dot-PACE.Rd has changed.
man/UMPCA.Rd has changed.
configure has changed.

@@ -59,188 +59,177 @@
 59 59 #' different (dimensional) domains 60 60 #' 61 61 #' This function calculates a multivariate functional principal component 62 - #' analysis (MFPCA) based on i.i.d. observations \eqn{x_1, \ldots, x_N} of 63 - #' a multivariate functional data-generating process \eqn{X = (X^{(1)}, 64 - #' \ldots X^{(p)})}{X = X^(1), \ldots, X^(p)} with elements \eqn{X^{(j)} 65 - #' \in L^2(\mathcal{T}_j)}{X^(j) in L^2(calT_j)} defined on a domain 66 - #' \eqn{\mathcal{T}_j \subset IR^{d_j}}{calT_j of IR^{d_j}}. In 67 - #' particular, the elements can be defined on different (dimensional) 68 - #' domains. The results contain the mean function, the estimated 69 - #' multivariate functional principal components \eqn{\hat \psi_1, \ldots, 70 - #' \hat \psi_M} (having the same structure as \eqn{x_i}), the associated 71 - #' eigenvalues \eqn{\hat \nu_1 \geq \ldots \geq \hat \nu_M > 0} and the 72 - #' individual scores \eqn{\hat \rho_{im} = \widehat{}}{\hat 73 - #' \rho_{im} = \hat{}}. Moreover, estimated trajectories for 74 - #' each observation based on the truncated Karhunen-Loeve representation 75 - #' \deqn{\hat x_i = \sum_{m = 1}^M \hat \rho_{im} \hat \psi_m}{\hat x_i = 76 - #' \sum_{m = 1}^M \hat \rho_{im} \hat \psi_m} are given if desired 77 - #' (\code{fit = TRUE}). The implementation of the observations \eqn{x_i = 78 - #' (x_i^{(1)}, \ldots , x_i^{(p)}),~ i = 1 , \ldots, N}{x_i = (x_i^(1), 79 - #' \ldots , x_i^(p)), i = 1 , \ldots, N}, the mean function and 80 - #' multivariate functional principal components \eqn{\hat \psi_1, \ldots, 81 - #' \hat \psi_M} uses the \code{\link[funData]{multiFunData}} class, which 82 - #' is defined in the package \pkg{funData}. 62 + #' analysis (MFPCA) based on i.i.d. observations \eqn{x_1, \ldots, x_N} of a 63 + #' multivariate functional data-generating process \eqn{X = (X^{(1)}, \ldots 64 + #' X^{(p)})}{X = X^(1), \ldots, X^(p)} with elements \eqn{X^{(j)} \in 65 + #' L^2(\mathcal{T}_j)}{X^(j) in L^2(calT_j)} defined on a domain 66 + #' \eqn{\mathcal{T}_j \subset IR^{d_j}}{calT_j of IR^{d_j}}. In particular, the 67 + #' elements can be defined on different (dimensional) domains. The results 68 + #' contain the mean function, the estimated multivariate functional principal 69 + #' components \eqn{\hat \psi_1, \ldots, \hat \psi_M} (having the same structure 70 + #' as \eqn{x_i}), the associated eigenvalues \eqn{\hat \nu_1 \geq \ldots \geq 71 + #' \hat \nu_M > 0} and the individual scores \eqn{\hat \rho_{im} = 72 + #' \widehat{}}{\hat \rho_{im} = \hat{}}. Moreover, 73 + #' estimated trajectories for each observation based on the truncated 74 + #' Karhunen-Loeve representation \deqn{\hat x_i = \sum_{m = 1}^M \hat \rho_{im} 75 + #' \hat \psi_m}{\hat x_i = \sum_{m = 1}^M \hat \rho_{im} \hat \psi_m} are given 76 + #' if desired (\code{fit = TRUE}). The implementation of the observations 77 + #' \eqn{x_i = (x_i^{(1)}, \ldots , x_i^{(p)}),~ i = 1 , \ldots, N}{x_i = 78 + #' (x_i^(1), \ldots , x_i^(p)), i = 1 , \ldots, N}, the mean function and 79 + #' multivariate functional principal components \eqn{\hat \psi_1, \ldots, \hat 80 + #' \psi_M} uses the \code{\link[funData]{multiFunData}} class, which is defined 81 + #' in the package \pkg{funData}. 83 82 #' 84 - #' \subsection{Weighted MFPCA}{If the elements vary considerably in 85 - #' domain, range or variation, a weight vector \eqn{w_1 , \ldots, w_p} can 86 - #' be supplied and the MFPCA is based on the weighted scalar product 87 - #' \deqn{<>_w = \sum_{j = 1}^p w_j \int_{\mathcal{T}_j} f^{(j)}(t) 88 - #' g^{(j)}(t) \mathrm{d} t}{<>_w = \sum_{j = 1}^p w_j \int_\calT_j 89 - #' f^(j)(t) g^(j)(t) d t} and the corresponding weighted covariance 90 - #' operator \eqn{\Gamma_w}.} 83 + #' \subsection{Weighted MFPCA}{If the elements vary considerably in domain, 84 + #' range or variation, a weight vector \eqn{w_1 , \ldots, w_p} can be supplied 85 + #' and the MFPCA is based on the weighted scalar product \deqn{<>_w = 86 + #' \sum_{j = 1}^p w_j \int_{\mathcal{T}_j} f^{(j)}(t) g^{(j)}(t) \mathrm{d} 87 + #' t}{<>_w = \sum_{j = 1}^p w_j \int_\calT_j f^(j)(t) g^(j)(t) d t} and the 88 + #' corresponding weighted covariance operator \eqn{\Gamma_w}.} 91 89 #' 92 90 #' \subsection{Bootstrap}{If \code{bootstrap = TRUE}, pointwise bootstrap 93 - #' confidence bands are generated for the multivariate eigenvalues 94 - #' \eqn{\hat \nu_1, \ldots, \hat \nu_M } as well as for multivariate 95 - #' functional principal components \eqn{\hat \psi_1, \ldots, \hat 96 - #' \psi_M}{\hat \psi_1, \ldots, \hat \psi_M}. The parameter 97 - #' \code{nBootstrap} gives the number of bootstrap iterations. In each 98 - #' iteration, the observations are resampled on the level of 99 - #' (multivariate) functions and the whole MFPCA is recalculated. In 100 - #' particular, if the univariate basis depends on the data (FPCA 101 - #' approaches), basis functions and scores are both re-estimated. If the 102 - #' basis functions are fixed (e.g. splines), the scores from the original 103 - #' estimate are used to speed up the calculations. The confidence bands 104 - #' for the eigenfunctions are calculated separately for each element as 105 - #' pointwise percentile bootstrap confidence intervals. Analogously, the 106 - #' confidence bands for the eigenvalues are also percentile bootstrap 107 - #' confidence bands. The significance level(s) can be defined by the 108 - #' \code{bootstrapAlpha} parameter, which defaults to 5\%. As a result, 109 - #' the \code{MFPCA} function returns a list \code{CI} of the same length 91 + #' confidence bands are generated for the multivariate eigenvalues \eqn{\hat 92 + #' \nu_1, \ldots, \hat \nu_M } as well as for multivariate functional principal 93 + #' components \eqn{\hat \psi_1, \ldots, \hat \psi_M}{\hat \psi_1, \ldots, \hat 94 + #' \psi_M}. The parameter \code{nBootstrap} gives the number of bootstrap 95 + #' iterations. In each iteration, the observations are resampled on the level of 96 + #' (multivariate) functions and the whole MFPCA is recalculated. In particular, 97 + #' if the univariate basis depends on the data (FPCA approaches), basis 98 + #' functions and scores are both re-estimated. If the basis functions are fixed 99 + #' (e.g. splines), the scores from the original estimate are used to speed up 100 + #' the calculations. The confidence bands for the eigenfunctions are calculated 101 + #' separately for each element as pointwise percentile bootstrap confidence 102 + #' intervals. Analogously, the confidence bands for the eigenvalues are also 103 + #' percentile bootstrap confidence bands. The significance level(s) can be 104 + #' defined by the \code{bootstrapAlpha} parameter, which defaults to 5\%. As a 105 + #' result, the \code{MFPCA} function returns a list \code{CI} of the same length 110 106 #' as \code{bootstrapAlpha}, containing the lower and upper bounds of the 111 - #' confidence bands for the principal components as \code{multiFunData} 112 - #' objects of the same structure as \code{mFData}. The confidence bands 113 - #' for the eigenvalues are returned in a list \code{CIvalues}, containing 114 - #' the upper and lower bounds for each significance level.} 107 + #' confidence bands for the principal components as \code{multiFunData} objects 108 + #' of the same structure as \code{mFData}. The confidence bands for the 109 + #' eigenvalues are returned in a list \code{CIvalues}, containing the upper and 110 + #' lower bounds for each significance level.} 115 111 #' 116 112 #' 117 - #' \subsection{Univariate Expansions}{The multivariate functional 118 - #' principal component analysis relies on a univariate basis expansion for 119 - #' each element \eqn{X^{(j)}}{X^(j)}. The univariate basis representation 120 - #' is calculated using the \code{\link{univDecomp}} function, that passes 121 - #' the univariate functional observations and optional parameters to the 122 - #' specific function. The univariate decompositions are specified via the 123 - #' \code{uniExpansions} argument in the \code{MFPCA} function. It is a 124 - #' list of the same length as the \code{mFData} object, i.e. having one 125 - #' entry for each element of the multivariate functional data. For each 126 - #' element, \code{uniExpansion} must specify at least the type of basis 127 - #' functions to use. Additionally, one may add further parameters. The 128 - #' following basis representations are supported: \itemize{\item Given 129 - #' basis functions. Then \code{uniExpansions[[j]] = list(type = "given", 130 - #' functions, scores, ortho)}, where \code{functions} is a \code{funData} 131 - #' object on the same domain as \code{mFData}, containing the given basis 132 - #' functions. The parameters \code{scores} and \code{ortho} are optional. 133 - #' \code{scores} is an \code{N x K} matrix containing the scores (or 134 - #' coefficients) of the observed functions for the given basis functions, 135 - #' where \code{N} is the number of observed functions and \code{K} is the 136 - #' number of basis functions. If this is not supplied, the scores are 137 - #' calculated. The parameter \code{ortho} specifies whether the given 138 - #' basis functions are orthonormal \code{orhto = TRUE} or not \code{ortho 139 - #' = FALSE}. If \code{ortho} is not supplied, the functions are treated as 140 - #' non-orthogonal. \code{scores} and \code{ortho} are not checked for 141 - #' plausibility, use them on your own risk! \item Univariate functional 142 - #' principal component analysis. Then \code{uniExpansions[[j]] = list(type 143 - #' = "uFPCA", nbasis, pve, npc, makePD)}, where 144 - #' \code{nbasis,pve,npc,makePD} are parameters passed to the 113 + #' \subsection{Univariate Expansions}{The multivariate functional principal 114 + #' component analysis relies on a univariate basis expansion for each element 115 + #' \eqn{X^{(j)}}{X^(j)}. The univariate basis representation is calculated using 116 + #' the \code{\link{univDecomp}} function, that passes the univariate functional 117 + #' observations and optional parameters to the specific function. The univariate 118 + #' decompositions are specified via the \code{uniExpansions} argument in the 119 + #' \code{MFPCA} function. It is a list of the same length as the \code{mFData} 120 + #' object, i.e. having one entry for each element of the multivariate functional 121 + #' data. For each element, \code{uniExpansion} must specify at least the type of 122 + #' basis functions to use. Additionally, one may add further parameters. The 123 + #' following basis representations are supported: \itemize{\item Given basis 124 + #' functions. Then \code{uniExpansions[[j]] = list(type = "given", functions, 125 + #' scores, ortho)}, where \code{functions} is a \code{funData} object on the 126 + #' same domain as \code{mFData}, containing the given basis functions. The 127 + #' parameters \code{scores} and \code{ortho} are optional. \code{scores} is an 128 + #' \code{N x K} matrix containing the scores (or coefficients) of the observed 129 + #' functions for the given basis functions, where \code{N} is the number of 130 + #' observed functions and \code{K} is the number of basis functions. Note that 131 + #' the scores need to be demeaned to give meaningful results. If scores are not 132 + #' supplied, they are calculated using the given basis functions. The parameter 133 + #' \code{ortho} specifies whether the given basis functions are orthonormal 134 + #' \code{orhto = TRUE} or not \code{ortho = FALSE}. If \code{ortho} is not 135 + #' supplied, the functions are treated as non-orthogonal. \code{scores} and 136 + #' \code{ortho} are not checked for plausibility, use them at your own risk! 137 + #' \item Univariate functional principal component analysis. Then 138 + #' \code{uniExpansions[[j]] = list(type = "uFPCA", nbasis, pve, npc, makePD)}, 139 + #' where \code{nbasis,pve,npc,makePD} are parameters passed to the 145 140 #' \code{\link{PACE}} function for calculating the univariate functional 146 141 #' principal component analysis. \item Basis functions expansions from the 147 - #' package \pkg{fda}. Then \code{uniExpansions[[j]] = list(type = "fda", 148 - #' ...)}, where \code{...} are passed to 149 - #' \code{\link[funData]{funData2fd}}, which heavily builds on 150 - #' \code{\link[fda]{eval.fd}}. If \pkg{fda} is not available, a warning is 151 - #' thrown. \item Spline basis functions (not penalized). Then 142 + #' package \pkg{fda}. Then \code{uniExpansions[[j]] = list(type = "fda", ...)}, 143 + #' where \code{...} are passed to \code{\link[funData]{funData2fd}}, which 144 + #' heavily builds on \code{\link[fda]{eval.fd}}. If \pkg{fda} is not available, 145 + #' a warning is thrown. \item Spline basis functions (not penalized). Then 152 146 #' \code{uniExpansions[[j]] = list(type = "splines1D", bs, m, k)}, where 153 147 #' \code{bs,m,k} are passed to the functions \code{\link{univDecomp}} and 154 - #' \code{\link{univExpansion}}. For two-dimensional tensor product 155 - #' splines, use \code{type = "splines2D"}. \item Spline basis functions 156 - #' (with smoothness penalty). Then \code{uniExpansions[[j]] = list(type = 157 - #' "splines1Dpen", bs, m, k)}, where \code{bs,m,k} are passed to the 158 - #' functions \code{\link{univDecomp}} and \code{\link{univExpansion}}. 159 - #' Analogously to the unpenalized case, use \code{type = "splines2Dpen"} 160 - #' for 2D penalized tensor product splines. \item Cosine basis functions. 161 - #' Use \code{uniExpansions[[j]] = list(type = "DCT2D", qThresh, parallel)} 162 - #' for functions one two-dimensional domains (images) and \code{type = 163 - #' "DCT3D"} for 3D images. The calculation is based on the discrete cosine 164 - #' transform (DCT) implemented in the C-library \code{fftw3}. If this 165 - #' library is not available, the function will throw a warning. 166 - #' \code{qThresh} gives the quantile for hard thresholding the basis 167 - #' coefficients based on their absolute value. If \code{parallel = TRUE}, 168 - #' the coefficients for different images are calculated in parallel.} See 169 - #' \code{\link{univDecomp}} and \code{\link{univExpansion}} for details.} 148 + #' \code{\link{univExpansion}}. For two-dimensional tensor product splines, use 149 + #' \code{type = "splines2D"}. \item Spline basis functions (with smoothness 150 + #' penalty). Then \code{uniExpansions[[j]] = list(type = "splines1Dpen", bs, m, 151 + #' k)}, where \code{bs,m,k} are passed to the functions \code{\link{univDecomp}} 152 + #' and \code{\link{univExpansion}}. Analogously to the unpenalized case, use 153 + #' \code{type = "splines2Dpen"} for 2D penalized tensor product splines. \item 154 + #' Cosine basis functions. Use \code{uniExpansions[[j]] = list(type = "DCT2D", 155 + #' qThresh, parallel)} for functions one two-dimensional domains (images) and 156 + #' \code{type = "DCT3D"} for 3D images. The calculation is based on the discrete 157 + #' cosine transform (DCT) implemented in the C-library \code{fftw3}. If this 158 + #' library is not available, the function will throw a warning. \code{qThresh} 159 + #' gives the quantile for hard thresholding the basis coefficients based on 160 + #' their absolute value. If \code{parallel = TRUE}, the coefficients for 161 + #' different images are calculated in parallel.} See \code{\link{univDecomp}} 162 + #' and \code{\link{univExpansion}} for details.} 170 163 #' 171 - #' @param mFData A \code{\link[funData]{multiFunData}} object containing 172 - #' the \code{N} observations. 164 + #' @param mFData A \code{\link[funData]{multiFunData}} object containing the 165 + #' \code{N} observations. 173 166 #' @param M The number of multivariate functional principal components to 174 167 #' calculate. 175 - #' @param uniExpansions A list characterizing the (univariate) expansion 176 - #' that is calculated for each element. See Details. 177 - #' @param weights An optional vector of weights, defaults to \code{1} for 178 - #' each element. See Details. 179 - #' @param fit Logical. If \code{TRUE}, a truncated multivariate 180 - #' Karhunen-Loeve representation for the data is calculated based on the 181 - #' estimated scores and eigenfunctions. 182 - #' @param approx.eigen Logical. If \code{TRUE}, the eigenanalysis problem 183 - #' for the estimated covariance matrix is solved approximately using the 168 + #' @param uniExpansions A list characterizing the (univariate) expansion that is 169 + #' calculated for each element. See Details. 170 + #' @param weights An optional vector of weights, defaults to \code{1} for each 171 + #' element. See Details. 172 + #' @param fit Logical. If \code{TRUE}, a truncated multivariate Karhunen-Loeve 173 + #' representation for the data is calculated based on the estimated scores and 174 + #' eigenfunctions. 175 + #' @param approx.eigen Logical. If \code{TRUE}, the eigenanalysis problem for 176 + #' the estimated covariance matrix is solved approximately using the 184 177 #' \pkg{irlba} package, which is much faster. If the number \code{M} of 185 - #' eigenvalues to calculate is high with respect to the number of 186 - #' observations in \code{mFData} or the number of estimated univariate 187 - #' eigenfunctions, the approximation may be inappropriate. In this case, 188 - #' approx.eigen is set to \code{FALSE} and the function throws a 189 - #' warning. Defaults to \code{FALSE}. 190 - #' @param bootstrap Logical. If \code{TRUE}, pointwise bootstrap 191 - #' confidence bands are calculated for the multivariate functional 192 - #' principal components. Defaults to \code{FALSE}. See Details. 193 - #' @param nBootstrap The number of bootstrap iterations to use. Defaults 194 - #' to \code{NULL}, which leads to an error, if \code{bootstrap = TRUE}. 195 - #' @param bootstrapAlpha A vector of numerics (or a single number) giving 196 - #' the significance level for bootstrap intervals. Defaults to 197 - #' \code{0.05}. 198 - #' @param bootstrapStrat A stratification variable for bootstrap. Must be 199 - #' a factor of length \code{nObs(mFData)} or \code{NULL} (default). If 200 - #' \code{NULL}, no stratification is made in the bootstrap resampling, 201 - #' i.e. the curves are sampled with replacement. If 202 - #' \code{bootstrapStrat} is not \code{NULL}, the curves are resampled 203 - #' with replacement within the groups defined by \code{bootstrapStrat}, 204 - #' hence keeping the group proportions fixed. 178 + #' eigenvalues to calculate is high with respect to the number of observations 179 + #' in \code{mFData} or the number of estimated univariate eigenfunctions, the 180 + #' approximation may be inappropriate. In this case, approx.eigen is set to 181 + #' \code{FALSE} and the function throws a warning. Defaults to \code{FALSE}. 182 + #' @param bootstrap Logical. If \code{TRUE}, pointwise bootstrap confidence 183 + #' bands are calculated for the multivariate functional principal components. 184 + #' Defaults to \code{FALSE}. See Details. 185 + #' @param nBootstrap The number of bootstrap iterations to use. Defaults to 186 + #' \code{NULL}, which leads to an error, if \code{bootstrap = TRUE}. 187 + #' @param bootstrapAlpha A vector of numerics (or a single number) giving the 188 + #' significance level for bootstrap intervals. Defaults to \code{0.05}. 189 + #' @param bootstrapStrat A stratification variable for bootstrap. Must be a 190 + #' factor of length \code{nObs(mFData)} or \code{NULL} (default). If 191 + #' \code{NULL}, no stratification is made in the bootstrap resampling, i.e. 192 + #' the curves are sampled with replacement. If \code{bootstrapStrat} is not 193 + #' \code{NULL}, the curves are resampled with replacement within the groups 194 + #' defined by \code{bootstrapStrat}, hence keeping the group proportions 195 + #' fixed. 205 196 #' @param verbose Logical. If \code{TRUE}, the function reports 206 197 #' extra-information about the progress (incl. timestamps). Defaults to 207 198 #' \code{options()$verbose}. 208 199 #' 209 200 #' @return An object of class \code{MFPCAfit} containing the following 210 - #' components: \item{values}{A vector of estimated eigenvalues \eqn{\hat 211 - #' \nu_1 , \ldots , \hat \nu_M}.} \item{functions}{A 201 + #' components: \item{values}{A vector of estimated eigenvalues \eqn{\hat \nu_1 202 + #' , \ldots , \hat \nu_M}.} \item{functions}{A 212 203 #' \code{\link[funData]{multiFunData}} object containing the estimated 213 - #' multivariate functional principal components \eqn{\hat \psi_1, 214 - #' \ldots, \hat \psi_M}.} \item{scores}{ A matrix of dimension \code{N x 215 - #' M} containing the estimated scores \eqn{\hat \rho_{im}}.} 216 - #' \item{vectors}{A matrix representing the eigenvectors associated with 217 - #' the combined univariate score vectors. This might be helpful for 218 - #' calculating predictions.} \item{normFactors}{The normalizing factors 219 - #' used for calculating the multivariate eigenfunctions and scores. This 220 - #' might be helpful when calculation predictions.} \item{meanFunction}{A 221 - #' multivariate functional data object, corresponding to the mean 222 - #' function. The MFPCA is applied to the de-meaned functions in 223 - #' \code{mFData}.}\item{fit}{A \code{\link[funData]{multiFunData}} 224 - #' object containing estimated trajectories for each observation based 225 - #' on the truncated Karhunen-Loeve representation and the estimated 226 - #' scores and eigenfunctions.} \item{CI}{A list of the same length as 227 - #' \code{bootstrapAlpha}, containing the pointwise lower and upper 228 - #' bootstrap confidence bands for each eigenfunction and each 229 - #' significance level in form of \code{\link[funData]{multiFunData}} 230 - #' objects (only if \code{bootstrap = TRUE}).} \item{CIvalues}{A list of 231 - #' the same length as \code{bootstrapAlpha}, containing the lower and 232 - #' upper bootstrap confidence bands for each eigenvalue and each 233 - #' significance level (only if \code{bootstrap = TRUE}).} 204 + #' multivariate functional principal components \eqn{\hat \psi_1, \ldots, \hat 205 + #' \psi_M}.} \item{scores}{ A matrix of dimension \code{N x M} containing the 206 + #' estimated scores \eqn{\hat \rho_{im}}.} \item{vectors}{A matrix 207 + #' representing the eigenvectors associated with the combined univariate score 208 + #' vectors. This might be helpful for calculating predictions.} 209 + #' \item{normFactors}{The normalizing factors used for calculating the 210 + #' multivariate eigenfunctions and scores. This might be helpful when 211 + #' calculation predictions.} \item{meanFunction}{A multivariate functional 212 + #' data object, corresponding to the mean function. The MFPCA is applied to 213 + #' the de-meaned functions in \code{mFData}.}\item{fit}{A 214 + #' \code{\link[funData]{multiFunData}} object containing estimated 215 + #' trajectories for each observation based on the truncated Karhunen-Loeve 216 + #' representation and the estimated scores and eigenfunctions.} \item{CI}{A 217 + #' list of the same length as \code{bootstrapAlpha}, containing the pointwise 218 + #' lower and upper bootstrap confidence bands for each eigenfunction and each 219 + #' significance level in form of \code{\link[funData]{multiFunData}} objects 220 + #' (only if \code{bootstrap = TRUE}).} \item{CIvalues}{A list of the same 221 + #' length as \code{bootstrapAlpha}, containing the lower and upper bootstrap 222 + #' confidence bands for each eigenvalue and each significance level (only if 223 + #' \code{bootstrap = TRUE}).} 234 224 #' 235 225 #' @export MFPCA 236 226 #' 237 227 #' @importFrom foreach %do% 238 228 #' @importFrom utils packageVersion 239 229 #' 240 - #' @references C. Happ, S. Greven (2018): Multivariate Functional 241 - #' Principal Component Analysis for Data Observed on Different 242 - #' (Dimensional) Domains. Journal of the American Statistical 243 - #' Association, 113(522): 649-659. DOI: 230 + #' @references C. Happ, S. Greven (2018): Multivariate Functional Principal 231 + #' Component Analysis for Data Observed on Different (Dimensional) Domains. 232 + #' Journal of the American Statistical Association, 113(522): 649-659. DOI: 244 233 #' \doi{10.1080/01621459.2016.1273115} 245 234 #' 246 235 #' @references C. Happ-Kurz (2020): Object-Oriented Software for Functional @@ -251,8 +240,7 @@ Loading  251 240 #' introduction to the \pkg{funData} package and it's interplay with 252 241 #' \pkg{MFPCA}. This file also includes a case study on how to use 253 242 #' \code{MFPCA}. Useful functions: \code{\link[funData]{multiFunData}}, 254 - #' \code{\link{PACE}}, \code{\link{univDecomp}}, 255 - #' \code{\link{univExpansion}}, 243 + #' \code{\link{PACE}}, \code{\link{univDecomp}}, \code{\link{univExpansion}}, 256 244 #' \code{\link[=summary.MFPCAfit]{summary}}, 257 245 #' \code{\link[=plot.MFPCAfit]{plot}}, 258 246 #' \code{\link[=scoreplot.MFPCAfit]{scoreplot}} @@ -1,54 +1,54 @@ Loading  1 1 #' UMPCA: Uncorrelated Multilinear Principle Component Analysis 2 - #'  3 - #' This function implements the uncorrelated multilinear principal component  4 - #' analysis for tensors of dimension 2, 3 or 4. The code is basically the same  2 + #' 3 + #' This function implements the uncorrelated multilinear principal component 4 + #' analysis for tensors of dimension 2, 3 or 4. The code is basically the same 5 5 #' as in the MATLAB toolbox UMPCA by Haiping Lu (Link: 6 - #' \url{http://www.mathworks.com/matlabcentral/fileexchange/35432}, see also 7 - #' references). 8 - #'  9 - #' @section Warning: As this algorithm aims more at uncorrelated features than  10 - #' at an optimal reconstruction of the data, hence it might give poor results  6 + #' \url{https://www.mathworks.com/matlabcentral/fileexchange/35432-uncorrelated-multilinear-principal-component-analysis-umpca}, 7 + #' see also references). 8 + #' 9 + #' @section Warning: As this algorithm aims more at uncorrelated features than 10 + #' at an optimal reconstruction of the data, hence it might give poor results 11 11 #' when used for the univariate decomposition of images in MFPCA. 12 - #'  13 - #' @param TX The input training data in tensorial representation, the last mode  14 - #' is the sample mode. For \code{N}th-order tensor data, \code{TX} is of  12 + #' 13 + #' @param TX The input training data in tensorial representation, the last mode 14 + #' is the sample mode. For \code{N}th-order tensor data, \code{TX} is of 15 15 #' \code{(N+1)}th-order with the \code{(N+1)}-mode to be the sample mode. 16 16 #' E.g., 30x20x10x100 for 100 samples of size 30x20x10. 17 - #' @param numP The dimension of the projected vector, denoted as \eqn{P} in the  18 - #' paper. It is the number of elementary multilinear projections (EMPs) in  17 + #' @param numP The dimension of the projected vector, denoted as \eqn{P} in the 18 + #' paper. It is the number of elementary multilinear projections (EMPs) in 19 19 #' tensor-to-vector projection. 20 - #'  21 - #' @return \item{Us}{The multilinear projection, consisting of \code{numP}  20 + #' 21 + #' @return \item{Us}{The multilinear projection, consisting of \code{numP} 22 22 #' (\eqn{P} in the paper) elementary multilinear projections (EMPs), each EMP 23 23 #' is consisted of \code{N} vectors, one in each mode.} \item{TXmean}{The mean 24 24 #' of the input training samples \code{TX}.} \item{odrIdx}{The ordering index 25 25 #' of projected features in decreasing variance.} 26 - #'  27 - #' @references Haiping Lu, K.N. Plataniotis, and A.N. Venetsanopoulos,  28 - #' "Uncorrelated Multilinear Principal Component Analysis for Unsupervised  29 - #' Multilinear Subspace Learning", IEEE Transactions on Neural Networks, Vol.  26 + #' 27 + #' @references Haiping Lu, K.N. Plataniotis, and A.N. Venetsanopoulos, 28 + #' "Uncorrelated Multilinear Principal Component Analysis for Unsupervised 29 + #' Multilinear Subspace Learning", IEEE Transactions on Neural Networks, Vol. 30 30 #' 20, No. 11, Page: 1820-1836, Nov. 2009. 31 - #'  31 + #' 32 32 #' @export UMPCA 33 - #'  33 + #' 34 34 #' @examples 35 35 #' set.seed(12345) 36 - #'  36 + #' 37 37 #' # define "true" components 38 38 #' a <- sin(seq(-pi, pi, length.out = 100)) 39 39 #' b <- exp(seq(-0.5, 1, length.out = 150)) 40 - #'  40 + #' 41 41 #' # simulate tensor data 42 42 #' X <- a %o% b %o% rnorm(80, sd = 0.5) 43 - #'  43 + #' 44 44 #' # estimate one component 45 45 #' UMPCAres <- UMPCA(X, numP = 1) 46 - #'  46 + #' 47 47 #' # plot the results and compare to true values 48 48 #' plot(UMPCAres$Us[[1]][,1]) 49 49 #' points(a/sqrt(sum(a^2)), pch = 20) # eigenvectors are defined only up to a sign change! 50 50 #' legend("topright", legend = c("True", "Estimated"), pch = c(20, 1)) 51 - #'  51 + #' 52 52 #' plot(UMPCAres$Us[[2]][,1]) 53 53 #' points(b/sqrt(sum(b^2)), pch = 20) 54 54 #' legend("topleft", legend = c("True", "Estimated"), pch = c(20, 1)) @@ -110,31 +110,31 @@ Loading  110 110 } 111 111 112 112 #' Use given basis functions for univariate representation 113 - #'  114 - #' @param funDataObject An object of class \code{\link[funData]{funData}}  115 - #' containing the observed functional data samples and for which the basis  116 - #' representation is to be calculated. 117 - #' @param functions A \code{funData} object that contains the basis  118 - #' functions. 119 - #' @param scores An optional matrix containing the scores or coefficients of  120 - #' the individual observations and each basis function. If \code{N} denotes 121 - #' the number of observations and \code{K} denotes the number of basis  122 - #' functions, then \code{scores} must be a matrix of dimensions \code{N x  123 - #' K}. If not supplied, the scores are calculated as projection of each  124 - #' observation on the basis functions. 125 - #' @param ortho An optional parameter, specifying whether the given basis  126 - #' functions are orthonormal (\code{ortho = TRUE}) or not (\code{ortho =  127 - #' FALSE}). If not supplied, the basis functions are considered as  128 - #' non-orthonormal and their pairwise scalar product is calculated for  129 - #' later use in the MFPCA. 130 - #'  131 - #' @return \item{scores}{The coefficient matrix.} \item{B}{A matrix 132 - #' containing the scalar product of all pairs of basis functions. This is 133 - #' \code{NULL}, if \code{ortho = TRUE}.}\item{ortho}{Logical, set to  134 - #' \code{TRUE}, if basis functions are orthonormal.} \item{functions}{A  135 - #' functional data object containing the basis functions.} 136 - #'  137 - #' @keywords internal 113 + #' 114 + #' @param funDataObject An object of class \code{\link[funData]{funData}} 115 + #' containing the observed functional data samples and for which the basis 116 + #' representation is to be calculated. The data is assumed to be demeaned. 117 + #' @param functions A \code{funData} object that contains the basis functions. 118 + #' @param scores An optional matrix containing the scores or coefficients of the 119 + #' individual observations and each basis function. If \code{N} denotes the 120 + #' number of observations and \code{K} denotes the number of basis functions, 121 + #' then \code{scores} must be a matrix of dimensions \code{N x K}. As the data 122 + #' is assumed to be demeaned, each column must have an average of 123 + #' approximately 0. If not supplied, the scores are calculated as projection 124 + #' of each observation on the basis functions. 125 + #' @param ortho An optional parameter, specifying whether the given basis 126 + #' functions are orthonormal (\code{ortho = TRUE}) or not (\code{ortho = 127 + #' FALSE}). If not supplied, the basis functions are considered as 128 + #' non-orthonormal and their pairwise scalar product is calculated for later 129 + #' use in the MFPCA. 130 + #' 131 + #' @return \item{scores}{The coefficient matrix.} \item{B}{A matrix containing 132 + #' the scalar product of all pairs of basis functions. This is \code{NULL}, if 133 + #' \code{ortho = TRUE}.}\item{ortho}{Logical, set to \code{TRUE}, if basis 134 + #' functions are orthonormal.} \item{functions}{A functional data object 135 + #' containing the basis functions.} 136 + #' 137 + #' @keywords internal 138 138 givenBasis <- function(funDataObject, functions, scores = NULL, ortho = NULL) 139 139 { 140 140  # check if funDataObject and functions are defined on the same domain @@ -149,6 +149,10 @@ Loading  149 149  if( ! isTRUE(all.equal(dim(scores), c(nObs(funDataObject), nObs(functions)))) ) 150 150  stop("Scores have wrong dimensions. Must be an N x K matrix with N the number of observations and K the number of basis functions.") 151 151   152 +  # check if scores have mean zero 153 +  if( ! isTRUE(all.equal(colMeans(scores), rep(0, nObs(functions)), tolerance = 2e-1))) 154 +  warning("Scores seem to be not demeaned. Please check.") 155 +   152 156  if(is.null(ortho)) 153 157  ortho <- FALSE 154 158   @@ -170,27 +174,27 @@ Loading  170 174 #' This function calculates a functional principal component basis 171 175 #' representation for functional data on one-dimensional domains. The FPCA is 172 176 #' calculated via the \code{\link{PACE}} function, which is built on 173 - #' \link[refund]{fpca.sc} in the \pkg{refund} package. 177 + #' \code{fpca.sc} in the \strong{refund} package. 174 178 #'  175 179 #' @param funDataObject An object of class \code{\link[funData]{funData}}  176 180 #' containing the observed functional data samples and for which the FPCA is  177 181 #' to be calculated. 178 182 #' @param nbasis An integer, representing the number of B-spline basis  179 183 #' functions used for estimation of the mean function and bivariate smoothing  180 184 #' of the covariance surface. Defaults to \code{10} (cf.  181 - #' \code{\link[refund]{fpca.sc}}). 185 + #' \code{fpca.sc} in \strong{refund}). 182 186 #' @param pve A numeric value between 0 and 1, the proportion of variance  183 187 #' explained: used to choose the number of principal components. Defaults to  184 - #' \code{0.99} (cf. \code{\link[refund]{fpca.sc}}). 188 + #' \code{0.99} (cf. \code{fpca.sc} in \strong{refund}). 185 189 #' @param npc An integer, giving a prespecified value for the number of  186 190 #' principal components. Defaults to \code{NULL}. If given, this overrides  187 - #' \code{pve} (cf. \code{\link[refund]{fpca.sc}}). 191 + #' \code{pve} (cf. \code{fpca.sc} in \strong{refund}). 188 192 #' @param makePD Logical: should positive definiteness be enforced for the  189 193 #' covariance surface estimate? Defaults to \code{FALSE} (cf.  190 - #' \code{\link[refund]{fpca.sc}}). 194 + #' \code{fpca.sc} in \strong{refund}). 191 195 #' @param cov.weight.type The type of weighting used for the smooth covariance 192 196 #' estimate in \code{\link{PACE}}. Defaults to \code{"none"}, i.e. no weighting. Alternatively,  193 - #' \code{"counts"} (corresponds to \code{\link[refund]{fpca.sc}} ) weights the pointwise estimates of the covariance function 197 + #' \code{"counts"} (corresponds to \code{fpca.sc} in \strong{refund}) weights the pointwise estimates of the covariance function 194 198 #' by the number of observation points. 195 199 #'  196 200 #' @return \item{scores}{A matrix of scores (coefficients) with dimension  @@ -234,69 +238,69 @@ Loading  234 238  )) 235 239 } 236 240 237 - #' Calculate an uncorrelated multilinear principal component basis  241 + #' Calculate an uncorrelated multilinear principal component basis 238 242 #' representation for functional data on two-dimensional domains 239 - #'  240 - #' This function calculates an uncorrelated multilinear principal component  241 - #' analysis (UMPCA) representation for functional data on two-dimensional  242 - #' domains. In this case, the data can be interpreted as images with \code{S1 x  243 - #' S2} pixels (assuming \code{nObsPoints(funDataObject) = (S1, S2)}), i.e. the  244 - #' total observed data are represented as third order tensor of dimension  243 + #' 244 + #' This function calculates an uncorrelated multilinear principal component 245 + #' analysis (UMPCA) representation for functional data on two-dimensional 246 + #' domains. In this case, the data can be interpreted as images with \code{S1 x 247 + #' S2} pixels (assuming \code{nObsPoints(funDataObject) = (S1, S2)}), i.e. the 248 + #' total observed data are represented as third order tensor of dimension 245 249 #' \code{N x S1 x S2}. The UMPCA of a tensor of this kind is calculated via the 246 - #' \link{UMPCA} function, which is an \code{R}-version of the analogous  247 - #' functions in the \code{UMPCA} MATLAB toolbox by Haiping Lu (Link:  248 - #' \url{http://www.mathworks.com/matlabcentral/fileexchange/35432}, see also  249 - #' references). 250 - #'  251 - #' @section Warning: As this algorithm aims more at uncorrelated features than  252 - #' at an optimal reconstruction of the data, hence it might give poor results  250 + #' \link{UMPCA} function, which is an \code{R}-version of the analogous 251 + #' functions in the \code{UMPCA} MATLAB toolbox by Haiping Lu (Link: 252 + #' \url{https://www.mathworks.com/matlabcentral/fileexchange/35432-uncorrelated-multilinear-principal-component-analysis-umpca}, 253 + #' see also references). 254 + #' 255 + #' @section Warning: As this algorithm aims more at uncorrelated features than 256 + #' at an optimal reconstruction of the data, hence it might give poor results 253 257 #' when used for the univariate decomposition of images in MFPCA. The function 254 258 #' therefore throws a warning. 255 - #'  256 - #' @param funDataObject An object of class \code{\link[funData]{funData}}  257 - #' containing the observed functional data samples (here: images) for which  259 + #' 260 + #' @param funDataObject An object of class \code{\link[funData]{funData}} 261 + #' containing the observed functional data samples (here: images) for which 258 262 #' the UMPCA is to be calculated. 259 - #' @param npc An integer, giving the number of principal components to be  263 + #' @param npc An integer, giving the number of principal components to be 260 264 #' calculated. 261 - #'  262 - #' @return \item{scores}{A matrix of scores (coefficients) with dimension  263 - #' \code{N x k}, reflecting the weight of each principal component in each  265 + #' 266 + #' @return \item{scores}{A matrix of scores (coefficients) with dimension 267 + #' \code{N x k}, reflecting the weight of each principal component in each 264 268 #' observation.} \item{B}{A matrix containing the scalar product of all pairs 265 - #' of basis functions.} \item{ortho}{Logical, set to \code{FALSE}, as basis  266 - #' functions are not orthonormal.} \item{functions}{A functional data object,  269 + #' of basis functions.} \item{ortho}{Logical, set to \code{FALSE}, as basis 270 + #' functions are not orthonormal.} \item{functions}{A functional data object, 267 271 #' representing the functional principal component basis functions.} 268 - #'  272 + #' 269 273 #' @seealso \code{\link{univDecomp}} 270 - #'  271 - #' @references Haiping Lu, K.N. Plataniotis, and A.N. Venetsanopoulos,  272 - #' "Uncorrelated Multilinear Principal Component Analysis for Unsupervised  273 - #' Multilinear Subspace Learning", IEEE Transactions on Neural Networks, Vol.  274 + #' 275 + #' @references Haiping Lu, K.N. Plataniotis, and A.N. Venetsanopoulos, 276 + #' "Uncorrelated Multilinear Principal Component Analysis for Unsupervised 277 + #' Multilinear Subspace Learning", IEEE Transactions on Neural Networks, Vol. 274 278 #' 20, No. 11, Page: 1820-1836, Nov. 2009. 275 - #'  279 + #' 276 280 #' @keywords internal 277 - #'  281 + #' 278 282 #' @examples 279 283 #' # simulate image data for N = 100 observations 280 284 #' N <- 100 281 285 #' b1 <- eFun(seq(0,1,0.01), M = 7, type = "Poly") 282 286 #' b2 <- eFun(seq(-pi, pi, 0.03), M = 8, type = "Fourier") 283 287 #' b <- tensorProduct(b1,b2) # 2D basis functions 284 288 #' scores <- matrix(rnorm(N*56), nrow = N) 285 - #'  289 + #' 286 290 #' # calculate observations (= linear combination of basis functions) 287 291 #' f <- MFPCA:::expandBasisFunction(scores = scores, functions = b) 288 - #'  292 + #' 289 293 #' # calculate basis functions based on UMPCA algorithm (needs some time) 290 294 #' \donttest{ 291 295 #' # throws warning as the function aims more at uncorrelated features than at 292 296 #' # optimal data reconstruction (see help) 293 - #' umpca <- MFPCA:::umpcaBasis(f, npc = 5)  294 - #'  297 + #' umpca <- MFPCA:::umpcaBasis(f, npc = 5) 298 + #' 295 299 #' oldpar <- par(no.readonly = TRUE) 296 - #'  300 + #' 297 301 #' for(i in 1:5) # plot all 5 basis functions 298 302 #' plot(umpca$functions, obs = i, main = paste("Basis function", i)) # plot first basis function 299 - #'  303 + #' 300 304 #' par(oldpar)} 301 305 umpcaBasis <- function(funDataObject, npc) 302 306 {

@@ -5,7 +5,7 @@
 5 5 #' Calculate univariate functional PCA 6 6 #'  7 7 #' This function is a slightly adapted version of the  8 - #' \code{\link[refund]{fpca.sc}} function in the \pkg{refund} package for  8 + #' \code{fpca.sc} function in the \strong{refund} package for  9 9 #' calculating univariate functional principal components based on a smoothed  10 10 #' covariance function. The smoothing basis functions are penalized splines. 11 11 #'
@@ -25,7 +25,7 @@
 25 25 #' covariance estimate? Defaults to \code{FALSE}. 26 26 #' @param cov.weight.type The type of weighting used for the smooth covariance 27 27 #' estimate. Defaults to \code{"none"}, i.e. no weighting. Alternatively,  28 - #' \code{"counts"} (corresponds to \code{\link[refund]{fpca.sc}} ) weights the pointwise estimates of the covariance function 28 + #' \code{"counts"} (corresponds to \code{fpca.sc} in \strong{refund}) weights the pointwise estimates of the covariance function 29 29 #' by the number of observation points. 30 30 #'  31 31 #' @return \item{fit}{The approximation of \code{Y.pred} (if \code{NULL}, the
@@ -37,7 +37,7 @@
 37 37 #' were calculated.} \item{sigma2}{The estimated variance of the measurement  38 38 #' error.} \item{estVar}{The estimated smooth variance function of the data.} 39 39 #'  40 - #' @seealso \code{\link[refund]{fpca.sc}}, \code{\link{PACE}} 40 + #' @seealso \code{\link{PACE}} 41 41 #'  42 42 #' @references Di, C., Crainiceanu, C., Caffo, B., and Punjabi, N. (2009).  43 43 #' Multilevel functional principal component analysis. Annals of Applied
@@ -139,7 +139,7 @@
 139 139 #'  140 140 #' This function calculates a univariate functional principal components  141 141 #' analysis by smoothed covariance based on code from  142 - #' \code{\link[refund]{fpca.sc}} (package \pkg{refund}). 142 + #' \code{fpca.sc} in package \strong{refund}. 143 143 #'  144 144 #' @section Warning: This function works only for univariate functional data  145 145 #' observed on one-dimensional domains.
@@ -157,19 +157,19 @@
 157 157 #' @param nbasis An integer, representing the number of B-spline basis  158 158 #' functions used for estimation of the mean function and bivariate smoothing  159 159 #' of the covariance surface. Defaults to \code{10} (cf.  160 - #' \code{\link[refund]{fpca.sc}}). 160 + #' \code{fpca.sc} in \strong{refund}). 161 161 #' @param pve A numeric value between 0 and 1, the proportion of variance  162 162 #' explained: used to choose the number of principal components. Defaults to  163 - #' \code{0.99} (cf. \code{\link[refund]{fpca.sc}}). 163 + #' \code{0.99} (cf. \code{fpca.sc} in \strong{refund}). 164 164 #' @param npc An integer, giving a prespecified value for the number of  165 165 #' principal components. Defaults to \code{NULL}. If given, this overrides  166 - #' \code{pve} (cf. \code{\link[refund]{fpca.sc}}). 166 + #' \code{pve} (cf. \code{fpca.sc} in \strong{refund}). 167 167 #' @param makePD Logical: should positive definiteness be enforced for the  168 168 #' covariance surface estimate? Defaults to \code{FALSE} (cf.  169 - #' \code{\link[refund]{fpca.sc}}). 169 + #' \code{fpca.sc} in \strong{refund}). 170 170 #' @param cov.weight.type The type of weighting used for the smooth covariance  171 171 #' estimate. Defaults to \code{"none"}, i.e. no weighting. Alternatively,  172 - #' \code{"counts"} (corresponds to \code{\link[refund]{fpca.sc}} ) weights the 172 + #' \code{"counts"} (corresponds to \code{fpca.sc} in \strong{refund}) weights the 173 173 #' pointwise estimates of the covariance function by the number of observation 174 174 #' points. 175 175 #'
@@ -186,12 +186,12 @@
 186 186 #' (if \code{predData} is \code{NULL}).} \item{npc}{The number of functional  187 187 #' principal components: either the supplied \code{npc}, or the minimum number 188 188 #' of basis functions needed to explain proportion \code{pve} of the variance  189 - #' in the observed curves (cf. \code{\link[refund]{fpca.sc}}).}  189 + #' in the observed curves (cf. \code{fpca.sc} in \strong{refund}).}  190 190 #' \item{sigma2}{The estimated measurement error variance (cf.  191 - #' \code{\link[refund]{fpca.sc}}).} \item{estVar}{The estimated smooth 191 + #' \code{fpca.sc} in \strong{refund}).} \item{estVar}{The estimated smooth 192 192 #' variance function of the data.} 193 193 #'  194 - #' @seealso \code{\link[funData]{funData}}, \code{\link[refund]{fpca.sc}},  194 + #' @seealso \code{\link[funData]{funData}},  195 195 #' \code{\link{fpcaBasis}}, \code{\link{univDecomp}} 196 196 #'  197 197 #' @export PACE

Showing 5 files with coverage changes found.

Changes in R/univDecomp.R
-14
+14
Changes in R/univariateExpansions.R
-8
+8
Changes in src/dct3D.c
-21
Changes in src/MFPCA-init.c
-1
Changes in src/dct2D.c
-18

### Show failed CI and contexual commits c 12 Commits

Contextual
Contextual
Contextual
Contextual
Contextual
Contextual
Contextual
Hiding 8 contexual commits
Contextual
Contextual
Files Coverage
R -2.25% 91.66%
src 100.00%
Project Totals (12 files) 91.71%