fit_led: Fit LED data.

In flowQB: Automated Quadratic Characterization of Flow Cytometer Instrument Sensitivity: Q, B and CV instrinsic calculations

Description

Fit observed means and variances of data generated by an LED pulser to a quadratic and a linear model involving the Poisson distribution expectations for the relation between them. The function assumes that data generated by different LED levels are provided as separate FCS files. These files are passed to the function in the form of a vector of FCS file paths. In addition, house keeping details about the data and the way the fitting procedure should be performed need to be provided, see the description of the arguments below.

Usage

    fit_led(fcs_file_path_list, ignore_channels, dyes, detectors, 
        signal_type, instrument_name, 
        bounds = list(minimum = -100, maximum = 100000),
        minimum_useful_peaks = 3, max_iterations = 10, ...)

Arguments

fcs_file_path_list	A vector of FCS file paths pointing to data generated by an LED pulser set to a range of LED levels; different levels generated different FCS files, all data coming from a single instrument.
ignore_channels	A vector of short channel names (values of the $PnN keywords) specifying channels that should not be considered for the fitting procedure. Normally, those should be all non-fluorescence channels, such as the time and the (forward and side) scatter channels.
dyes	A vector of dye names that you would normally use with the detectors specified below. This value does not affect the fitting, but those dyes will be “highlighted” in the provided results.
detectors	A vector of short channel names (values of the $PnN keywords) specifying channels matching to the dyes specified above. The length of this vector shall correspond to the length of the dyes vector. These channels should be all of the same type as specified by the signal_type below, i.e., area or height of the measured signal.
signal_type	The type of the signal specified as the “area” or “height”. This should match to the signal type that is being captured by the channels specified in the detectors argument. The signal type is being used in order to trigger type-specific peak validity checks. Currently, if signal type equals to “height” then peaks with a mean value lower than the lowest peak mean value are omitted from the fitting. In addition, peaks that are not sufficiently narrow (i.e., exceeding a specific maximum CV) are also omitted from the fitting. Currently, the maximum allowed CV is set to 0.65, but the code is designed to make this user-configurable and signal type dependent eventually.
instrument_name	The make/model of the instrument. The purpose if this argument is to allow for instrument-specific peak validity checks. At this point, if “BD Accuri” is passed as the instrument type, then peaks with a mean value lower than the lowest peak mean value are omitted from the fitting. Additional instrument-specific peak validity checks may be implemented in the future.
bounds	On some instruments, the lowest LED peaks may be cut off at a data baseline so that the peak statistics will not be valid. Therefore, peaks too close to the baseline need to be excluded from the fitting. Also, many instruments do not maintain good linearity to the full top of scale, so it is also important to specify a maximum level for good linearity and, on each fluorescence channel, exclude any peak that is above that maximum. The bounds argument shall provide a list specifying the minimum and maximum value for the means of valid peaks; peaks with means outsize of this range will be ignored for that particular channel.
minimum_useful_peaks	Different peaks may be omitted for different channels due to various validity checks described above. This argument specifies the minimal number of valid peaks required in order for the fitting procedure to be performed on a particular fluorescence channel. Generally, fitting the three quadratic parameters requires three valid points to obtain a fit at all, and 4 or more points are needed to obtain error estimates. Requiring higher values would exclude some of your data but likely produce better results.
max_iterations	The peaks have a wide range of variances, so unweighted least squares fitting is not appropriate, and we need to apply appropriate weights in the fitting procedure. In particular, the populations with lower variances get more weight since having the fit miss them by any particular amount is worse than missing a high variance population by the same amount. This argument specifies the maximum number of iterations for the iterative fitting approach with appropriate weight recalculations. In most cases, the fitting converges relatively fast. The iterating stops when either the maximum of iterations is used or if none of the coefficients of the model changed more than 0.00005. The default maximum of 10 iterations seems to be enough in most cases. You can also explore your results in order to see how many iterations were actually done for each of the all of the fitting.
...	Additional arguments that will be passed to the get_peak_statistics function used internally to calculate peak statistics, such as the maximum.cv.area and maximum.cv.height values.

Details

An LED light pulser is producing very uniform pulses at adjustable signal levels. White LEDs provide some signal at all visible wavelengths, but the far-red emission is weak. A given LED pulse level will generate quite different photoelectron signals on different detectors, so it is important to collect data over a wide range of LED levels to assure that the measurement series on each detector will include the low, middle and high level signals needed for optimal results in the fitting procedure.

Value

fit_led returns a list, see the vignette for a detailed description.

Author(s)

Josef Spidlen, Wayne Moore, Faysal El Khettabi

See Also

fit_beads

Examples

    library(flowCore)
    library(xlsx)
    library(flowQBData)

    inst_xlsx_path <- system.file("extdata", 
        "140126_InstEval_Stanford_LSRIIA2.xlsx", package="flowQBData")
    xlsx <- read.xlsx(inst_xlsx_path, 1, headers=FALSE, stringsAsFactors=FALSE)
    
    ignore_channels_row <- 9
    ignore_channels <- vector()
    i <- 1
    while(!is.na(xlsx[[i+4]][[ignore_channels_row]])) {
        ignore_channels[[i]] <- xlsx[[i+4]][[ignore_channels_row]]
        i <- i + 1
    }
    
    instrument_folder_row <- 9
    instrument_folder_col <- 2
    instrument_folder <- xlsx[[instrument_folder_col]][[instrument_folder_row]]
    folder_column <- 18
    folder_row <- 14
    folder <- xlsx[[folder_column]][[folder_row]]
    fcs_directory <- system.file("extdata", instrument_folder, 
        folder, package="flowQBData")
    fcs_file_path_list <- list.files(fcs_directory, "*.fcs", full.names= TRUE)

    bounds_min_col <- 6
    bounds_min_row <- 7
    bounds_max_col <- 7
    bounds_max_row <- 7
    bounds <- list()
    if (is.na(xlsx[[bounds_min_col]][[bounds_min_row]])) {
        bounds$minimum <- -100
    } else {
        bounds$minimum <- as.numeric(xlsx[[bounds_min_col]][[bounds_min_row]])
    }
    if (is.na(xlsx[[bounds_max_col]][[bounds_max_row]])) {
        bounds$maximum <- 100000
    } else {
        bounds$maximum <- as.numeric(xlsx[[bounds_max_col]][[bounds_max_row]])
    }
    signal_type_col <- 3
    signal_type_row <- 19
    signal_type <- xlsx[[signal_type_col]][[signal_type_row]]
    
    instrument_name_col <- 2
    instrument_name_row <- 5
    instrument_name <- xlsx[[instrument_name_col]][[instrument_name_row]]

    channel_cols <- 3:12
    dye_row <- 11
    detector_row <- 13
    dyes <- as.character(xlsx[dye_row,channel_cols])
    detectors <- as.character(xlsx[detector_row,channel_cols])

    led_results <- fit_led(fcs_file_path_list, ignore_channels, dyes,
        detectors, signal_type, instrument_name, bounds = bounds,
        minimum_useful_peaks = 3, max_iterations = 10)

flowQB documentation built on May 6, 2019, 3:05 a.m.