dscore 2.0.0 with default key fails to calculate a D-score

[stefvanbuuren]

@jmseiden wrote:

I wanted to make you aware of a minor bug in the latest release of the dscore package. When scoring SF data, currently leaving the key as NULL results in all scores reported as NA. I am not sure why this is, as it should take the gsed2406 key when key is set to NULL. If the key is specified, the SF data scores fine.

Interestingly, the LF data does not have this same issue, and scores correctly with or without the key being specified.

Below is a reproducible example:

library(dscore)
packageVersion("dscore")
#> [1] '2.0.0'

df <- data.frame(
  AGE = 0.2,
  # Short Form item names
  gpalac001 = 1,
  gpacgc002 = 0,
  gpafmc003 = 1,
  gpasec004 = 1,
  gpamoc005 = 0,
  # Long Form item names
  gl1gmd001 = 1,
  gl1gmd002 = 0,
  gl1gmd003 = 1,
  gl1gmd004 = 1,
  gl1gmd005 = 0
)

get_itemnames(instrument = "gl1", order = "idnm", domain = "gm")
#>  [1] "gl1gmd001" "gl1gmd002" "gl1gmd003" "gl1gmd004" "gl1gmd005" "gl1gmd006"
#>  [7] "gl1gmd007" "gl1gmd008" "gl1gmd009" "gl1gmd010" "gl1gmd011" "gl1gmd012"
#> [13] "gl1gmd013" "gl1gmd014" "gl1gmd015" "gl1gmd016" "gl1gmd017" "gl1gmd018"
#> [19] "gl1gmd019" "gl1gmd020" "gl1gmd021" "gl1gmd022" "gl1gmd023" "gl1gmd024"
#> [25] "gl1gmd025" "gl1gmd026" "gl1gmd027" "gl1gmd028" "gl1gmd029" "gl1gmd030"
#> [31] "gl1gmd031" "gl1gmd032" "gl1gmd033" "gl1gmd034" "gl1gmd035" "gl1gmd036"
#> [37] "gl1gmd037" "gl1gmd038" "gl1gmd039" "gl1gmd040" "gl1gmd041" "gl1gmd042"
#> [43] "gl1gmd043" "gl1gmd044" "gl1gmd045" "gl1gmd046" "gl1gmd047" "gl1gmd048"
#> [49] "gl1gmd049"

# SF scores correctly when specifying key
dscore(df,
       items = c("gpalac001", "gpacgc002", "gpafmc003", "gpasec004", "gpamoc005"),
       xname = "AGE",
       key = "gsed2406",
       xunit = "decimal")
#>     a n   p     d      sem    daz
#> 1 0.2 5 0.6 13.47 3.687342 -1.954

# Reports NA score when no key specified
dscore(df,
       items = c("gpalac001", "gpacgc002", "gpafmc003", "gpasec004", "gpamoc005"),
       xname = "AGE",
       xunit = "decimal")
#>     a n  p  d sem daz
#> 1 0.2 0 NA NA  NA  NA

# LF scores correctly without key specified
dscore(df,
       items = c("gl1gmd001", "gl1gmd002", "gl1gmd003", "gl1gmd004", "gl1gmd005"),
       xname = "AGE",
       xunit = "decimal")
#>     a n   p     d      sem    daz
#> 1 0.2 5 0.6 19.59 3.334029 -0.262

^{Created on 2025-10-07 with reprex v2.1.1}

[stefvanbuuren]

Thanks a lot. It is expected behaviour, but I understand the confusion.

Advice

Use gs1 instead of gpa.

Problem cause

The root cause is that instrument code gpa is not part of the gsed2510 key. Currently, dscore 2.0.0 only supports the gs1 (GSED SF) and gl1 (GSED LF) instrument codes. See the overview table https://d-score.org/dscore/articles/getting_started.html#is-your-measurement-instrument-covered. Note that instruments gpa (old GSED SF) and gto (old GSED LF) are not part anymore of this table. I did not explicitly mention in the NEWS, but gpa and gto are soft deprecated, and will not be supported into in future keys.

Your example mixes gpa and gl1. It finds valid estimates for gl1, but not for gpa. Hence, no D-score can be calculated for gpa items. If you change gpa into gs1 items, then your example should work.

The existence of gpa and gs1 to refer to the same instrument is confusing but has historic reasons. The older gpa items refer to the version of GSED SF that was used to collect data during Phase 1 of the validation study (before 2023), whereas gs1 assumes the GSED SF version published in 2023 by WHO. The number of items is the same (139) but their order differs. In order to ease the use of the published version, I created the instrument code gs1 to reflect to new order.

