Last data update: 2014.03.03

R: Software for high throughput phenotyping of fruit crops
GiNA-packageR Documentation

Software for high throughput phenotyping of fruit crops

Description

GiNA is a package designed for automatic highthoroughput phenotyping analysis of images. The program was conceived to read files with .JPG and .TIFF extensions (which stands for Joint Picture Experts Group) and uses image segmentation based on the EBImage package in order to recognize fruits and compute its features such as area, perimeter, color (in 3 channels), shape and volume to be used for GWAS, QTL or descriptive studies. The core of the package relays in 3 functions; 1) cutoff is the function in charge of determining the best cut off value for segmentation, the color scale in R goes from 0 to 1 and in other siftwares from 0 to 265, the function detects the color of the background (black or white) and returns several pictures of segmentation at different cutoff values in order to pick the most suitable for your crop, 2) pixArea reads the pictures and returns a plot with the pixel area for each object in the picture in order to provide an estimate of the minimum value to use in the real analysis, the value obtained from this function should be passed to the scanCRAN function as the minArea to discard all noise from the picture, 3) scanCRAN is the core of the package and performs image analysis for all pictures stored in the folder path provided at the cutoff value selected. The output from the scanCRAN function is a list structure with each element of the list being a dataframe with all measurements for the fruits or objects found in the picture.

Additional plotting functions to visualize the data have been provided such as color.plot which displays the digital color detected by the computer for each picture, the input of this function is the output of the scanCRAN function. The function jet.scan returns a heat.map of the variability found in the pictures and takes the same input than 'color.plot' function. For additional information such as tutorials and most recent releases please visit our website http://cggl.horticulture.wisc.edu/software/.

We have spent valuable time developing this package, please cite it in your publication:

Diaz-Garcia L, Covarrubias-Pazaran G, Schlautman B, Zalapa J. GiNA: A flexible high throughput phenotyping tool. http://horticulture.wisc.edu/cggl/ZalapaLab/People.html. 2015.

Author(s)

Luis Diaz-Garcia, Giovanny Covarrubias-Pazaran, Brandon Schlautman, Juan Zalapa.

References

Diaz-Garcia L, Covarrubias-Pazaran G, Schlautman B, Salazar W, Zalapa J. (2015) GiNA: A flexible high throughput phenotyping tool. http://horticulture.wisc.edu/cggl/ZalapaLab/People.html. 2015.

Ben Hui Liu. 1998. Statistical Genomics. CRC Press LLC. ISBN 0-8493-3166-8.

See Also

http://cggl.horticulture.wisc.edu/software/

Examples

####=========================================####
#### For CRAN time limitations most lines in the 
#### examples are silenced with one '#' mark, 
#### remove them and run the examples
####=========================================####

###########################################
###            GiNA package            ####
###########################################

# XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
###########################################
### call library 
library(GiNA)

### XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
###########################################
### EXPLORE YOUR DATA FIRST TO DETERMINE THE 'minArea' AND 'cutoff' VALUES
### indicate folder where sample pictures are, i.e.
### folder <- "C:/Users/zalapalab/Desktop/examp"

### for demonstration purposes we will call a sample picture
### included in the package, run the following 4 lines

data(GINA.sample) # RUN
display(GINA.sample)
writeImage(GINA.sample, "gina_cran.JPG") # RUN
folder <- getwd() # RUN

### XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
############################################
### check the best cutoff values for your pictures

?cutoff
cutoff(folder, cores=1) # RUN

### go to your working directory and analyze the segmentation
### results, you will agree with us than 0.5 is the best value
### for segmentation in the 'cutoff_vals' folder FOR THIS SAMPLE PICTURE

### XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
############################################
### check the best minimum area (in pixels) 
### to get rid of little trashes in the picture
### can be provided to the scanCRAN function if 
### you don't like the default

?pixArea
#area <- pixArea(folder,cutoffvalue=0.5,cores=1) # RUN!!!

### XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
###########################################
### RUN the scanCRAN function providing your
### cutoff and minimum area values found previously

