FNTDoptions-class: Options for sample processing and analysis

Description Usage Arguments Details Value Author(s) Examples


Class and functions to control the entire process of sample analysis. This is the main place to learn about the proper settings. Options can (and should) be set using an xml-file. The schema for these can be found using system.file("extdata", "FNTD.option.file.xsd", package = "FNTD").





An object of class FNTDoptions.


Option name, see details


Option value to set


Path to xml-file with options


Any number of options to override defaults, see details.


Options are:

Main options:


Used to describe the current settings.Default: "Default option set for IBCT FNTD analyses, adopt to your needs".


Short version of description, should not contain spaces and other problematic characters as this will be used for naming all output files related to these settings.Default: "default_options".

Path options:


Full path to data location. Images will be sought recursively in all subfolders at the given location. The path is also used for for the tracking and meta data files. Default: ".".


Name and path relative to data.path of the file (Excel format) containing meta data. Mandatory are the columns: sample id, particle.name, E.MeV.u (beam energy), but the latter two can be set to NA if not known. Additional variables can be given - for LSM data, this has to be laser.power (in percent, i.e. 5, 20, 100 etc.) and dwell.time.us in microseconds. See system.file("extdata", "TestImages", "meta.data.xlsx", package = "FNTD") for an example. Default: "MetaData.xlsx"


Name and path relative to data.path of the file (Excel format) containing

the parameters for tracking, i.e. radius, cutoff, and percentile,

the parameters for linking: link.range, displacement, radius.link, weight.distance, weight.intensity, weight.velocity, weight.angle, max_angle, angle_history, relink, relink.cost_factor, and relink.distance,

and the parameters for track filtering / evaluation: min.no.trackspots, min.no.slices, evaluation.radius and critical.distance

together with sample id. See also FNTD.find.trackspots and system.file("extdata", "TestImages", "tracking.parameters.xlsx", package = "FNTD") for an example. Default: "TrackingParameters.xlsx"


Name and path relative to data.path of the file (Excel format) containing parameters for distribution analysis together with sample id. Columns needed are method, which can be mixtools or threshold, followed by up to ten pairs of columns named XXX.1, XXX.2, YYY.1, YYY.2 and so on, where XXX and YYY etc. define the particle populations use, e.g. "primaries" and "fragments" or "C", "H", "He", "others" etc. In case of mixtools, the spectra will be analysed as super position of normal distributions with initial guesses for mean and standard deviation in the first and second column for the respective population. In case of threshold, the columns refer to min and max for an interval (may overlap) in which again a Gaussian will be fitted to the data. All sample not listed in the table will be treated as if all data belonged to the first population (raw). See also FNTDdistData-class. The first sheet of the excel file will be used for the fluorescence intensity distribution (both for slice and stack data), the second for the intensity straggling (in case of stack data). If one or both are empty, distribution analysis will default to method 'raw', i.e. using the average and standard deviation of all data for a respective sample and frame. Default: ""

Sample options:


The script assumes that the sample id is reflected in the first n characters of the filenames, so for example sg1000_C12_200MeV.tif yields 'sg1000' with id.length = 6. Default: 6


'FXR' or 'LSM'. Will trigger different recommendations for signal processing, e.g. saturation and laser-power correction for LSM. Default: "FXR"


'Regular' or 'Calibration'. If the latter is chose, additional analyses will be done, esp. the relation between LET and intensity. The user has to give proper meta data in this case. Default: "Regular"


List with voxel size in um, three entries for x (x.um), y (y.um), and z (z.um). Default: x.um = 100/504, y.um = 100/504, z.um = 5


List with parameters for correction of refraction effects. Default: n1 = 1.0, n2 = 1.77, NumAp = 0.95


Refractive index of medium between lens and FNTD, e.g. air or oil.


Refractive index of FNTD, i.e. 1.77.


Numerical Aperture of the lens used.


List with parameters for correction of surface tilt and offset. Default: z.offset.um = 0, image.offset.um = 0, xz.slope.offset = 0, yz.slope.offset = 0, tilt.correction = FALSE


