Content

• Introduction
• File formats
• Supported data structures
  • kstMatrix classes
  • kst classes
• Functionality and default parameters
  • Function liest
    • Reading functions
    • Writing functions
    • Utilities
  • Function parameters
    • Mandatory parameeters
    • Optional parameeters
• Examples
  • Setup
  • Spreadsheet files
  • 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 kstMatrixpackage 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.

Figure 1: kstMatrixclass 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’.

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¹
• read_kdata²
• read_kfamset¹
• read_kspace¹
• read_kstructure¹
• read_attributionfunction²
• read_surmisefunction²
• read_attributionrelation²
• read_surmiserelation²

¹These functions return a list with two elements, matrix and sets, containing the loaded data in the respective form. ²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. enforceis 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:

library(kstIO)

#> Loading required package: sets
#> Loading required package: kstMatrix
#> Loading required package: openxlsx2
#> Loading required package: readODS
#> Loading required package: tools

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:

xpl$basis

a	b	c	d
1	0	0	0
0	1	0	0
1	0	1	0
0	1	1	0
1	1	0	1

Spreadsheet files

First, we write the basis to a CSV file and print that file:

write_kbase(xpl$basis, csvname)
cat(readLines(csvname), sep='\n')

"a","b","c","d"
1,0,0,0
0,1,0,0
1,0,1,0
0,1,1,0
1,1,0,1

Next, we write it to an ODS file and show a screenshot of that file opened in LibreOffice.

write_kbase(xpl$basis, odsname)
odsname

[1] "/tmp/RtmpOFTD0Y/xpl_bas.ods"

Figure 3: LibreOffice Screenshot with saved ODS format basis file

In the next step, we read the ODS file.

read_kbase(paste0(tempdir(), "/xpl_bas.ods"))

$matrix
     a b c d
[1,] 1 0 0 0
[2,] 0 1 0 0
[3,] 1 0 1 0
[4,] 0 1 1 0
[5,] 1 1 0 1
attr(,"class")
[1] "kmbasis"  "kmfamset" "matrix"   "array"   

$sets
{{"a"}, {"b"}, {"a", "c"}, {"b", "c"}, {"a", "b", "d"}}

ASCII file

Finally, we write a classical ASCII file in SRBT format and print the file contents.

write_kbase(xpl$basis, srbtname, format="SRBT")
cat(readLines(srbtname), sep='\n')

#SRBT v2.0 basis
4
5
1000
0100
1010
0110
1101