---
title: "kstMatrix"
author: "Cord Hockemeyer"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{kstMatrix}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(kstMatrix)
library(igraph)
library(grDevices)
library(sets)
library(pks)
```

Knowledge space theory applies prerequisite relationships between items of knowledge
within a given domain for efficient adaptive assessment and training (Doignon & Falmagne, 
1999). The `kstMatrix` package implements some basic functions for working with
knowledge space. Furthermore, it provides several empirically obtained knowledge spaces
in form of their bases.

There is a certain overlap in functionality between the `kst`and `kstMatrix` packages, 
however the former uses a set representation and the latter a matrix representation. The
packages are to be seen as complementary, not as a replacement for each other.

## Different representations for knowledge spaces
Knowledge spaces can easily grow very large. Therefore, their bases are often used to store
the knowledge spaces with reduced space requirements. `kstmatrix` offers two  functions for 
computing bases from spaces and vice versa.

### `kmbasis()`
The `kmbasis` function computes the basis for a given knowledge space (actually, it can be
any family of sets represented by a binary matrix). 
```{r}
kmbasis(xpl$space)
```

### `kmunionclosure()`
The `kmunionclosure` function computes the knowledge space for a basis (mathematically
spoken it computes the closure under union of the given family of sets).
```{r}
kmunionclosure(xpl$basis)
```

### `kmsurmiserelation()`
The `kmsurmiserelation` function determines the surmise relation for a quasi-ordinal
knowledge space. For a more general family of sets, it computes the surmise relation
for the smallest quasi-ordinal knowledge space including that family.
```{r}
kmsurmiserelation(xpl$space)
```
The surmise relation can also be used to easily close a knowledge space under intersection:
```{r}
kmunionclosure(t(kmsurmiserelation(xpl$space)))
```
### `kmsurmisefunction()`
The `kmsurmisefunction`function computes the surmise function for a knowledge
space or basis. For a more general family of sets, it computes the surmise function 
for the smallest knowledge space including that family.
```{r}
kmsurmisefunction(xpl$space)
```
### `kmsf2basis()`
Determine the basis of the knowledge space corresponding to a given surmise function.
```{r}
sf <- kmsurmisefunction(xpl$space)
kmsf2basis(sf)
```

## Properties of knowledge structures
### `kmiswellgraded()`
The `kmiswellgraded` function determines whether a knowledge structure is wellgraded.
```{r}
kmiswellgraded(xpl$space)
```

### `kmnotions()`
The `kmnotions` function returns a matrix specifying the notions of a knowledge strucure,
i.e. the classes of equivalent items.
```{r}
x <- matrix(c(0,0,0, 1,0,0, 1,1,1), nrow = 3, byrow = TRUE)
kmnotions(x)
```

### `kmeqreduction()`
The `kmeqreduction` function returns a matrix with only one item
per equivalence class.
```{r}
x <- matrix(c(0,0,0, 1,0,0, 1,1,1), nrow = 3, byrow = TRUE)
kmeqreduction(x)
```

## Creating trivial knowledge spaces
For a given item number, there are two trivial knowledge spaces, the maximal knowledge
space representing absolutely no prerequisite relationships (the knowledge space is the 
power set of the item set and the basis matrix is the diagonal matrix), and the minimal
knowledge space representing equivalence of all items (the knowledge space contains just 
the empty set and the full item set, and the basis matrix contains one line full of '1's).

### `kmminimalspace()`
**Example:**
```{r}
kmminimalspace(5)
```

### `kmmaximalspace()`
**Example:**
```{r}
kmmaximalspace(4)
```

## Validating knowledge spaces

### `kmdist()`
The `kmdist` function computes a frequency distribution for the distances between a data 
set and a knowledge space.
```{r}
kmdist(xpl$data, xpl$space)
```

### `kmvalidate()`
The `kmvalidate` function returns the distance vector, the discrimination index DI,
and the distance agreement coefficient DA. The discrepancy index (DI) is the mean
distance; the distance agreement coefficient is the ratio between the mean distance between
data and space (ddat = DI) and the mean distance between space and power set (dpot).
```{r}
kmvalidate(xpl$data, xpl$space)
```

## Simulating response patterns
### `kmsimulate()`
The `kmsimulate` funtion provides a generation of response patterns by
applying the BLIM (Basic Local Independence Model; see Doignon & Falmagne, 1999)
to a given knowledge structure. The `beta` and `eta` parameters of the BLIM can each
be either a vector specifying different values for each item or a single numerical
where `beta` or `eta` is assumed to be equal for all items.
```{r}
kmsimulate(xpl$space, 10, 0.2, 0.1)
kmsimulate(xpl$space, 10, c(0.2, 0.25, 0.15, 0.2), c(0.1, 0.15, 0.05, 0.1))
kmsimulate(xpl$space, 10, c(0.2, 0.25, 0.15, 0.2), 0)
```

## Neighbourhood & Fringe
### `kmneighbourhood()`
The `kmneighbourhood` function determines the neighbourhood of a state in a knowledge structure,
i.e. the family of all states with a symmetric set diference of 1.
```{r}
kmneighbourhood(c(1,1,0,0), xpl$space)
```

### `kmfringe()`
The `kmfringe` function determines the fringe of a knowledge state, i.e. the set of thse items 
by which the state differs from its neighbouring states.
```{r}
kmfringe(c(1,0,0,0), xpl$space)
```

## Utilities
### `kmsymmsetdiff()`
The `kmsymmsetdiff` function returns the symmetric set difference between two
sets represented as binary vectors.
```{r}
kmsymmsetdiff(c(1,0,0), c(1,1,0))
```

### `kmsetdistance()`
The `kmsetdistance` function returns the cardinality of the symmetric set 
difference between two sets represented as binary vectors.
```{r}
kmsetdistance(c(1,0,0), c(1,1,0))
```

## Plotting with `kmhasse()`and `kmcolors()`
The `kmhasse` function draws a Hasse diagram of a knowledge structure,
the `kmcolors`function returns a color vector to be used with `kmhasse()`.
```{r}
kmhasse(xpl$space, horizontal = FALSE)
probability_vec <- (0:8)/8
colorvec <- kmcolors(probability_vec, cm.colors)
kmhasse(xpl$space, horizontal = TRUE, colors = colorvec)
```

### Plotting with `kmbasisdiagram()`
The `kmbasisdiagram` function draws a Hasse diagram of a basis similarly
to the `kmahsse` function.
```{r}
kmbasisdiagram(xpl$basis, horizontal=FALSE)
```

## Datasets provided by `kstMatrix`
The provided datasets were obtained by the research group around Cornelia Dowling by querying experts
in the respective fields. 

### cad
Six experts were queried about prerequisite relationships between 28 AutoCAD
knowledge items (Dowling, 1991; 1993a). A seventh basis represents those
prerequisite relationships on which the majority (4 out of 6) of the experts
agree (Dowling & Hockemeyer, 1998).
```{r}
summary(cad)
```

### readwrite
Three experts were queried about prerequisite relationships between 48 items
on reading and writing abilities (Dowling, 1991; 1993a). A fourth basis represents
those prerequisite relationships on which the majority of the experts agree
(Dowling & Hockemeyer, 1998).
```{r}
summary(readwrite)
```

### fractions
Three experts were queried about prerequisite relationships between 77 items
on fractions (Baumunk & Dowling, 1997). A fourth basis represents those
prerequisite relationships on which the majority of the experts agree
(Dowling & Hockemeyer, 1998).
```{r}
summary(fractions)
```

### xpl
This is just a small fictitious 4-item-example used for the examples in the
documentation.
```{r}
summary(xpl)
xpl$basis
xpl$space
xpl$data
```

## References
- Baumunk, K. & Dowling, C. E. (1997). Validity of spaces for assessing knowledge 
  about fractions. _Journal of Mathematical Psychology, 41,_ 99–105.
- Doignon, J.-P. & Falmagne, J.-C. (1999). _Knowledge Spaces._ Springer–Verlag, Berlin.
- Dowling, C. E. (1991). _Constructing Knowledge Structures from the Judgements of Experts._ 
  Habilitationsschrift, Technische Universität Carolo-Wilhelmina, Braunschweig, Germany.
- Dowling, C. E. (1993a). Applying the basis of a knowledge space for controlling the
  questioning of an expert. _Journal of Mathematical Psychology, 37,_ 21–48.
- Dowling, C. E. (1993b). On the irredundant construction of knowledge spaces.
  Journal of Mathematical Psychology, 37, 49–62.
- Dowling, C. E. & Hockemeyer, C. (1998). Computing the intersection of knowledge spaces using only 
  their basis. In Cornelia E. Dowling, Fred S. Roberts, & Peter Theuns, editors,
  _Recent Progress in Mathematical Psychology,_ pp. 133–141. Lawrence Erlbaum
  Associates Ltd., Mahwah, NJ.