Export pCAT analysis results and profile figures

pcat_write_analysis() writes a reproducible directory containing an analysis manifest, validation findings, optional classified responses, item summaries, consensus diagnostics, an optional action-plan worksheet, analysis settings, session information, and an optional profile PDF. pcat_save_profile_pdf() places one grouping combination on each page. It validates every page before writing a temporary PDF and replaces the target only after the complete temporary file is nonempty. An existing directory is rejected as an output path before any backup or output operation.

Usage

pcat_write_analysis(
  x,
  path,
  overwrite = FALSE,
  include_profile_pdf = TRUE,
  include_classified = TRUE,
  profile_label = c(
    "cfir_original_construct", "cfir_2022_construct", "item_text", "item_id"
  )
)

pcat_save_profile_pdf(
  data,
  path,
  group_vars = NULL,
  overwrite = FALSE,
  width = 11,
  height = 8.5,
  title_prefix = "pCAT profile",
  ...
)

Arguments

x

A pcat_analysis object returned by pcat_analyse().

path

Output directory for pcat_write_analysis() or output PDF file path for pcat_save_profile_pdf(). Existing directories are rejected for the PDF exporter.

overwrite

Logical; replace files previously generated by pcatR in the output directory. Unrelated files are retained.

include_profile_pdf

Logical; include a multi-page profile PDF in the analysis export.

include_classified

Logical; write respondent-item classifications to 02_classified_responses.csv. Set to FALSE when a response-level file is unnecessary or should not be distributed.

profile_label

Item-label field used in the exported profile PDF.

data

Raw, validated, or classified pCAT data.

group_vars

Grouping columns defining one PDF page.

width, height

Positive finite PDF page dimensions in inches.

title_prefix

Prefix used in profile page titles.

...

Additional arguments passed to plot_pcat_profile().

Details

If summary tables were created with suppress_below, the classified response file and profile PDF do not automatically inherit that suppression. Review respondent-level and graphical outputs under the applicable privacy and disclosure rules before dissemination. When overwrite = TRUE, only known files generated by pcat_write_analysis() are removed before the new export is written. If profile-page construction or writing fails, pcat_save_profile_pdf() identifies the affected group, removes its temporary file, and leaves any existing target unchanged.

Value

The normalized output directory or file path, invisibly.

Examples

analysis <- pcat_analyse(
  pcat_example_data(),
  group_vars = c("site_id", "timepoint"),
  validation_action = "none"
)

analysis_dir <- tempfile("pcat_analysis_")

pcat_write_analysis(
  analysis,
  path = analysis_dir,
  include_profile_pdf = FALSE,
  include_classified = FALSE
)

list.files(analysis_dir)
#> [1] "00_manifest.csv"              "01_validation_issues.csv"    
#> [3] "03_item_summary.csv"          "04_consensus_diagnostics.csv"
#> [5] "05_action_plan.csv"           "07_analysis_settings.csv"    
#> [7] "08_session_info.txt"          "README.txt"                  

profile_path <- tempfile("pcat_profiles_", fileext = ".pdf")

pcat_save_profile_pdf(
  analysis$classified,
  path = profile_path,
  group_vars = c("site_id", "timepoint"),
  label = "item_id"
)