derive_extreme_records: Add the First or Last Observation for Each By Group as New...

In admiral: ADaM in R Asset Library

Add the First or Last Observation for Each By Group as New Records

Description

Add the first or last observation for each by group as new observations. The new observations can be selected from the additional dataset. This function can be used for adding the maximum or minimum value as a separate visit. All variables of the selected observation are kept. This distinguishes derive_extreme_records() from derive_summary_records(), where only the by variables are populated for the new records.

Usage

derive_extreme_records(
  dataset = NULL,
  dataset_add,
  dataset_ref = NULL,
  by_vars = NULL,
  order = NULL,
  mode = NULL,
  filter_add = NULL,
  check_type = "warning",
  exist_flag = NULL,
  true_value = "Y",
  false_value = NA_character_,
  keep_source_vars = exprs(everything()),
  set_values_to
)

Arguments

dataset	Input dataset If the argument is not specified (or set to NULL), a new dataset is created. Otherwise, the new records are appended to the specified dataset.
dataset_add	Additional dataset The additional dataset, which determines the by groups returned in the input dataset, based on the groups that exist in this dataset after being subset by filter_add. The variables specified in the by_vars and filter_add parameters are expected in this dataset. If mode and order are specified, the first or last observation within each by group, defined by by_vars, is selected.
dataset_ref	Reference dataset The variables specified for by_vars are expected. For each observation of the specified dataset a new observation is added to the input dataset. For records which are added from dataset_ref because there are no records in dataset_add for the by group only those variables are kept which are also in dataset_add (and are included in keep_source_vars).
by_vars	Grouping variables If dataset_ref is specified, this argument must be specified.
order	Sort order Within each by group the observations are ordered by the specified order.
mode	Selection mode (first or last) If "first" is specified, the first observation of each by group is added to the input dataset. If "last" is specified, the last observation of each by group is added to the input dataset.
filter_add	Filter for additional dataset (dataset_add) Only observations in dataset_add fulfilling the specified condition are considered.
check_type	Check uniqueness? If "warning" or "error" is specified, the specified message is issued if the observations of the (restricted) additional dataset are not unique with respect to the by variables and the order.
exist_flag	Existence flag The specified variable is added to the output dataset. For by groups with at least one observation in the additional dataset (dataset_add) exist_flag is set to the value specified by the true_value argument. For all other by groups exist_flag is set to the value specified by the false_value argument.
true_value	True value For new observations selected from the additional dataset (dataset_add), exist_flag is set to the specified value.
false_value	False value For new observations not selected from the additional dataset (dataset_add), exist_flag is set to the specified value.
keep_source_vars	Variables to be kept in the new records A named list or tidyselect expressions created by exprs() defining the variables to be kept for the new records. The variables specified for by_vars and set_values_to need not be specified here as they are kept automatically.
set_values_to	Variables to be set The specified variables are set to the specified values for the new observations. Set a list of variables to some specified value for the new records LHS refer to a variable. RHS refers to the values to set to the variable. This can be a string, a symbol, a numeric value, an expression or NA. If summary functions are used, the values are summarized by the variables specified for by_vars. Any expression on the RHS must result in a single value per by group. For example: set_values_to = exprs( AVAL = sum(AVAL), DTYPE = "AVERAGE", )

Details

1. The additional dataset (dataset_add) is restricted as specified by the filter_add argument.

2. For each group (with respect to the variables specified for the by_vars argument) the first or last observation (with respect to the order specified for the order argument and the mode specified for the mode argument) is selected.

3. If dataset_ref is specified, observations which are in dataset_ref but not in the selected records are added. Variables that are common across dataset_ref, dataset_add and keep_source_vars() are also populated for the new observations.

4. The variables specified by the set_values_to argument are added to the selected observations.

5. The variables specified by the keep_source_vars argument are selected along with the variables specified in by_vars and set_values_to arguments.

6. The observations are added to input dataset (dataset). If no input dataset is provided, a new dataset is created.

Value

The input dataset with the first or last observation of each by group added as new observations.

See Also

derive_summary_records()

BDS-Findings Functions for adding Parameters/Records: default_qtc_paramcd(), derive_expected_records(), derive_extreme_event(), derive_locf_records(), derive_param_bmi(), derive_param_bsa(), derive_param_computed(), derive_param_doseint(), derive_param_exist_flag(), derive_param_exposure(), derive_param_framingham(), derive_param_map(), derive_param_qtc(), derive_param_rr(), derive_param_wbc_abs(), derive_summary_records()

admiral documentation built on May 28, 2026, 9:08 a.m.