?scanCRAN
#folder <- getwd()
#mydata <- scanCRAN(folder,cutoffvalue=0.5,cores=1, fact = 1) # RUN!!!
#str(mydata) # RUN!!!

### XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
###########################################
### see colors of your fruits in each picture

#color.plot(mydata) # RUN!!!
#jet.scan(mydata, var=3) # RUN!!!

### XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
###########################################

Results


R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(GiNA)
Loading required package: EBImage
Loading required package: png
Loading required package: parallel
Loading required package: doParallel
Loading required package: foreach
Loading required package: iterators
> png(filename="/home/ddbj/snapshot/RGM3/R_CC/result/GiNA/GiNA-package.Rd_%03d_medium.png", width=480, height=480)
> ### Name: GiNA-package
> ### Title: Software for high throughput phenotyping of fruit crops
> ### Aliases: GiNA
> ### Keywords: package
> 
> ### ** Examples
> 
> ####=========================================####
> #### For CRAN time limitations most lines in the 
> #### examples are silenced with one '#' mark, 
> #### remove them and run the examples
> ####=========================================####
> 
> ###########################################
> ###            GiNA package            ####
> ###########################################
> 
> # XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
> ###########################################
> ### call library 
> library(GiNA)
> 
> ### XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
> ###########################################
> ### EXPLORE YOUR DATA FIRST TO DETERMINE THE 'minArea' AND 'cutoff' VALUES
> ### indicate folder where sample pictures are, i.e.
> ### folder <- "C:/Users/zalapalab/Desktop/examp"
> 
> ### for demonstration purposes we will call a sample picture
> ### included in the package, run the following 4 lines
> 
> data(GINA.sample) # RUN
> display(GINA.sample)
> writeImage(GINA.sample, "gina_cran.JPG") # RUN
> folder <- getwd() # RUN
> 
> ### XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
> ############################################
> ### check the best cutoff values for your pictures
> 
> ?cutoff
cutoff                  package:GiNA                   R Documentation

_F_i_n_d_i_n_g _t_h_e _o_p_t_i_m_a_l _c_u_t_o_f_f _v_a_l_u_e _f_o_r _s_e_g_m_e_n_t_a_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     This function reads the picture provided in a path and performs
     image segmentation in a gray scale version of the picture at
     different values of color between 0 and 1 depending of the
     background color. If the background is black the function will
     segment the picture at values of 0.01 to 0.12 and if a white
     background is used values 0.5 to 0.8 will be used in order to
     determine the optimal value of segmentation, such values can be
     modified by the user in the argument `prefs`. The resulting images
     at different cutoff values will be stored in a folder created with
     the name `cutoff_vals` in the same folder provided by the user.

_U_s_a_g_e:

     cutoff(folder, cores = 1, prefs = NULL)
     
_A_r_g_u_m_e_n_t_s:

  folder: A path where the sample pictures are located.

   cores: A scalar value indicating the number of cores that you want
          to use for parallelizing the function, default is 1

   prefs: a vector containing the values of the cutoffvalues to be used
          in the analysis.

_D_e_t_a_i_l_s:

     In image analysis segmentation can be done based on different
     parameters, the most common way to do it is by maximizing the
     contrast of a background with the object of study (i.e. fruits).
     Most software uses white or black backgrounds to maximize the
     contrast with the objects, but a cuttoff value needs to be set in
     order to get accurate estimates of the objects in the pictures.
     GiNA has been optimized to be used with any background but an
     initial cutoff value needs to be provided to the core function
     'scanCRAN'. The purpose of this function is to try different
     cutoff values and decide the optimal.

_V_a_l_u_e:

     If parameters are indicated correctly the function returns:

     $pics pictures in a folder named "cutoff_vals" with different
          values for segmentation to help the user define the optimum
          cutoff value for the crop.

_R_e_f_e_r_e_n_c_e_s:

     We have spent valuable time developing this package, please cite
     it in your publication:

     Diaz-Garcia L, Covarrubias-Pazaran G, Schlautman B, Zalapa J.
     GiNA: A flexible high throughput phenotyping tool.
     http://horticulture.wisc.edu/cggl/ZalapaLab/People.html. 2015.

