% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/trajCluster.R
\name{trajCluster}
\alias{trajCluster}
\title{Calculate clusters for back trajectories}
\usage{
trajCluster(
  traj,
  method = "Euclid",
  n.cluster = 5,
  type = "default",
  cols = "Set1",
  split.after = FALSE,
  map.fill = TRUE,
  map.cols = "grey40",
  map.alpha = 0.4,
  projection = "lambert",
  parameters = c(51, 51),
  orientation = c(90, 0, 0),
  by.type = FALSE,
  origin = TRUE,
  plot = TRUE,
  ...
)
}
\arguments{
\item{traj}{An openair trajectory data frame resulting from the use of
\code{importTraj}.}

\item{method}{Method used to calculate the distance matrix for the back
trajectories. There are two methods available: \dQuote{Euclid} and
\dQuote{Angle}.}

\item{n.cluster}{Number of clusters to calculate.}

\item{type}{\code{type} determines how the data are split i.e. conditioned,
and then plotted. The default is will produce a single plot using the
entire data. Type can be one of the built-in types as detailed in
\code{cutData} e.g. \dQuote{season}, \dQuote{year}, \dQuote{weekday} and so
on. For example, \code{type = "season"} will produce four plots --- one for
each season. Note that the cluster calculations are separately made of each
level of "type".}

\item{cols}{Colours to be used for plotting. Options include
\dQuote{default}, \dQuote{increment}, \dQuote{heat}, \dQuote{jet} and
\code{RColorBrewer} colours --- see the \code{openair} \code{openColours}
function for more details. For user defined the user can supply a list of
colour names recognised by R (type \code{colours()} to see the full list).
An example would be \code{cols = c("yellow", "green", "blue")}}

\item{split.after}{For \code{type} other than \dQuote{default} e.g.
\dQuote{season}, the trajectories can either be calculated for each level
of \code{type} independently or extracted after the cluster calculations
have been applied to the whole data set.}

\item{map.fill}{Should the base map be a filled polygon? Default is to fill
countries.}

\item{map.cols}{If \code{map.fill = TRUE} \code{map.cols} controls the fill
colour. Examples include \code{map.fill = "grey40"} and \code{map.fill =
  openColours("default", 10)}. The latter colours the countries and can help
differentiate them.}

\item{map.alpha}{The transparency level of the filled map which takes values
from 0 (full transparency) to 1 (full opacity). Setting it below 1 can help
view trajectories, trajectory surfaces etc. \emph{and} a filled base map.}

\item{projection}{The map projection to be used. Different map projections
are possible through the \code{mapproj} package. See \code{?mapproject} for
extensive details and information on setting other parameters and
orientation (see below).}

\item{parameters}{From the \code{mapproj} package. Optional numeric vector of
parameters for use with the projection argument. This argument is optional
only in the sense that certain projections do not require additional
parameters. If a projection does not require additional parameters then set
to null i.e. \code{parameters = NULL}.}

\item{orientation}{From the \code{mapproj} package. An optional vector
c(latitude, longitude, rotation) which describes where the "North Pole"
should be when computing the projection. Normally this is c(90, 0), which
is appropriate for cylindrical and conic projections. For a planar
projection, you should set it to the desired point of tangency. The third
value is a clockwise rotation (in degrees), which defaults to the midrange
of the longitude coordinates in the map.}

\item{by.type}{The percentage of the total number of trajectories is given
for all data by default. Setting \code{by.type = TRUE} will make each panel
add up to 100.}

\item{origin}{If true a filled circle dot is shown to mark the receptor
point.}

\item{plot}{Should a plot be produced? \code{FALSE} can be useful when
analysing data to extract plot components and plotting them in other ways.}

\item{...}{Other graphical parameters passed onto \code{lattice:levelplot}
and \code{cutData}. Similarly, common axis and title labelling options
(such as \code{xlab}, \code{ylab}, \code{main}) are passed to
\code{levelplot} via \code{quickText} to handle routine formatting.}
}
\value{
an \link[=openair-package]{openair} object. The \code{data} component contains
both \code{traj} (the original data appended with its cluster) and \code{results}
(the average trajectory path per cluster, shown in the \code{trajCluster()}
plot.)
}
\description{
This function carries out cluster analysis of HYSPLIT back trajectories. The
function is specifically designed to work with the trajectories imported
using the \code{openair} \code{importTraj} function, which provides
pre-calculated back trajectories at specific receptor locations.
}
\details{
Two main methods are available to cluster the back trajectories using two
different calculations of the distance matrix. The default is to use the
standard Euclidian distance between each pair of trajectories. Also available
is an angle-based distance matrix based on Sirois and Bottenheim (1995). The
latter method is useful when the interest is the direction of the
trajectories in clustering.

The distance matrix calculations are made in C++ for speed. For data sets of
up to 1 year both methods should be relatively fast, although the
\code{method = "Angle"} does tend to take much longer to calculate. Further
details of these methods are given in the openair manual.
}
\examples{
\dontrun{
## import trajectories
traj <- importTraj(site = "london", year = 2009)
## calculate clusters
clust <- trajCluster(traj, n.cluster = 5)
head(clust$data) ## note new variable 'cluster'
## use different distance matrix calculation, and calculate by season
traj <- trajCluster(traj, method = "Angle", type = "season", n.cluster = 4)
}
}
\references{
Sirois, A. and Bottenheim, J.W., 1995. Use of backward trajectories to
interpret the 5-year record of PAN and O3 ambient air concentrations at
Kejimkujik National Park, Nova Scotia. Journal of Geophysical Research, 100:
2867-2881.
}
\seealso{
Other trajectory analysis functions: 
\code{\link{importTraj}()},
\code{\link{trajLevel}()},
\code{\link{trajPlot}()}

Other cluster analysis functions: 
\code{\link{polarCluster}()},
\code{\link{timeProp}()}
}
\author{
David Carslaw
}
\concept{cluster analysis functions}
\concept{trajectory analysis functions}
