### Install and develop PhysioCore from r-universe

Source: https://github.com/x-biosignal/physioclinical/blob/main/CONTRIBUTING.md

Development setup commands for contributing to Physio* packages. First install the package from r-universe, then for a source checkout load the package, run the test suite, and perform a full package check.

```r
install.packages(
  "PhysioCore",
  repos = c("https://x-biosignal.r-universe.dev", "https://cloud.r-project.org")
)
```

```bash
Rscript -e 'devtools::load_all()'   # load for development
Rscript -e 'devtools::test()'       # run the test suite
R CMD check .                        # full package check
```

--------------------------------

### Install PhysioClinical from x-biosignal R-universe

Source: https://github.com/x-biosignal/physioclinical/blob/main/README.md

Install the PhysioClinical package from the x-biosignal R-universe repository. Because the package containers build on Bioconductor, the BiocManager package must be installed first and its repositories included in the installation command.

```r
install.packages("BiocManager", repos = "https://cloud.r-project.org")
install.packages("PhysioClinical",
  repos = c("https://x-biosignal.r-universe.dev", BiocManager::repositories()))
```

--------------------------------

### Run raschAnalyze on synthetic Barthel responses

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/raschAnalyze.Rd

Example from the raschAnalyze documentation. It creates a synthetic Barthel response matrix, then calls raschAnalyze("barthel", resp) and prints the item_hierarchy field. The example is wrapped in \donttest and only runs if the PhysioAppKit package is installed.

```R
set.seed(1)
items <- getInstrument("barthel")@items
# a small synthetic cohort of weighted Barthel responses
resp <- t(replicate(50, {
  ability <- stats::rnorm(1)
  vapply(c(2, 1, 1, 2, 2, 2, 2, 3, 3, 2), function(m)
    c(0, 5, 10, 15)[min(m, max(0, round(ability + m / 2))) + 1], numeric(1))
}))
colnames(resp) <- items
if (requireNamespace("PhysioAppKit", quietly = TRUE)) {
  fit <- raschAnalyze("barthel", resp)
  fit$item_hierarchy
}
```

--------------------------------

### getClinimetric() examples: 10mWT MCII and FMA-UE MCID_anchor

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/getClinimetric.Rd

Look up a clinimetric constant for an instrument and statistic. The first example retrieves the MCII for the 10mWT; the second retrieves the MCID_anchor for the FMA-UE with a population key to disambiguate multiple rows. Both return a data.frame with value, CI, method, reference_doi, population_n, and provenance_note, or NA with a warning if no match.

```r
getClinimetric("10mWT", "MCII")
```

```r
getClinimetric("FMA-UE", "MCID_anchor", population = "chronic_stroke_minimal")
```

--------------------------------

### romReference() examples: filter by joint or motion

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/romReference.Rd

Two example calls to romReference(). The first filters by joint ("knee"), the second by motion ("flexion"). Both return a data.frame with columns joint, motion, plane, reference_deg, and source.

```r
romReference("knee")
```

```r
romReference(motion = "flexion")
```

--------------------------------

### Construct a ClinicalInstrument with toy scale

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/ClinicalInstrument.Rd

Creates a ClinicalInstrument with a toy scale, two items, and their ranges. The example uses default values for other parameters.

```r
ClinicalInstrument(
  id = "toy", name = "Toy scale", items = c("q1", "q2"),
  item_ranges = list(q1 = c(0, 4), q2 = c(0, 4)))
```

--------------------------------

### Setup: load PhysioClinical and check for PhysioAnnotationHub

Source: https://github.com/x-biosignal/physioclinical/blob/main/vignettes/clinical-outcomes.Rmd

Sets up the vignette chunk options and loads the PhysioClinical package. Also checks for the optional PhysioAnnotationHub package and stores the result in has_hub for conditional evaluation.

```r
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(PhysioClinical)
has_hub <- requireNamespace("PhysioAnnotationHub", quietly = TRUE)
```

--------------------------------

### raschResponder

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/raschResponder.Rd

Documentation for the raschResponder function, including usage, arguments, return value, and examples.

