Add a study

And where do I add my experimental design? Where can I describe how I grew my plants under different conditions?

With studies you can describe materials and resources. In this Violas-PhD-Project you can add the different growth conditions of your plants here.

Create a new study

Section titled Create a new study

ARCitect

1. Click on the plus icon next to studies to add a new study.

2. Enter a name for the New Study.

   

   AthalianaColdStress

3. Click New Study.

4. ARCitect adds the study AthalianaColdStress including the folders protocols and resources as well as a README.md and the isa.study.xlsx workbook.

   • DirectoryAthalianaColdStressSugar

     • Directorystudies

       • DirectoryAthalianaColdStress

         • Directoryprotocols

           • …
         • Directoryresources

           • …
         • isa.study.xlsx
         • README.md
     • …

   Note

   The isa.study.xlsx is not displayed inside ARCitect.

5. Click on the study’s name (AthalianaColdStress) in the file tree to edit the study metadata in the right panel.

6. Here you can add metadata about your study.

   

   My description: “Cold acclimation analysis of Arabidopsis leaf tissue”

7. Click the Save button to save your metadata.

   Note

   On the study level, you can add the same type of metadata as on the investigation level in the previous step.

   Tip

   If you add data from an external source or database, this is a good place to reference the data source or associated publications.

Protocols

Section titled Protocols

I saved my lab notes about the plant growth in the file growth_protocol.md. Can I store that somewhere?

You can use the protocol subdirectory to store free-text protocols that describe how the samples or materials were created.

ARCitect

1. Right-click on the protocols folder and select Import Files from the context menu.

2. Select the file growth_protocol.md from the demo data and click Open.

   Note

   In this example Viola has prepared a Markdown file (.md) as a protocol. Markdown Guide: https://www.markdowntutorial.com/

3. The file is added to your ARC.

   • DirectoryAthalianaColdStressSugar

     • Directorystudies

       • DirectoryAthalianaColdStress

         • Directoryprotocols

           • growth_protocol.md
     • …

4. A click on the protocol’s file name opens a text editor in the right panel.

Add samples to your study

Section titled Add samples to your study

And where do I note down the plants I used?

Structured metadata annotation in the ARC is mostly achieved via spreadsheet tables.

Let us start by adding the samples to the study.

ARCitect

1. Click on the study’s name (AthalianaColdStress) in the file tree.

2. At the bottom of the right panel, click on the + right next to the Study sheet.

3. This adds a new table sheet.

4. Right-click on sheet’s tab to rename it to plant-growth.

5. Click on the “Add Building Block” button next to “Or start from scratch!” option.

6. From the dropdown menu in the Add Building Block widget:

   • select Input -> Source Name and click Add Column
   • select Output -> Sample Name and click Add Column

7. At the bottom of the table, type 6 in the text field and click + to add six rows to your table.

   

   I called my plants: “Cold1”, “Cold2”, “Cold3” and “RT1”, “RT2”, “RT3”

   And the leaf samples accordingly: “Cold1_leaf”, “Cold2_leaf”, “Cold3_leaf” and “RT1_leaf”, “RT2_leaf”, “RT3_leaf”.

8. Add the sample identifiers into the columns Input[Source Name] and Output[Sample Name].

   Input[Source Name]	Output[Sample Name]
   Cold1	Cold1_leaf
   Cold2	Cold2_leaf
   Cold3	Cold3_leaf
   RT1	RT1_leaf
   RT2	RT2_leaf
   RT3	RT3_leaf

   This means that input “Cold1” results in output “Cold1_leaf”.

9. Click the Save button to save your metadata.

Referencing the protocol

Section titled Referencing the protocol

In the next step we draw a link between the original protocol and the structured metadata. We reference the protocol in the annotation table to say:

Plant “Cold1” results in sample “Cold1_leaf” by applying the protocol to it.

ARCitect

1. On top of the annotation table, click Add Building Block.

2. From the dropdown menu select More -> ProtocolREF and click Add Column.

3. On top, click File Picker.

4. In the File Picker widget, click Pick Files.

5. From the ARC select the file protocols/growth_protocol.md and click Open.

6. Select a cell in the Protocol REF column and click Insert file names.

   Input[Source Name]	Output[Sample Name]	ProtocolREF
   Cold1	Cold1_leaf	protocols/growth_protocol.md
   Cold2	Cold2_leaf
   Cold3	Cold3_leaf
   RT1	RT1_leaf
   RT2	RT2_leaf
   RT3	RT3_leaf

7. To fill the complete column with the same value, right-click on a cell and select Fill Column.

   Input[Source Name]	Output[Sample Name]	ProtocolREF
   Cold1	Cold1_leaf	protocols/growth_protocol.md
   Cold2	Cold2_leaf	protocols/growth_protocol.md
   Cold3	Cold3_leaf	protocols/growth_protocol.md
   RT1	RT1_leaf	protocols/growth_protocol.md
   RT2	RT2_leaf	protocols/growth_protocol.md
   RT3	RT3_leaf	protocols/growth_protocol.md

8. Click the Save button to save your metadata.

Tip

While it is recommended to store the protocol in an open format (.md, .txt, .docx, …), everything is possible also an URL to an electronic lab notebook.

But from my understanding this is not really machine readable, right?

Yes, but it still containes valuable information! As we now can link the protocol to the samples, we can later on use the protocol to extract more information from the samples.

From free-text protocol to structured metadata

Section titled From free-text protocol to structured metadata

Finding the metadata vocabulary and descriptors

Section titled Finding the metadata vocabulary and descriptors

