Title:	Analysis and Visualization of Droplet Digital PCR in R and on the Web
Version:	1.15.2
Description:	An interface to explore, analyze, and visualize droplet digital PCR (ddPCR) data in R. This is the first non-proprietary software for analyzing two-channel ddPCR data. An interactive tool was also created and is available online to facilitate this analysis for anyone who is not comfortable with using R.
URL:	https://github.com/daattali/ddpcr, https://daattali.com/shiny/ddpcr/
BugReports:	https://github.com/daattali/ddpcr/issues
Depends:	R (≥ 3.1.0)
Imports:	DT (≥ 0.2), dplyr (≥ 0.5.0), ggplot2 (≥ 2.2.0), lazyeval (≥ 0.1.10), magrittr (≥ 1.5), mixtools (≥ 1.0.2), plyr (≥ 1.8.1), readr (≥ 0.1.0), shiny (≥ 0.11.0), shinydisconnect, shinyjs (≥ 0.4.0), tibble
Suggests:	ggExtra (≥ 0.3.0), graphics, grid (≥ 3.2.2), gridExtra (≥ 2.0.0), knitr (≥ 1.7), rmarkdown, stats, testthat (≥ 0.11.0), utils
License:	MIT + file LICENSE
VignetteBuilder:	knitr
RoxygenNote:	7.2.3
Encoding:	UTF-8
NeedsCompilation:	no
Packaged:	2023-08-19 23:00:34 UTC; Dean-X1C
Author:	Dean Attali [aut, cre]
Maintainer:	Dean Attali <daattali@gmail.com>
Repository:	CRAN
Date/Publication:	2023-08-20 22:32:32 UTC

ddpcr: Analysis and Visualization of Droplet Digital PCR in R and on the Web

Description

An interface to explore, analyze, and visualize droplet digital PCR (ddPCR) data in R. This is the first non-proprietary software for analyzing two-channel ddPCR data. An interactive tool was also created and is available online to facilitate this analysis for anyone who is not comfortable with using R.

Author(s)

Maintainer: Dean Attali daattali@gmail.com (ORCID)

See Also

Useful links:

• https://github.com/daattali/ddpcr

• https://daattali.com/shiny/ddpcr/

• Report bugs at https://github.com/daattali/ddpcr/issues

magrittr forward-pipe operator

Description

magrittr forward-pipe operator

Determine if a numeric value is within a range

Description

Determine if a numeric value is within a range

Usage

x %btwn% rng

Arguments

regex for a well ID

Description

regex for a well ID

Usage

WELL_ID_REGEX

Format

An object of class character of length 1.

Is the analysis complete?

Description

Check if a ddPCR plate has been fully analyzed or if there are remaining steps.

Usage

analysis_complete(plate)

Arguments

Value

TRUE if the plate's analysis has been fully carried out; FALSE otherwise.

See Also

status
analyze

Run analysis on a ddPCR plate

Description

Every ddPCR plate has a set of defined steps that are taken in order, that together constitute "analyzing" the plate. Calling the analyze function will perform all the analysis steps, which may take several minutes. Running the analysis will classify the droplets in the plate into clusters (available via plate_data) and will add variables to the plate metadata (available via plate_meta).

Usage

analyze(plate, restart = FALSE)

Arguments

Details

This function will run an analysis to completion. If you want to run each step one at a time, use next_step.

Value

The analyzed ddPCR plate

Note

Most analysis steps result in some progress messages being printed to the screen. You can turn off these messages by disabling the verbose option with the command options(ddpcr.verbose = FALSE).

See Also

next_step
plot.ddpcr_plate
new_plate
steps
plate_data
plate_meta

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$custom_thresholds)
plate <- analyze(plate)

## End(Not run) 

Helper function for move_front and move_back

Description

Helper function for move_front and move_back

Usage

bind_df_ends(df, cols, dir = 1)

Calculate negative frequency based on number of drops

Description

Calculate negative frequency based on number of drops

Usage

calc_negative_freq_simple(negative_drops, positive_drops)

Arguments

Value

Fraction of drops that are negative.

See Also

pnpp_experiment

Examples

calc_negative_freq_simple(5, 45)

Calculate template concentration

Description

Calculate template concentration in each wells in a plate using the same formula that QuantaSoft uses. The concentration information is added to the plate's metadata.

Usage

calculate_concentration(plate)

Details

The concentration in a well as number of copies of template per microlitre of sample, and uses the following equation:

(-log(drops_empty / drops_total) * drops_total) / (droplet_volume * drops_total)

Value

A ddPCR plate with the metadata containing a new 'concentration' variable.

Calculate concentration in a single well

Description

Calculate concentration in a single well

Usage

calculate_concentration_single(plate, well_id)

Value

The concentration (integer) in a well.

Calculate negative frequency of a single well

Description

Calculate negative frequency of a single well

Usage

calculate_neg_freq_single(plate, well_id)

Arguments

Value

list with 3 elemnts: number of negative drops, number of positive drops, and fraction of negative drops.

See Also

pnpp_experiment

Examples

file <- system.file("sample_data", "small", "analyzed_pnpp.rds", package = "ddpcr")
plate <- load_plate(file)
plate %>% calculate_neg_freq_single("A05")

Calculate negative frequencies in whole plate

Description

The resulting plate has the same droplet data but an updated metadata with the number of negative/positive droplets and the negative frequency.

Usage

calculate_negative_freqs(plate)

Arguments

See Also

pnpp_experiment

Examples

file <- system.file("sample_data", "small", "analyzed_pnpp.rds", package = "ddpcr")
plate <- load_plate(file)
plate %>% calculate_negative_freqs %>%
  well_info(wells_success(plate), "negative_freq")

Capitalize the first letter of a string

Description

Capitalize the first letter of a string

Usage

capitalize(x)

Concatenate strings with no space between them

Description

Concatenate strings with no space between them

Usage

cat0(...)

Arguments

Ensure the plate's status is at the right step

Description

Before beginning a step, you can check to make sure the plate is currently at most one step behind the current step. If the plate is more than one step behind, an error will be thrown, so that the user will know they need to run the previous steps.

Usage

check_step(plate, step)

Examples

## Not run: 
dir <- sample_data_dir()
plate <- new_plate(dir)
status(plate) # current step
check_step(plate, 2) # are we ready to start step 2?
check_step(plate, 3) # are we ready to start step 3?
plate <- next_step(plate)
status(plate)
check_step(plate, 3) # now are we ready to start step 3?

## End(Not run)

Analysis step: Classify droplets

Description

The main analysis step for ddPCR plates of type pnpp_experiment. Classify each droplet as either rain, ++, or +-. Also calculate the frequency of negative droplets, and attempt to detemine if each well has a statistically significant number of such droplets.

See the README for more information about the algorithm used.

Usage

classify_droplets(plate)

Arguments

Details

This function is recommended to be run as part of an analysis pipeline (ie. within the analyze function) rather than being called directly.

Value

A ddPCR plate with all droplets assigned to a cluster. The plate's metadata will have several new variables.

Note

This is an S3 generic, which means that different ddPCR plate types can implement this function differently. See the README for more information on how to implement custom ddPCR plate types.

See Also

analyze
classify_droplets_single
mark_clusters
has_signif_negative_cluster

Analysis step: Classify droplets

Description

Analysis step: Classify droplets

Usage

## S3 method for class 'pnpp_experiment'
classify_droplets(plate)

Arguments

Classify droplets in a well

Description

This function runs the actual algorithm for classifying droplets in a single well.

Usage

classify_droplets_single(plate, well_id, ...)

Classify droplets in a well

Description

If you want to see details about how a well was classified, you can set plot = TRUE to plot the results.

Usage

## S3 method for class 'pnpp_experiment'
classify_droplets_single(plate, well_id, ..., plot = FALSE)

Analysis step: Classify droplets

Description

The main analysis step for ddPCR plates of type custom_thresholds. Assign each droplet into one of four quadrants based on the thresholds.

See the README for more information.

Usage

classify_thresholds(plate)

Arguments

Details

This function is recommended to be run as part of an analysis pipeline (ie. within the analyze function) rather than being called directly.

Value

A ddPCR plate with all the droplets assigned to a quadrant. The plate's metadata will have a few new variables relating to the number of droplets in each quadrant.

See Also

custom_thresholds
analyze
thresholds

Get cluster ID by name

Description

Get cluster ID by name

Usage

cluster(plate, cluster)

Examples