```APIDOC
## raschResponder

### Description
Classifies each person's change between two occasions using interval (logit) measures from `raschAnalyze()` / `PhysioAppKit::pcm_measure()`. The Rasch model's own standard errors give a distribution-free standard error of measurement and hence the Minimal Detectable Change; the pre/post change is then run through `mdcResponder()` (reliable change) and, when an MCID on the logit scale is supplied, `classifyResponder()` (the MDC x MCID framework).

### Usage
```r
raschResponder(
  pre,
  post,
  mcid = NULL,
  confidence = 0.95,
  direction = c("increase", "decrease")
)
```

### Arguments
- **pre, post** (poly_rasch fit, list with `theta`/`theta_se`, or numeric measure vector) - Required - Baseline and follow-up measures. `se` is required (from the fit) to derive the MDC.
- **mcid** (numeric) - Optional - MCID on the logit scale; enables the four-level `classifyResponder()` output.
- **confidence** (numeric) - Optional - Confidence level for the MDC (default 0.95).
- **direction** (character) - Optional - `"increase"` (default; higher measure = better) or `"decrease"`.

### Value
A `data.frame`, one row per person: `pre`, `post`, `change`, `improvement` (direction-aware), `sem`, `mdc`, `reliable_change` (from `mdcResponder()`) and, if `mcid` given, `classification` (from `classifyResponder()`). Attributes `sem`, `mdc`, `mcid` record the values used.

### Details
The two occasions must be on a common metric -- calibrate the items once and anchor them, or co-calibrate -- and the persons must align by row.

### Examples
```r
pre  <- list(theta = c(0, 0, 0, 0), theta_se = rep(0.3, 4))
post <- list(theta = c(1.5, 0.1, -1.2, 0.05), theta_se = rep(0.3, 4))
raschResponder(pre, post, mcid = 1.0)
```

### See Also
`raschAnalyze()`, `mdcResponder()`, `classifyResponder()`, `estimateMDC()`
```

--------------------------------

### estimateMCID_anchor example

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/estimateMCID_anchor.Rd

Example usage with simulated data: 50 improved and 50 unimproved cases. Sets a random seed, generates change scores from normal distributions, and calls estimateMCID_anchor with default ROC method.

```R
set.seed(1)
change <- c(rnorm(50, 1, 2), rnorm(50, 8, 2))
anchor <- rep(c(0, 1), each = 50)
estimateMCID_anchor(change, anchor)
```

--------------------------------

### estimateMCID_distribution example

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/estimateMCID_distribution.Rd

Computes the distribution-based MCID using the default fraction of 0.5, yielding 6 for a baseline standard deviation of 12.

```r
estimateMCID_distribution(baseline_sd = 12)
```

--------------------------------

### List clinimetric constants with listClinimetrics()

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/listClinimetrics.Rd

Lists clinimetric constants, optionally filtered by instrument name (case insensitive). The example filters for the "6MWT" instrument.

```r
listClinimetrics("6MWT")
```

--------------------------------

### Score MFIS with all items set to 2

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreMFIS.Rd

Scores the MFIS with all items set to 2. The example uses getInstrument("mfis") to obtain the item names for the named vector.

```r
scoreMFIS(stats::setNames(rep(2, 21), getInstrument("mfis")@items))
```

--------------------------------

### GovernedNormativeReference

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/GovernedNormativeReference.Rd

Documentation for the GovernedNormativeReference constructor function, including usage, arguments, return value, and an example.

```APIDOC
## GovernedNormativeReference

### Description
Constructs a validated governed normative reference object.

### Usage
```r
GovernedNormativeReference(
  id,
  modality,
  metric,
  version = "1.0.0",
  provenance = list(),
  consent = list(),
  license = list(),
  governance = list(),
  strata_vars = character(0),
  model = list(),
  n = NA_real_
)
```

### Arguments
- **id** (character) - Required - Identifying string.
- **modality** (character) - Required - Identifying string.
- **metric** (character) - Required - Identifying string.
- **version** (character) - Optional - Semantic version (default `"1.0.0"`).
- **provenance** (list) - Optional - Governance list; `provenance$source` is required.
- **consent** (list) - Optional - Governance list; `consent$status` is required.
- **license** (list) - Optional - Governance list; `license$spdx` is required.
- **governance** (list) - Optional - Governance list.
- **strata_vars** (character vector) - Optional - Character vector of stratification variables.
- **model** (list) - Optional - List holding the normative model (stratified mean/sd table or LMS coefficients).
- **n** (numeric) - Optional - Reference sample size.

### Value
A validated `GovernedNormativeReference` object.

### Examples
```r
GovernedNormativeReference(
  id = "gait_speed_adult", modality = "gait", metric = "gait_speed",
  version = "1.0.0",
  provenance = list(source = "Bohannon 1997", doi = "10.1093/ageing/26.1.15"),
  consent = list(status = "public_aggregate"),
  license = list(spdx = "CC-BY-4.0", redistribution_ok = TRUE),
  governance = list(custodian = "Matsui Lab", access_level = "open"),
  strata_vars = c("age", "sex"),
  model = list(type = "strata",
               table = data.frame(age = 70, sex = "M", mean = 1.3, sd = 0.2)),
  n = 230)
```

### See Also
`registerNormative()`, `validateNormativeManifest()`
```

--------------------------------

### raschResponder example with pre/post lists and MCID

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/raschResponder.Rd

Shows a minimal call to raschResponder() using two lists of theta and theta_se values for four persons, with an MCID of 1.0 on the logit scale. The pre and post lists must be on a common metric and persons aligned by row.

```r
pre  <- list(theta = c(0, 0, 0, 0), theta_se = rep(0.3, 4))
post <- list(theta = c(1.5, 0.1, -1.2, 0.05), theta_se = rep(0.3, 4))
raschResponder(pre, post, mcid = 1.0)
```

