utilities: Various utility functions used by ZooImage
In zooimage: Analysis of Numerical Plankton Images

Description Usage Arguments Details Value Author(s) See Also Examples

These functions are usually not called directly by the user, but they are interesting for developers.

sampleInfo(filename, type = c("sample", "fraction", "image", "scs",
    "date", "id", "frac", "imgnbr"), ext = "_dat[135][.]zim$")

underscoreToSpace(string)
trimString(string)

listSamples(ZIobj)
makeId(ZIDat)
addClass(ZIDat, ZIobj)
calcVars(x, drop.vars = NULL, drop.vars.def = dropVars())
dropVars()

ecd(area, cells = 1)

parseIni(data, label = "1")

calibrate(ODfile)

getDec()

zipNoteAdd(zipfile, zimfile)
zipNoteGet(zipfile, zimfile = NULL)

makeZIVignettes(orig.dir = getwd(), target.dir = dirname(orig.dir), clean.work = FALSE)

`filename`	name of a file from which to extract information. It is supposed to be spelled as: SCS.xxxx-xx-xx.SS+Fnn.ext where 'SCS' is the series-cruise-station code, 'xxxx-xx-xx' is the date of collection (year-month-day), 'SS' is the unique sample identifier, 'F' is the fraction, 'nn' is the image number (when there are several images per fraction) or 'nn.mmm' when there are 'mmm' pictures taken to cover a bigger area of cell 'nn', and 'ext' is the file extension.
`type`	the type of data to extract (see examples) for `sampleInfo()`, or the type of file to select in `selectFile()`.
`ext`	the pattern to use (regular expression) to eliminate file extension from the 'filename'.
`string`	a character string to rework, or a vector of character strings.
`ZIobj`	a ZooImage object (here, a 'ZIDat', 'ZIDesc', 'ZITrain' or 'ZITest' object; most probably one of the last two for `addClass()`).
`ZIDat`	a 'ZIDat' object, or a data frame with correct column labels.
`x`	a data frame, but most probably, a 'ZIDat' object.
`drop.vars`	a character vector with names of variables to drop, or `NULL` (by default) to keep them all.
`drop.vars.def`	a second list of variables to drop contained in a character vector. That list is supposed to match the name of variables that are obviously non informative and that are dropped by default. It can be gathered automatically using `dropVars()`. That list includes Id, Label, Dil, ... (see details, variables with an asterisk).
`area`	a numerical vector with areas from which ECDs are calculated (Equivalent Circular Diameter, a more suitable term for 2D images than ESD, Equivalent Spherical Diameter).
`cells`	the number of cells in the particle (colony). If different from 1, the area is first divided by the number of cells bevore calculating the cell individual ECD.
`data`	a vector containing the data to parse.
`label`	a label to include for the parsed data.
`ODfile`	an image file of O.D. calibrated items that can be used to calibrate grayscales.
`zipfile`	a zip archive.
`zimfile`	a .zim file to use, or to create. If `NULL` (default) in `zipNoteGet()`, the data are not written in a file, but returned.
`orig.dir`	the directory containing the data (current directory by default)
`target.dir`	where to place the results, by defaut, the parent directory of `orig.dir`
`clean.work`	should we clean intermediary items (`FALSE`, by default)

As these functions are not made to be directly used by end-users, We don't give more details here. Developers interested to use these functions are encouraged to look at their code in the zooimage package source!

Here is the list of all variables you got after running the standard version of calcVars() on ZIDat objects made by one of the ZooImage ImageJ plugins (you can provide your own version for, e.g., calculating more features):

