Package 'PPCSexRx' reference manual

Title:	Prescribe Sub-Symptom Exercise for Adolescent Concussion
Description:	A clinical decision support system for sub-symptom threshold aerobic exercise (SSTAE) prescription in adolescents with persistent post-concussion symptoms (PPCS). Implements an evidence-based protocol derived from a systematic review of seven studies (Li, 2026; <doi:10.17605/osf.io/kvuf6>), encoding safety screening, Buffalo Concussion Treadmill Test (BCTT)-guided heart rate prescription, session-level progress tracking, and evidence disclosure using the Grading of Recommendations, Assessment, Development and Evaluation (GRADE) framework into an open-source tool for athletic trainers and clinicians. Designed to support implementation in resource-limited settings where BCTT equipment may be unavailable. GRADE certainty of evidence: LOW. For clinician use only; not a substitute for clinical judgement.
Authors:	Guang Li [aut, cre] (ORCID: <https://orcid.org/0009-0004-2807-9029>)
Maintainer:	Guang Li <[email protected]>
License:	MIT + file LICENSE
Version:	0.1.0
Built:	2026-06-01 10:00:39 UTC
Source:	https://github.com/guangl10/ppcsexrx

Plot rehabilitation progress for a ppcs_track object

Description

Generates a dual-panel plot showing PCSS symptom trajectory and achieved HR over time. Requires base R graphics only (no dependencies).

Usage

## S3 method for class 'ppcs_track'
plot(x, ...)
## S3 method for class 'ppcs_track'
plot(x, ...)

Arguments

x

A ppcs_track object.

...

Further arguments passed to plot().

Value

Invisibly returns x, called for its side effect of drawing a two-panel base-graphics figure: the upper panel shows Post-Concussion Symptom Scale (PCSS) scores across sessions; the lower panel shows achieved and target heart rate (bpm) across sessions. Returns a message (via message) and invisible(x) without plotting if fewer than two sessions are recorded.

Prescribe Sub-symptom Aerobic Exercise for Adolescent PPCS

Description

Implements the evidence-based protocol from Li (2026). GRADE: LOW certainty, Conditional recommendation FOR. Run screen_ppcs first to confirm eligibility.

Usage

prescribe_ppcs(
  age,
  days_post_injury,
  hrst = NULL,
  vestibular_symptoms = FALSE,
  cervical_symptoms = FALSE,
  sessions_completed = 0,
  last_session_worse = FALSE
)
prescribe_ppcs(
  age,
  days_post_injury,
  hrst = NULL,
  vestibular_symptoms = FALSE,
  cervical_symptoms = FALSE,
  sessions_completed = 0,
  last_session_worse = FALSE
)

Arguments

age

Numeric. Age 13-18 years. CAT p.2, L10: inclusion 13-18.

days_post_injury

Numeric. Days since injury. Must be >=28 for PPCS. CAT p.2, L10.

hrst

Numeric or NULL. Symptom threshold HR from BCTT (bpm). If NULL, age-predicted fallback is used. CAT p.11, L19.

vestibular_symptoms

Logical. TRUE = contraindication. CAT p.11, L25.

cervical_symptoms

Logical. TRUE = contraindication. CAT p.11, L25.

sessions_completed

Integer. Sessions at current HR without worsening. CAT p.11, L21.

last_session_worse

Logical. Did PCSS increase >=2 points last session? CAT p.11, L21-22.

Value

An object of class ppcs_prescription with prescription details.

References

Li G. (2026). Sub-symptom Threshold Aerobic Exercise for Adolescents With PPCS: A Critically Appraised Topic. Winner, NATA Foundation Student Writing Contest.

Examples

# Case 1: Rural clinic, no BCTT available
prescribe_ppcs(age = 16, days_post_injury = 35)

# Case 2: University clinic with BCTT data
prescribe_ppcs(age = 17, days_post_injury = 40, hrst = 160)

# Case 3: Safety stop - vestibular symptoms present
try(prescribe_ppcs(age = 15, days_post_injury = 30,
                   vestibular_symptoms = TRUE))
# Case 1: Rural clinic, no BCTT available
prescribe_ppcs(age = 16, days_post_injury = 35)

# Case 2: University clinic with BCTT data
prescribe_ppcs(age = 17, days_post_injury = 40, hrst = 160)

# Case 3: Safety stop - vestibular symptoms present
try(prescribe_ppcs(age = 15, days_post_injury = 30,
                   vestibular_symptoms = TRUE))

Print method for ppcs_prescription objects

Description

Displays a formatted clinical prescription sheet.

Usage

## S3 method for class 'ppcs_prescription'
print(x, ...)
## S3 method for class 'ppcs_prescription'
print(x, ...)

Arguments

x

A ppcs_prescription object.

...

Further arguments passed to or from other methods.

Value

Invisibly returns x (a ppcs_prescription list), called primarily for its side effect of printing the formatted prescription to the console.

Print method for ppcs_screen objects

Description

Print method for ppcs_screen objects

Usage

## S3 method for class 'ppcs_screen'
print(x, ...)
## S3 method for class 'ppcs_screen'
print(x, ...)

Arguments

x

A ppcs_screen object.

...

Further arguments (unused).

Value

Invisibly returns x (a ppcs_screen list), called primarily for its side effect of printing the eligibility screen result to the console.

Print method for ppcs_track objects

Description

Print method for ppcs_track objects

Usage

## S3 method for class 'ppcs_track'
print(x, ...)
## S3 method for class 'ppcs_track'
print(x, ...)

Arguments

x

A ppcs_track object.

...

Further arguments (unused).

Value

Invisibly returns x (a ppcs_track list), called primarily for its side effect of printing the session progress summary to the console.

Screen Adolescent for SSTAE Eligibility

Description

Implements the PICO-based eligibility criteria from Li (2026). Run this before prescribe_ppcs to confirm the patient is appropriate for sub-symptom threshold aerobic exercise.

Usage

screen_ppcs(
  age,
  days_post_injury,
  vestibular_symptoms = FALSE,
  cervical_symptoms = FALSE,
  vision_symptoms = FALSE,
  verbose = TRUE
)
screen_ppcs(
  age,
  days_post_injury,
  vestibular_symptoms = FALSE,
  cervical_symptoms = FALSE,
  vision_symptoms = FALSE,
  verbose = TRUE
)

Arguments

age

Numeric. Patient age in years. Eligible range: 13-18.

days_post_injury

Numeric. Days since concussion. PPCS defined as >=28.

vestibular_symptoms

Logical. Active uncontrolled vestibular symptoms? Default FALSE. Contraindication per Li (2026), p.11.

cervical_symptoms

Logical. Active uncontrolled cervical symptoms? Default FALSE. Contraindication per Li (2026), p.11.

vision_symptoms

Logical. Exercise-induced vision dysfunction present? Default FALSE. Associated with prolonged PPCS (Vernau et al., 2023).

verbose

Logical. If TRUE (default), prints full clinical output. Set FALSE for patient/caregiver-facing simplified output.

Value

A list of class ppcs_screen with fields:

status: "eligible", "contraindicated", or "needs_referral"
reason: Character. Clinical rationale for status.
referral: Character or NA. Recommended referral if applicable.
next_step: Character. Recommended action.

References

Li G. (2026). Sub-symptom Threshold Aerobic Exercise for Adolescents With PPCS: A Critically Appraised Topic. Winner, NATA Foundation Student Writing Contest.

Vernau BT, Haider MN, Fleming A, et al. Exercise-Induced Vision Dysfunction Early After Sport-Related Concussion Is Associated With Persistent Postconcussive Symptoms. Clin J Sport Med. 2023;33(4):388-394.

Examples

# Eligible athlete
screen_ppcs(age = 16, days_post_injury = 35)

# Contraindicated: too early
screen_ppcs(age = 16, days_post_injury = 20)

# Needs referral: vestibular symptoms present
screen_ppcs(age = 16, days_post_injury = 35, vestibular_symptoms = TRUE)

# Patient/caregiver output
screen_ppcs(age = 16, days_post_injury = 35, verbose = FALSE)
# Eligible athlete
screen_ppcs(age = 16, days_post_injury = 35)

# Contraindicated: too early
screen_ppcs(age = 16, days_post_injury = 20)

# Needs referral: vestibular symptoms present
screen_ppcs(age = 16, days_post_injury = 35, vestibular_symptoms = TRUE)

# Patient/caregiver output
screen_ppcs(age = 16, days_post_injury = 35, verbose = FALSE)

Track SSTAE Rehabilitation Progress Over Time

Description

Records and evaluates session-level data over the course of a sub-symptom threshold aerobic exercise programme. Compares observed progress against the progression and stop rules described in Li (2026), p.14, and generates a recommendation for the next session.

Usage

track_progress(
  log,
  current_pcss,
  current_hr,
  current_duration,
  prescription,
  verbose = TRUE
)
track_progress(
  log,
  current_pcss,
  current_hr,
  current_duration,
  prescription,
  verbose = TRUE
)

Arguments

log

A data frame of previous sessions with columns:

date: Character or Date. Session date (e.g. "2026-03-01").
pcss: Numeric. Post-Concussion Symptom Scale total (0-132).
target_hr: Numeric. Prescribed HR target for that session (bpm).
achieved_hr: Numeric. Mean HR achieved during session (bpm).
duration_min: Numeric. Minutes of exercise completed.
symptoms_worsened: Logical. Did PCSS increase >= 2 points vs prior session?

Pass NULL to initialise an empty log (first session).

current_pcss

Numeric. Today's PCSS score (0-132).

current_hr

Numeric. HR achieved in today's session (bpm).

current_duration

Numeric. Minutes completed today.

prescription

A ppcs_prescription object from prescribe_ppcs. Used to retrieve the current target HR.

verbose

Logical. If TRUE (default), prints full clinician output. Set FALSE for patient/caregiver-facing simplified output.

Value

A list of class ppcs_track with fields:

updated_log: Data frame. The log with today's session appended.
phase: Character. Current rehabilitation phase.
recommendation: Character. Action for the next session.
adjust_hr: Numeric. Suggested HR target for next session (bpm).
sessions_total: Integer. Total sessions recorded.
pcss_change: Numeric. PCSS change from first to today.
verbose: Logical. Passed through for print method.

References

Li G. (2026). Sub-symptom Threshold Aerobic Exercise for Adolescents With PPCS: A Critically Appraised Topic. Winner, NATA Foundation Student Writing Contest. p.14.

Kurowski BG, et al. Aerobic Exercise for Adolescents With Prolonged Symptoms After Mild Traumatic Brain Injury. J Head Trauma Rehabil. 2017;32(2):79-89.

Examples

# Step 1: get a prescription
rx <- prescribe_ppcs(age = 16, days_post_injury = 35, hrst = 160)

# Step 2: first session - no prior log
t1 <- track_progress(
  log               = NULL,
  current_pcss      = 28,
  current_hr        = 120,
  current_duration  = 18,
  prescription      = rx
)
t1

# Step 3: second session - pass updated log forward
t2 <- track_progress(
  log               = t1$updated_log,
  current_pcss      = 24,
  current_hr        = 122,
  current_duration  = 20,
  prescription      = rx
)
t2
# Step 1: get a prescription
rx <- prescribe_ppcs(age = 16, days_post_injury = 35, hrst = 160)

# Step 2: first session - no prior log
t1 <- track_progress(
  log               = NULL,
  current_pcss      = 28,
  current_hr        = 120,
  current_duration  = 18,
  prescription      = rx
)
t1

# Step 3: second session - pass updated log forward
t2 <- track_progress(
  log               = t1$updated_log,
  current_pcss      = 24,
  current_hr        = 122,
  current_duration  = 20,
  prescription      = rx
)
t2

Package 'PPCSexRx'

Help Index

Plot rehabilitation progress for a ppcs_track object

Description

Usage

Arguments

Value

Prescribe Sub-symptom Aerobic Exercise for Adolescent PPCS

Description

Usage

Arguments

Value

References

Examples

Print method for ppcs_prescription objects

Description

Usage

Arguments

Value

Print method for ppcs_screen objects

Description

Usage

Arguments

Value

Print method for ppcs_track objects

Description

Usage

Arguments

Value

Screen Adolescent for SSTAE Eligibility

Description

Usage

Arguments

Value

References

Examples

Track SSTAE Rehabilitation Progress Over Time

Description

Usage

Arguments

Value

References

Examples