--------------------------------

### Build a Barthel to FIM crosswalk with equateScores

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/equateScores.Rd

Example from the documentation showing how to create a crosswalk from Barthel to FIM scores using simulated data. It sets a random seed, generates ability scores, transforms them into Barthel and FIM scales, calls equateScores with the default equipercentile method, and prints the first rows of the resulting table.

```r
set.seed(1)
ability <- rnorm(200)
barthel <- pmin(100, pmax(0, round((ability + 3) * 16 / 5) * 5))
fim <- pmin(126, pmax(18, round(18 + (ability + 3) * 18)))
eq <- equateScores(barthel, fim)          # Barthel -> FIM crosswalk
head(eq$table)
```

--------------------------------

### score6MWT example

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/score6MWT.Rd

Example call to score6MWT with a distance of 450 metres and demographics for the Enright reference equation. Returns a performance_test_score object with distance, predicted, percent_predicted, lln, and below_lln.

```r
score6MWT(450, age = 60, sex = "male", height_cm = 175, weight_kg = 75)
```

--------------------------------

### scoreTUG example: classify a TUG time

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreTUG.Rd

Example call to scoreTUG with a time of 15 seconds, which is >= 13.5 s and thus indicates elevated fall risk.

```r
scoreTUG(15)   # >= 13.5 s -> elevated fall risk
```

--------------------------------

### Construct a GovernedNormativeReference with stratified model

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/GovernedNormativeReference.Rd

Constructs a governed normative reference with required provenance, consent, and license fields. The example uses a stratified model with a data frame for age and sex strata, and sets n to 230.

```r
GovernedNormativeReference(
  id = "gait_speed_adult", modality = "gait", metric = "gait_speed",
  version = "1.0.0",
  provenance = list(source = "Bohannon 1997", doi = "10.1093/ageing/26.1.15"),
  consent = list(status = "public_aggregate"),
  license = list(spdx = "CC-BY-4.0", redistribution_ok = TRUE),
  governance = list(custodian = "Matsui Lab", access_level = "open"),
  strata_vars = c("age", "sex"),
  model = list(type = "strata",
               table = data.frame(age = 70, sex = "M", mean = 1.3, sd = 0.2)),
  n = 230)
```

--------------------------------

### Export ClinicalScore to FHIR with toFHIRObservation()

Source: https://github.com/x-biosignal/physioclinical/blob/main/vignettes/clinical-outcomes.Rmd

Serializes a ClinicalScore (the follow-up score from the earlier example) to an HL7 FHIR R4 Observation and prints its resourceType and valueQuantity.

```r
obs <- toFHIRObservation(fu)
obs$resourceType
obs$valueQuantity
```

--------------------------------

### Score SF-36 with best-health responses

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreSF36.Rd

Creates a named vector of raw responses representing all best-health answers and passes it to scoreSF36. The example uses getInstrument("sf36")@items to obtain the item names and expects every subscale to score 100.

```r
# all best-health responses -> every subscale scores 100
best <- stats::setNames(
  c(1, rep(3, 10), rep(2, 7), 1, 1, 1, 1, 6, 6, 1, 1, 6, 6, 1, 6, 5, 5, 1, 5, 1),
  getInstrument("sf36")@items)
scoreSF36(best)@subscales
```

--------------------------------

### Get BBS MDC clinimetric with getClinimetric()

Source: https://github.com/x-biosignal/physioclinical/blob/main/vignettes/clinical-outcomes.Rmd

Retrieves the published MDC value for the BBS from the bundled clinimetric store, with literature provenance.

```r
getClinimetric("BBS", "MDC", population = "elderly_baseline_45_56")
```

--------------------------------

### Call masLevelLabel with a numeric value

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/masLevelLabel.Rd

Example usage of masLevelLabel, converting the numeric value 1.5 to its ordinal label "1+".

```r
masLevelLabel(1.5)
```

--------------------------------

### Score MMSE with named component responses

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreMMSE.Rd

Scores the MMSE by passing named responses for each of the eleven components. The example uses setNames to assign the component names from getInstrument("mmse")@items to the numeric response vector.

```r
scoreMMSE(stats::setNames(c(5, 5, 3, 5, 3, 2, 1, 3, 1, 1, 1),
                          getInstrument("mmse")@items))
```

--------------------------------

### Score FMA-LE with all items set to 2

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreFMALE.Rd

Example usage of scoreFMALE with a named vector of 17 items, each set to the maximum score of 2, using the instrument's item names from getInstrument("fma_le").

```r
scoreFMALE(stats::setNames(rep(2, 17), getInstrument("fma_le")@items))
```

--------------------------------

### Score BPI with scoreBPI()

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreBPI.Rd

Scores the Brief Pain Inventory (short form) using named responses. The example passes a vector of 11 numeric responses (severity and interference items) with names from the instrument's item list. The result is a ClinicalScore with subscales for severity and interference means.

