fetch_quantiles: Fetch quantiles from the Generable API for a run

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

Fetch quantiles from the Generable API for a run

Description

Fetch quantiles of the specified parameter or predictive quantity from the Generable API for a model run

Usage

fetch_quantiles(
  parameter,
  run_id,
  project = NULL,
  project_version_id = NULL,
  type = c("posterior", "prior"),
  quiet = FALSE,
  .dots = list(),
  ...
)

Arguments

parameter	(str) [required] Name(s) of the parameters or predictive quantities to be retrieved. See list_parameter_names and list_predictive_names.
run_id	(str) [required] Run id(s). See find_runs to see runs available for this project.
project	(str) Project name. If NULL, defaults to value of environment variable GECO_API_PROJECT
project_version_id	(str) Project version. If NULL, defaults to the most recent version of the project if provided, or the value of environment variable GECO_API_PROJECT_VERSION
type	(str) Type of quantile to return, either posterior or prior. Default is 'posterior'. To access prior quantiles, set this to 'prior'.
quiet	(bool) if TRUE, suppress informative messages
.dots	(lists) advanced feature used to filter quantiles returned (alternate version of providing ...)
...	(lists) advanced feature used to filter quantiles returned. Example: quantile = c(0.5) to limit results to the median, rather than return all quantiles. Example: trial_arm = unique(subjects$trial_arm_id) to limit quantiles to a set of trial arms, for a parameter estimated per trial arm However, use of this feature requires that one be familiar with both the dimensions for a particular parameter and their names server-side.

Details

This function retrieves the quantiles from the Generable API for a model run. The user specifies the parameter or predictive quantity to query.

The returned object is a data.frame with one record per run, parameter, combination of parameter indices, and quantile value.

The data.frame has columns: 'quantile', '.variable', 'run_id', and '.value' columns, along with the dimensions over which the parameter is estimated such as 'subject', 'survival_time', or 'study'.

Use format_quantiles_as_widths to convert this to a format mimicking the format used by tidybayes.

Posterior quantiles are returned by default. The prior quantiles can be accessed by setting the 'type' argument to 'prior'.

Authentication (see login) is required prior to using this function and this pulls the quantiles from the Generable API.

Value

'data.frame' of quantiles in long format with 'quantile', '.variable', and '.value' columns for the 0.05, 0.10, 0.25, 0.50, 0.75, 0.90, and 0.95 quantile probabilities.

Note

The quantile probabilites are set to 0.05, 0.10, 0.25, 0.50, 0.75, 0.90, and 0.95. Other quantile probabilities can be computed directly from the draws, if necessary.

The parameters or predictive quantities for a particular model run can be found by calling list_parameter_names or list_predictive_names.

A project can be specified by using the project name or a specific project version.

1. If a project is specified using the name, data is fetched for the latest version of the project.

2. If a project is specified using the project version, the project name is not required.

3. If neither a project nor a project version is provided, the default project or project version is used. These are set by the environment variables GECO_API_PROJECT and GECO_API_PROJECT_VERSION

Both the parameter & run_id arguments are vectorized. In the case of multiple values, the rows returned for each run and/or parameter are concatenated into a single data.frame. This is intended for use where the runs use the same model, and parameters are similar dimension.

See Also

fetch_draws, list_parameter_names, list_predictive_names, format_quantiles_as_widths

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