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

ARCitect

1. Click on the plus icon add next to science 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.

   • AthalianaColdStressSugar
   • Directorystudies

     • AthalianaColdStress
     • 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”

   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.

ARCitect-GX

1. In the left sidebar open the File explorer

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

3. Enter an identifier for the New Study.

   

   AthalianaColdStress

4. Click Create Study.

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

   • AthalianaColdStressSugar
   • Directorystudies

     • AthalianaColdStress
     • Directoryprotocols

       • …
     • Directoryresources

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

6. Click on the study’s name (AthalianaColdStress) in the file tree to open the folder

7. Click on the isa.study.xlsx workbook to edit the study metadata in the right panel.

   

8. Here you can add metadata about your study.

   

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

   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

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.

   • AthalianaColdStressSugar
   • Directorystudies

     • AthalianaColdStress
     • Directoryprotocols

       • growth_protocol.md
   • …

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

ARCitect-GX

1. Right-click on the protocols folder and select Open Folder Location from the context menu.

   

2. Move the file growth_protocol.md from the demo data into the protocols folder.

3. The file is added to your ARC and can be edited in via ARCitect-GX

   • AthalianaColdStressSugar
   • Directorystudies

     • AthalianaColdStress
     • Directoryprotocols

       • growth_protocol.md
   • …

   Note

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

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

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.

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

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

3. Select “Create basic table”.

4. This adds a new table sheet with three columns Input[Sample Name], Protocol Uri and Output[Sample Name] and three empty rows

5. Right-click on sheet’s tab to rename it to “plant-growth”.

6. At the bottom of the table, type 3 in the text field and click + to add another three rows to the 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”.

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

   Input[Sample Name]	ProtocolUri	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”.

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.

1. On top of the annotation table, click .

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

3. On top click to open the 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 ProtocolUri column and click Insert file names.

   Input[Sample Name]	ProtocolUri	Output[Sample Name]
   Cold1	protocols/growth_protocol.md	Cold1_leaf
   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[Sample Name]	ProtocolUri	Output[Sample Name]
   Cold1	protocols/growth_protocol.md	Cold1_leaf
   Cold2	protocols/growth_protocol.md	Cold2_leaf
   Cold3	protocols/growth_protocol.md	Cold3_leaf
   RT1	protocols/growth_protocol.md	RT1_leaf
   RT2	protocols/growth_protocol.md	RT2_leaf
   RT3	protocols/growth_protocol.md	RT3_leaf

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 contains 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

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

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 [ ]

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

Parameters [ ]

• Exposure duration 4d
• Light intensity 200 µEinstein
• Temperature 6°C / 25°C

Add characteristics

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

   

   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

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.

1. In the Building Blocks widget , select Parameter, search for exposure duration.

2. Click 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 [exposure duration] and add “4”.

   Note

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

5. Repeat the steps for the parameter Light intensity.

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.

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

Show ontology information

You can press F2 after selecting a table cell or open the context menu with right click and open Details to view all ontology information stored for this cell. By default, only the term name is shown in the table with an green checkmark indicating that a full ontology term exists.

Term

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.

Tip

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

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.

Right-click a column and select

1. Delete Column to remove it
2. Move Column to move a column to another position