% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/seqdistMCSE.R
\name{seqdistMCSE}
\alias{seqdistMCSE}
\title{Mean and standard deviation of dissimilarities between pairs of randomly altered sequences.}
\usage{
seqdistMCSE(
  seqdata,
  method = "LCS",
  J = 1,
  R = 50,
  replic = "by.pair",
  verbose = TRUE,
  core = 1,
  unique = TRUE,
  model = "keep.dss",
  jfixed = FALSE,
  kchanges = NULL,
  ratios = TRUE,
  snow = TRUE,
  ...
)
}
\arguments{
\item{seqdata}{A state sequence \code{stslist} object as generated by \code{\link[TraMineR]{seqdef}}.}

\item{method}{Character string. Dissimilarity measure to compute distances. Default is \code{"LCS"}. See \code{\link[TraMineR]{seqdist}}.}

\item{J}{Integer or vector of positive numbers. If an integer, maximal timing error (number of unit periods around first state of new spell. Default is \code{J=1}.) If a vector, weights of the timing errors \code{k = -K, -(K-1), ..., K-1, K}, where \code{2K + 1} is the length of \code{J}. The vector length must be odd.}

\item{R}{Integer. Number of random replications of each sequence. Default is \code{R=50}.}

\item{replic}{Character string. One of \code{"by.pair"} (default) and \code{"once"}. When \code{"by.pair"} a fresh set of replications of the sequences is generated for each distance. When "once", replications of each sequence are generated once and reused for each distance involving the sequence.}

\item{verbose}{Logical. Should waiting and timing messages be printed?}

\item{core}{Integer. Number of cores to use for parallel computation.}

\item{unique}{Logical. Should simulations for distances between identical pairs of sequences be run only once? Default is \code{TRUE}.}

\item{model}{String. Time alteration model. One of \code{"keep.dss"} (default), \code{"indep"} (suppress spells erased by move of transition), and \code{"relative"} (keep time until next transitions unchanged).}

\item{jfixed}{Logical. Should same error j be applied to all transitions in a sequence? Default is \code{FALSE}.}

\item{kchanges}{Integer, string, or \code{NULL}. If integer, number of transitions whose time can potentially be altered. If \code{"rand"}, the number of potential changes is randomly selected for each sequence. If \code{NULL} (default), all transitions can potentially be altered.}

\item{ratios}{Logical. Should standardized ratios and the standard error of mean simulated distances be returned? Default is \code{TRUE}.}

\item{snow}{Logical. If \code{TRUE}, \code{doSNOW} is used for parallel computing, otherwise \code{doParallel} is used.}

\item{...}{Further arguments passed to \code{\link[TraMineR]{seqdist}}.}
}
\value{
A list of class \code{distMC} with for each pairwise distance: \cr - \code{MC.mean} (\code{dist} object) MC means of distances between MC-replicated sequences,\cr - \code{MC.se} (\code{dist} object) MC standard deviations of distances between MC-replicated sequences, \cr - \code{args.dist} list of arguments  passed to \code{seqdist}, \cr - \code{diss.o} (\code{dist} object) observed distances between sequences, \cr and when \code{ratios = TRUE}: \cr - \code{diss.z} (\code{dist} object) ratios \code{diss.u/MC.se}, \cr - \code{MC.mean.z} (\code{dist} object) ratios  \code{MC.mean/mean.se}, \cr - \code{mean.se} (\code{dist} object) standard errors of \code{MC.mean}.
}
\description{
For each pair of sequences, returns the mean and standard deviation (MCSE) of the dissimilarities between all combinations of MC-replicated sequences, where sequences are replicated with random timing changes.
}
\details{
Let \eqn{B_x} be the set of \code{R} sequences derived from a sequence \eqn{x} by randomly altering the timing of the transitions (state changes) in \eqn{x}. The MC standard error of the dissimilarity \eqn{d(x,y)} between two sequences \eqn{x} and \eqn{y} is the empirical standard deviation of the dissimilarities between the sequences of \eqn{B_x} and those of \eqn{B_y}. There are \code{R^2} such MC-simulated dissimilarities for each pair of observed sequences.

By default, MC standard errors are computed for distances between unique sequences and results are then expanded to all sequences. In addition, results for pairs of identical sequences are expanded to all such pairs in \code{seqdata}. With \code{unique=FALSE}, the computation is redone for each identical pairs and, therefore, results can vary across such identical pairs. Setting \code{unique=TRUE} (default) can save much computation time when same sequences occur multiple times.

A progress bar is displayed when \code{verbose=TRUE}. However, the progress bar works only with option \code{snow=TRUE} for parallel computing.

\code{seqdistMCSE} is much slower than \code{\link{MCseqdistSE}}, which considers only distances within sets of replicated sequences (generated with \code{\link{MCseqReplicate}}) instead of all combinations of replicated sequences.
}
\examples{
## mini test data, 6 sequences of length 4, 4 unique sequences
exdata <- read.table(text="
                a a b b
                a a b b
                b b a a
                a c c b
                b b a c
                b b a c
                ")
weights=rep(1, nrow(exdata))
s.exdata <- seqdef(exdata, weights = weights, id=paste("id",1:nrow(exdata), sep=""))

## Here we call function seqdistMCSE
MCd <- seqdistMCSE(s.exdata, method="LCS", J=1, R=50, core=1, verbose=TRUE)

## Results for distances between first sequences
MCd

## Summary statistics refer to all distances between original sequences
summary(MCd)
}
\references{
Liao, T.F. and G. Ritschard (2023). Evaluating uncertainty of dissimilarity measures between state sequences.
Manuscript in preparation.
}
\seealso{
\code{\link{MCseqdistSE}}, \code{\link{print.distMC}}, \code{\link{summary.distMC}}, and \code{\link{MCratios}}
}
\author{
Gilbert Ritschard
}
