diff --git a/NAMESPACE b/NAMESPACE index 1e7d9e4..687db6b 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,5 +1,14 @@ # Generated by roxygen2: do not edit by hand +export(apply_logics) +export(clone_arms) export(clone_censor_weighting) +export(create_censoring_logics_A) +export(create_final_data) +export(create_policy_A) +export(create_timestamp_table) export(make_surv_response) export(read_trial_data) +export(split_at_timestamp) +importFrom(rlang,":=") +importFrom(rlang,.data) diff --git a/R/clonecensorweighting-package.R b/R/clonecensorweighting-package.R index 27b992c..e3fc135 100644 --- a/R/clonecensorweighting-package.R +++ b/R/clonecensorweighting-package.R @@ -3,4 +3,6 @@ ## usethis namespace: start #' @importFrom rlang := +#' @importFrom rlang .data +NULL ## usethis namespace: end \ No newline at end of file diff --git a/man/apply_logics.Rd b/man/apply_logics.Rd new file mode 100644 index 0000000..17c3a56 --- /dev/null +++ b/man/apply_logics.Rd @@ -0,0 +1,25 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/apply_logics.R +\name{apply_logics} +\alias{apply_logics} +\title{Apply case_when logics (e.g. policy, censoring) to clones} +\usage{ +apply_logics(clones, logics) +} +\arguments{ +\item{clones}{A list of data frame. Each element of the list represents +each treatment arm.} + +\item{logics}{A nested list. Each element of outer list represents each +treatment arm. Each element of inner list represents each new variable +to be created by applying logics. Each element of inner list containts a +character vector that represents a sequence of logics to be passed into +\code{case_when()} call to determine a value of the new variable.} +} +\value{ +A list of data frame that each data frame include new variables +created by the provided logics. +} +\description{ +Apply case_when logics (e.g. policy, censoring) to clones +} diff --git a/man/clone_arms.Rd b/man/clone_arms.Rd new file mode 100644 index 0000000..e8b8038 --- /dev/null +++ b/man/clone_arms.Rd @@ -0,0 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/clone_arms.R +\name{clone_arms} +\alias{clone_arms} +\title{Duplicate data frame for each treatment arm to emulate} +\usage{ +clone_arms(data, arms) +} +\arguments{ +\item{data}{Input data frame that contains all observations of interest. +Each row represents an observation, and columns include +observation identifiers, binary treatment variable (0/1), +time to treatement (continuous), binary outcome variable (0/1), +observed followup time (continuous), and covariates.} + +\item{arms}{Character vector that each element represents each arm's name.} +} +\value{ +A list of data frame. +Each element of list is associated with each arm. +} +\description{ +Duplicate data frame for each treatment arm to emulate +} +\examples{ +data(lungcancer) +clones <- clone_arms(lungcancer, c("Control", "Surgery")) +} diff --git a/man/clonecensorweighting-package.Rd b/man/clonecensorweighting-package.Rd index 2f47157..ee9ba87 100644 --- a/man/clonecensorweighting-package.Rd +++ b/man/clonecensorweighting-package.Rd @@ -9,7 +9,12 @@ Provides a starter package for clone-censor-weighting workflows used in target trial emulation. The package currently includes data ingestion helpers, a minimal data cloning routine, and utilities for constructing survival responses. } \author{ -\strong{Maintainer}: Sangho Park \email{shstat1729@gmail.com} +\strong{Maintainer}: Sang Ho Park \email{shstat1729@gmail.com} + +Authors: +\itemize{ + \item Sang Ho Park \email{shstat1729@gmail.com} +} } \keyword{internal} diff --git a/man/create_censoring_logics_A.Rd b/man/create_censoring_logics_A.Rd new file mode 100644 index 0000000..d7cee53 --- /dev/null +++ b/man/create_censoring_logics_A.Rd @@ -0,0 +1,71 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/apply_logics.R +\name{create_censoring_logics_A} +\alias{create_censoring_logics_A} +\title{Generate censoring logic for scenario A} +\usage{ +create_censoring_logics_A( + arms, + treatment, + time_to_treatment, + grace_period, + followup, + clone_censoring = ".censoring", + clone_uncensored_followup = ".fup_uncensored" +) +} +\arguments{ +\item{arms}{A character vector of length 2. The first element represents +a name of the untreated arm, and the second element represents a name of +the treated arm.} + +\item{treatment}{A name of variable that represents whether each observation +was treated or not in observational data. The treatment variable should +exists in data frame that the return value of this function will be +applied, and the treatment variable value in the data frame should be +either 0 and 1, i.e. binary treatment.} + +\item{time_to_treatment}{A name of variable that represent time to +treatment in the observational data. The time-to-treatment variable should +exists in data frame that the return value of this function will be +applied, and the value in the data frame should be either numeric value +or NA if the observation was untreated in the observational data.} + +\item{grace_period}{A numeric value to represent grace period of treatment. +Treatment policy is assumed to be "provide treatment within the grace +period."} + +\item{followup}{A name of variable that represent follow up time in the +observational data. The follow up time variable should exists in data +frame that the return value of this function will be applied, and the +follow up time variable value in the data frame should be numeric.} + +\item{clone_censoring}{A name of binary indicator variable to be newly +created to represent whether the observation violates arm's policy or not. +The new variable name should not already exist in the data frame that the +return value of this function will be applied, to avoid accidental +overwriting.} + +\item{clone_uncensored_followup}{A name of variable to be newly created to +represent the earliest time that the value of the emulated censoring binary +indicator (i.e. variable to be named according to \code{clone_censoring} +argument) value can be determined for each observation. The new variable +name should not already exist in the data frame that the return value of +this function will be applied, to avoid accidental overwriting.} +} +\value{ +A nested list. The first element of the outer list represents +untreated arm, while the second element of the outer list represents +treated arm. For each element of outer list, the first element of the inner +list represents emulated censoring binary indicator (0/1) that represents +whether the observation violated the arm's policy or not within the grace +period, and the second. The second element of the inner list represents +the earliest time that the value of the emulated censoring binary +indicator can be determined for each observation. Each element of the +inner list represents a sequence of logics to be passed into \code{case_when()} +when creating new variables for emulated censoring indicator and censoring +time. +} +\description{ +Generate censoring logic for scenario A +} diff --git a/man/create_final_data.Rd b/man/create_final_data.Rd new file mode 100644 index 0000000..91296e4 --- /dev/null +++ b/man/create_final_data.Rd @@ -0,0 +1,62 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/reshape.R +\name{create_final_data} +\alias{create_final_data} +\title{Create training data for censoring probability estimation} +\usage{ +create_final_data( + clones, + clone_followup, + clone_outcome, + clone_censoring, + col_ids, + timestamp_start = "Tstart", + id = "ID", + timestamp_stop = "Tstop" +) +} +\arguments{ +\item{clones}{A list of data frame. Each element of the list represents +each treatment arm. This version of clones must contain a column that +represents an emulated follow up time (corresponding to \code{clone_followup} +argument), an emulated outcome (correspodning to \code{clone_outcome}), and a +binary indicator variable that represents whether the observation violates +arm's policy or not (corresponding to \code{clone_censoring} argument).} + +\item{clone_followup}{A column name that represents the emulated follow up +time in each arm of clones. The variable should exists in each element +data frame of \code{clones} argument.} + +\item{clone_outcome}{A column name that represents the emulated outcome +in each arm of clones. The variable should exists in each element +data frame of \code{clones} argument, and the variable value should be binary +(0 or 1).} + +\item{clone_censoring}{A column name that represent whether the observation +violates arm's policy or not. The variable should exists in each element +data frame of \code{clones} argument, and the variable value should be binary +(0 or 1).} + +\item{col_ids}{A vector of column names that a combination of their values +uniquely identifies each observation.} + +\item{timestamp_start}{A new variable name to denote start time of each +subrecord of observations in a long-form data.} + +\item{id}{A new variable name for a unique observation identifier, to +represents that multiple rows in output data frame is associated with the +same observation.} + +\item{timestamp_stop}{A new variable name to denote end time of each +subrecord of observations in a long-form data.} +} +\value{ +A list of long-form data frames. Each data frame represents each +clone arm. Each row of the long-form data frame represents a subrecord of +each observation associated with each specific time interval. The first +subrecord starts with time 0, and the rows are expanded up to +\code{clone_followup}, where cut times are determined by \code{t_events} argument. +} +\description{ +Create training data for censoring probability estimation +} diff --git a/man/create_policy_A.Rd b/man/create_policy_A.Rd new file mode 100644 index 0000000..ba27671 --- /dev/null +++ b/man/create_policy_A.Rd @@ -0,0 +1,71 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/apply_logics.R +\name{create_policy_A} +\alias{create_policy_A} +\title{Generate clone policy for scenario A} +\usage{ +create_policy_A( + arms, + treatment, + time_to_treatment, + grace_period, + outcome, + followup, + clone_outcome = ".outcome", + clone_followup = ".fup" +) +} +\arguments{ +\item{arms}{A character vector of length 2. The first element represents +a name of the untreated arm, and the second element represents a name of +the treated arm.} + +\item{treatment}{A name of variable that represents whether each observation +was treated or not in observational data. The treatment variable should +exists in data frame that the return value of this function will be +applied, and the treatment variable value in the data frame should be +either 0 and 1, i.e. binary treatment.} + +\item{time_to_treatment}{A name of variable that represent time to +treatment in the observational data. The time-to-treatment variable should +exists in data frame that the return value of this function will be +applied, and the value in the data frame should be either numeric value +or NA if the observation was untreated in the observational data.} + +\item{grace_period}{A numeric value to represent grace period of treatment. +Treatment policy is assumed to be "provide treatment within the grace +period."} + +\item{outcome}{A name of variable that represent outcome in the +observational data. The outcome variable should exists in data frame that +the return value of this function will be applied, and the outcome +variable value in the data frame should be either 0 and 1, i.e. binary +outcome.} + +\item{followup}{A name of variable that represent follow up time in the +observational data. The follow up time variable should exists in data +frame that the return value of this function will be applied, and the +follow up time variable value in the data frame should be numeric.} + +\item{clone_outcome}{A name of variable to be newly created to represent +emulated outcome in cloned data frame. The new variable name should not +already exist in the data frame that the return value of this function +will be applied, to avoid accidental overwriting.} + +\item{clone_followup}{A name of variable to be newly created to represent +emulated follow up time in cloned data frame. The new variable name should +not already exist in the data frame that the return value of this function +will be applied, to avoid accidental overwriting.} +} +\value{ +A nested list. The first element of the outer list represents +untreated arm, while the second element of the outer list represents +treated arm. For each element of outer list, the first element of the inner +list represents emulated outcome, and the second element of the inner list +represents emulated follow up time. Each element of the inner list +represents a sequence of logics to be passed into \code{case_when()} when +creating new variables for emulated outcome and follow up time. +} +\description{ +Generate clone policy for scenario A +} diff --git a/man/create_timestamp_table.Rd b/man/create_timestamp_table.Rd new file mode 100644 index 0000000..bf2b34a --- /dev/null +++ b/man/create_timestamp_table.Rd @@ -0,0 +1,26 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/reshape.R +\name{create_timestamp_table} +\alias{create_timestamp_table} +\title{Create timestamp table} +\usage{ +create_timestamp_table(clones, clone_followup) +} +\arguments{ +\item{clones}{A list of data frame. Each element of the list represents +each treatment arm. This version of clones must contain a column that +represents a emulated follow up time.} + +\item{clone_followup}{A column name in emulcated clone (i.e. \code{clones}) +that represents the emulated follow up time in cloned data frame.} +} +\value{ +A data frame with two columns: \code{tevent} and \code{ID_t}. +\code{tevent} represents a timestamp that outcome event can occur based on +observed data. \code{ID_t} represents an enumerated identifier of each +timestamp, from 1 to n where n represents the number of unique \code{tevent} +value. +} +\description{ +Create timestamp table +} diff --git a/man/read_trial_data.Rd b/man/read_trial_data.Rd index f303eeb..85c723e 100644 --- a/man/read_trial_data.Rd +++ b/man/read_trial_data.Rd @@ -9,7 +9,7 @@ read_trial_data(file, show_col_types = FALSE) \arguments{ \item{file}{Path to a CSV file.} -\item{show_col_types}{Passed to \code{\link[readr:read_delim]{readr::read_csv()}}.} +\item{show_col_types}{Passed to \code{\link[readr:read_csv]{readr::read_csv()}}.} } \value{ A tibble. diff --git a/man/split_at_timestamp.Rd b/man/split_at_timestamp.Rd new file mode 100644 index 0000000..1b50662 --- /dev/null +++ b/man/split_at_timestamp.Rd @@ -0,0 +1,47 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/reshape.R +\name{split_at_timestamp} +\alias{split_at_timestamp} +\title{Split each observation into multiple subrecords at each time cut} +\usage{ +split_at_timestamp( + clones, + clone_followup, + t_events, + event, + timestamp_start = "Tstart", + id = "ID" +) +} +\arguments{ +\item{clones}{A list of data frame. Each element of the list represents +each treatment arm. This version of clones must contain a column that +represents a emulated follow up time (corresponding to \code{clone_followup} +argument) and an event of interest (corresponding to \code{event} argument).} + +\item{clone_followup}{A column name in emulcated clone (i.e. \code{clones}) +that represents the emulated follow up time in cloned data frame.} + +\item{t_events}{A vector of timestamp that outcome event can occur based on +observed data.} + +\item{event}{A variable name of an event of interest. The variable should +exists in each data frame that is an element of \code{clones} argument, and +the variable value should be a binary (0 or 1).} + +\item{timestamp_start}{A new variable name to denote start time.} + +\item{id}{A new variable name for a unique observation identifier, to +represents that multiple rows in output data frame is associated with the +same observation.} +} +\value{ +A list of long-form data frames. Each data frame represents each +clone arm. Each row of the long-form data frame represents a subrecord of +each observation associated with each specific time interval. The first +subrecord starts with time 0, and the rows are expanded up to +\code{clone_followup}, where cut times are determined by \code{t_events} argument. +} +\description{ +Split each observation into multiple subrecords at each time cut +}