Skip to contents

Neurofilament light chain (NfL) marker

Source: vignettes/articles/nfl_marker.Rmd
nfl_marker.Rmd

Scope

Incorporate a neurofilament light chain (NfL) concentration measurement into the analysis pipeline. NfL is a biomarker of neuroaxonal injury; elevated plasma or CSF levels indicate neurodegeneration and typically increase with age and neurological disease. This function validates and passes through the input values (assumed plasma pg/mL) with optional NA handling and extreme-value scanning, returning a tidy tibble ready for downstream analysis.

Load packages and demo data 

library(HealthMarkers)
library(tibble)

df <- tibble::tibble(
  NfL = c(8.5, 14.2, 22.1, NA, 35.0)
)

Column map

The only required key is nfl.

cm <- list(nfl = "NfL")

Core calculation 

out <- nfl_marker(
  data = df,
  col_map = cm,
  na_action = "keep",
  check_extreme = FALSE,
  verbose = FALSE
)

out
#> # A tibble: 5 × 1
#>   nfl_value
#>       <dbl>
#> 1       8.5
#> 2      14.2
#> 3      22.1
#> 4      NA  
#> 5      35

Missing data handling

na_action = "keep" preserves rows with NA outputs; omit drops rows with missing required inputs; error aborts if any required input is missing; warn keeps rows but emits a warning.

df_na <- tibble::tibble(NfL = c(8.5, NA, 22.1))

keep_out <- nfl_marker(df_na, cm, na_action = "keep")
omit_out <- nfl_marker(df_na, cm, na_action = "omit")

list(keep_rows = nrow(keep_out), omit_rows = nrow(omit_out))
#> $keep_rows
#> [1] 3
#> 
#> $omit_rows
#> [1] 2

Extreme-value handling

check_extreme = TRUE scans values against a broad default range of [0, 1e6] pg/mL.
extreme_action controls the response: "warn" emits a warning without altering values, "cap" clips to the range boundary, "NA" blanks flagged values, "error" aborts.

df_ext <- tibble::tibble(NfL = c(8.5, -5, 22.1))  # negative value is out of range

nfl_marker(
  data = df_ext,
  col_map = cm,
  check_extreme = TRUE,
  extreme_action = "warn"
)
#> Warning: nfl_marker(): negative NfL values detected; check input data.
#> Warning: nfl_marker(): detected 1 extreme input values (not altered).
#> # A tibble: 3 × 1
#>   nfl_value
#>       <dbl>
#> 1       8.5
#> 2      -5  
#> 3      22.1

Custom range override:

nfl_marker(
  data = tibble::tibble(NfL = c(8.5, 5000, 22.1)),
  col_map = cm,
  check_extreme = TRUE,
  extreme_action = "cap",
  extreme_rules = list(nfl = c(0, 1000))
)
#> # A tibble: 3 × 1
#>   nfl_value
#>       <dbl>
#> 1       8.5
#> 2    1000  
#> 3      22.1

Verbose diagnostics

Set verbose = TRUE (and healthmarkers.verbose = "inform") to surface three structured messages on each call: preparing inputs, the column map, and a results summary.

old_opt <- options(healthmarkers.verbose = "inform")
nfl_marker(tibble::tibble(NfL = c(8.5, 14.2, 22.1)), cm, verbose = TRUE)
#> nfl_marker(): preparing inputs
#> nfl_marker(): column map: nfl -> 'NfL'
#> nfl_marker(): results: nfl_value 3/3
#> # A tibble: 3 × 1
#>   nfl_value
#>       <dbl>
#> 1       8.5
#> 2      14.2
#> 3      22.1
options(old_opt)

Tips

  • Units are preserved as-is; ensure all values are in the same unit (e.g., pg/mL) before calling.
  • Age-adjusted reference ranges are not applied by this function; use downstream tools or stratified z-scores for age normalisation.
  • For batch processing with imputed datasets, combine with impute_missing() upstream to handle systematic missingness before running nfl_marker().