% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hsa_quant.R
\name{hsa_quant}
\alias{hsa_quant}
\title{Quantify the stability of hespdiv clusters}
\usage{
hsa_quant(obj, probs = c(0.05, 0.5, 0.95))
}
\arguments{
\item{obj}{An object of class \code{hsa}.}

\item{probs}{A numeric vector of probabilities with values in the range
\eqn{0 \le p \le 1}. This argument is used to calculate quantiles of Jaccard similarity
values.}
}
\value{
A list containing three data frames:
\describe{
\item{jaccard.quantiles}{
Quantiles of Jaccard similarities between the basal cluster and
the analog clusters from alternative subdivisions.
}
\item{jaccard.similarity}{
Jaccard similarity values between the basal cluster and the analog
cluster from each alternative subdivision.
}
\item{analog.clusters}{
IDs of the hespdiv polygons that produced the analog clusters
in each alternative subdivision.
}
}
}
\description{
This function evaluates the stability of the basal subdivision
clusters using hespdiv sensitivity analysis results. It does so by
calculating Jaccard similarities between the observations of basal
subdivision clusters and the observations of alternative subdivision
clusters. For each basal cluster, the function identifies the most similar
analog cluster within each alternative subdivision. The stability of
each basal cluster can be assessed by examining the distribution of
similarity values with their corresponding analog clusters. If a highly
similar cluster reappears in multiple alternative subdivisions, it
indicates that the basal cluster is stable.
}
\details{
If a base subdivision cluster obtains a distribution of high similarity
values, it is considered stable and existing. Low analog-cluster similarity
values may indicate that a base cluster is an artifact of the
\code{hespdiv()} computation.

The more technical description of how \code{hsa_quant} works:
\describe{
\item{Obtaining alternative hespdiv clusters:}{ The function filters the \code{xy.dat} coordinates of the basal subdivision using all the polygons of alternative subdivisions, obtaining alternative hespdiv clusters.}
\item{Quantifying Jaccard similarity:}{ The function measures the Jaccard overlap index between the observations of the basal subdivision clusters and the observations of the alternative clusters. }
\item{Identification of analog clusters and value assignments:}{ Each basal hespdiv cluster from each alternative subdivision is assigned the ID of the cluster that produced the maximum Jaccard similarity value, along with the corresponding similarity value.}
}
The purpose of the \code{hsa_quant} function is to address situations where hespdiv
polygons, despite having different geometry and location, may filter nearly
identical sets of observations, leading to similar hespdiv clusters. This can occur when the spatial
coverage of observations is incomplete and irregular, or when the boundaries
between hespdiv polygons are expected to be open, soft, or fuzzy, such as in
the case of boundaries between bioregions. In such cases, visual hespdiv
sensitivity analysis alone may show irregular and non-converging
distributions of split-lines. However, \code{hsa_quant} can reveal that these
irregular polygons are based on nearly identical clusters of observations,
indicating a strong spatial structure within the analyzed data. Conversely,
if the observations within these clusters significantly differ, it indicates
that the basal clusters are specific to the hespdiv parameters used and
likely lack ontological meaning.

Thus, by analyzing the similarity values between clusters of observations, \code{hsa_quant}
facilitates the assessment of the stability and reliability of basal
subdivision clusters, aiding in evaluating their significance.
}
\note{
You can use the hsa_quant function to track the evolution of hespdiv
subdivisions over time by providing correctly formatted input. For
instance, you can obtain the basal subdivision for time bin 1 using the
hespdiv function. Then, using the hsa function, you can specify the paired
xy.dat and data from time bin 2. The resulting hsa object can be inputted
into \code{hsa_quant} The \code{hsa_quant} result will then provide insights into
extinctions, speciations, fusions, and splits of hespdiv polygons/clusters
that occur between time bin 1 and 2. This allows for the analysis of changes
and dynamics in hespdiv subdivisions over time.
}
\seealso{
Other functions for hespdiv sensitivity analysis: 
\code{\link{change_base}()},
\code{\link{hsa}()},
\code{\link{hsa_detailed}()},
\code{\link{hsa_sample_constrained}()},
\code{\link{plot_cs_hsa}()},
\code{\link{plot_hsa}()},
\code{\link{plot_hsa_q}()}

Other functions to evaluate hesdpiv cluster stability: 
\code{\link{plot_hsa_q}()}

Other functions for hespdiv results post-processing: 
\code{\link{cross_comp}()},
\code{\link{hsa}()},
\code{\link{hsa_detailed}()},
\code{\link{hsa_sample_constrained}()},
\code{\link{nulltest}()},
\code{\link{taxon_effect}()}
}
\author{
Liudas Daumantas
}
\concept{functions for hespdiv results post-processing}
\concept{functions for hespdiv sensitivity analysis}
\concept{functions to evaluate hesdpiv cluster stability}