```r
scoreBPI(stats::setNames(c(8, 2, 5, 4, 5, 6, 5, 7, 3, 5, 6),
                         getInstrument("bpi")@items))
```

--------------------------------

### Create ClinicalScore and export to QS domain

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/toCDISC_QS.Rd

Constructs a ClinicalScore object for the FIM instrument with total and subscale scores, then calls toCDISC_QS to generate the QS domain data frame. The example uses a subject ID and timestamp; the resulting data frame follows the SDTMIG column layout.

```r
sc <- methods::new("ClinicalScore", instrument_id = "fim", total = 90,
                   subscales = c(motor = 60, cognitive = 30),
                   subject_id = "01-001", timestamp = "2026-07-26")
toCDISC_QS(sc)
```

--------------------------------

### scoreMRS example

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreMRS.Rd

Scores a single mRS grade of 3, returning a ClinicalScore object with total 3 and the corresponding disability stratum.

```R
scoreMRS(3)
```

--------------------------------

### Score BBS instrument with scoreInstrument()

Source: https://github.com/x-biosignal/physioclinical/blob/main/vignettes/clinical-outcomes.Rmd

Scores a Berg Balance Scale (BBS) assessment at baseline and follow-up using scoreInstrument(). The example creates item response vectors for 14 items and prints the total scores.

```r
baseline_items <- setNames(c(4, 3, 4, 3, 2, 3, 2, 2, 3, 2, 1, 2, 1, 1),
                           sprintf("item%02d", 1:14))
followup_items <- setNames(c(4, 4, 4, 4, 3, 4, 3, 3, 4, 3, 3, 3, 2, 3),
                           sprintf("item%02d", 1:14))

bl <- scoreInstrument("berg", baseline_items, subject_id = "P001",
                      timestamp = "2026-01-10")
fu <- scoreInstrument("berg", followup_items, subject_id = "P001",
                      timestamp = "2026-04-10")
c(baseline = bl@total, followup = fu@total)
```

--------------------------------

### classifyResponder example with explicit MDC and MCID

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/classifyResponder.Rd

Classifies three subjects' changes from baseline to follow-up using explicit MDC and MCID thresholds. The function returns a data.frame with change, improvement, crossing flags, and a four-level classification factor. Missing baseline or follow-up values result in NA flags and classification.

```r
classifyResponder(c(20, 25, 30), c(31, 26, 45), mdc = 5.2, mcid = 9)
```

--------------------------------

### Score FIM with example responses

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreFIM.Rd

Scores the FIM instrument with a named numeric vector of 18 responses, each set to 4. The names are obtained from the instrument definition via getInstrument("fim")@items.

```r
scoreFIM(stats::setNames(rep(4, 18), getInstrument("fim")@items))
```

--------------------------------

### Score Barthel Index with named items

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreBarthel.Rd

Example call to scoreBarthel using a named numeric vector of item responses. The vector is created with stats::setNames and uses the item names from the instrument definition.

```r
scoreBarthel(stats::setNames(
  c(10, 5, 5, 10, 10, 10, 10, 15, 15, 10), getInstrument("barthel")@items))
```

--------------------------------

### Estimate MDC from test-retest data

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/estimateMDC.Rd

Example usage of estimateMDC with a simulated test-retest dataset. Sets a random seed, generates baseline and retest measurements, then calls estimateMDC on the combined matrix. The default confidence (0.95) and model ('twoway') are used.

```r
set.seed(1)
base <- rnorm(40, 50, 10)
retest <- base + rnorm(40, 0, 3)
estimateMDC(cbind(base, retest))
```

--------------------------------

### Score FMA-UE with all items at maximum

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreFMAUE.Rd

Scores the FMA-UE with all 33 items set to the maximum response of 2, producing a total score of 66. The example uses the instrument's item names from getInstrument("fma_ue")@items to construct a named numeric vector.

```r
scoreFMAUE(stats::setNames(rep(2, 33), getInstrument("fma_ue")@items))
```

--------------------------------

### Score MoCA with scoreMoCA()

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreMoCA.Rd

Scores the MoCA by passing named domain scores in the instrument's item order. The example supplies the seven domain scores (visuospatial/executive, naming, attention, language, abstraction, delayed recall, orientation) and relies on getInstrument("moca")@items to name them. Returns a ClinicalScore with total (0-30) and impairment stratum; a total below 26 indicates cognitive impairment.

```r
scoreMoCA(stats::setNames(c(5, 3, 6, 3, 2, 5, 6),
                          getInstrument("moca")@items))
```

--------------------------------

### Classify change scores with mdcResponder

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/mdcResponder.Rd

Example call to mdcResponder with change scores c(5, 0.5, -6) and sem_value = 1.5, using the default confidence of 0.95. Returns a character vector with values "improved", "stable", or "declined".

```r
mdcResponder(c(5, 0.5, -6), sem_value = 1.5)
```

--------------------------------

### Register a ClinicalInstrument object

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/registerInstrument.Rd