## Not run: 
plate <- new_plate(sample_data_dir())
# see what cluster names exist and their order
clusters(plate)
cluster(plate, 'FAILED')
cluster(plate, 'EMPTY')

## End(Not run)

Get cluster name by ID

Description

Get cluster name by ID

Usage

cluster_name(plate, cluster)

Examples

## Not run: 
plate <- new_plate(sample_data_dir())
# see what cluster names exist and their order
clusters(plate)
cluster_name(plate, 2)
cluster_name(plate, 4)

## End(Not run)

Potential droplet clusters for a plate type

Description

Each ddPCR plate type has a specific set of potential clusters the droplets can be assigned to.

Usage

clusters(plate)

Arguments

Details

See the README for more information on plate types.

Value

A character vector with the names of the clusters supported by the plate type.

Examples

## Not run: 
dir <- sample_data_dir()
new_plate(dir) %>% clusters
new_plate(dir, plate_types$fam_positive_pnpp) %>% clusters

## End(Not run)

Convert a plate column to a number

Description

Convert a plate column to a number

Usage

col_to_num(col)

Examples

col_to_num("05")  # 5L

Plate type: custom thresholds

Description

The custom_thresholds plate type is used when you want to gate ddPCR droplet data into four quadrants according to HEX and FAM values that you manually set. All wells in the plate will use the same threshold values.

Details

Plates with this type have only three analysis steps: INITIALIZE, REMOVE_OUTLIERS, and CLASSIFY (according to the custom thresholds).

Plates with this type have the following droplet clusters: UNDEFINED, OUTLIER, EMPTY (bottom-left quadrant), X_POSITIVE (bottom-right quadrant), Y_POSITIVE (top-left quadrant), BOTH_POSITIVE (top-right quadrant).

See the README for more information on plate types.

See Also

plate_types
x_threshold
y_threshold
thresholds
analyze
remove_outliers
classify_thresholds

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$custom_thresholds)
type(plate)
plate %>% analyze %>% plot

## End(Not run)

Plate type: ddPCR plate

Description

The default plate type that all other plates inherit from. If you initialize a ddPCR plate without specifying a plate type, ddpcr_plate will be the plate's type.

Details

Plates with this type have the following analysis steps: INITIALIZE, REMOVE_FAILURES, REMOVE_OUTLIERS, REMOVE_EMPTY.

Plates with this type have the following droplet clusters: UNDEFINED, FAILED, OUTLIER, EMPTY.

See the README for more information on plate types.

See Also

plate_types
remove_failures
remove_outliers
remove_empty

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$ddpcr_plate)
type(plate)
plate %>% analyze %>% plot

## End(Not run)

Define droplet clusters

Description

Every ddPCR plate type has a set of potential clusters the droplets can be assigned to. When creating a custom plate type, if your plate type uses a different set of clusters than its parent type, you must define this function to return the cluster names. When defining this function, you can use NextMethod("define_clusters") to get a list of the clusters available in the parent type if you want to simply add new clusters without defining all of them.

Usage

define_clusters(plate)

Arguments

Value

A list of potential droplet clusters for the plate type.

See Also

clusters

clusters
parent_plate_type
define_params
define_steps

Define droplet clusters for custom thresholds plates

Description

Define droplet clusters for custom thresholds plates

Usage

## S3 method for class 'custom_thresholds'
define_clusters(plate)

Arguments

Define droplet clusters for default plates

Description

Define droplet clusters for default plates

Usage

## S3 method for class 'ddpcr_plate'
define_clusters(plate)

Arguments

Define droplet clusters for PNPP experiments

Description

Define droplet clusters for PNPP experiments

Usage

## S3 method for class 'pnpp_experiment'
define_clusters(plate)

Arguments

Define plate type parameters

Description

Every ddPCR plate type has a set of default parameters. When creating a custom plate type, if your plate type needs a different set of parameters than its parent type, you must define this function to return the parameters specific to this plate. When defining this function, you can use NextMethod("define_params") to get a list of the parameters of the parent type so that you can simply add to that list rather than redefining all the parameters.

Usage

define_params(plate)

Arguments

Value

A list of default parameters for the plate type.

See Also

params

params
parent_plate_type
define_clusters
define_steps

Define plate type parameters for custom thresholds plates

Description

Define plate type parameters for custom thresholds plates

Usage

## S3 method for class 'custom_thresholds'
define_params(plate)

Arguments

Define plate type parameters for default plates

Description

Define plate type parameters for default plates

Usage

## S3 method for class 'ddpcr_plate'
define_params(plate)

Arguments

Define plate type parameters for FAM-positive PNPP

Description

Define plate type parameters for FAM-positive PNPP

Usage

## S3 method for class 'fam_positive_pnpp'
define_params(plate)

Arguments

Define plate type parameters for HEX-positive PNPP

Description

Define plate type parameters for HEX-positive PNPP

Usage

## S3 method for class 'hex_positive_pnpp'
define_params(plate)

Arguments

Define plate type parameters for PNPP experiments

Description

Define plate type parameters for PNPP experiments

Usage

## S3 method for class 'pnpp_experiment'
define_params(plate)

Arguments

Define plate type parameters for wildtype/mutant PNPP

Description

Define plate type parameters for wildtype/mutant PNPP

Usage

## S3 method for class 'wildtype_mutant_pnpp'
define_params(plate)

Arguments

Define analysis steps

Description

Every ddPCR plate type has an ordered set of steps that are run to analyze the data. When creating a new plate type, if your plate type has different analysis steps than its parent type, you must define this function to return a named list of the analysis steps. When defining this function, you can use NextMethod("define_steps") to get a list of the steps available in the parent type if you want to simply add new steps without defining all of them.

Usage

define_steps(plate)

Arguments

Value

A named list of analysis steps in the order they should be run on a dataset. The name of each item in the list is the human-readable name of the step and the value of each item is the function to call to perform the step.

See Also

steps
step_begin
step_end
parent_plate_type
define_clusters
define_params

Define analysis steps for custom thresholds plates

Description

Define analysis steps for custom thresholds plates

Usage

## S3 method for class 'custom_thresholds'
define_steps(plate)

Arguments

Define analysis steps for default plates

Description

Define analysis steps for default plates

Usage

## S3 method for class 'ddpcr_plate'
define_steps(plate)

Arguments

Define analysis steps for PNPP experiments

Description

Define analysis steps for PNPP experiments

Usage

## S3 method for class 'pnpp_experiment'
define_steps(plate)

Arguments

Euclidean distance between two points

Description

Calculate the distance between two points in 2D space. If only one points is given, then the distance to the origin is calculated.

Usage

## S3 method for class 'point2d'
diff(x, y, ...)

Arguments

See Also

point2d

Show an error message

Description

Show an error message

Usage

err_msg(x)

Arguments

Plate type: FAM-positive PNPP

Description

A ddPCR plate of type fam_positive_pnpp, which can also be expressed as (FAM+)/(FAM+HEX+), is a subtype of both pnpp_experiment and wildtype_mutant_pnpp. Use this plate type if your data has three main clusters of droplets: double-negative (empty droplets), FAM+HEX+ (wildtype droplets) and FAM+HEX- (mutant droplets).

Details

Plates with this type have the following analysis steps: INITIALIZE, REMOVE_FAILURES, REMOVE_OUTLIERS, REMOVE_EMPTY, CLASSIFY, RECLASSIFY.

Plates with this type have the following droplet clusters: UNDEFINED, FAILED, OUTLIER, EMPTY (double-negative), RAIN (not empty but not wildtype nor negative), POSITIVE (wildtype), NEGATIVE (mutant).

See the README for more information on plate types.

See Also

plate_types
wildtype_mutant_pnpp
hex_positive_pnpp
analyze
remove_failures
remove_outliers
remove_empty
classify_droplets
reclassify_droplets

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$fam_positive_pnpp)
type(plate)
plate %>% analyze %>% plot

## End(Not run)

Get column from well ID

Description

Get column from well ID

Usage

get_col(well)

Examples

get_col("C05" )  # "05"

Get the cutoff for empty droplets in a well

Description

Calculate the cutoff thresholds that define which droplets are empty in a well.

Usage

get_empty_cutoff(plate, well_id)

Value

A list with 2 elements named x and y with the values being the cutoff in the corresponding axis.

Get the cutoff for empty droplets in a well

Description

Get the cutoff for empty droplets in a well

Usage

## S3 method for class 'ddpcr_plate'
get_empty_cutoff(plate, well_id)

