---
title: "doc2concrete"
subtitle: "Concreteness in Natural Language"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{doc2concrete}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r echo=FALSE}
knitr::opts_chunk$set(comment = NA, message = FALSE, warning = FALSE)
```


# Concreteness

Concreteness has long been central to psychological theories of learning and thinking, and increasingly has practical applications to domains with prevalent natural language data, like advice and plan-making. However, the literature provides diffuse and competing definitions of concreteness in natural language. In this package, we codify simple guidelines for automated concreteness detection within and across domains, developed from a review of existing methods in the literature.

## Installation

You can install the doc2concrete package directly, like so:

```{r gh-installation, eval = FALSE}
install.packages("doc2concrete")
```

## Usage

 Here, we provide a single function, `doc2concrete`, that maps operationalize models of document-level concreteness based on a survey of datasets in several domains, including advice. This package is built as an accompaniment to Yeomans (2021), which reviews existing linguistic concreteness models across several domains. This function conducts two kinds of analyses, which can be selected using the `domain` argument. 

### Domain-Specific Pre-Trained Concreteness Model

First, we provide pre-trained models specifically tuned to measure concreteness in two open-ended goal pursuit domains - advice and plan-making. These were developed using supervised machine learning tools, and robustly outperform other domain-specific models. We trained the advice model across a range of datasets from lab and field settings (9 studies, 4,608 participants), and we trained the plan-making model from plans students wrote at the beginning of online classes (7 classes, 5,172 students). Our package implements the best- performing supervised  models - the LASSO model with bag-of-ngrams and dictionary features - to calculate concreteness in a new set of in-domain texts.

### Domain-General Concreteness Dictionary

Although it is not ideal, researchers may have to rely on a domain-general model if they are in an unfamiliar domain, or conducting exploratory work. In this case, our results suggest that the mTurk dictionary provides the most robust measure of concreteness across the domains we tested here (Brysbeart et al., 2014). We also found substantial variation in concreteness within and across domains, however we provide this open-domain model as a scaleable starting point for researchers interested in other domains. However, we highly recommend that researchers conduct deeper work to better understand their own domain-specific model of concreteness.

We offer a document-level implementation of the original Brysbaert dictionary, with some adjustments to the standard protocol. Previous practice commonly excluded documents with insufficient word counts, and produced skewed distributions (i.e. short documents had much higher variance). Instead, our package suggests smoothing, which calculates a weighted combination of each document's raw score and the group average, with the weight proportional to document length. This smoothing somewhat improved the accuracy of the model for concreteness in advice, and in plan-making. We suspect there may be other gains from fine-tuning the standard dictionary approach (for example, varying the weights on words) that should be explored in future research. 

```{r eval=TRUE}


library(doc2concrete)

doc2concrete(c("I am concrete","I am abstract"),
             domain="open")

doc2concrete(c("this is a brown rock.","this is a vague idea."),
             domain="open")

```

## Data: feedback_dat

We have included an example dataset, `feedback_dat`, for researchers to get a handle on the workflow. These data were collected from Mechanical Turk workers, who were asked to think of a person in their life to whom they could give feedback on a recent task. Then, they were asked to write what feedback they would provide (Blunden, Green & Gino, 2018). The written feedback was shown to 5-6 raters (also mTurkers) who evaluated the specificity of the feedback, and the average of these raters is offered as a ground truth measure of concreteness.

```{r, eval=TRUE}

data("feedback_dat")

cor.test(doc2concrete(feedback_dat$feedback,domain="open"),
    feedback_dat$concrete)

cor.test(doc2concrete(feedback_dat$feedback,domain="advice"),
         feedback_dat$concrete)


doc2concrete(c("Be more concrete","Be more abstract"),
             domain="advice")

doc2concrete(c("Act like a brown rock.","Act like a vague idea."),
             domain="advice")

```

## Conclusion

That's it! Enjoy! And please reach out to us with any questions, concerns, bug reports, use cases, comments, or fun facts you might have.

## References

Brysbaert, M., Warriner, A. B., & Kuperman, V. (2014). Concreteness ratings for 40 thousand generally known English word lemmas. Behavior Research Methods, 46(3), 904-911.

Blunden, H., Green, P., & Gino, F. (2018). The Impersonal Touch: Improving Feedback- Giving with Interpersonal Distance. Academy of Management Proceedings, 2018(1).

Yeomans, M. (2021). A concrete example of construct construction in natural language. Organizational Behavior and Human Decision Processes, 162, 81-94.
