R/zz_arguments.R
In M-E-Rademaker/cSEM: Composite-Based Structural Equation Modeling
Defines functions
handleArgs
args_default
args_assess_dotdotdot
Documented in
args_assess_dotdotdot
args_default
handleArgs
#' cSEMArguments
#'
#' An alphabetical list of all arguments used by functions of the `cSEM` package
#' including their description and defaults.
#' Mainly used for internal purposes (parameter inheritance). To list all arguments
#' and their defaults, use [args_default()]. To list all arguments and
#' their possible choices, use `args_default(.choices = TRUE)`.
#'
#' @param .alpha An integer or a numeric vector of significance levels.
#' Defaults to `0.05`.
#' @param .absolute Logical. Should the absolute HTMT values be returned?
#' Defaults to `TRUE` .
#' @param .approach_gcca Character string. The Kettenring approach to use for GCCA. One of
#' "*SUMCORR*", "*MAXVAR*", "*SSQCORR*", "*MINVAR*" or "*GENVAR*". Defaults to
#' "*SUMCORR*".
#' @param .approach_2ndorder Character string. Approach used for models containing
#' second-order constructs. One of: "*2stage*", or "*mixed*". Defaults to "*2stage*".
#' @param .approach_alpha_adjust Character string. Approach used to adjust the
#' significance level to accommodate multiple testing.
#' One of "*none*" or "*bonferroni*". Defaults to "*none*".
#' @param .approach_cor_robust Character string. Approach used to obtain a robust
#' indicator correlation matrix. One of: "*none*" in which case the standard
#' Bravais-Pearson correlation is used,
#' "*spearman*" for the Spearman rank correlation, or
#' "*mcd*" via \code{\link[MASS:cov.rob]{MASS::cov.rob()}} for a robust correlation matrix.
#' Defaults to "*none*". Note that many postestimation procedures (such as
#' [testOMF()] or [fit()] implicitly assume a continuous
#' indicator correlation matrix (e.g. Bravais-Pearson correlation matrix).
#' Only use if you know what you are doing.
#' @param .approach_mgd Character string or a vector of character strings.
#' Approach used for the multi-group comparison. One of: "*all*", "*Klesel*", "*Chin*",
#' "*Sarstedt*", "*Keil*, "*Nitzl*", "*Henseler*", "*CI_para*", or "*CI_overlap*".
#' Default to "*all*" in which case all approaches are computed (if possible).
#' @param .approach_nl Character string. Approach used to estimate nonlinear
#' structural relationships. One of: "*sequential*" or "*replace*".
#' Defaults to "*sequential*".
#' @param .approach_predict Character string. Which approach should be used to
#' predictions? One of "*earliest*" and "*direct*". If "*earliest*" predictions
#' for indicators associated to endogenous constructs are performed using only
#' indicators associated to exogenous constructs. If "*direct*", predictions for
#' indicators associated to endogenous constructs are based on indicators associated
#' to their direct antecedents. Defaults to "*earliest*".
#' @param .approach_p_adjust Character string or a vector of character strings.
#' Approach used to adjust the p-value for multiple testing.
#' See the `methods` argument of \code{\link[stats:p.adjust]{stats::p.adjust()}} for a list of choices and
#' their description. Defaults to "*none*".
#' @param .approach_paths Character string. Approach used to estimate the
#' structural coefficients. One of: "*OLS*" or "*2SLS*". If "*2SLS*", instruments
#' need to be supplied to `.instruments`. Defaults to "*OLS*".
#' @param .approach_score_benchmark Character string. How should the aggregation
#' of the estimates of the truncated normal distribution be done for the
#' benchmark predictions? Ignored if not OrdPLS or OrdPLSc is used to obtain benchmark predictions.
#' One of "*mean*", "*median*", "*mode*" or "*round*".
#' If "*round*", the benchmark predictions are obtained using the traditional prediction
#' algorithm for PLS-PM which are rounded for categorical indicators.
#' If "*mean*", the mean of the estimated endogenous indicators is calculated.
#' If "*median*", the mean of the estimated endogenous indicators is calculated.
#' If "*mode*", the maximum empirical density on the intervals defined by the thresholds
#' is used.
#' If `.treat_as_continuous = TRUE` or if all indicators are on a continuous scale,
#' `.approach_score_benchmark` is ignored. Defaults to "*round*".
#' @param .approach_score_target Character string. How should the aggregation of the estimates of
#' the truncated normal distribution for the predictions using OrdPLS/OrdPLSc be done?
#' One of "*mean*", "*median*" or "*mode*".
#' If "*mean*", the mean of the estimated endogenous indicators is calculated.
#' If "*median*", the mean of the estimated endogenous indicators is calculated.
#' If "*mode*", the maximum empirical density on the intervals defined by the thresholds
#' is used. Defaults to "*mean*".
#' @param .approach_weights Character string. Approach used to
#' obtain composite weights. One of: "*PLS-PM*", "*SUMCORR*", "*MAXVAR*",
#' "*SSQCORR*", "*MINVAR*", "*GENVAR*", "*GSCA*", "*PCA*", "*unit*", "*bartlett*",
#' or "*regression*". Defaults to "*PLS-PM*".
#' @param .args_used A list of function argument names whose value was modified
#' by the user.
#'
#' @param .attrbutes Character string. Variables used as attributes in IPMA.
#' @param .benchmark Character string. The procedure to obtain benchmark predictions.
#' One of "*lm*", "*unit*", "*PLS-PM*", "*GSCA*", "*PCA*", "*MAXVAR*", or "*NA*".
#' Default to "*lm*".
#' @param .bias_corrected Logical. Should the standard and the tStat
#' confidence interval be bias-corrected using the bootstrapped bias estimate?
#' If `TRUE` the confidence interval for some estimated parameter `theta`
#' is centered at `2*theta - theta*_hat`,
#' where `theta*_hat` is the average over all `.R` bootstrap estimates of `theta`.
#' Defaults to `TRUE`
#' @param .by_equation Should the criteria be computed for each structural model
#' equation separately? Defaults to `TRUE`.
#' @param .C A (J x J) composite variance-covariance matrix.
#' @param .check_errors Logical. Should the model to parse be checked for correctness
#' in a sense that all necessary components to estimate the model are given?
#' Defaults to `TRUE`.
#' @param .choices Logical. Should candidate values for the arguments be returned?
#' Defaults to `FALSE`.
#' @param .ci A vector of character strings naming the confidence interval to compute.
#' For possible choices see [infer()].
#' @param .ci_colnames Internal argument used by several print helper functions.
#' @param .closed_form_ci Logical. Should a closed-form confidence interval be computed?
#' Defaults to `FALSE`.
#' @param .conv_criterion Character string. The criterion to use for the convergence check.
#' One of: "*diff_absolute*", "*diff_squared*", or "*diff_relative*". Defaults
#' to "*diff_absolute*".
#' @param .csem_model A (possibly incomplete) [cSEMModel]-list.
#' @param .csem_resample A list resulting from a call to [resamplecSEMResults()].
#' @param .cv_folds Integer. The number of cross-validation folds to use. Setting
#' `.cv_folds` to `N` (the number of observations) produces
#' leave-one-out cross-validation samples. Defaults to `10`.
#' @param .data A `data.frame` or a `matrix` of standardized or unstandardized
#' data (indicators/items/manifest variables). Possible column types or classes
#' of the data provided are: "`logical`", "`numeric`" ("`double`" or "`integer`"),
#' "`factor`" ("`ordered`" and/or "`unordered`"), "`character`" (converted to factor),
#' or a mix of several types.
#' @param .dependent Character string. The name of the dependent variable.
#' @param .disattenuate Logical. Should composite/proxy correlations
#' be disattenuated to yield consistent loadings and path estimates if at least
#' one of the construct is modeled as a common factor? Defaults to `TRUE`.
#' @param .dist Character string. The distribution to use for the critical value.
#' One of *"t"* for Student's t-distribution or *"z"* for the standard normal distribution.
#' Defaults to *"z"*.
#' @param .distance Character string. A distance measure. One of: "*geodesic*"
#' or "*squared_euclidean*". Defaults to "*geodesic*".
#' @param .df Character string. The method for obtaining the degrees of freedom.
#' Choices are "*type1*" and "*type2*". Defaults to "*type1*" .
#' @param .dominant_indicators A character vector of `"construct_name" = "indicator_name"` pairs,
#' where `"indicator_name"` is a character string giving the name of the dominant indicator
#' and `"construct_name"` a character string of the corresponding construct name.
#' Dominant indicators may be specified for a subset of the constructs.
#' Default to `NULL`.
#' @param .E A (J x J) matrix of inner weights.
#' @param .effect Internal argument used by helper printEffects().
#' @param .estimate_structural Logical. Should the structural coefficients
#' be estimated? Defaults to `TRUE`.
#' @param .eval_plan Character string. The evaluation plan to use. One of
#' "*sequential*", "*multicore*", or "*multisession*". In the two latter cases
#' all available cores will be used. Defaults to "*sequential*".
#' @param .filename Character string. The file name.
#' @param .first_resample A list containing the `.R` resamples based on the original
#' data obtained by resamplecSEMResults().
#' @param .fit_measures Logical. (EXPERIMENTAL) Should additional fit measures
#' be included? Defaults to `FALSE`.
#' @param .force Logical. Should .object be resampled even if it contains resamples
#' already?. Defaults to `FALSE`.
#' @param .full_output Logical. Should the full output of summarize be printed.
#' Defaults to `TRUE`.
#' @param .graph_attrs Character string. Additional attributes that should be passed
#' to the DiagrammeR syntax, e.g., c("rankdir=LR", "ranksep=1.0"). Defaults to *c("rankdir=LR")*.
#' @param .H The (N x J) matrix of construct scores.
#' @param .handle_inadmissibles Character string. How should inadmissible results
#' be treated? One of "*drop*", "*ignore*", or "*replace*". If "*drop*", all
#' replications/resamples yielding an inadmissible result will be dropped
#' (i.e. the number of results returned will potentially be less than `.R`).
#' For "*ignore*" all results are returned even if all or some of the replications
#' yielded inadmissible results (i.e. number of results returned is equal to `.R`).
#' For "*replace*" resampling continues until there are exactly `.R` admissible solutions.
#' Depending on the frequency of inadmissible solutions this may significantly increase
#' computing time. Defaults to "*drop*".
#' @param .id Character string or integer. A character string giving the name or
#' an integer of the position of the column of `.data` whose levels are used
#' to split `.data` into groups. Defaults to `NULL`.
#' @param .inference Logical. Should critical values be computed? Defaults to `FALSE`.
#' @param .independent Character string. The name of the independent variable.
#' @param .instruments A named list of vectors of instruments. The names
#' of the list elements are the names of the dependent (LHS) constructs of the structural
#' equation whose explanatory variables are endogenous. The vectors
#' contain the names of the instruments corresponding to each equation. Note
#' that exogenous variables of a given equation **must** be supplied as
#' instruments for themselves. Defaults to `NULL`.
#' @param .iter_max Integer. The maximum number of iterations allowed.
#' If `iter_max = 1` and `.approach_weights = "PLS-PM"` one-step weights are returned.
#' If the algorithm exceeds the specified number, weights of iteration step
#' `.iter_max - 1` will be returned with a warning. Defaults to `100`.
#' @param .level Character. Used in `plot.cSEMIPMA` to indicate whether IPMA should be done
#' for constructs or indicators.
#' @param .matrix1 A `matrix` to compare.
#' @param .matrix2 A `matrix` to compare.
#' @param .matrices A list of at least two matrices.
#' @param .metrics Character string or a vector of character strings.
#' Which prediction metrics should be displayed? One of: "*MAE*", "*RMSE*", "*Q2*",
#' "*MER*", "*MAPE*, "*MSE2*", "*U1*", "*U2*", "*UM*", "*UR*", or "*UD*".
#' Default to c("*MAE*", "*RMSE*", "*Q2*").
#' @param .model A model in [lavaan model syntax][lavaan::model.syntax]
#' or a [cSEMModel] list.
#' @param .moderator Character string. The name of the moderator variable.
#' @param .modes A vector giving the mode for each construct in the form `"name" = "mode"`.
#' Only used internally.
#' @param .ms_criterion Character string. Either a single character string or a vector
#' of character strings naming the model selection criterion to compute.
#' Defaults to `"all"`.
#' @param .n Integer. The number of observations of the original data.
#' @param .n_steps Integer. A value giving the number of steps (the spotlights, i.e.,
#' values of .moderator in surface analysis or floodlight analysis)
#' between the minimum and maximum value of the moderator. Defaults to `100`.
#' @param .normality Logical. Should joint normality of
#' \eqn{[\eta_{1:p}; \zeta; \epsilon]}{[\eta_(1:p); \zeta; \epsilon]}
#' be assumed in the nonlinear model? See \insertCite{Dijkstra2014}{cSEM} for details.
#' Defaults to `FALSE`. Ignored if the model is not nonlinear.
#' @param .nr_comparisons Integer. The number of comparisons. Defaults to `NULL`.
#' @param .null_model Logical. Should the degrees of freedom for the null model
#' be computed? Defaults to `FALSE`.
#' @param .object An R object of class [cSEMResults] resulting from a call to [csem()].
#' @param .object1 An R object of class [cSEMResults] resulting from a call to [csem()].
#' @param .object2 An R object of class [cSEMResults] resulting from a call to [csem()].
#' @param .only_common_factors Logical. Should only concepts modeled as common
#' factors be included when calculating one of the following quality criteria:
#' AVE, the Fornell-Larcker criterion, HTMT, and all reliability estimates.
#' Defaults to `TRUE`.
#' @param .only_structural Should the the log-likelihood be based on the
#' structural model? Ignored if `.by_equation == TRUE`. Defaults to `TRUE`.
#' @param .original_arguments The list of arguments used within [csem()].
#' @param .output_type Character string. The type of output to return. One of
#' "*complete*" or "*structured*". See the Value section for details. Defaults to
#' "*complete*".
#' @param .P A (J x J) construct variance-covariance matrix (possibly disattenuated).
#' @param .parameters_to_compare A model in [lavaan model syntax][lavaan::model.syntax] indicating which
#' parameters (i.e, path (`~`), loadings (`=~`), weights (`<~`), or correlations (`~~`)) should be
#' compared across groups. Defaults to `NULL` in which case all weights, loadings and
#' path coefficients of the originally specified model are compared.
#' @param .path Character string. Path of the directory to save the file to. Defaults
#' to `NULL`.
#' @param .path_coefficients List. A list that contains the resampled and the original
#' path coefficient estimates. Typically a part of a `cSEMResults_resampled` object.
#' Defaults to `NULL`.
#' @param .PLS_approach_cf Character string. Approach used to obtain the correction
#' factors for PLSc. One of: "*dist_squared_euclid*", "*dist_euclid_weighted*",
#' "*fisher_transformed*", "*mean_arithmetic*", "*mean_geometric*", "*mean_harmonic*",
#' "*geo_of_harmonic*". Defaults to "*dist_squared_euclid*".
#' Ignored if `.disattenuate = FALSE` or if `.approach_weights` is not PLS-PM.
#' @param .plot_correlations Character string. Specify which correlations should be plotted, i.e.,
#' between the exogenous constructs (`exo`), between the exogenous constructs and the indicators (`all`),
#' or not at all (`none`). Defaults to `exo`.
#' @param .plot_labels Logical. Whether to display edge labels. Defaults to TRUE.
#' @param .plot_package Character string. Indicates which packages should be used for plotting.
#' @param .plot_significances Logical. Should p-values in the form of stars be plotted? Defaults to `TRUE`.
#' @param .plot_structural_model_only Logical. Should only the structural model,
#' i.e., the constructs and their relationships be plotted? Defaults to `FALSE`.
#' @param .plot_type Character string. Indicates the type of plot that is produced.
#' @param .PLS_ignore_structural_model Logical. Should the structural model be ignored
#' when calculating the inner weights of the PLS-PM algorithm? Defaults to `FALSE`.
#' Ignored if `.approach_weights` is not PLS-PM.
#' @param .PLS_modes Either a named list specifying the mode that should be used for
#' each construct in the form `"construct_name" = mode`, a single character
#' string giving the mode that should be used for all constructs, or `NULL`.
#' Possible choices for `mode` are: "*modeA*", "*modeB*", "*modeBNNLS*",
#' "*unit*", "*PCA*", a single integer or
#' a vector of fixed weights of the same length as there are indicators for the
#' construct given by `"construct_name"`. If only a single number is provided this is identical to
#' using unit weights, as weights are rescaled such that the related composite
#' has unit variance. Defaults to `NULL`.
#' If `NULL` the appropriate mode according to the type
#' of construct used is chosen. Ignored if `.approach_weight` is not PLS-PM.
#' @param .PLS_weight_scheme_inner Character string. The inner weighting scheme
#' used by PLS-PM. One of: "*centroid*", "*factorial*", or "*path*".
#' Defaults to "*path*". Ignored if `.approach_weight` is not PLS-PM.
#' @param .probs A vector of probabilities.
#' @param .postestimation_object An object resulting from a call to one of cSEM's
#' postestimation functions (e.g. [summarize()]).
#' @param .quality_criterion Character string. A single character string or a
#' vector of character strings naming the quality criterion to compute. See
#' the Details section for a list of possible candidates.
#' Defaults to "*all*" in which case all possible quality criteria are computed.
#' @param .quantity Character string. Which statistic should be returned?
#' One of "*all*", "*mean*", "*sd*", "*bias*", "*CI_standard_z*", "*CI_standard_t*",
#' "*CI_percentile*", "*CI_basic*", "*CI_bc*", "*CI_bca*", "*CI_t_interval*"
#' Defaults to "*all*" in which case all quantities that do not require
#' additional resampling are returned, i.e., all quantities but "*CI_bca*", "*CI_t_interval*".
#' @param .Q A vector of composite-construct correlations with element names equal to
#' the names of the J construct names used in the measurement model. Note
#' Q^2 is also called the reliability coefficient.
#' @param .reliabilities A character vector of `"name" = value` pairs,
#' where `value` is a number between 0 and 1 and `"name"` a character string
#' of the corresponding construct name, or `NULL`. Reliabilities
#' may be given for a subset of the constructs. Defaults to `NULL` in which case
#' reliabilities are estimated by `csem()`. Currently, only supported for
#' `.approach_weights = "PLS-PM"`.
#' @param .resample_method Character string. The resampling method to use. One of:
#' "*none*", "*bootstrap*" or "*jackknife*". Defaults to "*none*".
#' @param .resample_method2 Character string. The resampling method to use when resampling
#' from a resample. One of: "*none*", "*bootstrap*" or "*jackknife*". For
#' "*bootstrap*" the number of draws is provided via `.R2`. Currently,
#' resampling from each resample is only required for the studentized confidence
#' interval ("*CI_t_interval*") computed by the [infer()] function. Defaults to "*none*".
#' @param `.resample_object` An R object of class `cSEMResults_resampled`
#' obtained from [resamplecSEMResults()] or by setting `.resample_method = "bootstrap"`
#' or `"jackknife"` when calling [csem()].
#' @param .resample_sarstedt A matrix containing the parameter estimates that
#' could potentially be compared and an id column indicating the group adherence
#' of each row.
#' @param .r Integer. The number of repetitions to use. Defaults to `1`.
#' @param .R Integer. The number of bootstrap replications. Defaults to `499`.
#' @param .R2 Integer. The number of bootstrap replications to use when
#' resampling from a resample. Defaults to `199`.
#' @param .R_bootstrap Integer. The number of bootstrap runs. Ignored if `.object`
#' contains resamples. Defaults to `499`
#' @param .R_permutation Integer. The number of permutations. Defaults to `499`
#' @param .S The (K x K) empirical indicator correlation matrix.
#' @param .saturated Logical. Should a saturated structural model be used?
#' Defaults to `FALSE`.
#' @param .second_resample A list containing `.R2` resamples for each of the `.R`
#' resamples of the first run.
#' @param .seed Integer or `NULL`. The random seed to use. Defaults to `NULL` in which
#' case an arbitrary seed is chosen. Note that the scope of the seed is limited
#' to the body of the function it is used in. Hence, the global seed will
#' not be altered!
#' @param .sign_change_option Character string. Which sign change option should
#' be used to handle flipping signs when resampling? One of "*none*","*individual*",
#' "*individual_reestimate*", "*construct_reestimate*". Defaults to "*none*".
#' @param .sim_points Integer. How many samples from the truncated normal distribution should
#' be simulated to estimate the exogenous construct scores? Defaults to "*100*".
#' @param .stage Character string. The stage the model is needed for.
#' One of "*first*" or "*second*". Defaults to "*first*".
#' @param .standardized Logical. Should standardized scores be returned? Defaults
#' to `TRUE`.
#' @param .starting_values A named list of vectors where the
#' list names are the construct names whose indicator weights the user
#' wishes to set. The vectors must be named vectors of `"indicator_name" = value`
#' pairs, where `value` is the (scaled or unscaled) starting weight. Defaults to `NULL`.
#' @param .steps_mod A numeric vector. Steps used for the moderator variable in calculating
#' the simple effects of an independent variable on the dependent variable.
#' Defaults to `NULL`.
#' @param .terms A vector of construct names to be classified.
#' @param .test_data A matrix of test data with the same column names as the
#' training data.
#' @param .testtype Character string. One of "*twosided*" (H1: The models do not
#' perform equally in predicting indicators belonging to endogenous constructs)"
#' and *onesided*" (H1: Model 1 performs better in predicting indicators belonging
#' @param .title Character string. Title of an object. Defaults to *""*.
#' @param .tolerance Double. The tolerance criterion for convergence.
#' Defaults to `1e-05`.
#' @param .treat_as_continuous Logical. Should the indicators for the benchmark predictions
#' be treated as continuous? If `TRUE` all indicators are treated as continuous and PLS-PM/PLSc is applied.
#' If `FALSE` OrdPLS/OrdPLSc is applied. Defaults to `TRUE`.
#' @param .type_gfi Character string. Which fitting function should the GFI be based
#' on? One of *"ML"* for the maximum likelihood fitting function, *"GLS"* for
#' the generalized least squares fitting function or *"ULS"* for the
#' unweighted least squares fitting function (same as the squared Euclidean distance).
#' Defaults to *"ML"*.
#' @param .type_ci Character string. Which confidence interval should be calculated?
#' For possible choices, see the `.quantity` argument of the [infer()] function.
#' Only used if `.approch_mgd` is one of "*CI_para*" or "*CI_overlap*". Ignored otherwise.
#' Defaults to "*CI_percentile*".
#' @param .type_htmt Character string indicating the type of HTMT that should be
#' calculated, i.e., the original HTMT ("*htmt*") or the HTMT2 ("*htmt2*").
#' Defaults to "*htmt*"
#' @param .type_vcv Character string. Which model-implied correlation
#' matrix should be calculated?
#' One of "*indicator*" or "*construct*". Defaults to "*indicator*".
#' @param .verbose Logical. Should information (e.g., progress bar) be printed
#' to the console? Defaults to `TRUE`.
#' @param .user_funs A function or a (named) list of functions to apply to every
#' resample. The functions must take `.object` as its first argument (e.g.,
#' `myFun <- function(.object, ...) {body-of-the-function}`).
#' Function output should preferably be a (named)
#' vector but matrices are also accepted. However, the output will be
#' vectorized (columnwise) in this case. See the examples section for details.
#' @param .value_independent Integer. Only required for floodlight analysis;
#' The value of the independent variable in case that it appears as a
#' higher-order term.
#' @param .values_moderator A numeric vector. The values of the moderator in a
#' the simple effects analysis. Typically these are difference from the mean (=0)
#' measured in standard deviations. Defaults to `c(-2, -1, 0, 1, 2)`.
#' @param .vcv_asymptotic Logical. Should the asymptotic variance-covariance matrix be used, i.e.,
#' VCV(b0) - VCV(b1)= VCV(b1-b0), or should VCV(b1-b0) be computed directly?
#' Defaults to `FALSE`.
#' @param .vector1 A vector of numeric values.
#' @param .vector2 A vector of numeric values.
#' @param .W A (J x K) matrix of weights.
#' @param .what Internal argument used by several print helper functions.
#' @param .W_new A (J x K) matrix of weights.
#' @param .W_old A (J x K) matrix of weights.
#' @param .weighted Logical. Should estimation be based on a score that uses
#' the weights of the weight approach used to obtain `.object`?. Defaults to `FALSE`.
#' @param .X A matrix of processed data (scaled, cleaned and ordered).
#' @param .X_cleaned A data.frame of processed data (cleaned and ordered). Note: `X_cleaned`
#' may not be scaled!
#'
#' @name csem_arguments
#' @aliases cSEMArguments
#' @keywords internal
NULL
#' Complete list of assess()'s ... arguments
#'
#' A complete alphabetical list of all possible arguments accepted by `assess()`'s `...`
#' (dotdotdot) argument.
#'
#' Most arguments supplied to the `...` argument of `assess()` are only
#' accepted by a subset of the functions called by `assess()`. The following
#' list shows which argument is passed to which function:
#' \describe{
#' \item{.absolute}{Accepted by/Passed down to: [calculateHTMT()]}
#' \item{.alpha}{Accepted by/Passed down to: [calculateRhoT()], [calculateHTMT()], [calculateCN()]}
#' \item{.ci}{Accepted by/Passed down to: [calculateHTMT()]}
#' \item{.closed_form_ci}{Accepted by/Passed down to: [calculateRhoT()]}
#' \item{.handle_inadmissibles}{Accepted by/Passed down to: [calculateHTMT()]}
#' \item{.inference}{Accepted by/Passed down to: [calculateHTMT]}
#' \item{.null_model}{Accepted by/Passed down to: [calculateDf()]}
#' \item{.R}{Accepted by/Passed down to: [calculateHTMT()]}
#' \item{.saturated}{Accepted by/Passed down to: [calculateSRMR()],
#' [calculateDG()], [calculateDL()], [calculateDML()]and subsequently [fit()].}
#' \item{.seed}{Accepted by/Passed down to: [calculateHTMT()]}
#' \item{.type_gfi}{Accepted by/Passed down to: [calculateGFI()]}
#' \item{.type_vcv}{Accepted by/Passed down to: [calculateSRMR()],
#' [calculateDG()], [calculateDL()], [calculateDML()] and subsequently [fit()].}
#' }
#' @usage NULL
#'
#' @inheritParams csem_arguments
#' @keywords internal
args_assess_dotdotdot <- function(
.absolute = TRUE,
.alpha = 0.05,
.ci = c("CI_standard_z", "CI_standard_t", "CI_percentile",
"CI_basic", "CI_bc", "CI_bca", "CI_t_interval"),
.closed_form_ci = FALSE,
.handle_inadmissibles= c("drop", "ignore", "replace"),
.inference = FALSE,
.null_model = FALSE,
.R = 499,
.saturated = FALSE,
.seed = NULL,
.type_gfi = c("ML", "GLS", "ULS"),
.type_vcv = "indicator"
) {NULL}
#' Show argument defaults or candidates
#'
#' Show all arguments used by package functions including default or candidate
#' values. For argument descriptions see: [csem_arguments].
#'
#' By default `args_default()`returns a list of default values by argument name.
#' If the list of accepted candidate values is required instead, use `.choices = TRUE`.
#'
#' @usage args_default(.choices = FALSE)
#'
#' @inheritParams csem_arguments
#'
#' @return A named list of argument names and defaults or accepted candidates.
#'
#' @seealso [handleArgs()], [csem_arguments], [csem()], [foreman()]
#'
#' @export
args_default <- function(.choices = FALSE) {
args <- list(
.alpha = 0.05,
.absolute = TRUE,
.approach_2ndorder = c("2stage", "mixed"),
.approach_alpha_adjust = c("none", "bonferroni"),
.approach_cor_robust = c("none", "mcd", "spearman"),
.approach_gcca = c("SUMCORR", "MAXVAR", "SSQCORR", "MINVAR", "GENVAR"),
.approach_mgd = c("all", "Klesel", "Chin", "Sarstedt", "Keil", "Nitzl",
"Henseler","CI_para","CI_overlap"),
.approach_nl = c("sequential", "replace"),
.approach_p_adjust = "none",
.approach_paths = c("OLS", "2SLS"),
.approach_predict = c("earliest", "direct"),
.approach_score_benchmark= c("mean", "median", "mode", "round"),
.approach_score_target = c("mean", "median", "mode"),
.approach_weights = c("PLS-PM", "SUMCORR", "MAXVAR", "SSQCORR", "MINVAR", "GENVAR",
"GSCA", "PCA", "unit", "bartlett", "regression"),
.arguments = NULL,
.attributes = NULL,
.benchmark = c("lm", "unit", "PLS-PM", "GSCA", "PCA", "MAXVAR","NA"),
.bias_corrected = TRUE,
.by_equation = TRUE,
.C = NULL,
.check_errors = TRUE,
.choices = FALSE,
.ci = c("CI_standard_z", "CI_standard_t", "CI_percentile",
"CI_basic", "CI_bc", "CI_bca", "CI_t_interval"),
.ci_colnames = NULL,
.closed_form_ci = FALSE,
.conv_criterion = c("diff_absolute", "diff_squared", "diff_relative"),
.csem_model = NULL,
.csem_resample = NULL,
.cv_folds = 10,
.data = NULL,
.dependent = NULL,
.disattenuate = TRUE,
.dist = c("z", "t"),
.distance = c("geodesic", "squared_euclidean"),
.df = c("type1", "type2"),
.dominant_indicators = NULL,
.E = NULL,
.effect = NULL,
.estimate_structural = TRUE,
.eval_plan = c("sequential", "multicore","multisession"),
.filename = NULL,
.fit_measures = FALSE,
.first_resample = NULL,
.force = FALSE,
.full_output = TRUE,
.graph_attrs = c("rankdir=LR"),
.handle_inadmissibles = c("drop", "ignore", "replace"),
.H = NULL,
.id = NULL,
.inference = FALSE,
.independent = NULL,
.instruments = NULL,
.iter_max = 100,
.listMatrices = NULL,
.level = c('construct',"indicator"),
.matrix1 = NULL,
.matrix2 = NULL,
.matrices = NULL,
.metrics = c("MAE", "RMSE", "Q2", "MER",
"MAPE", "MSE2", "U1", "U2" , "UM", "UR", "UD"),
.model = NULL,
.moderator = NULL,
.modes = NULL,
.ms_criterion = c("all", "aic", "aicc", "aicu", "bic", "fpe", "gm", "hq",
"hqc", "mallows_cp"),
.n_steps = 100,
.normality = FALSE,
.nr_comparisons = NULL,
.null_model = FALSE,
.object = NULL,
.only_common_factors = TRUE,
.output_type = c("complete", "structured"),
.P = NULL,
.parameters_to_compare = NULL,
.path = NULL,
.path_coefficients = NULL,
.plot_correlations = c("exo", "none", "all"),
.plot_labels = TRUE,
.plot_package = NULL,
.plot_significances = TRUE,
.plot_structural_model_only = FALSE,
.plot_type = NULL,
.probs = NULL,
.PLS_approach_cf = c("dist_squared_euclid", "dist_euclid_weighted",
"fisher_transformed", "mean_arithmetic",
"mean_geometric", "mean_harmonic",
"geo_of_harmonic"),
.PLS_ignore_structural_model = FALSE,
.PLS_modes = NULL,
.PLS_weight_scheme_inner = c("path", "centroid", "factorial"),
.postestimation_object = NULL,
.quality_criterion = c("all", "aic", "aicc", "aicu", "bic", "fpe", "gm", "hq",
"hqc", "mallows_cp", "ave",
"rho_C", "rho_C_mm", "rho_C_weighted",
"rho_C_weighted_mm", "dg", "dl", "dml", "df",
"effects", "f2", "fl_criterion", "chi_square", "chi_square_df",
"cfi", "cn", "gfi", "ifi", "nfi", "nnfi",
"reliability",
"rmsea", "rms_theta", "srmr",
"gof", "htmt", "htmt2", "r2", "r2_adj",
"rho_T", "rho_T_weighted", "vif",
"vifmodeB"),
.quantity = c("all", "mean", "sd", "bias", "CI_standard_z", "CI_standard_t",
"CI_percentile", "CI_basic", "CI_bc", "CI_bca", "CI_t_intervall"),
.Q = NULL,
.r = 1,
.R = 499,
.R2 = 199,
.R_bootstrap = 499,
.R_permutation = 499,
.reliabilities = NULL,
.resample_method = c("none", "bootstrap", "jackknife"),
.resample_method2 = c("none", "bootstrap", "jackknife"),
.resample_object = NULL,
.resample_sarstedt = NULL,
.S = NULL,
.saturated = FALSE,
.second_resample = NULL,
.seed = NULL,
.sign_change_option = c("none", "individual", "individual_reestimate",
"construct_reestimate"),
.sim_points = 100,
.stage = c("first", "second"),
.standardized = TRUE,
.starting_values = NULL,
.steps_mod = NULL,
.terms = NULL,
.test_data = NULL,
.title = "",
.tolerance = 1e-05,
.treat_as_continuous = TRUE,
.type_gfi = c("ML", "GLS", "ULS"),
.type_htmt = c("htmt", "htmt2"),
.type_vcv = c("indicator", "construct"),
.type_ci = c("CI_percentile","CI_standard_z","CI_standard_t",
"CI_basic","CI_bc", "CI_bca"),
.user_funs = NULL,
.value_independent = 0,
.values_moderator = c(-2,-1,0,1,2),
.vcv_asymptotic = c(FALSE, TRUE),
.verbose = TRUE,
.W = NULL,
.weighted = FALSE,
.what = NULL,
.x = NULL,
.X = NULL,
.X_cleaned = NULL,
.y = NULL,
.z = NULL
)
if(!.choices) {
args <- lapply(args, function(x) eval(x)[1])
}
args_sorted <- args[sort(names(args))]
return(args_sorted)
}
#' Internal: Handle arguments
#'
#' Internal helper function to handle arguments passed to any function within `cSEM`.
#'
#' @param .args_used A list of argument names and user picked values.
#'
#' @return The [args_default] list, with default values
#' changed to the values given by the user.
#' @keywords internal
handleArgs <- function(.args_used) {
args_default <- args_default()
args_default_names <- names(args_default)
args_used_names <- names(.args_used)
## Are all argument names used valid?
args_diff <- setdiff(args_used_names, args_default_names)
if (length(args_diff) > 0) {
stop("The following argument(s) are not known to cSEM: ",
paste0("`", args_diff, '`', collapse = ", "), "\n",
"Please type 'args_default()' to find all valid arguments and their defaults. Or check ?args_default.",
call. = FALSE)
}
## Are arguments valid
# Note: for now, I will only check if string arguments are valid. In the
# future we could refine and check if e.g. numeric values are within a reasonable
# range or larger than zero if required etc.
# choices_logical <- Filter(function(x) any(is.logical(x)), args_default(.choices = TRUE))
# choices_numeric <- Filter(function(x) any(is.numeric(x)), args_default(.choices = TRUE))
choices_character <- Filter(function(x) any(is.character(x)), args_default(.choices = TRUE))
character_args <- intersect(names(choices_character), args_used_names)
x <- Map(function(x, y) x %in% y,
x = .args_used[character_args],
y = choices_character[character_args]
)
lapply(seq_along(x), function(i) {
if(isFALSE(x[[i]])) {
n <- names(x[i])
a <- args_default(.choices = TRUE)[[n]]
stop(paste0("`", .args_used[n], "` is not a valid choice for ", "`",
names(.args_used[n]),"`.\n"),
"Choices are: ", paste0("`", a[-length(a)],"`", collapse = ", "),
" or " , paste0("`", a[length(a)], "`"), call. = FALSE)
}
})
## Replace all arguments that were changed or explicitly given and keep
# the default values for the others
for(i in args_used_names) {
args_default[i] <- .args_used[i]
}
return(args_default)
}
M-E-Rademaker/cSEM documentation built on March 2, 2025, 1:04 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Defines functions handleArgs args_default args_assess_dotdotdot
Documented in args_assess_dotdotdot args_default handleArgs
#' cSEMArguments
#'
#' An alphabetical list of all arguments used by functions of the `cSEM` package
#' including their description and defaults.
#' Mainly used for internal purposes (parameter inheritance). To list all arguments
#' and their defaults, use [args_default()]. To list all arguments and
#' their possible choices, use `args_default(.choices = TRUE)`.
#'
#' @param .alpha An integer or a numeric vector of significance levels.
#' Defaults to `0.05`.
#' @param .absolute Logical. Should the absolute HTMT values be returned?
#' Defaults to `TRUE` .
#' @param .approach_gcca Character string. The Kettenring approach to use for GCCA. One of
#' "*SUMCORR*", "*MAXVAR*", "*SSQCORR*", "*MINVAR*" or "*GENVAR*". Defaults to
#' "*SUMCORR*".
#' @param .approach_2ndorder Character string. Approach used for models containing
#' second-order constructs. One of: "*2stage*", or "*mixed*". Defaults to "*2stage*".
#' @param .approach_alpha_adjust Character string. Approach used to adjust the
#' significance level to accommodate multiple testing.
#' One of "*none*" or "*bonferroni*". Defaults to "*none*".
#' @param .approach_cor_robust Character string. Approach used to obtain a robust
#' indicator correlation matrix. One of: "*none*" in which case the standard
#' Bravais-Pearson correlation is used,
#' "*spearman*" for the Spearman rank correlation, or
#' "*mcd*" via \code{\link[MASS:cov.rob]{MASS::cov.rob()}} for a robust correlation matrix.
#' Defaults to "*none*". Note that many postestimation procedures (such as
#' [testOMF()] or [fit()] implicitly assume a continuous
#' indicator correlation matrix (e.g. Bravais-Pearson correlation matrix).
#' Only use if you know what you are doing.
#' @param .approach_mgd Character string or a vector of character strings.
#' Approach used for the multi-group comparison. One of: "*all*", "*Klesel*", "*Chin*",
#' "*Sarstedt*", "*Keil*, "*Nitzl*", "*Henseler*", "*CI_para*", or "*CI_overlap*".
#' Default to "*all*" in which case all approaches are computed (if possible).
#' @param .approach_nl Character string. Approach used to estimate nonlinear
#' structural relationships. One of: "*sequential*" or "*replace*".
#' Defaults to "*sequential*".
#' @param .approach_predict Character string. Which approach should be used to
#' predictions? One of "*earliest*" and "*direct*". If "*earliest*" predictions
#' for indicators associated to endogenous constructs are performed using only
#' indicators associated to exogenous constructs. If "*direct*", predictions for
#' indicators associated to endogenous constructs are based on indicators associated
#' to their direct antecedents. Defaults to "*earliest*".
#' @param .approach_p_adjust Character string or a vector of character strings.
#' Approach used to adjust the p-value for multiple testing.
#' See the `methods` argument of \code{\link[stats:p.adjust]{stats::p.adjust()}} for a list of choices and
#' their description. Defaults to "*none*".
#' @param .approach_paths Character string. Approach used to estimate the
#' structural coefficients. One of: "*OLS*" or "*2SLS*". If "*2SLS*", instruments
#' need to be supplied to `.instruments`. Defaults to "*OLS*".
#' @param .approach_score_benchmark Character string. How should the aggregation
#' of the estimates of the truncated normal distribution be done for the
#' benchmark predictions? Ignored if not OrdPLS or OrdPLSc is used to obtain benchmark predictions.
#' One of "*mean*", "*median*", "*mode*" or "*round*".
#' If "*round*", the benchmark predictions are obtained using the traditional prediction
#' algorithm for PLS-PM which are rounded for categorical indicators.
#' If "*mean*", the mean of the estimated endogenous indicators is calculated.
#' If "*median*", the mean of the estimated endogenous indicators is calculated.
#' If "*mode*", the maximum empirical density on the intervals defined by the thresholds
#' is used.
#' If `.treat_as_continuous = TRUE` or if all indicators are on a continuous scale,
#' `.approach_score_benchmark` is ignored. Defaults to "*round*".
#' @param .approach_score_target Character string. How should the aggregation of the estimates of
#' the truncated normal distribution for the predictions using OrdPLS/OrdPLSc be done?
#' One of "*mean*", "*median*" or "*mode*".
#' If "*mean*", the mean of the estimated endogenous indicators is calculated.
#' If "*median*", the mean of the estimated endogenous indicators is calculated.
#' If "*mode*", the maximum empirical density on the intervals defined by the thresholds
#' is used. Defaults to "*mean*".
#' @param .approach_weights Character string. Approach used to
#' obtain composite weights. One of: "*PLS-PM*", "*SUMCORR*", "*MAXVAR*",
#' "*SSQCORR*", "*MINVAR*", "*GENVAR*", "*GSCA*", "*PCA*", "*unit*", "*bartlett*",
#' or "*regression*". Defaults to "*PLS-PM*".
#' @param .args_used A list of function argument names whose value was modified
#' by the user.
#'
#' @param .attrbutes Character string. Variables used as attributes in IPMA.
#' @param .benchmark Character string. The procedure to obtain benchmark predictions.
#' One of "*lm*", "*unit*", "*PLS-PM*", "*GSCA*", "*PCA*", "*MAXVAR*", or "*NA*".
#' Default to "*lm*".
#' @param .bias_corrected Logical. Should the standard and the tStat
#' confidence interval be bias-corrected using the bootstrapped bias estimate?
#' If `TRUE` the confidence interval for some estimated parameter `theta`
#' is centered at `2*theta - theta*_hat`,
#' where `theta*_hat` is the average over all `.R` bootstrap estimates of `theta`.
#' Defaults to `TRUE`
#' @param .by_equation Should the criteria be computed for each structural model
#' equation separately? Defaults to `TRUE`.
#' @param .C A (J x J) composite variance-covariance matrix.
#' @param .check_errors Logical. Should the model to parse be checked for correctness
#' in a sense that all necessary components to estimate the model are given?
#' Defaults to `TRUE`.
#' @param .choices Logical. Should candidate values for the arguments be returned?
#' Defaults to `FALSE`.
#' @param .ci A vector of character strings naming the confidence interval to compute.
#' For possible choices see [infer()].
#' @param .ci_colnames Internal argument used by several print helper functions.
#' @param .closed_form_ci Logical. Should a closed-form confidence interval be computed?
#' Defaults to `FALSE`.
#' @param .conv_criterion Character string. The criterion to use for the convergence check.
#' One of: "*diff_absolute*", "*diff_squared*", or "*diff_relative*". Defaults
#' to "*diff_absolute*".
#' @param .csem_model A (possibly incomplete) [cSEMModel]-list.
#' @param .csem_resample A list resulting from a call to [resamplecSEMResults()].
#' @param .cv_folds Integer. The number of cross-validation folds to use. Setting
#' `.cv_folds` to `N` (the number of observations) produces
#' leave-one-out cross-validation samples. Defaults to `10`.
#' @param .data A `data.frame` or a `matrix` of standardized or unstandardized
#' data (indicators/items/manifest variables). Possible column types or classes
#' of the data provided are: "`logical`", "`numeric`" ("`double`" or "`integer`"),
#' "`factor`" ("`ordered`" and/or "`unordered`"), "`character`" (converted to factor),
#' or a mix of several types.
#' @param .dependent Character string. The name of the dependent variable.
#' @param .disattenuate Logical. Should composite/proxy correlations
#' be disattenuated to yield consistent loadings and path estimates if at least
#' one of the construct is modeled as a common factor? Defaults to `TRUE`.
#' @param .dist Character string. The distribution to use for the critical value.
#' One of *"t"* for Student's t-distribution or *"z"* for the standard normal distribution.
#' Defaults to *"z"*.
#' @param .distance Character string. A distance measure. One of: "*geodesic*"
#' or "*squared_euclidean*". Defaults to "*geodesic*".
#' @param .df Character string. The method for obtaining the degrees of freedom.
#' Choices are "*type1*" and "*type2*". Defaults to "*type1*" .
#' @param .dominant_indicators A character vector of `"construct_name" = "indicator_name"` pairs,
#' where `"indicator_name"` is a character string giving the name of the dominant indicator
#' and `"construct_name"` a character string of the corresponding construct name.
#' Dominant indicators may be specified for a subset of the constructs.
#' Default to `NULL`.
#' @param .E A (J x J) matrix of inner weights.
#' @param .effect Internal argument used by helper printEffects().
#' @param .estimate_structural Logical. Should the structural coefficients
#' be estimated? Defaults to `TRUE`.
#' @param .eval_plan Character string. The evaluation plan to use. One of
#' "*sequential*", "*multicore*", or "*multisession*". In the two latter cases
#' all available cores will be used. Defaults to "*sequential*".
#' @param .filename Character string. The file name.
#' @param .first_resample A list containing the `.R` resamples based on the original
#' data obtained by resamplecSEMResults().
#' @param .fit_measures Logical. (EXPERIMENTAL) Should additional fit measures
#' be included? Defaults to `FALSE`.
#' @param .force Logical. Should .object be resampled even if it contains resamples
#' already?. Defaults to `FALSE`.
#' @param .full_output Logical. Should the full output of summarize be printed.
#' Defaults to `TRUE`.
#' @param .graph_attrs Character string. Additional attributes that should be passed
#' to the DiagrammeR syntax, e.g., c("rankdir=LR", "ranksep=1.0"). Defaults to *c("rankdir=LR")*.
#' @param .H The (N x J) matrix of construct scores.
#' @param .handle_inadmissibles Character string. How should inadmissible results
#' be treated? One of "*drop*", "*ignore*", or "*replace*". If "*drop*", all
#' replications/resamples yielding an inadmissible result will be dropped
#' (i.e. the number of results returned will potentially be less than `.R`).
#' For "*ignore*" all results are returned even if all or some of the replications
#' yielded inadmissible results (i.e. number of results returned is equal to `.R`).
#' For "*replace*" resampling continues until there are exactly `.R` admissible solutions.
#' Depending on the frequency of inadmissible solutions this may significantly increase
#' computing time. Defaults to "*drop*".
#' @param .id Character string or integer. A character string giving the name or
#' an integer of the position of the column of `.data` whose levels are used
#' to split `.data` into groups. Defaults to `NULL`.
#' @param .inference Logical. Should critical values be computed? Defaults to `FALSE`.
#' @param .independent Character string. The name of the independent variable.
#' @param .instruments A named list of vectors of instruments. The names
#' of the list elements are the names of the dependent (LHS) constructs of the structural
#' equation whose explanatory variables are endogenous. The vectors
#' contain the names of the instruments corresponding to each equation. Note
#' that exogenous variables of a given equation **must** be supplied as
#' instruments for themselves. Defaults to `NULL`.
#' @param .iter_max Integer. The maximum number of iterations allowed.
#' If `iter_max = 1` and `.approach_weights = "PLS-PM"` one-step weights are returned.
#' If the algorithm exceeds the specified number, weights of iteration step
#' `.iter_max - 1` will be returned with a warning. Defaults to `100`.
#' @param .level Character. Used in `plot.cSEMIPMA` to indicate whether IPMA should be done
#' for constructs or indicators.
#' @param .matrix1 A `matrix` to compare.
#' @param .matrix2 A `matrix` to compare.
#' @param .matrices A list of at least two matrices.
#' @param .metrics Character string or a vector of character strings.
#' Which prediction metrics should be displayed? One of: "*MAE*", "*RMSE*", "*Q2*",
#' "*MER*", "*MAPE*, "*MSE2*", "*U1*", "*U2*", "*UM*", "*UR*", or "*UD*".
#' Default to c("*MAE*", "*RMSE*", "*Q2*").
#' @param .model A model in [lavaan model syntax][lavaan::model.syntax]
#' or a [cSEMModel] list.
#' @param .moderator Character string. The name of the moderator variable.
#' @param .modes A vector giving the mode for each construct in the form `"name" = "mode"`.
#' Only used internally.
#' @param .ms_criterion Character string. Either a single character string or a vector
#' of character strings naming the model selection criterion to compute.
#' Defaults to `"all"`.
#' @param .n Integer. The number of observations of the original data.
#' @param .n_steps Integer. A value giving the number of steps (the spotlights, i.e.,
#' values of .moderator in surface analysis or floodlight analysis)
#' between the minimum and maximum value of the moderator. Defaults to `100`.
#' @param .normality Logical. Should joint normality of
#' \eqn{[\eta_{1:p}; \zeta; \epsilon]}{[\eta_(1:p); \zeta; \epsilon]}
#' be assumed in the nonlinear model? See \insertCite{Dijkstra2014}{cSEM} for details.
#' Defaults to `FALSE`. Ignored if the model is not nonlinear.
#' @param .nr_comparisons Integer. The number of comparisons. Defaults to `NULL`.
#' @param .null_model Logical. Should the degrees of freedom for the null model
#' be computed? Defaults to `FALSE`.
#' @param .object An R object of class [cSEMResults] resulting from a call to [csem()].
#' @param .object1 An R object of class [cSEMResults] resulting from a call to [csem()].
#' @param .object2 An R object of class [cSEMResults] resulting from a call to [csem()].
#' @param .only_common_factors Logical. Should only concepts modeled as common
#' factors be included when calculating one of the following quality criteria:
#' AVE, the Fornell-Larcker criterion, HTMT, and all reliability estimates.
#' Defaults to `TRUE`.
#' @param .only_structural Should the the log-likelihood be based on the
#' structural model? Ignored if `.by_equation == TRUE`. Defaults to `TRUE`.
#' @param .original_arguments The list of arguments used within [csem()].
#' @param .output_type Character string. The type of output to return. One of
#' "*complete*" or "*structured*". See the Value section for details. Defaults to
#' "*complete*".
#' @param .P A (J x J) construct variance-covariance matrix (possibly disattenuated).
#' @param .parameters_to_compare A model in [lavaan model syntax][lavaan::model.syntax] indicating which
#' parameters (i.e, path (`~`), loadings (`=~`), weights (`<~`), or correlations (`~~`)) should be
#' compared across groups. Defaults to `NULL` in which case all weights, loadings and
#' path coefficients of the originally specified model are compared.
#' @param .path Character string. Path of the directory to save the file to. Defaults
#' to `NULL`.
#' @param .path_coefficients List. A list that contains the resampled and the original
#' path coefficient estimates. Typically a part of a `cSEMResults_resampled` object.
#' Defaults to `NULL`.
#' @param .PLS_approach_cf Character string. Approach used to obtain the correction
#' factors for PLSc. One of: "*dist_squared_euclid*", "*dist_euclid_weighted*",
#' "*fisher_transformed*", "*mean_arithmetic*", "*mean_geometric*", "*mean_harmonic*",
#' "*geo_of_harmonic*". Defaults to "*dist_squared_euclid*".
#' Ignored if `.disattenuate = FALSE` or if `.approach_weights` is not PLS-PM.
#' @param .plot_correlations Character string. Specify which correlations should be plotted, i.e.,
#' between the exogenous constructs (`exo`), between the exogenous constructs and the indicators (`all`),
#' or not at all (`none`). Defaults to `exo`.
#' @param .plot_labels Logical. Whether to display edge labels. Defaults to TRUE.
#' @param .plot_package Character string. Indicates which packages should be used for plotting.
#' @param .plot_significances Logical. Should p-values in the form of stars be plotted? Defaults to `TRUE`.
#' @param .plot_structural_model_only Logical. Should only the structural model,
#' i.e., the constructs and their relationships be plotted? Defaults to `FALSE`.
#' @param .plot_type Character string. Indicates the type of plot that is produced.
#' @param .PLS_ignore_structural_model Logical. Should the structural model be ignored
#' when calculating the inner weights of the PLS-PM algorithm? Defaults to `FALSE`.
#' Ignored if `.approach_weights` is not PLS-PM.
#' @param .PLS_modes Either a named list specifying the mode that should be used for
#' each construct in the form `"construct_name" = mode`, a single character
#' string giving the mode that should be used for all constructs, or `NULL`.
#' Possible choices for `mode` are: "*modeA*", "*modeB*", "*modeBNNLS*",
#' "*unit*", "*PCA*", a single integer or
#' a vector of fixed weights of the same length as there are indicators for the
#' construct given by `"construct_name"`. If only a single number is provided this is identical to
#' using unit weights, as weights are rescaled such that the related composite
#' has unit variance. Defaults to `NULL`.
#' If `NULL` the appropriate mode according to the type
#' of construct used is chosen. Ignored if `.approach_weight` is not PLS-PM.
#' @param .PLS_weight_scheme_inner Character string. The inner weighting scheme
#' used by PLS-PM. One of: "*centroid*", "*factorial*", or "*path*".
#' Defaults to "*path*". Ignored if `.approach_weight` is not PLS-PM.
#' @param .probs A vector of probabilities.
#' @param .postestimation_object An object resulting from a call to one of cSEM's
#' postestimation functions (e.g. [summarize()]).
#' @param .quality_criterion Character string. A single character string or a
#' vector of character strings naming the quality criterion to compute. See
#' the Details section for a list of possible candidates.
#' Defaults to "*all*" in which case all possible quality criteria are computed.
#' @param .quantity Character string. Which statistic should be returned?
#' One of "*all*", "*mean*", "*sd*", "*bias*", "*CI_standard_z*", "*CI_standard_t*",
#' "*CI_percentile*", "*CI_basic*", "*CI_bc*", "*CI_bca*", "*CI_t_interval*"
#' Defaults to "*all*" in which case all quantities that do not require
#' additional resampling are returned, i.e., all quantities but "*CI_bca*", "*CI_t_interval*".
#' @param .Q A vector of composite-construct correlations with element names equal to
#' the names of the J construct names used in the measurement model. Note
#' Q^2 is also called the reliability coefficient.
#' @param .reliabilities A character vector of `"name" = value` pairs,
#' where `value` is a number between 0 and 1 and `"name"` a character string
#' of the corresponding construct name, or `NULL`. Reliabilities
#' may be given for a subset of the constructs. Defaults to `NULL` in which case
#' reliabilities are estimated by `csem()`. Currently, only supported for
#' `.approach_weights = "PLS-PM"`.
#' @param .resample_method Character string. The resampling method to use. One of:
#' "*none*", "*bootstrap*" or "*jackknife*". Defaults to "*none*".
#' @param .resample_method2 Character string. The resampling method to use when resampling
#' from a resample. One of: "*none*", "*bootstrap*" or "*jackknife*". For
#' "*bootstrap*" the number of draws is provided via `.R2`. Currently,
#' resampling from each resample is only required for the studentized confidence
#' interval ("*CI_t_interval*") computed by the [infer()] function. Defaults to "*none*".
#' @param `.resample_object` An R object of class `cSEMResults_resampled`
#' obtained from [resamplecSEMResults()] or by setting `.resample_method = "bootstrap"`
#' or `"jackknife"` when calling [csem()].
#' @param .resample_sarstedt A matrix containing the parameter estimates that
#' could potentially be compared and an id column indicating the group adherence
#' of each row.
#' @param .r Integer. The number of repetitions to use. Defaults to `1`.
#' @param .R Integer. The number of bootstrap replications. Defaults to `499`.
#' @param .R2 Integer. The number of bootstrap replications to use when
#' resampling from a resample. Defaults to `199`.
#' @param .R_bootstrap Integer. The number of bootstrap runs. Ignored if `.object`
#' contains resamples. Defaults to `499`
#' @param .R_permutation Integer. The number of permutations. Defaults to `499`
#' @param .S The (K x K) empirical indicator correlation matrix.
#' @param .saturated Logical. Should a saturated structural model be used?
#' Defaults to `FALSE`.
#' @param .second_resample A list containing `.R2` resamples for each of the `.R`
#' resamples of the first run.
#' @param .seed Integer or `NULL`. The random seed to use. Defaults to `NULL` in which
#' case an arbitrary seed is chosen. Note that the scope of the seed is limited
#' to the body of the function it is used in. Hence, the global seed will
#' not be altered!
#' @param .sign_change_option Character string. Which sign change option should
#' be used to handle flipping signs when resampling? One of "*none*","*individual*",
#' "*individual_reestimate*", "*construct_reestimate*". Defaults to "*none*".
#' @param .sim_points Integer. How many samples from the truncated normal distribution should
#' be simulated to estimate the exogenous construct scores? Defaults to "*100*".
#' @param .stage Character string. The stage the model is needed for.
#' One of "*first*" or "*second*". Defaults to "*first*".
#' @param .standardized Logical. Should standardized scores be returned? Defaults
#' to `TRUE`.
#' @param .starting_values A named list of vectors where the
#' list names are the construct names whose indicator weights the user
#' wishes to set. The vectors must be named vectors of `"indicator_name" = value`
#' pairs, where `value` is the (scaled or unscaled) starting weight. Defaults to `NULL`.
#' @param .steps_mod A numeric vector. Steps used for the moderator variable in calculating
#' the simple effects of an independent variable on the dependent variable.
#' Defaults to `NULL`.
#' @param .terms A vector of construct names to be classified.
#' @param .test_data A matrix of test data with the same column names as the
#' training data.
#' @param .testtype Character string. One of "*twosided*" (H1: The models do not
#' perform equally in predicting indicators belonging to endogenous constructs)"
#' and *onesided*" (H1: Model 1 performs better in predicting indicators belonging
#' @param .title Character string. Title of an object. Defaults to *""*.
#' @param .tolerance Double. The tolerance criterion for convergence.
#' Defaults to `1e-05`.
#' @param .treat_as_continuous Logical. Should the indicators for the benchmark predictions
#' be treated as continuous? If `TRUE` all indicators are treated as continuous and PLS-PM/PLSc is applied.
#' If `FALSE` OrdPLS/OrdPLSc is applied. Defaults to `TRUE`.
#' @param .type_gfi Character string. Which fitting function should the GFI be based
#' on? One of *"ML"* for the maximum likelihood fitting function, *"GLS"* for
#' the generalized least squares fitting function or *"ULS"* for the
#' unweighted least squares fitting function (same as the squared Euclidean distance).
#' Defaults to *"ML"*.
#' @param .type_ci Character string. Which confidence interval should be calculated?
#' For possible choices, see the `.quantity` argument of the [infer()] function.
#' Only used if `.approch_mgd` is one of "*CI_para*" or "*CI_overlap*". Ignored otherwise.
#' Defaults to "*CI_percentile*".
#' @param .type_htmt Character string indicating the type of HTMT that should be
#' calculated, i.e., the original HTMT ("*htmt*") or the HTMT2 ("*htmt2*").
#' Defaults to "*htmt*"
#' @param .type_vcv Character string. Which model-implied correlation
#' matrix should be calculated?
#' One of "*indicator*" or "*construct*". Defaults to "*indicator*".
#' @param .verbose Logical. Should information (e.g., progress bar) be printed
#' to the console? Defaults to `TRUE`.
#' @param .user_funs A function or a (named) list of functions to apply to every
#' resample. The functions must take `.object` as its first argument (e.g.,
#' `myFun <- function(.object, ...) {body-of-the-function}`).
#' Function output should preferably be a (named)
#' vector but matrices are also accepted. However, the output will be
#' vectorized (columnwise) in this case. See the examples section for details.
#' @param .value_independent Integer. Only required for floodlight analysis;
#' The value of the independent variable in case that it appears as a
#' higher-order term.
#' @param .values_moderator A numeric vector. The values of the moderator in a
#' the simple effects analysis. Typically these are difference from the mean (=0)
#' measured in standard deviations. Defaults to `c(-2, -1, 0, 1, 2)`.
#' @param .vcv_asymptotic Logical. Should the asymptotic variance-covariance matrix be used, i.e.,
#' VCV(b0) - VCV(b1)= VCV(b1-b0), or should VCV(b1-b0) be computed directly?
#' Defaults to `FALSE`.
#' @param .vector1 A vector of numeric values.
#' @param .vector2 A vector of numeric values.
#' @param .W A (J x K) matrix of weights.
#' @param .what Internal argument used by several print helper functions.
#' @param .W_new A (J x K) matrix of weights.
#' @param .W_old A (J x K) matrix of weights.
#' @param .weighted Logical. Should estimation be based on a score that uses
#' the weights of the weight approach used to obtain `.object`?. Defaults to `FALSE`.
#' @param .X A matrix of processed data (scaled, cleaned and ordered).
#' @param .X_cleaned A data.frame of processed data (cleaned and ordered). Note: `X_cleaned`
#' may not be scaled!
#'
#' @name csem_arguments
#' @aliases cSEMArguments
#' @keywords internal
NULL
#' Complete list of assess()'s ... arguments
#'
#' A complete alphabetical list of all possible arguments accepted by `assess()`'s `...`
#' (dotdotdot) argument.
#'
#' Most arguments supplied to the `...` argument of `assess()` are only
#' accepted by a subset of the functions called by `assess()`. The following
#' list shows which argument is passed to which function:
#' \describe{
#' \item{.absolute}{Accepted by/Passed down to: [calculateHTMT()]}
#' \item{.alpha}{Accepted by/Passed down to: [calculateRhoT()], [calculateHTMT()], [calculateCN()]}
#' \item{.ci}{Accepted by/Passed down to: [calculateHTMT()]}
#' \item{.closed_form_ci}{Accepted by/Passed down to: [calculateRhoT()]}
#' \item{.handle_inadmissibles}{Accepted by/Passed down to: [calculateHTMT()]}
#' \item{.inference}{Accepted by/Passed down to: [calculateHTMT]}
#' \item{.null_model}{Accepted by/Passed down to: [calculateDf()]}
#' \item{.R}{Accepted by/Passed down to: [calculateHTMT()]}
#' \item{.saturated}{Accepted by/Passed down to: [calculateSRMR()],
#' [calculateDG()], [calculateDL()], [calculateDML()]and subsequently [fit()].}
#' \item{.seed}{Accepted by/Passed down to: [calculateHTMT()]}
#' \item{.type_gfi}{Accepted by/Passed down to: [calculateGFI()]}
#' \item{.type_vcv}{Accepted by/Passed down to: [calculateSRMR()],
#' [calculateDG()], [calculateDL()], [calculateDML()] and subsequently [fit()].}
#' }
#' @usage NULL
#'
#' @inheritParams csem_arguments
#' @keywords internal
args_assess_dotdotdot <- function(
.absolute = TRUE,
.alpha = 0.05,
.ci = c("CI_standard_z", "CI_standard_t", "CI_percentile",
"CI_basic", "CI_bc", "CI_bca", "CI_t_interval"),
.closed_form_ci = FALSE,
.handle_inadmissibles= c("drop", "ignore", "replace"),
.inference = FALSE,
.null_model = FALSE,
.R = 499,
.saturated = FALSE,
.seed = NULL,
.type_gfi = c("ML", "GLS", "ULS"),
.type_vcv = "indicator"
) {NULL}
#' Show argument defaults or candidates
#'
#' Show all arguments used by package functions including default or candidate
#' values. For argument descriptions see: [csem_arguments].
#'
#' By default `args_default()`returns a list of default values by argument name.
#' If the list of accepted candidate values is required instead, use `.choices = TRUE`.
#'
#' @usage args_default(.choices = FALSE)
#'
#' @inheritParams csem_arguments
#'
#' @return A named list of argument names and defaults or accepted candidates.
#'
#' @seealso [handleArgs()], [csem_arguments], [csem()], [foreman()]
#'
#' @export
args_default <- function(.choices = FALSE) {
args <- list(
.alpha = 0.05,
.absolute = TRUE,
.approach_2ndorder = c("2stage", "mixed"),
.approach_alpha_adjust = c("none", "bonferroni"),
.approach_cor_robust = c("none", "mcd", "spearman"),
.approach_gcca = c("SUMCORR", "MAXVAR", "SSQCORR", "MINVAR", "GENVAR"),
.approach_mgd = c("all", "Klesel", "Chin", "Sarstedt", "Keil", "Nitzl",
"Henseler","CI_para","CI_overlap"),
.approach_nl = c("sequential", "replace"),
.approach_p_adjust = "none",
.approach_paths = c("OLS", "2SLS"),
.approach_predict = c("earliest", "direct"),
.approach_score_benchmark= c("mean", "median", "mode", "round"),
.approach_score_target = c("mean", "median", "mode"),
.approach_weights = c("PLS-PM", "SUMCORR", "MAXVAR", "SSQCORR", "MINVAR", "GENVAR",
"GSCA", "PCA", "unit", "bartlett", "regression"),
.arguments = NULL,
.attributes = NULL,
.benchmark = c("lm", "unit", "PLS-PM", "GSCA", "PCA", "MAXVAR","NA"),
.bias_corrected = TRUE,
.by_equation = TRUE,
.C = NULL,
.check_errors = TRUE,
.choices = FALSE,
.ci = c("CI_standard_z", "CI_standard_t", "CI_percentile",
"CI_basic", "CI_bc", "CI_bca", "CI_t_interval"),
.ci_colnames = NULL,
.closed_form_ci = FALSE,
.conv_criterion = c("diff_absolute", "diff_squared", "diff_relative"),
.csem_model = NULL,
.csem_resample = NULL,
.cv_folds = 10,
.data = NULL,
.dependent = NULL,
.disattenuate = TRUE,
.dist = c("z", "t"),
.distance = c("geodesic", "squared_euclidean"),
.df = c("type1", "type2"),
.dominant_indicators = NULL,
.E = NULL,
.effect = NULL,
.estimate_structural = TRUE,
.eval_plan = c("sequential", "multicore","multisession"),
.filename = NULL,
.fit_measures = FALSE,
.first_resample = NULL,
.force = FALSE,
.full_output = TRUE,
.graph_attrs = c("rankdir=LR"),
.handle_inadmissibles = c("drop", "ignore", "replace"),
.H = NULL,
.id = NULL,
.inference = FALSE,
.independent = NULL,
.instruments = NULL,
.iter_max = 100,
.listMatrices = NULL,
.level = c('construct',"indicator"),
.matrix1 = NULL,
.matrix2 = NULL,
.matrices = NULL,
.metrics = c("MAE", "RMSE", "Q2", "MER",
"MAPE", "MSE2", "U1", "U2" , "UM", "UR", "UD"),
.model = NULL,
.moderator = NULL,
.modes = NULL,
.ms_criterion = c("all", "aic", "aicc", "aicu", "bic", "fpe", "gm", "hq",
"hqc", "mallows_cp"),
.n_steps = 100,
.normality = FALSE,
.nr_comparisons = NULL,
.null_model = FALSE,
.object = NULL,
.only_common_factors = TRUE,
.output_type = c("complete", "structured"),
.P = NULL,
.parameters_to_compare = NULL,
.path = NULL,
.path_coefficients = NULL,
.plot_correlations = c("exo", "none", "all"),
.plot_labels = TRUE,
.plot_package = NULL,
.plot_significances = TRUE,
.plot_structural_model_only = FALSE,
.plot_type = NULL,
.probs = NULL,
.PLS_approach_cf = c("dist_squared_euclid", "dist_euclid_weighted",
"fisher_transformed", "mean_arithmetic",
"mean_geometric", "mean_harmonic",
"geo_of_harmonic"),
.PLS_ignore_structural_model = FALSE,
.PLS_modes = NULL,
.PLS_weight_scheme_inner = c("path", "centroid", "factorial"),
.postestimation_object = NULL,
.quality_criterion = c("all", "aic", "aicc", "aicu", "bic", "fpe", "gm", "hq",
"hqc", "mallows_cp", "ave",
"rho_C", "rho_C_mm", "rho_C_weighted",
"rho_C_weighted_mm", "dg", "dl", "dml", "df",
"effects", "f2", "fl_criterion", "chi_square", "chi_square_df",
"cfi", "cn", "gfi", "ifi", "nfi", "nnfi",
"reliability",
"rmsea", "rms_theta", "srmr",
"gof", "htmt", "htmt2", "r2", "r2_adj",
"rho_T", "rho_T_weighted", "vif",
"vifmodeB"),
.quantity = c("all", "mean", "sd", "bias", "CI_standard_z", "CI_standard_t",
"CI_percentile", "CI_basic", "CI_bc", "CI_bca", "CI_t_intervall"),
.Q = NULL,
.r = 1,
.R = 499,
.R2 = 199,
.R_bootstrap = 499,
.R_permutation = 499,
.reliabilities = NULL,
.resample_method = c("none", "bootstrap", "jackknife"),
.resample_method2 = c("none", "bootstrap", "jackknife"),
.resample_object = NULL,
.resample_sarstedt = NULL,
.S = NULL,
.saturated = FALSE,
.second_resample = NULL,
.seed = NULL,
.sign_change_option = c("none", "individual", "individual_reestimate",
"construct_reestimate"),
.sim_points = 100,
.stage = c("first", "second"),
.standardized = TRUE,
.starting_values = NULL,
.steps_mod = NULL,
.terms = NULL,
.test_data = NULL,
.title = "",
.tolerance = 1e-05,
.treat_as_continuous = TRUE,
.type_gfi = c("ML", "GLS", "ULS"),
.type_htmt = c("htmt", "htmt2"),
.type_vcv = c("indicator", "construct"),
.type_ci = c("CI_percentile","CI_standard_z","CI_standard_t",
"CI_basic","CI_bc", "CI_bca"),
.user_funs = NULL,
.value_independent = 0,
.values_moderator = c(-2,-1,0,1,2),
.vcv_asymptotic = c(FALSE, TRUE),
.verbose = TRUE,
.W = NULL,
.weighted = FALSE,
.what = NULL,
.x = NULL,
.X = NULL,
.X_cleaned = NULL,
.y = NULL,
.z = NULL
)
if(!.choices) {
args <- lapply(args, function(x) eval(x)[1])
}
args_sorted <- args[sort(names(args))]
return(args_sorted)
}
#' Internal: Handle arguments
#'
#' Internal helper function to handle arguments passed to any function within `cSEM`.
#'
#' @param .args_used A list of argument names and user picked values.
#'
#' @return The [args_default] list, with default values
#' changed to the values given by the user.
#' @keywords internal
handleArgs <- function(.args_used) {
args_default <- args_default()
args_default_names <- names(args_default)
args_used_names <- names(.args_used)
## Are all argument names used valid?
args_diff <- setdiff(args_used_names, args_default_names)
if (length(args_diff) > 0) {
stop("The following argument(s) are not known to cSEM: ",
paste0("`", args_diff, '`', collapse = ", "), "\n",
"Please type 'args_default()' to find all valid arguments and their defaults. Or check ?args_default.",
call. = FALSE)
}
## Are arguments valid
# Note: for now, I will only check if string arguments are valid. In the
# future we could refine and check if e.g. numeric values are within a reasonable
# range or larger than zero if required etc.
# choices_logical <- Filter(function(x) any(is.logical(x)), args_default(.choices = TRUE))
# choices_numeric <- Filter(function(x) any(is.numeric(x)), args_default(.choices = TRUE))
choices_character <- Filter(function(x) any(is.character(x)), args_default(.choices = TRUE))
character_args <- intersect(names(choices_character), args_used_names)
x <- Map(function(x, y) x %in% y,
x = .args_used[character_args],
y = choices_character[character_args]
)
lapply(seq_along(x), function(i) {
if(isFALSE(x[[i]])) {
n <- names(x[i])
a <- args_default(.choices = TRUE)[[n]]
stop(paste0("`", .args_used[n], "` is not a valid choice for ", "`",
names(.args_used[n]),"`.\n"),
"Choices are: ", paste0("`", a[-length(a)],"`", collapse = ", "),
" or " , paste0("`", a[length(a)], "`"), call. = FALSE)
}
})
## Replace all arguments that were changed or explicitly given and keep
# the default values for the others
for(i in args_used_names) {
args_default[i] <- .args_used[i]
}
return(args_default)
}
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.