# pcatR

[![R-CMD-check](https://github.com/JaeManP/pcatR/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/JaeManP/pcatR/actions/workflows/R-CMD-check.yaml)
[![test-coverage](https://github.com/JaeManP/pcatR/actions/workflows/test-coverage.yaml/badge.svg)](https://github.com/JaeManP/pcatR/actions/workflows/test-coverage.yaml)
[![pkgdown](https://github.com/JaeManP/pcatR/actions/workflows/pkgdown.yaml/badge.svg)](https://github.com/JaeManP/pcatR/actions/workflows/pkgdown.yaml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

`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:

```r
pcat_user_guide()
```

## Installation

### From GitHub

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

### From a downloaded source archive

```r
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

```r
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:

| Component | Code | Meaning |
|---|---:|---|
| Direction | 1 | Disagree / potential barrier |
| Direction | 2 | Neutral |
| Direction | 3 | Agree / potential facilitator |
| Effect | 0 | Weak or no effect |
| Effect | 1 | Strong effect |

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:

| Direction | Effect | Classification | Display code |
|---:|---:|---|---:|
| 1 | 1 | Strong barrier | -2 |
| 1 | 0 | Weak barrier | -1 |
| 2 | blank | Neutral | 0 |
| 3 | 0 | Weak facilitator | +1 |
| 3 | 1 | Strong facilitator | +2 |

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`.

```r
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:

```r
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

| Task | Primary functions |
|---|---|
| Instrument and mappings | `pcat_items()`, `pcat_construct_map()`, `pcat_response_options()` |
| Templates and import | `pcat_template()`, `pcat_write_template()`, `pcat_read_csv()`, `pcat_standardize()` |
| Validation | `pcat_validate()`, `pcat_validation_issues()` |
| Classification | `pcat_classify()` |
| End-to-end analysis | `pcat_analyse()` |
| Item summaries | `pcat_summarise()` |
| Agreement/disagreement | `pcat_consensus()` |
| Repeated assessment | `pcat_change()` |
| Action planning | `pcat_action_plan()`, `pcat_strategy_candidates()` |
| Figures | `plot_pcat_profile()`, `plot_pcat_heatmap()`, `plot_pcat_change()` |
| Export | `pcat_write_analysis()`, `pcat_save_profile_pdf()` |
| Technical guide | `pcat_user_guide()` |
| Diagnostic check | `pcat_self_test()` |
| Optional dashboard | `pcat_app()` |

## 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:

```r
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](https://www.unk.edu/academics/management/lilac-li.php).
Jae Man Park is the package maintainer. Author and maintainer profile links are
retained in the package metadata and website.

Run:

```r
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](LICENSE.note) and
[REFERENCES.md](https://github.com/JaeManP/pcatR/blob/main/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

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

See [CONTRIBUTING.md](https://github.com/JaeManP/pcatR/blob/main/CONTRIBUTING.md), [GOVERNANCE.md](https://github.com/JaeManP/pcatR/blob/main/GOVERNANCE.md), and
[SECURITY.md](https://github.com/JaeManP/pcatR/blob/main/SECURITY.md) before contributing.

Before publishing, follow [PUBLISHING.md](https://github.com/JaeManP/pcatR/blob/main/PUBLISHING.md), use [RELEASE_CHECKLIST.md](https://github.com/JaeManP/pcatR/blob/main/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](https://github.com/JaeManP/pcatR/blob/main/RELEASE_VALIDATION.md).
