Merge pull request #4106 from solgenomics/topic/wishlist

[sgn.git] / docs / 03_managing_breeding_data / 03_07.md

---
title: "3.7 Managing Field Trials"
layout: doc_page
---

<!-- TOC-START -->
* TOC
{:toc}
<!-- TOC-END -->

To view trial details on the database, click on the "Field Trials" link under the "manage" menu on the toolbar.

![]({{"assets/images/image290.png" | relative_url }})

Clicking on the "Field Trials" link will bring you to the "Manage Trials" page. On this page, trials are organized according to their breeding programs. To access trial details, click on the + icon next to your breeding program.

![]({{"assets/images/image153.png" | relative_url }})

Trials can be placed directly in their breeding program. Alternatively, they can be organized by using folders within each breeding program. Clicking on trial name will take you directly to the trial details page.

![]({{"assets/images/image279.png" | relative_url }})

Trial Detail Page
-----------------

Trial detail page displays important information about individual trial including breeding program, location, year, description of the trial, design, and any files associated with that trial.

![]({{"assets/images/trial_detail_page_start.png" | relative_url }})

The "Navigator" section on the trial detail page allows easy access to all aspects of your trial. This section contains subsections for printing labels for your plots or plants, recording phenotypes, viewing your trial layout or design, viewing phenotypes for this trial, or conducting analyses.

![]({{"assets/images/trial_detail_page_navigator.png" | relative_url }})

Adding Trials
-------------