Creates a ClinicalInstrument object and registers it. The instrument id "toy2" is used, and the default overwrite = FALSE means registering an existing id would raise an error.

```R
inst <- ClinicalInstrument(id = "toy2", items = c("a", "b"),
  item_ranges = list(a = c(0, 1), b = c(0, 1)))
registerInstrument(inst)
```

--------------------------------

### Score goals with defineGoal() and scoreGAS()

Source: https://github.com/x-biosignal/physioclinical/blob/main/vignettes/clinical-outcomes.Rmd

Defines two goals with importance and difficulty ratings, then scores them using Goal Attainment Scaling with attained levels of 1 and 0.

```r
goals <- list(
  defineGoal("Independent standing balance", importance = 3, difficulty = 2),
  defineGoal("Walk 10 m unaided", importance = 3, difficulty = 3))
scoreGAS(goals, attained_levels = c(1, 0))
```

--------------------------------

### writeOMOPTables(tables, path)

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/writeOMOPTables.Rd

Function to write OMOP CDM tables to CSV files.

```APIDOC
## writeOMOPTables(tables, path)

### Description
Writes each non-empty table from `toOMOP()` to `<path>/<table>.csv` (lower-cased, e.g. `measurement.csv`), following the one-file-per-table OMOP convention.

### Usage
```r
writeOMOPTables(tables, path)
```

### Arguments
- **tables** (ClinicalScore, list of ClinicalScore, or list from `toOMOP()`) - Required - A `ClinicalScore`, a list of them, or the list returned by `toOMOP()`.
- **path** (character) - Required - Output directory (created if needed).

### Value
A character vector of written file paths, invisibly.

### See Also
`toOMOP()`
```

--------------------------------

### defineGoal

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/defineGoal.Rd

Documentation for the defineGoal function, which creates a Goal Attainment Scaling goal object.

```APIDOC
## defineGoal(description, levels = -2:2, weight = 1, importance = NULL, difficulty = NULL, icf_tag = NULL)

### Description
Defines a Goal Attainment Scaling (GAS) goal with attainment levels, a weight, and an optional ICF linkage. When both `importance` and `difficulty` are provided, the weight is their product (Turner-Stokes); otherwise the `weight` argument is used (default 1, i.e., unweighted GAS).

### Usage
```r
defineGoal(
  description,
  levels = -2:2,
  weight = 1,
  importance = NULL,
  difficulty = NULL,
  icf_tag = NULL
)
```

### Parameters
- **description** (character) - Required - Free-text goal description.
- **levels** (numeric vector) - Optional - Ordered numeric attainment levels (must include 0, the expected outcome); default `-2:2`.
- **weight** (numeric) - Optional - Goal weight when `importance`/`difficulty` are not supplied (default 1, positive).
- **importance** (numeric) - Optional - 0+ rating; if both `importance` and `difficulty` are given, the weight is `importance * difficulty`.
- **difficulty** (numeric) - Optional - 0+ rating; if both `importance` and `difficulty` are given, the weight is `importance * difficulty`.
- **icf_tag** (character) - Optional - ICF code (e.g., `"d450"`) linking the goal to the International Classification of Functioning.

### Return Value
A `"gas_goal"` object.

### Example
```r
defineGoal("Walk 100 m unaided", importance = 3, difficulty = 2,
           icf_tag = "d450")
```

### References
Kiresuk & Sherman (1968); Turner-Stokes (2009).

### See Also
`scoreGAS()`
```

--------------------------------

### ClinicalInstrument()

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/ClinicalInstrument.Rd

Documentation for the ClinicalInstrument constructor function in the physioclinical R package.

```APIDOC
## ClinicalInstrument(id, name, version, items, item_ranges, item_type, subscales, aggregation, direction, strata, item_values, item_recode, source_ref)

### Description
Constructs a ClinicalInstrument object representing a clinical measurement instrument (e.g., a scale or questionnaire).

### Usage
```r
ClinicalInstrument(
  id,
  name = NA_character_,
  version = NA_character_,
  items,
  item_ranges,
  item_type = "interval",
  subscales = list(),
  aggregation = "sum",
  direction = "higher_better",
  strata = list(),
  item_values = list(),
  item_recode = list(),
  source_ref = NA_character_
)
```

### Arguments
- **id** (character) - Required - Instrument identifier.
- **name** (character) - Optional - Instrument name (default: NA).
- **version** (character) - Optional - Instrument version (default: NA).
- **items** (character vector) - Required - Item identifiers.
- **item_ranges** (list) - Required - List of valid ranges for each item.
- **item_type** (character) - Optional - Type of item measurement (default: "interval").
- **subscales** (list) - Optional - Subscale definitions (default: empty list).
- **aggregation** (character) - Optional - Aggregation method (default: "sum").
- **direction** (character) - Optional - Scoring direction (default: "higher_better").
- **strata** (list) - Optional - Stratification definitions (default: empty list).
- **item_values** (list) - Optional - Item value mappings (default: empty list).
- **item_recode** (list) - Optional - Item recoding rules (default: empty list).
- **source_ref** (character) - Optional - Source reference (default: NA).

### Value
A `ClinicalInstrument` object.

### Example
```r
ClinicalInstrument(
  id = "toy", name = "Toy scale", items = c("q1", "q2"),
  item_ranges = list(q1 = c(0, 4), q2 = c(0, 4)))
