FNTDoptions-class: Options for sample processing and analysis

Description Usage Arguments Details Value Author(s) Examples

Description

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").

Usage

1
2
3
4

Arguments

options

An object of class FNTDoptions.

name

Option name, see details

value

Option value to set

file.name

Path to xml-file with options

...

Any number of options to override defaults, see details.

Details

Options are:

Main options:

description

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

short.description

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:

data.path

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: ".".

meta.data.file

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"

tracking.par.file

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"

distribution.par.file

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:

id.length

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

device

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

data.type

'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"

voxel.size

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

optical.param

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

n1

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

n2

Refractive index of FNTD, i.e. 1.77.

NumAp

Numerical Aperture of the lens used.

surface.param

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

z.offset.um

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

image.offset.um

Additions offset (in um) due to microscopy stage

xz.slope.offset

Tilt of sample in x direction

yz.slope.offset

Tilt of sample in y direction

tilt.correction

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

Processing options:

debug.mode

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"

use.cluster

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"

max.n.cores

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

process.heap.space.arg

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)

use.tracking.results

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

remove.first.slice

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

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

use.slice.thickness.for.tracks

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

amplitude.method

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

"maximum"

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

"sum"

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

"Gauss.amplitude"

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

"Gauss.volume"

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.

width.methode

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

"average"

Mean value of width in x and y.

"x"

Use only width in x.

"y"

Use only width in y.

"min"

Use smaller width.

evaluation.radius

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

Analyzing options:

plot.images.for.report

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

distribution.plots

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

distribution.plots.log

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"

calibration.function

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

"log.log"

Linear model in double log scale.

"empiral.log"

Formula from Klimpki et al., 2015

calibration.coefs

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

"log.log"

c - Intercept and a - slope.

"empiral.log"

a, b, c

Correction options:

correction.background

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"

"none"

No background will be assessed and subtracted.

"Mosaic"

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.

"Gauss"

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

background.window.size

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

correction.spher.abb

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

"none"

No correction will be applied.

"Bartz2014"

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"
correction.angular

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

"none"

No correction will be applied.

"Bartz2014"

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

"Hyperbola"

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

angular.corr.factor

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

correction.FOV.uniform

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

"none"

No correction will be applied.

"Bartz2014"

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"
correction.fluctuation

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

"none"

No correction will be applied.

"Bartz2014"

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.

correct.saturation

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

saturation.count.rate.MHz

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

correct.saturation

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

use.adjusted.count.rate

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

laser.power.exponent

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

Value

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.

Author(s)

S. Greilich

Examples

1
2
3
4
5
6
7
## 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.