Only users with the account status of "submitter" may create trials. To learn how to change your account status from "user" to "submitter" visit the [*Managing Your Account*]({{site.baseurl}}{% link 01_basic_website_usage.md%}#managing-your-account) page.

### Prerequisites

-   To add a trial, all of your accessions should already exist in the database before you begin to design a trial. If you have accessions that are not in the database, see the instructions for adding accessions .

-   Breeding program and location for your trial should also exist in the database. If you need to add breeding program and/or location to the database, see instructions for adding breeding program and location in the “Managing Breeding Programs” and “Managing locations” respectively.

On the “Manage Trials” page, there are three alternative methods for you to add new trials: by using “Add Trial” form, “Upload Trial” form, or “Add Multi-location Trial” form.

![]({{"assets/images/trial_create_manage_trials.png" | relative_url }})

### 3.7.1 Adding a trial by using “Add Trial” form

#### Step 1. Begin the "Design new trial" workflow

Click on “Design New Trial” to begin.

![]({{"assets/images/trial_create_open_form.png" | relative_url }})

The first step in this workflow is an introduction that looks like:

![]({{"assets/images/trial_create_form_1.png" | relative_url }})

Here it gives information about what is required for a trial, including that to create a new trial, you need to create a list of the accessions that you would like to use in the trial. Lists can be viewed, created, and modified with the "**lists**" tool at the upper right of the screen. For more information on lists, click [*here*]({{site.baseurl}}{% link 01_basic_website_usage.md%}#working-with-lists).

#### Step 2. Enter "Trial Information"

On this screen you need to enter basic information about the trial, such as breeding program and location(s). You must also select a design type, such as Complete Block Design. The design is important because it influences how your genotypes are distributed and randomized over the trial. You must first click validate before proceeding to the next step.

![]({{"assets/images/trial_create_form_2.png" | relative_url }})

#### Step 3. Enter "Design Information"

On this screen you need to specify a list of accessions to use in the experiment. This list must be a valid list of accessions. You must also specify all required design information, such as number of blocks in this case.

![]({{"assets/images/trial_create_form_3.png" | relative_url }})

#### Step 4. Enter "Field Map Information" (Optional)

On this screen you can specify how the row and column numbers will be generated for the plots in the trial. The row and column number represent a relative position of the plot in the field. If you are not exactly sure of how you will plant the plots in the field or you have an irregular (non-rectangular) layout, you can skip this step for now. This information can be added on the Trial Detail Page once the trial is saved in the database in order to reflect exactly how the plots were planted in the field.

![]({{"assets/images/trial_create_form_4.png" | relative_url }})

#### Step 5. Custom Plot Naming (Optional)

On this screen it is possible to change the format in which plot names will be generated for your trial. It is recommended to skip this step and just use the format generated by the database by default.

![]({{"assets/images/trial_create_form_5.png" | relative_url }})

#### Step 6. Review Designed Trial

On this screen you can review the trial that the database has generated.

You will see a graphical representation of the trial. The numbers on the squares represent the plot_number of each plot and on mouse hover you can see further information about the plot.

![]({{"assets/images/trial_create_form_6_top.png" | relative_url }})

You will also see a table representation of all the plots and their information. If you want to redo the randomization, you can click the "Redo Randomization" button.

![]({{"assets/images/trial_create_form_6_middle.png" | relative_url }})

At the bottom there is a brief summary of the trial followed by two buttons.

![]({{"assets/images/trial_create_form_6_bottom.png" | relative_url }})

#### Step 7. Add Field Management Factors to your design (Optional).

You can add Field Management Factors by clicking "Add Field Management Factor(s) to Design". Clicking this opens a dialog to name your factor. You can name this to account for fertilizer or watering regime or inoculation or anything else. This is optional and can be added from the trial detail page afterwards.

![]({{"assets/images/add_management_factor_name_dialog.png" | relative_url }})

Click "Continue" and a dialog will appear where you can specify plots for which the factor was applied. There is a select all button also.

![]({{"assets/images/add_management_factor_dialog.png" | relative_url }})

#### Step 8. Saving new trial in the database.

Once you are done reviewing the trial you can click "Confirm" to save the generated trial into the database. Once the trial has saved you will see the final completion screen:

![]({{"assets/images/trial_create_form_7.png" | relative_url }})

### 3.7.2 Adding a trial from an uploaded file

If you already have trial design layout in a spreadsheet, you can add your trial into the database by using “Upload Trial” form. To access “Upload Trial” form, click on “Upload Existing Trial(s)” button on the “Manage Trials” page.

![]({{"assets/images/manage_trials.png" | relative_url }})

When you click "Upload Existing Trial(s)" you will see the following workflow. Notice that there are 5 numbered sections to the workflow.

#### Step 1:

The first step is to understand what the format of the trial upload is. It is important to understand that the field layout represents plots in the experiment. Each plot has a globally unique plot_name, a sequential plot_number that is unique in the trial (but not globally unique. e.g. 101, 102, 103 for three separate plots), an accession_name representing what genotype is planted in that plot, and a block_number representing design replication. Each plot can be thought of as having a row_number and a column_number representing the relative position of the plot in a grid (e.g. the top left plot is row 1 column 1 following by row 1 column 2). Each plot can be planted with an amount of seed from a seedlot, where the seedlot_name represents the specific seed packet that was used, and num_seed_per_plot and weight_gram_seed_per_plot represent amount that were transferred from the seedlot_name to the plot_name. Treatments (management factors) can be applied onto plots using additional column names in your file, where a 1 represents if the factor was applied to the plot and an empty cell means it was not applied.

![]({{"assets/images/manage_trials_upload_trial_1.png" | relative_url }})

This information and more can be found by clicking "Information about file format", which shows the following:

![]({{"assets/images/manage_trials_upload_trial_template.png" | relative_url }})


##### Minimum File requirements

-   All accession names in the file must exist in the database. See adding accessions for more information.

-   The uploaded file should be XLS file format (NOT XLSX or CSV).

-   The first row (header) must contain the column names: plot_name accession_name plot_number block_number is_a_control rep_number range_number row_number col_number seedlot_name num_seed_per_plot weight_gram_seed_per_plot

Minimal Example:

| **plot\_name** | **accession\_name** | **plot\_number** | **block\_number** | **is\_a\_control** | **rep\_number** | **range\_number** | **row\_number** | **col\_number** | **seedlot\_name** | **num\_seed\_per\_plot** | **weight\_gram\_seed\_per\_plot** |
|----------------|---------------------|------------------|-------------------|--------------------|-----------------|-------------------|-----------------|-----------------|-------------------|--------------------------|-----------------------------------|
| 2018plot1      | my_accession1       | 101              | 1                 | 1                  |                 |                   |                 |                 |                   |                          |                                   |
| 2018plot2      | my_accession2       | 201              | 2                 |                    |                 |                   |                 |                 |                   |                          |                                   |
| 2018plot3      | my_accession2       | 102              | 1                 |                    |                 |                   |                 |                 |                   |                          |                                   |
| 2018plot4      | my_accession1       | 202              | 2                 | 1                  |                 |                   |                 |                 |                   |                          |                                   |

##### File validation

-   In case of errors in the uploaded file such as missing or invalid data, a window will appear listing the specific errors in the file that must be corrected before a successful upload.

##### Uploading a trial with Field Management Factors

-   You can upload a trial with field management factor(s) by adding additional column(s). The column header will be the factor e.g. fertilizer, watering regime, inoculation, etc. and the values in these columns will be either 1 or empty, indicating that the factor was applied to the plot or not.

#### Step 2:

Once you feel that your experiment field layout is in the right format, click on to the Next Step. You will see the following form which must be filled in completely:

![]({{"assets/images/manage_trials_upload_trial_2.png" | relative_url }})

The trial name must be globally unique in the database. Please try to follow standard naming conventions for your group.

First you need to validate the form, and then you can click "Upload Trial".

#### Step 3:

In the case where you have uploaded an experiment using accession_names that are not already present in the database, you will be taken to this screen. If the accession_names in your file are all already in the database, this step will be skipped.
The reason it is necessary for your accessions to be in the database before you can add a trial using them is that a single accession can be used among many trials and therefore must exist as a separate entity in the database; because of this it is also very important to be careful about adding wrongly duplicated accession_names into the database. From this screen it is possible to make a new list with the missing accession_names and then click "Add Accessions to the database" to immediately resolve the issue. Once all your accessions are in the database, click to move to the Next Step.

![]({{"assets/images/manage_trials_upload_trial_3.png" | relative_url }})

#### Step 4:

In the case where you have uploaded an experiment using seedlot_names that are not already present in the database, you will be taken to this screen. If the seedlots in your file are all already in teh database, this step will be skipped.
The reason it is necessary for your seedlots to be in the database before you can add a trial using them is that a ginel seedlot can be used among many trials and therefore must exist as a separate entity in the database. From this screen it is possible to add the missing seedlots; you can either upload an XLS file to add many at once or you can add them one by one. Once all your seedlots are in the database, click to move to the Next Step.

![]({{"assets/images/manage_trials_upload_trial_4.png" | relative_url }})

#### Step 5:

If there are any other errors with your file, such as if the plot_names are not globally unique in the database or your plot_numbers are not unique in your trial or row_number is not an integer or any other error, you will see the errors listed in the red box. It is up to you to correct these errors in your file. Simply open up the file you selected earlier in Excel and correct the issues and then save the file. Then you can click "Submit Trial" and it will resubmit it for you. You can continue to edit your file here and submit as many times as you need until it is accepted.

![]({{"assets/images/manage_trials_upload_trial_5.png" | relative_url }})

#### Completion screen

Whether you were lucky enough to submit your trial successfully on Step 2 or if you tried many times on Step 5, once your trial has been saved in the database you will see the following screen:

![]({{"assets/images/manage_trials_upload_trial_6.png" | relative_url }})


### 3.7.3 Multi-location trials

To add multi-location trials, simply select the multiple locations while using the 'Add Trial' form.

This will create a separate trial for each selected location, but they will share the same design and will be grouped in a single folder.

By default each trial design will have a fresh randomization, but if desired you may check the "Use same randomization for all locations" option.

### 3.7.4 Viewing Trial HeatMap

In this section, trial physical layout is displayed by default.

![]({{"assets/images/heatmap_default_display.png" | relative_url }})

#### Tracking plot images on fieldMap

Plot images can be seen on fieldMap if a plot is associated to any image.

![]({{"assets/images/fieldmap_plot_image.png" | relative_url }})

To view plot image(s), click on a plot, a dialog will appear.

![]({{"assets/images/fieldmap_view_plot_image.png" | relative_url }})

On the appeared dialog, click on View plot images. To see more images if a plot has more that 2 images, click on See more images... Medium size of an image can be viewed by clicking on an image.

![]({{"assets/images/fieldmap_display_plot_image.png" | relative_url }})


#### Viewing assayed trait heatmap

Phenotype heatmap can be viewed by selecting a specific assayed trait from the selectbox drop-down. Mousing over the plots, highlights the plot in green and also displays the plot's field information including the selected trait's phenotype value.

![]({{"assets/images/heatmap_assayed_trait_view.png" | relative_url }})

[//]: # ![]({{"assets/images/trial_detail_page_trait_heatmap.png" | relative_url }})

#### Suppressing Plot Phenotype

Clicking on a plot on the heatmap would display a dialog that has a button for suppressing a plot phenotype value for a given trait. A suppressed plot value can be excluded during trial analysis and phenotype download.

![]({{"assets/images/trial_detail_page_suppress_phenotype.png" | relative_url }})

### 3.7.5 Adding additional information in the “Trial Detail” page

After you added a new trial to the database, you can edit trial details or add more information for that trial through the“Trial Detail” page.

#### Uploading Physical Trial Layout

You can upload physical trial layout by clicking on the “Upload trial coordinates” button on the “Trial Detail” page.

![]({{"assets/images/image332.png" | relative_url }})

Please check file format carefully. You can find file format information by clicking on the “Spreadsheet format” on the “Upload trial coordinates” window.

![]({{"assets/images/image340.png" | relative_url }})

Spreadsheet format:

![]({{"assets/images/image190.png" | relative_url }})

#### Physical Trial Layout File requirements

-   All plot names in the file must exist in the database.

-   The uploaded file should be tab delimited (txt).

-   The first row (header) must contain the column names

Example:

| plot\_name | row\_number | col\_number |
|------------|-------------|-------------|
| plot1      | 1           | 1           |
| plot2      | 1           | 2           |
| plot3      | 1           | 3           |

Select the trial layout coordinates file that you want to upload for this trial, then click “OK” button to upload the file.

![]({{"assets/images/image79.png" | relative_url }})

The following message is displayed after the coordinates are uploaded.

> <img src='{{"assets/images/image276.png" | relative_url }}' width="300" height="138" />

The field layout can be viewed by clicking on the “Trial Heatmap Section” to see a drop-down of the field map.

<img src='{{"assets/images/heatmap_default_display.png" | relative_url }}' width="571" height="351" />

#### Downloading Field Map Spreadsheet

Field map spreadsheet can be downloaded if the trial has field coordinate (row and column numbers) uploaded for it plots.
To download, click on the Download FieldMap Layout link on the Trial Heatmap section.

![]({{"assets/images/field_map_download_link.png" | relative_url }})

A dialog will appear, click on the submit button to download.

![]({{"assets/images/field_map_download_dialog.png" | relative_url }})

Click to view downloaded spreadsheet.

![]({{"assets/images/field_map_download_spreadsheet.png" | relative_url }})

#### Editing Physical Trial Layout

“Usage Help” link contains information on how to edit physical trial layout.

![]({{"assets/images/image332.png" | relative_url }})

![]({{"assets/images/image319.png" | relative_url }})

![]({{"assets/images/image317.png" | relative_url }})

There are three different options for editing trial layout:

-   Replacing plot accession by clicking on the plot in the layout.

-   Replacing trial accession by using “Edit Field Map” link.

-   Substituting plot accessions by using “Edit Field Map” link.

When you move a cursor over a plot on the trial layout, information for that plot appears.

<img src='{{"assets/images/image320.png" | relative_url }}' alt="Picture2modified.png" width="414" height="361" />

To edit a specific plot, clicking on that plot. Entering new accession on the “Replace Plot Accession” form, then clicking on “Replace Plot Accession” button.

<img src='{{"assets/images/image262.png" | relative_url }}' alt="Picture3modified.png" width="423" height="309" />

To replace an accession (in every plot/plant of that accession), clicking on “Edit Field Map” button.

![]({{"assets/images/image173.png" | relative_url }})

On the “Edit Field Map” window, clicking on “Replace Accession” button.

![]({{"assets/images/image87.png" | relative_url }})

Selecting any accession that you want to replace and entering your new accession, then clicking “Replace Trial Accession” button.

![]({{"assets/images/image85.png" | relative_url }})

You can switch plot accessions between any two plots by clicking on “Substitute Accession” button.

![]({{"assets/images/image162.png" | relative_url }})

On the “Substitute Plot Accession” form, selecting the two plots that you want to switch, then clicking on the “Substitute Plot Accession” button.

![]({{"assets/images/image282.png" | relative_url }})

### 3.7.6 Downloading the Trial Layout from the “Trial Detail” page

Click on "Download Layout" on the Trial Detail page.

![]({{"assets/images/image348.png" | relative_url }})

The trial layout includes all information regarding the observation units in the experiment. The observation units can be plots, plants, or subplots. The trial layout can include trial design information such as the block_number and rep_number. It can also include physical map information such as the row_number and col_number, if that information is available for the trial.
The trial layout also includes information regarding treatments that have been applied in the field.
Optionally, the layout can give information regarding accession's global performance for a list of traits.

![]({{"assets/images/image347.png" | relative_url }})

### 3.7.7 Adding Plant Entries To Your Trial

After you added a new trial to the database you can choose to add plant entries to your trial. Adding plant entries enables plant level phenotyping. It is generally better to enter data at the plant level into the database because it is always possible to calculate plot level phenotypes from the individual plant data.

Plant entries can be added to your trial in two ways:
1) Automatically generated by the database. The only input required is the number of plants per plot.
2) Uploaded in an XLS file. This allows you to specifically name your plant entries.

These two options are available in the "Plant Entries" section on the Trial Detail Page, as shown in the screen shot below.

![]({{"assets/images/trial_detail_page_add_plant_entries.png" | relative_url }})

#### Automatically Generate Plant Entries

Clicking on "Add plant entries" opens the following dialog box. The only input required is the number of plants per plot. This will create plant entries that are named as a concatenation of the plot_name and the plant's index number e.g. plot_name_plant_1

![]({{"assets/images/trial_detail_page_add_plant_entries_autogenerated.png" | relative_url }})

#### Upload Plant Entries

Alternatively, you can choose to upload an XLS file that contains the names of the plant entries. Clicking on "Upload plant entries" opens the following dialog box.

![]({{"assets/images/trial_detail_page_add_plant_entries_upload.png" | relative_url }})

Clicking on "Spreadsheet format" will give you information about the XLS file to upload. Clicking this will open the following dialog box.

![]({{"assets/images/trial_detail_page_add_plant_entries_upload_info.png" | relative_url }})

This shows you that the files requires the header to contain "plot_name" and "plant_name". The plot_name must exist in the database already and the plant_name must be unique in the database.

Along with the file, you must specify "number of plants per plot". This is intended to be the total number of plants that were plants. If the file you upload shows three plants in one plot and four plants in another plot, that is fine.

### 3.7.8 Adding Tissue Sample Entries To Your Trial

Some trials require tissue samples to be collected from plants in a field trial. The database will generate these tissue sample identifiers for you and will maintain all relationships with the plant, plot, accession, etc. To begin, go to the Design section of a trial's detail page and open the "tissue sample entries" section.
Please note that tissue samples are directly related to plants, therefore your trial requires plants before you can add tissue samples.

![]({{"assets/images/manage_trials_tissue_sample_default.png" | relative_url }})

When you click on "Add tissue sample entries" you will see a dialog where you specify the number of tissue samples you require per plant. Once you have specified how many tissues samples, you can give specific words to distinguish samples, such as "root" or "stem", as seen below.

![]({{"assets/images/manage_trials_tissue_sample_create.png" | relative_url }})

Once you have added tissue sample entries they will appear in the design section of the trial as seen below.

![]({{"assets/images/manage_trials_tissue_samples.png" | relative_url }})

Each tissue sample has a detail page where you can add information about the sample, such as if it is in transit or in storage somewhere.

![]({{"assets/images/manage_trials_tissue_sample_detail.png" | relative_url }})

The related stocks section near the bottom of this detail page displays the relationships between all stocks, including tissue samples.

![]({{"assets/images/manage_trials_tissue_sample_related_stock.png" | relative_url }})

### 3.7.9 Uploading GPS Coordinates For Plots

You can upload GPS coordinates for the plots in your trial. There is a link on the Trial Detail Page as shown below.

![]({{"assets/images/trial_detail_page_add_plot_gps.png" | relative_url }})

Clicking on this link will bring up the following dialog.

![]({{"assets/images/trial_detail_page_add_plot_gps_dialog.png" | relative_url }})

Here you can upload an XLS file. To see information on the format of the file that should be uploaded, click on "Spreadsheet format". This will bring up the following dialog.

![]({{"assets/images/trial_detail_page_add_plot_gps_upload_info.png" | relative_url }})

This dialog tells you that the file must be XLS and must contain: plot_name     WGS84_bottom_left_x     WGS84_bottom_left_y     WGS84_bottom_right_x    WGS84_bottom_right_y    WGS84_top_right_x       WGS84_top_right_y       WGS84_top_left_x        WGS84_top_left_y
The GPS coordinates should be WGS84 format and specify a four-pointed polygon around the plot.

### 3.7.10 Uploading Additional Files To Trial

It may be of interest to you to upload additional documents, images, or recordings to your trial. To do this, scroll down to the "Uploaded Additional File" section on the trial detail page. From here you can view and download any of these additional files.

![]({{"assets/images/trial_upload_additional_file.png" | relative_url }})

To upload an additional file, click on the "Upload Additional Files" link. A dialog will appear where you simply select your desired file. For information, you can click "Upload information" to see the following message.

![]({{"assets/images/trial_upload_additional_file_info.png" | relative_url }})

### 3.7.11 Deleting Trial Data

To delete a trial data, click on the "Delete trial data" section. There are links to delete traits, layout and trial entry data.

![]({{"assets/images/trial_detail_page_delete_trait1.png" | relative_url }})

To delete assayed trait data, click on "Delete trait data" link. On the appeared dialog, confirm deletion by clicking on the "Select Traits For Deletion" button, then select one or more traits to delete from the trial.

![]({{"assets/images/trial_detail_page_delete_trait2.png" | relative_url }})

![]({{"assets/images/trial_detail_page_delete_trait3.png" | relative_url }})

To delete trial layout data, click on the "Delete layout data" link. Confirm deletion on the appeared dialog.

To Delete trial entry, click on "Delete trial entry" link. Confirm deletion on the appeared dialog.