---
title: "exams.forge.data"
author: "Sigbert Klinke"
date: "`r Sys.Date()`"
output: 
  html_document:
    toc: yes
  rmarkdown::html_vignette:
    toc: true
  pdf_document:
    toc: yes
vignette: >
  %\VignetteIndexEntry{exams.forge.data}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options:
  markdown:
    wrap: 72
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library("exams.forge.data")
```

## Sum of Squares Dataset

The package contains the precomputed dataset `sos100`, which holds integer solutions for:

1. $\sum_{i=1}^{k} x_i = 0$
2. $\sum_{i=1}^{k} x_i^2 = 100$

This dataset can be used as a basis for Pearson correlation, linear regression, or other computations requiring integer data with exact sums of squares.

```{r sos}
data("sos100")
str(sos100)
# sum_i x_i
head(rowSums(sos100, na.rm=TRUE))
# sum_i x_i^2
head(rowSums(sos100^2, na.rm=TRUE))
# number of non-missing observations
head(rowSums(!is.na(sos100)))
```

### Using `sos()` for other datasets

For other values of `n` or different maximum number of summands (`nmax`), use the `sos()` function from the **`exams.forge`** package:

```{r, eval=FALSE}
library("exams.forge")   # version 1.0.12 is required
# Retrieve or compute the dataset for n = 200
sos200 <- sos(200)
# With a custom nmax
sos_custom <- sos(150, nmax = 12)
```

This function will attempt to load the dataset from the package, a cached location, GitHub, or compute it on the fly if necessary.

## Available Exercises

**Note:**

* All exercises are provided in German, and not all of them have appeared on exams.
* Some exercises require the installation of additional R packages.
* Several exercises apply the same calculation methods but in different contexts.
* The quality of the exercises may vary, and certain difficulties often become apparent only during the exam.

**Exercises:**

on [Github](https://github.com/sigbertklinke/exams.forge.data/tree/main/inst/aufgaben) you can find an overview of all exercises included in the package, organized by topic (directory).

```{r, echo=FALSE}
library("knitr")
files <- list.files(path = system.file("aufgaben", package = "exams.forge.data"), pattern = "\\.Rmd$", recursive = TRUE, full.names = FALSE)
tab   <- table(dirname(files))
df    <- data.frame(Topic=names(tab), Exercises=as.integer(tab))               
kable(df, format = "markdown")
```

### Exploring Exercises with `view()`

The `view()` function is designed to help users explore and render exercises included in the exams.forge.data package. It provides a fully scriptable interface for browsing topics, listing exercises, and optionally rendering them to PDF or HTML, without relying on interactive menus.

#### Key Features

1. List available topics

```{r topic}
head(view("topic"))
```

Returns a character vector of all exercise topics (i.e., subdirectories under aufgaben/). This helps users understand the structure of the exercises and pick a topic of interest.

2. List exercises in a topic or matching a pattern

```{r file}
head(view("file", pattern = "ttest"))
```

Returns exercise filenames relative to the subdirectory `aufgaben/` in the package.

* `pattern` can filter by directory names (topics) or, if `topic = FALSE`, by content inside exercises.
* This allows you to quickly locate exercises relevant to a specific concept or statistical test.

3. Render exercises to HTML

```{r html, eval=FALSE}
view("html", pattern = "hyper")
```

Uses `exams2html()` to render the selected exercises. Output is silently generated, suppressing messages and warnings.

4. Render exercises to PDF

```{r pdf, eval=FALSE}
view("pdf", pattern = "ttest")
```

Uses `exams2pdf()` to render the selected exercises to PDF. A plain LaTeX template is applied, and messages/warnings are suppressed to avoid console clutter.

#### Parameters

* `action`: `"topic"`, `"file"`, `"pdf"`, or `"html"`. Determines what the function returns or does.
* `pattern`: Optional regular expression to filter files or topics.
* `topic`: Logical; if `TRUE` (default), pattern is applied to topic (directory) names; if `FALSE`, pattern is applied to file contents.
* `...`: Additional arguments passed to `grepl()` for filtering.

#### Workflow Example

```{r workflow, eval=FALSE}
# 1. List all topics
topics <- view("topic")

# 2. Select exercises from a specific topic
files <- view("file", pattern = "ttest", topic = TRUE)

# 3. Render them to HTML
view("html", pattern = "ttest")
```

This approach allows users to explore hundreds of exercises efficiently, filter by topic or content, and generate outputs in multiple formats without manual interaction.

### Render All Exercises 

To render all exercises (on my computer, this takes roughly 1 minute), use the following code:

```{r all, eval=FALSE}
library("exams.forge")
files <- list.files(path=system.file("aufgaben", package="exams.forge.data"), 
                    pattern="\\.Rmd$", recursive = TRUE, full.names = TRUE)
# Render all 500+ exercises
exams2html(files)   
# Render all exercises as PDF using a custom LaTeX template
# (required because 'exams' does not support \usepackage[xtable]{xcolor})
exams2pdf(files, template=system.file("aufgaben", "plain.tex", package="exams.forge.data"))
```

__Notes:__

* You may see warnings such as:
  + `In search_files(file, dir = dir, recursive = recursive) :`
     `The following files are found more than once, first match used: ...`
  + `LaTeX Warning: 'h' float specifier changed to 'ht'.`

These warnings are generally harmless and can be safely ignored.