fetch_draws: Fetch draws from the Generable API for a run

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

Fetch draws from the Generable API for a run

Description

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

Usage

fetch_draws(
  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 limit draws returned (alternate version of providing ...)
...	(lists) advanced feature used to limit draws returned. Example: draws = c(0:10), chains = 0 to limit to first chain, 10 draws. Filters are applied server-side so they use 0-indexing. Example: trial_arm = unique(subjects$trial_arm_id) to limit draws 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 of a particular parameter and their names server-side.

Details

This function retrieves the draws from the Generable API for one or more model runs.

The user provides a parameter or predictive quantity to query.

The returned object is a data.frame in long format, mimicking the structure of draws_df in the posterior package. The data.frame has columns 'run_id', '.chain', '.iteration', '.variable', '.value', and '.draw', plus the coordinates (indices) for the multi-dimensional parameters.

Note: this function may take a long time to return depending on the size of the parameter. If a summary of the parameter is sufficient, use fetch_quantiles to access the quantiles of the draw.

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

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

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

Value

'data.frame' of draws in long format with '.chain', '.iteration', '.variable', '.value', and '.draw'.

Note

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_quantiles, list_parameter_names, list_predictive_names

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