In whitwort/plateKinetics: Analysis of kinetic reads from multiwell plates

Introduction

This package uses a nested list structure to describe the design of experiments. Designs include information about what kind of multiwell plate was used, how source data files should be loaded, and the organization of samples among wells (factor annotations).

The simplest way to provide this information when loading an experiment with loadExperiment is to create a design file in yaml format. Alternatively, you can supply a nested R list of the same structure.

To create a template design file in the current working directory, you can simply run:

newDesign()

Provide a file argument to choose an alternative path or file name:

newDesign(file = "~/myproj/myproj-design.yaml")

A simple example

Before we dive into each element of a design, let's look at a simple complete example in yaml file format:

loader:   read.table
platform: 96
wells:    A1 -> H12

channels:
  channel1: data1.txt
  channel2: data2.txt

factors:

  factor1:
    A1 -> H6:  A
    A7 -> H12: B

  factor2:
    A1 -> D12: C
    E1 -> H12: D

This design describes an experiment performed 96-well format, using all wells on the plate, with two sets of readings found in two different input files (data1.txt and data2.txt) read using R's built in read.table. Finally, in this experiment wells contain one of two different levels of two categorical factors.

An identical design created as a native R list structure would be:

list( loader   = "read.table"
    , platform = '96'
    , wells    = "A1 -> H12"
    , channels = list( channel1 = "data1.txt", channel2 = "data2.txt")
    , factors  = list( factor1 = list(`A1->H6`  = "A", `A7->H12` = "B")
                     , factor2 = list(`A1->D12` = "C", `E1->H12` = "D")
                     )
    )

Describing wells

There are two places in a design file where you'll need to describe sets of wells: the top level wells: entry and within factor blocks. In both contexts there is some syntatic sugar available to make it easy to describe complex setups.

First you can just list a single well, like:

A1

You can list multiple wells using commas:

A1, A10, B6

You can also describe rectangular blocks of wells using the forward arrow -> syntax (as in the example above). The use of the right-handed horizontal arrow is designed to reflect that this syntax will generate a set of well labels row-wise across the rectangle. For example:

A1 -> B2

is equivalent to:

A1, A2, B1, B2

This is important to keep in mind if you are loading source data without explicit well labels.

Finally, it's fine to combine all of the above options and white space is stripped, so the following perfectly valid (if odd):

A1 ->B4, C6, H6-> H12

In all cases, the usable well label strings are defined by the platform (see below).

Design entries

The following subsections describe each of the design entries (top level associate array keys in yaml or names on an R list). The order does not matter.

loader

The value should be string that evaluates to a function used to read source data files listed in channels; if no value is provided read.table will be used by default. This package provides a suitable read.magellan function if you are collecting data using Tecan's Magellan suite.

If you need to provide a custom data loader function it should take a single required argument, the path to the source data file to load, and return a data.frame containing read data. See the source-files vignette for acceptable return data.frame structures.

platform

The value should be a string describing the multiwell plate platform used in the experiment. This can be done in two ways. First, the string can reference a platform on the built-in platforms list: r names(plateKinetics::platforms).

Alternatively, this string can evaluate to variable holding a character matrix of well labels in the current environment. If you need to create a custom platform beyond what is provided by the built in platforms list, the platformLabels function might be helpful.

wells

The value should be the set of wells within the platform that were used to collect data in this experiment. If you are loading data from source files without explicit well labels it is essential that the series of well lables given here matches the order of data in input files.

If no value is given this will default to all wells in the platform.

channels

The channels entry should hold an associative array/list that links an experimental plate reader setting with a source data file. For example:

channels:
  channel1: file1.txt
  channel2: file2.txt

Here the function given by the loader (above) would be used to load data from file1.txt and file2.txt and refer to those data as belonging to channel1 and channel1, respectively.

If you need to append data from multiple files (for example, when you have to stop and restart a run) that can be done using a yaml list. For example:

channels:
  channel1: 
    - file-A.txt
    - file-B.txt

Or the equivalent one-line syntax:

channels:
  channel1: [file-A.txt, file-B.txt]

Both of these examples would append time course data loaded from file-B.txt to the data in file-A.txt. If the time stamps in the second file are all larger than the time stamps in the first file, it is assumed that they are abolute times and do not need to be adjusted.

If this isn't the case, times in each file will be adjusted based on the ending time in the previous file. Additionally, you can supply a set of timeOffset as a top-level design entry to include offsets in this calculation.

For example:

channels:
  channel1: 
    - file-A.txt
    - file-B.txt
timeOffset: 100

In this case, the time points in file-B.txt would all be increased by the highest time point in file-A.txt plus 100. The timeOffset entry should be a list if you are appending more than two files (with one fewer value than the number of files):

channels:
  channel1: 
    - file-A.txt
    - file-B.txt
    - file-C.txt
timeOffset: [100, 80]

Adjustments are made cumulatively across multiple files.

factors

Factors describe your experimental variables, which can be either quantitative or categorical. Each entry under factors gives the name of an experimental factor. Each subentry under a factor should link wells to categorical levels or numeric values as key: value pairs.

For example, suppose you have two experimental factors: Factor1 and Factor2. Factor1 has two categorical levels: "A" (in wells A1 to A2) and "B" (in wells B1 to B2) and Factor2 has the quantitative levels 1 (in row 1) and 2 (in row 2). This design would be described with:

factors:

  factor1:
    A1, A2: A
    B1, B2: B

  factor2:
    A1, B1: 1
    A2, B2: 2

Factor names should be valid R variable names; if they are not they will be coerced to a string that is on import (see ?make.names). If you intend for factors to be quatitative (as for Factor2 in the example above), make sure entries only contain numbers. Units for values can be included in the factor names themselves if needed.

whitwort/plateKinetics documentation built on May 4, 2019, 5:23 a.m.