---
title: "CbKST---Functions for Competence-Based Knowledge Space Theory"
author: "Cord Hockemeyer"
date: "`{r} format(Sys.time(), '%B %d, %Y')`"
output: html
vignette: >
  %\VignetteIndexEntry{CbKST}
  %\VignetteEngine{litedown::vignette}
  %\VignetteEncoding{UTF-8}

---

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

# Table of contents
- [Introduction](#chp:introduction)
- [Geneeral remarks](#chp:general-remarks)
  - [Some general remarks on the competence extension to KST](#sec:some-general-remarks-on-the-competence-extension-to-kst)
  - [Core data structure](#sec:core-data-structure)
  - [File format](#sec:file-format)
- [Functions in CbKST](#chp:functions-in-cbkst)
  - [Input/Output](#sec:input-output)
    - [Example](#sec:example_1)
  - [Mapping states between skills and performances](#sec:mapping-states-between-skills-and-performances)
    - [Example](#sec:example_2)
  - [Mapping structures between skills and performances](#sec:mapping-structures-between-skills-and-performances)}
    - [Example](#sec:example_3)
  - [Example data](#sec:example-data)
- [References](#chp:references)


# Introduction
Knowledge space theory (KST) was founded by Doignon and Falmagne (1985, 1999; see also Falmagne et al., 2013; Heller & Stefanutti,
2024a) as a means for
efficient adaptive assessment of knowledge. Efficiency here means that the number of items tested should be relatively small. KST
models prerequisite relationships between test items and infers from previous answers to the mastery of other items based on these
prerquisites. However, it is a behavioral model, i.e. it does not look into the skills and competencies underlying the response
behaviour.

Competence-based Knowledge Space Theory (CbKST; see, e.g., Doignon, 1994; Düntsch & Gediga, 1995; Korossy, 1997; Albert & Lukas, 
1999; Heller et al., 2006, Heller et al., 2013, Heller & Stefanutti, 2024b) aims at mending this. Its core element are skill maps 
or skill multimaps assigning to each test items the skills and competencies required for solving it.

# General remarks

## Some general remarks on the competence extension to KST
In the context of knowledge space theory, the terms _skill_ and _competence_ are often used synonymously. When skill multimaps are used, however, there is a clear distinction: competences are the subsets of skills assigned to an item through the skill multimap. The competences are interpreted as alternative sets of prerequisites for solving the item, especially for different possible solujtion paths.

It should be noticed that, for two competence states $C$ and $C'$ and the corresponding performance states $P$ and $P'$, the
performance state corresponding to $C\cup C'$ is not necessarily $P\cup P'$ but may be a (strict) superset of it. As a consequence,
the performance structure corresponding to a competence space (`cbkst_performancestructure(multimap, comp)`) is not necessarily 
a performance space, i.e. closed under union. Also, if we map an arbitrary subset $P$ of test items with `cbkst_perf2comp()`
to the minimal competence states and map them back to the performance level with `cbkst_comp2perf()`, we may obtain a larger 
subset $P'\supset P$; more concretely, we would obtain one or more performance states, actually the minimal ones containing $P$.

## Core data structure
While generally, CbKST focuses on skill maps with skill multimaps as an extension allowing for different solution paths for the 
test items, within the implementation of the `CbKST` package, the skill multimaps are the core element and basic object class.
Skill maps are a mere special case (and thus a sub class) of skill multimaps. Practically, both classes are identical, i.e. data 
frames. These data frames contain item IDs in the first columns and a binary matrix in subsequent columns (one per skill) where 
a '1' denotes the case that a skill is a prerequisite for the mastery of the respective test item (and '0' otherwise). If a skill
multimap data frame has exactly one row per test item, it describes a skill map.

## File format
Skill (multi-) map files can be in ODS or XLSX spreadsheet format. Their table layout is basically the same as the data frame 
structure. A preceding header row contains the skill IDs in the columns 2 to $n$. The first entry in the header row is not used 
by the functions in `CbKST`.

```{r message=FALSE}
exampledata$mu
```


# Functions in `CbKST`

## Input/Output
We start CbKST activities with reading a skill (multi) map from file. This is done through `read_skillmultimap()`. For practical
reasons, only spreadsheet format files are allowed, currently concretely ODS (Libreoffice/Openoffice) and XLSX (Microsoft Excel)
format. CSV files (comma separated values) may follow at a later time.

The `read_skillmultimap()` function is deliberately kept simple, it takes a filename as only parameter. This includes certain
assumptions, e.g. the existence of a header row in the file containing the skill names (see next section).

### Example
```{r message=FALSE}
fpath <- system.file("extdata", "skillmap.ods", package="CbKST")
sm <- read_skillmultimap(fpath)
sm
class(sm)
fpath <- system.file("extdata", "multimap.ods", package="CbKST")
mm <- read_skillmultimap(fpath)
mm
class(mm)
```
As can be seen in the code and results above, the result of  `read_skillmultimap()` is of class `cbkst_skillmultimap`. If, 
however, we have the special case of a skill map, i.e. every item is assigned exactly one competence, the result belongs
additionally also to class `cbkst_skillmap`.

## Mapping states between skills and performances
There are three functions mapping states between skill/competence and performance level. `cbkst_comp2per()` determines the
subset of items (performance state) solvable by a person in a given skill state. In the counter direction, `cbkst_perf2comp()`
determines the minimal skill states (as binary matrix of class `kmfamset`) allowing for a specified performance state. This function can also regard an additionally
specified skill structure further constraining the result. A simplified variant is `cbkst_simple_perf2comp()` which required
a skill map (instead of a more general skill multimap) as parameter and does not allow for further constraints through a 
competence structure. Here, the result is again (like in `cbkst_comp2perf()`) a single state (as a vector). 

Please note that for 
`cbkst_perf2comp()` and `cbkst_simple_perf2comp()`, the performance state must be specified as a named vector. The item IDs
of the performance state must fit to the item IDs used in the skill (multi) map.

### Example
```{r message=FALSE}
cbkst_comp2perf(c(1,1,0,0), exampledata$mu)
perf <- c(1,1,1,0,0)
names(perf) <- c("z", "y", "x", "w", "v")
cbkst_perf2comp(perf, exampledata$multi, exampledata$cspace)
cbkst_simple_perf2comp(perf, exampledata$mu)
```


## Mapping structures between skills and performances
The functions `cbkst_performaancestructure()` and `cbkst_competencestructure()` map whole structures. `cbkst_performancestructure()`
determines the family of all subset of test items which are a performance state for some competence state. 
` cbkst_competencestructure()` on the other hand provides all minimal competence states behind some performance state.

### Example
```{r message=FALSE}
cbkst_performancestructure(exampledata$mu)
cbkst_performancestructure(exampledata$mu, comp=exampledata$cspace)
cbkst_competencestructure(exampledata$multi)
cbkst_competencestructure(exampledata$multi, perf=exampledata$pspace)
```

## Example data
The `CbKST` package provides some example data --- mainly for testing and illustration. They can be accessed as elements of the 
list `exampledata`.
- `mu` is a skill map on five test items and four skills.
- `multi` is a very similar skill multi map.
-` cpsace` and `pspace` are simple competence and performance spaces. Actually both follow a linear structure between the items 
or skills, repetively.

```{r}
exampledata
```

These data are in parallel also given as files in the package's `extdata` directory. The file path can be built as shown below.
```{r message=FALSE}
fpath <- system.file("extdata", "skillmap.ods", package="CbKST")
```
The following four files are provided:
- `linearCompSpace.ods` is a linear skill/competence space --- the same as `exampledata$cspace`.
- `linearPerfSpace.ods` is teh pendant on the performance level --- `exampledata.pspace`.
- `multimap.ods` and `skillmap.ods` contain the skill multimap and skill map also available as `exampledata$multi`
and `exampledata$mu`.


# References
- Albert D & Lukas J (eds.) (1999). _Knowledge Spaces: Theories, Empirical Research, Applications._ Lawrence Erlbaum Associates,
  Mahwah, NJ. 
- Doignon J (1994). Knowledge spaces and skill assignments. In Fischer GH, Laming D (eds.), _Contributions to Mathematical 
  Psychology, Psychometrics, and Methodology,_ 111–121. Springer, New York. 
- Doignon J & Falmagne J (1985). Spaces for the assessment of knowledge. _International Journal of Man-Machine Studies, 23,_
  175–196. 
- Doignon J & Falmagne J (1999). _Knowledge Spaces._ Springer–Verlag, Berlin. 
- Düntsch I & Gediga G (1995). Skills and Knowledge Structures. _British Journal of Mathematical and Statistical Psychology, 48,_
  9–27. 
- Falmagne J, Albert D, Doble C, Eppstein D, & Hu X (eds.) (2013). _Knowledge Spaces: Applications in Education._ Springer,
  Heidelberg. 
- Heller J & Stefanutti L (eds.) (2024a). _Knowledge Structures: Recent Developments in Theory and Application,_ volume 7 of 
  _Advanced Series on Mathematical Psychology._ World Scientific, Singapore. doi:10.1142/13519. 
- Heller J & Stefanutti L (2024b). Knowledge Structures and Their Competence–Based Extension. In Heller J & Stefanutti L (eds.),
  _Knowledge Structures: Recent Developments in Theory and Application,_ volume 7 of _Advanced Series on Mathematical Psychology,_
  3–26. World Scientific, Singapore. doi:10.1142/9789811280481_0001. 
- Heller J, Steiner C, Hockemeyer C, & Albert D (2006). Competence–Based Knowledge Structures for Personalised Learning. 
  _International Journal on E–Learning, 5(1),_ 75-88. 
- Heller J, Ünlü A, & Albert D (2013). Skills, Competencies and Knowledge Structures. In Falmagne J, Albert D, Doble C, 
  Eppstein D, Hu X (eds.), _Knowledge Spaces: Applications in Education,_ 229–242. Springer, Heidelberg. 
- Korossy K (1997). Extending the Theory of Knowledge Spaces: A Competence–Performance Approach. _Zeitschrift für Psychologie, 205,_
  53–82.