---
title: "Introduction to the desk-package"
output: rmarkdown::html_vignette
#toc: true
vignette: >
  %\VignetteIndexEntry{Introduction to the desk-package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
Sys.setenv(LANGUAGE="en")

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```
<!-- <br/><br/> -->
The acronym **desk** stands for **didactic econometrics starter kit**. The primary audience of this package are students and teachers, but also casual users. **desk** ...

1. **provides visualizations that speed up the learning process and enhance the understanding of econometrics.**
2. **lowers barriers for the use of R in general.**

In the following, we present the most important and easy-to-grasp features. We illustrate these features in the form of functions and mostly through resulting graphical representations.

```{r setup, echo=FALSE, results=FALSE}
suppressMessages(library(desk))
```

## Ordinary Least Squares: `ols()`
As the cornerstone of econometrics, the OLS method is typically the initial step in computing an estimator. Our version is similar to the **lm** function (**l**inear **m**odel, a base function in R), but it yields a more appealing output and various applications in combination with the base functions `plot()` and `print()`. The following code creates data points and plots them:

```{r}
x <- c(1,2,3,4)
y <- c(2,3,2,5)
plot(x,y)
```

A regression line is now estimated and the results are presented both, numerically and as a straight line through the data points:

```{r}
my.model.est <- ols(y ~ x)
my.model.est

plot(my.model.est)
```

Being useful to calculate further figures or reproduce them, details of the estimation can be shown:

```{r}
print(my.model.est, details = TRUE)
```

In contrast to `summary(lm(y ~ x))`, the sum of squares residual and the sample's standard error ($\widehat{\sigma}^2$) are included. However, detailed information about the residuals is hidden, as it is rarely used.

## t-test: `par.t.test()`
To test a single linear combination of parameters, a t-test is typically employed. First, we replicate the standard test for the slope parameter using the OLS results above: 

```{r}
par.t.test(my.model.est, nh = c(0,1))
```

Furthermore, we save a similar, one-sided test to visualize the results:
```{r, fig.width = 6}
my.test <- par.t.test(my.model.est, nh = c(0,1), dir = "right")

plot(my.test)
```

The same principle applies to other functions in our package, allowing for various tests to be visualized.

## Available data: `datasets()`
The simple command `datasets()` (without arguments, i.e. with empty brackets) shows available datasets in the package alongside a short description:

```{r}
datasets()
```

Typing in a dataset's name shows the data in the console:

```{r}
data.anscombe
```

It can also be saved into the global environment:
```{r}
my.data <- data.anscombe
```

As with functions, a question mark as prefix shows the help-file:
```{r}
?data.anscombe
```

## Simulated data: `repeat.sample()`
A fundamental insight in (applied) econometrics involves the restriction of repeated samples, which can be challenging to grasp. As a didactic aid for educators, random samples can be drawn while maintaining the same population slope and intercept. Here, we generate four samples with a slope of 1 and no intercept over x-values ranging from 1 to 30:

```{r}
x <- 1:30
four.samples <- repeat.sample(x, true.par = c(0, 1), sd = 10, rep = 4)
```

```{r, echo=FALSE}
plot(x,four.samples$y[,1], ylab = "", main = "1. Sample")
plot(x,four.samples$y[,2], ylab = "", main = "2. Sample")
plot(x,four.samples$y[,3], ylab = "", main = "3. Sample")
plot(x,four.samples$y[,4], ylab = "", main = "4. Sample")
```

Additional graphical representations help to understand the relationship between the true parameters and the estimated ones. To better visualize the distribution of data points around the regression line and the various estimated regression lines, we limit the x-values to a range of 1 to 10 and generate 100 samples, respectively.

```{r}
x <- 1:10
hundred.samples <- repeat.sample(x, true.par = c(0, 1), sd = 1, rep = 100)

plot(hundred.samples, plot.what = "scatter")
plot(hundred.samples, plot.what = "reglines")
```

## Useful tools
Alongside the 35 functions relating to econometrics, **desk** also includes some useful tools to make working with **R** easier. 

The function `rm.all()` removes all objects from global environment, while `new.session()` accomplishes the same task and additionally resets most settings. Moreover, it sets the working directory to the source file location if the function is used from an R script. Starting a script with this function can speed up the working flow. Both functions can be used without input.

Furthermore, the `arguments()` function reveals a function's possible input in a simple way:

```{r}
arguments(par.t.test)
```