convolutions: Make convolution calculations from numeric matrix

In imagine: IMAGing engINEs, Tools for Application of Image Filters to Data Matrices

Make convolution calculations from numeric matrix

Description

This function takes a matrix object, and for each cell multiplies its neighborhood by the kernel. Finally, it returns for each cell the mean of the kernel-weighted sum.

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

X	A numeric matrix object used for apply filters.
kernel	A little matrix used as mask for each cell of X.
times	How many times do you want to apply the filter?
normalize	logical indicating if results will (or not) be normalized. See details.
na_only	logical, Do you want to apply the filter ONLY in cells with NA?
probs	numeric vector of probabilities with values in [0,1].

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 (sum(abs(as.numeric(kernel))), disabled by default).

na_only performs two actions at once: (1) it applies the filter only in the positions where the original value is NA and (2) for the rest of the cells, it is replaced with the value of the original matrix.

Value

convolution2D returns a matrix object with the same dimensions of X.

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

convolutionMedian is a wrapper of convolutionQuantile with probs = 0.5.

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))

imagine documentation built on April 3, 2025, 7:24 p.m.