notas-moodle.Rmd

---
title: "Notas: Moodle"
author: "Fernando Mayer (LEG/DEST/UFPR)"
date: |
  | 2019-02-08
  | Última atualização: 2020-06-01
output:
  html_document:
    toc: true
    code_folding: show
---

```{r setup, include=FALSE, cache=FALSE}
source("setup_knitr.R")
```

# Como são calculadas as notas no Moodle

## Versão simplificada

As questões de múltipla escolha feitas no Moodle possuem um método de
atribuição de pontos que segue algumas regras, demonstradas a seguir.

A primeira coisa a saber é que o valor de cada alternativa muda conforme
o número de alternativas verdadeiras/falsas. Cada alternativa verdadeira
terá pontuação sempre dada por
$$
\frac{1}{\text{# verdadeiras}}
$$
ou seja, cada alternativa verdadeira será uma fração do número total de
alternativas verdadeiras.

Ao marcar uma alternativa falsa, existirá uma penalização, ou seja, você
receberá uma pontuação negativa por ter marcado uma alternativa falsa.
Essa pontuação negativa será utilizada para descontar da nota final
obtida marcando-se as alternativas verdadeiras. O cálculo da pontuação
de cada alternativa falsa marcada é dado por
$$
\frac{1}{\max\{ \text{# falsas, 2} \}}
$$
A ideia é a mesma da pontuação das alternativas verdadeiras, mas se
houverem apenas uma ou nenhuma alternativa falsa na questão, a fração será
sempre $1/2$. Esse detalhe serve para que, no caso de ocorrer apenas uma
alternativa falsa, a marcação dessa alternativa não anule toda a
questão. Portanto, no caso de ocorrer apenas uma alternativa falsa, a
penalização por marcar essa alternativa será $1/2 = 0,5$, e não $1/1 =
1$ se não houvesse esse detalhe.

É importante notar que, de acordo com esses critérios, a nota final
**poderia** ser negativa. No entanto, **a nota nunca será negativa**, já
que existe uma restrição para que seja no mínimo **zero**.

<div class="alert alert-warning" role="alert">
**Atenção:** esse é o comportamento padrão para a correção de questões
de múltipla escolha adotado pelo pacote **exams**. Esse padrão pode ser
alterado. Veja mais informações na seção [detalhes
técnicos](#detalhes-técnicos).
</div>

## Exemplos

Suponha uma questão com 2 alternativas verdadeiras (V) e 3 falsas
(F). A pontuação de cada alternativa será:

- $1/2 = 0,5$ para alternativas verdadeiras
- $1/3 = 0,33$ para alternativas falsas

Alguns cenários possíveis:

- Ao marcar 2 V e 0 F, a nota será $1,00 - 0,00 = 1,00$.
- Ao marcar 2 V e 1 F, a nota será $1,00 - 0,33 = 0,67$.
- Ao marcar 2 V e 2 F, a nota será $1,00 - 0,66 = 0,34$.
- Ao marcar 1 V e 1 F, a nota será $0,50 - 0,33 = 0,17$.
- Ao marcar 1 V e 2 F, a nota será $0,50 - 0,66 = 0,00$.
- Ao marcar 2 V e 3 F, a nota será $1,00 - 1,00 = 0,00$.

Suponha uma questão com 4 alternativas verdadeiras (V) e 1 falsa
(F). A pontuação de cada alternativa será:

- $1/4 = 0,25$ para alternativas verdadeiras
- $1/2 = 0,5$ para alternativa falsa (observe o detalhe da regra)

Alguns cenários possíveis:

- Ao marcar 4 V e 0 F, a nota será $1,00 - 0,00 = 1,00$.
- Ao marcar 4 V e 1 F, a nota será $1,00 - 0,50 = 0,50$.
- Ao marcar 3 V e 0 F, a nota será $0,75 - 0,00 = 0,75$.
- Ao marcar 3 V e 1 F, a nota será $0,75 - 0,50 = 0,25$.
- Ao marcar 2 V e 1 F, a nota será $0,50 - 0,50 = 0,00$.
- Ao marcar 1 V e 1 F, a nota será $0,25 - 0,50 = 0,00$.

## Tabelas de notas

Abaixo você pode conferir as pontuações atribuídas ao marcar um certo
número de alternativas verdadeiras e falsas em questões com 1 a 5
alternativas verdadeiras.

As linhas das tabelas se referem ao número de alternativas verdadeiras
marcadas, enquanto que as colunas se referem ao número de alternativas
falsas marcadas.

```{r, echo=FALSE}
z <- function(p, v, x, y, negative = FALSE, rule = "false2"){
    stopifnot(rule %in% c("false2", "false"))
    f <- 5 - v
    if(rule == "false2"){
        res <- ifelse(f < 2,
                      x * p/v - y * p/2,
                      x * p/v - y * p/f)
    } else{
        res <- x * p/v - y * p/f
    }
    res <- ifelse(isFALSE(negative) & res < 0, 0, res)
    return(res)
}
makegrid <- function(p, v, ...){
    f <- 5 - v
    gx <- 0:v
    gy <- 0:f
    grid <- expand.grid(x = gx, y = gy)
    for(i in 1:nrow(grid)){
        grid$z[i] <- z(p = p, v = v, x = grid$x[i], y = grid$y[i], ...)
    }
    tab <- matrix(grid$z, nrow = length(unique(grid$x)),
                  ncol = length(unique(grid$y)),
                  dimnames = list(V = unique(grid$x),
                                  F = unique(grid$y)))
    return(round(tab, 2))
}
```

Questão com 1 alternativa verdadeira e 4 falsas
```{r, echo=FALSE}
makegrid(p = 1, v = 1, rule = "false2")
```
Questão com 2 alternativas verdadeiras e 3 falsas
```{r, echo=FALSE}
makegrid(p = 1, v = 2, rule = "false2")
```
Questão com 3 alternativas verdadeiras e 2 falsas
```{r, echo=FALSE}
makegrid(p = 1, v = 3, rule = "false2")
```
Questão com 4 alternativas verdadeiras e 1 falsa
```{r, echo=FALSE}
makegrid(p = 1, v = 4, rule = "false2")
```
Questão com 5 alternativas verdadeiras e 0 falsas
```{r, echo=FALSE}
makegrid(p = 1, v = 5, rule = "false2")
```

## Detalhes técnicos

### Atribuição de notas do pacote exams

A correção automática de questões do pacote **exams** segue uma das
cinco regras implementadas na função `exams_eval()`, que possui os
seguintes argumentos
```{r}
library(exams)
args(exams_eval)
```
onde os argumentos são:

- `partial = TRUE`: permite que questões de múltipla escolha possuam
  créditos parciais. Do contrário, uma alternativa falsa marcada como
  verdadeira anula toda a questão.
- `negative = FALSE`: controla se a questão pode ter nota negativa (o
  que pode acontecer de acordo com algumas regras de correção).
- `rule`: as cinco regras implementadas (detalhes abaixo).

### Regras de pontuação

Em questões de múltipla escolha com créditos parciais, a fração
atribuída para cada alternativa verdadeira selecionada será sempre
$1/\text{V}$, onde $\text{V}$ é o número de alternativas corretas
(verdadeiras). Quando uma alternativa errada (falsa) é selecionada, a
pontuação (negativa) atribuída varia conforme uma das cinco regras. Para
cada alternativa errada selecionada, a pontuação negativa atribuída
será:

- `false2` (default): $1/\max\{\text{F}, 2\}$, onde $\text{F}$ é o
  número de alternativas erradas (falsas).
- `false`: usa $1/\text{F}$.
- `true`: usa $1/\text{V}$, de forma que cada alternativa errada
  selecionada anula uma alternativa correta.
- `all`: usa $1$, de forma que uma única alternativa errada selecionada
  anula todas as corretas selecionadas.
- `none`: usa $0$, de forma que marcar alternativas erradas não desconta
  nenhuma fração da nota.

Por exemplo, uma questão com 2 alternativas verdadeiras e 3 falsas terá
as seguintes pontuações de acordo com cada uma das regras:
```{r}
## false2
eef2 <- exams_eval(partial = TRUE, negative = FALSE, rule = "false2")
eef2$pointvec("11000")
## false
eef <- exams_eval(partial = TRUE, negative = FALSE, rule = "false")
eef$pointvec("11000")
## true
eet <- exams_eval(partial = TRUE, negative = FALSE, rule = "true")
eet$pointvec("11000")
## all
eea <- exams_eval(partial = TRUE, negative = FALSE, rule = "all")
eea$pointvec("11000")
## none
een <- exams_eval(partial = TRUE, negative = FALSE, rule = "none")
een$pointvec("11000")
```

Pela definição das regras, a diferença entre `false2` e `false` ocorre
apenas quando existirem uma ou nenhuma alternativa errada. Veja os
exemplos:
```{r}
## Uma errada ----------------------------------------------------------
## false2
eef2$pointvec("11110")
## false
eef$pointvec("11110")
## Nenhuma errada ------------------------------------------------------
## false2
eef2$pointvec("11111")
## false
eef$pointvec("11111")
```
O que ocorre é que `false2` considera que no mínimo sempre haverão duas
alternativas erradas, para que a pontuação máxima a ser descontada não
seja maior do que $0.5$ e a questão não seja anulada.

### Cálculo das notas

A nota final de uma questão será portanto dependente de dois fatores:

1. A regra de pontuação adotada.
2. O número de alternativas verdadeiras/falsas.

Para simplificar, vamos focar apenas nas regras `false2` (a padrão) e
`false`. De maneira geral, a nota final ($Z$) de uma questão usando a
regra `false2` será

\[z = \left\{
  \begin{array}{lr}
    x \frac{\text{P}}{\text{V}} - y \frac{\text{P}}{2},
    &  \text{se } \text{F} < 2\\
    x \frac{\text{P}}{\text{V}} - y \frac{\text{P}}{\text{F}},
    &  \text{se } \text{F} \geqslant 2\\
  \end{array}
\right.
\]

onde $X$ é o número de alternativas corretas marcadas, $Y$ é o número de
alternativas erradas marcadas, $\text{P}$ é a pontuação da questão, e
$\text{V}$ e $\text{F}$ são o número de alternativas verdadeiras e
falsas, respectivamente. Para a regra `false`, o cálculo da pontuação
simplifica apenas para
$$
z = x \frac{\text{P}}{\text{V}} - y \frac{\text{P}}{\text{F}}
$$

Os exemplos abaixo mostram a pontuação final em dois cenários:

1. Uma questão com 1 alternativa verdadeira.
2. Uma questão com 4 alternativas verdadeiras.

```{r}
## (1) Questão com 1 alternativa verdadeira ----------------------------
## Uma verdadeira marcada
eef2$pointsum("10000", "10000") # false2
eef$pointsum("10000", "10000")  # false
## Uma verdadeira e uma errada marcadas
eef2$pointsum("10000", "10001") # false2
eef$pointsum("10000", "10001")  # false
## (2) Questão com 4 alternativas verdadeiras --------------------------
## Quatro verdadeira marcada
eef2$pointsum("11110", "11110") # false2
eef$pointsum("11110", "11110")  # false
## Quatro verdadeiras e uma errada marcadas
eef2$pointsum("11110", "11111") # false2
eef$pointsum("11110", "11111")  # false
```

Com essas regras gerais, podemos definir uma função para fazer o cálculo
das notas seguindo estas duas regras.
```{r}
z <- function(p, v, x, y, negative = FALSE, rule = "false2"){
    stopifnot(rule %in% c("false2", "false"))
    f <- 5 - v
    if(rule == "false2"){
        res <- ifelse(f < 2,
                      x * p/v - y * p/2,
                      x * p/v - y * p/f)
    } else{
        res <- x * p/v - y * p/f
    }
    res <- ifelse(isFALSE(negative) & res < 0, 0, res)
    return(res)
}
```

Alguns exemplos similares aos cenários acima seriam
```{r}
## Uma alternativa verdadeira, uma verdadeira e uma errada marcadas
z(p = 1, v = 1, x = 1, y = 1, rule = "false2")
z(p = 1, v = 1, x = 1, y = 1, rule = "false")
## Quatro alternativas verdadeiras, quatro verdadeiras e uma errada
## marcadas
z(p = 1, v = 4, x = 4, y = 1, rule = "false2")
z(p = 1, v = 4, x = 4, y = 1, rule = "false")
```

Com isso, podemos criar uma função que gera uma tabela com todos os
possíveis resultados para um número diferente de alternativas
verdadeiras/falsas.
```{r}
makegrid <- function(p, v, ...){
    f <- 5 - v
    gx <- 0:v
    gy <- 0:f
    grid <- expand.grid(x = gx, y = gy)
    for(i in 1:nrow(grid)){
        grid$z[i] <- z(p = p, v = v, x = grid$x[i], y = grid$y[i], ...)
    }
    tab <- matrix(grid$z, nrow = length(unique(grid$x)),
                  ncol = length(unique(grid$y)),
                  dimnames = list(V = unique(grid$x),
                                  F = unique(grid$y)))
    return(round(tab, 2))
}
```

Assim, temos todas as possibilidades para cada regra:

```{r}
## false2 --------------------------------------------------------------
makegrid(p = 1, v = 0, rule = "false2")
makegrid(p = 1, v = 1, rule = "false2")
makegrid(p = 1, v = 2, rule = "false2")
makegrid(p = 1, v = 3, rule = "false2")
makegrid(p = 1, v = 4, rule = "false2")
makegrid(p = 1, v = 5, rule = "false2")

## false ---------------------------------------------------------------
makegrid(p = 1, v = 1, rule = "false")
makegrid(p = 1, v = 2, rule = "false")
makegrid(p = 1, v = 3, rule = "false")
makegrid(p = 1, v = 4, rule = "false")
makegrid(p = 1, v = 5, rule = "false")
```