```

### See Also
- `scoreInstrument()`
- `registerInstrument()`
```

--------------------------------

### Register a normative reference with registerNormative

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/registerNormative.Rd

Creates a GovernedNormativeReference with provenance, consent, license, and governance metadata, then registers it using registerNormative with a temporary root directory. The artifact must pass object validity and validateNormativeManifest.

```r
ref <- GovernedNormativeReference("gs", "gait", "gait_speed",
  provenance = list(source = "x"), consent = list(status = "public"),
  license = list(spdx = "CC0-1.0"),
  governance = list(custodian = "lab", access_level = "open"))
registerNormative(ref, root = tempfile("norm"))
```

--------------------------------

### Score Lawton IADL with all items set to 1

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreLawton.Rd

Example call to scoreLawton using a named vector of eight 1s, with names from the instrument's item list. This produces a total score of 8.

```r
scoreLawton(stats::setNames(rep(1, 8), getInstrument("lawton_iadl")@items))
```

--------------------------------

### applyEquating(equating, values)

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/applyEquating.Rd

Applies a score crosswalk to new values, converting source-scale values to target-scale equivalents. The conversion uses linear interpolation within the crosswalk and clamps to its range.

```APIDOC
## applyEquating(equating, values)

### Description
Apply a score crosswalk to new values. Converts numeric source-scale values to target-scale equivalents using the provided score crosswalk.

### Usage
applyEquating(equating, values)

### Arguments
- **equating** (score_equating) - Required - A score_equating object from equateScores().
- **values** (numeric) - Required - Numeric source-scale values to convert.

### Value
Numeric target-scale equivalents (linearly interpolated within the crosswalk, clamped to its range).

### Examples
```r
set.seed(1)
ability <- rnorm(200)
barthel <- pmin(100, pmax(0, round((ability + 3) * 16 / 5) * 5))
fim <- pmin(126, pmax(18, round(18 + (ability + 3) * 18)))
applyEquating(equateScores(barthel, fim), c(40, 60, 80))
```

### See Also
- equateScores()
```

--------------------------------

### Apply equating crosswalk to new values with applyEquating

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/applyEquating.Rd

Creates simulated Barthel and FIM scores, equates them with equateScores(), then applies the crosswalk to new values c(40, 60, 80). The output is numeric target-scale equivalents, linearly interpolated and clamped to the crosswalk range.

```r
set.seed(1)
ability <- rnorm(200)
barthel <- pmin(100, pmax(0, round((ability + 3) * 16 / 5) * 5))
fim <- pmin(126, pmax(18, round(18 + (ability + 3) * 18)))
applyEquating(equateScores(barthel, fim), c(40, 60, 80))
```

--------------------------------

### Validate a normative reference manifest with validateNormativeManifest

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/validateNormativeManifest.Rd

Creates a GovernedNormativeReference with all required governance fields and validates it. The manifest must include a semantic version and non-empty provenance$source, consent$status, license$spdx, governance$custodian, and governance$access_level; otherwise validation fails with an error naming the missing or invalid fields.

```r
ref <- GovernedNormativeReference("m", "gait", "gait_speed",
  provenance = list(source = "x"), consent = list(status = "public"),
  license = list(spdx = "CC0-1.0"),
  governance = list(custodian = "lab", access_level = "open"))
validateNormativeManifest(ref)
```

--------------------------------

### Tag ICF and get Stroke Core Set with PhysioAnnotationHub

Source: https://github.com/x-biosignal/physioclinical/blob/main/vignettes/clinical-outcomes.Rmd

Tags the Berg Balance Scale with ICF categories and retrieves the Stroke Core Set, showing the first few ICF codes and category titles. Requires the PhysioAnnotationHub package.

```r
PhysioAnnotationHub::tagICF("berg")
head(PhysioAnnotationHub::getCoreSet("Stroke")[, c("icf_code", "category_title")])
```

--------------------------------

### gasSummary(object, ...)

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/gasSummary.Rd

Tabulate a GAS result.

```APIDOC
## gasSummary(object, ...)

### Description
Tabulate a GAS result.

### Usage
```r
gasSummary(object, ...)
```

### Arguments
- **object** (`"gas_result"`) - Required - A `"gas_result"` from `scoreGAS()`.
- **...** - Unused.

### Value
A `data.frame` with one row per goal (description, ICF tag, weight, attained level and its weighted contribution) plus the T-score as an attribute.

### See Also
`scoreGAS()`
```

--------------------------------

### Score FSS with scoreFSS()

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreFSS.Rd

