---
title: "A student's introduction to markmyassignment"
author: "Mans Magnusson and Oscar Pettersson"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{markmyassignment}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

The `markmyassignment` package is a tool to easily get automatic feedback on your lab assignment before handing it in.

### Installing the package

The easiest way to install the package in R is as follows:

```{r, message=FALSE, eval=FALSE}
install.packages("markmyassignment")
```

### How to get help

All documentation of the package and the functionality can be found using:

```{r, message=FALSE, eval=FALSE}
help(package = "markmyassignment")
```

You can also get troubleshooting or answers to common questions [here](https://github.com/MansMeg/markmyassignment/blob/master/FAQ.md). Please add your own questions and solutions if you have any!

### Usage

To use the package markmyassignment, you must first load it into your R session:

```{r, message=FALSE}
library(markmyassignment)
```

Then, use ```set_assignment()``` with the path provided by the teacher. Below you will find an example assignment that is part of the ```markmyassignment``` package. The assignment path of this example assignment depends on the local R installation.

```{r, message=TRUE}
assignment_path <- 
 file.path(system.file(package = "markmyassignment"), "extdata", "example_assignment01.yml")
set_assignment(assignment_path)
```

Let us look at the tasks included in our example assignment. To check which task that is included we use the function ```show_tasks()```.

```{r}
show_tasks()
```

In this example assignment, there are two tasks and also a mandatory requirement.

**Mandatory requirement: **

*Store your name in the variable* ```my_name```*.*

**task1:**

*Create a vector containing the values of $\pi$ and e. The name of the vector should be* ```task1```*.*

**task2:**

*Create a function that takes a numeric vector as the argument and returns the sum of the first and last element. Name the function* ```task2```*.*

We start to solve this assignment by solving the first task.

```{r}
task1 <- c(pi, exp(1))
print(task1)
```

It seems to work as intended.

We now try to correct our lab assignment using ```markmyassignment```:

```{r}
mark_my_assignment()
```

That did not work very well. This is how it looks when something goes wrong when the `markmyassignment` package is used. It looks very daunting in this vignette, but using the function in R will result in less output.

The first part of the message contains the names of the tests that are run and the number of OK, F(ailures) and W(arnings). You do not want any Failures and Warnings may be something wrong and should be checked.

The easiest way to go through the error messages is to start in a chronological order. Start with the first error (error number 1) and correct this error and then run the ```mark_my_assignment()``` function again. Let's look at the first error message:

```
test-2-1.R:6: failure: Marking task2
exists("task2") isn't true.
task2() does not exist.
```

The problem is that we tried to mark the second task, but we have not yet tried to solve this part of the assignment. Let us correct only the first task, using the ```tasks``` argument in ```mark_my_assignment()```:

```{r}
mark_my_assignment(tasks = "task1")
```

That worked better! But we still get an error:

```
test-mandatory-1.R:6: failure: Mandatory tests
exists("my_name") isn't true.
Variable my_name is missing
```

We forgot to add the mandatory name. Let's do that now:

```{r}
my_name <- "SkyNet"
```

Now it worked out! We have solved the first task. Let us try to solve the second task.

```{r}
task2 <- function(vector){
  vector[1] + vector[5]
}
task2(1:5)
```

It seems to work well at a first glance. Let us see what markmyassignment says.

```{r}
mark_my_assignment(tasks = "task2")
```

Oh! There seems to be an error in our function? Ah, the problem seems to be that we assumed a fixed length vector argument. Let us correct that and check our task again.

```{r}
task2 <- function(vector){
  vector[1] + vector[length(vector)]
}
mark_my_assignment(tasks = "task2")
```

We succeeded this time! Now all tasks are completed and we can now use ```mark_my_assignment()``` to correct the whole lab assignment. Note that ```my_name```, ```task1``` and ```task2``` need to exist in the global environment. To check this, we can use ```ls()```.

```{r}
ls()
mark_my_assignment()
```

Yay! We have completed the whole lab assignment!

If we save our file now, we could even clean the global environment and run the tests on the assignment file we will turn in. This is also what the teacher will do when correcting the labs (but probably with some extra tests). We need both the file path to our file and the assignment path that we used to ```set_assignment()```:

```{r}
mark_file <- file.path(system.file(package = "markmyassignment"), "extdata", "example_lab_file.R")

assignment_path <- 
 file.path(system.file(package = "markmyassignment"), "extdata", "example_assignment01.yml")

mark_my_file(mark_file = mark_file, assignment_path = assignment_path)
```

It is also possible to just specify the assignment path and then choose the assignment file as follows:

```{r, eval=FALSE}
mark_my_file(assignment_path = assignment_path)
```

We could also check individual tasks in our file, similar to before:

```{r}
mark_my_file(tasks = "task1", mark_file = mark_file, assignment_path = assignment_path)
```


Good luck! If you have any suggestions, comments or ideas feel free to add an issue at the package [webpage](https://github.com/MansMeg/markmyassignment)!