Get the cutoff for empty droplets in a well

Description

Very similar to the get_empty_cutoff method of the base plate type, except for this plate type we know that we don't expect any droplets in one of the corners, so we can save time by only having an empty cutoff in one dimension.

Usage

## S3 method for class 'pnpp_experiment'
get_empty_cutoff(plate, well_id)

Get border of filled droplets in PNPP experiment

Description

In a PNPP experiment, the rain droplets are the non-empty drops that don't have a high enough intensity in the positive dimension to be considered as filled with high quality sample DNA. Only droplets considered as filled are candidates for the negative and positive clusters. get_filled_border returns the threshold value in the positive dimension that is used to determine which drops are filled.

Usage

get_filled_border(plate, well_id)

Arguments

Value

Thresholds of filled drops in the positive dimension.

See Also

pnpp_experiment
positive_dim
get_filled_drops

Examples

file <- system.file("sample_data", "small", "analyzed_pnpp.rds", package = "ddpcr")
plate <- load_plate(file)
get_filled_border(plate, "A05")
get_filled_border(plate, "F05")

Get filled droplets in PNPP experiment

Description

In a PNPP experiment, the rain droplets are the non-empty drops that don't have a high enough intensity in the positive dimension to be considered as filled with high quality sample DNA. Only droplets considered as filled are candidates for the negative and positive clusters. get_filled_drops returns the droplets that are considered filled.

Usage

get_filled_drops(plate, well_id, border)

Arguments

Value

Dataframe with all filled droplets in the given well.

See Also

pnpp_experiment
positive_dim
get_filled_drops

Examples

file <- system.file("sample_data", "small", "analyzed_pnpp.rds", package = "ddpcr")
plate <- load_plate(file)
get_filled_drops(plate, "A05")
get_filled_drops(plate, "A05", get_filled_border(plate, "A05"))

Get the cutoff for outliers

Description

Get the cutoff for outliers

Usage

get_outlier_cutoff(plate)

Value

A named list with two elements, giving the cutoff for outliers in each dimension.

Get the cutoff for outliers

Description

Get the cutoff for outliers

Usage

## S3 method for class 'ddpcr_plate'
get_outlier_cutoff(plate)

Get row from well ID

Description

Get row from well ID

Usage

get_row(well)

Examples

get_row("C05" )  # "C"

Get droplet data from a well

Description

Get droplet data from a well

Usage

get_single_well(
  plate,
  well_id,
  empty = FALSE,
  outliers = FALSE,
  clusters = FALSE
)

Arguments

Value

A dataframe with the fluorescence value of all droplets in the given well.

Get all wells between two wells (assume a rectangle layout)

Description

Get all wells between two wells (assume a rectangle layout)

Usage

get_wells_btwn(well1, well2)

Examples

get_wells_btwn("C04", "D06")

Does a well have a statistically significant number of negative droplets?

Description

Classify a well as having a significant negative cluster (eg. a mutant well) or not using a binomial test.

We can call a well as mutant if it is statistically significantly more than 1 mutant drops, then the mutant frequency is 1.4 significantly more than 1 P(x >= 7) = 1 - P(x <= 7) + P(x = 7) = 1 - pbinom(7, 500, .01) + dbinom(7, 500, .01) = 0.237 > 0.01 So not statistically significantly enough, so we say it's a wildtype well. But if there are 5000 drops and 70 mutant drops (same 1.4 with higher absolute numbers), then P(x >= 70) = 1 - pbinom(70, 5000, .01) + dbinom(70, 5000, .01) = 0.004 So this is indeed significant, and this well would be deemed mutant.

Usage

has_signif_negative_cluster(plate, neg, pos)

Arguments

Value

TRUE if the number of negative drops is statistically significant, FALSE otherwise.

Does a ddPCR plate have a step with this name?

Description

Does a ddPCR plate have a step with this name?

Usage

has_step(plate, step)

Arguments

Examples

## Not run: 
dir <- sample_data_dir()
plate <- new_plate(dir)
steps(plate)
has_step(plate, 'REMOVE_FAILURES')
has_step(plate, 'NO_SUCH_STEP')

## End(Not run)

Plate type: HEX-positive PNPP

Description

A ddPCR plate of type hex_positive_pnpp, which can also be expressed as (HEX+)/(FAM+HEX+), is a subtype of both pnpp_experiment and wildtype_mutant_pnpp. Use this plate type if your data has three main clusters of droplets: double-negative (empty droplets), FAM+HEX+ (wildtype droplets) and HEX+FAM- (mutant droplets).

Details

Plates with this type have the following analysis steps: INITIALIZE, REMOVE_FAILURES, REMOVE_OUTLIERS, REMOVE_EMPTY, CLASSIFY, RECLASSIFY.

Plates with this type have the following droplet clusters: UNDEFINED, FAILED, OUTLIER, EMPTY (double-negative), RAIN (not empty but not wildtype nor negative), POSITIVE (wildtype), NEGATIVE (mutant).

See the README for more information on plate types.

See Also

plate_types
wildtype_mutant_pnpp
fam_positive_pnpp
analyze
remove_failures
remove_outliers
remove_empty
classify_droplets
reclassify_droplets

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$hex_positive_pnpp)
type(plate)
plate %>% analyze %>% plot

## End(Not run)

Determine if a given path is a valid directory

Description

Determine if a given path is a valid directory

Usage

is_dir(path)

Arguments

Is the plate object dirty (ie has changed since the analysis was run)?

Description

Is the plate object dirty (ie has changed since the analysis was run)?

Usage

is_dirty(plate)

Arguments

Value

TRUE if any plate settings have changed that require the plate analysis to re-run; FALSE otherwise

Is a plate empty?

Description

A plate is considered empty if it has not yet been fully initialized, and thus its status is 0.

Usage

is_empty_plate(plate)

See Also

status

Determine if a given path is a valid file

Description

Determine if a given path is a valid file

Usage

is_file(path)

Arguments

Is the given parameter a range?

Description

Is the given parameter a range?

Usage

is_range(x)

Examples

is_range("C05")            # FALSE
is_range(c("C05", "F05"))  # FALSE
is_range("C05")            # FALSE
is_range("C05, F05")       # TRUE
is_range("C05:F05")        # TRUE
is_range("C05.F05")        # FALSE

Determine if a well had a successful ddPCR run

Description

This function runs the actual algorithm for determining which wells failed.

Usage

is_well_success(plate, well_id)

Value

FALSE if there are obvious quality problems with the well that suggest the ddPCR run failed; TRUE otherwise.

Determine if a well had a successful ddPCR run

Description

Determine if a well had a successful ddPCR run

Usage

## S3 method for class 'ddpcr_plate'
is_well_success(plate, well_id)

Determine if a well had a successful ddPCR run

Description

Very similar to the is_well_success method of the base plate type, except for this plate type we know where we expect to see droplets so we can save time by using QC metrics more specific to this plate type.

Usage

## S3 method for class 'pnpp_experiment'
is_well_success(plate, well_id)

Run the interactive analysis tool (Shiny app) in a web browser

Description

In addition to the functions provided in this package, the ddpcr package also provides an interactive tool that can be used to analyze ddPCR data more easily. The tool will be launched in a web browser.

Usage

launch()

Load a previously saved ddPCR plate

Description

Reloads a plate that has been saved with save_plate.

Usage

load_plate(file)

Arguments

Value

The plate that was saved in the given file.

See Also

save_plate

Examples

plate <- new_plate(sample_data_dir())
save_plate(plate, "myplate")
plate2 <- load_plate("myplate")
plate3 <- load_plate("myplate.rds")
identical(plate, plate2)
identical(plate, plate3)
unlink("myplate.rds")

Get the indices of the local maxima in a list of numbers

Description

Get the indices of the local maxima in a list of numbers

Usage

local_maxima(x)

Arguments

Value

A vector containing the indices of the elements that are local maxima in the given input.

Examples

local_maxima(c(1, 5, 3, 2, 4, 3))

Get the indices of the local minima in a list of numbers

Description

Get the indices of the local minima in a list of numbers

Usage

local_minima(x)

Arguments

Value

A vector containing the indices of the elements that are local minima in the given input.

Examples

local_minima(c(1, 5, 3, 2, 4, 3))

Convert a list of lists returned from vapply to a dataframe

Description

When running a vapply function and each element returns a list with multiple values, the return value is a list of lists. This function can be used to convert that return value into a data.frame.

Usage

lol_to_df(lol, name = "well")

