---
title: "kstIO"
author: "Cord Hockemeyer"
date: "Version 0.6-0"
output: 
  html: 
    default
    fig_caption: true
vignette: >
  %\VignetteIndexEntry{kstIO}
  %\VignetteEngine{litedown::vignette}
  %\VignetteEncoding{UTF-8}
---

# Content

- [Introduction](#chp:introduction)
- [File formats](#chp:file-formats)
- [Supported data structures](#chp:supported-data-structures)
  - [`kstMatrix` classes](#sec:kstmatrix-classes)
  - [`kst` classes](#sec:kst-classes)
- [Functionality and default parameters](#chp:functionality-and-default-parameters)
  - [Function liest](#sec:function-list)
    - [Reading functions](#sec:reading-functions)
    - [Writing functions](#sec:writing-functions)
    - [Utilities](#sec:utilities)
  - [Function parameters](#sec:function-parameters)
    - [Mandatory parameeters](#sec:mandatory-parameters)
    - [Optional parameeters](#sec:optional-parameters)
- [Examples](#chp:examples)
  - [Setup](#sec:setup)
  - [Spreadsheet files](#sec:spreadsheet-files)
  - [ASCII file](#sec:ascii-file)

# Introduction
The current functionality of `kstIO` stems from two developmental processes:
- **File formats:** Earlier (pre--R) software developments used various ASCII 
  and binary file formats developed over time. Later, `kstIO` was extended
  to allow also for spreadsheet formats (CSV, ODS, and XLSX).
- **R package development** There are two general R packages on knowledge 
  space theory, `kst` and `kstMatrix`. The former uses sets and relations
  as representation, the latter uses matrices. The hope behind developing 
  `kstMatrix` was that matrices as *native* data type in R might be 
  processed faster than sets.
  
  `kstIO` was originally developed to offer I/O functions supporting the
  `kst` package and later extended to support also the meanwhile created
  `kstMatrix`package and its data object classes.
  
# File formats
## *Classical* ASCII file formats
The aforementioned binary file formats are not (and probably never 
will be) supported by `kstIO`. The ASCII formats are fully supported; they 
come in three different forms, each expanding the previous one by additional
header lines containing meta information.
- Matrix form: The matrix format files consist simply of a binary matrix,
  one row per knowledge state (or response pattern) and per--item columns.
  A cell contains a `1` if the respective item is element of the respective 
  knowledge state, and a `0` otherwise.
- KST form: The Matrix is simply preceded by two header lines containing 
  the number of items and the number of knowledge states (or response 
  patterns). 
- SRBT form: This form was developed in a project on surmise relations
  between tests (therefore the name). It expands the KST form by yet another
  preceding header line with information about the file content (e.g., basis,
  space, relation) and the storage format (ASCII vs. binary).
  
## Spreadsheet formats
The more recent spreadsheet formats comprise three types: CSV (comma-separated
values), ODS (Open Document Spreadsheet, e.g. by LibreOffice or OpenOffice),
and XLSX (Microsoft Excel). All `kstIO` I/O functions support all three 
spreadsheet types.

The spreadsheet tables have the same form in all three formats (CSV, ODS, 
and XHTML). They typically (exceptions are, e.g., surmise 
functions; see below) start with a header line containing the item names
followed by the binary matrix as described above for the ASCII files.
Surmise and attribution functions have an additional preceding column 
containing the name of the item for which the respective matrix row 
describes a clause.
  
# Supported data structures
Both basic KST packages, `kst` and `kstMatrix`, use hierarchies of R classes.
Class names in `kst` start with a 'k', those in `kstmatrix` with a 'km'. 
In principle, if an object belongs to some class, the `kst` and `kstMatrix`
functions assume that it fulfills the conditions of that class.

## `kstMatrix` classes
The subsequent figure (from the `kstMatrix` vignette) shows the class hierarchy 
in that package. It means, e.g., that `kmqspace` is a sub-class of `kmspace` 
which is a sub-class of `kmstructure` which again is a sub-class of `kmfamset`.

![](kstMatrixClasses_v2.jpeg)
Figure 1: `kstMatrix`class hierarchy

### List of `kstMatrix` classes
- **`kmfamset`:** Family of sets, i.e. the rows of the matrix are unique.
- **`kmbasis`:** Basis, i.e. a set of knowledge states (`kmfamset`) which are
  minimal for some item.
- **`kmstructure`:** Knowledge structure, i.e. a `kmfamset` which includes the 
  empty set and the full items set.
- **`kmspace`:** A knowledge space, i.e. a knowledge structure which is closed under union.
- **`kmqspace`:** A quasi--ordinal knowledge space, i.e. a knowledge space which 
  is **also** closed under intersection.
- **`kmmneighbourhood`:** A `kmfamset` including one knowledge state and its 
  neighbours. This class was introduced to allow for a respective `plot()`
  method.
- **`kmdata`:** A data set, i.e. a set of response patterns. Rows may be repeated
  multiply within the matrix.
- **`kmattributionrelation`:** Mathematically any binary relation on a set. Please
  note that rows and columns have different meanings in relations than in the
  previous classes.
- **`kmsurmiserelation`:** A surmise relation, i.e. mathematically a quasi--order.
- **`kmattributionfunction`:** A map assigning to each item one or more clauses.
  Technically, it is a data.frame where the first column contains the items and
  the subsequent columns the binary vector representing the clauses.
- **`kmsurmisefunction`:** An attribution function which is closed under 
  reflexivity, transitivity, and incomparability.

## `kst` classes
The class hierarchy of `kst` is very similar, basically it is a subset
because some functionality (and therefore several classes) have been developed
(or defined, respectively) in `kstMatrix` only. While `kstMatrix` class-names
start with 'km', the `kst` class-names start with a simple 'k'.

![](kstClasses.jpeg){width=350}    
Figure 2: `kst` class hierarchy

# Functionality and default parameters
For most of the data types shown in Figures 1 & 2, there are reading and 
writing functions as listed below. Exceptions to this are quasi--ordinal 
knowledge spaces (`kmqspace` class) and neighbourhoods (`kmneighbourhood`
class).

## Function list

### Reading functions
- read_kbase^1^
- read_kdata^2^
- read_kfamset^1^
- read_kspace^1^
- read_kstructure^1^
- read_attributionfunction^2^
- read_surmisefunction^2^
- read_attributionrelation^2^
- read_surmiserelation^2^

^1^These functions return a list with two elements, `matrix` and `sets`,
containing the loaded data in the respective form.
^2^These functions return the respective data as `kstMatrix` class object as 
there is no corresponding `kst` class.

### Writing functions
- write_kbase
- write_kdata
- write_kfamset
- write_kspace
- write_kstructure
- write attributionfunction
- write_surmisefunction
- write attributionrelation
- write_surmiserelation

These functions accept `kst` and `kstMatrix` data objects.

One might consider to integrate the `write` functions into one S3 class. 
However, for technical reasons this would not work for the `read` functions.

### Utilities
There are two utility functions mapping between set and matrix representations.
These functions do not respect the classes assigned to the objects which are 
to be mapped.
- as.binaryMatrix
- as.famset

## Function parameters
There are numerous parameters shared by most of the reading and writing 
functions. 

### Mandatory parameters
- For writing functions, the first mandatory parameter is the object to be 
  written.
- For all reading and writing functions, the specification of the filename is 
  mandatory.
  
### Optional parameters
- `format`: File format (see also above). There are the spreadsheet 
  formats 'CSV', 'ODS', and 'XLSX' which are usable with all functions. The 
  ASCII file formats 'matrix', 'KST', and 'SRBT' are only partially available. 
  Finally, the quasi-format 'auto' refers to auto-detection.
- `as.letters`: How to name items (for read functions). This can be either 
  alphabetic (alphanumeric for more than 26 items) or numeric (`as.letters` = 
  FALSE). If the file is in spreadsheet format with item names in a header row,
  this parameter is ignored.
- `header`: For reading spreadsheet files: Does the file have a header row?
  Default is always `TRUE`.
- `sep`: For reading or writing CSV files: Cell separator (maybe ',' (default)
  or ';').
- `enforce`: If `TRUE`, the properties of the  object class are 
  enforced by running the respective closure operator or constructor.
  `enforce`is `TRUE` by default. For writing functions, it will only be 
  observed if the object does not have the respective class.

Please note that not all optional parameters are supported by all functions. 
For example, there are no properties to be enforced with `kmdata` objects.

# Examples
For the following examples, we use the `xpl` basis from the `kstMatrix` package
just because the object and the resulting files are small.

## Setup
We start with some setup: importing libraries and defining filenames:
```{r setup}
library(kstIO)
library(kstMatrix)
csvname <- paste0(tempdir(), "/xpl_bas.csv")
odsname <- paste0(tempdir(), "/xpl_bas.ods")
srbtname <- paste0(tempdir(), "/xpl.bas")
```

The `xpl` basis looks like this:
```{r}
xpl$basis
```

## Spreadsheet files
First, we write the basis to a CSV file and print that file:
```{r comment=''}
write_kbase(xpl$basis, csvname)
cat(readLines(csvname), sep='\n')
```

Next, we write it to an ODS file and show a screenshot of that file opened in LibreOffice.
```{r comment=''}
write_kbase(xpl$basis, odsname)
odsname
```
![](Screenshot_ODS.jpeg){width=400}    
Figure 3: LibreOffice Screenshot with saved ODS format basis file

In the next step, we read the ODS file.
```{r comment=''}
read_kbase(paste0(tempdir(), "/xpl_bas.ods"))
```

## ASCII file
Finally, we write a *classical* ASCII file in SRBT format and print the file contents.
```{r comment=''}
write_kbase(xpl$basis, srbtname, format="SRBT")
cat(readLines(srbtname), sep='\n')
```