% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/imagine-main.R
\name{convolution2D}
\alias{convolution2D}
\alias{convolutionQuantile}
\alias{convolutionMedian}
\title{Make convolution calculations from numeric matrix}
\usage{
convolution2D(X, kernel, times = 1, normalize = FALSE, na_only = FALSE)

convolutionQuantile(
  X,
  kernel,
  probs,
  times = 1,
  normalize = FALSE,
  na_only = FALSE
)

convolutionMedian(X, kernel, times = 1, na_only = FALSE)
}
\arguments{
\item{X}{A numeric \code{matrix} object used for apply filters.}

\item{kernel}{A little matrix used as mask for each cell of \code{X}.}

\item{times}{How many times do you want to apply the filter?}

\item{normalize}{\code{logical} indicating if results will (or not) be
normalized. See details.}

\item{na_only}{\code{logical}, Do you want to apply the filter ONLY in cells
with NA?}

\item{probs}{\code{numeric} vector of probabilities with values in [0,1].}
}
\value{
\code{convolution2D} returns a \code{matrix} object with the same
dimensions of \code{X}.

\code{convolutionQuantile} uses the kernel but, for each cell, it
returns the position of quantile 'probs' (value between 0 and 1).

\code{convolutionMedian} is a wrapper of \code{convolutionQuantile}
with probs = 0.5.
}
\description{
This function takes a \code{matrix} object, and for each cell
multiplies its neighborhood by the \code{kernel}. Finally, it returns for
each cell the mean of the kernel-weighted sum.
}
\details{
Convolution is a mathematical operation that combines two arrays of numbers
to produce an array of the same structure. The output will consist of only
valid values, meaning those where both arrays have non-missing data.
Consequently, any missing values (NAs) in the input matrix will propagate
outwards to the extent of the convolution kernel.

Through normalization, the output of each convolution window is scaled by
dividing it by the sum of the absolute values of the kernel
(\code{sum(abs(as.numeric(kernel)))}, disabled by default).

\code{na_only} performs two actions at once: (1) it applies the filter only in
the positions where the original value is \code{NA} and (2) for the rest of
the cells, it is replaced with the value of the original matrix.
}
\examples{
# Generate example matrix
nRows <- 50
nCols <- 100

myMatrix <- matrix(runif(nRows*nCols, 0, 100), nrow = nRows, ncol = nCols)
kernel <- diag(3)

# Make convolution
myOutput1 <- convolution2D(myMatrix, kernel)
myOutput2 <- convolutionQuantile(myMatrix, kernel, probs = 0.7)

# Plot results
par(mfrow = c(2, 2))
image(myMatrix, zlim = c(0, 100))
image(myOutput1, zlim = c(0, 100))
image(myOutput2, zlim = c(0, 100))
}
