R/design-study.R

In R4VN: Health Data Analysis and Publication-Ready Reporting

.r4vn_design_recommend_study <- function(purpose, answers = list()) {
  a <- answers
  out <- list(
    id = .r4vn_design_id("SD"),
    purpose = purpose,
    answers = answers,
    design = NA_character_,
    subtype = NULL,
    why = character(),
    alternatives = character(),
    best_for = character(),
    considerations = character(),
    guideline = NULL,
    reference = NULL
  )

  if (identical(purpose, "describe")) {
    target <- a$describe_target %||% "proportion"
    if (target %in% c("proportion", "mean", "distribution")) {
      out$design <- "Descriptive cross-sectional study"
      out$why <- c(
        "The primary objective is descriptive rather than causal.",
        "Participants are assessed within a defined study period without investigator-assigned exposure.",
        "The design is appropriate for estimating population characteristics such as prevalence, means, or distributions."
      )
      out$best_for <- c("Prevalence", "Population means", "Population distributions")
      out$considerations <- c("Representative sampling", "Non-response", "Clear target population and eligibility criteria")
      out$guideline <- "STROBE cross-sectional reporting guidance"
    } else {
      out$design <- "Prospective cohort / incidence study"
      out$why <- c(
        "The primary target is an incidence or rate that requires observation of new events over time.",
        "Participants therefore need a defined time at risk and follow-up."
      )
      out$best_for <- c("Incidence proportion", "Incidence rate", "Time-to-event")
      out$considerations <- c("Follow-up duration", "Loss to follow-up", "Person-time definition")
      out$guideline <- "STROBE cohort reporting guidance"
    }
  }

  if (identical(purpose, "association")) {
    basis <- a$selection_basis %||% "population"
    if (identical(basis, "outcome")) {
      out$design <- "Case-control study"
      out$why <- c(
        "Participants are primarily selected according to outcome status.",
        "The study compares previous or current exposures between cases and controls.",
        "This design is efficient for uncommon outcomes and for studying several exposures."
      )
      out$alternatives <- c(
        "Cross-sectional study: less suitable when sampling explicitly starts from outcome status.",
        "Cohort study: useful when sampling starts from exposure or a source population and outcomes are then observed."
      )
      out$best_for <- c("Odds ratio", "Rare outcomes", "Multiple exposures")
      out$considerations <- c("Control selection", "Recall bias", "Selection bias", "Confounding")
      out$guideline <- "STROBE case-control reporting guidance"
    } else if (identical(basis, "exposure")) {
      timing <- a$cohort_timing %||% "prospective"
      out$design <- switch(timing,
        retrospective = "Retrospective cohort study",
        ambidirectional = "Ambidirectional cohort study",
        "Prospective cohort study"
      )
      out$why <- c(
        "Participants are identified from exposure status or a source population rather than from outcome status.",
        "Outcome occurrence is evaluated in relation to the exposure.",
        if (timing == "retrospective") "Existing records contain the relevant historical follow-up." else "The design preserves the temporal ordering of exposure before subsequent outcome assessment."
      )
      out$alternatives <- c(
        "Case-control study: would select participants by outcome status instead.",
        "Cross-sectional study: would not provide the same direct follow-up of incident outcomes."
      )
      out$best_for <- c("Incidence", "Risk ratio", "Incidence-rate ratio", "Hazard ratio")
      out$considerations <- c("Loss to follow-up", "Confounding", "Exposure measurement", "Follow-up time")
      out$guideline <- "STROBE cohort reporting guidance"
    } else {
      out$design <- "Analytical cross-sectional study"
      out$why <- c(
        "Participants are sampled from a population without selecting them primarily by exposure or outcome status.",
        "Exposure and outcome are assessed during the same general study period.",
        "The design can estimate prevalence and evaluate cross-sectional associations."
      )
      out$alternatives <- c(
        "Cohort study: preferred if the main aim requires incidence or clear temporal follow-up.",
        "Case-control study: preferred when sampling is explicitly based on outcome status."
      )
      out$best_for <- c("Prevalence", "Prevalence ratio", "Prevalence odds ratio", "Exploratory associations")
      out$considerations <- c("Temporality may be unclear", "Confounding", "Representative sampling")
      out$guideline <- "STROBE cross-sectional reporting guidance"
    }
  }

  if (identical(purpose, "intervention")) {
    randomized <- isTRUE(a$randomized)
    cluster <- identical(a$randomization_unit, "cluster")
    sequence <- a$trial_sequence %||% "parallel"
    if (randomized) {
      if (cluster && identical(sequence, "stepped")) {
        out$design <- "Stepped-wedge cluster randomized trial"
        out$why <- c(
          "The investigator assigns the intervention.",
          "Randomization occurs at the cluster level.",
          "Clusters cross from control to intervention according to a randomized rollout schedule."
        )
      } else if (cluster) {
        out$design <- "Cluster randomized controlled trial"
        out$why <- c(
          "The investigator assigns the intervention.",
          "Randomization occurs at the level of groups or clusters rather than individual participants.",
          "Analysis and sample size must account for within-cluster correlation."
        )
      } else if (identical(sequence, "crossover")) {
        out$design <- "Randomized crossover trial"
        out$why <- c(
          "The investigator randomly assigns treatment sequences.",
          "Each participant receives more than one intervention in sequence.",
          "Within-participant comparisons can improve efficiency when carryover is adequately controlled."
        )
      } else {
        out$design <- "Parallel-group randomized controlled trial"
        out$why <- c(
          "The investigator assigns the intervention.",
          "Participants are randomly allocated to parallel intervention groups.",
          "Random allocation supports unbiased causal comparison when allocation concealment and follow-up are appropriate."
        )
      }
      out$best_for <- c("Causal intervention effects", "Risk/mean/time-to-event comparisons")
      out$considerations <- c("Allocation concealment", "Primary outcome", "Loss to follow-up", "Intention-to-treat analysis")
      out$guideline <- "CONSORT reporting guidance"
    } else {
      qtype <- a$quasi_type %||% "before_after"
      out$design <- switch(qtype,
        controlled_before_after = "Controlled before-and-after study",
        its = "Interrupted time-series study",
        did = "Difference-in-differences design",
        rd = "Regression discontinuity design",
        "Before-and-after quasi-experimental study"
      )
      out$why <- c(
        "The investigator evaluates an intervention but allocation is not randomized.",
        switch(qtype,
          its = "Repeated measurements before and after the intervention allow estimation of level and trend changes.",
          did = "Intervention and comparison groups are observed before and after intervention, enabling a difference-in-differences contrast.",
          controlled_before_after = "Both intervention and comparison groups are measured before and after the intervention.",
          rd = "Treatment assignment is determined by a threshold or cutoff, allowing a discontinuity-based effect estimate near that threshold.",
          "Outcomes are compared before and after the intervention."
        )
      )
      out$considerations <- c("Secular trends", "Confounding", "Concurrent interventions", "Appropriate comparison structure")
      out$guideline <- "Use design-specific quasi-experimental reporting guidance where available"
    }
  }

  if (identical(purpose, "diagnostic")) {
    out$design <- "Diagnostic accuracy study"
    out$why <- c(
      "The objective is to evaluate how accurately an index test identifies a target condition.",
      "The design compares the index test with an appropriate reference standard.",
      "Key estimands may include sensitivity, specificity, likelihood ratios, predictive values, and AUC."
    )
    out$best_for <- c("Sensitivity", "Specificity", "Likelihood ratios", "AUC")
    out$considerations <- c("Reference standard", "Spectrum of participants", "Blinding", "Prespecified threshold")
    out$guideline <- "STARD reporting guidance"
  }

  if (identical(purpose, "prediction")) {
    stage <- a$prediction_stage %||% "development"
    out$design <- switch(stage,
      validation = "External validation study of a prediction model",
      updating = "Prediction model updating study",
      "Prediction model development study"
    )
    out$why <- c(
      if (stage == "development") "The objective is to develop a multivariable model for individual prediction." else if (stage == "validation") "The objective is to evaluate an existing prediction model in new data." else "The objective is to update or recalibrate an existing prediction model.",
      "Sample size should be based on model-specific criteria rather than a simple events-per-variable rule."
    )
    out$best_for <- c("Calibration", "Discrimination", "Prediction error", "Clinical utility")
    out$considerations <- c("Candidate predictor parameters", "Outcome frequency", "Overfitting", "Calibration precision")
    out$guideline <- "TRIPOD / TRIPOD+AI reporting guidance"
  }

  if (identical(purpose, "scale")) {
    stage <- a$scale_stage %||% "validation"
    out$design <- switch(stage,
      development = "Scale development and psychometric evaluation study",
      adaptation = "Cross-cultural adaptation and measurement-property study",
      "Psychometric validation study"
    )
    out$why <- c(
      "The main objective concerns a measurement instrument rather than a disease frequency or treatment effect.",
      "Different measurement properties require different sample-size considerations.",
      "Internal consistency, structural validity, reliability, validity, and responsiveness should be planned separately when relevant."
    )
    out$best_for <- c("EFA/CFA", "Cronbach's alpha / omega", "ICC/test-retest", "Construct validity", "Measurement invariance")
    out$considerations <- c("Item quality", "Factor structure", "Independent EFA/CFA samples when planned", "Measurement-property-specific subsamples")
    out$guideline <- "COSMIN measurement-property guidance"
  }

  if (identical(purpose, "prognosis")) {
    out$design <- "Prospective prognostic cohort study"
    out$why <- c(
      "The objective is to characterize future outcomes or prognostic factors among participants at a defined starting point.",
      "Follow-up preserves the temporal sequence between baseline predictors and subsequent outcomes."
    )
    out$best_for <- c("Prognostic factors", "Survival", "Cumulative incidence", "Hazard ratios")
    out$considerations <- c("Start point", "Competing risks", "Loss to follow-up", "Outcome ascertainment")
    out$guideline <- "STROBE and prognosis-specific guidance"
  }

  if (is.na(out$design)) {
    out$design <- "Design requires investigator judgment"
    out$why <- "The current answers do not map to one prespecified R4VN design pathway."
    out$considerations <- "Clarify the primary research objective, sampling basis, intervention assignment, timing, and outcome structure."
  }

  out$created <- as.character(Sys.time())
  out$r4vn_version <- .r4vn_design_r4vn_version()
  class(out) <- "r4vn_study_design"
  out
}