% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/moc-gapbk.R
\name{moc.gapbk}
\alias{moc.gapbk}
\alias{moc.gabk}
\title{Multi-Objective Clustering Guided by a-Priori Biological Knowledge (MOC-GaPBK)}
\usage{
moc.gapbk(
  dmatrix1,
  dmatrix2,
  num_k,
  generation = 50,
  pop_size = 10,
  rat_cross = 0.8,
  rat_muta = 0.01,
  tour_size = 2,
  neighborhood = 0.1,
  local_search = FALSE,
  cores = 2
)

moc.gabk(...)
}
\arguments{
\item{dmatrix1}{A square distance matrix. Must have the same
dimensions as \code{dmatrix2}.}

\item{dmatrix2}{A square distance matrix. Must have the same
dimensions as \code{dmatrix1}. Typically encodes a-priori
biological knowledge.}

\item{num_k}{The number \eqn{k} of clusters represented by medoids in
each individual. Must be greater than 1.}

\item{generation}{Number of generations to be performed. Default 50.}

\item{pop_size}{Size of the population. Default 10.}

\item{rat_cross}{Probability of crossover. Default 0.80.}

\item{rat_muta}{Probability of mutation. Default 0.01.}

\item{tour_size}{Size of the tournament for parent selection. Default 2.}

\item{neighborhood}{Percentage of neighborhood used by Pareto Local
Search. A real value between 0 and 1. The neighborhood size is
computed as \code{neighborhood * num_objects}. Default 0.10.}

\item{local_search}{Logical. If \code{TRUE}, Path-Relinking (PR) and
Pareto Local Search (PLS) are applied as intensification and
diversification strategies. Default \code{FALSE}.}

\item{cores}{Number of cores used by Path-Relinking. Default 2.}

\item{...}{Arguments passed to \code{\link{moc.gapbk}}.}
}
\value{
A named list with three elements:
\describe{
  \item{\code{population}}{A data frame containing the final
    population of medoids together with the values of the two
    objective functions, the Pareto ranking and the crowding
    distance, ordered accordingly.}
  \item{\code{matrix.solutions}}{A data frame whose columns are
    clustering solutions on the Pareto front. Each row corresponds
    to an object and each cell to its assigned cluster.}
  \item{\code{clustering}}{A list of named integer vectors. Element
    \code{i} is the partition produced by the \eqn{i}-th solution
    on the Pareto front.}
}
}
\description{
Performs the MOC-GaPBK algorithm proposed by Parraga-Alava and others
(2018). It receives two distance matrices and returns a set of
non-dominated clustering solutions.
}
\details{
MOC-GaPBK couples NSGA-II with Path-Relinking and Pareto Local Search.
Two versions of the Xie-Beni validity index are used as objectives,
one per distance matrix.

\code{moc.gabk} (note the single \code{p}) is a deprecated alias kept
for backward compatibility with versions 0.1.x. New code should call
\code{moc.gapbk} directly.
}
\examples{
set.seed(1)
x <- matrix(stats::runif(50 * 20, min = -5, max = 10),
            nrow = 50, ncol = 20)

# Two distance matrices from base R; in real applications dmatrix2
# typically encodes a-priori biological knowledge (e.g. GO semantic
# similarity). See vignette("moc-gapbk-intro") for examples using
# amap::Dist() with correlation-based distances.
dmatrix1 <- as.matrix(stats::dist(x, method = "euclidean"))
dmatrix2 <- as.matrix(stats::dist(x, method = "manhattan"))

res <- moc.gapbk(dmatrix1, dmatrix2, num_k = 3,
                 generation = 5, pop_size = 6)

head(res$matrix.solutions)

}
\references{
J. Parraga-Alava, M. Dorn, M. Inostroza-Ponta (2018). \emph{A
multi-objective gene clustering algorithm guided by apriori
biological knowledge with intensification and diversification
strategies}. BioData Mining. 11(1) 1-16.
\doi{10.1186/s13040-018-0178-4}.

K. Deb, A. Pratap, S. Agarwal, T. Meyarivan (2002). \emph{A fast and
elitist multiobjective genetic algorithm: NSGA-II}. IEEE Transactions
on Evolutionary Computation, 6(2) 182-197.

F. Glover (1997). \emph{Tabu Search and Adaptive Memory Programming -
Advances, Applications and Challenges}. Interfaces in Computer
Science and Operations Research. 1-75.

J. Dubois-Lacoste, M. Lopez-Ibanez, T. Stutzle (2015). \emph{Anytime
Pareto local search}. European Journal of Operational Research,
243(2) 369-385.
}
\author{
Jorge Parraga-Alava, Marcio Dorn, Mario Inostroza-Ponta
}
