Package {PTE}

A n \times p dataframe of covariates where one column is labeled "treatment" and it is a binary vector of treatment allocations in the study.

An n-length numeric vector which is the response

A string indicating the regression problem. Legal values are "continous" (the response y is a real number with no missing data, the default), "incidence" (the reponse y is either 0 or 1) and "survival". If the type is "survival", the user must also supply additional data via the parameter censored.

Ignored unless the regression_type is "incidence" and difference_function is set to NULL (in the latter case, you have specified a more custom metric). Then, this parameter allows the user to select which of the three standard metrics to use for comparison: "probability_difference", "risk_ratio", "odds_ratio" where the default is "odds_ratio".

An R function that will be evaluated to construct the personalized medicine / recommendation model. In the formula for the model, the response is "y", the treatment vector is "treatment" and the data is "Xytrain". This function must return some type of object that can be used for prediction later via predict_function. Here are the defaults for each regression_type. They are linear models with first order interactions:

                                    personalized_model_build_function = switch(regression_type,
                                        continuous = function(Xytrain) { #defalt is OLS regression
                                            lm(y ~ . * treatment,
                                                data = Xytrain)
                                        },
                                        incidence = function(Xytrain) { #default is logistic regression
                                            glm(y ~ . * treatment,
                                                data = Xytrain,
                                                family = "binomial")
                                        },
                                        survival = function(Xytrain) { #default is Weibull regression
                                            survreg(Surv(Xytrain$y, Xytrain$censored) ~ (. - censored) * treatment,
                                                data = Xytrain,
                                                dist = "weibull")
                                        }
                                    )
                                    

Only required if the regression_type is "survival". In this case, this vector is of length n and is binary where 0 indicates censored and 1 indicates uncensored. In a clinical trial, someone who is still alive at the end of the study or was lost to follow up will receive a censor value of 0, while someone who died during the study will receive a censor value of 1. n and is binary where 0 indicates censorship (e.g. the patient died).

An R function that will be evaluated on left out data after the model is built with the training data. This function uses the object "mod" that is the result of the personalized_model_build_function and it must make use of "Xyleftout", a subset of observations from X. This function must return a scalar numeric quantity for comparison. The default function is predict(mod, obs_left_out) e.g. the default looks like:

                                    function(mod, Xyleftout) {
                                        predict(mod, Xyleftout)
                                    }
                                    

A function which takes the result of one out of sample experiment (boostrap or not) of all n samples and converts it into a difference that will be used as a score in a score distribution to determine if the personalization model is statistically significantly able to distinguish subjects. The function looks as follows:

                                    function(results, indices_1_1, indices_0_0, indices_0_1, indices_1_0) {
                                        ...
                                        c(rec_vs_non_rec_diff_score, rec_vs_all_score, rec_vs_best_score)
                                    }
                                    

where results is a matrix consisting of columns of the estimated response of the treatment administered, the estimated response of the counterfactual treatment, the administered treatment, the recommended treatment based on the personalization model, the real response, and if this subject was censored (0 if so). Here are a couple of example entries:

est_true est_counterfactual given_tx rec_tx real_y censored 166.8 152.2 1 1 324 1 1679.1 2072.0 1 0 160 0

The arguments indices_1_1, indices_0_0, indices_0_1, indices_1_0 give the indices of the subjects whose treatment was administered as 1 and whose optimal was 1, whose treatment was administered 0 and whose optimal was 0, etc.

This function should return three numeric scores: the recommend vs. the non-recommended (adversarial), the recommended vs. all (all) and the recommended vs. the best average treatment (best) as a 3-dimensional vector as illustrated above.

By default, this parameter is NULL which means for continuous and incidence the average difference is used and for survival, the median Kaplan-Meier survival is used.

A function that is called at the end of a cross validation iteration to cleanup the model in some way. This is used for instance if you would like to release the memory your model is using but generally does not apply. The default is NA for "no function."

True if a response value being higher is clinically "better" than one that is lower (e.g. cognitive ability in a drug trial for the mentally ill). False if the response value being lower is clinically "better" than one that is higher (e.g. amount of weight lost in a weight-loss trial). Default is TRUE.

Prints out a dot for each bootstrap sample. This only works on some platforms.

Prints out full information for each cross validation model for each bootstrap sample. This only works on some platforms.

The \mu_{I_0} value in H_0. Default is NULL which specifies 0 for regression types continuous, survival and incidence (with incidence metric "probability_difference") or 1 if the regression type is incidence and the incidence metric is "risk_ratio" or "odds_ratio". These defaults essentially answer the question: does my allocation procedure do better than the business-as-usual / naive allocation procedure?