Scores the Fatigue Severity Scale (FSS) by averaging nine item responses (each rated 1-7). A mean of 4 or more indicates clinically significant fatigue. The example uses named responses via setNames with the instrument's item names.

```r
scoreFSS(stats::setNames(c(6, 6, 5, 6, 5, 6, 6, 5, 6),
                         getInstrument("fss")@items))
```

--------------------------------

### Compare measured ROM to reference and contralateral side

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/romNormalcy.Rd

Compare a measured knee flexion of 100 degrees against the packaged reference angle, and optionally against a contralateral value of 130 degrees. The function returns a one-row data.frame with class "rom_normalcy" containing reference_deg, percent_of_normal, deficit_vs_reference, and limited, plus contralateral-related columns when a contralateral value is supplied.

```r
romNormalcy(100, "knee", "flexion")
romNormalcy(100, "knee", "flexion", contralateral = 130)
```

--------------------------------

### Convert a PROMIS summed score to a T-score with promisRawToT()

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/promisRawToT.Rd

Creates a minimal conversion table with raw scores 4 through 8 and their corresponding T-scores, then calls promisRawToT() with a raw score of 6. The function returns a list with tscore and se (NA if the table has no se column), or NA with a warning if the raw score is not in the table.

```r
tab <- data.frame(raw = 4:8, tscore = c(21.5, 30.1, 35.7, 40.2, 44.0))
promisRawToT(6, tab)
```

--------------------------------

### registerInstrument(spec, overwrite = FALSE)

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/registerInstrument.Rd

Registers a clinical instrument in the registry, accepting a ClinicalInstrument object, a spec list, or a YAML file path.

```APIDOC
## registerInstrument(spec, overwrite = FALSE)

### Description
Adds an instrument to the registry, either a ClinicalInstrument object, a parsed-spec list, or the path to a YAML spec file.

### Usage
registerInstrument(spec, overwrite = FALSE)

### Arguments
- **spec** (ClinicalInstrument, list, or character) - Required - A ClinicalInstrument, a spec list, or a path to a .yaml file.
- **overwrite** (logical) - Optional - Replace an existing instrument with the same id? Default FALSE (an existing id is an error).

### Value
Invisibly, the registered ClinicalInstrument.

### Examples
```r
inst <- ClinicalInstrument(id = "toy2", items = c("a", "b"),
  item_ranges = list(a = c(0, 1), b = c(0, 1)))
registerInstrument(inst)
```
```

--------------------------------

### show,ClinicalInstrument-method

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/ClinicalInstrument-class.Rd

Displays a ClinicalInstrument object. This method is part of the S4 class and is called automatically when the object is printed.

```APIDOC
## show(ClinicalInstrument)

### Description
Displays a ClinicalInstrument object.

### Usage
\S4method{show}{ClinicalInstrument}(object)

### Arguments
- **object** (ClinicalInstrument) - Required - A ClinicalInstrument object.

### Details
This method is automatically invoked when the object is printed. It provides a human-readable summary of the instrument specification.

```

--------------------------------

### Define a GAS goal with importance, difficulty, and ICF tag

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/defineGoal.Rd

Creates a goal for walking 100 m unaided with importance 3, difficulty 2, and ICF code d450. The weight is computed as importance * difficulty (6) when both are supplied.

```r
defineGoal("Walk 100 m unaided", importance = 3, difficulty = 2,
           icf_tag = "d450")
```

--------------------------------

### Score Katz Index with named responses

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreKatz.Rd

Scores the Katz Index of Independence in ADL for a named vector of six binary responses (1 = independent, 0 = dependent). The example uses a named vector in the instrument's item order; the total ranges from 0 to 6 and the result is a ClinicalScore with the impairment stratum.

```r
scoreKatz(c(bathing = 1, dressing = 1, toileting = 1,
            transferring = 1, continence = 0, feeding = 1))
```

--------------------------------

### Compute GAS T-score with scoreGAS

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreGAS.Rd

Create two goals with defineGoal and compute the GAS T-score with scoreGAS, passing the goals as a list and attained levels as a numeric vector. The default rho of 0.3 is used.

```r
g1 <- defineGoal("Transfers", importance = 3, difficulty = 2)
g2 <- defineGoal("Stairs", importance = 2, difficulty = 3)
scoreGAS(list(g1, g2), attained_levels = c(1, 0))
```

--------------------------------

### Score PROMIS responses with illustrative calibration

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scorePROMIS.Rd

Creates a calibration data frame with item slopes and thresholds, then calls scorePROMIS with a named response vector. The calibration is illustrative and NOT official PROMIS parameters.

```r
# illustrative calibration (NOT official PROMIS parameters)
cal <- data.frame(item = c("i1", "i2", "i3"), a = c(2.4, 1.9, 2.7),
  b1 = c(-2, -1.5, -1.8), b2 = c(-1, -0.5, -0.7),
  b3 = c(0.2, 0.1, 0), b4 = c(1.4, 1.2, 1.1))
scorePROMIS(c(i1 = 4, i2 = 5, i3 = 4), cal)
```