Arguments

See Also

named_vec_to_df

Examples

vapply(c("a", "b", "c"),
       function(x) list(low = x, up = toupper(x)),
       list(character(1), character(1))) %>%
  lol_to_df("key")

Mark the clusters of droplets only in certain wells to their assigned cluster

Description

This function simply looks at all droplets of certain wells and marks the cluster of each droplet according to the gates that are already calculated. This function is called once after classify_droplets_single determines the gates for every well, and it's called again when reclassifying wells gives us more accurate information.

Usage

mark_clusters(plate, wells)

Overwrite a column in a data.frame based on a matching column in another df

Description

Sometimes you want to merge two dataframes and specify that column X in one dataframe should overwrite the same column in the other dataframe. If there is a missing value in the column in the new dataframe, then the value from the old dataframe is kept.

Usage

merge_dfs_overwrite_col(olddf, newdf, cols, bycol = "well")

Arguments

Examples

df <- function(...) data.frame(..., stringsAsFactors = FALSE)

df1 <- df(a = 1:4, b = c("one", NA, "three", "four"))
df2 <- df(a = 1:4, b = c("ONE", "TWO", NA, "FOUR"))
merge_dfs_overwrite_col(df1, df2, "b", "a")
merge_dfs_overwrite_col(df2, df1, "b", "a")

df3 <- df(a = 1:3, b = c("one", NA, "three"))
df4 <- df(a = 2:4, b = c("TWO", NA, "FOUR"))
merge_dfs_overwrite_col(df3, df4, "b", "a")
merge_dfs_overwrite_col(df4, df3, "b", "a")

df5 <- df(a = 1:3, b = c("one", "two", "three"), c = letters[1:3])
df6 <- df(b = c("ONE", "TWO", "THREE"), c = LETTERS[1:3], a = 1:3)
merge_dfs_overwrite_col(df5, df6, "b", "a")
merge_dfs_overwrite_col(df6, df5, "b", "a")

df7 <- df(a = 1:3, b = c("one", "two", "three"))
df8 <- df(a = 1:4)
merge_dfs_overwrite_col(df7, df8, "b", "a")
merge_dfs_overwrite_col(df8, df7, "b", "a")

df9 <- df(a = 1:3, b = c("one", "two", "three"), c = 1:3)
df10 <- df(a = 1:3, b = c("ONE", NA, "THREE"), c = 4:6)
merge_dfs_overwrite_col(df9, df10, c("b", "c"), "a")
merge_dfs_overwrite_col(df10, df9, c("b", "c"), "a")

Name of variable in PNPP experiment metadata

Description

A default PNPP experiment uses the names "positive" and "negative" for its two non-empty clusters. If they are changed (for example, to "wildtype" and "mutant"), then any variable in the metadata will be renamed to use these names. meta_var_name translates a default metadata variable name to the correct one.

Usage

meta_var_name(plate, var)

See Also

pnpp_experiment

Examples

plate <- new_plate(dir = sample_data_dir(), type = plate_types$pnpp_experiment)
negative_name(plate) <- "mutant"
meta_var_name(plate, 'num_negative_drops')

Move columns to the back of a data.frame

Description

This function is taken from daattali/rsalad R package.

Usage

move_back(df, cols)

Arguments

Examples

df <- data.frame(a = character(0), b = character(0), c = character(0), stringsAsFactors = TRUE)
move_back(df, "b")
move_back(df, c("b", "a"))

Move columns to the front of a data.frame

Description

This function is taken from daattali/rsalad R package.

Usage

move_front(df, cols)

Arguments

Examples

df <- data.frame(a = character(0), b = character(0), c = character(0), stringsAsFactors = TRUE)
move_front(df, "b")
move_front(df, c("c", "b"))

Write a message to the user if the 'ddpcr.verbose' option is on

Description

Running a ddpcr analysis results in many messages being printed to the console. By default, these messages are on when the user is using R interactively and off otherwise. You can overwrite this setting with options(ddpcr.verbose = FALSE).

Usage

msg(...)

Arguments

Plate name

Description

Get or set the name of a dataset.

Usage

name(plate)

name(plate) <- value

Arguments

Value

Plate name

Examples

## Not run: 
plate <- new_plate(sample_data_dir())
name(plate)
name(plate) <- "foo"
name(plate)

## End(Not run)

Convert a named vector returned from vapply to a dataframe

Description

When running a vapply function and each element returns a single value, the return value is a named vector. This function can be used to convert that return value into a data.frame. Similar to lol_to_df, but because the output format from vapply is different depending on whether a single value or multiple values are returned, a different function needs to be used.

Usage

named_vec_to_df(v, name, rowname = "well")

Arguments

See Also

lol_to_df

Examples

vapply(c("a", "b", "c"),
       toupper,
       character(1)) %>%
  named_vec_to_df("capital", "letter")

Create a new ddPCR plate

Description

Any ddPCR analysis must start by creating a ddPCR plate object. Use this function to read ddPCR data into R and create a plate object that can then be analyzed.

Usage

new_plate(dir, type, data_files, meta_file, name, params)

Arguments

Details

See the README for more information on plate types.

Value

A new ddPCR plate object with droplet data loaded that is ready to be analyzed.

Providing ddPCR data

The first step to using the ddpcr package is to get the ddPCR data into R. This package uses as input the data files that are exported by QuantaSoft. For a dataset with 20 wells, QuantaSoft will create 20 well files (each ending with "_Amplitude.csv") and one results file. The well files are essential for analysis since they contain the actual droplet data, and the results file is optional because the only information used from it is the mapping from well IDs to sample names.

The easiest way to use your ddPCR data with this package is to Export the data from QuantaSoft into some directory, and providing that directory as the dir argument. This way, this package will automatically find all the data files as well as the results file. Alternatively, you can provide the data files (well files) manually as a list of filenames using the data_files argument. If you use the data_files argument instead of dir, you can also optionally provide the results file as the meta_file argument. If no results file is provided then the wells will not be mapped to their sample names.

Plate parameters

Every plate has a set of default parameters that are used in the analysis. You can see all the parameters of a plate with the params function. If you want to provide different values for some parameters when initializing a plate, you can do that with the params argument. This is considered an advanced feature.

For example, if you inspect the parameters of any ddPCR plate, you will see that by defalt the random seed used by default is 8. If you want to create a new plate that uses a different random seed, you could do so like this:

plate <- new_plate(sample_data_dir(), params = list('GENERAL' = list('RANDOM_SEED' = 10)))
plate 

Most numeric parameters that are used in the algorithms of the analysis steps can be modified in a similar fashion. This can be used to fine-tune the analysis of a plate if you require different parameters.

See Also

plate_types
type
reset
analyze
plot.ddpcr_plate
params

Examples

## Not run: 
plate <- new_plate(sample_data_dir())

## End(Not run) 

Run the next step in an analysis

Description

Every ddPCR plate has a set of defined steps that are taken in order, that together constitute "analyzing" the plate. Calling the next_step function will run the next step in the analysis, which may take several minutes. If you want to run all the remaining steps at once, use analyze instead.

Usage

next_step(plate, n = 1)

Arguments

Value

The ddPCR plate after running the next step

See Also

plot.ddpcr_plate
analyze
steps
plate_data
plate_meta

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$custom_thresholds)
plate <- next_step(plate)

## End(Not run) 

Normalize a file name to .rds suffix

Description

Normalize a file name to .rds suffix

Usage

normalize_to_rds(file)

Examples

normalize_to_rds("somefile")       # somefile.rds
normalize_to_rds("somefile.rds")   # somefile.rds
normalize_to_rds("somefile.r")     # somefile.r.rds

Convert a number to plate column

Description

Convert a number to plate column

Usage

num_to_col(num)

Examples

num_to_col(5)  # "05"

Convert a number to plate row

Description

Convert a number to plate row

Usage

num_to_row(num)

Examples

num_to_row(4)  # "D"

Given an axis (X or Y), return the other

Description

Given an axis (X or Y), return the other

Usage

other_dim(dim = c("X", "Y"))

Examples

other_dim("X")
other_dim("Y")

Plate parameters

Description

Every ddPCR plate object has adjustable parameters associated with it. Each parameter belongs to a category of parameters, and has a unique name. For example, there are general parameters (category 'GENERAL') that apply to the plate as a whole, and each analysis step has its own set of parameters that are used for the algorithm in that step.

You can either view all parameters of a plate by not providing any arguments, view all parameters in a category by providing the category, or view the value of a specific parameter by providing both the category and the parameter name.

