update roxygen tags for all functions

R/AdditionalCovariates.R

@@ -1,6 +1,6 @@
 # @file AdditionalCovariates.R
 #
-# Copyright 2022 Observational Health Data Sciences and Informatics
+# Copyright 2025 Observational Health Data Sciences and Informatics
 #
 # This file is part of PatientLevelPrediction
 #
@@ -37,7 +37,7 @@
 #' @param ...  additional arguments from FeatureExtraction
 #'
 #' @return
-#' The models will now be in the package
+#' CovariateData object with covariates, covariateRef, and analysisRef tables
 #'
 #' @export
 getCohortCovariateData <- function(

R/AndromedaHelperFunctions.R

@@ -1,4 +1,8 @@
-# @file ffHelperFunctions.R Copyright 2021 Observational Health Data Sciences and Informatics This file is part of PatientLevelPrediction
+# @file AndromedaHelperFunctions.R 
+# 
+# Copyright 2025 Observational Health Data Sciences and Informatics 
+# 
+# This file is part of PatientLevelPrediction
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -95,32 +99,3 @@ batchRestrict <- function(covariateData, population, sizeN = 10000000) {
 
   return(newCovariateData)
 }
-
-
-# is this used?
-# return prev of ffdf
-calculatePrevs <- function(plpData, population) {
-  # ===========================
-  # outcome prevs
-  # ===========================
-
-  # add population to sqllite
-  population <- dplyr::as_tibble(population)
-  plpData$covariateData$population <- population %>%
-    dplyr::select("rowId", "outcomeCount")
-
-  outCount <- nrow(plpData$covariateData$population %>% dplyr::filter(.data$outcomeCount == 1))
-  nonOutCount <- nrow(plpData$covariateData$population %>% dplyr::filter(.data$outcomeCount == 0))
-
-  # join covariate with label
-  prevs <- plpData$covariateData$covariates %>%
-    dplyr::inner_join(plpData$covariateData$population) %>%
-    dplyr::group_by(.data$covariateId) %>%
-    dplyr::summarise(
-      prev.out = 1.0 * sum(.data$outcomeCount == 1, na.rm = TRUE) / outCount,
-      prev.noout = 1.0 * sum(.data$outcomeCount == 0, na.rm = TRUE) / nonOutCount
-    ) %>%
-    dplyr::select("covariateId", "prev.out", "prev.noout")
-
-  return(as.data.frame(prevs))
-}

R/CalibrationSummary.R

@@ -1,3 +1,21 @@
+# @file CalibrationSummary.R
+#
+# Copyright 2025 Observational Health Data Sciences and Informatics
+#
+# This file is part of PatientLevelPrediction
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 #' Get a sparse summary of the calibration
 #'
 #' @details

R/CovariateSummary.R

@@ -1,6 +1,6 @@
 # @file CovariateSummary.R
 #
-# Copyright 2021 Observational Health Data Sciences and Informatics
+# Copyright 2025 Observational Health Data Sciences and Informatics
 #
 # This file is part of PatientLevelPrediction
 #
@@ -37,7 +37,7 @@
 #'                                           to create covariates before summarising
 #'
 #' @return
-#' A data.frame containing: CovariateCount	CovariateMean and CovariateStDev plus these values
+#' A data.frame containing: CovariateCount, CovariateMean and CovariateStDev 
 #' for any specified stratification
 #' @export
 covariateSummary <- function(

R/CyclopsModels.R

@@ -1,6 +1,6 @@
-# @file lassoLogisticRegression.R
+# @file CyclopsModels.R
 #
-# Copyright 2021 Observational Health Data Sciences and Informatics
+# Copyright 2025 Observational Health Data Sciences and Informatics
 #
 # This file is part of PatientLevelPrediction
 #
@@ -19,7 +19,7 @@
 
 fitCyclopsModel <- function(
     trainData,
-    modelSettings, # old:param,
+    modelSettings, 
     search = "adaptive",
     analysisId,
     ...) {
@@ -240,7 +240,7 @@ fitCyclopsModel <- function(
 
 
 
-#' Create predictive probabilities
+#' Predict risk for a population using a Cyclops model
 #'
 #' @details
 #' Generates predictions for the population specified in plpData given the model.
@@ -253,6 +253,8 @@ fitCyclopsModel <- function(
 #'                          \code{\link{fitPlp}}.
 #' @param data         The new plpData containing the covariateData for the new population
 #' @param cohort       The cohort to calculate the prediction for
+#'
+#' @return The cohort dataframe with a new column "value" containing the predicted risk
 #' @export
 predictCyclops <- function(plpModel, data, cohort) {
   start <- Sys.time()

R/CyclopsSettings.R

@@ -1,19 +1,43 @@
-#' Create setting for lasso logistic regression
+# @file CyclopsSettings.R
+#
+# Copyright 2025 Observational Health Data Sciences and Informatics
+#
+# This file is part of PatientLevelPrediction
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+#' Create modelSettings for lasso logistic regression
 #'
 #' @param variance   	Numeric: prior distribution starting variance
 #' @param seed       An option to add a seed when training the model
 #' @param includeCovariateIds a set of covariate IDS to limit the analysis to
-#' @param noShrinkage a set of covariates whcih are to be forced to be included in the final model. default is the intercept
+#' @param noShrinkage a set of covariates whcih are to be forced to be includedin
+#' in the final model. default is the intercept
 #' @param threads    An option to set number of threads when training model
 #' @param forceIntercept  	Logical: Force intercept coefficient into prior
 #' @param upperLimit  	Numeric: Upper prior variance limit for grid-search
 #' @param lowerLimit  	Numeric: Lower prior variance limit for grid-search
-#' @param tolerance   Numeric: maximum relative change in convergence criterion from successive iterations to achieve convergence
-#' @param maxIterations 	Integer: maximum iterations of Cyclops to attempt before returning a failed-to-converge error
-#' @param priorCoefs    Use coefficients from a previous model as starting points for model fit (transfer learning)
+#' @param tolerance   Numeric: maximum relative change in convergence criterionfrom
+#' from successive iterations to achieve convergence
+#' @param maxIterations 	Integer: maximum iterations of Cyclops to attempt 
+#' before returning a failed-to-converge error
+#' @param priorCoefs    Use coefficients from a previous model as starting 
+#' points for model fit (transfer learning
+#'
+#' @return `modelSettings` object
 #'
 #' @examples
-#' model.lr <- setLassoLogisticRegression()
+#' modelLasso <- setLassoLogisticRegression()
 #' @export
 setLassoLogisticRegression <- function(
     variance = 0.01,
@@ -94,8 +118,9 @@ setLassoLogisticRegression <- function(
 #' @param tolerance   Numeric: maximum relative change in convergence criterion from successive iterations to achieve convergence
 #' @param maxIterations 	Integer: maximum iterations of Cyclops to attempt before returning a failed-to-converge error
 #'
+#' @return `modelSettings` object
 #' @examples
-#' model.lr <- setCoxModel()
+#' coxL1 <- setCoxModel()
 #' @export
 setCoxModel <- function(
     variance = 0.01,
@@ -161,7 +186,7 @@ setCoxModel <- function(
 }
 
 
-#' Create setting for lasso logistic regression
+#' Create setting for Iterative Hard Thresholding model
 #'
 #' @param K              The maximum number of non-zero predictors
 #' @param penalty        Specifies the IHT penalty; possible values are `BIC` or `AIC` or a numeric value
@@ -174,9 +199,11 @@ setCoxModel <- function(
 #' @param maxIterations  integer
 #' @param threshold      numeric
 #' @param delta          numeric
+#' 
+#' @return `modelSettings` object
 #'
 #' @examples
-#' model.lr <- setLassoLogisticRegression()
+#' modelIht <- setIterativeHardThresholding()
 #' @export
 setIterativeHardThresholding <- function(
     K = 10,

R/DataSplitting.R

@@ -1,5 +1,5 @@
 # @file DataSplitting.R
-# Copyright 2021 Observational Health Data Sciences and Informatics
+# Copyright 2025 Observational Health Data Sciences and Informatics
 #
 # This file is part of PatientLevelPrediction
 #
@@ -96,6 +96,7 @@ createDefaultSplitSetting <- function(testFraction = 0.25,
 #' Create the settings for defining how the plpData are split into
 #' test/validation/train sets using an existing split - good to use for 
 #' reproducing results from a different run 
+#' 
 #' @param splitIds (data.frame) A data frame with rowId and index columns of 
 #' type integer/numeric. Index is -1 for test set, positive integer for train 
 #' set folds
@@ -118,7 +119,14 @@ createExistingSplitSettings <- function(splitIds) {
 #' Split the plpData into test/train sets using a splitting settings of class 
 #' \code{splitSettings}
 #'
-#' @details
+#' @param plpData   An object of type \code{plpData} - the patient level 
+#' prediction data extracted from the CDM.
+#' @param population The population created using \code{createStudyPopulation} 
+#' that define who will be used to develop the model
+#' @param splitSettings An object of type \code{splitSettings} specifying the 
+#' split - the default can be created using \code{createDefaultSplitSetting}
+#'
+#' @return
 #' Returns a list containing the training data (Train) and optionally the test
 #' data (Test). Train is an Andromeda object containing
 #' \itemize{\item covariates: a table (rowId, covariateId, covariateValue)
@@ -136,15 +144,6 @@ createExistingSplitSettings <- function(splitIds) {
 #'          \item labels: a table (rowId, outcomeCount, ...) for each data
 #' point in the test data (outcomeCount is the class label)
 #'          }
-#' @param plpData   An object of type \code{plpData} - the patient level 
-#' prediction data extracted from the CDM.
-#' @param population The population created using \code{createStudyPopulation} 
-#' that define who will be used to develop the model
-#' @param splitSettings An object of type \code{splitSettings} specifying the 
-#' split - the default can be created using \code{createDefaultSplitSetting}
-#'
-#' @return
-#' An object of class \code{splitSettings}
 #' @export
 splitData <- function(plpData = plpData,
                       population = population,

R/DatabaseMigration.R

@@ -1,6 +1,6 @@
 # @file DatabaseMigration.R
 #
-# Copyright 2023 Observational Health Data Sciences and Informatics
+# Copyright 2025 Observational Health Data Sciences and Informatics
 #
 # This file is part of PatientLevelPrediction
 #
@@ -26,7 +26,9 @@
 #' @param connectionDetails             DatabaseConnector connection details object
 #' @param databaseSchema                String schema where database schema lives
 #' @param  tablePrefix                  (Optional) Use if a table prefix is used before table names (e.g. "cd_")
-#' 
+#'
+#' @return Nothing. Is called for side effects of migrating data model in the 
+#' database
 #' @export
 migrateDataModel <- function(connectionDetails, databaseSchema, tablePrefix = "") {
   ParallelLogger::logInfo("Migrating data set")

R/DemographicSummary.R

@@ -1,14 +1,32 @@
-#' Get a calibration per age/gender groups
+# @file DemographicSummary.R
+# Copyright 2025 Observational Health Data Sciences and Informatics
+#
+# This file is part of PatientLevelPrediction
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+#' Get a demographic summary
 #'
 #' @details
-#' Generates a data.frame with the calibration per each 5 year age group and gender group
+#' Generates a data.frame with a prediction summary per each 5 year age group 
+#' and gender group
 #'
 #' @param prediction            A prediction object
 #' @param predictionType        The type of prediction (binary or survival)
 #' @param typeColumn            A column that is used to stratify the results
 #'
 #' @return
-#' A dataframe with the calibration summary
+#' A dataframe with the demographic summary
 #' @export
 getDemographicSummary <- function(
     prediction,

R/DiagnosePlp.R

@@ -1,6 +1,6 @@
 # @file Diagnostics.R
 #
-# Copyright 2021 Observational Health Data Sciences and Informatics
+# Copyright 2025 Observational Health Data Sciences and Informatics
 #
 # This file is part of PatientLevelPrediction
 #
@@ -19,7 +19,7 @@
 #' Run a list of predictions diagnoses
 #'
 #' @details
-#' This function will run all specified prediction design diagnoses as defined using .
+#' This function will run all specified prediction design diagnoses.
 #'
 #' @param databaseDetails               The database settings created using \code{createDatabaseDetails()}
 #' @param modelDesignList                A list of model designs created using \code{createModelDesign()}
@@ -230,19 +230,14 @@ diagnoseMultiplePlp <- function(
 #' @param saveDirectory         The path to the directory where the results will be saved (if NULL uses working directory)
 #'
 #' @return
-#' An object containing the model or location where the model is save, the data selection settings, the preprocessing
+#' An object containing the model or location where the model is saved, the data selection settings, the preprocessing
 #' and training settings as well as various performance measures obtained by the model.
 #'
 #' \item{distribution}{list for each O of a data.frame containing: i) Time to observation end distribution, ii) Time from observation start distribution, iii) Time to event distribution and iv) Time from last prior event to index distribution (only for patients in T who have O before index) }
 #' \item{incident}{list for each O of incidence of O in T during TAR}
 #' \item{characterization}{list for each O of Characterization of T, TnO, Tn~O}
 #'
-#'
 #' @export
-#' @examples
-#' \dontrun{
-#' #******** EXAMPLE 1 *********
-#' }
 diagnosePlp <- function(
     plpData = NULL,
     outcomeId,

R/EvaluatePlp.R

@@ -1,6 +1,6 @@
-# @file Evaluate.R
+# @file EvaluatePlp.R
 #
-# Copyright 2021 Observational Health Data Sciences and Informatics
+# Copyright 2025 Observational Health Data Sciences and Informatics
 #
 # This file is part of PatientLevelPrediction
 #
@@ -26,9 +26,13 @@
 #' @param typeColumn                         The column name in the prediction object that is used to
 #'                                           stratify the evaluation
 #' @return
-#' A list containing the performance values
-#'
-
+#' An object of class plpEvaluation containing the following components
+#' - evaluationStatistics: A data frame containing the evaluation statistics'
+#' - thresholdSummary: A data frame containing the threshold summary'
+#' - demographicSummary: A data frame containing the demographic summary'
+#' - calibrationSummary: A data frame containing the calibration summary'
+#' - predictionDistribution: A data frame containing the prediction distribution'
+#' 
 #' @export
 evaluatePlp <- function(prediction, typeColumn = "evaluationType") {
   start <- Sys.time()
@@ -157,7 +161,7 @@ evaluatePlp <- function(prediction, typeColumn = "evaluationType") {
 #' @param prediction         the prediction object found in the plpResult object
 #'
 #' @return
-#' model-based concordance value
+#' The model-based concordance value
 #'
 #' @export
 modelBasedConcordance <- function(prediction) {