derive_extreme_event: Add the Worst or Best Observation for Each By Group as New...

In admiral: ADaM in R Asset Library

Add the Worst or Best Observation for Each By Group as New Records

Description

Add the first available record from events for each by group as new records, all variables of the selected observation are kept. It can be used for selecting the extreme observation from a series of user-defined events. This distinguishes derive_extreme_event() from derive_extreme_records(), where extreme records are derived based on certain order of existing variables.

Usage

derive_extreme_event(
  dataset = NULL,
  by_vars,
  events,
  tmp_event_nr_var = NULL,
  order,
  mode,
  source_datasets = NULL,
  check_type = "warning",
  set_values_to = NULL,
  keep_source_vars = exprs(everything())
)

Arguments

dataset	Input dataset The variables specified by the by_vars and order arguments are expected to be in the dataset.
by_vars	Grouping variables
events	Conditions and new values defining events A list of event() or event_joined() objects is expected. Only observations listed in the events are considered for deriving extreme event. If multiple records meet the filter condition, take the first record sorted by order. The data is grouped by by_vars, i.e., summary functions like all() or any() can be used in condition. For event_joined() events the observations are selected by calling filter_joined(). The condition field is passed to the filter_join argument.
tmp_event_nr_var	Temporary event number variable The specified variable is added to all source datasets and is set to the number of the event before selecting the records of the event. It can be used in order to determine which record should be used if records from more than one event are selected. The variable is not included in the output dataset.
order	Sort order If a particular event from events has more than one observation, within the event and by group, the records are ordered by the specified order. For handling of NAs in sorting variables see the "Sort Order" section in vignette("generic").
mode	Selection mode (first or last) If a particular event from events has more than one observation, "first"/"last" is used to select the first/last record of this type of event sorting by order.
source_datasets	Source datasets A named list of datasets is expected. The dataset_name field of event() and event_joined() refers to the dataset provided in the list.
check_type	Check uniqueness? If "warning" or "error" is specified, the specified message is issued if the observations of the input dataset are not unique with respect to the by variables and the order.
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. For example: set_values_to = exprs( PARAMCD = "WOBS", PARAM = "Worst Observations" )
keep_source_vars	Variables to keep from the source dataset For each event the specified variables are kept from the selected observations. The variables specified for by_vars and created by set_values_to are always kept. The keep_source_vars field of the event will take precedence over the value of the keep_source_vars argument.

Details

1. For each event select the observations to consider:

   1. If the event is of class event, the observations of the source dataset are restricted by condition and then the first or last (mode) observation per by group (by_vars) is selected.

      If the event is of class event_joined, filter_joined() is called to select the observations.

   2. The variables specified by the set_values_to field of the event are added to the selected observations.

   3. The variable specified for tmp_event_nr_var is added and set to the number of the event.

   4. Only the variables specified for the keep_source_vars field of the event, and the by variables (by_vars) and the variables created by set_values_to are kept. If keep_source_vars = NULL is used for an event in derive_extreme_event() the value of the keep_source_vars argument of derive_extreme_event() is used.

2. All selected observations are bound together.

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

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

5. The observations are added to input dataset.

Note: This function creates temporary datasets which may be much bigger than the input datasets. If this causes memory issues, please try setting the admiral option save_memory to TRUE (see set_admiral_options()). This reduces the memory consumption but increases the run-time.

Value

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

See Also

event(), event_joined(), derive_vars_extreme_event()

BDS-Findings Functions for adding Parameters/Records: default_qtc_paramcd(), derive_expected_records(), derive_extreme_records(), 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.