---
title: "The Language-Based Assessment Model (L-BAM) Library"
vignette: >
  %\VignetteIndexEntry{LBAM}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The L-BAM library comprises information about pre-trained models, including information about where they are located online so that they can be automatically downloaded in R. The models are continuously being tested using GitHub actions, and you can checkout the code for running each model [here](https://github.com/OscarKjell/text/blob/master/tests/testthat/test_2_10_lbam_models.R). The models can be called with `textPredict()`, `textAssess()` or `textClassify()` like this:

```{r textPredict_examples, eval = FALSE, echo=TRUE}
library(text)

# Example calling a model using the URL
textPredict(
  model_info = "valence_facebook_mxbai23_eijsbroek2024",
  texts = "what is the valence of this text?"
)


# Example calling a model having an abbreviation
textClassify(
  model_info = "implicitpower_roberta23_nilsson2024",
  texts = "It looks like they have problems collaborating."
)
```

The text prediction functions can be given a model and a text, and automatically transform the text to word embeddings and produce estimated scores or probabilities.

Important: Language-based assessments can be developed in one context—such as social media—and applied in another—like clinical interviews. However, models don’t always generalize across settings. A model’s performance depends on several factors, including the context in which it was trained, the population, the distribution of the psychological outcome, and the language domain (i.e., how similar the language in the training data is to the new data).

Because of this, users are responsible for evaluating whether a model is appropriate for their specific use case. This means checking whether the training and evaluation conditions align with their own data—and, if needed, validating the model’s performance on a subset of their own data before making any conclusions. That’s why each model in the L-BAM Library comes with detailed documentation on its training data, performance metrics, and development process. Transparent documentation helps users make informed decisions and supports reproducible, trustworthy research (for more information see Nilsson et al., in progress).

If you want to add a pre-trained model to the L-BAM library, please fill out the details in this [Google sheet](https://docs.google.com/spreadsheets/d/1K16JdK7zOmuRktqgaYs5sgaHnkUVwB9v6ERxZdd9iW8/edit#gid=0) and email us (*oscar [ d_o t] kjell [a _ t] psy [DOT] lu [d_o_t]se*) so that we can update the table online.

*Note that you can adjust the width of the columns when scrolling the table.*

```{r models_table, eval = TRUE, echo=FALSE}
library("reactable")
# see vignette: https://glin.github.io/reactable/articles/examples.html#custom-rendering

model_data <- read.csv(system.file("extdata",
                                   "The_L-BAM_Library.csv",
                                   package = "text"),
                       header = TRUE, 
                       skip = 3)

reactable::reactable(
  data = model_data,
  filterable = TRUE,
  defaultPageSize = 20,
  highlight = TRUE, 
  resizable = TRUE,
  theme = reactableTheme(
    borderColor = "#1f7a1f",
  #  stripedColor = "#e6ffe6",
    highlightColor = "#ebfaeb",
    cellPadding = "8px 12px",
    style = list(fontFamily = "-apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif")
  ),
  columns = list(
    Construct_Concept_Behaviours = colDef(minWidth = 280),
    Outcome = colDef(minWidth = 280),
    Language = colDef(minWidth = 280),
    Language_type = colDef(minWidth = 280),
    Level = colDef(minWidth = 280),
    N_training = colDef(minWidth = 280),
    N_evaluation = colDef(minWidth = 280),
    Source = colDef(minWidth = 280),
    Participants_training = colDef(minWidth = 280),
    Participants_evaluation = colDef(minWidth = 280),
    Label_types = colDef(minWidth = 280),
    Language_domain_distribution = colDef(minWidth = 280),
    Open_data = colDef(minWidth = 280),
    Model_type = colDef(minWidth = 280),
    Features = colDef(minWidth = 280),
    Validation_metric1 = colDef(minWidth = 280),
    N_fold_cv_accuracy.1 = colDef(minWidth = 280),
    Held_out_accuracy.1 = colDef(minWidth = 280),
    SEMP_accuracy.1 = colDef(minWidth = 280),
    Other_metrics_n_fold_cv = colDef(minWidth = 280),
    Other_metrics_held_out = colDef(minWidth = 280),
    Other_metrics_SEMP = colDef(minWidth = 280),
    Ethical_approval = colDef(minWidth = 280),
    Ethical_statement = colDef(minWidth = 280),
    Reference = colDef(minWidth = 280),
    Date = colDef(minWidth = 280),
    Contact_details = colDef(minWidth = 280),
    License = colDef(minWidth = 280),
    Study_type = colDef(minWidth = 280),
    Original = colDef(minWidth = 280),
    Miscellaneous = colDef(minWidth = 280),
    Command_info = colDef(minWidth = 800),
    Name = colDef(minWidth = 280),
    Path = colDef(minWidth = 280),
    Model_Type = colDef(minWidth = 280)
  ), 
  showPageSizeOptions = TRUE,
  groupBy = "Construct_Concept_Behaviours"
)
```



### Overview of L-BAM pipelines
Training and using models from the L-BAM library involves three key steps.
First, written language is turned into numerical formats known as word embeddings using a large language model (Figure 1A).
Next, these embeddings are used to build a predictive model linked to a specific outcome or assessment target (Figure 1B).
Finally, the trained model can be applied to new texts for evaluation or classification purposes (Figure 1C).

You can find a detailed guide on how to transform language into embeddings and train L-BAMs using the text package in Kjell et al. (2023).
Below, we briefly introduce the embedding and training process before showing how to apply models from the L-BAM library.
![](l_bam_overview.png){width=500px}

<br>
Figure from Nilsson et al. (in progress). 


### References

Gu, Kjell, Schwartz & Kjell. (2024). Natural Language Response Formats for Assessing Depression and Worry with Large Language Models: A Sequential Evaluation with Model Pre-registration.

Kjell, O. N., Sikström, S., Kjell, K., & Schwartz, H. A. (2022). Natural language analyzed with AI-based transformers predict traditional subjective well-being measures approaching the theoretical upper limits in accuracy. Scientific reports, 12(1), 3918.

Nilsson, Runge, Ganesan, Lövenstierne, Soni & Kjell (2024) Automatic Implicit Motives Codings are at Least as Accurate as Humans’ and 99% Faster
