Updating vignettes to reflect changes

vignettes/ep_overview.Rmd

@@ -51,7 +51,7 @@ The parameters of each endpoint specification can be grouped in to the sets belo
   <th>Endpoint parameter</th>
  </tr>
  <tr>
-  <td rowspan="13">Population and outcome specifications</td>
+  <td rowspan="14">Population and outcome specifications</td>
   <td rowspan="2">[ADaM data](ep_spec_adam_data.html). What data to use and how to consolidate it into a single data table for the endpoint that is used to calculate statistics.</td>
   <td>`study_metadata`</td>
  </tr>
@@ -89,13 +89,16 @@ The parameters of each endpoint specification can be grouped in to the sets belo
   <td>`group_by`</td>
  </tr>
  <tr>
-  <td rowspan="1">[Strata](ep_spec_strata_def.html). How to slice the data within the endpoint.</td>
+  <td rowspan="2">[Strata](ep_spec_strata_def.html). How to slice the data within the endpoint and if only slices with events should be kept.</td>
   <td>`stratify_by`</td>
+ </tr>
+ <tr>
+  <td>`only_strata_with_events`</td>
  </tr>
   <tr>
-  <td rowspan="1">[Endpoint label](ep_spec_label.html). What events the endpoint describes.</td>
+  <td rowspan="1">[Endpoint label](ep_spec_label.html). Description of what events the endpoint presents.</td>
   <td>`endpoint_label`</td>
- </tr>
+ </tr> 
  <tr>
   <td rowspan="6">Methods</td>
   <td rowspan="3">[Criteria methods](methods_criteria.html). Requirements that must be met to include different types of statistics in the endpoint results.</td>

vignettes/ep_spec_strata_def.Rmd

@@ -22,7 +22,7 @@ These are the key properties of the `stratify_by` parameter:
 
 * `stratify_by` is a `list()` object
 * The list may be empty if no stratification is needed. 
-* Regardless of whether any srtata are specified (and meet the strata criteria c.f. [Criteria methods](methods_criteria.html)) or not, the endpoint statistics will always be derived for the *total* analysis population in the endpoint. The *total* can be considered a special stratum with only one level. 
+* Regardless of whether any strata are specified (and meet the strata criteria c.f. [Criteria methods](methods_criteria.html)) or not, the endpoint statistics will always be derived for the *total* analysis population in the endpoint. The *total* is a special stratification with only one level. 
 * The stratum values are not required in `stratify_by`. All relevant statistics will be applied to each stratum.
 * The strata variables are applied independently, i.e. strata will not be combined. So if e.g. you stratify by age group and gender, you will not have cross combination such as `SEX="F" & AGEGR="<65"`. 
 
@@ -31,6 +31,9 @@ If cross combinations of two stratum variables `A` and `B` are required, either:
 1. Create a derived variable in `data_prepare` that combines `A` and `B` and stratify on this new variable.
 2. Use `endpoint_filter` or `group_by` to group or filter the data on `A` and then stratify on `B` within each group level.
 
+The `only_strata_with_events` Boolean endpoint parameter enables the user to trim the set of presented stratification levels to those that only contain events. 
+Activating this trimming may save a considerable amount of computation time if the combination of `group_by` and `stratify_by` forms many hundreds of strata levels of which only a handful of strata levels have events and are of interest. 
+
 # Examples
 
 ##### Ex 5.1

vignettes/results_datamodel.Rmd