Usage

params(plate, category, name)

params(plate, category, name) <- value

Arguments

Details

Setting new parameter values should only be done by advanced users. Note that if you change any parameters, you need to re-run the analysis in order for the parameter changes to take effect.

Tip: it can be easier to visually inspect the parameters by wrapping the return value in a str().

Warning: Do not directly set the GENERAL-X_VAR or GENERAL-Y_VAR parameters. Instead, use x_var or y_var.

Value

If no category is provided, return all parameters. If a category is provided, return all parameters in that category. If both a category and a name are provided, return the value of the specific parameter.

See Also

x_var

Examples

## Not run: 
plate <- new_plate(sample_data_dir())

# retrieving plate parameters
str(params(plate))
str(params(plate, 'GENERAL'))
params(plate, 'GENERAL', 'RANDOM_SEED')

# setting plate parameters
params(plate, 'GENERAL', 'RANDOM_SEED') <- 10
str(params(plate, 'GENERAL'))

## End(Not run)

Parent plate type

Description

Each ddPCR plate has a "parent" plate type from which it inherits all its properties. When creating a custom plate type, if your plate type inherits from any plate type other than the base type of ddpcr_plate, you must define this function to return the parent plate type. Inheriting from a parent plate means that the same cluster types, analysis steps, and parameters will be used by default.

Usage

parent_plate_type(plate)

Arguments

Details

See the README for more information on plate types.

Value

The parent type of the given plate.

See Also

type
define_params
define_clusters
define_steps

Parent plate type of default plates

Description

Parent plate type of default plates

Usage

## S3 method for class 'ddpcr_plate'
parent_plate_type(plate)

Arguments

Parent plate type of any plate

Description

Parent plate type of any plate

Usage

## Default S3 method:
parent_plate_type(plate)

Arguments

Parent plate type of FAM-positive PNPP

Description

Parent plate type of FAM-positive PNPP

Usage

## S3 method for class 'fam_positive_pnpp'
parent_plate_type(plate)

Arguments

Parent plate type of HEX-positive PNPP

Description

Parent plate type of HEX-positive PNPP

Usage

## S3 method for class 'hex_positive_pnpp'
parent_plate_type(plate)

Arguments

Parent plate type of wildtype/mutant PNPP

Description

Parent plate type of wildtype/mutant PNPP

Usage

## S3 method for class 'wildtype_mutant_pnpp'
parent_plate_type(plate)

Arguments

Plate data (droplets data)

Description

The main piece of information in every ddPCR plate is the droplets data, which contains the fluorescence intensities for every single droplet in every well. After a ddPCR plate gets analyzed, this data also includes the assigned cluster for each droplet. The plate data may be useful programatically, but it's not very useful to a human, so if you want to visualize the plate data you should instead plot it using plot.ddpcr_plate.

Usage

plate_data(plate)

Arguments

Value

A dataframe containing all the droplets in the plate, along with the assigned cluster of each droplet.

See Also

plate_meta
plot.ddpcr_plate

Examples

## Not run: 
plate <- new_plate(sample_data_dir())
plate_data(plate)

## End(Not run)

Overwrite the plate data

Description

When creating custom analysis steps for new plate types, it is often necessary to set the plate data with new data, especially when assigning new clusters to the plate droplets.

Usage

plate_data(plate) <- value

Arguments

See Also

plate_data

Plate metadata

Description

The metadata is a collection of variables that describe each well in the plate. The metadata of an unanalyzed plate only contains basic information about each well, such as the sample name, whether the well was used, and the number of droplets in the well. Analyzing a plate adds many more variables to the metadata, such as the number of empty droplets, the number of outliers, the template concentration, and more.

Usage

plate_meta(plate, only_used = FALSE)

Arguments

Value

A dataframe containing the plate metadata

See Also

plate_data plot.ddpcr_plate

Examples

## Not run: 
plate <- new_plate(sample_data_dir())
plate %>% plate_meta(only_used = TRUE)
plate %>% analyze %>% plate_meta(only_used = TRUE)

## End(Not run)

Overwrite the plate metadata

Description

When creating custom analysis steps for new plate types, it is often necessary to add/change variables in the plate metadata.

Usage

plate_meta(plate) <- value

Arguments

See Also

plate_meta

Supported plate types

Description

Each ddPCR plate has a plate type which determines what type of analysis to run on the data. plate_types is a list containing the plate types that are supported. If no plate type is specified, the default assumed type is ddpcr_plate.

The most useful built-in plate types are: fam_positive_pnpp, hex_positive_pnpp, custom_thresholds.

For full details on the differences between plate types or to learn how to add a new plate type, see the package README.

See Also

new_plate
fam_positive_pnpp
hex_positive_pnpp
custom_thresholds
pnpp_experiment
wildtype_mutant_pnpp
ddpcr_plate
type

Examples

## Not run: 
dir <- sample_data_dir()
new_plate(dir, type = plate_types$ddpcr_plate)
new_plate(dir, type = plate_types$custom_thresholds)
new_plate(dir, type = plate_types$fam_positive_pnpp)

## End(Not run)

Plot a ddPCR plate of type custom thresholds

Description

Same plot as plot.ddpcr_plate but with a few extra features that are specific to plates with custom thresholds. Take a look at plot.ddpcr_plate to see all supported parameters and more information.

Usage

## S3 method for class 'custom_thresholds'
plot(
  x,
  wells,
  samples,
  ...,
  show_thresholds = TRUE,
  col_thresholds = "black",
  show_drops_empty = TRUE,
  col_drops_x_positive = "green3",
  col_drops_y_positive = "blue",
  col_drops_both_positive = "orange"
)

Arguments

Value

A ggplot2 plot object.

See Also

plot.ddpcr_plate
custom_thresholds

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$custom_thresholds)
plate %>% set_thresholds(c(5500, 8000)) %>% analyze %>% plot

## End(Not run)

Plot a ddPCR plate

Description

Plot the data of a ddPCR plate. A plate can be plotted throughout any stage of the analysis, and the most up-to-date data will be shown. For example, a plot performed after initializing a plat will show all the raw data, but a plot performed after analyzing a plate will show information such as empty drops and failed wells.

Usage

## S3 method for class 'ddpcr_plate'
plot(
  x,
  wells,
  samples,
  superimpose = FALSE,
  show_full_plate = FALSE,
  show_drops = TRUE,
  show_drops_empty = FALSE,
  show_drops_outlier = FALSE,
  show_failed_wells = TRUE,
  col_drops = "black",
  col_drops_undefined = col_drops,
  col_drops_failed = col_drops,
  col_drops_empty = col_drops,
  col_drops_outlier = "orange",
  bg_plot = "transparent",
  bg_failed = "#111111",
  bg_unused = "#FFFFFF",
  alpha_drops = 0.2,
  alpha_drops_outlier = 1,
  alpha_bg_failed = 0.7,
  xlab = x_var(plate),
  ylab = y_var(plate),
  title = NULL,
  show_grid = FALSE,
  show_grid_labels = FALSE,
  drops_size = 1,
  text_size_title = 14,
  text_size_row_col = 12,
  text_size_axes_labels = 12,
  text_size_grid_labels = 12,
  ...
)

Arguments

Value

A ggplot2 plot object.

Droplet visibility options

To make it easier to support any plate type with any types of droplet clusters, there are three categories of special parameters that can always be used:

• show_drops_* Whether or not to show a specific group of droplets.

• col_drops_* What colour to use for a specific group of droplets.

• alpha_drops_* What transparency to use for a specific group of droplets.

The * in the parameter name can be replaced by the name of any droplet cluster. Use the clusters function to find out what clusters the droplets in a plate can be assigned to.

For example, the default clusters that exist in a plain ddpcr_plate are "UNDEFINED", "FAILED", "OUTLIER", and "EMPTY". This means that if you want to hide the empty drops and make the transparency of drops in failed wells 0.5, you could add the two parameters show_drops_empty = FALSE and alpha_drops_failed = 0.5. Note that letter case is not important. If another plate type defines a new clsuter of type "MUTANT" and you want to show these drops in red, you can add the parameter col_drops_mutant = "red".

Note that some of the more common combinations of these parameters are defined by default (for example, col_drops_failed is defined in the list of parameters), but these three parameter categories will work for any cluster type.

Extending ddpcr_plate

