patternize - An R package for quantifying color pattern variation

Quantifying variation in color patterns to study and compare the consistency of their expression necessitates the homologous alignment and color-based segmentation of images. Patternize is an R package that quantifies variation in color patterns as obtained from image data. Patternize defines homology between pattern positions across specimens either through fixed landmarks or image registration. Pattern identification is performed by categorizing the distribution of colors using either an RGB threshold or an unsupervised image segmentation. The quantification of the color patterns can be visualized as heat maps and compared between sets of samples.

Please do not hesitate to contact me with any questions or suggestions!

Install patternize in R from CRAN (not up to date at this time!!):

install.packages("patternize")

Install patternize in R from GitHub using devtools:

install.packages("devtools")
library(devtools)
install_github("StevenVB12/patternize")
# Morpho has committed a change that affects computeTransform used in
# the patternize functions patLanRGB and patLanK (not available in CRAN)
install_github("zarquon42b/Morpho")

Installation errors

Some people have noted platform specific installation errors (mostly Mac). If you don't find your solution here, please contact me.

error: unable to load shared object 
'/Library/Frameworks/R.framework/Versions/3.4/Resources/library/rgl/libs/rgl.so'

Solution: download XQuartz https://www.xquartz.org 

For examples see package examples or https://github.com/StevenVB12/patternize-examples

Workflow

Setting landmarks

I set landmarks using the Fiji distribution of ImageJ (https://fiji.sc/):

Fiji
> File > open (image)
> Multi-point (make sure points are set in the same order for each sample)
> Save As > XY coordinates

But you can also use (setting a resampleFactor > 0 speeds up things, but reduces resolution):

landmarkList <- sampleLandmarks(sampleList, resampleFactor = NULL, crop = c(0,0,0,0))

If you are working with Heliconius or related butterflies, consider using this landmark scheme:

Setting RGB value

You can assign an RGB vector manually (e.g. RGB <- c(255,0,0) for red) or use:

RGB <- sampleRGB(image, resampleFactor = NULL, crop = c(0,0,0,0))

Making cartoon for plotting (or masking)

To plot a cartoon of the organism or trait of interest I use XY coordinates of an outline or lines obtained in the Fiji distribution of ImageJ (https://fiji.sc/). This is an annoying manual task, but if done precisely it can provide an outline or cartoon for any type of shape. The cartoon should be drawn for the reference (target) image when using image registration (patRegRGB or patRegK) or when using landmark transformation to a target image (patLanRGB or patLanK; transformRef = 'sample_ID'). When using transformRef = 'meanshape', the cartoon will also be transformed to the mean shape.

outline

Fiji
> File > open (image)
> Polygon selections (draw outline)
> Save As > XY coordinates

lines (same as setting landmarks)

Fiji
> File > open (image)
> Multi-point (draw lines by setting points)
> Save As > XY coordinates

Calibrate images using ColorChecker

The ColorChecker (Macbeth ColorChecker) is a color calibration target consisting of a framed arrangement of 24 squares of painted samples. The chart patches are selected to mimic those of natural objects and to have consistent color appearance under a variety of lighting conditions. By including this chart in an image, it can be used to calibrate images taken in different lightning conditions.

You can calibrate images like this:

IDlist <- c('image1', 'image2')
extension <- '.jpg'
colorChecker(IDlist, extension)

The function is also available as a stand alone app: https://stevenvanbelleghem.shinyapps.io/shiny_colorchecker/ (see https://github.com/StevenVB12/shiny_ColorChecker)

This calculates a second order polynomial regression between the observed and expected RGB values of the 24 ColorChecker patches and performs the calibration of the image. The function will ask you to define the corners of the ColorChecker like this (also works for images taken with a skew angle):