The ARC builds on standards and leverages ontologies for metadata annotation. The details are out of the scope of this guide. However, it is good to know that a combination of structural and biological ontologies are combined to semantically structure the metadata.

So I need to find the important information in my protocol and then add it to the metadata table?

Yes! Imagine ontologies like a vocabulary. You can use them to describe your samples in a standardized way. This makes it easier for others to understand your data.

Parameterizing the study

Section titled Parameterizing the study

Let us look at the growth protocol and extract the important information.

growth_protocol.md

# Study Name: Growth Protocol for *Arabidopsis thaliana*

## Parameters:
- 200 µmol photons m²/s (200 Einstein)
- Alternating 6°C (cold treatment) and 25°C (control)
- 4 days

## Characteristics:
- *Arabidopsis thaliana*
- Leaf
- Hydroponic culture
- Columbia (Col-0)

...

Then we need to put this information into context:

“Arabidopsis thaliana” is a “Characteristic” of the samples, describing its “Organism”.

Characteristics [ ]

Section titled Characteristics [ ]

• Organism Arabidopsis thaliana
• Tissue Leaf
• Growth medium Hydroponic culture
• Ecotype Columbia

Parameters [ ]

Section titled Parameters [ ]

• Light intensity 200 µEinstein
• Temperature 6°C / 25°C
• Growth time 4d

Add characteristics

Section titled Add characteristics

ARCitect

1. On top of the annotation table, open the Add Building Block widget.

2. From the dropdown menu select Characteristic. The order of blocks shown below may not correspond to what you see in ARCitect but we will learn how to rearrange columns later.

   

   I worked on Arabidopsis thaliana plants

3. Enter organism in the search bar. This search looks for suitable terms in the ontology database.

4. Select the Term with the id OBI:0100026 and click Add Column.

5. In the table, insert values by selecting any cell below Characteristic [organism].

6. Search for Arabidopsis thaliana, select a suitable hit and again fill the complete column with right-click on a cell and select Fill Column.

   Input[Source Name]	Characteristic [organism]	Output[Sample Name]
   Cold1	Arabidopsis thaliana	Cold1_leaf
   Cold2		Cold2_leaf
   Cold3		Cold3_leaf
   RT1		RT1_leaf
   RT2		RT2_leaf
   RT3		RT3_leaf

7. Click the Save button.

   

   Great, I’ve got this! Now I can add building blocks for the characteristics “tissue” and “growth medium” and enter the values “leaf” and “hydroponic plant culture media”, respectively.

Add a parameter with a unit

Section titled Add a parameter with a unit

Parameters works just like Characteristics, right? But they also contain numbers with a unit, how can i add that?

Yes, you are right! Parameters are similar to Characteristics. To use units you can simply select the Unit toggle during the Add building block step and then insert the value in the table afterwards.

ARCitect

1. In the Building Blocks widget, select Parameter, search for growth time.

2. Toggle Unit and search for day in the adjacent search bar. Select the term with the id “UO:0000033” from the unit ontology (UO).

3. Click Add Column.

4. In the annotation table, select any cell below Parameter [growth time] and add “4”.

   Note

   You can see the numbers being complemented with the associated unit.

5. Fill out the other missing parameters, except for “temperature”! This is a special parameter as it dictates our experiment goal.

Add a factor building block

Section titled Add a factor building block

So what do i do with “temperature”? My experiment revolves around this specific parameter.

In this case, you can use a Factor building block. Factors are used to describe the experimental conditions that are manipulated in an experiment.

ARCitect

1. In the Building Blocks widget, select Factor, search for temperature day, select the term with the ID DPBO:0000007.

2. Check the box for Unit and search for degree celsius in the adjacent search bar.

3. Select UO:0000027.

4. Click Add Column.

5. In the annotation table, add “25” vs. “6” degree celsius to the respective samples.

   Input[Source Name]	Characteristic [organism]	Factor [temperature day]	Output[Sample Name]
   Cold1	Arabidopsis thaliana	6 degree celsius	Cold1_leaf
   Cold2	Arabidopsis thaliana	6 degree celsius	Cold2_leaf
   Cold3	Arabidopsis thaliana	6 degree celsius	Cold3_leaf
   RT1	Arabidopsis thaliana	25 degree celsius	RT1_leaf
   RT2	Arabidopsis thaliana	25 degree celsius	RT2_leaf
   RT3	Arabidopsis thaliana	25 degree celsius	RT3_leaf

6. Click the Save button.

Show ontology information

Section titled Show ontology information

ARCitect

1. By clicking >> or << in the column headers you can show or hide the ontology information.

   Characteristic [organism]	Unit	TSR (OBI:0100026)	TAN (OBI:0100026)
   Arabidopsis thaliana	-	NCBITaxon	NCBITaxon:3702
   Arabidopsis thaliana	-	NCBITaxon	NCBITaxon:3702
   Arabidopsis thaliana	-	NCBITaxon	NCBITaxon:3702
   Arabidopsis thaliana	-	NCBITaxon	NCBITaxon:3702
   Arabidopsis thaliana	-	NCBITaxon	NCBITaxon:3702
   Arabidopsis thaliana	-	NCBITaxon	NCBITaxon:3702

   

   So if someone needs to look up my species, they will find it in an online ontology database.

   Note

   You can see that Arabidopsis thaliana was added with id and source ontology in the reference (hidden) columns.

   Tip

   Go to OLS (https://www.ebi.ac.uk/ols4).

Re-organize the annotation table

Section titled Re-organize the annotation table

If the order of the building blocks needs to be adjusted, you can delete or move them from your annotation table.

ARCitect

1. Right-click a column and select:
   • Delete Column to remove it including all related ontology reference columns
   • Move Column to move a column to another position