# /******************************************************************
# Scale ID:           FES-I
# Scale Name:         Falls Efficacy Scale
# TILDA Variables:    FESIscore
# Dataset:            TILDA Wave 2,3,6
# Author:
# Institution:        The Irish Longitudinal Study on Ageing (TILDA)
#
# Description:
# Generates score for the Falls Efficacy Scale.
#
# Version:      1.0
# Date:         2026-09-01
# Language:     R
# ******************************************************************/
#
# Assumption: the working data frame is called `data`.


# ---------------------------------------------------------------
# 1. Create scored copies of the 16 FES-I items
# ---------------------------------------------------------------

fesi_source <- paste0("SCQFalls", 1:16)
fesi_items  <- paste0("FESI", 1:16)

data[fesi_items] <- data[fesi_source]


# ---------------------------------------------------------------
# 2. Recode TILDA special missing values
# ---------------------------------------------------------------

special_missing <- c(-99, -812, -823, -834)

for (v in fesi_items) {
  data[[v]][data[[v]] %in% special_missing] <- NA_real_
}


# ---------------------------------------------------------------
# 3. Restrict items to valid FES-I responses
#    1 = Not at all concerned
#    2 = Somewhat concerned
#    3 = Fairly concerned
#    4 = Very concerned
# ---------------------------------------------------------------

for (v in fesi_items) {
  data[[v]][!is.na(data[[v]]) &
            !(data[[v]] >= 1 & data[[v]] <= 4)] <- NA_real_
}


# ---------------------------------------------------------------
# 4. Count valid items and calculate observed sum
# ---------------------------------------------------------------

data$FESI_nvalid <- rowSums(!is.na(data[fesi_items]))

data$FESI_sum <- rowSums(data[fesi_items], na.rm = TRUE)


# ---------------------------------------------------------------
# 5. Calculate official FES-I total score
# ---------------------------------------------------------------

data$FESIscore <- NA_real_


# All 16 items completed
complete <- data$FESI_nvalid == 16

data$FESIscore[complete] <- data$FESI_sum[complete]


# 1-4 items missing:
# prorate according to official FES-I instructions
prorate <- data$FESI_nvalid >= 12 & data$FESI_nvalid <= 15

data$FESIscore[prorate] <- ceiling(
  (data$FESI_sum[prorate] / data$FESI_nvalid[prorate]) * 16
)


# 5 or more items missing:
# score remains missing
data$FESIscore[data$FESI_nvalid < 12] <- NA_real_


# ---------------------------------------------------------------
# 6. Labels / notes
# ---------------------------------------------------------------

attr(data$FESIscore, "label") <-
  "Falls Efficacy Scale - International total score (16-64)"

attr(data$FESIscore, "note") <-
  paste(
    "Higher scores indicate greater concern about falling.",
    "If <=4 items are missing, the completed-item mean is multiplied",
    "by 16 and rounded upward; >=5 missing items results in a missing score."
  )


# ---------------------------------------------------------------
# 7. Checks
# ---------------------------------------------------------------

summary(data$FESIscore)

table(data$FESI_nvalid, useNA = "ifany")

stopifnot(
  all(
    is.na(data$FESIscore) |
      (data$FESIscore >= 16 & data$FESIscore <= 64)
  )
)


# ---------------------------------------------------------------
# 8. Drop temporary scoring variables if not required
# ---------------------------------------------------------------

data[fesi_items] <- NULL
data$FESI_nvalid <- NULL
data$FESI_sum <- NULL