Offset (in um) of the first slice read-out (has to be consistent with slices.selected)


Additions offset (in um) due to microscopy stage


Tilt of sample in x direction


Tilt of sample in y direction


If true, sample tilt (mean slopes of tracks + additional tilt given in x and y direction) will be corrected

Processing options:


If TRUE all intermediate results will be kept in the FNTD.results structure, also those that are not used in reporting. Can slow down the process due to the enormous size of some data frames. Default: "Sample-wise"


Computing can be done in parallel using as many cores as the system provides. Can be turned of for debugging purposes. If set to "Sample-wise" samples will be sent to separate nodes where a loop will run through the sample's frames. Use this if you have many samples (i.e. more than nodes). If set to "Frame-wise", samples will be processed subsequently and the sample's frames will be distributed between nodes. Use this options for few samples with many (i.e. more than nodes) frames. Default: "Sample-wise"


Maximum number of cores to be used in parallel processing. Can be used to minimize system load if necessary (e.g. when too much memory is allocated when using all cores available). Default: 10000


Argument for maximum heap space size for processes in parallel computing: for heavy tasks of for example tracking and linking, this value has to be adapted to avoid a java heap space ('out of memory') error. For the main script (and forked processes, i.e. processing track results under Linux) the heap space has to be set BEFORE loading the package via options(java.parameters = "-Xmx2g") or similar. Remember that the R session has to be restarted in order to shut down the Java virtual machine and the setting change to take effect. For SOCK processes, a separate JVM is started (JVMs cannot be forked) whose maximum heap size is set via this option. It is written into a temporary .Rprofile file read at startup of the Rscript-based process. Default: -Xmx1g (1 GB)


If true, result for tracking and linking automatically saved during a previous run will be used. Can save a lot of time but to be used with caution! Default: FALSE


If TRUE, first slice in stack will be removed and image size and offset adjusted. Useful if first slice is surface. Default: FALSE


Reference slice for sperical abberation correction and slice on which slice specific analyses will be run. If user chose to remove first slice, this will automatically set to 2 (if 1 is chosen). Default: 1


If true, tracks will be extrapolated by half a z-slice beyond first and last trackspot as long as this expansion does not leave the read-out volume. Default: TRUE


Method of assessing fluorescence amplitude of trackspots. Default: "sum".


Value of hottest pixel within disc of radius evaluation.radius around trackspot center.


Total fluorescence signal within disc of radius evaluation.radius around trackspot center.


Amplitude of a 2D Gaussian fit (with different width in x and y, but no rotation), corresponding to the intensity maximum of the trackspot.


Volume under the 2D Gaussian curve fitted, corresponding to the intensity sum of the trackspot. Equals 2*pi*width.x*width.y times the amplitude.


Method of assessing the width of trackspots. Default: "average".


Mean value of width in x and y.


Use only width in x.


Use only width in y.


Use smaller width.


Radius (in pixel) around trackspot center used in amplitude assessment. Default: 6

Analyzing options:


If true, the net images including an overlay indicating tracking results will be written to disc. Default: FALSE


If true, a report will be created that shows the results of distribution analysis for all samples and frames (even if no distribution parameters are given, since the 'raw' methode, i.e. taking the mean and st.dev of all intensities in a frame, corresponds to fitting a Gaussian to the intensity distribution - for which the validity should be checked). As the production of this report can be time-consuming, it has to be explicitely enabled. Default: FALSE


Determines which axes in the heapmap plots of distributions will be log-scale, can be any combination of "x", "y", and "z", for example "xz". "all" is equivalent to "xyz", "none" to "". Default: "none"


Function used for relation of fluorescence amplitude and intensity. Default: "log.log"


Linear model in double log scale.


Formula from Klimpki et al., 2015


Parameters used with relation of fluorescence amplitude and intensity. Default: -0.1285, 0.5498


c - Intercept and a - slope.


a, b, c

Correction options:


