Skip to contents

Per-symptom inclusion counts across optimization scenarios

Source: R/scenario_tables.R
symptom_frequency.Rd

Returns a long-format data frame giving how often each of the 20 PCL-5 symptoms appears in the top combinations of each scenario in a compare_optimizations result. This is the data source for plot_symptom_frequency and matches the structure of the preprint's Supplementary Table S4.

Usage

symptom_frequency(
  comparison,
  include_overall = TRUE,
  overall_includes_fixed = FALSE,
  clusters = NULL
)

Arguments

comparison

A ptsdiag_comparison object.

include_overall

Logical. If TRUE (default), an OVERALL row is appended that pools across scenarios.

overall_includes_fixed

Logical. If TRUE, fixed criteria contribute to the OVERALL row. Default FALSE.

clusters

Named list of item indices defining the clusters used by the hierarchical scenarios, for the Baseline column. Defaults to the standard DSM-5-TR PCL-5 clusters.

Value

A data.frame with columns Symptom (integer 1-20), Approach (factor with levels in scenario order, optionally ending in "OVERALL"), Count (integer), RelFreq (numeric in \[0, 1\]), Baseline (the chance selection frequency for that scenario, NA for fixed criteria) and Enrichment (RelFreq / Baseline).

Details

For optimize scenarios, Count ranges from 0 to n_top (the number of stored combinations). For fixed scenarios such as ICD-11, the fixed symptom set contributes exactly one combination so Count is either 0 or 1. RelFreq normalises Count by the number of combinations stored in that scenario.

The optional OVERALL row pools counts across scenarios. By default fixed scenarios are excluded from the OVERALL pool so that OVERALL continues to reflect data-driven symptom selection. Set overall_includes_fixed = TRUE to weight every combination equally.

RelFreq cannot be read on its own. Every combination contains the same number of items, so the frequencies are zero-sum and an item can only gain at another's expense. Baseline gives the proportion of the scenario's own candidate space that contains each item, and Enrichment their ratio: values above 1 mean the item was selected more often than drawing combinations at random would produce. The baseline matters most under the hierarchical rule, where it varies by cluster because every combination must draw at least one item from each. Fixed criteria such as ICD-11 have no candidate space, so both columns are NA for them.

See also

compare_optimizations, plot_symptom_frequency, summarize_top_combinations.

Examples

# \donttest{
# Use a 250-row subset and a small 4-symptom search to keep the example
# fast; omit `scenarios` to run the three default rules
ptsd_data <- rename_ptsd_columns(simulated_ptsd[1:250, ],
                                 id_col = c("patient_id", "age", "sex"))
comp <- compare_optimizations(
  ptsd_data,
  scenarios = list(
    "3/4 Non-hierarchical" = list(n_symptoms = 4, n_required = 3,
                                  hierarchical = FALSE)
  ),
  include_icd11 = TRUE, n_top = 5, show_progress = FALSE
)
#> ℹ Evaluated 4845 combinations. Best: 6, 7, 12, 17
freq <- symptom_frequency(comp)
head(freq)
#>   Symptom             Approach Count RelFreq Baseline Enrichment
#> 1       1 3/4 Non-hierarchical     0     0.0      0.2          0
#> 2       2 3/4 Non-hierarchical     0     0.0      0.2          0
#> 3       3 3/4 Non-hierarchical     0     0.0      0.2          0
#> 4       4 3/4 Non-hierarchical     2     0.4      0.2          2
#> 5       5 3/4 Non-hierarchical     0     0.0      0.2          0
#> 6       6 3/4 Non-hierarchical     5     1.0      0.2          5
# }