---
title: "Basic Setup"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Setup}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
The moodleR package contains functions and algorithms to access Moodle$^{TM}$ data and perform reporting and/or learning analytics based in these data. For more information about Moodle go to [www.moodle.org](https://www.moodle.org:443/). For more information about $\chi^\color{red}2$ (chi square) Laboratories and the work we do in learning analytics, visit our website: [www.chi2labs.com](https://www.chi2labs.com).
## Installing and loading the package
To install the latest stable release from CRAN use:
```{r setup, eval=FALSE}
install.packages("moodleR")
```
To install the latest development version:
```{r, eval=FALSE}
devtools::install("chi2labs/moodleR")
```
After which the package is attached in the usual way.
```{r}
library(moodleR)
```
## Connecting to a Moodle Database
### Configuration
When connecting to a moodle database moodleR will look for database information
in a config file (config.yml). The fields that need to be included can be seen in the snipped below:
```{yaml}
default:
moodleR:
user: "root"
password: "root"
dbname: "moodle38"
host: "localhost"
port: 3306
```
### Connecting to a moodle DB instance
Once the connection information available you can get a connection to the database by calling `mdl_get_connection()`, with the `use_cache` set to false:
```{r, eval=FALSE}
mdl_con <- mdl_get_connection(use_cache = FALSE)
```
The reason for `use_cache = FALSE` will be explained below.
## Caching Data
The moodleR package allows you to create a cache of the most relevant data on
your local computer.
There are several reasons you would want to cache data locally rather than
operating directly on a moodle database:
* You don't want to create additional server traffic that will worry the system administrator and generate bandwidth and hardware charges.
* You are experimenting with exotic new features and want to avoid any accidents which may get you banned from accessing the data in the future
* You only need a subset of courses
* You are conducting exploratory research a sample of courses and want to make sure you data stays stable during your experimentation
* You want your Notebooks and Rmarkdown document to compile faster
The moodleR package provides a method `moodle_cache` which allows for local caching of the data.
### Caching to sqlite
When you run the `moodle_cache` function moodleR will create a local directory `mdl_cache` in your working directory. In this directory an sqlite database, `mdl_cache.sqlite`, will be created to contain the cached tables.
```{r, eval = FALSE}
mdl_create_cache()
```
The output should look something like this:
```
#> Gettng Moodle DB connection
#> Gettng sqlite connection
#> Directory ' /home/sasha/chi2/moodleR/mdl_cache' used by default.
#> Set config variable in moodleR:mdl_cache_dir to override.
#> This message is displayed once per session.
#> Filename 'mdl_cache.sqlite' used by default.
#> Set config variable in moodleR:mdl_cache_dir to override.
#> Cache file created: /home/sasha/chi2/moodleR/mdl_cache/mdl_cache.sqlite
#> Downloading course table
#> Joining, by = "categoryid"
#> Caching course table
#> Downloading discussion posts table
#> Caching discussion posts table
#> Downloading user table
#> Caching user table
#> Downloading grades table
#> Caching grades table
#> Downloading config table
#> Downloading log table
#> Caching log table
#> Downloading roles table
#> Caching role table
#> Downloading enrolments
#> Caching enrolments
```