R/RcppExports.R

In susanathey/MCPanel: Matrix Completion algorithms for Causal Panel Data Models

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' This function computes the minimum value of lambda_L which causes L to be zero. 
#' User can get the output of this function and fit the low-rank model with her desired value of lambda_L.
#' 
#' @param M Matrix of observed entries. The input should be N (number of units) by T (number of time periods).
#' @param mask Binary mask with the same shape as M containing observed entries.
#' @param to_estimate_u Optional boolean input for wheter estimating fixed unit effects (row means of M) or not. Default is 1.
#' @param to_estimate_u Optional boolean input for wheter estimating fixed time effects (column means of M) or not. Default is 1.
#' @param niter Optional parameter on the number of iterations taken in the algorithm for each fixed value of lambda_L. The default value is 1000 and it is sufficiently large as the algorithm is using warm-start strategy.
#' @param rel_tol Optional parameter on the stopping rule. Once the relative improve in objective value drops below rel_tol, execution is halted. Default value is 1e-5. 
#' @return The minimum value of lambda_L causing L to be zero.
#' @examples
#' mcnnm_lam_range(M = replicate(5,rnorm(5)), mask = matrix(rbinom(5*5,1,0.8),5,5))
mcnnm_lam_range <- function(M, mask, to_estimate_u = 1L, to_estimate_v = 1L, niter = 1000L, rel_tol = 1e-5) {
    .Call('_MCPanel_mcnnm_lam_range', PACKAGE = 'MCPanel', M, mask, to_estimate_u, to_estimate_v, niter, rel_tol)
}

#' This function trains all models for a given vector of lambda_L. Each model contains L, u, v, and lambda_L.

#' @param num_lam_L Optional parameter on the number of lambda_Ls to consider for learning. The default number is 100 and lambda_L values are from minimum number which makes L zero to 1e-3 times this minimum number.
#' @param lambda_L Optional numeric vector containing all lambda_L values that user want to train model on sorted decreasingly (important for warm-start). By default this is empty (user need not to provide this) and num_lam_L and the rule explained above is used. However, once this vector is passed by user manually, num_lam_L argument will not be used
#' @param is_quiet Optional boolean input which indicates whether to print the status of learning and convergence results for Cyclic Coordinate Descent algorithm or not. The default value is 1 (no output is printed).
#' @inheritParams mcnnm_lam_range
#' @return The list of all models trained with the given vector of lambda_Ls.
#' @examples
#' mcnnm(M = replicate(5,rnorm(5)), mask = matrix(rbinom(5*5,1,0.8),5,5), lambda_L = c(10,5,1,0.5,0.1,0.05))
mcnnm <- function(M, mask, num_lam_L = 100L, lambda_L = as.numeric( c()), to_estimate_u = 1L, to_estimate_v = 1L, niter = 1000L, rel_tol = 1e-5, is_quiet = 1L) {
    .Call('_MCPanel_mcnnm', PACKAGE = 'MCPanel', M, mask, num_lam_L, lambda_L, to_estimate_u, to_estimate_v, niter, rel_tol, is_quiet)
}

#' This function trains a model for a specified value of lambda_L. The result contains L, u, v, and lambda_L. 
#' The only difference with mcnnm is that this function trains only for a specified value of lambda_L.

#' @param lambda_L Required parameter for fitting the model as this function computes the result for a specified value of lambda_L. 
#' @param is_quiet Optional boolean input which indicates whether to print the status of learning and convergence results for Cyclic Coordinate Descent algorithm or not. The default value is 1 (no output is printed).
#' @inheritParams mcnnm_lam_range
#' @return The fitted model for the given value of lambda_L.
#' @examples
#' mcnnm_fit(M = replicate(5,rnorm(5)), mask = matrix(rbinom(5*5,1,0.8),5,5), lambda_L = 0.5)
#' @seealso \code{\link{mcnnm}}
mcnnm_fit <- function(M, mask, lambda_L, to_estimate_u = 1L, to_estimate_v = 1L, niter = 1000L, rel_tol = 1e-5, is_quiet = 1L) {
    .Call('_MCPanel_mcnnm_fit', PACKAGE = 'MCPanel', M, mask, lambda_L, to_estimate_u, to_estimate_v, niter, rel_tol, is_quiet)
}