@@ -14,9 +14,10 @@ knitr::opts_chunk$set(
 )
 ```
 
-The output from {chef} is a `data.table` containing the statistics for each stratum within each endpoint based on the specified analysis data for each endpoint.
+The primary output from {chef} is a `data.table` containing the statistics for each stratum within each endpoint based on the specified analysis data for each endpoint.
+For bookkeeping, any endpoints or strata that have not been accepted are stored in another output `data.table`, which has the same data structure, except it only contains a subset of relevant columns.
 
-The columns in the table contain information on six different hierarchical levels, meaning that e.g. information on level 2 is a sub level of level 1. 
+The columns in the primary output contain information on six different hierarchical levels, meaning that e.g. information on level 2 is a sub level of level 1. 
 
 The table utilizes a long format structure, ensuring that each row corresponds to the most granular level of information (level 6). This level comprises individual statistical outcomes derived from the applied statistical functions. 
 
@@ -42,7 +43,7 @@ The table below describes all the columns in the output table. Note that informa
 </thead>
 <tbody>
  <tr>
- <td rowspan="13">Level 1: Endpoint specification</td>
+ <td rowspan="14">Level 1: Endpoint specification</td>
  <td>`endpoint_spec_id`</td>
  <td>int</td>
  <td>Id of endpoint specification.</td>
@@ -102,18 +103,18 @@ The table below describes all the columns in the output table. Note that informa
  <td>list</td>
  <td>List of variables on which to stratify the analysis data.</td>
  </tr>
+ <tr>
+ <td>`only_strata_with_events`</td>
+ <td>logical</td>
+ <td>Optionally specify if all strata levels without events should be removed. Default is ``FALSE`.</td>
+ </tr>
  <tr>
  <td>`key_analysis_data`</td>
  <td>char</td>
  <td>Id of analysis data set (filtered by population filter).</td>
  </tr>
  <tr>
- <td rowspan="7">Level 2: Endpoint</td>
- <td>`empty`</td>
- <td>logical</td>
- <td>Indicates if the endpoint is empty (no events).</td>
- </tr>
- <tr>
+ <td rowspan="6">Level 2: Endpoint</td>
  <td>`endpoint_group_metadata`</td>
  <td>list</td>
  <td>Specification of group slice.</td>
@@ -141,7 +142,7 @@ The table below describes all the columns in the output table. Note that informa
  <tr>
  <td>`crit_accept_endpoint`</td>
  <td>logical</td>
- <td>Evaluation of crit_endpoint.</td>
+ <td>Evaluation of `crit_endpoint`.</td>
  </tr>
  <tr>
  <td rowspan="4">Level 3: Stratifier</td>
@@ -165,7 +166,7 @@ The table below describes all the columns in the output table. Note that informa
  <td>Evaluation of `crit_by_strata_across_trt`.</td>
  </tr>
  <tr>
- <td rowspan="5">Level 4: Statistical function</td>
+ <td rowspan="4">Level 4: Statistical function</td>
  <td>`fn_hash`</td>
  <td>char</td>
  <td>Id of stat function.</td>
@@ -185,16 +186,11 @@ The table below describes all the columns in the output table. Note that informa
  <td>char</td>
  <td>Stat function parsing (name of stat function and arguments).</td>
  </tr>
- <tr>
- <td>`fn_callable`</td>
- <td>list</td>
- <td>Stat function code.</td>
- </tr>
  <tr>
  <td rowspan="5">Level 5: Stratum</td>
- <td>`stat_empty`</td>
+ <td>`stat_event_exist`</td>
  <td>logical</td>
- <td>Indicates if stratum is empty (`cell_index` is empty).</td>
+ <td>Indicates if the stratum contains any events, i.e. if the intersection of `event_index` and `cell_index` is non-empty (`TRUE`) or not (`FALSE`).</td>
  </tr>
  <tr>
  <td>`stat_metadata`</td>
@@ -217,15 +213,20 @@ The table below describes all the columns in the output table. Note that informa
  <td>Indices (rows) in the analysis data included in the stratum.</td>
  </tr>
  <tr>
- <td rowspan="3">Level 6: Statistics</td>
+ <td rowspan="4">Level 6: Statistics</td>
  <td>`stat_result_description`</td>
  <td>char</td>
  <td>Description of the statistics (returned from statistical function).</td>
  </tr>
  <tr>
  <td>`stat_result_label`</td>
  <td>char</td>
- <td>Label to the statistical value (returned from statistical function).</td>
+ <td>Label to the statistics (returned from statistical function).</td>
+ </tr>
+ <tr>
+ <td>`stat_result_qualifiers`</td>
+ <td>char</td>
+ <td>Qualifiers to the statistics (returned from statistical function).</td>
  </tr>
  <tr>
  <td>`stat_result_value`</td>