Solutions

The preferred solution is to translate the gpa names into gs1 names. gpa is part of the gsed2 lexicon. gs1 is part of the gsed3 lexicon. We can use the function rename_vector() to translate gpa items into gs1 items. The advantage of this option is that replaces any gpa codes by gs1 codes, which will stay.

As you suggested, another option is to use the former key gsed2406. There are two ways of doing that:

• Install version dscore 1.11.0 from CRAN to run existing code. This will automatically pick gsed2406.
• Add a key argument to the call to dscore(..., key = "gsed2406").

Both ways are meant to remain compatible with existing code, but neither is future-proof.

The example below shows how to implement these solutions.

library("dscore")
packageVersion("dscore")
#> [1] '2.0.0'

df <- data.frame(
  AGE = 0.2,
  # Short Form item names
  gpalac001 = 1,
  gpacgc002 = 0,
  gpafmc003 = 1,
  gpasec004 = 1,
  gpamoc005 = 0,
  # Long Form item names
  gl1gmd001 = 1,
  gl1gmd002 = 0,
  gl1gmd003 = 1,
  gl1gmd004 = 1,
  gl1gmd005 = 0
)

# Show lexicons gsed2 and gsed3 for SF
translate <- builtin_translate |> 
  dplyr::filter(instrument == "SF") |> 
  dplyr::select(gsed2, gsed3, label) |>
  dplyr::mutate(label = substr(label, 1, 40))
head(translate)
#>       gsed2     gsed3                                    label
#> 1 gpasec004 gs1sec001             SF001 Does your child smile?
#> 2 gpamoc006 gs1moc002 SF002 When lying on his/her back, does y
#> 3 gpasec015 gs1sec003 SF003 Does your child look at your face 
#> 4 gpalac001 gs1lgc004 SF004 Does your child cry when he/she is
#> 5 gpafmc003 gs1moc005 SF005 Does your child grasp your finger 
#> 6 gpacgc002 gs1cgc006 SF006 Does your child look at and focus

# Option 1 (recommended): ---> Rename items into gsed3 lexicon
names_old <- colnames(df)
names_new <- rename_vector(names_old, lexin = "gsed2")
cbind(names_old, names_new)
#>       names_old   names_new  
#>  [1,] "AGE"       "age"      
#>  [2,] "gpalac001" "gs1lgc004"
#>  [3,] "gpacgc002" "gs1cgc006"
#>  [4,] "gpafmc003" "gs1moc005"
#>  [5,] "gpasec004" "gs1sec001"
#>  [6,] "gpamoc005" "gs1moc008"
#>  [7,] "gl1gmd001" "gl1gmd001"
#>  [8,] "gl1gmd002" "gl1gmd002"
#>  [9,] "gl1gmd003" "gl1gmd003"
#> [10,] "gl1gmd004" "gl1gmd004"
#> [11,] "gl1gmd005" "gl1gmd005"

# use the gsed3 lexicon names
df2 <- df
names(df2) <- names_new
items <- get_itemnames(names(df2), ins = "gs1")
get_tau(items)  # using default key: gsed2510
#> gs1cgc006 gs1lgc004 gs1moc005 gs1moc008 gs1sec001 
#>      7.94        NA      5.33      7.78      2.56
dscore(df2,
       items = items,
       xname = "age",
       xunit = "decimal",
       verbose = TRUE)
#> key:         gsed2510 
#> population:  preliminary_standards 
#> transform:   55.72413 3.603965 
#> qp range:    -10 125 
#> algorithm:   current
#>     a n   p     d      sem    daz
#> 1 0.2 4 0.5 12.35 3.574215 -2.213

# Option 2: ---> Specify key that supports gpa-instrument code
items <- get_itemnames(names(df), ins = "gpa")
get_tau(items)  # using default key: gsed2510. No support for gpa-instrument
#> gpacgc002 gpafmc003 gpalac001 gpamoc005 gpasec004 
#>        NA        NA        NA        NA        NA
get_tau(items, key = "gsed2406")  # using old key
#> gpacgc002 gpafmc003 gpalac001 gpamoc005 gpasec004 
#>      6.90      5.77      4.57      8.14      1.10
dscore(df,
       items = c("gpalac001", "gpacgc002", "gpafmc003", "gpasec004", "gpamoc005"),
       xname = "AGE",
       xunit = "decimal",
       key = "gsed2406")
#>     a n   p     d      sem    daz
#> 1 0.2 5 0.6 13.47 3.687342 -1.954

^{Created on 2025-10-08 with reprex v2.1.1}