pcatR

pcatR is an independent R package for reproducible analysis of the 14-item Pragmatic Context Assessment Tool (pCAT). It imports and validates response data, classifies barriers and facilitators, summarizes item-level patterns, describes team agreement and disagreement, compares repeated assessments, creates implementation action-planning tables, and produces publication-ready figures.

Read this first

The pCAT was developed as a brief pragmatic reflection and problem-solving tool, not as a conventional multi-item psychometric scale. Accordingly, pcatR:

• reports items and constructs rather than a single overall score;
• does not calculate or endorse a validated total pCAT scale score;
• uses the -2 to +2 display code only for plotting and within-item transition descriptions;
• treats implementation-strategy links as prompts for local deliberation, not automated prescriptions; and
• should not replace a fuller contextual assessment when comprehensive CFIR determinant evaluation is required.

Read the Technical User Guide before analyzing study or operational data. After installation, open the packaged guide with:

pcat_user_guide()

Installation

From GitHub

install.packages("remotes")
remotes::install_github("JaeManP/pcatR")

From a downloaded source archive

install.packages(
  "pcatR_1.0.1.tar.gz",
  repos = NULL,
  type = "source"
)

pcatR is a pure-R package. Its required plotting dependency, ggplot2, is installed automatically by standard package installers. The optional Shiny interface requires shiny.

Sixty-second workflow

library(pcatR)

# Use synthetic example data, or replace this with pcat_read_csv("file.csv").
dat <- pcat_example_data()

analysis <- pcat_analyse(
  dat,
  group_vars = c("site_id", "timepoint"),
  require_complete = TRUE,
  validation_action = "none"
)

analysis
pcat_validation_issues(analysis$validation)
head(analysis$summary)
head(analysis$consensus)
head(analysis$action_plan)

plot_pcat_profile(
  analysis$classified,
  group_vars = c("site_id", "timepoint"),
  label = "cfir_original_construct"
)

example_output <- tempfile("pcat_analysis_", tmpdir = tempdir())

pcat_write_analysis(
  analysis,
  path = example_output,
  include_classified = FALSE
)

unlink(example_output, recursive = TRUE, force = TRUE)

The export directory contains a manifest, validation findings, classified responses, item summaries, consensus diagnostics, an action-plan worksheet, and an optional multi-page profile PDF. Set include_classified = FALSE when a respondent-level export is not required.

The temporary path keeps this documentation example out of the current working directory. For real analyses, choose an explicit, approved project output directory.

Response coding

Each item has two response components:

Leave effect blank when direction = 2 (neutral). A neutral response paired with any effect value is flagged by default.

The five complete descriptive classifications are:

The display code must not be summed across items or treated as an interval-scale outcome.

Standard long-format data

Required columns are respondent_id, item_id, direction, and effect. Recommended metadata columns include project_id, site_id, team_id, role, timepoint, assessment_date, and comment.

template_path <- tempfile("pcat_long_template_", fileext = ".csv")

pcat_write_template(
  template_path,
  format = "long",
  n_respondents = 10,
  include_item_text = TRUE
)

unlink(template_path, force = TRUE)

For non-standard source data, map columns explicitly:

standard <- pcat_standardize(
  raw_data,
  respondent_id = "participant_code",
  item_id = "question_number",
  direction = "barrier_facilitator_response",
  effect = "effect_strength",
  site_id = "clinic",
  timepoint = "wave"
)

Core functions

Summary denominators

Directional percentages use all eligible records with a valid direction and therefore use n_valid_direction. The directional n_neutral count includes every valid neutral direction. Complete five-category percentages use only eligible records with a complete direction-plus-effect classification and use n_complete_class; their neutral numerator is n_neutral_complete. A neutral direction with an invalid effect remains in n_neutral but is excluded from n_neutral_complete and the complete five-category distribution. pct_complete_class is the share of valid-direction records that have a complete five-category classification and can be reviewed as a completeness diagnostic before interpreting category-specific percentages.

CFIR mappings

The package retains the original pCAT-to-CFIR mapping and the updated mapping reported in 2026. Item 10 has two updated-CFIR links in Supplementary Table S3: Available Resources: Materials & Equipment (primary in the package dictionary) and Available Resources: Funding (secondary). Retrieve all links with:

pcat_construct_map("2022", include_secondary = TRUE)

Privacy and operational use

Use coded respondent identifiers. Do not place names, medical-record numbers, email addresses, or protected health information in pCAT files. Avoid respondent-level heatmaps for small or identifiable teams. For tabular outputs, pcat_summarise(..., suppress_below = 5) suppresses numerical analytic results and the derived modal_class below a user-specified respondent threshold while retaining grouping, item, and CFIR metadata. Select the threshold required by your protocol or organization.

The Shiny interface is an analysis convenience, not a secure survey-collection platform.

Citation and attribution

The package author is Lilac Li. Jae Man Park is the package maintainer. Author and maintainer profile links are retained in the package metadata and website.

Run:

citation("pcatR")

Analyses should cite the software, the original pCAT development article, and, when updated CFIR mappings are used, the 2026 mapping article. Instrument wording and source-derived mapping content are attributed under CC BY 4.0; package code is MIT licensed. See LICENSE.note and REFERENCES.md.

This software is independent and is not an official product or endorsement of the original pCAT authors, the U.S. Department of Veterans Affairs, the CFIR Leadership Team, or the instrument repository.

Development

install.packages(c("devtools", "testthat", "pkgdown"))
devtools::document()
devtools::test()
devtools::check()
pkgdown::build_site()

See CONTRIBUTING.md, GOVERNANCE.md, and SECURITY.md before contributing.

Before publishing, follow PUBLISHING.md, use RELEASE_CHECKLIST.md as the reusable review template, and require all GitHub Actions jobs to pass. The completed release-candidate checks and remaining external gates are documented in RELEASE_VALIDATION.md.