Variable	Description	Origin
Area	Area of the region of interest (ROI)	ImageJ
Mean	Average gray value of the ROI	ImageJ
StdDev	Standard deviation of the gray values	ImageJ
Mode	Most frequent gray value within the ROI	ImageJ
Min	Minimum gray value within the ROI	ImageJ
Max	Maximum gray value within the ROI	ImageJ
X*	X coordinate of the centroid of the ROI in the image	ImageJ
Y*	Y coordinate of the centroid of the ROI in the image	ImageJ
XM*	X coordinate of the center of mass of the ROI in the image	ImageJ
YM*	Y coordinate of the center of mass of the ROI in the image	ImageJ
Perim.	Perimeter of the ROI	ImageJ
BX*	X coordinate of the upper left corner of the bounding rectangle (BR)	ImageJ
BY*	Y coordinate of the upper left corner of the BR	ImageJ
Width*	Width of the rectangle enclosing the ROI	ImageJ
Height*	Height of the rectangle enclosing the ROI	ImageJ
Major	Length of the longest axis of the ellipse fitted to the ROI	ImageJ
Minor	Length of the smallest axis of ellipse fitted to the ROI	ImageJ
Angle*	Angle between longest axis and an horizontal line	ImageJ
Circ.	Circularity of the ROI	ImageJ
Feret	Longest Feret diameter	ImageJ
IntDen	Sum of the gray values within the ROI	ImageJ
Median	Median value of the gray values within the ROI	ImageJ
Skew	Third order moment for the gray value	ImageJ
Kurt	Fourth order moment for the gray value	ImageJ
XStart*	X coordinate of initial point for the outline of the ROI	ImageJ
YStart*	Y coordinate of initial point for the outline of the ROI	ImageJ
Id*	Unique identifier of the ROI (Label_Item)	zooimage
Label*	Unique name of the image	zooimage
Item*	Name of the ROI	zooimage
ECD	Equivalent circular diameter of the ROI	zooimage
Dil*	Dilution coefficient to use for that ROI	zooimage
AspectRatio	Aspect ratio of the ROI	zooimage
CentBoxD	Distance between the centroid and the center of the BR	zooimage
GrayCentBoxD	Distance between the center of mass and the center of the BR	zooimage
CentroidsD	Distance between the centroid and the center mass	zooimage
Range	Range of the gray values in the ROI	zooimage
MeanPos	Position of mean gray value in the range of gray values	zooimage
SDNorm	Normalized standard deviation of the gray values	zooimage
CV	Coefficient of variation of gray values	zooimage
MeanDia	Mean diameter calculated on Major and Minor	zooimage
MeanFDia	Mean diameter calculated on Feret and Minor	zooimage
Transp1	Transparency calculated using ECD and MeanDia	zooimage
Transp2	Transparency calculated using ECD and MeanFDia	zooimage
Elongation	Elongation of the ROI	zooimage
Compactness	Compactness of the ROI	zooimage
Roundness	Roundness of the ROI	zooimage
Class*	Manual identification of the vignette for that ROI	zooimage
Predicted*	Automatic identification of the vignette for that ROI	zooimage
Predicted2*	Second automatic identification of the vignette for that ROI	zooimage

For the origin, ImageJ = measured during image ananlysis plugin in ImageJ, zooimage = calculated either during importation of data, or by calcVars(). Variables whose name ends with an asterisk are dropped by default.

A string or vector of strings for sampleInfo(), listSamples() and makeId(). For those functions, character(0) is returned to indicate a problem (usually with a warning issued to explain it), while an empty string ("") is returned in case there is no corresponding element found.

The data.frame with additional columns for calculated variables with calcVars(). Variables to drop are gathered using dropVars(), altogether with a list provided explicitly in the drop.vars = argument. The list of variable names to drop automatically and silently can be stored in a variable named ZI.dropVarsDef or in options(ZI.dropVarsDef = ....).

A vector of numerical values for ecd().

Transformed strings for trimstring() and underscoreToSpace()

parseIni() reads the data and creates a list of data frames. Each entry in the list maps one section in the ini file (with the same name). For 'key=value' pairs, a one line data frame containing values and with keys as column names. The first column of these data frames is named label and get the corresponding value passed by the 'label' argument. That way, one can easily keep track of entries when data frames originated from various different ini files are merged together.

calibrate() returns a vector of two numbers with white and black point calibration (gray levels corresponding, respectively to O.D. = 0 and O.D. = 1.024), plus a "msg" attribute with some explanation in case of problem.

zipNoteAdd() returns TRUE or FALSE depending if the data from the zimfile was successfully added to the zip archive or not. Problem is returned in a warning. zipNoteGet() returns the comment included in the zip archive (invisibly if 'zimfile' is not NULL), character(0) if no comment if found, or NULL in case of a problem. The problem is detailled in a warning.

Philippe Grosjean <Philippe.Grosjean@umons.ac.be>

noExtension, selectObject

# Given a correct ZooImage name for a sample, return parts of it
smp__ <- "MTLG.2010-03-15.H1+A1.03_dat1.zim"
sampleInfo(smp__, "sample")
sampleInfo(smp__, "fraction")
sampleInfo(smp__, "image")
sampleInfo(smp__, "scs")
sampleInfo(smp__, "date")
sampleInfo(smp__, "id")
sampleInfo(smp__, "frac")
sampleInfo(smp__, "imgnbr")
rm(smp__)
sampleInfo(c("ScanG16.2004-10-20+A1.tif", "ScanG16.2004-10-20+B1.tif"),
    type = "sample", ext = extensionPattern("tif"))

# Character strings manipulation functions
underscoreToSpace("Some_string_to_convert")
trimString("    \tString with\textra spaces  \t")

# Variables calculation utilities
df__ <- data.frame(Label = c("Alabel", "AnotherLabel"), Item = c("01", "02"))
makeId(df__)
rm(df__)
ecd(1:10)
ecd(1:10, cells = 2)
ecd(1:10, cells = 1:10)

### TODO: addClass(), calibrate(), calcVars(), parseIni(), zipNoteAdd() and zipNoteGet() examples