% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/summary.colspace.R
\name{summary.colspace}
\alias{summary.colspace}
\title{Colourspace data summary}
\usage{
\method{summary}{colspace}(object, by = NULL, ...)
}
\arguments{
\item{object}{(required) a \code{colspace} object.}

\item{by}{when the input is in \code{tcs} colourspace, \code{by} is either
a single value specifying the range of colour points for which
summary tetrahedral-colourspace variables should be calculated (for example, \code{by} = 3
indicates summary will be calculated for groups of 3 consecutive colour points (rows)
in the quantum catch colour data frame) or a vector containing identifications for
the rows in the quantum catch colour data frame (in which case summaries will be
calculated for each group of points sharing the same identification). If \code{by}
is left blank, the summary statistics are calculated across all colour points in the
data.}

\item{...}{class consistency (ignored).}
}
\value{
returns all attributes of the data as mapped to the selected colourspace, including
options specified when calculating the visual model. Also return the default
\code{data.frame} summary, except when the object is the result of \code{\link[=tcspace]{tcspace()}},
in which case the following variables are output instead:
\itemize{
\item \verb{centroid.u, .s, .m, .l} the centroids of \code{usml} coordinates of points.
\item \code{c.vol} the total volume occupied by the points, computed with a convex
hull.
\item \code{rel.c.vol} volume occupied by the points (convex hull volume) relative to
the tetrahedron volume.
\item \code{colspan.m} the mean hue span.
\item \code{colspan.v} the variance in hue span.
\item \code{huedisp.m} the mean hue disparity.
\item \code{huedisp.v} the variance in hue disparity.
\item \code{mean.ra} mean saturation.
\item \code{max.ra} maximum saturation achieved by the group of points.
\item \code{a.vol} colour volume computed with \eqn{\alpha}{alpha}-shapes.
}
}
\description{
Returns the attributes of \code{colspace} objects.
}
\examples{
# Colour hexagon
data(flowers)
vis.flowers <- vismodel(flowers,
  visual = "apis", qcatch = "Ei", relative = FALSE,
  vonkries = TRUE, bkg = "green"
)
flowers.hex <- hexagon(vis.flowers)
summary(flowers.hex)

# Tetrahedral model
data(sicalis)
vis.sicalis <- vismodel(sicalis, visual = "avg.uv")
csp.sicalis <- colspace(vis.sicalis)
summary(csp.sicalis, by = rep(c("C", "T", "B"), 7))
}
\references{
Stoddard, M. C., & Prum, R. O. (2008). Evolution of avian plumage
color in a tetrahedral color space: A phylogenetic analysis of new world buntings.
The American Naturalist, 171(6), 755-776.

Endler, J. A., & Mielke, P. (2005). Comparing entire colour patterns
as birds see them. Biological Journal Of The Linnean Society, 86(4), 405-431.

Gruson H. (2020). Estimation of colour volumes as concave hypervolumes using
\eqn{\alpha}{alpha}-shapes. Methods in Ecology and Evolution, 11(8), 955-963
\doi{10.1111/2041-210X.13398}
}
\author{
Rafael Maia \email{rm72@zips.uakron.edu}
}
