diff --git a/DESCRIPTION b/DESCRIPTION index e32dbc29..8563ba86 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: familiar Title: End-to-End Automated Machine Learning and Model Evaluation -Version: 2.0.0 +Version: 2.0.1 Authors@R: c( person("Alex", "Zwanenburg", email = "alexander.zwanenburg@nct-dresden.de", @@ -26,7 +26,6 @@ Depends: R (>= 4.0.0) License: EUPL Encoding: UTF-8 LazyData: true -RoxygenNote: 7.3.3 Roxygen: list(markdown = TRUE) VignetteBuilder: knitr Imports: @@ -227,3 +226,4 @@ Collate: 'aaa.R' Config/testthat/parallel: true Config/testthat/edition: 3 +Config/roxygen2/version: 8.0.0 diff --git a/NAMESPACE b/NAMESPACE index ef302870..88c77b63 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -70,6 +70,7 @@ exportMethods(plot_feature_similarity) exportMethods(plot_ice) exportMethods(plot_kaplan_meier) exportMethods(plot_model_performance) +exportMethods(plot_pd) exportMethods(plot_permutation_variable_importance) exportMethods(plot_sample_clustering) exportMethods(plot_shap_dependence) diff --git a/NEWS.md b/NEWS.md index d4dbd5b2..479b3696 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,35 @@ +# Version 2.0.1 (Brilliant Bat) + +## Minor changes + +- `plot_feature_similarity` and `plot_sample_clustering` now have the `features` + argument, which selects the features that appear in the heatmap. + +- `plot_feature_similarity` and `plot_sample_clustering` now have the + `remove_feature_labels` argument, which suppresses rendering of feature + names as tick labels for the heatmap. + +- `plot_sample_clustering` now has the `remove_sample_labels` argument, which + suppresses rendering of sample names as tick labels for the heatmap. + +- `plot_kaplan_meier` now plots strata in one facet if the risk group is equal + to the data set. + +- `plot_kaplan_meier` now correctly shows the results of the log-rank test for + strata in each facet. + +## Fixes + +- Prevents an error when evaluating models in bootstrap or cross-validation + experiments without variable importances and a number features in the model + that exceeds `n_important_features`. + +- `plot_pd` is now correctly exported and can be called externally. + +- `plot_kaplan_meier` now works correctly if the column indicated by `risk_group_column` + contains `NA` values. + + # Version 2.0.0 (Astonishing Anteater) ## Breaking changes diff --git a/R/DataObject.R b/R/DataObject.R index 061744b5..c0631469 100644 --- a/R/DataObject.R +++ b/R/DataObject.R @@ -2338,7 +2338,10 @@ setMethod( # Check if features are present as column name if (length(features) > 0L) { if (!all(features %in% colnames(data@data))) { - logger_stop("Not all features were found in the data set.") + missing_features <- setdiff(features, colnames(data@data)) + logger_stop( + paste0("Not all features were found in the data set: ", paste_s(missing_features)) + ) } } diff --git a/R/DataParameterChecks.R b/R/DataParameterChecks.R index d705f6ed..8b2c9e56 100644 --- a/R/DataParameterChecks.R +++ b/R/DataParameterChecks.R @@ -73,6 +73,11 @@ ) { settings$data$sample_col <- get_id_columns(single_column = "sample") } + + } else if (is.null(settings$data$sample_col)) { + if (get_id_columns(single_column = "sample") %in% colnames(data)) { + settings$data$sample_col <- get_id_columns(single_column = "sample") + } } if (!is.null(settings$data$batch_col) && check_stringency != "strict") { @@ -83,6 +88,11 @@ ) { settings$data$batch_col <- get_id_columns(single_column = "batch") } + + } else if (is.null(settings$data$batch_col)) { + if (get_id_columns(single_column = "batch") %in% colnames(data)) { + settings$data$batch_col <- get_id_columns(single_column = "batch") + } } if (!is.null(settings$data$series_col) && check_stringency != "strict") { @@ -93,6 +103,11 @@ ) { settings$data$series_col <- get_id_columns(single_column = "series") } + + } else if (is.null(settings$data$series_col)) { + if (get_id_columns(single_column = "series") %in% colnames(data)) { + settings$data$series_col <- get_id_columns(single_column = "series") + } } ## Sample column ------------------------------------------------------------- diff --git a/R/Familiar.R b/R/Familiar.R index 949e085c..aa5e8eb1 100644 --- a/R/Familiar.R +++ b/R/Familiar.R @@ -609,8 +609,7 @@ summon_familiar <- function( #' @inheritParams .parse_variable_importance_settings #' @inheritDotParams .parse_experiment_settings -config #' @inheritDotParams .parse_setup_settings -config -#' @inheritDotParams .parse_preprocessing_settings -config -data -parallel -#' -outcome_type +#' @inheritDotParams .parse_preprocessing_settings -config -data -parallel -outcome_type #' #' @details This is a thin wrapper around `summon_familiar`, and functions like #' it, but automatically skips computation of variable importance, learning @@ -729,8 +728,7 @@ precompute_data_assignment <- function( #' @inheritParams .parse_variable_importance_settings #' @inheritDotParams .parse_experiment_settings -config #' @inheritDotParams .parse_setup_settings -config -#' @inheritDotParams .parse_preprocessing_settings -config -data -parallel -#' -outcome_type +#' @inheritDotParams .parse_preprocessing_settings -config -data -parallel -outcome_type #' #' @details This is a thin wrapper around `summon_familiar`, and functions like #' it, but automatically skips computation of variable importance, learning diff --git a/R/FamiliarDataComputation.R b/R/FamiliarDataComputation.R index 2e23ee98..aa55dd40 100644 --- a/R/FamiliarDataComputation.R +++ b/R/FamiliarDataComputation.R @@ -202,6 +202,11 @@ setMethod( #' vignette on performance metrics for the available metrics. If not provided #' explicitly, this parameter is read from settings used at creation of the #' underlying `familiarModel` objects. +#' +#'@param features Features that should be considered for extracting information +#' from. Typically called in external workflows, e.g. for plotting. Internally, +#' i.e. from summon_familiar, this variable is not used. +#' #'@param feature_cluster_method The method used to perform clustering. These are #' the same methods as for the `cluster_method` configuration parameter: #' `none`, `hclust`, `agnes`, `diana` and `pam`. @@ -319,6 +324,7 @@ setMethod( stratification_method = waiver(), evaluation_times = waiver(), metric = waiver(), + features = waiver(), feature_cluster_method = waiver(), feature_cluster_cut_method = waiver(), feature_linkage_method = waiver(), @@ -346,7 +352,7 @@ setMethod( "feature_expressions", "permutation_vimp") %in% data_element)) { # Not for the fs_vimp data elements. This is because the subset of # features in the ensemble is generally smaller than that assessed within - # feature selection.. + # feature selection. # Compute a table containing the pairwise distance between features. feature_similarity <- extract_feature_similarity( @@ -358,6 +364,7 @@ setMethod( confidence_level = confidence_level, bootstrap_ci_method = bootstrap_ci_method, is_pre_processed = is_pre_processed, + features = features, feature_cluster_method = feature_cluster_method, feature_linkage_method = feature_linkage_method, feature_cluster_cut_method = feature_cluster_cut_method, @@ -378,6 +385,7 @@ setMethod( data = data, cl = cl, is_pre_processed = is_pre_processed, + features = features, sample_limit = sample_limit, sample_similarity_metric = sample_similarity_metric, sample_cluster_method = sample_cluster_method, @@ -639,6 +647,7 @@ setMethod( data = data, cl = cl, ensemble_method = ensemble_method, + features = features, evaluation_times = evaluation_times, sample_limit = sample_limit, n_important_features = n_important_features, @@ -663,6 +672,7 @@ setMethod( data = data, cl = cl, ensemble_method = ensemble_method, + features = features, evaluation_times = evaluation_times, sample_limit = sample_limit, detail_level = detail_level, diff --git a/R/FamiliarDataComputationFeatureExpression.R b/R/FamiliarDataComputationFeatureExpression.R index da13b190..02c885c1 100644 --- a/R/FamiliarDataComputationFeatureExpression.R +++ b/R/FamiliarDataComputationFeatureExpression.R @@ -279,6 +279,27 @@ setMethod( + +.feature_expression_remove_feature <- function(x, features) { + if (is_empty(x)) return(x) + + all_features <- names(x@feature_info) + available_features <- intersect(all_features, features) + + if (length(available_features) == 0L) return(NULL) + + # Filter features. + x@feature_info <- x@feature_info[available_features] + x@data <- x@data[, mget(c(setdiff(colnames(x@data), all_features), available_features))] + x@value_column <- available_features + + return(x) +} + + + + + # export_feature_expressions (generic) ----------------------------------------- #'@title Extract and export feature expressions. @@ -286,6 +307,9 @@ setMethod( #'@description Extract and export feature expressions for the features in a #' familiarCollection. #' +#'@param features Features that should be exported. If `NULL` or `waiver()`, all +#' features exported (default). +#' #'@param evaluation_time One or more time points that are used to create the #' outcome columns in expression plots. If not provided explicitly, this #' parameter is read from settings used at creation of the underlying @@ -314,6 +338,7 @@ setGeneric( "export_feature_expressions", function( object, + features = waiver(), dir_path = NULL, evaluation_time = waiver(), export_collection = FALSE, @@ -333,6 +358,7 @@ setMethod( signature(object = "familiarCollection"), function( object, + features = waiver(), dir_path = NULL, evaluation_time = waiver(), export_collection = FALSE, @@ -348,6 +374,11 @@ setMethod( # Check that the data are not empty. if (is_empty(x)) return(NULL) + if (!is.waive(features) && !is.null(features)) { + # Filter features. + x <- lapply(x, .feature_expression_remove_feature, features = features) + } + if (!is.waive(evaluation_time)) { # Check values. @@ -391,6 +422,7 @@ setMethod( signature(object = "ANY"), function( object, + features = waiver(), dir_path = NULL, evaluation_time = waiver(), export_collection = FALSE, @@ -403,6 +435,7 @@ setMethod( args = c( list( "object" = object, + "features" = features, "data_element" = "feature_expressions", "evaluation_times" = evaluation_time ), @@ -415,6 +448,7 @@ setMethod( args = c( list( "object" = object, + "features" = features, "dir_path" = dir_path, "evaluation_time" = evaluation_time, "export_collection" = export_collection diff --git a/R/FamiliarDataComputationFeatureSimilarity.R b/R/FamiliarDataComputationFeatureSimilarity.R index 39151e4c..16611b2a 100644 --- a/R/FamiliarDataComputationFeatureSimilarity.R +++ b/R/FamiliarDataComputationFeatureSimilarity.R @@ -36,6 +36,8 @@ setClass( #' used in a `familiarEnsemble` object. This table can be used to cluster #' features, and is exported directly by `export_feature_similarity`. #' +#'@param features (*optional*) Features for which feature similarity is computed. +#' #'@inheritParams .extract_data #' #'@return A data.table containing pairwise distance between features. This data @@ -55,6 +57,7 @@ setGeneric( confidence_level = waiver(), bootstrap_ci_method = waiver(), is_pre_processed = FALSE, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -82,6 +85,7 @@ setMethod( confidence_level = waiver(), bootstrap_ci_method = waiver(), is_pre_processed = FALSE, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -201,6 +205,7 @@ setMethod( cl = cl, object = object, data = data, + features = features, proto_data_element = proto_data_element, is_pre_processed = is_pre_processed, aggregate_results = aggregate_results, @@ -239,6 +244,7 @@ setMethod( confidence_level = waiver(), bootstrap_ci_method = waiver(), is_pre_processed = FALSE, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -359,6 +365,7 @@ setMethod( cl = cl, object = object, data = object, + features = features, proto_data_element = proto_data_element, is_pre_processed = is_pre_processed, aggregate_results = aggregate_results, @@ -375,6 +382,7 @@ setMethod( .extract_feature_similarity <- function( object, data, + features = NULL, proto_data_element, cl = NULL, is_pre_processed, @@ -404,7 +412,15 @@ setMethod( # if not. if (get_n_samples(data, "series") <= 5L) return(NULL) - if (is(object, "familiarEnsemble")) { + # Check if specific features need to be processed. + if (is.waive(features)) features <- NULL + if (!is.null(features)) { + data <- filter_features( + data = data, + available_features = features + ) + + } else if (is(object, "familiarEnsemble")) { # Maintain only important features. The current set is based on the required # features. data <- filter_features( @@ -516,6 +532,21 @@ setMethod( +.feature_similarity_remove_feature <- function(x, features) { + + # Suppress NOTES due to non-standard evaluation in data.table + feature_name_1 <- feature_name_2 <- NULL + + if (is_empty(x)) return(x) + + # Filter all features. + x@data <- x@data[feature_name_1 %in% features & feature_name_2 %in% features] + + return(x) +} + + + .append_feature_similarity_dendrogram <- function(x) { if (is_empty(x)) return(x) @@ -716,6 +747,7 @@ setGeneric( object, dir_path = NULL, aggregate_results = TRUE, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -740,6 +772,7 @@ setMethod( object, dir_path = NULL, aggregate_results = TRUE, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -835,6 +868,11 @@ setMethod( ) { x <- .compute_data_element_estimates(x) + if (!is.waive(features) && !is.null(features)) { + # Filter features. + x <- lapply(x, .feature_similarity_remove_feature, features) + } + if (export_dendrogram || export_ordered_data || export_clustering) { # Add dendrogram and other cluster objects. x <- lapply(x, .append_feature_similarity_dendrogram) @@ -876,6 +914,7 @@ setMethod( object, dir_path = NULL, aggregate_results = TRUE, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -892,6 +931,7 @@ setMethod( "object" = object, "data_element" = "feature_similarity", "aggregate_results" = aggregate_results, + "features" = features, "feature_cluster_method" = feature_cluster_method, "feature_linkage_method" = feature_linkage_method, "feature_cluster_cut_method" = feature_cluster_cut_method, @@ -908,6 +948,7 @@ setMethod( "object" = object, "dir_path" = dir_path, "aggregate_results" = aggregate_results, + "features" = features, "feature_cluster_method" = feature_cluster_method, "feature_linkage_method" = feature_linkage_method, "feature_cluster_cut_method" = feature_cluster_cut_method, diff --git a/R/FamiliarDataComputationICE.R b/R/FamiliarDataComputationICE.R index 2d0e91a7..f4a2bc6e 100644 --- a/R/FamiliarDataComputationICE.R +++ b/R/FamiliarDataComputationICE.R @@ -100,6 +100,8 @@ setMethod( ... ) { + if (is.waive(features)) features <- NULL + # Message extraction start if (is.null(features)) { logger_message( diff --git a/R/FamiliarDataComputationRiskStratificationData.R b/R/FamiliarDataComputationRiskStratificationData.R index e41fad60..68daa3d8 100644 --- a/R/FamiliarDataComputationRiskStratificationData.R +++ b/R/FamiliarDataComputationRiskStratificationData.R @@ -253,6 +253,9 @@ setMethod( # This mostly follows the same routines as extract_prediction_data. In # addition, tests are created during export. + # Suppress NOTES due to non-standard evaluation in data.table + group <- NULL + # Only assess stratification for survival outcomes. if (!object@outcome_type %in% c("survival")) return(NULL) @@ -274,8 +277,10 @@ setMethod( range = c(0.0, 1.0), closed = c(FALSE, FALSE) ) - - if (is.waive(risk_group_column)) risk_group_column <- get_id_columns("batch") + + # Set default risk group (batch). + batch_id_column <- get_id_columns(single_column = "batch") + if (is.waive(risk_group_column)) risk_group_column <- batch_id_column # Check if only one column is provided as risk_group_column. .check_argument_length( @@ -298,6 +303,11 @@ setMethod( ) prediction_data <- .merge_slots_into_data(prediction_data) + # Remove instances where the assigned group is NA. + if (!is_empty(prediction_data@data)) { + prediction_data@data <- prediction_data@data[!is.na(group), ] + } + # Manually set attributes for this dataElement. prediction_data@detail_level <- "ensemble" prediction_data@estimation_type <- "point" diff --git a/R/FamiliarDataComputationSHAP.R b/R/FamiliarDataComputationSHAP.R index c1508fcd..ea95e259 100644 --- a/R/FamiliarDataComputationSHAP.R +++ b/R/FamiliarDataComputationSHAP.R @@ -138,6 +138,8 @@ setMethod( ) { # Compute SHAP values. + if (is.waive(features)) features <- NULL + # Message extraction start logger_message( paste0("Extracting SHAP values for the ensemble."), diff --git a/R/FamiliarDataComputationSampleSimilarity.R b/R/FamiliarDataComputationSampleSimilarity.R index 947ccf47..de05c142 100644 --- a/R/FamiliarDataComputationSampleSimilarity.R +++ b/R/FamiliarDataComputationSampleSimilarity.R @@ -57,6 +57,7 @@ setGeneric( data, cl = NULL, is_pre_processed = FALSE, + features = waiver(), sample_limit = waiver(), sample_cluster_method = waiver(), sample_linkage_method = waiver(), @@ -80,6 +81,7 @@ setMethod( data, cl = NULL, is_pre_processed = FALSE, + features = waiver(), sample_limit = waiver(), sample_cluster_method = waiver(), sample_linkage_method = waiver(), @@ -88,7 +90,7 @@ setMethod( message_indent = 0L, ... ) { - + # TODO: pass-through features. # Message extraction start logger_message( paste0("Computing pairwise similarity between samples."), @@ -147,6 +149,7 @@ setMethod( object = object, data = data, sample_limit = sample_limit, + features = features, proto_data_element = proto_data_element, is_pre_processed = is_pre_processed, aggregate_results = TRUE, @@ -182,6 +185,7 @@ setMethod( data, cl = NULL, is_pre_processed = FALSE, + features = waiver(), sample_limit = waiver(), sample_cluster_method = waiver(), sample_linkage_method = waiver(), @@ -258,6 +262,7 @@ setMethod( object = object, data = object, sample_limit = sample_limit, + features = features, proto_data_element = proto_data_element, is_pre_processed = is_pre_processed, aggregate_results = TRUE, @@ -274,6 +279,7 @@ setMethod( .extract_sample_similarity <- function( object, data, + features = NULL, proto_data_element, cl = NULL, sample_limit, @@ -312,12 +318,23 @@ setMethod( seed = 0L ) - if (is(object, "familiarEnsemble")){ - # Maintain only important features when assessing data from the perspective - # of an ensemble. The current set is based on the required features. + # Check if specific features need to be processed. + if (is.waive(features)) features <- NULL + if (!is.null(features)) { data <- filter_features( data = data, - available_features = object@model_features + available_features = features + ) + + # Aggregate features. + data <- aggregate_data(data = data) + + } else if (is(object, "familiarEnsemble")) { + # Maintain only important features. The current set is based on the required + # features. + data <- filter_features( + data = data, + available_features = get_model_features(object) ) # Aggregate features. @@ -327,6 +344,8 @@ setMethod( # Identify eligible columns. feature_columns <- get_feature_columns(x = data) + if (length(feature_columns) == 0L) return(NULL) + # Compute the similarity table data_element@data <- set_similarity_table( data = data, diff --git a/R/FamiliarDataComputationUtilities.R b/R/FamiliarDataComputationUtilities.R index b9ec2a37..45b6edac 100644 --- a/R/FamiliarDataComputationUtilities.R +++ b/R/FamiliarDataComputationUtilities.R @@ -307,33 +307,49 @@ # If signature is used, don't use fall-back option. if (object@vimp_method %in% .get_available_signature_only_vimp_methods()) use_fallback <- FALSE - # Set-up fallback vimp-table + # Set-up fallback vimp-table. if (use_fallback) { - # Spawn task to obtain variable importance tables. - vimp_task <- methods::new( - "familiarTaskVimp", - project_id = object@project_id, - vimp_method = fallback_vimp_method, - data_id = object@data_id, - run_id = object@run_id, - file = NA_character_ - ) + # VIMP-tables are created per model, so that we use - # Fill details required to get the data, in case the data is delayed. - # Note that training data is used for obtaining variable importance. - if (is(data, "delayedDataObject")) { - data@data_id <- object@data_id - data@run_id <- object@run_id - } + vimp_table <- list() - # Create variable importance table. - vimp_table <- .perform_task( - object = vimp_task, - feature_info_list = object@feature_info, - vimp_aggregation_method = vimp_aggregation_method, - vimp_rank_threshold = vimp_rank_threshold, - data = data - ) + if (is(object, "familiarEnsemble")) { + model_list <- object@model_list + } else { + model_list <- list(object) + } + + for (ii in seq_along(model_list)) { + # Get model. + model <- model_list[[ii]] + + # Fill details required to get the data, in case the data is delayed. + # Note that training data is used for obtaining variable importance. + if (is(data, "delayedDataObject")) { + data@data_id <- model@data_id + data@run_id <- model@run_id + data@validation <- FALSE + } + + # Spawn task to obtain variable importance tables. + vimp_task <- methods::new( + "familiarTaskVimp", + project_id = object@project_id, + vimp_method = fallback_vimp_method, + data_id = model@data_id, + run_id = model@run_id, + file = NA_character_ + ) + + # Create variable importance table. + vimp_table[[ii]] <- .perform_task( + object = vimp_task, + feature_info_list = object@feature_info, + vimp_aggregation_method = vimp_aggregation_method, + vimp_rank_threshold = vimp_rank_threshold, + data = data + ) + } } # For signature-only, return all signature features, with no preference. diff --git a/R/FamiliarObjectConversion.R b/R/FamiliarObjectConversion.R index f030e419..11cbedca 100644 --- a/R/FamiliarObjectConversion.R +++ b/R/FamiliarObjectConversion.R @@ -336,6 +336,7 @@ setMethod( # Parse dataObject. if (all(sapply(object, is, "dataObject"))) { + # Split by batch-id. object <- lapply(object, .split_data_by_batch_id) diff --git a/R/PlotFeatureSimilarity.R b/R/PlotFeatureSimilarity.R index aeb02889..270421a7 100644 --- a/R/PlotFeatureSimilarity.R +++ b/R/PlotFeatureSimilarity.R @@ -26,6 +26,8 @@ NULL #' gradient. This should be a range of two values, e.g. `c(0, 1)`. Lower or #' upper boundary can be unset by using `NA`. If not set, the full #' metric-specific range is used. +#' @param remove_feature_labels (*optional*) If `TRUE`, feature labels are not +#' shown. By default, feature labels are shown. #' @param show_dendrogram (*optional*) Show dendrogram around the main panel. #' Can be `TRUE`, `FALSE`, `NULL`, or a position, i.e. `top`, `bottom`, `left` #' and `right`. Up to two positions may be provided, but only as long as the @@ -47,7 +49,7 @@ NULL #' @inheritParams .check_plot_splitting_variables #' @inheritDotParams as_familiar_collection -object #' @inheritDotParams ggplot2::ggsave -height -width -units -path -filename -plot -#' @inheritDotParams extract_feature_similarity -object -feature_cluster_method -feature_linkage_method -feature_cluster_cut_method -feature_similarity_threshold +#' @inheritDotParams extract_feature_similarity -object -feature_cluster_method -feature_linkage_method -feature_cluster_cut_method -feature_similarity_threshold -features #' #' @details This function generates area under the ROC curve plots. #' @@ -75,6 +77,7 @@ setGeneric( "plot_feature_similarity", function( object, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -99,6 +102,7 @@ setGeneric( y_n_breaks = 3L, y_breaks = NULL, rotate_x_tick_labels = waiver(), + remove_feature_labels = FALSE, show_dendrogram = c("top", "right"), dendrogram_height = grid::unit(1.5, "cm"), width = waiver(), @@ -121,6 +125,7 @@ setMethod( signature(object = "ANY"), function( object, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -145,6 +150,7 @@ setMethod( y_n_breaks = 3L, y_breaks = NULL, rotate_x_tick_labels = waiver(), + remove_feature_labels = FALSE, show_dendrogram = c("top", "right"), dendrogram_height = grid::unit(1.5, "cm"), width = waiver(), @@ -160,6 +166,7 @@ setMethod( list( "object" = object, "data_element" = "feature_similarity", + "features" = features, "feature_cluster_method" = feature_cluster_method, "feature_linkage_method" = feature_linkage_method, "feature_cluster_cut_method" = feature_cluster_cut_method, @@ -173,6 +180,7 @@ setMethod( plot_feature_similarity, args = list( "object" = object, + "features" = features, "draw" = draw, "dir_path" = dir_path, "split_by" = split_by, @@ -193,6 +201,7 @@ setMethod( "y_n_breaks" = y_n_breaks, "y_breaks" = y_breaks, "rotate_x_tick_labels" = rotate_x_tick_labels, + "remove_feature_labels" = remove_feature_labels, "show_dendrogram" = show_dendrogram, "dendrogram_height" = dendrogram_height, "width" = width, @@ -214,6 +223,7 @@ setMethod( signature(object = "familiarCollection"), function( object, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -238,6 +248,7 @@ setMethod( y_n_breaks = 3L, y_breaks = NULL, rotate_x_tick_labels = waiver(), + remove_feature_labels = FALSE, show_dendrogram = c("top", "right"), dendrogram_height = grid::unit(1.5, "cm"), width = waiver(), @@ -252,6 +263,7 @@ setMethod( # Get input data x <- export_feature_similarity( object = object, + features = features, feature_cluster_method = feature_cluster_method, feature_linkage_method = feature_linkage_method, feature_cluster_cut_method = feature_cluster_cut_method, @@ -436,6 +448,7 @@ setMethod( y_n_breaks = y_n_breaks, y_breaks = y_breaks, rotate_x_tick_labels = rotate_x_tick_labels, + remove_feature_labels = remove_feature_labels, show_dendrogram = show_dendrogram, dendrogram_height = dendrogram_height ) @@ -519,6 +532,7 @@ setMethod( y_n_breaks, y_breaks, rotate_x_tick_labels, + remove_feature_labels = FALSE, show_dendrogram, dendrogram_height ) { @@ -588,6 +602,7 @@ setMethod( plot_sub_title = plot_sub_title, caption = caption, rotate_x_tick_labels = rotate_x_tick_labels, + remove_feature_labels = remove_feature_labels, show_dendrogram = show_dendrogram, similarity_metric = x_split@similarity_metric ) @@ -707,6 +722,7 @@ setMethod( plot_sub_title, caption, rotate_x_tick_labels, + remove_feature_labels, show_dendrogram, similarity_metric ) { @@ -837,6 +853,14 @@ setMethod( ) ) } + + # Remove tick labels + if (remove_feature_labels) { + p <- p + ggplot2::theme( + axis.text.x = ggplot2::element_blank(), + axis.text.y = ggplot2::element_blank() + ) + } return(p) } diff --git a/R/PlotICE.R b/R/PlotICE.R index 24ab529e..9ef3f054 100644 --- a/R/PlotICE.R +++ b/R/PlotICE.R @@ -359,7 +359,7 @@ setMethod( #' the output in the figure. #' #' @return `NULL` or list of plot objects, if `dir_path` is `NULL`. -#' @exportMethod plot_ice +#' @exportMethod plot_pd #' @md #' @rdname plot_pd-methods setGeneric( diff --git a/R/PlotKaplanMeier.R b/R/PlotKaplanMeier.R index 3aae02db..ab6a079e 100644 --- a/R/PlotKaplanMeier.R +++ b/R/PlotKaplanMeier.R @@ -275,7 +275,7 @@ setMethod( # Make sure the collection object is updated. object <- update_object(object = object) - + # Get input data x <- export_risk_stratification_data( object = object, @@ -402,7 +402,7 @@ setMethod( # Store plots to list in case no dir_path is provided if (is.null(dir_path)) plot_list <- list() - + # Add default splitting variables. if (is.null(split_by) && is.null(color_by) && @@ -411,6 +411,13 @@ setMethod( split_by <- c("vimp_method", "learner", "stratification_method") color_by <- c("group") facet_by <- c("data_set") + + # The grouping variable may be identical to the data_set. In that case, + # do not facet by data_set. + if (identical(x@data$group, x@data$data_set)) { + facet_by <- NULL + x@data$data_set <- factor(x = rep_len("placeholder", nrow(x@data))) + } } # Check splitting variables and generate sanitised output @@ -463,7 +470,7 @@ setMethod( plot_sub_title = plot_sub_title, caption = caption ) - + # Create plots ------------------------------------------------------------- # Determine if subtitle should be generated. @@ -669,6 +676,9 @@ setMethod( # Skip if the split doesn't contain any information. if (is_empty(x_split@data) || all(is.na(x_split@data$outcome_time))) next + # Update groups attribute to reflect groups present in the current split. + x_split@groups <- unique(as.character(x_split@data$group)) + # Compute strata for the current split. strata <- .compute_risk_stratification_curves( x = x_split, @@ -684,7 +694,7 @@ setMethod( } else { test_data <- NULL } - + # Kaplan-Meier plots p_kaplan_meier <- .create_km_subplot( x = strata, diff --git a/R/PlotSampleClustering.R b/R/PlotSampleClustering.R index 2d9624b3..134f2184 100644 --- a/R/PlotSampleClustering.R +++ b/R/PlotSampleClustering.R @@ -38,6 +38,10 @@ NULL #' outcome data. If NULL, the legend will not have a name. By default, #' `class`, `value` and `event` are used for `binomial` and `multinomial`, #' `continuous`, and `survival` outcome types, respectively. +#' @param remove_feature_labels (*optional*) If `TRUE`, feature labels are not +#' shown. By default, feature labels are shown. +#' @param remove_sample_labels (*optional*) If `TRUE`, sample labels are not +#' shown. By default, feature labels are shown. #' @param show_feature_dendrogram (*optional*) Show feature dendrogram around #' the main panel. Can be `TRUE`, `FALSE`, `NULL`, or a position, i.e. `top`, #' `bottom`, `left` and `right`. @@ -143,6 +147,7 @@ setGeneric( "plot_sample_clustering", function( object, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), sample_cluster_method = waiver(), @@ -176,6 +181,8 @@ setGeneric( y_n_breaks = 3L, y_breaks = NULL, rotate_x_tick_labels = waiver(), + remove_feature_labels = FALSE, + remove_sample_labels = FALSE, show_feature_dendrogram = TRUE, show_sample_dendrogram = TRUE, show_normalised_data = TRUE, @@ -204,6 +211,7 @@ setMethod( signature(object = "ANY"), function( object, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), sample_cluster_method = waiver(), @@ -237,6 +245,8 @@ setMethod( y_n_breaks = 3L, y_breaks = NULL, rotate_x_tick_labels = waiver(), + remove_feature_labels = FALSE, + remove_sample_labels = FALSE, show_feature_dendrogram = TRUE, show_sample_dendrogram = TRUE, show_normalised_data = TRUE, @@ -259,6 +269,7 @@ setMethod( "object" = object, "data_element" = "feature_expressions", "sample_limit" = sample_limit, + "features" = features, "feature_cluster_method" = feature_cluster_method, "feature_linkage_method" = feature_linkage_method, "sample_cluster_method" = sample_cluster_method, @@ -272,6 +283,7 @@ setMethod( plot_sample_clustering, args = list( "object" = object, + "features" = features, "feature_cluster_method" = feature_cluster_method, "feature_linkage_method" = feature_linkage_method, "sample_cluster_method" = sample_cluster_method, @@ -304,6 +316,8 @@ setMethod( "y_n_breaks" = y_n_breaks, "y_breaks" = y_breaks, "rotate_x_tick_labels" = rotate_x_tick_labels, + "remove_feature_labels" = remove_feature_labels, + "remove_sample_labels" = remove_sample_labels, "show_feature_dendrogram" = show_feature_dendrogram, "show_sample_dendrogram" = show_sample_dendrogram, "show_normalised_data" = show_normalised_data, @@ -331,6 +345,7 @@ setMethod( signature(object = "familiarCollection"), function( object, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), sample_cluster_method = waiver(), @@ -364,6 +379,8 @@ setMethod( y_n_breaks = 3L, y_breaks = NULL, rotate_x_tick_labels = waiver(), + remove_feature_labels = FALSE, + remove_sample_labels = FALSE, show_feature_dendrogram = TRUE, show_sample_dendrogram = TRUE, show_normalised_data = TRUE, @@ -387,12 +404,14 @@ setMethod( # Get feature expression data feature_expression <- export_feature_expressions( object = object, + features = features, evaluation_time = evaluation_times ) # Get feature similarity data. feature_similarity <- export_feature_similarity( object = object, + features = features, feature_cluster_method = feature_cluster_method, feature_linkage_method = feature_linkage_method, export_dendrogram = FALSE, @@ -846,6 +865,8 @@ setMethod( y_n_breaks = y_n_breaks, y_breaks = y_breaks, rotate_x_tick_labels = rotate_x_tick_labels, + remove_feature_labels = remove_feature_labels, + remove_sample_labels = remove_sample_labels, show_feature_dendrogram = show_feature_dendrogram, show_sample_dendrogram = show_sample_dendrogram, show_normalised_data = show_normalised_data, @@ -952,6 +973,8 @@ setMethod( y_n_breaks, y_breaks, rotate_x_tick_labels, + remove_feature_labels, + remove_sample_labels, show_feature_dendrogram, show_sample_dendrogram, show_normalised_data, @@ -1300,6 +1323,8 @@ setMethod( plot_sub_title = plot_sub_title, caption = caption, rotate_x_tick_labels = rotate_x_tick_labels, + remove_feature_labels = remove_feature_labels, + remove_sample_labels = remove_sample_labels, show_feature_dendrogram = show_feature_dendrogram, show_sample_dendrogram = show_sample_dendrogram ) @@ -1585,6 +1610,8 @@ setMethod( plot_sub_title, caption, rotate_x_tick_labels, + remove_feature_labels, + remove_sample_labels, show_feature_dendrogram, show_sample_dendrogram ) { @@ -1697,6 +1724,24 @@ setMethod( ) ) } + + if (remove_feature_labels) { + if (x_axis_by == "feature") { + p <- p + ggplot2::theme(axis.text.x = ggplot2::element_blank()) + + } else { + p <- p + ggplot2::theme(axis.text.y = ggplot2::element_blank()) + } + } + + if (remove_sample_labels) { + if (x_axis_by == "sample") { + p <- p + ggplot2::theme(axis.text.x = ggplot2::element_blank()) + + } else { + p <- p + ggplot2::theme(axis.text.y = ggplot2::element_blank()) + } + } return(p) } diff --git a/cran-comments.md b/cran-comments.md index bdaacc37..33decb71 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,4 +1,6 @@ -Update familiar to version 2.0.0 +Update familiar to version 2.0.1 + +Version 2.0.1 primarily fixes a few bugs present in version 2.0.0. Vignettes are pre-compiled to avoid long compilation times on build (several minutes). diff --git a/man/as_familiar_collection-methods.Rd b/man/as_familiar_collection-methods.Rd index c891ec29..b7b18787 100644 --- a/man/as_familiar_collection-methods.Rd +++ b/man/as_familiar_collection-methods.Rd @@ -109,7 +109,7 @@ parameter is one or more \code{familiarData} objects.} \item{collection_name}{Name of the collection.} \item{...}{ - Arguments passed on to \code{\link[=.extract_data]{.extract_data}} + Arguments passed on to \code{\link{.extract_data}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} @@ -159,6 +159,9 @@ sample. vignette on performance metrics for the available metrics. If not provided explicitly, this parameter is read from settings used at creation of the underlying \code{familiarModel} objects.} + \item{\code{features}}{Features that should be considered for extracting information +from. Typically called in external workflows, e.g. for plotting. Internally, +i.e. from summon_familiar, this variable is not used.} \item{\code{feature_cluster_method}}{The method used to perform clustering. These are the same methods as for the \code{cluster_method} configuration parameter: \code{none}, \code{hclust}, \code{agnes}, \code{diana} and \code{pam}. diff --git a/man/as_familiar_data-methods.Rd b/man/as_familiar_data-methods.Rd index 7a743d23..c546309d 100644 --- a/man/as_familiar_data-methods.Rd +++ b/man/as_familiar_data-methods.Rd @@ -36,7 +36,7 @@ as_familiar_data(object, ...) \code{familiarData} object. Paths to such objects can also be provided.} \item{...}{ - Arguments passed on to \code{\link[=.extract_data]{.extract_data}} + Arguments passed on to \code{\link{.extract_data}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} @@ -86,6 +86,9 @@ sample. vignette on performance metrics for the available metrics. If not provided explicitly, this parameter is read from settings used at creation of the underlying \code{familiarModel} objects.} + \item{\code{features}}{Features that should be considered for extracting information +from. Typically called in external workflows, e.g. for plotting. Internally, +i.e. from summon_familiar, this variable is not used.} \item{\code{feature_cluster_method}}{The method used to perform clustering. These are the same methods as for the \code{cluster_method} configuration parameter: \code{none}, \code{hclust}, \code{agnes}, \code{diana} and \code{pam}. diff --git a/man/dot-extract_data.Rd b/man/dot-extract_data.Rd index 35f8cee7..61272dee 100644 --- a/man/dot-extract_data.Rd +++ b/man/dot-extract_data.Rd @@ -17,6 +17,7 @@ stratification_method = waiver(), evaluation_times = waiver(), metric = waiver(), + features = waiver(), feature_cluster_method = waiver(), feature_cluster_cut_method = waiver(), feature_linkage_method = waiver(), @@ -136,6 +137,10 @@ vignette on performance metrics for the available metrics. If not provided explicitly, this parameter is read from settings used at creation of the underlying \code{familiarModel} objects.} +\item{features}{Features that should be considered for extracting information +from. Typically called in external workflows, e.g. for plotting. Internally, +i.e. from summon_familiar, this variable is not used.} + \item{feature_cluster_method}{The method used to perform clustering. These are the same methods as for the \code{cluster_method} configuration parameter: \code{none}, \code{hclust}, \code{agnes}, \code{diana} and \code{pam}. diff --git a/man/dot-parse_general_settings.Rd b/man/dot-parse_general_settings.Rd index f242aa70..d35eb3d9 100644 --- a/man/dot-parse_general_settings.Rd +++ b/man/dot-parse_general_settings.Rd @@ -16,7 +16,7 @@ worklow} \item{data}{Data set as loaded using the \code{.load_data} function.} \item{...}{ - Arguments passed on to \code{\link[=.parse_setup_settings]{.parse_setup_settings}}, \code{\link[=.parse_preprocessing_settings]{.parse_preprocessing_settings}}, \code{\link[=.parse_variable_importance_settings]{.parse_variable_importance_settings}}, \code{\link[=.parse_model_development_settings]{.parse_model_development_settings}}, \code{\link[=.parse_hyperparameter_optimisation_settings]{.parse_hyperparameter_optimisation_settings}}, \code{\link[=.parse_evaluation_settings]{.parse_evaluation_settings}} + Arguments passed on to \code{\link{.parse_setup_settings}}, \code{\link{.parse_preprocessing_settings}}, \code{\link{.parse_variable_importance_settings}}, \code{\link{.parse_model_development_settings}}, \code{\link{.parse_hyperparameter_optimisation_settings}}, \code{\link{.parse_evaluation_settings}} \describe{ \item{\code{parallel}}{(\emph{optional}) Enable parallel processing. Defaults to \code{TRUE}. When set to \code{FALSE}, this disables all parallel processing, regardless of diff --git a/man/dot-parse_initial_settings.Rd b/man/dot-parse_initial_settings.Rd index 3ad9232d..953fcc35 100644 --- a/man/dot-parse_initial_settings.Rd +++ b/man/dot-parse_initial_settings.Rd @@ -11,7 +11,7 @@ define the experiment} \item{config}{A list of settings, e.g. from an xml file.} \item{...}{ - Arguments passed on to \code{\link[=.parse_experiment_settings]{.parse_experiment_settings}}, \code{\link[=.parse_setup_settings]{.parse_setup_settings}} + Arguments passed on to \code{\link{.parse_experiment_settings}}, \code{\link{.parse_setup_settings}} \describe{ \item{\code{batch_id_column}}{(\strong{recommended}) Name of the column containing batch or cohort identifiers. This parameter is required if more than one dataset diff --git a/man/export_all-methods.Rd b/man/export_all-methods.Rd index af389221..8e1782ad 100644 --- a/man/export_all-methods.Rd +++ b/man/export_all-methods.Rd @@ -23,7 +23,7 @@ will allow export as a structured list of data.tables.} aggregated for export.} \item{...}{ - Arguments passed on to \code{\link[=.extract_data]{.extract_data}}, \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{.extract_data}}, \code{\link{as_familiar_collection}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} @@ -73,6 +73,9 @@ sample. vignette on performance metrics for the available metrics. If not provided explicitly, this parameter is read from settings used at creation of the underlying \code{familiarModel} objects.} + \item{\code{features}}{Features that should be considered for extracting information +from. Typically called in external workflows, e.g. for plotting. Internally, +i.e. from summon_familiar, this variable is not used.} \item{\code{feature_cluster_method}}{The method used to perform clustering. These are the same methods as for the \code{cluster_method} configuration parameter: \code{none}, \code{hclust}, \code{agnes}, \code{diana} and \code{pam}. diff --git a/man/export_auc_data-methods.Rd b/man/export_auc_data-methods.Rd index dc1ab155..13ca3bce 100644 --- a/man/export_auc_data-methods.Rd +++ b/man/export_auc_data-methods.Rd @@ -43,7 +43,7 @@ aggregated for export.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_auc_data]{extract_auc_data}}, \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{extract_auc_data}}, \code{\link{as_familiar_collection}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} diff --git a/man/export_calibration_data-methods.Rd b/man/export_calibration_data-methods.Rd index e4d82312..5a18d987 100644 --- a/man/export_calibration_data-methods.Rd +++ b/man/export_calibration_data-methods.Rd @@ -43,7 +43,7 @@ aggregated for export.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_calibration_data]{extract_calibration_data}}, \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{extract_calibration_data}}, \code{\link{as_familiar_collection}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} diff --git a/man/export_calibration_info-methods.Rd b/man/export_calibration_info-methods.Rd index 31688d27..65c2d3f1 100644 --- a/man/export_calibration_info-methods.Rd +++ b/man/export_calibration_info-methods.Rd @@ -43,7 +43,7 @@ aggregated for export.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{as_familiar_collection}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/export_confusion_matrix_data-methods.Rd b/man/export_confusion_matrix_data-methods.Rd index 5794a2d6..c78c28e0 100644 --- a/man/export_confusion_matrix_data-methods.Rd +++ b/man/export_confusion_matrix_data-methods.Rd @@ -37,7 +37,7 @@ will allow export as a structured list of data.tables.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_confusion_matrix]{extract_confusion_matrix}}, \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{extract_confusion_matrix}}, \code{\link{as_familiar_collection}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} diff --git a/man/export_decision_curve_analysis_data-methods.Rd b/man/export_decision_curve_analysis_data-methods.Rd index e6ff8f5b..07239bbb 100644 --- a/man/export_decision_curve_analysis_data-methods.Rd +++ b/man/export_decision_curve_analysis_data-methods.Rd @@ -38,7 +38,7 @@ will allow export as a structured list of data.tables.} aggregated for export.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{as_familiar_collection}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/export_feature_expressions-methods.Rd b/man/export_feature_expressions-methods.Rd index 1bc4c81a..3323edf3 100644 --- a/man/export_feature_expressions-methods.Rd +++ b/man/export_feature_expressions-methods.Rd @@ -8,6 +8,7 @@ \usage{ export_feature_expressions( object, + features = waiver(), dir_path = NULL, evaluation_time = waiver(), export_collection = FALSE, @@ -16,6 +17,7 @@ export_feature_expressions( \S4method{export_feature_expressions}{familiarCollection}( object, + features = waiver(), dir_path = NULL, evaluation_time = waiver(), export_collection = FALSE, @@ -24,6 +26,7 @@ export_feature_expressions( \S4method{export_feature_expressions}{ANY}( object, + features = waiver(), dir_path = NULL, evaluation_time = waiver(), export_collection = FALSE, @@ -34,6 +37,9 @@ export_feature_expressions( \item{object}{A \code{familiarCollection} object, or other other objects from which a \code{familiarCollection} can be extracted. See details for more information.} +\item{features}{Features that should be exported. If \code{NULL} or \code{waiver()}, all +features exported (default).} + \item{dir_path}{Path to folder where extracted data should be saved. \code{NULL} will allow export as a structured list of data.tables.} @@ -45,7 +51,7 @@ parameter is read from settings used at creation of the underlying \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_feature_expression]{extract_feature_expression}}, \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[=as_data_object]{as_data_object}} + Arguments passed on to \code{\link{extract_feature_expression}}, \code{\link{as_familiar_collection}}, \code{\link{as_data_object}} \describe{ \item{\code{feature_similarity}}{Table containing pairwise distance between sample. This is used to determine cluster information, and indicate which @@ -120,6 +126,135 @@ computation and extraction of various data elements.} \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} \item{\code{collection_name}}{Name of the collection.} + \item{\code{check_stringency}}{Specifies stringency of various checks. This is mostly: +\itemize{ +\item \code{strict}: default value used for \code{summon_familiar}. Thoroughly checks +input data. Used internally for checking development data. +\item \code{external_warn}: value used for \code{extract_data} and related methods. Less +stringent checks, but will warn for possible issues. Used internally for +checking data for evaluation and explanation. +\item \code{external}: value used for external methods such as \code{predict}. Less +stringent checks, particularly for identifier and outcome columns, which may +be completely absent. Used internally for \code{predict}. +}} + \item{\code{.no_features_required}}{Internal flag to signify that data without +features is allowed. Default: FALSE (most processing steps require features).} + \item{\code{batch_id_column}}{(\strong{recommended}) Name of the column containing batch +or cohort identifiers. This parameter is required if more than one dataset +is provided, or if external validation is performed. + +In familiar any row of data is organised by four identifiers: +\itemize{ +\item The batch identifier \code{batch_id_column}: This denotes the group to which a +set of samples belongs, e.g. patients from a single study, samples measured +in a batch, etc. The batch identifier is used for batch normalisation, as +well as selection of development and validation datasets. +\item The sample identifier \code{sample_id_column}: This denotes the sample level, +e.g. data from a single individual. Subsets of data, e.g. bootstraps or +cross-validation folds, are created at this level. +\item The series identifier \code{series_id_column}: Indicates measurements on a +single sample that may not share the same outcome value, e.g. a time +series, or the number of cells in a view. +\item The repetition identifier: Indicates repeated measurements in a single +series where any feature values may differ, but the outcome does not. +Repetition identifiers are always implicitly set when multiple entries for +the same series of the same sample in the same batch that share the same +outcome are encountered. +}} + \item{\code{sample_id_column}}{(\strong{recommended}) Name of the column containing +sample or subject identifiers. See \code{batch_id_column} above for more +details. + +If unset, every row will be identified as a single sample.} + \item{\code{series_id_column}}{(\emph{optional}) Name of the column containing series +identifiers, which distinguish between measurements that are part of a +series for a single sample. See \code{batch_id_column} above for more details. + +If unset, rows which share the same batch and sample identifiers but have a +different outcome are assigned unique series identifiers.} + \item{\code{development_batch_id}}{(\emph{optional}) One or more batch or cohort +identifiers to constitute data sets for development. Defaults to all, or +all minus the identifiers in \code{validation_batch_id} for external validation. +Required if external validation is performed and \code{validation_batch_id} is +not provided.} + \item{\code{validation_batch_id}}{(\emph{optional}) One or more batch or cohort +identifiers to constitute data sets for external validation. Defaults to +all data sets except those in \code{development_batch_id} for external +validation, or none if not. Required if \code{development_batch_id} is not +provided.} + \item{\code{outcome_name}}{(\emph{optional}) Name of the modelled outcome. This name will +be used in figures created by \code{familiar}. + +If not set, the column name in \code{outcome_column} will be used for +\code{binomial}, \code{multinomial}, and \code{continuous} outcomes. For other outcomes +(\code{survival} and \code{competing_risk}) no default is used.} + \item{\code{outcome_column}}{(\strong{recommended}) Name of the column containing the +outcome of interest. May be identified from a formula, if a formula is +provided as an argument. Otherwise an error is raised. Note that \code{survival} +and \code{competing_risk} outcome type outcomes require two columns that +indicate the time-to-event or the time of last follow-up and the event +status.} + \item{\code{outcome_type}}{(\strong{recommended}) Type of outcome found in the outcome +column. The outcome type determines many aspects of the overall process, +e.g. the available variable importance methods and learners, but also the +type of assessments that can be conducted to evaluate the resulting models. +Implemented outcome types are: +\itemize{ +\item \code{binomial}: categorical outcome with 2 levels. +\item \code{multinomial}: categorical outcome with 2 or more levels. +\item \code{continuous}: general continuous numeric outcomes. +\item \code{survival}: survival outcome for time-to-event data. +} + +If not provided, the algorithm will attempt to obtain outcome_type from +contents of the outcome column. This may lead to unexpected results, and we +therefore advise to provide this information manually. + +Note that \code{competing_risk} survival analysis are not fully supported, and +is currently not a valid choice for \code{outcome_type}. The \code{count} outcome +type was deprecated in version 2.0.0, and superseded by \code{continuous}.} + \item{\code{class_levels}}{(\emph{optional}) Class levels for \code{binomial} or \code{multinomial} +outcomes. This argument can be used to specify the ordering of levels for +categorical outcomes. These class levels must exactly match the levels +present in the outcome column.} + \item{\code{event_indicator}}{(\strong{recommended}) Indicator for events in \code{survival} +and \code{competing_risk} analyses. \code{familiar} will automatically recognise \code{1}, +\code{true}, \code{t}, \code{y} and \code{yes} as event indicators, including different +capitalisations. If this parameter is set, it replaces the default values.} + \item{\code{censoring_indicator}}{(\strong{recommended}) Indicator for right-censoring in +\code{survival} and \code{competing_risk} analyses. \code{familiar} will automatically +recognise \code{0}, \code{false}, \code{f}, \code{n}, \code{no} as censoring indicators, including +different capitalisations. If this parameter is set, it replaces the +default values.} + \item{\code{competing_risk_indicator}}{(\strong{recommended}) Indicator for competing +risks in \code{competing_risk} analyses. There are no default values, and if +unset, all values other than those specified by the \code{event_indicator} and +\code{censoring_indicator} parameters are considered to indicate competing +risks.} + \item{\code{exclude_features}}{(\emph{optional}) Feature columns that will be removed +from the data set. Cannot overlap with features in \code{signature}, +\code{novelty_features} or \code{include_features}.} + \item{\code{include_features}}{(\emph{optional}) Feature columns that are specifically +included in the data set. By default all features are included. Cannot +overlap with \code{exclude_features}, but may overlap \code{signature}. Features in +\code{signature} and \code{novelty_features} are always included. If both +\code{exclude_features} and \code{include_features} are provided, \code{include_features} +takes precedence, provided that there is no overlap between the two.} + \item{\code{reference_method}}{(\emph{optional}) Method used to set reference levels for +categorical features. There are several options: +\itemize{ +\item \code{auto} (default): Categorical features that are not explicitly set by the +user, i.e. columns containing boolean values or characters, use the most +frequent level as reference. Categorical features that are explicitly set, +i.e. as factors, are used as is. +\item \code{always}: Both automatically detected and user-specified categorical +features have the reference level set to the most frequent level. Ordinal +features are not altered, but are used as is. +\item \code{never}: User-specified categorical features are used as is. +Automatically detected categorical features are simply sorted, and the +first level is then used as the reference level. This was the behaviour +prior to familiar version 1.3.0. +}} }} } \value{ diff --git a/man/export_feature_similarity-methods.Rd b/man/export_feature_similarity-methods.Rd index badf3b6a..ea708ea8 100644 --- a/man/export_feature_similarity-methods.Rd +++ b/man/export_feature_similarity-methods.Rd @@ -10,6 +10,7 @@ export_feature_similarity( object, dir_path = NULL, aggregate_results = TRUE, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -25,6 +26,7 @@ export_feature_similarity( object, dir_path = NULL, aggregate_results = TRUE, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -40,6 +42,7 @@ export_feature_similarity( object, dir_path = NULL, aggregate_results = TRUE, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -61,6 +64,10 @@ will allow export as a structured list of data.tables.} \item{aggregate_results}{Flag that signifies whether results should be aggregated for export.} +\item{features}{Features that should be considered for extracting information +from. Typically called in external workflows, e.g. for plotting. Internally, +i.e. from summon_familiar, this variable is not used.} + \item{feature_cluster_method}{The method used to perform clustering. These are the same methods as for the \code{cluster_method} configuration parameter: \code{none}, \code{hclust}, \code{agnes}, \code{diana} and \code{pam}. @@ -109,7 +116,7 @@ element objects.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[=as_data_object]{as_data_object}} + Arguments passed on to \code{\link{as_familiar_collection}}, \code{\link{as_data_object}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} @@ -117,6 +124,135 @@ parameter is one or more \code{familiarData} objects.} \item{\code{data}}{A \code{data.frame} or \code{data.table}, a path to such tables on a local or network drive, or a path to tabular data that may be converted to these formats.} + \item{\code{check_stringency}}{Specifies stringency of various checks. This is mostly: +\itemize{ +\item \code{strict}: default value used for \code{summon_familiar}. Thoroughly checks +input data. Used internally for checking development data. +\item \code{external_warn}: value used for \code{extract_data} and related methods. Less +stringent checks, but will warn for possible issues. Used internally for +checking data for evaluation and explanation. +\item \code{external}: value used for external methods such as \code{predict}. Less +stringent checks, particularly for identifier and outcome columns, which may +be completely absent. Used internally for \code{predict}. +}} + \item{\code{.no_features_required}}{Internal flag to signify that data without +features is allowed. Default: FALSE (most processing steps require features).} + \item{\code{batch_id_column}}{(\strong{recommended}) Name of the column containing batch +or cohort identifiers. This parameter is required if more than one dataset +is provided, or if external validation is performed. + +In familiar any row of data is organised by four identifiers: +\itemize{ +\item The batch identifier \code{batch_id_column}: This denotes the group to which a +set of samples belongs, e.g. patients from a single study, samples measured +in a batch, etc. The batch identifier is used for batch normalisation, as +well as selection of development and validation datasets. +\item The sample identifier \code{sample_id_column}: This denotes the sample level, +e.g. data from a single individual. Subsets of data, e.g. bootstraps or +cross-validation folds, are created at this level. +\item The series identifier \code{series_id_column}: Indicates measurements on a +single sample that may not share the same outcome value, e.g. a time +series, or the number of cells in a view. +\item The repetition identifier: Indicates repeated measurements in a single +series where any feature values may differ, but the outcome does not. +Repetition identifiers are always implicitly set when multiple entries for +the same series of the same sample in the same batch that share the same +outcome are encountered. +}} + \item{\code{sample_id_column}}{(\strong{recommended}) Name of the column containing +sample or subject identifiers. See \code{batch_id_column} above for more +details. + +If unset, every row will be identified as a single sample.} + \item{\code{series_id_column}}{(\emph{optional}) Name of the column containing series +identifiers, which distinguish between measurements that are part of a +series for a single sample. See \code{batch_id_column} above for more details. + +If unset, rows which share the same batch and sample identifiers but have a +different outcome are assigned unique series identifiers.} + \item{\code{development_batch_id}}{(\emph{optional}) One or more batch or cohort +identifiers to constitute data sets for development. Defaults to all, or +all minus the identifiers in \code{validation_batch_id} for external validation. +Required if external validation is performed and \code{validation_batch_id} is +not provided.} + \item{\code{validation_batch_id}}{(\emph{optional}) One or more batch or cohort +identifiers to constitute data sets for external validation. Defaults to +all data sets except those in \code{development_batch_id} for external +validation, or none if not. Required if \code{development_batch_id} is not +provided.} + \item{\code{outcome_name}}{(\emph{optional}) Name of the modelled outcome. This name will +be used in figures created by \code{familiar}. + +If not set, the column name in \code{outcome_column} will be used for +\code{binomial}, \code{multinomial}, and \code{continuous} outcomes. For other outcomes +(\code{survival} and \code{competing_risk}) no default is used.} + \item{\code{outcome_column}}{(\strong{recommended}) Name of the column containing the +outcome of interest. May be identified from a formula, if a formula is +provided as an argument. Otherwise an error is raised. Note that \code{survival} +and \code{competing_risk} outcome type outcomes require two columns that +indicate the time-to-event or the time of last follow-up and the event +status.} + \item{\code{outcome_type}}{(\strong{recommended}) Type of outcome found in the outcome +column. The outcome type determines many aspects of the overall process, +e.g. the available variable importance methods and learners, but also the +type of assessments that can be conducted to evaluate the resulting models. +Implemented outcome types are: +\itemize{ +\item \code{binomial}: categorical outcome with 2 levels. +\item \code{multinomial}: categorical outcome with 2 or more levels. +\item \code{continuous}: general continuous numeric outcomes. +\item \code{survival}: survival outcome for time-to-event data. +} + +If not provided, the algorithm will attempt to obtain outcome_type from +contents of the outcome column. This may lead to unexpected results, and we +therefore advise to provide this information manually. + +Note that \code{competing_risk} survival analysis are not fully supported, and +is currently not a valid choice for \code{outcome_type}. The \code{count} outcome +type was deprecated in version 2.0.0, and superseded by \code{continuous}.} + \item{\code{class_levels}}{(\emph{optional}) Class levels for \code{binomial} or \code{multinomial} +outcomes. This argument can be used to specify the ordering of levels for +categorical outcomes. These class levels must exactly match the levels +present in the outcome column.} + \item{\code{event_indicator}}{(\strong{recommended}) Indicator for events in \code{survival} +and \code{competing_risk} analyses. \code{familiar} will automatically recognise \code{1}, +\code{true}, \code{t}, \code{y} and \code{yes} as event indicators, including different +capitalisations. If this parameter is set, it replaces the default values.} + \item{\code{censoring_indicator}}{(\strong{recommended}) Indicator for right-censoring in +\code{survival} and \code{competing_risk} analyses. \code{familiar} will automatically +recognise \code{0}, \code{false}, \code{f}, \code{n}, \code{no} as censoring indicators, including +different capitalisations. If this parameter is set, it replaces the +default values.} + \item{\code{competing_risk_indicator}}{(\strong{recommended}) Indicator for competing +risks in \code{competing_risk} analyses. There are no default values, and if +unset, all values other than those specified by the \code{event_indicator} and +\code{censoring_indicator} parameters are considered to indicate competing +risks.} + \item{\code{exclude_features}}{(\emph{optional}) Feature columns that will be removed +from the data set. Cannot overlap with features in \code{signature}, +\code{novelty_features} or \code{include_features}.} + \item{\code{include_features}}{(\emph{optional}) Feature columns that are specifically +included in the data set. By default all features are included. Cannot +overlap with \code{exclude_features}, but may overlap \code{signature}. Features in +\code{signature} and \code{novelty_features} are always included. If both +\code{exclude_features} and \code{include_features} are provided, \code{include_features} +takes precedence, provided that there is no overlap between the two.} + \item{\code{reference_method}}{(\emph{optional}) Method used to set reference levels for +categorical features. There are several options: +\itemize{ +\item \code{auto} (default): Categorical features that are not explicitly set by the +user, i.e. columns containing boolean values or characters, use the most +frequent level as reference. Categorical features that are explicitly set, +i.e. as factors, are used as is. +\item \code{always}: Both automatically detected and user-specified categorical +features have the reference level set to the most frequent level. Ordinal +features are not altered, but are used as is. +\item \code{never}: User-specified categorical features are used as is. +Automatically detected categorical features are simply sorted, and the +first level is then used as the reference level. This was the behaviour +prior to familiar version 1.3.0. +}} }} } \value{ diff --git a/man/export_fs_vimp-methods.Rd b/man/export_fs_vimp-methods.Rd index 4b92129c..f6c6136d 100644 --- a/man/export_fs_vimp-methods.Rd +++ b/man/export_fs_vimp-methods.Rd @@ -86,7 +86,7 @@ This parameter is only relevant for \code{stability}, \code{exponential}, \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{as_familiar_collection}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/export_hyperparameters-methods.Rd b/man/export_hyperparameters-methods.Rd index d19b276f..e036ed0e 100644 --- a/man/export_hyperparameters-methods.Rd +++ b/man/export_hyperparameters-methods.Rd @@ -43,7 +43,7 @@ aggregated for export.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{as_familiar_collection}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/export_ice_data-methods.Rd b/man/export_ice_data-methods.Rd index edbd4020..84af2e4c 100644 --- a/man/export_ice_data-methods.Rd +++ b/man/export_ice_data-methods.Rd @@ -43,7 +43,7 @@ aggregated for export.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_ice]{extract_ice}}, \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{extract_ice}}, \code{\link{as_familiar_collection}} \describe{ \item{\code{features}}{Names of the feature or features (2) assessed simultaneously. By default \code{NULL}, which means that all features are assessed one-by-one.} diff --git a/man/export_model_performance-methods.Rd b/man/export_model_performance-methods.Rd index 0075ae32..129e1d43 100644 --- a/man/export_model_performance-methods.Rd +++ b/man/export_model_performance-methods.Rd @@ -43,7 +43,7 @@ aggregated for export.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_performance]{extract_performance}}, \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{extract_performance}}, \code{\link{as_familiar_collection}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} diff --git a/man/export_model_vimp-methods.Rd b/man/export_model_vimp-methods.Rd index 3197a319..d0060fd9 100644 --- a/man/export_model_vimp-methods.Rd +++ b/man/export_model_vimp-methods.Rd @@ -86,7 +86,7 @@ This parameter is only relevant for \code{stability}, \code{exponential}, \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{as_familiar_collection}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/export_partial_dependence_data-methods.Rd b/man/export_partial_dependence_data-methods.Rd index c83ad430..4b69fa82 100644 --- a/man/export_partial_dependence_data-methods.Rd +++ b/man/export_partial_dependence_data-methods.Rd @@ -43,7 +43,7 @@ aggregated for export.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_ice]{extract_ice}}, \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{extract_ice}}, \code{\link{as_familiar_collection}} \describe{ \item{\code{features}}{Names of the feature or features (2) assessed simultaneously. By default \code{NULL}, which means that all features are assessed one-by-one.} diff --git a/man/export_permutation_vimp-methods.Rd b/man/export_permutation_vimp-methods.Rd index 34b985d4..af973ddb 100644 --- a/man/export_permutation_vimp-methods.Rd +++ b/man/export_permutation_vimp-methods.Rd @@ -43,7 +43,7 @@ aggregated for export.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_permutation_vimp]{extract_permutation_vimp}}, \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{extract_permutation_vimp}}, \code{\link{as_familiar_collection}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} diff --git a/man/export_prediction_data-methods.Rd b/man/export_prediction_data-methods.Rd index c7944480..07788c7f 100644 --- a/man/export_prediction_data-methods.Rd +++ b/man/export_prediction_data-methods.Rd @@ -23,7 +23,7 @@ will allow export as a structured list of data.tables.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_predictions]{extract_predictions}}, \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{extract_predictions}}, \code{\link{as_familiar_collection}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} diff --git a/man/export_risk_stratification_data-methods.Rd b/man/export_risk_stratification_data-methods.Rd index 1b469ecd..e28cdfcd 100644 --- a/man/export_risk_stratification_data-methods.Rd +++ b/man/export_risk_stratification_data-methods.Rd @@ -1,5 +1,6 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/FamiliarDataComputationRiskStratificationData.R +% Please edit documentation in +% R/FamiliarDataComputationRiskStratificationData.R \name{export_risk_stratification_data} \alias{export_risk_stratification_data} \alias{export_risk_stratification_data,familiarCollection-method} @@ -50,7 +51,7 @@ the full time range is used.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_risk_stratification_data]{extract_risk_stratification_data}}, \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{extract_risk_stratification_data}}, \code{\link{as_familiar_collection}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} diff --git a/man/export_risk_stratification_info-methods.Rd b/man/export_risk_stratification_info-methods.Rd index 3f3b3e7d..e888ca80 100644 --- a/man/export_risk_stratification_info-methods.Rd +++ b/man/export_risk_stratification_info-methods.Rd @@ -1,5 +1,6 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/FamiliarDataComputationRiskStratificationInfo.R +% Please edit documentation in +% R/FamiliarDataComputationRiskStratificationInfo.R \name{export_risk_stratification_info} \alias{export_risk_stratification_info} \alias{export_risk_stratification_info,familiarCollection-method} @@ -43,7 +44,7 @@ aggregated for export.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{as_familiar_collection}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/export_sample_similarity-methods.Rd b/man/export_sample_similarity-methods.Rd index 5f1dab42..1a69d1fd 100644 --- a/man/export_sample_similarity-methods.Rd +++ b/man/export_sample_similarity-methods.Rd @@ -85,7 +85,7 @@ creation of the underlying \code{familiarModel} objects.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[=as_data_object]{as_data_object}} + Arguments passed on to \code{\link{as_familiar_collection}}, \code{\link{as_data_object}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} @@ -93,6 +93,135 @@ parameter is one or more \code{familiarData} objects.} \item{\code{data}}{A \code{data.frame} or \code{data.table}, a path to such tables on a local or network drive, or a path to tabular data that may be converted to these formats.} + \item{\code{check_stringency}}{Specifies stringency of various checks. This is mostly: +\itemize{ +\item \code{strict}: default value used for \code{summon_familiar}. Thoroughly checks +input data. Used internally for checking development data. +\item \code{external_warn}: value used for \code{extract_data} and related methods. Less +stringent checks, but will warn for possible issues. Used internally for +checking data for evaluation and explanation. +\item \code{external}: value used for external methods such as \code{predict}. Less +stringent checks, particularly for identifier and outcome columns, which may +be completely absent. Used internally for \code{predict}. +}} + \item{\code{.no_features_required}}{Internal flag to signify that data without +features is allowed. Default: FALSE (most processing steps require features).} + \item{\code{batch_id_column}}{(\strong{recommended}) Name of the column containing batch +or cohort identifiers. This parameter is required if more than one dataset +is provided, or if external validation is performed. + +In familiar any row of data is organised by four identifiers: +\itemize{ +\item The batch identifier \code{batch_id_column}: This denotes the group to which a +set of samples belongs, e.g. patients from a single study, samples measured +in a batch, etc. The batch identifier is used for batch normalisation, as +well as selection of development and validation datasets. +\item The sample identifier \code{sample_id_column}: This denotes the sample level, +e.g. data from a single individual. Subsets of data, e.g. bootstraps or +cross-validation folds, are created at this level. +\item The series identifier \code{series_id_column}: Indicates measurements on a +single sample that may not share the same outcome value, e.g. a time +series, or the number of cells in a view. +\item The repetition identifier: Indicates repeated measurements in a single +series where any feature values may differ, but the outcome does not. +Repetition identifiers are always implicitly set when multiple entries for +the same series of the same sample in the same batch that share the same +outcome are encountered. +}} + \item{\code{sample_id_column}}{(\strong{recommended}) Name of the column containing +sample or subject identifiers. See \code{batch_id_column} above for more +details. + +If unset, every row will be identified as a single sample.} + \item{\code{series_id_column}}{(\emph{optional}) Name of the column containing series +identifiers, which distinguish between measurements that are part of a +series for a single sample. See \code{batch_id_column} above for more details. + +If unset, rows which share the same batch and sample identifiers but have a +different outcome are assigned unique series identifiers.} + \item{\code{development_batch_id}}{(\emph{optional}) One or more batch or cohort +identifiers to constitute data sets for development. Defaults to all, or +all minus the identifiers in \code{validation_batch_id} for external validation. +Required if external validation is performed and \code{validation_batch_id} is +not provided.} + \item{\code{validation_batch_id}}{(\emph{optional}) One or more batch or cohort +identifiers to constitute data sets for external validation. Defaults to +all data sets except those in \code{development_batch_id} for external +validation, or none if not. Required if \code{development_batch_id} is not +provided.} + \item{\code{outcome_name}}{(\emph{optional}) Name of the modelled outcome. This name will +be used in figures created by \code{familiar}. + +If not set, the column name in \code{outcome_column} will be used for +\code{binomial}, \code{multinomial}, and \code{continuous} outcomes. For other outcomes +(\code{survival} and \code{competing_risk}) no default is used.} + \item{\code{outcome_column}}{(\strong{recommended}) Name of the column containing the +outcome of interest. May be identified from a formula, if a formula is +provided as an argument. Otherwise an error is raised. Note that \code{survival} +and \code{competing_risk} outcome type outcomes require two columns that +indicate the time-to-event or the time of last follow-up and the event +status.} + \item{\code{outcome_type}}{(\strong{recommended}) Type of outcome found in the outcome +column. The outcome type determines many aspects of the overall process, +e.g. the available variable importance methods and learners, but also the +type of assessments that can be conducted to evaluate the resulting models. +Implemented outcome types are: +\itemize{ +\item \code{binomial}: categorical outcome with 2 levels. +\item \code{multinomial}: categorical outcome with 2 or more levels. +\item \code{continuous}: general continuous numeric outcomes. +\item \code{survival}: survival outcome for time-to-event data. +} + +If not provided, the algorithm will attempt to obtain outcome_type from +contents of the outcome column. This may lead to unexpected results, and we +therefore advise to provide this information manually. + +Note that \code{competing_risk} survival analysis are not fully supported, and +is currently not a valid choice for \code{outcome_type}. The \code{count} outcome +type was deprecated in version 2.0.0, and superseded by \code{continuous}.} + \item{\code{class_levels}}{(\emph{optional}) Class levels for \code{binomial} or \code{multinomial} +outcomes. This argument can be used to specify the ordering of levels for +categorical outcomes. These class levels must exactly match the levels +present in the outcome column.} + \item{\code{event_indicator}}{(\strong{recommended}) Indicator for events in \code{survival} +and \code{competing_risk} analyses. \code{familiar} will automatically recognise \code{1}, +\code{true}, \code{t}, \code{y} and \code{yes} as event indicators, including different +capitalisations. If this parameter is set, it replaces the default values.} + \item{\code{censoring_indicator}}{(\strong{recommended}) Indicator for right-censoring in +\code{survival} and \code{competing_risk} analyses. \code{familiar} will automatically +recognise \code{0}, \code{false}, \code{f}, \code{n}, \code{no} as censoring indicators, including +different capitalisations. If this parameter is set, it replaces the +default values.} + \item{\code{competing_risk_indicator}}{(\strong{recommended}) Indicator for competing +risks in \code{competing_risk} analyses. There are no default values, and if +unset, all values other than those specified by the \code{event_indicator} and +\code{censoring_indicator} parameters are considered to indicate competing +risks.} + \item{\code{exclude_features}}{(\emph{optional}) Feature columns that will be removed +from the data set. Cannot overlap with features in \code{signature}, +\code{novelty_features} or \code{include_features}.} + \item{\code{include_features}}{(\emph{optional}) Feature columns that are specifically +included in the data set. By default all features are included. Cannot +overlap with \code{exclude_features}, but may overlap \code{signature}. Features in +\code{signature} and \code{novelty_features} are always included. If both +\code{exclude_features} and \code{include_features} are provided, \code{include_features} +takes precedence, provided that there is no overlap between the two.} + \item{\code{reference_method}}{(\emph{optional}) Method used to set reference levels for +categorical features. There are several options: +\itemize{ +\item \code{auto} (default): Categorical features that are not explicitly set by the +user, i.e. columns containing boolean values or characters, use the most +frequent level as reference. Categorical features that are explicitly set, +i.e. as factors, are used as is. +\item \code{always}: Both automatically detected and user-specified categorical +features have the reference level set to the most frequent level. Ordinal +features are not altered, but are used as is. +\item \code{never}: User-specified categorical features are used as is. +Automatically detected categorical features are simply sorted, and the +first level is then used as the reference level. This was the behaviour +prior to familiar version 1.3.0. +}} }} } \value{ diff --git a/man/export_shap-methods.Rd b/man/export_shap-methods.Rd index dd72e897..633c8aa7 100644 --- a/man/export_shap-methods.Rd +++ b/man/export_shap-methods.Rd @@ -55,7 +55,7 @@ determining dependence.} interaction with the feature(s) in \code{feature_x}.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{as_familiar_collection}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/export_univariate_analysis_data-methods.Rd b/man/export_univariate_analysis_data-methods.Rd index 57f9c806..ecbfacfa 100644 --- a/man/export_univariate_analysis_data-methods.Rd +++ b/man/export_univariate_analysis_data-methods.Rd @@ -45,7 +45,7 @@ p-values} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_univariate_analysis]{extract_univariate_analysis}}, \code{\link[=as_familiar_collection]{as_familiar_collection}} + Arguments passed on to \code{\link{extract_univariate_analysis}}, \code{\link{as_familiar_collection}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} diff --git a/man/extract_feature_similarity.Rd b/man/extract_feature_similarity.Rd index b30ae2b9..8e2ea1a8 100644 --- a/man/extract_feature_similarity.Rd +++ b/man/extract_feature_similarity.Rd @@ -13,6 +13,7 @@ extract_feature_similarity( confidence_level = waiver(), bootstrap_ci_method = waiver(), is_pre_processed = FALSE, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -95,6 +96,8 @@ accelerated (BCa) method is not implemented yet.} pre-processed externally, e.g. normalised and clustered. Only used if the \code{data} argument is a \code{data.table} or \code{data.frame}.} +\item{features}{(\emph{optional}) Features for which feature similarity is computed.} + \item{feature_cluster_method}{The method used to perform clustering. These are the same methods as for the \code{cluster_method} configuration parameter: \code{none}, \code{hclust}, \code{agnes}, \code{diana} and \code{pam}. diff --git a/man/extract_risk_stratification_data.Rd b/man/extract_risk_stratification_data.Rd index 09bd975e..6798580a 100644 --- a/man/extract_risk_stratification_data.Rd +++ b/man/extract_risk_stratification_data.Rd @@ -1,5 +1,6 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/FamiliarDataComputationRiskStratificationData.R +% Please edit documentation in +% R/FamiliarDataComputationRiskStratificationData.R \name{extract_risk_stratification_data} \alias{extract_risk_stratification_data} \title{Internal function to extract stratification data.} diff --git a/man/extract_risk_stratification_info.Rd b/man/extract_risk_stratification_info.Rd index 1fcb0867..b3bc0754 100644 --- a/man/extract_risk_stratification_info.Rd +++ b/man/extract_risk_stratification_info.Rd @@ -1,5 +1,6 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/FamiliarDataComputationRiskStratificationInfo.R +% Please edit documentation in +% R/FamiliarDataComputationRiskStratificationInfo.R \name{extract_risk_stratification_info} \alias{extract_risk_stratification_info} \title{Internal function to extract risk stratification info from data.} diff --git a/man/extract_sample_similarity.Rd b/man/extract_sample_similarity.Rd index 5e47c79b..8154bf32 100644 --- a/man/extract_sample_similarity.Rd +++ b/man/extract_sample_similarity.Rd @@ -9,6 +9,7 @@ extract_sample_similarity( data, cl = NULL, is_pre_processed = FALSE, + features = waiver(), sample_limit = waiver(), sample_cluster_method = waiver(), sample_linkage_method = waiver(), @@ -33,6 +34,10 @@ used to speed up computation through parallellisation.} pre-processed externally, e.g. normalised and clustered. Only used if the \code{data} argument is a \code{data.table} or \code{data.frame}.} +\item{features}{Features that should be considered for extracting information +from. Typically called in external workflows, e.g. for plotting. Internally, +i.e. from summon_familiar, this variable is not used.} + \item{sample_limit}{(\emph{optional}) Set the upper limit of the number of samples that are used during evaluation steps. Cannot be fewer than 20. diff --git a/man/familiar.Rd b/man/familiar.Rd index cdbf7a1f..97aa7108 100644 --- a/man/familiar.Rd +++ b/man/familiar.Rd @@ -34,6 +34,7 @@ Useful links: Authors: \itemize{ + \item Alex Zwanenburg \email{alexander.zwanenburg@nct-dresden.de} (\href{https://orcid.org/0000-0002-0342-9545}{ORCID}) \item Steffen Löck } diff --git a/man/plot_auc_precision_recall_curve-methods.Rd b/man/plot_auc_precision_recall_curve-methods.Rd index b04e4c1c..996844aa 100644 --- a/man/plot_auc_precision_recall_curve-methods.Rd +++ b/man/plot_auc_precision_recall_curve-methods.Rd @@ -193,7 +193,7 @@ from the number of features and the number of facets.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}} + Arguments passed on to \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/plot_auc_roc_curve-methods.Rd b/man/plot_auc_roc_curve-methods.Rd index 865c54c1..c86c597c 100644 --- a/man/plot_auc_roc_curve-methods.Rd +++ b/man/plot_auc_roc_curve-methods.Rd @@ -193,7 +193,7 @@ from the number of features and the number of facets.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link[=extract_auc_data]{extract_auc_data}} + Arguments passed on to \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link{extract_auc_data}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/plot_calibration_data-methods.Rd b/man/plot_calibration_data-methods.Rd index 6b234589..c7dd6133 100644 --- a/man/plot_calibration_data-methods.Rd +++ b/man/plot_calibration_data-methods.Rd @@ -258,7 +258,7 @@ from the number of features and the number of facets.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link[=extract_calibration_data]{extract_calibration_data}} + Arguments passed on to \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link{extract_calibration_data}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/plot_confusion_matrix-methods.Rd b/man/plot_confusion_matrix-methods.Rd index dad5d2b0..713869b0 100644 --- a/man/plot_confusion_matrix-methods.Rd +++ b/man/plot_confusion_matrix-methods.Rd @@ -177,7 +177,7 @@ from the number of features and the number of facets.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link[=extract_confusion_matrix]{extract_confusion_matrix}} + Arguments passed on to \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link{extract_confusion_matrix}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/plot_decision_curve-methods.Rd b/man/plot_decision_curve-methods.Rd index 2ca03e0d..e1262fb2 100644 --- a/man/plot_decision_curve-methods.Rd +++ b/man/plot_decision_curve-methods.Rd @@ -203,7 +203,7 @@ from the number of features and the number of facets.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link[=extract_decision_curve_data]{extract_decision_curve_data}} + Arguments passed on to \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link{extract_decision_curve_data}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/plot_feature_similarity-methods.Rd b/man/plot_feature_similarity-methods.Rd index 2e72e990..2d615a46 100644 --- a/man/plot_feature_similarity-methods.Rd +++ b/man/plot_feature_similarity-methods.Rd @@ -8,6 +8,7 @@ \usage{ plot_feature_similarity( object, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -32,6 +33,7 @@ plot_feature_similarity( y_n_breaks = 3L, y_breaks = NULL, rotate_x_tick_labels = waiver(), + remove_feature_labels = FALSE, show_dendrogram = c("top", "right"), dendrogram_height = grid::unit(1.5, "cm"), width = waiver(), @@ -43,6 +45,7 @@ plot_feature_similarity( \S4method{plot_feature_similarity}{ANY}( object, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -67,6 +70,7 @@ plot_feature_similarity( y_n_breaks = 3L, y_breaks = NULL, rotate_x_tick_labels = waiver(), + remove_feature_labels = FALSE, show_dendrogram = c("top", "right"), dendrogram_height = grid::unit(1.5, "cm"), width = waiver(), @@ -78,6 +82,7 @@ plot_feature_similarity( \S4method{plot_feature_similarity}{familiarCollection}( object, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), feature_cluster_cut_method = waiver(), @@ -102,6 +107,7 @@ plot_feature_similarity( y_n_breaks = 3L, y_breaks = NULL, rotate_x_tick_labels = waiver(), + remove_feature_labels = FALSE, show_dendrogram = c("top", "right"), dendrogram_height = grid::unit(1.5, "cm"), width = waiver(), @@ -115,6 +121,10 @@ plot_feature_similarity( \item{object}{A \code{familiarCollection} object, or other other objects from which a \code{familiarCollection} can be extracted. See details for more information.} +\item{features}{Features that should be considered for extracting information +from. Typically called in external workflows, e.g. for plotting. Internally, +i.e. from summon_familiar, this variable is not used.} + \item{feature_cluster_method}{The method used to perform clustering. These are the same methods as for the \code{cluster_method} configuration parameter: \code{none}, \code{hclust}, \code{agnes}, \code{diana} and \code{pam}. @@ -243,6 +253,9 @@ is unset.} controlled through the \code{ggtheme}. In this case, \code{FALSE} should be provided explicitly.} +\item{remove_feature_labels}{(\emph{optional}) If \code{TRUE}, feature labels are not +shown. By default, feature labels are shown.} + \item{show_dendrogram}{(\emph{optional}) Show dendrogram around the main panel. Can be \code{TRUE}, \code{FALSE}, \code{NULL}, or a position, i.e. \code{top}, \code{bottom}, \code{left} and \code{right}. Up to two positions may be provided, but only as long as the @@ -271,7 +284,7 @@ from the number of features and the number of facets.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link[=extract_feature_similarity]{extract_feature_similarity}} + Arguments passed on to \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link{extract_feature_similarity}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/plot_ice-methods.Rd b/man/plot_ice-methods.Rd index 77abff6a..397cfd6d 100644 --- a/man/plot_ice-methods.Rd +++ b/man/plot_ice-methods.Rd @@ -310,7 +310,7 @@ from the number of features and the number of facets.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=export_ice_data]{export_ice_data}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link[=extract_ice]{extract_ice}} + Arguments passed on to \code{\link{export_ice_data}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link{extract_ice}} \describe{ \item{\code{aggregate_results}}{Flag that signifies whether results should be aggregated for export.} diff --git a/man/plot_kaplan_meier-methods.Rd b/man/plot_kaplan_meier-methods.Rd index d38f39ae..01e5480d 100644 --- a/man/plot_kaplan_meier-methods.Rd +++ b/man/plot_kaplan_meier-methods.Rd @@ -279,7 +279,7 @@ from number of facets and the inclusion of survival tables.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link[=extract_risk_stratification_data]{extract_risk_stratification_data}} + Arguments passed on to \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link{extract_risk_stratification_data}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/plot_model_performance-methods.Rd b/man/plot_model_performance-methods.Rd index 5c982499..d3e307b6 100644 --- a/man/plot_model_performance-methods.Rd +++ b/man/plot_model_performance-methods.Rd @@ -236,7 +236,7 @@ or \code{value_ci} (median value plus 95\% credibility intervals).} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_performance]{extract_performance}}, \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}} + Arguments passed on to \code{\link{extract_performance}}, \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} diff --git a/man/plot_pd-methods.Rd b/man/plot_pd-methods.Rd index 0fcd6b95..aad47ce9 100644 --- a/man/plot_pd-methods.Rd +++ b/man/plot_pd-methods.Rd @@ -241,7 +241,7 @@ from the number of features and the number of facets.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=export_ice_data]{export_ice_data}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link[=extract_ice]{extract_ice}} + Arguments passed on to \code{\link{export_ice_data}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link{extract_ice}} \describe{ \item{\code{aggregate_results}}{Flag that signifies whether results should be aggregated for export.} diff --git a/man/plot_permutation_variable_importance-methods.Rd b/man/plot_permutation_variable_importance-methods.Rd index 84d5cc0d..7b0517e0 100644 --- a/man/plot_permutation_variable_importance-methods.Rd +++ b/man/plot_permutation_variable_importance-methods.Rd @@ -192,7 +192,7 @@ from the number of features and the number of facets.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link[=extract_permutation_vimp]{extract_permutation_vimp}} + Arguments passed on to \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link{extract_permutation_vimp}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/plot_sample_clustering-methods.Rd b/man/plot_sample_clustering-methods.Rd index d4d0b698..7c8deea7 100644 --- a/man/plot_sample_clustering-methods.Rd +++ b/man/plot_sample_clustering-methods.Rd @@ -8,6 +8,7 @@ \usage{ plot_sample_clustering( object, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), sample_cluster_method = waiver(), @@ -41,6 +42,8 @@ plot_sample_clustering( y_n_breaks = 3L, y_breaks = NULL, rotate_x_tick_labels = waiver(), + remove_feature_labels = FALSE, + remove_sample_labels = FALSE, show_feature_dendrogram = TRUE, show_sample_dendrogram = TRUE, show_normalised_data = TRUE, @@ -58,6 +61,7 @@ plot_sample_clustering( \S4method{plot_sample_clustering}{ANY}( object, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), sample_cluster_method = waiver(), @@ -91,6 +95,8 @@ plot_sample_clustering( y_n_breaks = 3L, y_breaks = NULL, rotate_x_tick_labels = waiver(), + remove_feature_labels = FALSE, + remove_sample_labels = FALSE, show_feature_dendrogram = TRUE, show_sample_dendrogram = TRUE, show_normalised_data = TRUE, @@ -108,6 +114,7 @@ plot_sample_clustering( \S4method{plot_sample_clustering}{familiarCollection}( object, + features = waiver(), feature_cluster_method = waiver(), feature_linkage_method = waiver(), sample_cluster_method = waiver(), @@ -141,6 +148,8 @@ plot_sample_clustering( y_n_breaks = 3L, y_breaks = NULL, rotate_x_tick_labels = waiver(), + remove_feature_labels = FALSE, + remove_sample_labels = FALSE, show_feature_dendrogram = TRUE, show_sample_dendrogram = TRUE, show_normalised_data = TRUE, @@ -160,6 +169,10 @@ plot_sample_clustering( \item{object}{A \code{familiarCollection} object, or other other objects from which a \code{familiarCollection} can be extracted. See details for more information.} +\item{features}{Features that should be considered for extracting information +from. Typically called in external workflows, e.g. for plotting. Internally, +i.e. from summon_familiar, this variable is not used.} + \item{feature_cluster_method}{The method used to perform clustering. These are the same methods as for the \code{cluster_method} configuration parameter: \code{none}, \code{hclust}, \code{agnes}, \code{diana} and \code{pam}. @@ -329,6 +342,12 @@ is unset.} controlled through the \code{ggtheme}. In this case, \code{FALSE} should be provided explicitly.} +\item{remove_feature_labels}{(\emph{optional}) If \code{TRUE}, feature labels are not +shown. By default, feature labels are shown.} + +\item{remove_sample_labels}{(\emph{optional}) If \code{TRUE}, sample labels are not +shown. By default, feature labels are shown.} + \item{show_feature_dendrogram}{(\emph{optional}) Show feature dendrogram around the main panel. Can be \code{TRUE}, \code{FALSE}, \code{NULL}, or a position, i.e. \code{top}, \code{bottom}, \code{left} and \code{right}. @@ -412,7 +431,7 @@ from the number of features and the number of facets.} plotting.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link[=extract_feature_expression]{extract_feature_expression}} + Arguments passed on to \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link{extract_feature_expression}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/plot_shap_dependence-methods.Rd b/man/plot_shap_dependence-methods.Rd index b76eeb37..903a1d35 100644 --- a/man/plot_shap_dependence-methods.Rd +++ b/man/plot_shap_dependence-methods.Rd @@ -211,7 +211,7 @@ from the number of features and the number of facets.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_performance]{extract_performance}}, \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}} + Arguments passed on to \code{\link{extract_performance}}, \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} diff --git a/man/plot_shap_force-methods.Rd b/man/plot_shap_force-methods.Rd index e81d1526..5d46bd73 100644 --- a/man/plot_shap_force-methods.Rd +++ b/man/plot_shap_force-methods.Rd @@ -223,7 +223,7 @@ from the number of features and the number of facets.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_performance]{extract_performance}}, \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}} + Arguments passed on to \code{\link{extract_performance}}, \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} diff --git a/man/plot_shap_summary-methods.Rd b/man/plot_shap_summary-methods.Rd index 6fc1286a..1e5ecbb0 100644 --- a/man/plot_shap_summary-methods.Rd +++ b/man/plot_shap_summary-methods.Rd @@ -241,7 +241,7 @@ from the number of features and the number of facets.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_performance]{extract_performance}}, \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}} + Arguments passed on to \code{\link{extract_performance}}, \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} diff --git a/man/plot_shap_waterfall-methods.Rd b/man/plot_shap_waterfall-methods.Rd index 75f7eca4..77125a40 100644 --- a/man/plot_shap_waterfall-methods.Rd +++ b/man/plot_shap_waterfall-methods.Rd @@ -188,7 +188,7 @@ from the number of features and the number of facets.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=extract_performance]{extract_performance}}, \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}} + Arguments passed on to \code{\link{extract_performance}}, \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}} \describe{ \item{\code{data}}{A \code{dataObject} object, \code{data.table} or \code{data.frame} that constitutes the data that are assessed.} diff --git a/man/plot_univariate_importance-methods.Rd b/man/plot_univariate_importance-methods.Rd index dd1bb076..00cd175c 100644 --- a/man/plot_univariate_importance-methods.Rd +++ b/man/plot_univariate_importance-methods.Rd @@ -260,7 +260,7 @@ plotting.} \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link[=extract_univariate_analysis]{extract_univariate_analysis}} + Arguments passed on to \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link{extract_univariate_analysis}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/plot_variable_importance-methods.Rd b/man/plot_variable_importance-methods.Rd index d640a377..8acb6885 100644 --- a/man/plot_variable_importance-methods.Rd +++ b/man/plot_variable_importance-methods.Rd @@ -314,7 +314,7 @@ from number of facets, and the length of the longest feature name (if \item{export_collection}{(\emph{optional}) Exports the collection if TRUE.} \item{...}{ - Arguments passed on to \code{\link[=as_familiar_collection]{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link[=extract_fs_vimp]{extract_fs_vimp}} + Arguments passed on to \code{\link{as_familiar_collection}}, \code{\link[ggplot2:ggsave]{ggplot2::ggsave}}, \code{\link{extract_fs_vimp}} \describe{ \item{\code{familiar_data_names}}{Names of the dataset(s). Only used if the \code{object} parameter is one or more \code{familiarData} objects.} diff --git a/man/precompute_data_assignment.Rd b/man/precompute_data_assignment.Rd index 65862908..1977f51d 100644 --- a/man/precompute_data_assignment.Rd +++ b/man/precompute_data_assignment.Rd @@ -97,7 +97,7 @@ training set.} messages and warnings are returned.} \item{...}{ - Arguments passed on to \code{\link[=.parse_experiment_settings]{.parse_experiment_settings}}, \code{\link[=.parse_setup_settings]{.parse_setup_settings}}, \code{\link[=.parse_preprocessing_settings]{.parse_preprocessing_settings}} + Arguments passed on to \code{\link{.parse_experiment_settings}}, \code{\link{.parse_setup_settings}}, \code{\link{.parse_preprocessing_settings}} \describe{ \item{\code{batch_id_column}}{(\strong{recommended}) Name of the column containing batch or cohort identifiers. This parameter is required if more than one dataset diff --git a/man/precompute_feature_info.Rd b/man/precompute_feature_info.Rd index b45ac461..e2b3092b 100644 --- a/man/precompute_feature_info.Rd +++ b/man/precompute_feature_info.Rd @@ -99,7 +99,7 @@ This argument is ignored if the \code{experiment_data} argument is set.} messages and warnings are returned.} \item{...}{ - Arguments passed on to \code{\link[=.parse_experiment_settings]{.parse_experiment_settings}}, \code{\link[=.parse_setup_settings]{.parse_setup_settings}}, \code{\link[=.parse_preprocessing_settings]{.parse_preprocessing_settings}} + Arguments passed on to \code{\link{.parse_experiment_settings}}, \code{\link{.parse_setup_settings}}, \code{\link{.parse_preprocessing_settings}} \describe{ \item{\code{batch_id_column}}{(\strong{recommended}) Name of the column containing batch or cohort identifiers. This parameter is required if more than one dataset diff --git a/man/precompute_vimp.Rd b/man/precompute_vimp.Rd index c68af9bf..5ba0da0c 100644 --- a/man/precompute_vimp.Rd +++ b/man/precompute_vimp.Rd @@ -120,7 +120,7 @@ assessing variable importance.} messages and warnings are returned.} \item{...}{ - Arguments passed on to \code{\link[=.parse_experiment_settings]{.parse_experiment_settings}}, \code{\link[=.parse_setup_settings]{.parse_setup_settings}}, \code{\link[=.parse_preprocessing_settings]{.parse_preprocessing_settings}}, \code{\link[=.parse_variable_importance_settings]{.parse_variable_importance_settings}} + Arguments passed on to \code{\link{.parse_experiment_settings}}, \code{\link{.parse_setup_settings}}, \code{\link{.parse_preprocessing_settings}}, \code{\link{.parse_variable_importance_settings}} \describe{ \item{\code{batch_id_column}}{(\strong{recommended}) Name of the column containing batch or cohort identifiers. This parameter is required if more than one dataset diff --git a/man/summon_familiar.Rd b/man/summon_familiar.Rd index 04eb3261..10c82aff 100644 --- a/man/summon_familiar.Rd +++ b/man/summon_familiar.Rd @@ -68,7 +68,7 @@ messages and warnings are returned.} the file system.} \item{...}{ - Arguments passed on to \code{\link[=.parse_file_paths]{.parse_file_paths}}, \code{\link[=.parse_experiment_settings]{.parse_experiment_settings}}, \code{\link[=.parse_setup_settings]{.parse_setup_settings}}, \code{\link[=.parse_preprocessing_settings]{.parse_preprocessing_settings}}, \code{\link[=.parse_variable_importance_settings]{.parse_variable_importance_settings}}, \code{\link[=.parse_model_development_settings]{.parse_model_development_settings}}, \code{\link[=.parse_hyperparameter_optimisation_settings]{.parse_hyperparameter_optimisation_settings}}, \code{\link[=.parse_evaluation_settings]{.parse_evaluation_settings}} + Arguments passed on to \code{\link{.parse_file_paths}}, \code{\link{.parse_experiment_settings}}, \code{\link{.parse_setup_settings}}, \code{\link{.parse_preprocessing_settings}}, \code{\link{.parse_variable_importance_settings}}, \code{\link{.parse_model_development_settings}}, \code{\link{.parse_hyperparameter_optimisation_settings}}, \code{\link{.parse_evaluation_settings}} \describe{ \item{\code{project_dir}}{(\emph{optional}) Path to the project directory. \code{familiar} checks if the directory indicated by \code{experiment_dir} and data files in diff --git a/man/train_familiar.Rd b/man/train_familiar.Rd index 14961b58..654ed5d1 100644 --- a/man/train_familiar.Rd +++ b/man/train_familiar.Rd @@ -119,7 +119,7 @@ be conducted using these values.} messages and warnings are returned.} \item{...}{ - Arguments passed on to \code{\link[=.parse_experiment_settings]{.parse_experiment_settings}}, \code{\link[=.parse_setup_settings]{.parse_setup_settings}}, \code{\link[=.parse_preprocessing_settings]{.parse_preprocessing_settings}}, \code{\link[=.parse_variable_importance_settings]{.parse_variable_importance_settings}}, \code{\link[=.parse_model_development_settings]{.parse_model_development_settings}}, \code{\link[=.parse_hyperparameter_optimisation_settings]{.parse_hyperparameter_optimisation_settings}} + Arguments passed on to \code{\link{.parse_experiment_settings}}, \code{\link{.parse_setup_settings}}, \code{\link{.parse_preprocessing_settings}}, \code{\link{.parse_variable_importance_settings}}, \code{\link{.parse_model_development_settings}}, \code{\link{.parse_hyperparameter_optimisation_settings}} \describe{ \item{\code{batch_id_column}}{(\strong{recommended}) Name of the column containing batch or cohort identifiers. This parameter is required if more than one dataset diff --git a/tests/old_experiments/2_0_0_binomial.rds b/tests/old_experiments/2_0_0_binomial.rds deleted file mode 100644 index 9b17959b..00000000 Binary files a/tests/old_experiments/2_0_0_binomial.rds and /dev/null differ diff --git a/tests/old_experiments/2_0_0_continuous.rds b/tests/old_experiments/2_0_0_continuous.rds deleted file mode 100644 index f39d0f17..00000000 Binary files a/tests/old_experiments/2_0_0_continuous.rds and /dev/null differ diff --git a/tests/old_experiments/2_0_0_survival.rds b/tests/old_experiments/2_0_0_survival.rds deleted file mode 100644 index 39c5e9d7..00000000 Binary files a/tests/old_experiments/2_0_0_survival.rds and /dev/null differ diff --git a/tests/old_experiments/2_0_1_binomial.rds b/tests/old_experiments/2_0_1_binomial.rds new file mode 100644 index 00000000..44599eff Binary files /dev/null and b/tests/old_experiments/2_0_1_binomial.rds differ diff --git a/tests/old_experiments/2_0_1_continuous.rds b/tests/old_experiments/2_0_1_continuous.rds new file mode 100644 index 00000000..e5fe3466 Binary files /dev/null and b/tests/old_experiments/2_0_1_continuous.rds differ diff --git a/tests/old_experiments/2_0_0_multinomial.rds b/tests/old_experiments/2_0_1_multinomial.rds similarity index 51% rename from tests/old_experiments/2_0_0_multinomial.rds rename to tests/old_experiments/2_0_1_multinomial.rds index b3d4a170..ca827190 100644 Binary files a/tests/old_experiments/2_0_0_multinomial.rds and b/tests/old_experiments/2_0_1_multinomial.rds differ diff --git a/tests/old_experiments/2_0_1_survival.rds b/tests/old_experiments/2_0_1_survival.rds new file mode 100644 index 00000000..8b8c46a4 Binary files /dev/null and b/tests/old_experiments/2_0_1_survival.rds differ diff --git a/tests/old_experiments/archiveExperiment.R b/tests/old_experiments/archiveExperiment.R index 7f380d79..e5b10a15 100644 --- a/tests/old_experiments/archiveExperiment.R +++ b/tests/old_experiments/archiveExperiment.R @@ -14,6 +14,7 @@ test_run_archive_experiment <- function(parameters) { args = c( list( "data" = data, + "estimation_type" = "point", "parallel" = FALSE, ".force_output" = TRUE ), diff --git a/tests/testthat/test-experimental_design.R b/tests/testthat/test-experimental_design.R index 86380ba4..125baf13 100644 --- a/tests/testthat/test-experimental_design.R +++ b/tests/testthat/test-experimental_design.R @@ -4,88 +4,81 @@ testthat::skip_on_ci() debug_flag <- FALSE # Simple test -familiar:::integrated_test( - experimental_design = "fs+mb", - vimp_method = "none", - cluster_method = "none", - imputation_method = "simple", - parallel = FALSE, - skip_evaluation_elements = "all", - outcome_type_available = "binomial", - debug = debug_flag -) +vimp_methods <- c("none", "mim", "mim") +experimental_designs <- c("fs+mb", "fs+mb", "mb") +for (ii in seq_along(vimp_methods)) { + familiar:::integrated_test( + experimental_design = experimental_designs[ii], + vimp_method = vimp_methods[ii], + parallel = FALSE, + estimation_type = "point", + n_important_features = 2L, + outcome_type_available = "binomial", + debug = debug_flag + ) + + # Using all features for evaluation. + familiar:::integrated_test( + experimental_design = experimental_designs[ii], + vimp_method = vimp_methods[ii], + parallel = FALSE, + estimation_type = "point", + outcome_type_available = "binomial", + debug = debug_flag + ) +} -# Bootstrap (without optimisation within bootstraps) -familiar:::integrated_test( - experimental_design = "bt(fs+mb, 5)", - vimp_method = "none", - cluster_method = "none", - imputation_method = "simple", - parallel = FALSE, - skip_evaluation_elements = "all", - outcome_type_available = "binomial", - debug = debug_flag -) -# Bootstrap (with pre-processing and optimisation within bootstraps) -familiar:::integrated_test( - experimental_design = "bs(fs+mb, 5)", - vimp_method = "none", - cluster_method = "none", - imputation_method = "simple", - parallel = FALSE, - skip_evaluation_elements = "all", - outcome_type_available = "binomial", - debug = debug_flag -) +# Bootstrap (without optimisation within bootstraps) +experimental_designs <- c("bt(fs+mb, 3)", "bt(fs+mb, 3)", "bt(mb, 3)") +for (ii in seq_along(vimp_methods)) { + familiar:::integrated_test( + experimental_design = experimental_designs[ii], + vimp_method = vimp_methods[ii], + parallel = FALSE, + estimation_type = "point", + n_important_features = 2L, + outcome_type_available = "binomial", + debug = debug_flag + ) +} -# Cross-validation -familiar:::integrated_test( - experimental_design = "cv(fs+mb, 3)", - vimp_method = "none", - cluster_method = "none", - imputation_method = "simple", - parallel = FALSE, - skip_evaluation_elements = "all", - outcome_type_available = "binomial", - debug = debug_flag -) -# Leave-one-out cross-validation -familiar:::integrated_test( - experimental_design = "lv(fs+mb)", - vimp_method = "none", - cluster_method = "none", - imputation_method = "simple", - parallel = FALSE, - skip_evaluation_elements = "all", - outcome_type_available = "binomial", - debug = debug_flag -) +# Bootstrap (with pre-processing and optimisation within bootstraps) +experimental_designs <- c("bs(fs+mb, 3)", "bs(fs+mb, 3)", "bs(mb, 3)") +for (ii in seq_along(vimp_methods)) { + familiar:::integrated_test( + experimental_design = experimental_designs[ii], + vimp_method = vimp_methods[ii], + parallel = FALSE, + estimation_type = "point", + n_important_features = 2L, + outcome_type_available = "binomial", + debug = debug_flag + ) +} -# Imbalance corrections using full undersampling -familiar:::integrated_test( - experimental_design = "ip(fs+mb)", - imbalance_correction_method = "full_undersampling", - vimp_method = "none", - cluster_method = "none", - imputation_method = "simple", - parallel = FALSE, - skip_evaluation_elements = "all", - outcome_type_available = "binomial", - debug = debug_flag -) -# Imbalance corrections using full undersampling -familiar:::integrated_test( - experimental_design = "ip(fs+mb)", - imbalance_correction_method = "random_undersampling", - imbalance_n_partitions = 3, - vimp_method = "none", - cluster_method = "none", - imputation_method = "simple", - parallel = FALSE, - skip_evaluation_elements = "all", - outcome_type_available = "binomial", - debug = debug_flag -) +# Cross-validation +experimental_designs <- c("cv(fs+mb, 3)", "cv(fs+mb, 3)", "cv(mb, 3)") +for (ii in seq_along(vimp_methods)) { + familiar:::integrated_test( + experimental_design = experimental_designs[ii], + vimp_method = vimp_methods[ii], + parallel = FALSE, + estimation_type = "point", + n_important_features = 2L, + outcome_type_available = "binomial", + debug = debug_flag + ) + + # Using all features for evaluation. + familiar:::integrated_test( + experimental_design = experimental_designs[ii], + vimp_method = vimp_methods[ii], + parallel = FALSE, + estimation_type = "point", + outcome_type_available = "binomial", + debug = debug_flag + ) +} diff --git a/tests/testthat/test-experimental_design_imbalance.R b/tests/testthat/test-experimental_design_imbalance.R new file mode 100644 index 00000000..0231956c --- /dev/null +++ b/tests/testthat/test-experimental_design_imbalance.R @@ -0,0 +1,33 @@ +testthat::skip_on_cran() +testthat::skip_on_ci() + +debug_flag <- FALSE + +# Simple test +vimp_methods <- c("none", "mim") + +# Imbalance corrections using full undersampling +experimental_designs <- c("ip(fs+mb)", "ip(mb)") +for (ii in seq_along(vimp_methods)) { + familiar:::integrated_test( + experimental_design = experimental_designs[ii], + imbalance_correction_method = "full_undersampling", + vimp_method = vimp_methods[ii], + parallel = FALSE, + estimation_type = "point", + n_important_features = 2L, + outcome_type_available = "binomial", + debug = debug_flag + ) + + familiar:::integrated_test( + experimental_design = experimental_designs[ii], + imbalance_correction_method = "random_undersampling", + imbalance_n_partitions = 3, + vimp_method = vimp_methods[ii], + parallel = FALSE, + skip_evaluation_elements = "all", + outcome_type_available = "binomial", + debug = debug_flag + ) +} diff --git a/tests/testthat/test-experimental_design_loocv.R b/tests/testthat/test-experimental_design_loocv.R new file mode 100644 index 00000000..45ca64b9 --- /dev/null +++ b/tests/testthat/test-experimental_design_loocv.R @@ -0,0 +1,14 @@ +testthat::skip_on_cran() +testthat::skip_on_ci() + +debug_flag <- FALSE + +# Leave-one-out-cross-validation +familiar:::integrated_test( + experimental_design = "lv(fs+mb)", + vimp_method = "none", + parallel = FALSE, + skip_evaluation_elements = "all", + outcome_type_available = "binomial", + debug = debug_flag +) diff --git a/tests/testthat/test-plot_feature_similarity.R b/tests/testthat/test-plot_feature_similarity.R index 24828404..ead9b1be 100644 --- a/tests/testthat/test-plot_feature_similarity.R +++ b/tests/testthat/test-plot_feature_similarity.R @@ -65,6 +65,30 @@ familiar:::test_plots( ) +# Plots with selection of features. +familiar:::test_plot_ordering( + plot_function = familiar:::plot_feature_similarity, + data_element = "feature_similarity", + outcome_type_available = c("continuous", "binomial", "multinomial", "survival"), + plot_args = list( + "features" = c("feature_1", "feature_2a", "feature_2b") + ), + debug = debug_flag +) + +# Plots without tick labels on x and y-axes. +familiar:::test_plot_ordering( + plot_function = familiar:::plot_feature_similarity, + data_element = "feature_similarity", + outcome_type_available = c("continuous", "binomial", "multinomial", "survival"), + plot_args = list( + "remove_feature_labels" = TRUE + ), + debug = debug_flag +) + + + # Test plotting from dataObject. data <- familiar:::test_create_good_data(outcome_type = "continuous") p <- familiar::plot_feature_similarity(object = data, feature_similarity_metric = "spearman") @@ -108,3 +132,16 @@ p <- familiar::plot_feature_similarity( testthat::test_that("Plotting feature similarity using data.table works.", { testthat::expect_true(is(p[[1L]], "gtable")) }) + + + +# Test plotting from dataObject with set features. +data <- familiar:::test_create_good_data(outcome_type = "continuous") +p <- familiar::plot_feature_similarity( + object = data, + features = c("feature_1", "feature_2a", "feature_2b"), + feature_similarity_metric = "spearman" +) +testthat::test_that("Plotting feature similarity using dataObject and a limited number of features works.", { + testthat::expect_true(is(p[[1L]], "gtable")) +}) diff --git a/tests/testthat/test-plot_kaplan_meier_curve.R b/tests/testthat/test-plot_kaplan_meier_curve.R index 43a86471..aacb1096 100644 --- a/tests/testthat/test-plot_kaplan_meier_curve.R +++ b/tests/testthat/test-plot_kaplan_meier_curve.R @@ -109,7 +109,6 @@ testthat::test_that("Plotting kaplan-meier curves for two groups works.", { data <- familiar:::test_create_good_data(outcome_type = "survival", to_data_object = FALSE) p <- familiar::plot_kaplan_meier( object = data, - feature_similarity_metric = "spearman", batch_id_column = "batch_id", sample_id_column = "sample_id", series_id_column = "series_id", @@ -125,7 +124,6 @@ testthat::test_that("Plotting kaplan-meier curves using data.table works (surviv data <- familiar:::test_create_data_without_feature(outcome_type = "survival", to_data_object = FALSE) p <- familiar::plot_kaplan_meier( object = data, - feature_similarity_metric = "spearman", batch_id_column = "batch_id", sample_id_column = "sample_id", series_id_column = "series_id", @@ -141,7 +139,25 @@ testthat::test_that("Plotting kaplan-meier curves using data.table without any f data <- familiar:::test_create_good_data(outcome_type = "survival") data@data[, "risk_group" := "risk-group A"] data@data[51L:100L, "risk_group" := "risk-group B"] -p <- familiar::plot_kaplan_meier(object = data, risk_group_column = "risk_group") +p <- familiar::plot_kaplan_meier( + object = data, + risk_group_column = "risk_group" +) testthat::test_that("Plotting kaplan-meier curves using data.table without a risk_group_column works (survival).", { testthat::expect_true(is(p[[1L]], "gtable")) }) + + +# Test plotting from data.table, but with batch_id as risk group. +data <- familiar:::test_create_good_data(outcome_type = "survival", to_data_object = FALSE) +data[, "batch_id" := "batch A"] +data[51L:100L, "batch_id" := "batch B"] +p <- familiar::plot_kaplan_meier( + object = data, + risk_group_column = "batch_id", + outcome_type = "survival", + outcome_column = c("outcome_time", "outcome_event") +) +testthat::test_that("Plotting kaplan-meier curves using data.table works (survival).", { + testthat::expect_true(is(p[[1L]], "gtable")) +}) diff --git a/tests/testthat/test-plot_sample_clustering_b.R b/tests/testthat/test-plot_sample_clustering_b.R index b794b29f..5778d89a 100644 --- a/tests/testthat/test-plot_sample_clustering_b.R +++ b/tests/testthat/test-plot_sample_clustering_b.R @@ -84,6 +84,42 @@ familiar:::test_plot_ordering( ) +# Plots without feature tick labels. +familiar:::test_plot_ordering( + plot_function = familiar:::plot_sample_clustering, + data_element = "feature_expressions", + outcome_type_available = c("continuous", "binomial", "multinomial", "survival"), + plot_args = list( + "remove_feature_labels" = TRUE + ), + debug = debug_flag +) + + +# Plots without sample tick labels. +familiar:::test_plot_ordering( + plot_function = familiar:::plot_sample_clustering, + data_element = "feature_expressions", + outcome_type_available = c("continuous", "binomial", "multinomial", "survival"), + plot_args = list( + "remove_sample_labels" = TRUE + ), + debug = debug_flag +) + + +# Plots with feature subset. +familiar:::test_plot_ordering( + plot_function = familiar:::plot_sample_clustering, + data_element = "feature_expressions", + outcome_type_available = c("continuous", "binomial", "multinomial", "survival"), + plot_args = list( + "features" = c("feature_1", "feature_2a", "feature_2b") + ), + debug = debug_flag +) + + # Test plotting from dataObject. data <- familiar:::test_create_good_data(outcome_type = "survival") @@ -98,6 +134,17 @@ testthat::test_that("Plotting sample similarity using dataObject works (continuo testthat::expect_true(is(p[[1L]], "gtable")) }) +# Test plotting from dataObject with selection of features. +data <- familiar:::test_create_good_data(outcome_type = "continuous") +p <- familiar::plot_sample_clustering( + object = data, + feature_similarity_metric = "spearman", + features = c("feature_1", "feature_2a", "feature_2b") +) +testthat::test_that("Plotting sample similarity using dataObject works (continuous).", { + testthat::expect_true(is(p[[1L]], "gtable")) +}) + # Test plotting from dataObject with two groups. data <- familiar:::test_create_good_data(outcome_type = "continuous", two_groups = TRUE)