In the cross-validation, the proportion of the original dataset left out to estimate out-of-sample metrics. The default is 0.1 which corresponds to 10-fold cross validation.

Within each bootstrap sample, the exponent \gamma used to set the resample size (sampled with replacement) to m = \lfloor n^{\gamma} \rfloor, implementing the "m-out-of-n bootstrap." Politis, Romano & Wolf (Subsampling, 1999) show that bootstrap consistency for non-smooth (non-regular) functionals – as arises here because the treatment recommendation is a hard threshold on the estimated treatment effect – requires m \to \infty and m / n \to 0, i.e. \gamma < 1; \gamma = 1 recovers the classical (and here potentially inconsistent) n-out-of-n bootstrap. The default \gamma = 0.75 follows the Politis-Romano-Wolf recommended rate as a practical compromise between bias (\gamma too close to 1, reintroducing the non-regularity) and excess bootstrap Monte Carlo variance (\gamma too small); see their book for the data-driven "minimum volatility" method for calibrating \gamma to a specific dataset. When \gamma < 1, the reported confidence intervals are rescaled by \sqrt{m / n} as required by m-out-of-n bootstrap theory; this rescaling is a no-op when \gamma = 1 (i.e. m = n).

The number of bootstrap samples to take. We recommend making this as high as you can tolerate given speed considerations. The default is 3000.

Defines the confidence interval size (1 - alpha). Defaults to 0.05.

Do the BCA bootstrap as well. This takes double the time. It defaults to FALSE.

The adversarial score records the personalization metric versus the deliberate opposite of the personalization. This does not correspond to any practical situation but it is useful for debugging. Default is FALSE.

The number of cores to use in parallel to run the bootstrap samples more rapidly. Defaults to NULL which uses max(cores - 1, 1) where cores is detected once when the PTE package is loaded and cached in options(mc.cores = ...) (see ?options). Pass an explicit value here to override the cached default for a single call.

A PTE_bootstrap_results model object built via running the PTE_bootstrap_inference function.

Other methods passed to plot

A PTE_bootstrap_results model object built via running the PTE_bootstrap_inference function.

Other methods passed to print

A n \times p dataframe of covariates where one column is labeled "treatment" and it is a binary vector of treatment allocations in the study. See PTE_bootstrap_inference.

An n-length numeric vector which is the response. See PTE_bootstrap_inference.

See PTE_bootstrap_inference. Default "continuous".

See PTE_bootstrap_inference. Default "odds_ratio".

See PTE_bootstrap_inference. Default NULL (use the built-in default for regression_type).

See PTE_bootstrap_inference. Required if regression_type is "survival".

See PTE_bootstrap_inference. Default NULL (use the built-in default).

See PTE_bootstrap_inference. Default NULL (use the built-in default for regression_type).

See PTE_bootstrap_inference. Default NULL (no cleanup).

See PTE_bootstrap_inference. Default TRUE.

See PTE_bootstrap_inference. Default 0.10.

The grid of candidate \gamma exponents to evaluate (each entry is a candidate value for PTE_bootstrap_inference's m_pow_of_n argument). Must have at least volatility_window entries so every interior grid point has a complete neighborhood. The default, seq(0.5, 1, by = 0.05), brackets the Politis-Romano-Wolf-recommended \gamma = 0.75 on both sides, up to (but not below) \gamma = 0.5 (m = \sqrt{n}, a common lower-rate benchmark) and \gamma = 1 (the classical, here potentially inconsistent, n-out-of-n bootstrap, included only as a reference point – see volatility_window).

Which of the three PTE estimands' confidence interval width to stabilize: "adversarial", "average" (the default) or "best"; see PTE_bootstrap_inference.

The number of bootstrap samples to take at each grid point. Since the total cost is length(m_pow_of_n_grid) * B bootstrap replicates, this defaults to a much smaller 250 than PTE_bootstrap_inference's own default of 3000 – this function is for calibrating m_pow_of_n, not for the final reported inference.

Confidence interval size (1 - alpha) used to measure CI width at each grid point. Defaults to 0.05.

The number of adjacent grid points (must be odd and \geq 3) averaged into the volatility measure at each interior grid point. Only grid points with a complete, centered window are eligible to be selected (this excludes the (volatility_window - 1) / 2 grid points at each end of m_pow_of_n_grid from selection, since their neighborhoods would otherwise be one-sided and their apparent volatility artificially low). Default 3.

See PTE_bootstrap_inference. Passed through unchanged to each grid point's call (grid points are evaluated sequentially, not in additional parallel, to avoid nested parallelism on top of PTE_bootstrap_inference's own).

A PTE_bootstrap_results model object built via running the PTE_bootstrap_inference function.

Other methods passed to summary