fetch_association_state: Fetch the association states from the biomarker model

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

Fetch the association states from the biomarker model

Description

Fetch the association states linking the biomarker model and the survival model

Usage

fetch_association_state(
  run_id,
  level = c("subject", "trial_arm"),
  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 or trial_arm. Default value is per subject.
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

Inferences for association states can be provided at different levels of the hierarchical model:

1. Per subject

2. Per trial_arm

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 parameter (.variable).

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, there will be three values: one per association state estimated

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. subject_id | trial_arm_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()

# ---- Pairs plot of subject states ----
subject_states <- fetch_association_state(run_id, level = 'subject') %>%
         left_join(fetch_subjects() %>%
                        distinct(subject_id, trial_arm_id, trial_arm_name),
                   by = 'subject_id')

ggplot(subject_states %>% spread(association_state, .value),
       aes(x = log1p_time_to_baseline_months, y = log1p_time_to_min_sld_months,
          colour = trial_arm_name)) +
    geom_point()

# ---- summarize sampling quality for trial-arm-level parameters ----

library(posterior)
d <- fetch_association_state(run_id, level = 'trial_arm', return = 'draws')

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

## End(Not run)

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