If you create your own plate type, this default plot function might be enough if there is no extra information you want to display in a plot. If you do need to provide a more customized plot function, it can be a good idea to use the output from this plot function as a basis and only add the code that is necessary to append to the plot. See plot.custom_thresholds as an example of how to extend this plot function.

Examples

## Not run: 
plate <- new_plate(sample_data_dir())
plot(plate)
plate <- plate %>% analyze
plot(plate)
plot(plate, "A01:C05", show_drops_empty = TRUE, col_drops_empty = "red")

## End(Not run)

Plot a ddPCR plate of type PNPP experiment

Description

Same plot as plot.ddpcr_plate but with a few extra features that are specific to PNPP experiments The main additions are that the negative frequency of each well can be written in each well, and well background colours can be used to differentiate between wells with a significant negative cluster vs wells with mostly positive drops. Take a look at plot.ddpcr_plate to see all supported parameters and more information.

Usage

## S3 method for class 'pnpp_experiment'
plot(
  x,
  wells,
  samples,
  ...,
  col_drops_negative = "purple3",
  col_drops_positive = "green3",
  col_drops_rain = "black",
  show_negative_freq = TRUE,
  text_size_negative_freq = 4,
  alpha_drops_low_negative_freq = 0.5,
  show_low_high_neg_freq = TRUE,
  bg_negative = "purple3",
  bg_positive = "green3",
  alpha_bg_low_high_neg_freq = 0.1,
  superimpose = FALSE,
  show_drops = TRUE,
  drops_size = 1
)

Arguments

Value

A ggplot2 plot object.

See Also

plot.ddpcr_plate
pnpp_experiment

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$pnpp_experiment)
positive_dim(plate) <- "Y"
plot(plate)
plate <- plate %>% analyze
plot(plate)
plot(plate, "A01:C05", col_drops_rain = "blue")

## End(Not run)

Plot a ddPCR plate of type wildtype/mutant PNPP

Description

Same plot as plot.pnpp_experiment but with a few extra features that are specific to wildtype/mutant PNPP plates. Take a look at plot.pnpp_experiment to see all supported parameters and more information.

Usage

## S3 method for class 'wildtype_mutant_pnpp'
plot(
  x,
  wells,
  samples,
  ...,
  col_drops_mutant = "purple3",
  col_drops_wildtype = "green3",
  col_drops_rain = "black",
  show_mutant_freq = TRUE,
  text_size_mutant_freq = 4,
  alpha_drops_low_mutant_freq = 0.5,
  show_low_high_mut_freq = TRUE,
  bg_mutant = "purple3",
  bg_wildtype = "green3",
  alpha_bg_low_high_mut_freq = 0.1
)

Arguments

Value

A ggplot2 plot object.

See Also

plot.ddpcr_plate
plot.pnpp_experiment
wildtype_mutant_pnpp

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$fam_positive_pnpp) %>% analyze
wells_wildtype(plate)
plot(plate)
plate <- plate %>% analyze
plot(plate)
plot(plate, "A01:C05", col_drops_rain = "blue")

## End(Not run)

Plate type: PNPP experiment

Description

PNPP stands for "Positive-Negative;Positive-Positive", which is a reflection of the clusters of non-empty droplets in the wells. Use this plate type when your ddPCR data has three main clusters: double-negative (FAM-HEX-; empty droplets), double-positive (FAM+HEX+; represent the "PP" in PNPP), and singly-positive (either FAM+HEX- or HEX+FAM-; represent the "NP" in PNPP).

Details

Every pnpp_experiment plate must define which dimension is its positive dimension. The positive dimension is defined as the dimension that corresponds to the dye that has a high fluoresence intensity in all non-empty droplets. The other dimension is defined as the variable dimension. For example, assuming the HEX dye is plotted along the X axis and the FAM dye is along the Y axis, a FAM+/FAM+HEX+ plate will have "Y" as its positive dimension because both non-empty clusters have FAM+ droplets. Similarly, a HEX+/FAM+HEX+ plate will have "X" as its positive dimension.

The positive dimension must be set in order to use a pnpp_experiment. It is not recommended to use this type directly; instead you should use one of the subtypes (fam_positive_pnpp or hex_positive_pnpp). If you do use this type directly, you must set the positive dimension with positive_dim.

Plates with this type have the following analysis steps: INITIALIZE, REMOVE_FAILURES, REMOVE_OUTLIERS, REMOVE_EMPTY, CLASSIFY, RECLASSIFY.

Plates with this type have the following droplet clusters: UNDEFINED, FAILED, OUTLIER, EMPTY (double-negative), RAIN, POSITIVE, NEGATIVE.

See the README for more information on plate types.

See Also

plate_types
fam_positive_pnpp
hex_positive_pnpp
wildtype_mutant_pnpp
positive_dim
wells_positive
wells_negative
analyze
remove_failures
remove_outliers
remove_empty
classify_droplets
reclassify_droplets

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$pnpp_experiment)
type(plate)

## End(Not run)

Representation of a 2D point

Description

Representation of a 2D point

Usage

point2d(x)

Arguments

Value

An object of class point2d with the given coordinates.

Examples

point2d(c(10, 20))

Positive dimension in a PNPP experiment

Description

Get or set the positive dimension (X or Y), which is defined as the dimension that has a high fluorescence intensity in all non-empty drops in a pnpp_experiment plate.

Usage

positive_dim(plate)

positive_dim(plate) <- value

Arguments

See Also

pnpp_experiment
variable_dim

Examples

plate <- new_plate(dir = sample_data_dir(), type = plate_types$pnpp_experiment)
positive_dim(plate) <- "Y"

Name of dye in positive dimension in PNPP experiment

Description

Get the name of the dye that is along the positive dimension.

Usage

positive_dim_var(plate)

See Also

pnpp_experiment
positive_dim

Name identifier for positive and negative droplets

Description

Name identifier for positive and negative droplets

Usage

positive_name(plate)

positive_name(plate) <- value

negative_name(plate)

negative_name(plate) <- value

Arguments

See Also

pnpp_experiment

Print info about a ddPCR plate

Description

Print info about a ddPCR plate

Usage

## S3 method for class 'ddpcr_plate'
print(x, ...)

Suppress all output from an expression. Works cross-platform.

Description

Suppress all output from an expression. Works cross-platform.

Usage

quiet(expr, all = TRUE)

Arguments

Convert a list of ranges to a vector of its individual components

Description

Convert a list of ranges to a vector of its individual components

Usage

range_list_to_vec(rangel)

Examples

range_list_to_vec("A01")
range_list_to_vec("A01:A04")
range_list_to_vec("A01, B03")
range_list_to_vec("A01, B02:C04, C07")

Extract the two endpoints of a range

Description

Extract the two endpoints of a range

Usage

range_to_endpoints(range)

Examples

range_to_endpoints("B05:G09")   # c("B05", "G09")
range_to_endpoints("B05")       # c("B05", "B05")

Convert a range to a vector of all elements between the endpoints

Description

Convert a range to a vector of all elements between the endpoints

Usage

range_to_seq(rng)

Examples

range_to_seq(c(5, 8))   # 5:8
range_to_seq(c(8, 5))   # 5:8

Analysis step: Reclassify droplets

Description

After classifying droplets into clusters in each well individually, it may be useful to attempt to reclassify droplets in wells where the gates are not very clearly defined. This function uses information taken from wells with a high negative frquency (where the gate is easily defined) to adjust the gates in the other wells.

See the README for more information about the algorithm used.

Usage

reclassify_droplets(plate)

Details

This function is recommended to be run as part of an analysis pipeline (ie. within the analyze function) rather than being called directly.

Note

This is an S3 generic, which means that different ddPCR plate types can implement this function differently. See the README for more information on how to implement custom ddPCR plate types.

See Also

analyze
reclassify_droplets_single
mark_clusters

Analysis step: Reclassify droplets

Description

Analysis step: Reclassify droplets

Usage

## S3 method for class 'pnpp_experiment'
reclassify_droplets(plate)

Reclassify droplets in a well

Description

Reclassify droplets in a well

Usage

reclassify_droplets_single(plate, well_id, ...)

Reclassify droplets in a well

Description

Reclassify droplets in a well given the ratio of where to place the MT border over the median WT drops

Usage

## S3 method for class 'pnpp_experiment'
reclassify_droplets_single(plate, well_id, ..., consensus_border_ratio)

Analysis step: Remove empty droplets

Description

Find the empty droplets (double-negative droplets) in each well in a plate and assign these droplets to the EMPTY cluster.

See the README for more information about the algorithm used to find empty droplets.

