Package 'nlcs'

Compute N-LCS CDM and CDA Metrics

Description

Computes cognitive deviation magnitude (CDM) and cognitive deviation angle (CDA) relative to a fitted healthy-control reference model.

Usage

compute_nlcs_metrics(nlcs_result, data_z, ids = NULL)

Arguments

nlcs_result	An object of class nlcs_result returned by fit_nlcs.
data_z	A complete, finite numeric matrix or data frame standardized using the same healthy-control reference as the model. Rows are subjects. Columns must have the model's test names and are reordered to model order.
ids	An optional vector of subject identifiers, with one identifier per row of data_z.

Value

A data.frame with one row per input subject, in input row order, containing:

id

Subject identifiers, included only when ids is supplied.

CDM

A numeric cognitive deviation measure. When CDM_type is "axis_projection", this is the signed projection of the healthy-control-centered, whitened score vector onto the fitted unit axis. Its sign follows the orientation of the fitted loadings. When CDM_type is "whitened_magnitude", it is the nonnegative Euclidean length of that vector, representing distance from the healthy-control center in healthy-control covariance-standardized coordinates.

CDA_raw

The numeric angle in degrees, between 0 and 180, from the whitened score vector to the fitted axis. Smaller angles indicate closer directional alignment. The angle is NA when the whitened score vector has zero length.

CDA

Numeric CDA_raw minus the median raw healthy-control angle stored in the model. Positive values indicate angles above the healthy-control median; negative values indicate angles below it. Undefined raw angles remain NA.

CDM_type

A character column containing "axis_projection" or "whitened_magnitude", as determined by the model.

Examples

set.seed(42)
ability <- rnorm(100)
hc <- sapply(seq_len(4), function(j) {
  ability + rnorm(100, sd = 0.4)
})
colnames(hc) <- paste0("test", seq_len(4))

new <- hc[1:3, , drop = FALSE] - 0.5
std <- standardize_normative(hc, new)

# Few iterations keep the example fast; use the default for analysis.
model <- fit_nlcs(std$hc_z, parallel_iter = 10L)

scores <- compute_nlcs_metrics(
  model,
  std$new_z,
  ids = c("A", "B", "C")
)
scores

---

Construct a Normative Latent Cognitive Structure

Description

Fits a one-factor normative latent cognitive structure (N-LCS) when both parallel analysis and the original MAP procedure recommend one factor.

Usage

fit_nlcs(hc_z, parallel_iter = 1000L, loading_tolerance = 1e-8)

Arguments

hc_z	A complete, finite numeric matrix or data frame of healthy-control scores standardized using standardize_normative. Rows are subjects and columns are named cognitive tests.
parallel_iter	Number of parallel-analysis iterations.
loading_tolerance	Absolute loading threshold below which loadings are treated as zero when selecting the cognitive deviation magnitude (CDM) definition.

Details

Parallel analysis uses random simulations. Use set.seed() for reproducibility. Factor-retention recommendations are reported as messages.

Value

A named list of class nlcs_result containing:

variables

A character vector of test names in model order.

hc_z_mean

A named numeric vector of healthy-control means in standardized units.

covariance

The numeric healthy-control sample covariance matrix.

whitening_matrix

The numeric symmetric inverse square root of the healthy-control covariance matrix. This transforms centered scores into healthy-control covariance-standardized coordinates.

fa

The one-factor fit returned by psych::fa(), with classes psych and fa.

loadings

A named numeric vector of one-factor loadings.

latent_axis_whitened

A named numeric unit vector defining the fitted latent axis in whitened space. Its orientation follows the fitted loadings.

parallel_analysis

The full parallel-analysis result from psych::fa.parallel(), with classes psych and parallel.

map

The full MAP result from EFAtools::N_FACTORS(), with classes efa_retain and N_FACTORS.

retention

A list containing integer factor counts parallel_analysis and map_tr2. Both equal one in a successfully returned model.

loading_tolerance

The numeric loading threshold used to classify loading signs.

cdm_type

A character string: "axis_projection" when all nonzero loadings have the same sign, or "whitened_magnitude" when they have mixed signs.

cda_reference_median

The numeric median raw healthy-control cognitive deviation angle in degrees, excluding undefined angles. This is subtracted when computing adjusted CDA.

The model defines the healthy-control reference geometry used by compute_nlcs_metrics. An error is raised if either retention procedure does not recommend one factor.

Examples

set.seed(42)
ability <- rnorm(100)
hc <- sapply(seq_len(4), function(j) {
  ability + rnorm(100, sd = 0.4)
})
colnames(hc) <- paste0("test", seq_len(4))
std <- standardize_normative(hc)

# Few iterations keep the example fast; use the default for analysis.
model <- fit_nlcs(std$hc_z, parallel_iter = 10L)
model$loadings
model$retention

---

Print a Fitted Normative Latent Cognitive Structure

Description

Prints the number of cognitive tests, factor-retention results, and the cognitive deviation magnitude (CDM) definition.

Usage

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

Arguments

x	An object of class nlcs_result returned by fit_nlcs.
...	Additional arguments, currently unused.

Value

The input x, a named list of class nlcs_result, returned invisibly and unchanged. Its components describe the fitted healthy-control reference model and are documented in fit_nlcs.

The function is called for the side effect of printing a concise model summary to the console.

Examples

set.seed(42)
ability <- rnorm(100)
hc <- sapply(seq_len(4), function(j) {
  ability + rnorm(100, sd = 0.4)
})
colnames(hc) <- paste0("test", seq_len(4))
std <- standardize_normative(hc)

# Few iterations keep the example fast; use the default for analysis.
model <- fit_nlcs(std$hc_z, parallel_iter = 10L)
print(model)

---

Standardize Cognitive Tests to Healthy Controls

Description

Uses healthy-control means and sample standard deviations as the normative reference for both healthy controls and new subjects.

Usage

standardize_normative(hc_data, new_data = NULL)

Arguments

hc_data	A complete, finite numeric matrix or data frame. Rows are healthy controls and columns are cognitive tests. Column names are required. At least two healthy controls are required, and each test must have a nonzero sample standard deviation.
new_data	An optional complete, finite numeric matrix or data frame for new subjects, with the same test names as hc_data. Columns are reordered to match the healthy-control reference.

Details

Data cleaning, test selection, missing-data handling, and direction recoding must be completed before using this function.

Value

A named list of class nlcs_standardization containing:

hc_z

A numeric matrix of standardized healthy-control scores, with the same dimensions and column names as hc_data.

new_z

A numeric matrix of standardized new-subject scores, with columns in healthy-control order, or NULL if new_data is omitted.

means

A named numeric vector of healthy-control test means.

sds

A named numeric vector of healthy-control sample standard deviations.

variables

A character vector of test names in healthy-control column order.

Each standardized score is the original score minus the healthy-control mean, divided by the healthy-control sample standard deviation. Positive values are above the healthy-control mean and negative values are below it. Whether higher scores indicate better performance depends on the original test coding.

Examples

hc <- cbind(
  test1 = c(8, 10, 12, 14, 16),
  test2 = c(3, 5, 4, 7, 6)
)
new <- cbind(test1 = c(9, 13), test2 = c(4, 6))

std <- standardize_normative(hc, new)
std$hc_z
std$new_z
std$means
std$sds

---