#' This function computes the best model fitted to the data. Best value of lambda_L is chosen via cross-validation using all observed entries.
#' It creates some folds, divides the observed entry to training and validation on each fold, computes the best model on training sets and finds root mean squared error on validation sets.
#' Finally, it chooses the model which gives the smallest average RMSE.
#' 
#' @param num_lam_L Optional parameter on the number of lambda_Ls to consider for learning. The default number is 100 and lambda_L values are from minimum number which makes L zero to 1e-3 times this minimum number.
#' @param num_folds Optional parameter indicating the number of cross-validation folds. Default value is 5. For larger size problems we recommend decreasing this number for a faster cross-validation.
#' @param cv_ratio Optional parameter indicating what percentage of observed entries to be used for training. 1-cv_ratio will be dedicated to validation set. For each fold these two sets are chosen randomly. Default value is 80/20 for training/validation.
#' @param is_quiet Optional boolean input which indicates whether to print the status of learning and convergence results for Cyclic Coordinate Descent algorithm or not. The default value is 1 (no output is printed).
#' @inheritParams mcnnm_lam_range
#' @return The best model fitted using lambda_L chosen via cross-validation. The final model is fitted to all observed entries (not only training set). The output also includes the vector of average root mean squared error for different values of lambda_L.
#' @examples
#' mcnnm_cv(M = replicate(5,rnorm(5)), mask = matrix(rbinom(5*5,1,0.8),5,5))
mcnnm_cv <- function(M, mask, to_estimate_u = 1L, to_estimate_v = 1L, num_lam_L = 100L, niter = 400L, rel_tol = 1e-5, cv_ratio = 0.8, num_folds = 5L, is_quiet = 1L) {
  .Call('_MCPanel_mcnnm_cv', PACKAGE = 'MCPanel', M, mask, to_estimate_u, to_estimate_v, num_lam_L, niter, rel_tol, cv_ratio, num_folds, is_quiet)
}

#' This function computes the minimum value of lambda_L and lambda_H which causes L and H to be zero. 
#' User can get the output of this function and fit the low-rank matrix L, and the sparse matrix H, for her desired values of lambda_L and lambda_H.

#' @param X Matrix containing unit-related covariates. The number of rows of X should match with the number of units (number of rows of M). If unit-related covariates do not exist X = matrix(0L,0,0) should be used as input.
#' @param Z Matrix containing time-related covariates. The number of rows of Z should match with the number of time periods (number of columns in M). If time-related covariates do not exist use Z = matrix(0L,0,0)
#' @param to_add_ID Optional boolean parameter indicating whether identity matrices are concatenated with X and Z in the model X * H * Z'. The default value is true (identity matrices are concatenated) and the model becomes X*H_X + X*H_{XZ}*Z^T+ H_Z Z^T (the rest of matrix in H forced to zero).
#' @param to_normalize Optional boolean parameter indicating whether to normalize covariates or not (columns of X and Z). The default value is 1. If this value is set to 0, the result would be sensitive to scales in covariates.
#' @inheritParams mcnnm_lam_range
#' @return The minimum value of lambda_L and lambda_H which makes L and H equal to zero. This function is helpful when user wants to manually choose (lambda_L, lambda_H) pair.
#' @examples 
#' mcnnm_wc_lam_range(M = replicate(5,rnorm(5)), X = replicate(3, rnorm(5)), Z = matrix(0L, 0, 0),  mask = matrix(rbinom(5*5,1,0.8),5,5))
#' @seealso \code{\link{mcnnm_lam_range}}
mcnnm_wc_lam_range <- function(M, X, Z, mask, to_normalize = 1L, to_estimate_u = 1L, to_estimate_v = 1L, to_add_ID = 1L, niter = 1000L, rel_tol = 1e-5) {
  .Call('_MCPanel_mcnnm_wc_lam_range', PACKAGE = 'MCPanel', M, X, Z, mask, to_normalize, to_estimate_u, to_estimate_v, to_add_ID, niter, rel_tol)
}


#' This function trains all models for given vectors of lambda_L and lambda_H. Each model contains L, H, u, v, lambda_H, and lambda_L.

#' @param is_quiet Optional boolean input which indicates whether to print the status of learning and convergence results for Cyclic Coordinate Descent algorithm or not. The default value is 1 (no output is printed).
#' @param num_lam_L Optional parameter on the number of lambda_Ls to consider for learning. The default number is 30 and lambda_L values are from minimum number which makes L zero to 1e-3 times this minimum number. 
#' @param num_lam_H Optional parameter on the number of lambda_Hs to consider for learning. The default number is 30 and lambda_H values are from minimum number which makes H zero to 1e-3 times this minimum number.
#' @param lambda_L Optional numeric vector containing all lambda_L values that user want to train model on sorted decreasingly (important for warm-start). By default this is empty (user need not to provide this) and num_lam_L and the rule explained above is used. However, once this vector is passed by user manually, num_lam_L argument will not be used.
#' @param lambda_H Optional numeric vector containing all lambda_H values that user want to train model on sorted decreasingly (important for warm-start). By default this is empty (user need not to provide this) and num_lam_H and the rule explained above is used. However, once this vector is passed by user manually, num_lam_H argument will not be used.
#' @inheritParams mcnnm_wc_lam_range
#' @return The list of all models trained with the given vector of lambda_Ls and lambda_Hs.
#' @examples 
#' mcnnm_wc(M = replicate(5,rnorm(5)), X = replicate(3, rnorm(5)), Z = matrix(0L, 0, 0),  mask = matrix(rbinom(5*5,1,0.8),5,5), lambda_L=c(5,1,0.5,0.1), lambda_H=c(5,1,0.5,0.1))
#' @seealso \code{\link{mcnnm}}
mcnnm_wc <- function(M, X, Z, mask, num_lam_L = 30L, num_lam_H = 30L, lambda_L = as.numeric( c()), lambda_H = as.numeric( c()), to_normalize = 1L, to_estimate_u = 1L, to_estimate_v = 1L, to_add_ID = 1L, niter = 100L, rel_tol = 1e-5, is_quiet = 1L) {
    .Call('_MCPanel_mcnnm_wc', PACKAGE = 'MCPanel', M, X, Z, mask, num_lam_L, num_lam_H, lambda_L, lambda_H, to_normalize, to_estimate_u, to_estimate_v, to_add_ID, niter, rel_tol, is_quiet)
}

