Skip to contents

Summarise a transported plateau for release

Source: R/transport.R
transport_plateau.Rd

The releasable counterpart of evaluate_sets. A site that holds data it cannot share receives a list of symptom combinations derived elsewhere, evaluates them locally, and returns two things and nothing else:

  • a five-number summary of balanced accuracy, sensitivity and specificity across each transported plateau – order statistics over combinations, with the combination-to-value linkage discarded;

  • two-by-two counts for a short, pre-specified list of named combinations.

Usage

transport_plateau(
  data,
  plateau_specs,
  named_specs,
  sample_id,
  payload_id = NA_character_,
  flag_cell = 5L
)

Arguments

data

A data frame with symptom_1 through symptom_20.

plateau_specs

A named list of plateau specifications. Each element is a list with derivation, rule_form, delta, n_required, clusters and sets.

named_specs

A named list of the same shape, each additionally carrying ranks alongside sets.

sample_id

Identifier of this sample. It names every returned file and appears as a column in every returned table.

payload_id

Identifier of the payload these combinations came from, carried through to the returns so a bundle can be matched to the request that produced it. Optional.

flag_cell

Warn about any two-by-two cell below this size.

Value

An object of class ptsdiag_transport: a list of summary, named, sample_id and payload_id. Because the point of this object is that its contents are exactly what may be released, both tables are listed in full.

  • summary: one row per plateau specification and metric, with sample_id, payload_id, derivation, rule_form, delta, metric ("ba", "sensitivity", "specificity"), and the five-number summary n_sets, min, q1, median, q3, max. No combination identifiers appear here.

  • named: one row per named combination plus one for ICD-11, with sample_id, payload_id, derivation, rule_form, rank, set_id, the counts tp, fn, fp, tn, and every non-count column of diagnostic_metrics computed from them (n, n_pos, n_neg, prevalence, sensitivity, specificity, ppv, npv, accuracy, ba, lr_pos, lr_neg, kappa, each with _lo and _hi Wilson bounds where applicable, and pct_agreement).

Details

Why the linkage is discarded. Per-combination (tp, fp, fn, tn) for a whole candidate space of 38,760 six-item subsets is 77,520 linear constraints on the response-pattern count vector, which in a sample of a few hundred has at most a few hundred non-zero entries among 2^20. That is an over-determined sparse-recovery problem, so the multiset of binarized response patterns cross-classified by reference label would be recoverable – and at that size a rare pattern is effectively an individual record. A five-number summary over combinations supports no such reconstruction.

This function therefore has no argument that emits per-combination detail for a plateau. That is deliberate: a collaborator cannot release it by accident.

Counts for the named combinations are not suppressed when small, because a confusion-matrix table of a handful of pre-specified rules is standard reporting and blanking cells would empty it. Instead flag_cell warns, so a small-cell disclosure is visible before the bundle is sent.

See also

write_transport to serialise, evaluate_sets for the per-combination results that stay local.

Examples

# \donttest{
ptsd_data <- rename_ptsd_columns(
  simulated_ptsd_genpop[1:400, c("patient_id", paste0("S", 1:20))],
  id_col = "patient_id")
fit <- score_all_combinations(ptsd_data, n_symptoms = 3, n_required = 2,
                              show_progress = FALSE)
plateau <- compute_plateau(fit, delta = 1)

bundle <- transport_plateau(
  ptsd_data,
  plateau_specs = list(list(derivation = "example", rule_form = "flat_2_3",
                            delta = 1, n_required = 2, clusters = NULL,
                            sets = plateau$sets$combination_id)),
  named_specs = list(list(derivation = "example", rule_form = "flat_2_3",
                          n_required = 2, clusters = NULL,
                          sets = fit$combination_id[1:3], ranks = 1:3)),
  sample_id = "site_a"
)
bundle
#> <ptsdiag_transport>
#>   sample:      site_a
#>   payload:     NA
#>   summaries:   3 rows (1 derivation(s) x 1 rule form(s) x 1 delta x 3 metrics)
#>   named sets:  4 rows
bundle$summary
#>   sample_id payload_id derivation rule_form delta      metric n_sets       min
#> 1    site_a       <NA>    example  flat_2_3     1          ba      1 0.9204812
#> 2    site_a       <NA>    example  flat_2_3     1 sensitivity      1 0.9213483
#> 3    site_a       <NA>    example  flat_2_3     1 specificity      1 0.9196141
#>          q1    median        q3       max
#> 1 0.9204812 0.9204812 0.9204812 0.9204812
#> 2 0.9213483 0.9213483 0.9213483 0.9213483
#> 3 0.9196141 0.9196141 0.9196141 0.9196141
# }