Software: pcatR - Analyze and Visualize Pragmatic Context Assessment Tool Data
Version: 1.0.1
Document version: 1.6
Document status: CRAN submission candidate
Prepared: July 12, 2026
Last updated: August 21, 2026
Author: Lilac Li
Maintainer: Jae Man Park
Repository: https://github.com/JaeManP/pcatR
Package website: https://jaemanp.github.io/pcatR/
| Field | Specification |
|---|---|
| Intended audience | Implementation researchers, evaluators, quality-improvement teams, analysts, data managers, and facilitators using the 14-item pCAT |
| Purpose | Define correct installation, data preparation, validation, analysis, interpretation, reporting, privacy, and reproducibility procedures |
| Software status | Independent open-source implementation; not an official product of the pCAT authors, U.S. Department of Veterans Affairs, CFIR Leadership Team, or instrument repository |
| Code license | MIT License |
| Instrument and mapping content | Attributed source content under Creative Commons Attribution 4.0, as described in LICENSE.note |
| Primary software language | R, version 4.1.0 or later |
| Required package dependency | ggplot2 3.4.0 or later |
| Optional dependencies | shiny, testthat, knitr, rmarkdown, covr, pkgdown, and development tools |
Critical methodological boundary: The pCAT is an abbreviated pragmatic context assessment. The original development article states that each CFIR construct is represented by a single question and that the instrument did not follow a psychometric paradigm of development.
pcatRtherefore does not calculate, validate, or recommend an overall pCAT total score.
The package creates a descriptive five-category classification for each item:
| Category | Display code | Permitted use |
|---|---|---|
| Strong barrier | -2 | Item profiles and within-item transition displays |
| Weak barrier | -1 | Item profiles and within-item transition displays |
| Neutral | 0 | Item profiles and within-item transition displays |
| Weak facilitator | +1 | Item profiles and within-item transition displays |
| Strong facilitator | +2 | Item profiles and within-item transition displays |
Do not sum or average these display codes across the 14 items and present the result as a validated scale. Any item-level median or mean display statistic requested from the software is descriptive only and must be labeled accordingly.
The pCAT should be anchored to a specific planned or ongoing implementation or improvement effort. Respondents should not rate a vague, general organizational climate. The same contextual feature can be a barrier for one implementation effort and a facilitator for another.
The package does not replace full CFIR assessment. A 2026 evaluation found the updated 14-construct pCAT mapping useful as a rapid starting point but incomplete when comprehensive determinant assessment was required. Use full or purpose-selected CFIR methods when rigor, comprehensiveness, or generalizability is the primary goal.
Before using results, confirm that:
pcatR software are cited.pcatR provides a reproducible workflow for:
Appropriate uses include pre-implementation planning, mid-implementation reflection, team discussion, rapid context assessment, quality-improvement facilitation, and descriptive implementation research. Results should remain tied to the implementation effort, setting, respondent group, and assessment time point.
The package is not designed to:
The official instrument asks respondents to indicate whether each statement represents a potential barrier, neutral condition, or potential facilitator and then, for a barrier or facilitator, indicate likely effect strength.
| Component | Code | Official label | Interpretation |
|---|---|---|---|
| Direction | 1 | Disagree | Potential barrier |
| Direction | 2 | Neutral | Neither barrier nor facilitator |
| Direction | 3 | Agree | Potential facilitator |
| Effect | 0 | Weak/no effect | Weak or no likely effect on implementation |
| Effect | 1 | Strong effect | Strong likely effect on implementation |
For neutral responses, effect should be blank because the effect question applies to a condition identified as a barrier or facilitator. By default, pcatR flags any non-missing effect paired with a neutral direction. The response is still classified as neutral so the source record remains analyzable, but the warning must be reviewed and the data-collection design documented. For a legacy form that forced an effect response, use neutral_effect = "allow" only after confirming the form behavior; use neutral_effect = "set_missing" when the forced value should be removed from the standardized analytic data.
| Item | Item statement | Original CFIR mapping | Updated CFIR mapping |
|---|---|---|---|
| 1 | People here regularly seek to understand the needs of patients and make changes to better meet those needs. | Patient Needs & Resources | Culture: Recipient-Centeredness |
| 2 | I have open lines of communication with everyone needed to make the change. | Networks & Communications | Communications |
| 3 | I have access to data to help track changes in outcomes. | Reflecting & Evaluating | Reflecting & Evaluating |
| 4 | The change is aligned with leadership goals. | Goals & Feedback | Mission Alignment |
| 5 | The change is aligned with clinician values. | Compatibility | Innovation Deliverers: Capability |
| 6 | The change is compatible with existing clinical processes. | Compatibility | Compatibility |
| 7 | The structures and policies in place here enable us to make the change. | Structural Characteristics | Structural Characteristics: Work Infrastructure |
| 8 | We have sufficient space to accommodate the change. | Available Resources | Available Resources: Space |
| 9 | We have sufficient time dedicated to make the change. | Available Resources | Innovation Deliverers: Opportunity |
| 10 | We have other needed resources to make the change (staff, money, supplies, etc.). | Available Resources | Available Resources: Materials & Equipment; Available Resources: Funding |
| 11 | People here see the current situation as intolerable and that the change is needed. | Tension for Change | Tension for Change |
| 12 | People here see the advantage of implementing this change versus an alternative change. | Relative Advantage | Innovation Relative Advantage |
| 13 | Higher level leaders are committed, involved, and accountable for the planned improvement. | Leadership Engagement | High-Level Leaders: Motivation |
| 14 | Leaders I work with most closely are committed, involved, and accountable for the planned improvement. | Leadership Engagement | Mid-Level Leaders: Motivation |
The original 14 items represent 10 original CFIR constructs because Compatibility, Available Resources, and Leadership Engagement are represented by multiple items. The updated mapping assigns a primary updated CFIR construct to each item; item 10 also has a source-reported secondary Funding mapping available through pcat_construct_map(include_secondary = TRUE).
The online instrument repository currently lists Learning Climate among subscale metadata and only one Leadership Engagement item. The official two-page instrument and the original development article instead contain two Leadership Engagement items and no Learning Climate item. pcatR treats the official instrument attachment and peer-reviewed development article as authoritative for item wording and original mappings. The package retains source notes so mapping decisions are auditable.
Use these functions to inspect provenance before analysis:
pcat_items("both")
pcat_construct_map("original")
pcat_construct_map("2022", include_secondary = TRUE)
pcat_response_options()install.packages("pak")
pak::pak("JaeManP/pcatR")Alternative:
install.packages("remotes")
remotes::install_github("JaeManP/pcatR")install.packages(
"pcatR_1.0.1.tar.gz",
repos = NULL,
type = "source"
)The package contains no compiled C, C++, or Fortran code. A normal installation from GitHub usually does not require compilation. Rtools is required for a complete Windows package-development and source-check workflow and may be requested by the installer depending on the R version, dependency state, or build command used.
library(pcatR)
packageVersion("pcatR")
pcat_self_test()Expected version:
[1] '1.0.1'The self-test checks the 14-item dictionary, mappings, validation, classification, summaries, reshaping, longitudinal comparison, strategy lookup, action planning, and the end-to-end wrapper. Plot construction is also checked when ggplot2 is available; ggplot2 is a required dependency of an installed pcatR package.
Open this guide from R:
pcat_user_guide()pCAT responses can reveal organizational problems, leadership perceptions, resource limitations, and professional opinions. Even when they are not protected health information, they may be sensitive employment or organizational data.
Apply the following controls:
pcatR performs local analysis. It does not transmit data by itself. The optional Shiny application is not a secure survey system. Deploying it to a server introduces hosting, authentication, logging, and data-retention responsibilities that are outside the package.
The suppress_below argument can replace numeric analytic measures and the derived modal_class with missing values for groups below a user-defined respondent count. Grouping, item, and CFIR metadata remain visible. This is a disclosure-control aid, not a complete statistical disclosure-control system.
Each row should represent one respondent, one assessment, and one pCAT item.
| Column | Required | Type | Definition |
|---|---|---|---|
respondent_id |
Yes | Character | Coded respondent identifier |
item_id |
Yes | Integer | pCAT item number 1 through 14 |
direction |
Yes | Integer or recognized text | 1 barrier, 2 neutral, 3 facilitator |
effect |
Yes as a column | Integer or recognized text | 0 weak/no effect, 1 strong effect; should be blank for neutral |
project_id |
Recommended | Character | Implementation project identifier |
site_id |
Recommended | Character | Site, facility, clinic, or organizational unit |
team_id |
Optional | Character | Implementation team identifier |
role |
Optional | Character | Respondent role or professional group |
timepoint |
Recommended for repeated assessment | Character | Planning, mid-implementation, sustainment, or another defined occasion |
assessment_date |
Recommended | Date or ISO character | Date of assessment |
comment |
Optional | Character | De-identified contextual note |
Create a template:
template_path <- tempfile("pcat_long_template_", fileext = ".csv")
pcat_write_template(
template_path,
format = "long",
n_respondents = 20,
include_item_text = TRUE
)
unlink(template_path, force = TRUE)Temporary paths keep documentation examples out of the current working directory. For operational use, select an explicit, approved project path.
One row represents one assessment. Item response columns use two-digit item numbers:
item01_direction, item01_effect, ..., item14_direction, item14_effectCreate a wide template:
wide_template_path <- tempfile("pcat_wide_template_", fileext = ".csv")
pcat_write_template(
wide_template_path,
format = "wide",
n_respondents = 20
)
unlink(wide_template_path, force = TRUE)Wide-to-long conversion rejects item numbers outside 1 through 14 and duplicate item-component columns.
By default, validation defines an assessment using the available columns among:
project_id, site_id, team_id, timepoint, assessment_date, respondent_idThe item number is appended to identify one response row. Specify key_cols explicitly when the default does not uniquely represent an assessment. This is essential when a respondent completes more than one assessment with the same nominal time point.
pcat_validate(
data,
key_cols = c("project_id", "site_id", "assessment_date", "respondent_id"),
require_complete = TRUE
)data <- pcat_read_csv(
file.choose(),
layout = "auto"
)Auto-detection prioritizes standard long format when all four required long columns are present; otherwise it detects standard wide response names.
standard <- pcat_standardize(
raw_data,
respondent_id = "participant_code",
item_id = "question_number",
direction = "barrier_facilitator",
effect = "effect_strength",
project_id = "implementation_project",
site_id = "clinic",
role = "professional_role",
timepoint = "wave",
assessment_date = "survey_date",
comment = "notes"
)pcat_standardize() copies source fields to standard names. With keep_original = TRUE, source columns are retained for auditability. With keep_original = FALSE, source fields that differ from standard names are removed.
Direction parsing recognizes numeric codes and common labels such as disagree, barrier, neutral, agree, and facilitator. Effect parsing recognizes weak/no effect, weak, no effect, strong, and related variants. Unrecognized text is flagged rather than silently recoded.
Run validation before classification or analysis:
validation <- pcat_validate(
data,
require_complete = TRUE,
neutral_effect = "flag",
action = "none"
)
print(validation)
pcat_validation_issues(validation)| Issue code | Meaning | Default severity |
|---|---|---|
missing_respondent_id |
Respondent identifier is blank | Error |
missing_item_id |
Item identifier is blank | Error |
invalid_item_id |
Item identifier is not an integer 1 through 14 | Error |
missing_direction |
Direction is blank | Error |
invalid_direction |
Direction is not 1, 2, 3, or a recognized label | Error |
invalid_effect |
Effect is not 0, 1, or a recognized label | Error |
missing_effect |
Barrier or facilitator direction lacks effect | Error |
effect_without_direction |
Effect supplied while direction is blank | Warning |
neutral_with_effect |
Neutral paired with any non-missing effect | Warning |
duplicate_key |
More than one row has the same assessment-item key | Error |
When require_complete = TRUE, each assessment must contain exactly one row for every item 1 through 14. Missing items, repeated items, or additional valid-item rows produce incomplete_assessment.
neutral_effect = "flag": retain the value and issue a warning for any non-missing effect paired with neutral. This is the default.neutral_effect = "allow": retain the value without a warning. Use only for a documented legacy form that required an effect response after neutral.neutral_effect = "set_missing": replace any effect paired with neutral by missing and issue a warning.action = "none": return findings without a warning or error.action = "warn": return findings and emit a warning when issues exist.action = "error": stop when the validation object is invalid.strict = TRUE: treat warnings as invalid in the valid field.The reported error and warning counts are counts of findings, not necessarily counts of unique rows or assessments.
Classified output retains problematic rows. Rows with invalid or missing item identifiers, missing respondent identifiers, or duplicate assessment-item keys are marked pcat_record_eligible = FALSE and excluded from item summaries. Response-level invalidity and missingness remain visible through classification fields and denominator counts.
classified <- pcat_classify(validation)| Direction | Effect | pcat_class |
pcat_display_code |
|---|---|---|---|
| 1 | 1 | strong_barrier |
-2 |
| 1 | 0 | weak_barrier |
-1 |
| 1 | Missing | barrier_effect_missing |
Missing |
| 2 | Missing, 0, or 1 | neutral |
0 |
| 3 | 0 | weak_facilitator |
+1 |
| 3 | 1 | strong_facilitator |
+2 |
| 3 | Missing | facilitator_effect_missing |
Missing |
| Missing | Any | missing |
Missing |
| Invalid | Any | invalid |
Missing |
pcat_class5 contains only the five complete analytic categories. This is the field used for the five-category profile. pcat_side retains barrier, neutral, or facilitator direction even when effect is missing. A non-missing effect paired with neutral does not change the neutral classification, but validation records neutral_with_effect unless the user explicitly selects neutral_effect = "allow".
pcat_strength is assigned only when both direction and effect parsing and validation are valid. An invalid direction or invalid effect therefore produces pcat_strength = "invalid". A neutral direction with an invalid effect can remain directionally neutral in pcat_side, but it has no complete pcat_class5 value.
summary <- pcat_summarise(
classified,
group_vars = c("site_id", "timepoint"),
respondent_id = "respondent_id",
suppress_below = 5
)Two denominators serve different purposes:
n_valid_direction: eligible rows with a valid barrier, neutral, or facilitator direction. This denominator supports pct_barrier, pct_neutral, pct_facilitator, pct_effect_missing, and pct_complete_class.n_complete_class: eligible rows that can be assigned to one of the five complete categories. This denominator supports pct_strong_barrier, pct_weak_barrier, pct_neutral_complete, pct_weak_facilitator, pct_strong_facilitator, and modal_class_share.Directional percentages use all eligible records with a valid direction. Complete five-category percentages use only eligible records with a complete direction-plus-effect classification. The directional n_neutral count includes every valid neutral direction, whereas n_neutral_complete includes only neutral rows with a complete five-category classification. A neutral response with an invalid effect remains part of n_neutral but is excluded from n_neutral_complete and the complete five-category distribution.
Never infer denominators from percentages alone. Report the relevant n with every percentage, especially when effect responses are missing or invalid. The five complete-category counts partition n_complete_class, and their percentages sum to one whenever that denominator is positive.
| Field | Definition |
|---|---|
n_rows_input |
All item rows in the analytic group |
n_rows_eligible |
Rows eligible for summary |
n_rows_excluded |
Rows excluded because of invalid keys or identifiers |
n_respondents |
Unique eligible respondent identifiers |
n_valid_direction |
Valid barrier, neutral, or facilitator directions |
n_complete_class |
Complete five-category classifications |
n_neutral |
Valid neutral directions, including rows without a complete effect classification |
n_neutral_complete |
Neutral rows in the complete five-category classification |
pct_barrier |
Barrier directions divided by valid directions |
pct_neutral |
Neutral directions divided by valid directions |
pct_facilitator |
Facilitator directions divided by valid directions |
pct_effect_missing |
Barrier/facilitator responses missing effect divided by valid directions |
pct_complete_class |
Complete classifications divided by valid directions |
pct_strong_barrier |
Strong barriers divided by complete classifications |
pct_weak_barrier |
Weak barriers divided by complete classifications |
pct_neutral_complete |
n_neutral_complete divided by complete classifications |
pct_weak_facilitator |
Weak facilitators divided by complete classifications |
pct_strong_facilitator |
Strong facilitators divided by complete classifications |
modal_class |
Most frequent complete category, or tie |
modal_class_share |
Modal-category count divided by complete classifications |
When suppress_below applies to a summary row, numeric analytic measures and the derived modal_class are missing. Group identifiers, item identifiers and wording, CFIR metadata, and the suppressed indicator remain available for context.
The summary includes item-level mean and median display codes. Because the categories are ordered but not established as an interval scale, these are exploratory descriptive summaries. Prefer category percentages and visual profiles for substantive reporting.
consensus <- pcat_consensus(
summary,
agreement_threshold = 0.60,
polarization_min = 0.20,
minimum_n = 2
)The function adds:
agreement_share: largest of barrier, neutral, and facilitator direction shares;dominant_side: barrier, neutral, facilitator, or tie;polarized: both barrier and facilitator shares meet the configured minimum;normalized_entropy: distributional dispersion across the three directions, from 0 for complete concentration to 1 for an even three-way distribution; andconsensus_label: insufficient data, polarized, consensus barrier, consensus neutral, consensus facilitator, or mixed.When the barrier or facilitator share is unavailable, including after small-cell suppression, polarized is missing rather than FALSE. Suppressed rows retain consensus_label = "insufficient_data"; unavailable data are not interpreted as evidence that a cell is nonpolarized.
The default 60% agreement and 20% polarization rules are package conventions. They are not empirically established pCAT cut points. Prespecify and report any threshold used. Sensitivity analysis is recommended when decisions depend on a threshold.
Each probability threshold must be one finite numeric value from 0 through 1. Vectors, missing or infinite values, character values, and values outside that range are rejected.
A polarized result is analytically important. It may indicate different roles, workflows, information access, or local experiences rather than measurement error. Review comments and stratified results before collapsing disagreement into a single summary.
The pCAT can be administered during planning and again during implementation. Pair respondents and items only when identifiers represent the same people and assessment units across time.
change <- pcat_change(
classified,
timepoint = "timepoint",
from = "planning",
to = "mid_implementation",
id_cols = c("project_id", "site_id", "respondent_id", "item_id")
)Transition categories:
| Transition | Definition |
|---|---|
toward_barrier |
Later category has a lower descriptive display code |
no_code_change |
Earlier and later complete categories are identical in display code |
toward_facilitation |
Later category has a higher descriptive display code |
newly_observed |
No earlier record, later record present |
followup_missing |
Earlier record present, no later record |
not_comparable |
Pair exists but one or both responses lack a complete display code |
delta_display_code ranges from -4 to +4. It describes ordered movement only. It is not a continuous change score, standardized effect, causal estimate, or evidence that implementation caused the change.
When respondent anonymity prevents pairing, compare group-level item distributions instead and clearly describe the analysis as repeated cross-sectional.
action_plan <- pcat_action_plan(
summary,
group_vars = c("site_id", "timepoint"),
barrier_threshold = 0.50,
strong_barrier_threshold = 0.20,
include_strategy_candidates = TRUE,
include_approximate = FALSE
)An item enters the action plan when barrier prevalence or strong-barrier prevalence meets the configured threshold. The output may include multiple candidate strategies per item.
The package intentionally leaves these fields blank:
selected_strategy;planned_action;local_adaptation;owner;target_date;status; andaction_notes.Complete them through stakeholder deliberation. Consider implementation fit, feasibility, equity, staff burden, resources, readiness, sequencing, and unintended consequences.
The candidate strategy table is source-derived and does not constitute automated treatment selection. include_approximate = FALSE excludes the non-identical Relative Priority to Relative Advantage linkage. Any approximate mapping should be disclosed.
The default action-plan rule uses pct_barrier with n_valid_direction as its denominator and pct_strong_barrier with n_complete_class as its denominator. Review pct_complete_class and effect missingness before interpreting a strong-barrier threshold. A row with a missing strong-barrier percentage is never retained solely because the value is missing.
Both action-plan probability thresholds must be finite numeric scalars from 0 through 1; vector or nonnumeric inputs are rejected.
profile <- plot_pcat_profile(
classified,
group_vars = c("site_id", "timepoint"),
label = "cfir_original_construct",
facet_ncol = 2,
show_neutral = TRUE,
show_n = TRUE
)
print(profile)Barriers appear to the left and facilitators to the right. Neutral labels show the neutral percentage and complete-response denominator. The bars use complete five-category responses as the denominator.
For several groups or long labels, use one page per group:
profile_path <- tempfile("pcat_profiles_", fileext = ".pdf")
pcat_save_profile_pdf(
classified,
path = profile_path,
group_vars = c("site_id", "timepoint"),
label = "cfir_original_construct"
)
unlink(profile_path, force = TRUE)The exporter constructs and validates every requested group page before creating output, writes the complete document to a temporary PDF in the target directory, and replaces the requested path only after the temporary file is confirmed nonempty. If any group lacks complete five-category data or another page fails, the error identifies that group, a new target is not left behind, and an existing target remains unchanged.
The output path must identify a PDF file, not a directory, even when overwrite = TRUE. Page width and height must each be one positive finite number. These checks occur before any backup or output operation.
plot_pcat_heatmap(
classified,
respondent_id = "respondent_id",
facet_vars = c("site_id", "timepoint")
)Use heatmaps cautiously when respondent identifiers are sensitive. Replace identifiers with display codes or suppress the figure before sharing.
plot_pcat_change(
change,
respondent_id = "respondent_id",
facet_vars = "site_id",
display = "transition"
)The transition display is preferred because it avoids presenting ordinal differences as interval-scaled effects.
figure_path <- tempfile("pcat_profile_", fileext = ".png")
ggplot2::ggsave(
filename = figure_path,
plot = profile,
width = 16,
height = 12,
units = "in",
dpi = 300
)
unlink(figure_path, force = TRUE)library(pcatR)
# 1. Import a standard CSV.
data <- pcat_read_csv(file.choose(), layout = "auto")
# 2. Run the standard analysis.
analysis <- pcat_analyse(
data,
group_vars = c("site_id", "timepoint"),
respondent_id = "respondent_id",
require_complete = TRUE,
neutral_effect = "flag",
validation_action = "warn",
suppress_below = 5,
agreement_threshold = 0.60,
polarization_min = 0.20,
minimum_n = 2,
barrier_threshold = 0.50,
strong_barrier_threshold = 0.20
)
# 3. Review validation before interpreting results.
analysis$validation
pcat_validation_issues(analysis$validation)
# 4. Inspect outputs.
analysis$summary
analysis$consensus
analysis$action_plan
# 5. Export an auditable bundle.
results_dir <- tempfile("pcat_results_", tmpdir = tempdir())
pcat_write_analysis(
analysis,
path = results_dir,
include_classified = FALSE,
include_profile_pdf = TRUE
)
unlink(results_dir, recursive = TRUE, force = TRUE)The export includes:
| File | Content |
|---|---|
00_manifest.csv |
Package version, timestamp, row counts, validation counts, grouping, completeness setting, and profile status |
01_validation_issues.csv |
Row- and assessment-level findings |
02_classified_responses.csv |
Optional standardized and classified response-level data; written only when include_classified = TRUE |
03_item_summary.csv |
Item-level counts, percentages, denominators, and mappings |
04_consensus_diagnostics.csv |
Agreement, polarization, entropy, and labels |
05_action_plan.csv |
Barrier-focused planning worksheet, when requested |
06_profile.pdf |
One profile page per group, when complete categories exist |
07_analysis_settings.csv |
Analysis settings |
08_session_info.txt |
R and package session information |
README.txt |
Export inventory and methodological warning |
Respondent-level classified data and profile figures are not protected by summary-table small-cell suppression. Set include_classified = FALSE for a shareable aggregate bundle unless response-level disclosure has been reviewed. If overwrite = TRUE, pcat_write_analysis() removes only known pcatR-generated files before writing the new export; unrelated files in the directory are left untouched.
The optional shiny package must be installed separately before launching the application. Launch it only in an interactive R session:
if (interactive() && requireNamespace("shiny", quietly = TRUE)) {
pcat_app()
}The application supports CSV upload, layout selection, validation, group selection, profiles, item summaries, consensus diagnostics, action plans, and CSV downloads.
Do not deploy the app with sensitive data until the hosting environment has appropriate authentication, authorization, encrypted transport, encrypted storage, logging, retention, backup, and incident-response controls. The package does not implement those controls.
Record the following in every analysis:
packageVersion("pcatR")
R.version.string
sessionInfo()Use the export manifest and settings files. Preserve the raw input, a read-only copy of the item dictionary and mappings used, the exact analysis script, and the package lockfile where applicable.
For an R project, renv can preserve package versions:
install.packages("renv")
renv::init()
renv::snapshot()For software development, run:
devtools::document()
devtools::test(stop_on_failure = TRUE)
devtools::check(error_on = "warning")GitHub Actions supplied with the repository run multi-platform package checks, website deployment, and coverage calculation.
At minimum, state:
Suggested methods language:
We analyzed the 14-item Pragmatic Context Assessment Tool using pcatR version 1.0.1. Direction responses were classified as barrier, neutral, or facilitator; barrier and facilitator responses were further classified as weak/no effect or strong effect. We reported item-level distributions using valid direction and complete five-category denominators as appropriate. We did not calculate an overall pCAT score. Consensus and action-planning thresholds were prespecified as descriptive analytic conventions.
Suggested limitation language:
The pCAT is an abbreviated pragmatic context assessment and does not comprehensively represent all CFIR determinants. Each construct is represented by a single item, and the instrument was not developed as a conventional psychometric scale. Findings are context-specific and should be integrated with stakeholder interpretation and, when comprehensiveness is required, broader determinant assessment.
The path supplied to pcat_read_csv() must identify an actual file. Use:
path <- file.choose()
file.exists(path)
data <- pcat_read_csv(path)Check for either the four standard long fields or wide names such as item01_direction. Import with base R and use pcat_standardize() for non-standard names.
Barrier and facilitator directions require effect 0 or 1. Neutral responses should leave effect blank. If a legacy electronic form forced an effect response after neutral, document that design and select the appropriate neutral_effect handling rather than treating the forced value as substantive effect strength.
Confirm that key_cols identify one assessment. Include assessment date or wave when a respondent completes multiple assessments. Do not simply delete duplicates until the source record is reconciled.
Use pcat_validation_issues(validation, level = "assessment") to identify missing or repeated item IDs. Decide whether partial item-level analysis is appropriate and document the decision.
Save at a larger size or use pcat_save_profile_pdf() for one group per page. Use label = "item_id" for compact multi-panel overviews and provide an item key.
Update R and installation tools, then run:
install.packages("pak")
pak::pkg_system_requirements("pcatR")
pak::pak("JaeManP/pcatR")For development problems, include sessionInfo(), the exact error, and a synthetic reproducible example.
| Function | Primary purpose |
|---|---|
pcat_analyse() |
End-to-end validation, classification, summary, consensus, and action plan |
pcat_write_analysis() |
Export an auditable analysis bundle |
pcat_items() |
Item dictionary and primary mappings |
pcat_construct_map() |
Long-form original and updated mapping table |
pcat_response_options() |
Response coding dictionary |
pcat_strategy_candidates() |
Source-derived strategy prompts |
pcat_example_data() |
Synthetic complete example data |
pcat_read_csv() |
Import standard long or wide CSV |
pcat_standardize() |
Map non-standard columns to standard names |
pcat_template() |
Create an in-memory entry template |
pcat_write_template() |
Write a CSV entry template |
pcat_wide_to_long() |
Convert standard wide data to long |
pcat_long_to_wide() |
Convert long data to standard wide |
pcat_validate() |
Validate rows, keys, codes, and completeness |
pcat_validation_data() |
Extract standardized validation data |
pcat_validation_issues() |
Extract validation findings |
pcat_classify() |
Create direction, strength, five-category, and display fields |
pcat_summarise() |
Item-level counts, percentages, denominators, and mappings |
pcat_consensus() |
Agreement, polarization, entropy, and consensus labels |
pcat_change() |
Paired item transitions across two occasions |
pcat_action_plan() |
Barrier-focused planning worksheet and strategy prompts |
plot_pcat_profile() |
Diverging item profile |
plot_pcat_heatmap() |
Respondent-by-item classification heatmap |
plot_pcat_change() |
Paired transition or descriptive delta heatmap |
pcat_save_profile_pdf() |
Multi-page one-group-per-page profile PDF |
pcat_palette() |
Default named colors |
pcat_app() |
Optional local Shiny interface |
pcat_user_guide() |
Locate or open this guide |
pcat_self_test() |
Run built-in integrity and behavior checks |
| Document version | Date | Software version | Change |
|---|---|---|---|
| 1.6 | August 21, 2026 | 1.0.1 | Updated package authorship and software-copyright metadata to list Lilac Li as package author and Jae Man Park as package maintainer and joint copyright holder without the package-author role |
| 1.5 | August 6, 2026 | 1.0.1 | Revised examples and output paths in response to CRAN review; executable demonstrations use temporary locations with cleanup, and the Shiny launch is guarded |
| 1.4 | July 18, 2026 | 1.0.1 | Added the complete-classification diagnostic, safe directory-path and finite-dimension checks for PDF export, and explicit unknown-polarization semantics |
| 1.3 | July 17, 2026 | 1.0.1 | Documented analytical and privacy hardening, distinct neutral counts, scalar threshold validation, and failure-safe profile export |
| 1.2 | July 12, 2026 | 1.0.1 | Added installed editable source and submission-candidate metadata |
| 1.1 | July 12, 2026 | 1.0.1 | Added CRAN-ready attribution, citation, and installed guide formats |
| 1.0 | July 12, 2026 | 1.0.0 | Initial stable technical guide for the GitHub release |
Robinson CH, Damschroder LJ. A pragmatic context assessment tool (pCAT): using a Think Aloud method to develop an assessment of contextual barriers to change. Implementation Science Communications. 2023;4:3. doi:10.1186/s43058-022-00380-5.
Domlyn AM, Dodge J, Pfeiffer PN, Robinson CH, Evans L, Damschroder LJ, Stewart MA, Garlick B, Sussman JB, Nevedal AL. Evaluating the utility of an abbreviated Consolidated Framework for Implementation Research (CFIR) for rapid qualitative analysis: a suicide prevention program case study. Implementation Science Communications. 2026;7:129. doi:10.1186/s43058-026-00956-5.
Official instrument attachment: Pragmatic Context Assessment Tool / Barrier Buster Tool, available through the Dissemination and Implementation Models in Health Research and Practice assessment-instrument repository.
R Core Team. Writing R Extensions. R Foundation for Statistical Computing.
citation("pcatR")When reporting pCAT results, cite the original instrument article and the software. Cite the 2026 article when using or discussing the updated CFIR mappings.
pcatR is an independent software implementation. It is not an official product or endorsement of Claire H. Robinson, Laura J. Damschroder, the U.S. Department of Veterans Affairs, the CFIR Leadership Team, or the instrument repository.
The R source code is licensed under MIT. Exact instrument wording and source-derived mappings are attributed under CC BY 4.0. See LICENSE and LICENSE.note for details.