--- 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') ```