\encoding{UTF-8}
\name{read_kdata}
\alias{read_kdata}
\title{Read a response patterns file}

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

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

\arguments{
  \item{filename}{A character string specifying the name of the data 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.}
}

\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 value \code{"auto"} (default)
  requests an automatic detection of the format by thje \code{read_XXX}
  function. 

  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 binary matrix with the response patterns.}

\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.
}

\author{Cord Hockemeyer \email{cord.hockemeyer@uni-graz.at}}

\seealso{\link{kstIO-package}
}

\examples{
# Produce a data file
d <- getwd()
setwd(tempdir())
space <- kmunionclosure(phsg$basis)
data <- kmsimulate(space, 10, 0.1, 0.05)
write_kdata(data, "phsg.ods", "ODS") # matrix format (without any headers)
# Read file; only the first ten rows of the matrix are printed by default
read_kdata("phsg.ods") # Automatic format detection (default)
data <- read_kdata("phsg.ods", "ODS") # Explicit format specification
data
dim(data)
setwd(d)
}

\keyword{file}
