--- # ---------------------------------------------------------------------------- - type: information ref: tut-test title: Configuração do teste text: | O teste é configurado num ficheiro `yaml` (ver especificação [aqui](https://yaml.org)). A configuração contém a identificação do teste, base de dados dos alunos, ficheiros de perguntas a importar e uma selecção de perguntas e respectivas cotações. Exemplo: ```yaml --- # -------------------------------------------------------------------------- ref: tutorial # referência, pode ser reusada em vários turnos title: Demonstração # título da prova database: students.db # base de dados já inicializada com initdb answers_dir: ans # directório onde ficam os testes entregues # opcional duration: 60 # duração da prova em minutos (default=inf) show_points: true # mostra cotação das perguntas scale_points: true # recalcula cotações para a escala [0, scale_max] scale_max: 20 # limite superior da escala debug: false # mostra informação de debug na prova (browser) # -------------------------------------------------------------------------- questions_dir: ~/topics # raíz da árvore de directórios das perguntas # Ficheiros de perguntas a importar (relativamente a `questions_dir`) files: - tabelas.yaml - topic_A/questions.yaml - topic_B/part_1/questions.yaml - topic_B/part_2/questions.yaml # -------------------------------------------------------------------------- # Especificação das perguntas do teste e respectivas cotações. # O teste é uma lista de perguntas, onde cada pergunta é especificada num # dicionário com a referência da pergunta e a respectiva cotação. questions: - ref: pergunta1 points: 3.5 - ref: pergunta2 points: 2 - ref: tabela-auxiliar # escolhe aleatoriamente uma das variantes - ref: [pergunta3a, pergunta3b] points: 0.5 # a cotação é 1.0 por defeito (se omitida) - ref: pergunta4 # se for uma string (não dict), é interpretada como referência - pergunta5 # -------------------------------------------------------------------------- ``` A ordem das perguntas é mantida quando apresentada para o aluno. O mesmo teste pode ser realizado várias vezes em vários turnos, não é necessário alterar nada. # ---------------------------------------------------------------------------- - type: information ref: tut-questions title: Especificação das perguntas text: | As perguntas estão definidas num ou mais ficheiros `yaml` como uma lista de dicionários, onde cada pergunta é um dicionário. Por exemplo, um ficheiro com o conteúdo abaixo contém duas perguntas, uma de escolha múltipla e outra apenas informativa: ```yaml --- #----------------------------------------------------------------------------- - type: radio ref: chave-unica-1 text: Quanto é $1+1$? options: - 1 - 2 - 3 #----------------------------------------------------------------------------- - type: information ref: chave-unica-2 text: | Quando o texto da pergunta tem várias linhas, dá jeito usar o símbolo `|` de pipe, para indicar que tudo o que estiver indentado faz parte do texto. É o caso desta pergunta. O texto das perguntas é escrito em `markdown`. #----------------------------------------------------------------------------- ``` As chaves são usadas para construir o teste e não se podem repetir em ficheiros diferentes. A seguir vamos ver exemplos de cada tipo de pergunta. # ---------------------------------------------------------------------------- - type: radio ref: tut-radio title: Escolha simples, uma opção correcta. text: | As perguntas de escolha simples, permitem fazer uma pergunta e apresentar várias opções de resposta em que apenas uma delas está certa. A utilização mais simples é a seguinte: ```yaml - type: radio ref: pergunta-1 title: Escolha simples, uma opção correcta. text: | Bla bla bla. options: - Opção 0 - Opção 1 - Opção 2 - Opção 3 - Opção 4 ``` Sem outras configurações, assume-se que a primeira opção é a resposta correcta ("Opção 0" neste caso) e as 5 opções são apresentadas por ordem aleatória. Para evitar que os alunos memorizem os textos das opções, podem definir-se várias opções correctas com escrita ligeiramente diferente, sendo escolhida apenas uma delas para apresentação. Por exemplo, se as 2 primeiras opções estiverem correctas e as restantes erradas, e quisermos apresentar ao aluno 3 opções no total, acrescenta-se: ```yaml correct: [1, 1, 0, 0, 0] choose: 3 ``` Neste caso, será escolhida uma opção certa de entre o conjunto das certas e duas erradas de entre o conjunto das erradas. Os valores em `correct` representam o grau de correcção no intervalo [0, 1] onde 1 representa 100% certo e 0 representa 0%. Por defeito, as opções são apresentadas por ordem aleatória. Para manter a ordem acrescenta-se: ```yaml shuffle: false ``` Por defeito, as respostas erradas descontam, tendo uma cotação de -1/(n-1) do valor da pergunta, onde n é o número de opções apresentadas ao aluno (a ideia é o valor esperado ser zero quando as respostas são aleatórias e uniformemente distribuídas). Para não descontar acrescenta-se: ```yaml discount: false ``` options: - Opção 0 (certa) - Opção 1 (certa) - Opção 2 - Opção 3 - Opção 4 correct: [1, 1, 0, 0, 0] choose: 3 solution: | A solução correcta é a **Opção 0** ou a **Opção 1**. # ---------------------------------------------------------------------------- - ref: tut-checkbox type: checkbox title: Escolha múltipla, várias opções correctas text: | As perguntas de escolha múltipla permitem apresentar um conjunto de opções podendo ser seleccionadas várias em simultaneo. Funcionam como múltiplas perguntas independentes de resposta sim/não. Cada opção seleccionada (`sim`) recebe a cotação indicada em `correct`. Cada opção não seleccionadas (`não`) tem a cotação simétrica. ```yaml - type: checkbox ref: tut-checkbox title: Escolha múltipla, várias opções correctas text: | Bla bla bla. options: - Opção 0 (certa) - Opção 1 - Opção 2 - Opção 3 (certa) - Opção 4 correct: [1, -1, -1, 1, -1] ``` Neste exemplo, seleccionando as opções 0 e 3 obtém-se cotação +1 em cada uma, enquanto que seleccionando as opções 1, 2 e 4 obtém-se cotação -1. As opções não seleccionadas pelo aluno dão a cotação simétrica à indicada. Por exemplo se não seleccionar a opção 0, tem cotação -1, e não seleccionando a opção 1 obtém-se +1. *(Note que o `correct` não funciona do mesmo modo que nas perguntas do tipo `radio`. Em geral, um aluno só deve responder se souber mais de metade das respostas, caso contrário arrisca-se a ter cotação negativa na pergunta. Não há forma de não responder a apenas algumas delas.)* Cada opção pode opcionalmente ser escrita como uma afirmação e o seu contrário, de maneira a aumentar a variabilidade dos textos. Por exemplo: ```yaml options: - ["O céu é azul", "O céu não é azul"] - ["Um triangulo tem 3 lados", "Um triangulo tem 2 lados"] - O nosso planeta tem um satélite natural correct: [1, 1, 1] ``` Assume-se que a primeira alternativa de cada opção tem a cotação indicada em `correct`, enquanto a segunda alternativa tem a cotação simétrica. Tal como nas perguntas do tipo `radio`, podem ser usadas as configurações `shuffle` e `discount` com valor `false` para as desactivar. Se `discount` é `false` então as respostas erradas têm cotação 0 em vez do simétrico. options: - ['Opção 0 (sim)', 'Opção 0 (não)'] - ['Opção 1 (não)', 'Opção 1 (sim)'] - Opção 2 (não) - Opção 3 (sim) correct: [1, -1, -1, 1] shuffle: false # ---------------------------------------------------------------------------- - type: text ref: tut-text title: Resposta de texto em linha text: | Este tipo de perguntas permite uma resposta numa linha de texto. A resposta está correcta se coincidir exactamente com alguma das respostas admissíveis. ```yaml - type: text ref: tut-text title: Resposta de texto em linha text: | De que cor é o céu? Escreva a resposta em português. correct: ['azul', 'Azul', 'AZUL'] ``` Neste caso, as respostas aceites são `azul`, `Azul` ou `AZUL`. correct: ['azul', 'Azul', 'AZUL'] # --------------------------------------------------------------------------- - type: text-regex ref: tut-text-regex title: Resposta de texto em linha, expressão regular text: | Este tipo de pergunta é semelhante à linha de texto da pergunta anterior. A única diferença é que esta é validada por uma expressão regular. ```yaml - type: text-regex ref: tut-text-regex title: Resposta de texto em linha text: | Bla bla bla correct: '(VERDE|[Vv]erde)' ``` Neste exemplo a expressão regular é `(VERDE|[Vv]erde)`. --- **Atenção:** A expressão regular deve seguir as convenções da suportadas em python (ver [Regular expression operations](https://docs.python.org/3/library/re.html)). Em particular, a expressão regular acima também aceita a resposta `verde, azul`. Possivelmente devia marcar-se o final com o cifrão `(VERDE|[Vv]erde)$`. correct: '(VERDE|[Vv]erde)' # --------------------------------------------------------------------------- - type: numeric-interval ref: tut-numeric-interval title: Resposta numérica em linha de texto text: | Este tipo de perguntas esperam uma resposta numérica (vírgula flutuante). O resultado é considerado correcto se estiver dentro do intervalo fechado indicado. ```yaml - type: numeric-interval ref: tut-numeric-interval title: Resposta numérica em linha de texto text: | Escreva o número $\pi$ com pelo menos duas casa decimais. correct: [3.14, 3.15] ``` Neste exemplo o intervalo de respostas correctas é [3.14, 3.15]. **Atenção:** as respostas têm de usar o ponto como separador decimal. Em geral são aceites números inteiros, como `123`, ou em vírgula flutuante, como em `0.23`, `1e-3`. correct: [3.14, 3.15] solution: | Sabems que $\pi\approx 3.14159265359$. Portanto, um exemplo de uma resposta correcta é `3.1416`. # --------------------------------------------------------------------------- - type: textarea ref: tut-textarea title: Resposta em múltiplas linhas de texto text: | Este tipo de perguntas permitem respostas em múltiplas linhas de texto, que podem ser úteis por exemplo para introduzir código. A resposta é enviada para um programa externo para ser avaliada. O programa externo é um programa qualquer executável pelo sistema. Este recebe a resposta submetida pelo aluno via `stdin` e devolve a classificação via `stdout`. Exemplo: ```yaml - type: textarea ref: tut-textarea title: Resposta em múltiplas linhas de texto text: | Bla bla bla correct: correct/correct-question.py # programa a executar timeout: 5 ``` Neste exemplo, o programa de avaliação é um script python que verifica se a resposta contém as três palavras red, green e blue, e calcula uma nota no intervalo 0.0 a 1.0. O programa externo é um programa executável no sistema, escrito em qualquer linguagem de programação. A interacção com o servidor faz-se sempre via stdin/stdout. Se o programa externo exceder o `timeout` indicado (em segundos), é automaticamente cancelado e é atribuída a classificação de 0.0 valores. Após terminar a correcção, o programa externo deve enviar a classificação para o stdout. Pode simplesmente fazer `print` da classificação como um número em vírgula flutuante, por exemplo ```yaml 0.75 ``` ou opcionalmente escrever em formato yaml, eventualmente com um comentário que será arquivado com o teste. Exemplo: ```yaml grade: 0.5 comments: | Esqueceu-se de algumas cores. A resposta correcta era `red green blue`. ``` O comentário é mostrado na revisão de prova. answer: | Esta caixa aumenta de tamanho automaticamente e pode estar previamente preenchida (use answer: texto). correct: correct/correct-question.py timeout: 5 # --------------------------------------------------------------------------- - type: information ref: tut-information title: Texto informativo text: | As perguntas deste tipo não contam para avaliação. O objectivo é fornecer instruções para os alunos, por exemplo tabelas para consulta, fórmulas, etc. Nesta, tal como em todos os tipos de perguntas podem escrever-se fórmulas em LaTeX. Exemplo: A distribuição gaussiana $\mathcal{N}(x\mid\mu,\sigma^2)$ é definida pela função densidade de probabilidade $$ p(x) = \frac{1}{\sqrt{2\pi\sigma^2}} \exp\Big({-\frac{(x-\mu)^2}{2\sigma^2}}\Big). $$ --- ```yaml - type: information ref: tut-information title: Texto informativo text: | A distribuição gaussiana $\mathcal{N}(x\mid\mu,\sigma^2)$ é definida pela função densidade de probabilidade $$ p(x) = \frac{1}{\sqrt{2\pi\sigma^2}} \exp\Big({-\frac{(x-\mu)^2}{2\sigma^2}}\Big). $$ ``` # --------------------------------------------------------------------------- - type: success ref: tut-success title: Texto informativo (sucesso) text: | Também não conta para avaliação. É apenas o aspecto gráfico que muda. Além das fórmulas LaTeX, também se pode escrever troços de código: ```C int main() { printf("Hello world!"); return 0; // comentario } ``` --- - type: success ref: tut-success title: Texto informativo (sucesso) text: | Também não conta para avaliação. É apenas o aspecto gráfico que muda. Além das fórmulas LaTeX, também se pode escrever troços de código: ```C int main() { printf("Hello world!"); return 0; // comentario } ``` # --------------------------------------------------------------------------- - type: warning ref: tut-warning title: Texto informativo (aviso) text: | Não conta para avaliação. Neste exemplo mostramos como se pode construir uma tabela como a seguinte: Left | Center | Right -----------------|:----------------:|----------: *hello* | $\sin(x^2)$ | $1600.00 **world** | $\frac{1}{2\pi}$ | $12.50 `code` | $\sqrt{\pi}$ | $1.99 As tabelas podem conter Markdown e LaTeX. --- ```yaml - type: warning ref: tut-warning title: Texto informativo (aviso) text: | Bla bla bla Left | Center | Right -----------------|:----------------:|----------: *hello* | $\sin(x^2)$ | $1600.00 **world** | $\frac{1}{2\pi}$ | $12.50 `code` | $\sqrt{\pi}$ | $1.99 ``` # ---------------------------------------------------------------------------- - type: alert ref: tut-alert title: Texto informativo (perigo) text: | Não conta para avaliação. Texto importante. ![planetas](planets.png "Planetas do Sistema Solar") As imagens podem ser adicionadas usando a notação standard em markdown. Há duas possibilidads: - Imagens inline: não têm título definido e podem ser incluídas no meio de uma linha de texto usando`![alt text](image.jpg)`. - Imagens centradas com título: `![alt text](image.jpg "Título da imagem")`. O título aprece por baixo da imagem. O título pode ser uma string vazia. # ---------------------------------------------------------------------------- - type: information text: This question is not included in the test and will not show up. # ----------------------------------------------------------------------------