_E_x_a_m_p_l_e_s:

     library(GiNA)
     
     data(GINA.sample) # RUN
     display(GINA.sample)
     writeImage(GINA.sample, "gina_cran.JPG") # RUN
     folder <- getwd() # RUN
     ?cutoff
     cutoff(folder, cores=1) # RUN
     

> cutoff(folder, cores=1) # RUN

You are using 1 core(s) out of 4 available

Please monitor the progress of the segmentation for the different values of color threshold at the folder:
/home/ddbj/DataUpdator-rgm3/target/cutoff_vals

You selected to test the following values:

 0.5, 0.55, 0.6, 0.65, 0.7, 0.75, 0.8 if background is white, or
 0.01, 0.03, 0.05, 0.07, 0.09, 0.11 if background is black. 

Please check the segmentation pictures and decide the best value of segmentation for posterior analysis


Please remember to use the optimum cutoff value we have found for the posterior functions 

See the results in the folder: 

 /home/ddbj/DataUpdator-rgm3/target/cutoff_vals 

> 
> ### go to your working directory and analyze the segmentation
> ### results, you will agree with us than 0.5 is the best value
> ### for segmentation in the 'cutoff_vals' folder FOR THIS SAMPLE PICTURE
> 
> ### XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
> ############################################
> ### check the best minimum area (in pixels) 
> ### to get rid of little trashes in the picture
> ### can be provided to the scanCRAN function if 
> ### you don't like the default
> 
> ?pixArea
pixArea                  package:GiNA                  R Documentation

_F_i_n_d_i_n_g _t_h_e _a_v_e_r_a_g_e _a_r_e_a _i_n _p_i_x_e_l_s _f_o_r _o_b_j_e_c_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     Even not required, the average value area in pixels for the
     objects analyzed is a parameter of interest when the objects to be
     analyzed are particularly small such as seeds or extremely small
     fruits. Therefore, the use of this function provides a plot of the
     are in pixels for all the objects in the picture for a given
     cutoff value provided. Once the value has determined this can be
     provided to the 'scanCRAN' function in the argument `minArea` to
     make the function perform faster.

_U_s_a_g_e:

     pixArea(folder, cutoffvalue = 0.5, cores = 1, square = 10, fact = 0.25)
     
_A_r_g_u_m_e_n_t_s:

  folder: A path where the pictures are located

cutoffvalue: A scalar value where the fruits are distinguishable from
          the background in the color scale handled by R which is 0-1

   cores: A scalar value indicating the number of cores that you want
          to use for parallelizing the function

  square: size of the square to brush smaller objects from the picture

    fact: a scalar value between 0-1 indicating at what extent the
          picture should be reduced in size in order to make
          computations faster, by default the pictures are sized at the
          25 percent of their original size. If no reduction is
          required the user should set the argument to 1.

_V_a_l_u_e:

     If parameters are indicated correctly the function returns:

     $plot a plot showing the size of different objects in the picture
          in number of pixels.

_R_e_f_e_r_e_n_c_e_s:

     We have spent valuable time developing this package, please cite
     it in your publication:

     Diaz-Garcia L, Covarrubias-Pazaran G, Schlautman B, Zalapa J.
     GiNA: A flexible high throughput phenotyping tool.
     http://horticulture.wisc.edu/cggl/ZalapaLab/People.html. 2015.

_E_x_a_m_p_l_e_s:

     library(GiNA)
     data(GINA.sample) # RUN
     display(GINA.sample)
     writeImage(GINA.sample, "gina_cran.JPG") # RUN
     folder <- getwd() # RUN
     area <- pixArea(folder,cutoffvalue=0.5,cores=1) # RUN!!!
     

> #area <- pixArea(folder,cutoffvalue=0.5,cores=1) # RUN!!!
> 
> ### XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
> ###########################################
> ### RUN the scanCRAN function providing your
> ### cutoff and minimum area values found previously
> 
> ?scanCRAN
scanCRAN                 package:GiNA                  R Documentation

_H_i_g_h _t_h_r_o_u_g_h_p_u_t _p_h_e_n_o_t_y_p_i_n_g _u_s_i_n_g _s_c_a_n_C_R_A_N

