% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/read_SPE2R.R
\name{read_SPE2R}
\alias{read_SPE2R}
\title{Import Princeton Instruments (TM) SPE-file into R}
\usage{
read_SPE2R(
  file,
  output.object = "RLum.Data.Image",
  frame.range = NULL,
  txtProgressBar = TRUE,
  verbose = TRUE,
  ...
)
}
\arguments{
\item{file}{\link{character} (\strong{required}):
SPE-file name (including path), e.g.
\itemize{
\item \verb{[WIN]}: \code{read_SPE2R("C:/Desktop/test.spe")}
\item \verb{[MAC/LINUX]}: \code{read_SPE2R("/User/test/Desktop/test.spe")}.
Additionally, it can be a URL starting with \verb{http://} or \verb{https://}.
}}

\item{output.object}{\link{character} (\emph{with default}):
set the output object type. Allowed types are \code{"RLum.Data.Spectrum"},
\code{"RLum.Data.Image"} or \code{"matrix"}.}

\item{frame.range}{\link{vector}, \link{integer} (\emph{optional}):
range of frames to read. For example, \code{frame.range = c(1, 10)} selects only
the first 10 frames. If not specifie, all available frames (up to a maximum
of 100 if \code{output.object = "RLum.Data.Image"}) are read.}

\item{txtProgressBar}{\link{logical} (\emph{with default}):
enable/disable the progress bar. Ignored if \code{verbose = FALSE}.}

\item{verbose}{\link{logical} (\emph{with default}): enable/disable output to the
terminal.}

\item{...}{not used, for compatibility reasons only.}
}
\value{
Depending on the chosen option the functions returns three different
type of objects:

\code{output.object}

\code{RLum.Data.Spectrum}

An object of type \linkS4class{RLum.Data.Spectrum} is returned.  Row
sums are used to integrate all counts over one channel.

\code{RLum.Data.Image}

An object of type \linkS4class{RLum.Data.Image} is returned.  Due to
performance reasons the import is aborted for files containing more than 100
frames. This limitation can be overwritten manually by using the argument
\code{frame.range}.

\code{matrix}

Returns a matrix of the form: Rows = Channels, columns = Frames. For the
transformation the function \link{get_RLum} is used,
meaning that the same results can be obtained by using the function
\link{get_RLum} on an \code{RLum.Data.Spectrum} or \code{RLum.Data.Image} object.
}
\description{
The function imports Princeton Instruments (TM) SPE-files into R and
provides \linkS4class{RLum.Data.Image} objects as output. The import
functionality is based on the file format description provided by
Princeton Instruments and a MatLab script written by Carl Hall (see
references).
}
\note{
\strong{The function does not test whether the input data are spectra or pictures for spatial resolved analysis!}

The function has been successfully tested for SPE format versions 2.x.

\emph{Currently not all information provided by the SPE format are supported.}
}
\section{Function version}{
 0.1.5
}

\examples{

## to run examples uncomment lines and run the code

##(1) Import data as RLum.Data.Spectrum object
#file <- file.choose()
#temp <- read_SPE2R(file)
#temp

##(2) Import data as RLum.Data.Image object
#file <- file.choose()
#temp <- read_SPE2R(file, output.object = "RLum.Data.Image")
#temp

##(3) Import data as matrix object
#file <- file.choose()
#temp <- read_SPE2R(file, output.object = "matrix")
#temp

##(4) Export raw data to csv, if temp is a RLum.Data.Spectrum object
# write.table(x = get_RLum(temp),
#             file = "[your path and filename]",
#             sep = ";", row.names = FALSE)

} 

\section{How to cite}{
Kreutzer, S., 2025. read_SPE2R(): Import Princeton Instruments (TM) SPE-file into R. Function version 0.1.5. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., Steinbuch, L., Boer, A.d., 2025. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 1.1.2. https://r-lum.github.io/Luminescence/
}

\references{
Princeton Instruments, 2014. Princeton Instruments SPE 3.0 File
Format Specification, Version 1.A (for document URL please use an internet search machine)

Hall, C., 2012: readSPE.m.
\verb{https://www.mathworks.com/matlabcentral/fileexchange/35940-readspe}
}
\seealso{
\link{readBin}, \linkS4class{RLum.Data.Spectrum}
}
\author{
Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany)
, RLum Developer Team}
\keyword{IO}
