docs/03_managing_breeding_data/03_19.md

   1 ---
   2 title: "3.19 Managing Spectral Data"
   3 layout: doc_page
   4 ---
   5
   6 <!-- TOC-START -->
   7 * TOC
   8 {:toc}
   9 <!-- TOC-END -->
  10
  11 Breedbase has implemented a flexible spectral data storage protocol that handles spectral data irrespective of the source spectrometer. Spectral data storage and analysis in Breedbase makes use of the R package *waves* for outlier identification, plotting, sample aggregation, and prediction model training.
  12
  13 <img src='{{"assets/images/waves_breedbase_schema.png" | relative_url }}' width="522" />
  14
  15 ---
  16 ### 3.19.1 Initiate upload of spectral data file
  17 Spectral data can be added as a CSV file that includes metadata in the leftmost columns followed by one column per spectral measurement to the right. Rows represent a single scan or sample, each with a unique ID that must match to a Breedbase observationUnitName. Future data transfer using [BrAPI](https://brapi.org) will allow for interoperability with data collection software.
  18
  19 To upload a spectral dataset, navigate to the 'Manage NIRS Data' page by selecting 'NIRS' in the 'Manage' menu and click the blue 'Upload NIRS' button. This will open an upload workflow. A link to the required file format and an example .csv file can be found by clicking in the light blue info box in this workflow. Another example of the file format is shown below.
  20
  21 * **id**: Optional identifier for each NIRS read. The id must be an integer.
  22 * **sampling_id**: Optional identifier for each sample. Strings are allowed.
  23 * **sampling_date**: Optional field. The format allowed is: YYYY-MM-DD.
  24 * **observationunit_name**: Required field that matches existing data in the database. It can be the plot name, subplots, plant name, or tissue sample, depending how your trial is designed.
  25 * **device_id**: Optional field to identify your device. Strings are allowed.
  26 * **device_type**: Required field. It is possible upload data for a single device type. They can be: SCiO, QST, Foss6500, BunchiN500, or LinkSquare.
  27 * **comments**: Optional field for general comments.
  28 All other columns are required wavelengths. You can add how many columns you want upload -- there is no limit.
  29
  30 <img src='{{"assets/images/manage_NIRS_main_display.png" | relative_url }}' width="522" />
  31
  32 <img src='{{"assets/images/upload_NIRS_example_format.png" | relative_url }}' width="522" />
  33
  34 ### 3.19.2 Evaluate and remove spectral outliers
  35 Spectral calibration models can be heavily affected by the presence of outliers, whether they come from spectrometer spectral artifacts or user errors. Mahalanobis distance (Mahalanobis, 1936) is a measure of the distance between a single observation and a larger distribution and is commonly used in the identification of outliers in a multivariate space (Des Maesschalck et al, 2000). The *FilterSpectra()* function in the R package [*waves*](https://CRAN.R-project.org/package=waves) calculates the Mahalanobis distance of each observation in a given spectral matrix using the *stats::mahalanobis()* function. Observations are identified as outliers if the squared distance is greater than the 95th percentile of a $\chi$^2^-distribution with *p* degrees of freedom, where *p* is the number of columns (wavelengths) in the spectral matrix (Johnson and Wichern, 2007). In Breedbase, this procedure is applied on a per-dataset basis on upload and outliers are given binary tags "Outlier."
  36
  37 ### 3.19.3 Plot spectra with outliers highlighted
  38 After outlier identification, a plot is generated using the *PlotSpectra()* function in [*waves*](https://CRAN.R-project.org/package=waves). This function uses the filtered spectra and *ggplot2::ggplot()* to create a line plot with outliers highlighted by color. A list of rows identified as outliers are shown beneath the plot. Plots are saved as .png files and linked to the original input datasets. Plot image files can be downloaded via the "Download Plot" button in the upload workflow.
  39
  40 <img src='{{"assets/images/upload_NIRS_plot_example.png" | relative_url }}' width="522" />
  41
  42 ### 3.19.4 Aggregate spectra by observation units
  43 To obtain a stable and reliable spectral profile, most spectrometer manufacturers recommend that multiple spectral scans are captured for each sample. While some spectrometers aggregate these scans internally, many do not, requiring the user to do so before analysis can take place. Breedbase handles these cases upon data upload following filtering steps by calling the *AggregateSpectra()* function from [*waves*](https://CRAN.R-project.org/package=waves), saving the aggregated scans for future access through the search wizard feature. Scans are aggregated by sample mean (e.g. plot-level basis) according to the provided observationUnitName field. After aggregation, the user exits the upload workflow and the raw data file is saved in the upload archive.
  44
  45 ### 3.19.5 References
  46 * De Maesschalck, R., Jouan-Rimbaud, D., and Massart, D. L. (2000). The Mahalanobis distance. Chemom. Intell. Lab. Syst. 50(1): 1-18.
  47 * Johnson, R. A. \& Wichern, D. W. (2007). Applied Multivariate Statistical Analysis (6th Edition). p 773.
  48 * Mahalanobis, P. C. (1936). On the generalized distance in statistics. National Institute of Science of India.
  49
  50 [**Analysis tool documentation**]({{site.baseurl}}{% link 04_data_analysis_tools.md%}#spectral-analysis)