Usage

remove_empty(plate)

Arguments

Details

This function is recommended to be run as part of an analysis pipeline (ie. within the analyze function) rather than being called directly.

Value

A ddPCR plate with the empty droplets marked as empty. The plate's metadata will have a few new variables relating to the empty droplets.

Note

This is an S3 generic, which means that different ddPCR plate types can implement this function differently. See the README for more information on how to implement custom ddPCR plate types.

See Also

analyze
get_empty_cutoff

Analysis step: Remove empty droplets

Description

Analysis step: Remove empty droplets

Usage

## S3 method for class 'ddpcr_plate'
remove_empty(plate)

Arguments

Analysis step: Remove empty droplets

Description

Analysis step: Remove empty droplets

Usage

## S3 method for class 'pnpp_experiment'
remove_empty(plate)

Arguments

Analysis step: Remove failed wells

Description

Check if any wells have failed the ddPCR experiment by checking a series of quality control metrics. If any well is deemed as a failure, all the droplets in that well will be assigned to the FAILED cluster.

See the README for more information about the algorithm used to find failed wells.

Usage

remove_failures(plate)

Arguments

Details

This function is recommended to be run as part of an analysis pipeline (ie. within the analyze function) rather than being called directly.

Value

A ddPCR plate with the droplets in failed wells marked as failed. The plate's metadata will have a new variable success which will be FALSE for any failed well and TRUE for all others.

Note

This is an S3 generic, which means that different ddPCR plate types can implement this function differently. See the README for more information on how to implement custom ddPCR plate types.

See Also

analyze
is_well_success

Analysis step: Remove failed wells

Description

Analysis step: Remove failed wells

Usage

## S3 method for class 'ddpcr_plate'
remove_failures(plate)

Arguments

Analysis Step: Remove outlier droplets

Description

Identify droplets that have an abnormally high fluorescence intensity as outliers. Any such droplets will be assigned to the OUTLIER cluster.

See the README for more information about the algorithm used to find outlier droplets.

Usage

remove_outliers(plate)

Arguments

Details

This function is recommended to be run as part of an analysis pipeline (ie. within the analyze function) rather than being called directly.

Value

A ddPCR plate with outlier droplets marked as outliers. The plate's metadata will have a new variable drops_outlier which will count the number of outlier droplets in each well.

Note

This is an S3 generic, which means that different ddPCR plate types can implement this function differently. See the README for more information on how to implement custom ddPCR plate types.

See Also

analyze
get_outlier_cutoff

Analysis Step: Remove outlier droplets

Description

Analysis Step: Remove outlier droplets

Usage

## S3 method for class 'ddpcr_plate'
remove_outliers(plate)

Arguments

Reset a plate

Description

Reset a ddPCR plate object back to its original state. After resetting a plate, all the analysis progress will be lost, but the original droplet data and plate metadata will be kept. Two common reasons to reset a plate are either to restart the analysis, or to re-analyze the plate as a different plate type.

Usage

reset(plate, type, params, keep_type = FALSE, keep_params = FALSE)

Arguments

Value

A new unanalyzed ddPCR plate

See Also

plate_types
new_plate

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$custom_thresholds)
plate <- reset(plate, type=plate_types$fam_positive_pnpp)

## End(Not run) 

Convert a plate row to a number

Description

Convert a plate row to a number

Usage

row_to_num(row)

Examples

row_to_num("D")  # 4L

Get sample data

Description

These functions return sample data files or folders and can be used to load ddPCR plates with sample data. They are used primarily in the documentation examples, but you can also use them for learning purposes. There are two sample datasetes: a small dataset and a large dataset. The small dataset contains the full raw data, but the large dataset only includes the processed data because the raw data would be too large.

sample_data_dir: get the directory of the small or large sample dataset
sample_data_file: get path to one of the data files in the small sample dataset
sample_results_file: get path to the results file of the small sample dataset
sample_plate: get the ddpcr plate object containing the data of the small or large dataset

Usage

sample_data_dir()

sample_data_file()

sample_results_file()

sample_plate(size = c("small", "large"))

Arguments

Examples

plate1 <- new_plate(dir = sample_data_dir())
plate2 <- new_plate(data_files = sample_data_file(), meta_file = sample_results_file())
plate3 <- sample_plate()

Save a ddPCR plate

Description

Saves a plate to a file, including all its data, parameters, and current analysis state. The file can be read back later using load_plate. The file is not human-readable - if you want to save the droplets data or the metadata of a plate, then first retrieve the data using plate_data or plate_meta and save it with write.csv.

Usage

save_plate(plate, file)

Arguments

Value

The given plate, unchanged.

See Also

load_plate

Examples

plate <- new_plate(sample_data_dir())
save_plate(plate, "myplate")
unlink("myplate.rds")

Reset plate parameters to their defaults

Description

Use this function to reset a ddPCR plate's parameters back to their default values.

Usage

set_default_params(plate)

Arguments

Value

The plate with the parameters set to the plate type's default values.

See Also

params

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$custom_thresholds)
x_var(plate) <- "VIC"
plate <- set_default_params(plate)

## End(Not run) 

Plate status

Description

The status of a plate corresponds to the number of analysis steps that have taken place. A plate that has been initialized but has not yet been analyzed at all has status 1.

If you add custom analysis steps to a new plate type, you should make sure to update the status of the plate after each step. You can use check_step to ensure that the plate is at an appropriate status before beginning each step.

Usage

status(plate)

status(plate) <- value

See Also

steps
check_step

Get step ID by step name

Description

Get step ID by step name

Usage

step(plate, step)

Examples

## Not run: 
plate <- new_plate(sample_data_dir())
# see what step names exist and their order
steps(plate)
step(plate, 'REMOVE_OUTLIERS')

## End(Not run)

Inform the user that an analysis step is starting

Description

When an analysis step starts running, it's recommended to call this function so that the user will know what step is taking place. The time when a step begins gets recorded so that the user will see exactly how long it took.

Usage

step_begin(text)

Arguments

See Also

step_end

Inform the user that an analysis step finished

Description

When an analysis step is done, it's recommended to call this function so that the user will know the step finished. The time when a step finishes gets recorded so that the user will see exactly how long it took. An earlier call to step_begin must have taken place.

Usage

step_end()

See Also

step_begin

Get step name by ID

Description

Get step name by ID

Usage

step_name(plate, step)

Examples

## Not run: 
plate <- new_plate(sample_data_dir())
# see what step names exist and their order
steps(plate)
step_name(plate, 2)

## End(Not run)

Analysis steps of a ddPCR plate

Description

Every ddPCR plate type has an ordered set of steps that are run to analyze the data. You can run all the steps with analyze or run the analysis step by step with next_step. The order of the steps in the list is the order in which they are run on the dataset.

Usage

steps(plate)

Arguments

Value

A named character vector, where every name is the human-readable name of an analysis step, and every value is the name of the function used to perform the step.

See Also

analyze
next_step

Examples

## Not run: 
dir <- sample_data_dir()
new_plate(dir) %>% steps
new_plate(dir, plate_types$fam_positive_pnpp) %>% steps

## End(Not run)

Subsetting a ddPCR plate

Description

Select specific wells or samples from a ddPCR plate.

Usage

## S3 method for class 'ddpcr_plate'
subset(x, wells, samples, targets_ch1, targets_ch2, ...)

Arguments

Details

Keeps only data from the selected wells. If sample names are provided instead of well IDs, then any well corresponding to any of the sample names will be kept. Either well IDs or sample names must be provided, but not both.

Value

Plate with data only from the specified wells/samples.

Range notation

The most basic way to select wells is to provide a vector of wells such as c("B03", "C12"). When selecting wells, a special range notation is supported to make it easier to select many wells: use a colon (:) to specify a range of wells, and use a comma (,) to add another well or range. When specifying a range, all wells in the rectangular area between the two wells are selected. For example, B04:D06 is equivalent to B04, B05, A05, C04, C05, C06, D04, D05, D06. You can combine multiple ranges in one selection; see the Examples section below. Note that this notation is only supported for the wells parameter, but not for the samples parameter.

Examples

