Summarize a trial into the quantities a synthetic copy is built from

The only stage that reads patient data. Reduces each subject's trajectories and baseline covariates to principal-component scores, models those scores against the arm, and fits a dosing model and a visit model per arm. The returned object holds nothing but summaries: no patient row survives it.

Usage

synpmx_pca_summarize(
  data,
  roles,
  seed = NULL,
  dose_term = c("factor", "log"),
  pca_variance = 0.9,
  n_components = NULL,
  min_column_patients = NULL,
  min_arm_patients = 3L,
  min_category_patients = 3L
)

Arguments

data: Source PMX event data.
roles: Explicit column roles from pmx_roles(), including nominal_time.
seed: Seed for the one random step in summarizing: censored values are replaced by a draw inside the censoring region before the basis is fitted, so that a column where most subjects sit at the assay limit describes the patients rather than the assay. The boundary is reapplied at generation.
dose_term: How dose enters the score model. "factor" gives each arm its own mean score vector and its own residual covariance. "log" regresses the scores on log1p() of the total dose, which spends one coefficient rather than one mean per arm and extrapolates to doses the study did not run, at the cost of assuming the dose-response is log-linear and that every arm has the same between-subject spread. A lower limit of quantification breaks both assumptions, which is why "factor" is the default.
pca_variance: Cumulative variance the retained components must reach.
n_components: Number of components, overriding pca_variance.
min_column_patients: Minimum distinct patients holding an observation in a grid cell for that cell to be modelled. Defaults to the larger of 3 and a tenth of the cohort.
min_arm_patients: Minimum patients in every arm. An arm below it has no spread of its own to model, so its mean score vector and its covariance would describe the one or two patients in it. Those patients are dropped with a warning naming the arms, and the synthetic data has no such arm. Pool the arm, drop the column from strata, or lower this to keep them.
min_category_patients: Minimum distinct patients holding a level of a categorical covariate, a keep value in an arm, or a level the summary's schema stores, 3 by default, as synpmx_model_estimate() uses. A rarer covariate level gets no column in the basis and cannot be generated; the patients holding it are treated as missing on that covariate. Set to 1 to retain all observed levels.

Value

A pmx_trial_summary.

Details

Run this, look at what it produced with pca_report(), pca_dosing(), pca_visits() and pca_components(), then pass it to synpmx_pca_generate(). Generation reads the model and nothing else, so what those four functions show is the whole of what the synthetic data was built from.

nominal_time is required. The grid it names is the axis every feature sits on, and dose rows and observation rows are placed on it together, so it is the caller's statement about the protocol rather than something inferred from recorded times.

No formal privacy claim is made.

Examples

data <- pmx_simulated_fixture(60)
roles <- pmx_roles(
  id = "ID", time = "TIME", nominal_time = "NTIME", dv = "DV", amt = "AMT",
  evid = "EVID", cmt = "CMT", dvid = "DVID", mdv = "MDV"
)
trial_summary <- synpmx_pca_summarize(data, roles)
trial_summary
#> A trial summary, from synpmx_pca_summarize()
#> 
#>   fitted on    60 patients, 1 arm(s): all (60) 
#>   endpoints    cp (8 visits modelled), pd (6 visits modelled) 
#>   covariates   none 
#>   components   1 (100% of variance) 
#>   dose term    factor 
#>   dosing       2 planned cycle(s) per arm | no reductions, interruptions or early stops 
#> 
#> synpmx_pca_generate() reads this object and nothing else. To look inside it:
#>   pca_report()      what it read out of the source data
#>   pca_dosing()      the planned dose schedule, per arm
#>   pca_dose_rates()  reduction, interruption and discontinuation
#>   pca_visits()      each endpoint's attendance rate, at each visit an arm has
#>   pca_components()  the loadings, over time
pca_report(trial_summary)
#> What the PCA fit read out of the source data
#> 
#>   subjects: 60  components retained: 1 
#> 
#>             quantity
#>           visit grid
#>      feature centers
#>       feature scales
#>             loadings
#>          score means
#>     score covariance
#>  endpoint transforms
#>         assay limits
#>         dosing model
#>          visit model
#>        arm constants
#>                                                             what numbers
#>                             Nominal times modelled, per endpoint      14
#>                             Mean of each grid cell and covariate      14
#>                                   Standard deviation of the same      14
#>                               Component loadings on each feature      14
#>                                       Mean score vector, per arm       1
#>                           Residual covariance between components       1
#>                                    Log or identity, per endpoint       2
#>                                 Censoring boundary, per endpoint       0
#>  Planned cycles per arm; the dose ladder and three rates, pooled       8
#>     One attendance rate per endpoint, at the visits each arm has      14
#>                       Strata and kept columns, one value per arm       0
#>  min_patients
#>            60
#>            60
#>            60
#>            60
#>            60
#>            60
#>            60
#>            60
#>            60
#>            60
#>            60