---
title: "synr: Quick start"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{synr: Quick start}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width=6, 
  fig.height=5
)
```

```{r setup}
library(synr)
```
This is the 'quick start' guide to synr. For an in-depth tutorial, please see the [main tutorial](synr-tutorial.html).

## Rolling up the data
If you have long format data (otherwise see [Creating ParticipantGroup objects](synr-creategroup.html)):

```{r roll_up_data}
pg <- create_participantgroup(
  raw_df=synr_exampledf_long_small,
  n_trials_per_grapheme=2,
  id_col_name="participant_id",
  symbol_col_name="trial_symbol",
  color_col_name="response_color",
  time_col_name="response_time", # optional, not necessary for core functionality
  color_space_spec="Luv"
)
```
The resulting object (`pg`) is a nested structure implemented with [reference classes](http://adv-r.had.co.nz/OO-essentials.html#rc). With this, you can call various methods and access various attributes. Examples of common use cases are included below.

## Calculate participant consistency scores
Consistency scores for all participants, looking only at trials involving letters.
```{r calc_cons_scores}
cons_scores_letters <- pg$get_mean_consistency_scores(symbol_filter=LETTERS)
print(cons_scores_letters)
```

## Produce a plot of a single participant's responses
Plot of single participant's per-grapheme consistency scores, looking only at trials involving the graphemes 'A' and '7'.
```{r get_single_plot}
pg$participants[['1']]$get_plot(symbol_filter=c('A', '7'))
```

## Export relevant participant data to a data frame
``` {r summary_df}
# get mean consistency scores for all participants, filtering first by letters, then digits
mean_cscores_letters <- pg$get_mean_consistency_scores(symbol_filter=LETTERS)
mean_cscores_digits <- pg$get_mean_consistency_scores(symbol_filter=0:9)

# get number of graphemes where all response colors were non-missing, 
# filtering first by letters, then digits
# (in the example data frame, all participants have all-valid responses)
num_valid_letters <- pg$get_numbers_all_colored_graphemes(symbol_filter=LETTERS)
num_valid_digits <- pg$get_numbers_all_colored_graphemes(symbol_filter=0:9)

p_ids <- pg$get_ids()

mean_scores_df <- data.frame(
  participant_id=p_ids, 
  cscore_letters=mean_cscores_letters,
  cscore_digits=mean_cscores_digits,
  num_valid_letters=num_valid_letters,
  num_valid_digits=num_valid_digits
)
print(mean_scores_df)
```

## Finding more information
Apart from the aforementioned vignettes, you can find help documentation for fields/attributes and methods of involved objects by running `help(ParticipantGroup)`, `help(Participant)` or `help(Grapheme)`.