fetch_predicted_survival: Fetch predicted survival curve over time

In generable/rgeco: R package for accessing the Generable API

Fetch predicted survival curve over time

Description

Fetch predicted survival at regular intervals during the follow-up window.

Usage

fetch_predicted_survival(
  run_id,
  level = c("trial_arm", "study", "subject", "overall"),
  return = c("median", "quantiles", "intervals", "draws"),
  type = c("posterior", "prior"),
  subject_id = NULL,
  individual_id = NULL,
  trial_arm_name = NULL,
  trial_name = NULL,
  trial_id = NULL,
  chains = NULL,
  draws = NULL,
  quantiles = NULL,
  intervals = c(0.5, 0.8, 0.9),
  project = NULL,
  project_version_id = NULL
)

Arguments

run_id	[required] One or several model run_ids. See find_runs for a list of runs available.
level	The level at which to return predicted values. One of: subject, trial_arm, study, or overall. Default value is per trial_arm.
return	The type of summary to return. One of: median, quantiles, intervals, or draws. Default: median
type	Whether to return posterior or prior predictions. Default: posterior
subject_id	If provided, limit results to this set of subject_id(s). This is a unique UUID identifying a subject in the Geco Database. See fetch_subjects for a listing of subject_ids for your project.
individual_id	If provided, limit results to this set of individual_id(s). This typically corresponds to the patient identifier in the original database, which may not be unique across trials and projects.
trial_arm_name	If provided, limit results to this set of trial_arm_name(s). See fetch_subjects for a listing of trial_arm_name(s) for your project.
trial_name	If provided, limit results to this set of trial_name(s). See fetch_subjects for a listing of trial_name(s) for your project.
trial_id	If provided, limit results to this set of trial_id(s). This is a unique UUID for each trial in the Geco Database. See fetch_subjects for a listing of subject_ids for your project.
chains	If provided, limit returned draws to the set of chains listed. Note that chains are 0-indexed on the server. This filter only applies to the draws return type, and will be ignored for other return types.
draws	If provided, limit returned draws to the set of draw indices listed. Note that draws are 0-indexed on the server. This filter only applies to the draws return type, and will be ignored for other return types.
quantiles	If provided, limit returned quantiles to the set of values listed. Only some quantiles are pre-computed, and inputs requested which are not available will be ignored. This filter only applies to the quantiles return type, and will be ignored for other return types.
intervals	If provided, limit returned interval widths to the set of values listed. Only 0.5, 0.8, 0.9 widths are currently, and inputs requested which are not available will be ignored. This filter only applies to the intervals return type, and will be ignored for other return types.
project	The name of the project to which the run_id belongs.
project_version_id	The specific project_version_id to which the run_id belongs. Defaults to the most recent project_version_id if none provided.

Details

Predicted survival values can be provided at different levels of the hierarchical model:

1. Per subject: predict for each subject, using subject-level parameters

2. Per trial_arm: summarize survival over all subjects in a trial-arm, for each followup timepoint

3. Per study: summarize survival over all subjects in a study, for each followup timepoint

4. Overall: summarize survival over all subjects in the run, including simulated data comprising the background set

Use the level argument to select the desired level at which to summarize predicted values.

Authentication (see login) is required prior to using this function. This function accesses information from the Generable API.

There are four slightly different return formats, depending on the return argument provided. See notes for details.

Value

A data.frame in tidy format, with one record per parameter, run_id, and summarized level. See notes for specific details about each return type.

Return format

The columns returned depends on the value of the 'return' argument. The default is to return median values for each level and prediction time (biomarker_time, in days).

All return formats share a set of columns containing meta-information about the predicted quantities:

1. .variable Text label for the predicted quantity or variable. In this case, "predicted_survival"

2. run_id Text field containing the run_id from which each returned value was generated.

3. .type Text field containing the type (prior or posterior) of predicted quantity or inferences summarized.

4. .level Text field containing the level (subject, trial_arm, or overall) at which the predicted values were prepared.

5. survival_time Numeric field containing the study time (days) at which the predicted value was prepared.

6. subject_id | trial_arm_id | trial_id If returning predicted values at the subject, study, or trial-arm level, the ids corresponding to the subjects or trial-arms used in the prediction.

In addition, there will be a few columns to provide and describe the predicted quantities. The set of columns included here will depend on the 'return' argument:

1. if return == 'median', a pair of columns: .value and .point

2. if return == 'quantiles', a pair of columns: .value and quantile

3. if return == 'intervals', a set of columns: .value, .width, .lower, and .upper containing the median estimate (.value) along with the lower (.lower) and upper (.upper) bounds for the 50, 80, and 90 percent credible intervals (.width).

   • In addition, columns .point and .interval describe the type of point estimate ('median') and interval ('qi')

   • This data structure mimics that returned by median_qi function in the tidybayes package.

4. if return == 'draws', a set of columns: .value, .chain, .iteration, and .draw describing the predicted quantities for each draw, chain and iteration. This data structure mimics the draws_df format from the posterior package.

Examples

## Not run: 
library(tidybayes)
library(tidyverse)

login()

# ---- Plot median predicted survival over time ----
d <- fetch_predicted_survival(run_id, level = 'overall')

ggplot(d, aes(x = survival_time, y = .value)) +
  geom_line() +
  scale_y_continuous('Predicted Survival', labels = scales::percent)


# ---- Plot predicted survival over time from intervals ----
d <- fetch_predicted_survival(run_id, level = 'overall', return = 'intervals')

ggplot(d, aes(x = survival_time, y = .value, ymin = .lower, ymax = .upper, group = .width)) +
  geom_lineribbon(alpha = 0.2) +
  scale_y_continuous('Predicted Survival', labels = scales::percent) +
  scale_fill_brewer()


# ---- Plot predicted survival by trial-arm over time ----
d <- fetch_predicted_survival(run_id, level = 'trial_arm', return = 'intervals') %>%
     inner_join(fetch_subjects() %>% distinct(trial_arm_id, trial_arm_name))

ggplot(d, aes(x = survival_time, y = .value, ymin = .lower, ymax = .upper, group = .width,
   fill = trial_arm_name, colour = trial_arm_name)) +
  geom_lineribbon(alpha = 0.2) +
  scale_y_continuous('Predicted Survival', labels = scales::percent) +
  theme(legend.position = 'bottom') +
  facet_wrap(~ trial_arm_name)


# ----Plot predicted survival over time from draws ----
d <- fetch_predicted_survival(run_id, level = 'overall', return = 'draws')

ggplot(d, aes(x = survival_time, y = .value)) +
  stat_lineribbon(alpha = 0.4, .width = c(0.66, 0.99)) +
  scale_y_continuous('Predicted Survival', labels = scales::percent) +
  scale_fill_brewer() +
  theme_minimal()

# ---- summarize sampling quality ----

library(posterior)
d <- fetch_predicted_survival(run_id, level = 'overall', return = 'draws')

d %>% spread(.variable, .value) %>%
   group_by(.level, survival_time, .type, run_id) %>%
   group_modify(~ summarise_draws(.x))

## End(Not run)

generable/rgeco documentation built on Oct. 16, 2024, 2:45 a.m.