_D_e_s_c_r_i_p_t_i_o_n:

     This function is the core of the GiNA package which is in charge
     of reading the pictures find in the folder provided and perform
     the image segmentation in order to find the objects in the picture
     (i.e. fruits) and measure parameters such as area, perimeter,
     shape, volume, gray color, red, green and blue color.

_U_s_a_g_e:

     scanCRAN(folder, cutoffvalue=NULL, minArea = NULL, 
             cores = 1, gray = TRUE, stand = c(0, 0), 
             fact = 0.25)
     
_A_r_g_u_m_e_n_t_s:

  folder: A path where the pictures are located

cutoffvalue: A scalar value (0-1) where the fruits are distinguishable
          from the background in the color scale handled by R which is
          0-1. if not passed the function will determine the color of
          the background and assign the value of 0.08 if black and 0.6
          if white. We highly recommend to use the 'cutoff' function to
          find the optimum segmentation value which will determine the
          success of your experiment.

 minArea: A scalar number indicating the minimum size in pixels for a
          real object in the picture to avoid the program to confuse
          some little trash with an object. The function 'cutoff' can
          provide an idea of the sizes of real objects and noise. If
          not passed the argument uses minArea=(length/40)*(width/40),
          where length and width refers to the dimensions of the
          picture

   cores: A scalar value indicating the number of cores that you want
          to use for parallelizing the function

    gray: a TRUE/FALSE value indicating if the user want the color to
          bereturned in grayscale besides the RGB color

   stand: a vector with 2 scalar values for width and length of your
          references

    fact: a scalar value between 0-1 indicating at what extent the
          picture should be reduced in size in order to make
          computations faster, by default the pictures are sized at the
          25 percent of their original size. If no reduction is
          required the user should set the argument to 1.

_D_e_t_a_i_l_s:

     In order to exploit the advantages of this function we highly
     recommend the users to determine the best cutoff value with the
     use of the 'cutoff' function to achieve a good segmentation of the
     objects. The package is sensitive to the prescense of shades in
     the picture, for that reason we highly recommend the use of black
     background and reference circles in a clear color (i.e. white).

     This is a rough idea of how you should take the pictures, where
     the circles are your references and the dots are your fruits. Your
     fruits shouldn't block the references and YOUR REFERENCES SHOULD
     BE ALWAYS ON THE SIDES OF YOUR PICTURE.

     O . .  .  .  O

     O .  .  .  .  . O

     O .  .  . .  . O

     For additional information such as tutorials and most recent
     releases please visit our website
     http://cggl.horticulture.wisc.edu/software/.

_V_a_l_u_e:

     If parameters are indicated correctly the function returns:

     $x3 a list of dataframes, one for each picture provided. The
          dataframe contains the measurements for each object (rows)
          found in the puncture for the variables (columns) area,
          perimeter, length, width, shape (ratio of length/width),
          volume and red, green, blue, grey color.

_R_e_f_e_r_e_n_c_e_s:

     We have spent valuable time developing this package, please cite
     it in your publication:

     Diaz-Garcia L, Covarrubias-Pazaran G, Schlautman B, Zalapa J.
     GiNA: A flexible high throughput phenotyping tool.
     http://horticulture.wisc.edu/cggl/ZalapaLab/People.html. 2015.

_E_x_a_m_p_l_e_s:

     library(GiNA)
     data(GINA.sample) # RUN
     writeImage(GINA.sample, "gina_cran.JPG") # RUN
     folder <- getwd()
     mydata <- scanCRAN(folder,cutoffvalue=0.5,cores=1, fact = 1) # RUN!!!
     

> #folder <- getwd()
> #mydata <- scanCRAN(folder,cutoffvalue=0.5,cores=1, fact = 1) # RUN!!!
> #str(mydata) # RUN!!!
> 
> ### XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
> ###########################################
> ### see colors of your fruits in each picture
> 
> #color.plot(mydata) # RUN!!!
> #jet.scan(mydata, var=3) # RUN!!!
> 
> ### XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX #
> ###########################################
> 
> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>