Using PaCeQuantAna to analyze and visualize feature values extracted from Pavement cell microscopy images with PaCeQuant

Set up the working environment

Load the PaCeQuantAna package with library(PaCeQuantAna).

Set the path to you prefered working directory with setwd("path"). By default the working directory is the currently selected directory.

Set the name of the output folder with setOutputFolder("name_of_folder"). All results (figures and tables) are stored below this output folder. When invoking the function setOutputFolder("name_of_folder") folders for storing the results in a structured way a generated, e.g. folders for storing box_plots, histograms or stats.

Set the path to the directory that contains the data fulfilling the PaCeQuant output structure with setDataDir("path_to_data").

Set up the meta data corresponding to the feature data

Read the meta data containing file with readDescriptionFile("data_description.csv"). The function readDescriptionFile("data_description.csv") expects an “*.csv” file named “data_description.csv” located in the selected output folder. It has to be placed there manually by an experienced user or can be created with default values with createDescriptionFileTemplate(filename="my_data_description_file.csv"). The content of the data description file is organized in a tabular. It has as many rows as folders in the chosen data directory and five columns. The columns contain definitions that are used for producing plots, e.g. plot labels, plot order, colors or font shape (e.g. normal, italic or bold).

Structure of a data description file generated with createDescriptionFileTemplate()

group	plot_labels	plot_order	plot_colors	plot_font
folder 1	folder 1	1	#FF0000FF	1
folder 2	folder 2	2	#00FF00FF	1
folder 3	folder 3	3	#0000FFFF	1
…	…	…	…	…

The entries in the last four columns can be customized by the user to affect the look of the plots. Also, complete rows can be deleted if a certain species, time point or treatment should be excluded from analysis. The names in the first column have to correspond to the names of the folders (representing the groups) that contain the “results” folders and should not be changed.

Loading and quality checking the data

Load cell shape feature data with data <- readFeatureData(). This function checks if a data description file was provided and loads data if it is in the correct structure. The function will read all “*-table.txt” files recursively from the data directory (and folders specified in the data description file). Each feature table file corresponds to an image and each line within a feature table corresponds to a cell. For each cell the corresponding image and region IDs, the name of the folder (which corresponds to a group e.g. species) and the feature values are stored in a list object named data. Names of the list elements will have the prefix raw.

For a quality check of the data invoke printStatsOnCells(data,type="raw",printToFile=FALSE). This function will print the number of images per group, cells per group, and cells per image and group either to the console or a file. The number of cells detected per image should be similar within a group and between different groups if all advices of proper image preparation and processing were followed, e.g. same conditions for taking the picture and same parameter settings in PaCeQuant. Images having a very low number of cells compared to the others should be checked by manual inspection. A low number of detected cells could result from bad image quality or a non-optimal parameter setting in the image processing with PaCeQuant.

Setting or determining cell size thresholds

Size thresholds (on cell areas) can be set, e.g., to remove small cells such as stomata cells, meristemoids or small pavement cells, which are not yet differentiated. By default all analysis procedures run without size filtering. An a priori size filtering can also be done with PaCeQuant. For cell size filtering two values are needed: first an upper bound for small cell sizes (small or \(t_s\)) and second an upper bound for medium size cells (medium or \(t_m\)). All cells having a size above \(t_m\) are referred to as large. There a different ways to set size thresholds:

• setDefaultSizeThresholds(): Set the size thresholds according to experimentally determined thresholds (in microns) for size categorization as reported in Möller, Poeschl, and Bürstenbinder (2017)

• setSizeThresholds(ts=1400, tm=4042): Set user-selected cell size thresholds for small (\(< t_s\)), medium (\(≥ t_s\) & \(< t_m\)) and large cells (\(≥ t_m\)) in the same unit as selected in the PaCeQuant processing. Default values correspond to the values set in setDefaultSizeThresholds().

• determineCustomSizeThresholds(data, quantile=0.9): Thresholds are determined from data. This function is currently under construction…

These size thresholds have different meaning depending on the context of follow up analyses. In case of a time series analysis the thresholds can be used to define developmental stages of the pavement cells based on there sizes. In case of comparative analyses (which is also possible for a time series data set) the thresholds are used to filter out small cells and to retain cells of almost equal sizes.

Analysis of developmental stages (cells of different size)

For studies on developmental stages time series data is recommended.

To visualize the distribution of cell sizes between different time points in a histogram use plotHistogramOnArea(data, type="raw", show_ts=TRUE, show_tm=TRUE). Earlier time points should contain more smaller cells than later time points.

The values of all 27 features within the defined size categories (developmental stages) and between the individual time points can be visualized in box plots using boxplotsOnDevelopmentalStages(data). This function produces a pdf file for each of the four feature groups containing the box plots for each of the features, in which features are boxed according to the time point and size category (developmental stage).

Comparative analyses of cells of the same developmental stage (cells of similar size)

For comparative analysis of shape features values of cell with similar size (and same developmental stage) between different groups, such as species, genotypes, time points or treatments, small cells have to be filtered out. Remaining cells should have initiated lobe formation and expansion already. Filter out stomata cells and too small pavement cells with data <- filterOutSmallCells(data). This function applies the previously defined threshold for small size cells \(t_s\) and extends the list object data with new list elements which will have the prefix filtered and small. Nothing is discarded, the raw data is split into filtered and small.

To check the number of remaining cells for each group after filtering invoke printStatsOnCells(data,type="filtered",printToFile=FALSE).

Descriptive comparisons

For descriptive analyses the PaCeQuantAna package provides plot functions to visualize different aspects of the feature values. These plot functions generate almost publication ready figures. The default font family is Arial. All plots are saved as *.pdf files in a way that they can be modified with external graphical editors like Inkscape…

Provided plot functions are:

• Histograms on the cell areas use

  plotHistogramOnArea(data, type="filtered")

• Histograms of all cell shape features use

  plotHistograms(data, type="filtered")

• Box plots of all cell shape features can be generated with

  plotBoxplots(data, type="filtered")

• Violin plots of all cell shape features are created using

  plotViolinplots(data, type="filtered")

• Cumulative distributions of all cell shape features are plotted with

  plotCumulativeDistributions(data, type="filtered")

• Scatter plots of each feature versus all other features are created with

  plotScatterplots(data, type="filtered")

Notes:

All figures are stored in intuitively-named folders in the selected output folder.

All plot functions can be invoked on the types raw, filtered and small.

Statistical comparisons

Additionally the PaCeQuantAna package provides functions for comparative statistical analyses. Statistical comparative analyses are done between all groups (defined in the data description file) by applying for each feature a Kruskal-Wallis-test and post-hoc Dunn-tests of all pairwise combinations of all groups. These statistical tests can be performed by invoking kwDunnTest(data, type="filtered") on the data object.

Resulting p values are saved in two separate files, one for the Kruskal-Wallis-tests and one for the Dunn-tests. p values resulting from the Dunn-tests are additionally visualized in a heatmap where the values are replaced by colors and significance is labled with * padj < 0.05, ** padj < 0.01, *** padj < 0.001. Tables containing the p values and the heatmap are saved in the output folder.