#' This function trains a model for specified values of lambda_L and lambda_H. The result contains L, H, u, v, lambda_L, and lambda_H. 
#' The only difference with mcnnm_wc is that this function trains only for specified pair of values (lambda_L, lambda_H).

#' @param is_quiet Optional boolean input which indicates whether to print the status of learning and convergence results for Cyclic Coordinate Descent algorithm or not. The default value is 1 (no output is printed).
#' @param lambda_L Required parameter for fitting the model as this function computes the result for a specified value of lambda_L. 
#' @param lambda_H Required parameter for fitting the model as this function computes the result for a specified value of lambda_H. 
#' @inheritParams mcnnm_wc_lam_range
#' @return The fitted model for the given value of lambda_L and lambda_H. The result contains L, H, u, v, lambda_L, and lambda_H.
#' @examples
#' mcnnm_wc_fit(M = replicate(5,rnorm(5)), X = replicate(3, rnorm(5)), Z = matrix(0L, 0, 0),  mask = matrix(rbinom(5*5,1,0.8),5,5), lambda_L=0.1, lambda_H=0.1)
#' @seealso \code{\link{mcnnm_fit}}, \code{\link{mcnnm_wc}}
mcnnm_wc_fit <- function(M, X, Z, mask, lambda_L, lambda_H, to_normalize = 1L, to_estimate_u = 1L, to_estimate_v = 1L, to_add_ID = 1L, niter = 100L, rel_tol = 1e-5, is_quiet = 1L) {
    .Call('_MCPanel_mcnnm_wc_fit', PACKAGE = 'MCPanel', M, X, Z, mask, lambda_L, lambda_H, to_normalize, to_estimate_u, to_estimate_v, to_add_ID, niter, rel_tol, is_quiet)
}

#' This function computes the best model fitted to the data. Best values of lambda_L and lambda_H are chosen via cross-validation using all observed entries.
#' It creates some folds, divides the observed entry to training and validation on each fold, computes the best model on training sets and finds root mean squared error on validation sets.
#' Finally, it chooses the model which gives the smallest average RMSE.

#' @param num_lam_L Optional parameter on the number of lambda_Ls to consider for learning. The default number is 30 and lambda_L values are from minimum number which makes L zero to 1e-3 times this minimum number.
#' @param num_lam_H Optional parameter on the number of lambda_Hs to consider for learning. The default number is 30 and lambda_H values are from minimum number which makes H zero to 1e-3 times this minimum number.
#' @param is_quiet Optional boolean input which indicates whether to print the status of learning and convergence results for Cyclic Coordinate Descent algorithm or not. The default value is 1 (no output is printed).
#' @param num_folds Optional parameter indicating the number of cross-validation folds. Default value is 3. For larger size problems we recommend decreasing this number for a faster cross-validation.
#' @param cv_ratio Optional parameter indicating what percentage of observed entries to be used for training. 1-cv_ratio will be dedicated to validation set. For each fold these two sets are chosen randomly. Default value is 80/20 for training/validation.
#' @inheritParams mcnnm_wc_lam_range
#' @return The best model fitted using lambda_L and lambda_H chosen via cross-validation using all observed entries (not only training set). The output also includes the matrix of average root mean squared error for different values of lambda_L and lambda_H.
#' examples
#' mcnnm_wc_cv(M = replicate(5,rnorm(5)), X = replicate(3, rnorm(5)), Z = matrix(0L, 0, 0),  mask = matrix(rbinom(5*5,1,0.8),5,5))
#' @seealso \code{\link{mcnnm_cv}}
mcnnm_wc_cv <- function(M, X, Z, mask, to_normalize = 1L, to_estimate_u = 1L, to_estimate_v = 1L, to_add_ID = 1L, num_lam_L = 30L, num_lam_H = 30L, niter = 100L, rel_tol = 1e-5, cv_ratio = 0.8, num_folds = 1L, is_quiet = 1L) {
    .Call('_MCPanel_mcnnm_wc_cv', PACKAGE = 'MCPanel', M, X, Z, mask, to_normalize, to_estimate_u, to_estimate_v, to_add_ID, num_lam_L, num_lam_H, niter, rel_tol, cv_ratio, num_folds, is_quiet)
}