\encoding{UTF-8}
\name{read_kbase}
\alias{read_kbase}
\title{Read base file}

\description{
  Read a base from
  a file. The file formats are described in the \link{kstIO-package}
  information page.
}

\usage{
  read_kbase(filename, 
             format = "auto", 
             as.letters = TRUE, 
             header = TRUE,
             sep = ',',
             enforce = TRUE)
}

\arguments{
  \item{filename}{A character string specifying the name of the base file.}

  \item{format}{Specification of the files format. Can be "SRBT", "KST",
    "matrix", "CSV", or "auto" (default).}
  \item{as.letters}{logical, should the elements of the sets be letters
                    or numbers?}
  \item{header}{For spreadsheet files only: does the file contain a header row?}
  \item{sep}{For CSV files only: character separating cells within a row.}
  \item{enforce}{Should we enforce that the result is really a basis, i.e. should we run \link[kstMatrix]{kmbasis}  on it?}
}

\details{
  The \code{format} values \code{"SRBT"}, \code{"KST"}, and 
  \code{"matrix"} refer to the different generations of file formats 
  described in \link{kstIO-package}. The values \code{"CSV"}, \code{"ODS"}, and
  \code{"XLSX"} refer to the respective spreadsheet file formats.
  The value \code{"auto"} (default) requests an automatic detection of the format. 

  If \code{as.letters} is \code{TRUE} the item names are letters,
  otherwise numbers. If the data are read from a spreadsheet file (CSV, XLSX, or ODS)
  containing a header row, item names are taken from there. If they are read from
  a spreadsheet file without header, the reading function automatically assigns
  item names from \code{"V1"} to \code{"Vn"} where \code{n} is the number of items.
}

\value{A list with the following elements:
  \item{matrix}{the read structure/data as binary matrix}
  \item{sets}{the read structure as object of class \code{kbase}
  }
}

\references{
  Hockemeyer, C. (2001). \emph{KST Tools User Manual} (2nd ed.). 
  \url{https://resources.cord-hockemeyer.info/techreports/KST-Tools_TechRep_FWF01.pdf}.

  Poetzi, S. & Wesiak, G. (2001). SRbT Tools User Manual.
  \url{https://resources.cord-hockemeyer.info/techreports/SRBT-Tools_TechRep_FWF01.pdf}
}

\note{In automatic format detection, the distinction between \code{"matrix"}
  and \code{"KST"} formats work somewhat heuristic. In other words, in rare
  cases the automatic detection might give the wrong result.
}

\seealso{\code{\link[kst]{kbase}}, \code{\link[kstMatrix]{kmbasis}},
	 \link{kstIO-package}
}

\examples{
# Produce a base file
library(kstIO)
d <- getwd()
setwd(tempdir())
write_kbase(phsg$basis, "phsg.bas", "KST") # (Old) KST format
# Read file
read_kbase("phsg.bas") # Automatic format detection
read_kbase("phsg.bas", "KST") # Explicit format specification
setwd(d)
}

\keyword{file}