--------------------------------

### Create GovernedNormativeReference and call normativeZScore

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/normativeZScore.Rd

Creates a GovernedNormativeReference with a stratified model and calls normativeZScore on a value of 1.0 for sex "M". The reference requires provenance, consent, license, and governance metadata, and the model table must contain the strata variable.

```r
ref <- GovernedNormativeReference("gs", "gait", "gait_speed",
  provenance = list(source = "x"), consent = list(status = "public"),
  license = list(spdx = "CC0-1.0"),
  governance = list(custodian = "lab", access_level = "open"),
  strata_vars = "sex",
  model = list(type = "strata",
               table = data.frame(sex = "M", mean = 1.3, sd = 0.2)))
normativeZScore(1.0, ref, list(sex = "M"))
```

--------------------------------

### Score responses with scoreInstrument

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreInstrument.Rd

Creates a toy ClinicalInstrument with three items (q1, q2, q3) each ranging from 0 to 4, then scores a named response vector with scoreInstrument. The default missing-data policy is "error", so all items must be present.

```r
inst <- ClinicalInstrument(
  id = "toy", items = c("q1", "q2", "q3"),
  item_ranges = list(q1 = c(0, 4), q2 = c(0, 4), q3 = c(0, 4)))
scoreInstrument(inst, c(q1 = 2, q2 = 3, q3 = 4))
```

--------------------------------

### Compute normative z-score with normativeZScore()

Source: https://github.com/x-biosignal/physioclinical/blob/main/vignettes/clinical-outcomes.Rmd

Creates a GovernedNormativeReference with illustrative age/sex gait-speed strata and computes a normative z-score for an observed value of 0.83. The reference uses illustrative data for demonstration.

```r
ref <- GovernedNormativeReference(
  "demo_gs", "gait", "gait_speed",
  provenance = list(source = "illustrative vignette data"),
  consent = list(status = "public"), license = list(spdx = "CC0-1.0"),
  governance = list(custodian = "demo", access_level = "open"),
  strata_vars = c("age", "sex"),
  model = list(type = "strata", table = data.frame(
    age = c(60, 60, 70, 70), sex = c("M", "F", "M", "F"),
    mean = c(1.30, 1.24, 1.15, 1.10), sd = c(0.20, 0.18, 0.18, 0.17))))

z <- normativeZScore(0.83, ref, covariates = list(age = 70, sex = "M"))
z[c("z", "percentile", "deviation_flag")]
```

--------------------------------

### summary.responder_classification

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/classifyResponder.Rd

S3 summary method for responder_classification objects.

```APIDOC
## summary(object, ...)

### Description
Summarizes a "responder_classification" object by returning the MDC x MCID contingency table. Counts subjects with missing baseline/followup values.

### Usage
\method{summary}{responder_classification}(object, ...)

### Parameters
- **object** (responder_classification) - Required - The object to summarize.
- **...** - Optional - Unused.

### Return Value
The MDC x MCID contingency table.
```

--------------------------------

### scoreEQ5D5L(items, ...)

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/scoreEQ5D5L.Rd

Documentation for the scoreEQ5D5L function, which computes the EQ-5D-5L level-sum score.

```APIDOC
## scoreEQ5D5L(items, ...)

### Description
Sums the five EQ-5D-5L dimension levels (1 = no problems to 5 = extreme problems / unable) to a level-sum score of 5-25, higher indicating worse health. The utility index requires a country-specific value set and is not computed here; the EQ-VAS (0-100) is a separate rating.

### Usage
```r
scoreEQ5D5L(items, ...)
```

### Arguments
- **items** (numeric) - Named numeric levels (e.g. `mobility = 2`, `pain_discomfort = 3`) or an unnamed vector in the instrument's item order (mobility, self-care, usual activities, pain/discomfort, anxiety/depression).
- **...** - Passed to `scoreInstrument()`.

### Value
A `ClinicalScore` with the level-sum score (5-25).

### Examples
```r
scoreEQ5D5L(c(mobility = 2, self_care = 1, usual_activities = 2,
              pain_discomfort = 3, anxiety_depression = 2))
```

### See Also
- `getInstrument()`
```

--------------------------------

### Round-trip a katz_adl score through toFHIRObservation and fromFHIR

Source: https://github.com/x-biosignal/physioclinical/blob/main/man/fromFHIR.Rd

Creates a ClinicalScore for the katz_adl instrument with all six items set to 1 and subject_id "P01", then converts it to a FHIR Observation and back with fromFHIR, printing the recovered total. The round-trip is lossy for items_used and missing_handling; stratum is re-derived only when the instrument is registered.

```r
sc <- scoreInstrument("katz_adl",
  stats::setNames(rep(1, 6), getInstrument("katz_adl")@items),
  subject_id = "P01")
fromFHIR(toFHIRObservation(sc))@total
```