Method of assessing and subtracting fluorescence background. Can be done using a slightly modified version of the MOSAIC background subtractor (that allows for negative values) or by considering the offset from a Gaussian fit to the trackspots. In the latter case, either "Gauss.amplitude" or "Gauss.volume" has to be selected. If saturatiuon correction is selected (as should be done for the LSM device), the offset is subtracted AFTER the correction since the latter affects the entire and not only the net signal. Default: "Mosaic"


No background will be assessed and subtracted.


Histogram-based background assessment using the 'Background Subtractor' plugin of MOSAIC ToolSuite, but allowing for negative pixel values. A sliding window size has to be given. The background is subtracted pixel-wise from the entire original image before amplitude assessment.


The offset from the 2D Gaussian fit is used as an estimator for the local background.


Side length (in pixel) of the sliding window used in Mosaic's background subtractor. Default: 30


Method of correction for spherical abberation. Default: "Frame-wise tracks"


No correction will be applied.


Normalizes TRACKSPOT intensities of similar magnitude per slice across all frames as described in Bartz et al., 2014. "Similar" means average intensity +/- 2 sd. Corresponds (except for track selection) to "Sample-wise tracks"

"Frame-wise total"
"Frame-wise tracks"
"Sample-wise total"
"Sample-wise tracks"

Method of correction for intensity decrease due to tilting of tracks. Default: "Hyperbola"


No correction will be applied.


Formula from Bartz et al., 2014, with parameter angular.corr.factor = 3.5


Formula from Bartz et al., 2014, with parameter angular.corr.factor set to any value


Weighting factor in Bartz et al., 2014, angular correction. Default: 3.5


Method of correction for field-of-view non-uniformity ("flatfield"). Default: "Frame-wise tracks"


No correction will be applied.


A 2D polynomial (CAVE: original publication says 3D - typo?) is fitted intensity of the selected TRACKS all collapsed into one frame. "Similar" means average intensity +/- 2 sd. Corresponds (except for track selection) to "Sample-wise tracks"

"Frame-wise tracks"
"Sample-wise tracks"

Method of correction for (intra-detector) sensitivity fluctuation between frames (= stacks). The correction factors are reported in a plot. Default: "Frame-wise tracks"


No correction will be applied.


A 3D polynomial (CAVE: original publication says 2D - typo?) is fitted to the track intensity of similar magnitude across all frames as described in Bartz et al., Charge-spectroscopy..., 2014. "Similar" means average intensity +/- 2 sd. IMPORTANT: frames are assumed to be adjacent and quadratic (i.e. 2x2, 3x3, ...) and scanning is supposed to be in x first, then in y. This is not assumed for the other options.

"Frame-wise tracks"

The intensities of all tracks in all slices is summed for each frame (stack) of a sample. Then, these sums are normalized to their average.


Dead-time correction for saturation effects in the photon-counting APD (Zeiss LSM710 only). Default: FALSE


Characteristic count-rate in MHz for saturation correction, cf. Greilich et al., 2013. Default: 16.2


Dead-time correction for saturation effects in the photon-counting APD (Zeiss LSM710 only). Default: FALSE


Compensates for differences when images were read out with different dwell-time and laser-power. Can also account for non-linearities from laser power difference are used (see Klimpki et al., 2016). Default: FALSE


Exponent to use for laser power correction, cf. Klimpki et al., 2016. 0.0 for perfect linearity. Default: 0.165


FNTD.options() returns an FNTDoptions object with defaults, except for those values that were overridden by the user. FNTD.get.option returns the value of the option requested. FNTD.set.option returns a message if the setting was successful.


S. Greilich


## Not run: 
my.options <- FNTD.options(data.path            = "/data/home/greilich/workspace/mySamples",
                           meta.data.file       = "meta.data.xlsx",
                           tracking.par.file    = "tracking.parameters.xlsx",
                           id.length            = 3,
                           use.tracking.results = FALSE)
## End(Not run)

FNTD/R-package documentation built on Oct. 18, 2017, 12:59 p.m.