Generating example files to work with

If you don’t have any files to work with, or if you can’t figure out why something isn’t working, I’ve included a good number of files in this package that should be helpful. To generate these files in your computer, use the make_example_files() function. If you do not provide a directory, it will create the files in your current directory:

make_example_files(directory = '~/Desktop/example_directory')

I will refer to these files moving forward, so if you want to be able to replicate any of the steps, you can use these files as a guide.

Sample weighing using barcoded tubes

A key aspect of measuring microbiota density in fecal samples is to accurately mass each sample. To do this, we’ve developed a barcoding system to label and keep track of tubes as they are weighed using the digital scale. A key part of this is the LabelMaker Spreadsheet which makes barcodes for each sample. With these labels on the tubes, we can weigh each tube quickly and keep track of which tube is which. By weighing each tube before and after collecting a sample, we can calculate the mass of each sample. Since tubes can easily get shuffled around, the point of the mass_and_order() function is to use the barcodes to keep track of each sample, and to pair each full weight with the correct empty weight. We can use it to read in two sample mass files and get a sample mass output:

sample_weights <- mass_and_order(empty_weights = 'Example_empty_weights.txt', full_weights = 'Example_full_weights.txt')

If you take a look at the example weight files (Example_empty_weights.txt and Example_full_weights.txt) you’ll notice that in one of the two files, I have scanned BOTH the tube barcodes that are physically on the bottoms of the matrix tubes, as well as the LabelMaker-generated barcodes (which may be printed on the labels). By containing this information in either one of the empty or full barcode files, we can patch together that information so we can then add more meaningful information about our samples to our sample masses.

Another feature of this function is that by default, samples are put into the data frame in the order provided by the file containing full weights. This way, if you weigh your samples in the order in which you add them to a rack, you will have the samples in the correct order after using this function.

To get an even better sense of where each individual tube is, we can use the plate scanner from the Cho lab to give each of our samples a location within the 96-tube rack. If you have your samples in the Matrix tubes, and within the Matrix rack, you can scan your rack and export the .csv file to be used in this same function. By adding this file to our function, we can get a data frame that also includes sample location information:

sample_weights_and_location <- mass_and_order(empty_weights = 'Example_empty_weights.txt', full_weights = 'Example_full_weights.txt', order = 'Example_matrix_plate_scan.csv', plate_name = 'Example Plate')

If you do not provide a plate name, it will return the plate name given from the plate scanner.

Reading in files with sample information

If you have a file that contains more sample information that what is contained in the barcode, you can also read it in and join it with any other data. To do so, you can use the read_sample_info() function, which was written to be able to take in any type of tabular data (.csv OR excel), and load it into R. You can then join the data using the dplyr package join functions which should be loaded with the FaithLabTools package. It is important to note that at least one column must be shared between your sample information and the data you want to join it to - otherwise it will be impossible to combine the right information and sample.

sample_information <- read_sample_info('Example_sampleInfo.csv')

annotated_data <- left_join(sample_weights_and_location, sample_information) %>% mutate(ReaderWell = SampleWell)

This data can now be used to join with other data sources and to plot data according to any number of variables included in the sample information.

Reading plate reader files

Whether you are using the plate reader to read an ELISA or DNA concentrations, you can use the general read_plate() function. The function is intended to read files from the plate reader directly (the raw excel file that it produces), and expects that the plate reader only makes one measurement per well:

plate_reader_data <- read_plate(plate_reader_file = 'Example_BR_raw.xlsx', plate_name = 'Example Plate')
#> New names:
#> * `` -> `..1`
#> * `` -> `..2`
#> * `` -> `..3`
#> * `` -> `..4`
#> * `` -> `..5`
#> * … and 10 more

The function also allows you to specify if you are using a 384-well plate by changing the size parameter, but I haven’t worked much with 384-well plates and the plate reader so it isn’t as well tested as using a 96-well plate.

Measuring DNA concentrations

For the specific case of measuring DNA concentrations using the qubit dyes (HS or BR), I’ve put together a function that will read in the plate reader file, compute a standard curve, and generate DNA concentrations for each sample. The measure_dna_concentration() function requires a lot more inputs than the previous ones, so I will describe them more in full:

• plate_reader_file - path to the raw file from the plate reader
• standards_plate_reader_file - path to the raw file from the plate reader that contains the standards information. If the standards are on the same plate that you want to measure, you can leave this out, since it defaults to the plate_reader_file.
• standard_wells - a vector of the wells that contain the standards, in increasing concentration order. These need to be in the 2-digit format (e.g. “A01”, “B07”, and NOT “A1”, “B7”).
• dye_used - specify whether you measured DNA with the HS or BR dye. Must be wrapped in quotes.
• qubit_volume - indicate how much DNA was used to measure the DNA (default = 2 uL)
• elution_volume - indicate how much EB was used to elute the DNA (default = 100 uL)
• plate_size - indicate plate size (default = 96, and honestly I haven’t tried 384)
• plate_name - a name for the plate, similar to examples above
• print_standard_curve - TRUE or FALSE to indicate whether or not to print a plot of the standard curve

sample_HS_dna <- measure_dna_concentration(plate_reader_file = 'Example_HS_raw.xlsx', standards_plate_reader_file = 'Example_standards_raw.xlsx', standard_wells = c("A01", "A02", "A03", "A04", "A05", "A06", "A07", "A08"), dye_used = "HS", qubit_volume = 2, elution_volume = 100, plate_size = 96, plate_name = 'Example Plate', print_standard_curve = TRUE)

sample_BR_dna <- measure_dna_concentration(plate_reader_file = 'Example_BR_raw.xlsx', standards_plate_reader_file = 'Example_standards_raw.xlsx', standard_wells = c("B01", "B02", "B03", "B04", "B05", "B06", "B07", "B08"), dye_used = "BR", qubit_volume = 2, elution_volume = 100, plate_size = 96, plate_name = 'Example Plate', print_standard_curve = TRUE)

The output of these functions looks like:

If you are measuring the same sample with both the BR and HS dyes, you may want to combine the data from these two measurements. As in the example above, it is not uncommon for samples with low concentration of DNA to produce negative values if you measure only with the BR dye (e.g. sample in well A01 above). The qubit_merger() function helps stitch together measurements of samples with both dyes by selecting the DNA concentration according to the following rules:

• If the HS DNA concentration is less than 75 ng/uL and the BR DNA concentration is less than 50 ng/uL, use the HS DNA concentration.
• If the HS concentration is greater than 75 ng/uL and the BR DNA concentration is greater than 50 ng/uL, use the BR DNA concentration.
• For all other cases, average the HS and BR DNA concentrations.

By doing this, we try to keep the DNA concentration measurements in the more reliable ranges of the Qubit dyes.

sample_dna_combined <- qubit_merger(hs_data = sample_HS_dna, br_data = sample_BR_dna) %>% mutate(PlateID = 'Example Plate', SampleWell = ReaderWell)

This produces a data table that contains both of the individual measured concentrations and the “final” concentration:

Joining, filtering, and computing new columns

To demonstrate a couple of examples of how to filter rows from your table, and how to add new columns to your data, I’ll walk through a “manual” version of computing microbiota density from samples. All of the pieces are in place if you follow the functions outlined above, we just need to do some division, and clean up our data.

The DNA measurement functions will produce a table containing DNA concentrations based on all the samples in the plate that are not standards (so either 88 or 96 samples, for most uses). If there are wells that were empty, they will be carried over using these functions. To eliminate them, we can filter out individual wells using something like filtered_table <- filter(unfiltered_table, !(SampleWell %in% c("F11", "F12", "G04"))). We can employ a variation of this to filter our samples based on some of the fields in our annotated sample information above. If you have used the Matrix plate scanner, you can simply filter out any samples that have a “No Tube” in the TubeBarcode field. Another filter that you can use commonly is to remove any samples whose mass is less than 10 mg. These are often empty tubes, or samples for which the fecal sample was too small, and so any errors in the DNA extraction are exacerbated when you calculate things like microbiota density.

As a side note, I use the pipe function (%>%) from the magrittr package that really helps make the code much more readable by passing along the results of any computations/data performed on the left of the pipe to the functions to the right of the pipe.

sample_dna_annotated <- left_join(annotated_data, sample_dna_combined) %>% 
  filter(SampleMass > 10, TubeBarcode != "No Tube")