title: "Example"

output:

rmarkdown::html_vignette:

df_print: kable

vignette: >

```{r, include = FALSE}

```{r setup}

Markr has an example marking project that you can use to learn about the package. Run the following code to create a `r glossary("directory")` called `markr_example` and open the file `demo.Rmd`.

``` r

markr::markr_example()

You can open the file `marks.csv` in Excel, but the code below opens it in R and you can click on the `r glossary("object")` `marks` in the Environment `r glossary("panes", "pane")`. This data table has a column for the student ID, three columns for category marks (KR, CE and AC), a column for the numeric mark, and a column with individual text feedback.

```{r, eval = FALSE}

```{r, echo = FALSE}

Markr has a convenience function for translating between number and letter grades for different purposes, such as numbers for averaging marks and letters for reporting final grades. It defaults to the `glasgow22()` scale, but you can add your own scale.

You will need to create a template `r glossary("R markdown")` file for individual feedback. You can get a demo template using **`New File > R Markdown... > From Template`**.

Each file will have two data objects available to it:

* `marks` (the whole marking spreadsheet)

* `student` (the individual student's data)

In the most typical case, where each student has one row in the spreadsheet, you can reference the student's data in code `r glossary("chunk", "chunks")` or inline R like this:

You can display a table of marks for specific criteria by specifying the column names (`cols`) for each criterion and the order that the categories should go in (`cats`).

You can translate abbreviations used in the marking sheet using `r glossary("list", "lists")` and even change the `symbol` to an emoji.

Once you have your marks and feedback in a table and a template file ready, you can create a feedback document for each student with the `make_feedback()` `r glossary("function")`.

Make sure to set the `filename` to something unique for each student. You can use any columns in the marks table as part of the filename.

```{r, eval = FALSE}

If you have longer blocks of feedback text, the `r glossary("YAML")` style of marking sheet might work better than spreadsheets. It can be a little tricky to get YAML to parse right, but after you've mastered it, it's an efficient way to store your marking feedback text.

You can include all of the columns or just the student ID and feedback, then join this to the spreadsheet table.

```{r, eval = FALSE}

If you have `r glossary("tabular data")` and want to convert it to YAML, use the function `tbl2yaml()`. You can add extra columns (or overwrite existing columns). Add a `filename` to save to file.

```{r, eval = FALSE}

If you just have a list of IDs and want to create a YAML file for feedback, you can set it up without a pre-existing table. Use `"...\n"` to insert a place-holder for multi-line info, such as feedback paragraphs

```{r, eval = FALSE}

<pre><code>

```{r, echo = FALSE, results='asis'}

tbl2yaml(ID = marks$ID, feedback = "...\n", open = FALSE) %>% cat()

```

</code></pre>

You can just use YAML for paragraphs of text and put all other data in a table. Set up the YAML file with corresponding ID columns to join rows.

```{r, eval = FALSE}

You can display a summary plot of the marks in the student feedback or for your own purposes.

```{r mark-dist-plot-1, fig.alt="Bar plot of the mark distribution. The N's for the scores 0-5 are 0=0, 1=1, 2=1, 3=1, 4=2, 5=0"}

Here we've made a new `marks` table with 100 students. Each student answered one of three questions, indicated by the `questions` column.

```{r, echo = FALSE}

You can plot the letter grade by question using the following code. To get the letters to display in the right order, we set the `scale` `r glossary("argument")` to the categories in the order we want to show them. The Glasgow 22-point scale has 4 categories we don't want to show on this plot, so you can quickly get the values we do want using the code `glasgow22()$letters[5:26]`, or you can manually create a `r glossary("vector")` with the scale order like `c("G2", "G1", "F3", ..., "A1")`.

```{r mark-dist-by-q-plot, fig.alt="Plot of the mark distribution separated by question"}

This marking table has three columns that show individual marking criteria: `KR`, `CE` and `AC`, so we could also make a plot of the individual criteria by question. This function uses the `cols` and `cats` lists we made above to translate the abbreviations in the marking table to the full terms in the plot.

```{r cat-dist-plot, fig.alt="Plot of the distribution of the individual criteria for each question."}

The default category plots are stacked bar plots.

Set `xaxis = "cat"` to display the categories across the x-axis instead. The output is a ggplot object, so you can add further ggplot functions to customise your plots.

```{r cat-dist-x-plot, message = FALSE, warning = FALSE, fig.alt="Plot of the distribution of the individual criteria for each question with a red, ornage and yellow colour scheme."}

```{r, echo = FALSE}