plate <- new_plate(sample_data_dir())
plate %>% wells_used
plate %>% subset("C01") %>% wells_used
plate %>% subset(c("C01", "F05")) %>% wells_used
plate %>% subset("C01, F05") %>% wells_used
plate %>% subset("C01:F05") %>% wells_used
plate %>% subset("C01:F05, A01") %>% wells_used
plate %>% subset("A01:C03") %>% wells_used
plate %>% subset("A01:C05") %>% wells_used
plate %>% subset("A01, A05:F05") %>% wells_used
plate %>% subset("A01, A05:C05, F05") %>% wells_used
plate %>% subset("A01:A05, C01:C05, F05") %>% wells_used
plate %>% subset(samples = "Dean") %>% wells_used
plate %>% subset(samples = c("Dean", "Mike")) %>% wells_used

Get/set the thresholds

Description

For ddPCR plates of type custom_thresholds, get or set the thresholds that divide the four droplet quadrants.

Usage

thresholds(plate)

thresholds(plate) <- value

set_thresholds(plate, value)

Arguments

Value

The current thresholds

See Also

custom_thresholds
x_threshold
y_threshold

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$custom_thresholds)
thresholds(plate)
thresholds(plate) <- c(5500, 8000)
set_thresholds(plate, c(5500, 8000))

## End(Not run)

Plate type

Description

Get the type of a ddPCR plate. See the README for more information on plate types.

Usage

type(plate, all = FALSE)

Arguments

Value

A character vector with the plate type(s).

See Also

plate_types

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$fam_positive_pnpp)
type(plate)
type(plate, TRUE)

## End(Not run)

Get unanalyzed cluseter IDs

Description

Get the clusters that have not been considered yet in the analysis. This means the UNDEFINED cluster (since all droplets begin as UNDEFINED) and also all clusters that are defined later than the current cluster. The latter is to ensure that when re-running an analysis step, droplets that were analyzed in a later step will still be considered for analysis.

Usage

unanalyzed_clusters(plate, current)

Arguments

Value

All clusters that have not yet been analyzed

See Also

cluster

Examples

## Not run: 
plate <- new_plate(sample_data_dir())
unanalyzed_clusters(plate, 3)
unanalyzed_clusters(plate, cluster(plate, "OUTLIER"))
plate %>% unanalyzed_clusters(cluster(plate, "OUTLIER")) %>% cluster_name(plate, .)

## End(Not run)

Variable dimension in a PNPP experiment

Description

Get or set the variable dimension (X or Y), which is defined as the dimension that can have both high and low fluorescence intensities in the non-empty drops in a pnpp_experiment plate.

Usage

variable_dim(plate)

variable_dim(plate) <- value

See Also

pnpp_experiment
positive_dim

Examples

plate <- new_plate(dir = sample_data_dir(), type = plate_types$pnpp_experiment)
variable_dim(plate) <- "Y"
variable_dim(plate)
positive_dim(plate)

Name of dye in variable dimension in PNPP experiment

Description

Get the name of the dye that is along the variable dimension.

Usage

variable_dim_var(plate)

See Also

pnpp_experiment
variable_dim

Show a warning message

Description

Show a warning message

Usage

warn_msg(x)

Arguments

Get metadata info of a well

Description

Each ddPCR plate has associated metadata that stores infromation for every well. Use this function to retrieve any metadata information for a single well or for a list of wells.

Usage

well_info(plate, well_ids, var)

Arguments

Value

A character vector with the wanted metadata variable value for each well.

See Also

plate_meta

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$custom_thresholds)
well_info(plate, "A01", "drops")

## End(Not run) 

Get mutant wells

Description

After a ddPCR plate of type wildtype_mutant_pnpp has been analyzed, get the wells that were deemed as mutant.

Usage

wells_mutant(plate)

Arguments

Value

Character vector with well IDs of mutant wells

See Also

wildtype_mutant_pnpp
wells_wildtype

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$fam_positive_pnpp) %>% analyze
wells_mutant(plate)

## End(Not run)

Get negative wells

Description

After a ddPCR plate of type pnpp_experiment has been analyzed, get the wells that were not deemed as having mostly positive droplets.

Usage

wells_negative(plate)

Arguments

Value

Character vector with well IDs of negative wells

See Also

pnpp_experiment
wells_positive

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$pnpp_experiment) %>% analyze
wells_negative(plate)

## End(Not run)

Get positive wells

Description

After a ddPCR plate of type pnpp_experiment has been analyzed, get the wells that were deemed as having mostly positive droplets.

Usage

wells_positive(plate)

Arguments

Value

Character vector with well IDs of positive wells

See Also

pnpp_experiment
wells_negative

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$pnpp_experiment) %>% analyze
wells_positive(plate)

## End(Not run)

Get successful/failed wells

Description

Get a list of wells that had successful or failed ddPCR runs. One of the analysis steps for ddPCR plates includes identifying failed wells, which are wells where the ddPCR run was not successful and did not produce useful droplet data.

Usage

wells_success(plate)

wells_failed(plate)

Arguments

Value

List of wells that had a successful/failed ddPCR run.

See Also

remove_failures

Examples

## Not run: 
dir <- sample_data_dir()
plate <- new_plate(dir) %>% analyze
plate %>% wells_success
plate %>% wells_failed

## End(Not run)

Get wells used in a ddPCR plate

Description

Get a list of the wells that have any data in a ddPCR plate.

Usage

wells_used(plate)

Arguments

Value

List of wells that have any data in the given plate.

See Also

subset.ddpcr_plate

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$custom_thresholds)
wells_used(plate)
plate <- subset(plate, "A01:C05")
wells_used(plate)

## End(Not run) 

Get wildtype wells

Description

After a ddPCR plate of type wildtype_mutant_pnpp has been analyzed, get the wells that were deemed as wildtype.

Usage

wells_wildtype(plate)

Arguments

Value

Character vector with well IDs of wildtype wells

See Also

wildtype_mutant_pnpp
wells_mutant

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$fam_positive_pnpp) %>% analyze
wells_wildtype(plate)

## End(Not run)

Plate type: wildtype/mutant PNPP

Description

A plate of type wildtype_mutant_pnpp is a subtype of pnpp_experiment that assumes the double-positive cluster denotes wildtype and the other non-empty cluster denotes mutant droplets. There are two plate types that are subtypes of wildtype_mutant_pnpp: fam_positive_pnpp and hex_positive_pnpp. It is not recommended to use this type directly; instead you should use one of the subtypes.

Details

Plates with this type have the following analysis steps: INITIALIZE, REMOVE_FAILURES, REMOVE_OUTLIERS, REMOVE_EMPTY, CLASSIFY, RECLASSIFY.

Plates with this type have the following droplet clusters: UNDEFINED, FAILED, OUTLIER, EMPTY (double-negative), RAIN (not empty but not wildtype nor negative), POSITIVE (wildtype), NEGATIVE (mutant).

See the README for more information on plate types.

See Also

plate_types
fam_positive_pnpp
hex_positive_pnpp
pnpp_experiment
analyze
remove_failures
remove_outliers
remove_empty
classify_droplets
reclassify_droplets

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$wildtype_mutant_pnpp)
type(plate)

## End(Not run)

Get/set the X threshold

Description

For ddPCR plates of type custom_thresholds, get or set the threshold along the X axis that divides the droplet quadrants.

Usage

x_threshold(plate)

x_threshold(plate) <- value

Arguments

Value

The current X threshold

See Also

custom_thresholds
y_threshold
thresholds

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$custom_thresholds)
x_threshold(plate)
x_threshold(plate) <- 5500
plot(plate)

## End(Not run)

Get/set the X/Y variable (dye name)

Description

By default, the dye visualized along the X axis is HEX and the dye visualized along the Y axis is FAM. You can use these functions to get or set these values if your plate uses different dyes.

Usage

x_var(plate)

y_var(plate)

x_var(plate) <- value

y_var(plate) <- value

Arguments

Details

The X/Y variables are simply parameters in the plate, which can also be accessed or changed using params. You should use these functions to change the X/Y variable rather than changing the parameters directly.

Value

Dye name

See Also

params

Examples

## Not run: 
plate <- new_plate(sample_data_dir())
x_var(plate)
x_var(plate) <- "VIC"
x_var(plate)

## End(Not run)

Get/set the Y threshold

Description

For ddPCR plates of type custom_thresholds, get or set the threshold along the Y axis that divides the droplet quadrants.

Usage

y_threshold(plate)

y_threshold(plate) <- value

Arguments

Value

The current Y threshold

See Also

custom_thresholds
x_threshold
thresholds

Examples

## Not run: 
plate <- new_plate(sample_data_dir(), type = plate_types$custom_thresholds)
y_threshold(plate)
y_threshold(plate) <- 8000
plot(plate)

## End(Not run)