---
title: "User Guide"
subtitle: "'learnrbook' `r packageVersion('learnrbook')`"
author: "Pedro  J. Aphalo"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{User Guide}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  markdown: 
    wrap: 72
---

## The R Package 'learnrbook'

This package contains data sets used in the code examples in the books
"Learn R: As a Language" (1ed) by Pedro J. Aphalo (2020) and
"Learn R: As a Language" (2ed) by Pedro J. Aphalo (2024). 

The book uses mostly data sets included in the
R distribution itself and in packages available through CRAN, so only a few
additional data sets are included as R data in this package. However, to
demonstrate the reading of foreign data formats I use in the book
several files. These files are part of this package and installed in the
`extdata` folder.

For more information on the book, please, visit 
[the website that I have created for it](https://www.learnr-book.info/). In
the website you will find the Preface and the Table of Contents with
chapter summaries.

## Installation of the package

Installation of the package itself is not different to that of any other
package available through CRAN.

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

## Loading the package

```{r}
library(learnrbook)
```

## Installation of other packages used in the book

In the code examples in the book I use several packages available from
CRAN. To facilitate their installation and use, vectors containing package names are provided.

To install all the packages used in the 2nd edition of the book you can use.

```{r, eval=FALSE}
install.packages(learnrbook::pkgs_all_2ed)
```

To install all the packages used in the 1st edition of the book you can use.

```{r, eval=FALSE}
install.packages(learnrbook::pkgs_all_1ed)
```

If you rather install only the packages used in a given chapter, for
example, chapter 9 of the 2ed, about the *Grammar of Graphics* it is possible to
install only these.

```{r, eval=FALSE}
install.packages(learnrbook::pkgs_ch9_2ed)
```

To install only the packages that are missing.

```{r, eval=FALSE}
intalled_pkgs <- installed.packages()[ , 1]
missing_pkgs <- setdiff(learnrbook::pkgs_all_2ed, intalled_pkgs)
if (length(missing_pkgs) > 0) {
 install.packages(missing_pkgs)
}
```

## Use of R data objects

Please, see the individual help pages for additional details on the data
sets.

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

```{r, eval=FALSE}
data(package = "learnrbook")
```

Display the top six rows.

```{r}
head(viikki_d29.dat)
```

## Use of examples files

Example files are installed in folder `extdata` under the root folder of
the installed package. The location and path to where a package is
installed is dependent on the operating system and account settings, and
on the settings in the `.Rprofile` file. However, R provides a simple
way of finding the path to this folder.

```{r, eval=FALSE}
system.file("extdata", package = "learnrbook")
```

A list of all the data files used in at least one of the editions can be obtained with.

```{r}
path2examples <- system.file("extdata", package = "learnrbook")
list.files(path2examples)
```

The formats of these files are:

| File name "tag" | Format | other                                           |
|:----------------|:-------|:------------------------------------------------|
| .SYS            | Systat | proprietary, format depends on operating system |
| .sav            | SPSS   | proprietary                                     |
| .txt            | text   | plain text                                                |
| .fwd            | text   | fixed-width data fields                         |
| .csv            | text   | comma separated fields                          |
| .tsv            | text   | tab(ulator) separated values                    |
| .gpx            | text   | GPS position data, XML based                    |
| .nc             | NetCDF | binary, with metadata                           |
| .xlsx           | Excel  | "workbooks", XML based and compressed           |
| .ods            | ODS    | non-proprietary, XML based                      |
| .R              | text   | R script file                                   |
| .idx            | text   | $\LaTeX$ index                                  |

Most data files are used in the last chapter *Data Input and Output*.

The example R script is used in Chapter *The R language: "Paragraphs"
and "essays"*.

The sources of the data in these files, and a short descriptions of the
data follows for those files that contain real data.

| File                 | when saved | Data                          | Source                       |
|:---------------------|:-----------|:------------------------------|------------------------------|
| BIRCH1.SYS           | 1992       | Birch seedlings               | Aphalo and Rikala (2002)     |
| logger_1.txt         | 2016       | from Yocto Puce datalogger    | Original, P. J. Aphalo       |
| meteo-data.nc        | 2017       | meteorological                |                              |
| pet_ltm.nc           | 2014       | meteorological                | Data of Anders Lindfors, FMI |
| pevpr.sfc.mon.ltm.nc | 20XX       | meteorological                | NASA                         |
| thiamin.sav          | ????       | Vitamin B1                    |                              |
| rindex.idx           | 2020       | word list with markup         | alphabetical R index         |
| rcatsidx.idx         | 2020       | word list with markup         | R index by categories        |
| cloudindex.idx       | 2020       | word list with minimal markup | word cloud on the cover      |

## R code for code chunks in the book

The code examples from the book, extracted with `knitr::purl()` are included in this package in files `purl-output-2ed.zip` and `purl-output-1ed.zip`. The code from chunks in the book are in one `.R` file per chapter. The code below extracts and saves these files in a new directory called `purl-output` under the directory passed as argument to `exdir`. Here we use `~` to select the home directory of the current user:

```{r, purl-output, eval=FALSE}
zip.file <- system.file("example-chunks/purl-output-2ed.zip", package = "learnrbook")
unzip(zip.file, exdir = "~")
```

Alternatively the whole `.zip` file can be copied:

```{r, zip-copy, eval=FALSE}
file.copy(from = zip.file, to = "~")
```

