Skip to content

Latest commit

 

History

History
421 lines (266 loc) · 12.5 KB

70-Swate-HandsOn.md

File metadata and controls

421 lines (266 loc) · 12.5 KB
Raw
marp theme paginate license title author
true
marp-theme_dataplant-ceplas-ccby
true
Swate hands-on

Swate hands-on

Goals

  • Get familiar with ISA metadata and Swate
  • Annotate data in your ARC

Check Swate installation

☑️ Make sure Swate is installed:

  1. Open Excel (online or Desktop)
  2. Go to the Insert tab: Click the arrow next to "My Add-ins". There you should be able to select Swate.
  3. Go to the Data tab: you should see the Swate (Core) add-in.

💡 Alternatively, you can use Swate standalone
(:warning: this is however work in progress and likely to change)

Have a simple text editor ready

  • Windows Notepad
  • MacOS TextEdit

Recommended text editor with code highlighting, git support, terminal, etc: Visual Studio Code

Download the demo data

bg right:40% w:250

  1. Open the ARCitect
  2. Login (1) to your DataHUB account
  3. Navigate to Download ARC (4)

Download the demo data

  1. Search for Talinum-CAM-Photosynthesis
  2. Click the download button, select a location and open the ARC.

w:700

💡 This is basically the ARC we created last session.

Where we left off last time

👩‍💻 Initiated an ARC 📂 Structured and ...
🌐 Shared with collaborators


Today we want to

... annotate the experimental data

bg right:40% width:400

Swate hands-on with demo data

Swate Overview

width:1000

Let's annotate the plant samples first

  1. Navigate to the demo ARC.
  2. Open the lab notes studies/talinum_drought/protocols/plant_material.txt in a text editor.
  3. Open the empty studies/talinum_drought/isa.study.xlsx workbook in Excel.

Create an annotation table


<style scoped> .columns { /* grid-template-columns: repeat(2, minmax(0, 1fr)); */ grid-template-columns: 500px 500px; gap: 30px; display: flex; justify-content: center; } </style>

Create a Swate annotation table via the create annotation table button in the yellow pop-up box OR click the Create Annotation Table quick access button.


💡 Each table is by default created with one input (Source Name) and one output (Sample Name) column

💡 Only one annotation table can be added per Excel sheet

Add a building block

  1. Navigate to the Building Blocks tab via the navbar. Here you can add Building Blocks to the table.
  2. Instead of Parameter select Characteristic from the drop-down menu (A)
  3. Search for organism in the search bar (B). This search looks for suitable Terms in our Ontology database.
  4. Select the Term with the id OBI:0100026 and,
  5. Click Add building block.

💡 This adds three columns to your table, one visible and two hidden.

bg right:30% w:400

Insert values to annotate your data

  1. Navigate to the Terms tab in the Navbar
  2. In the annotation table, select any number of cells below Characteristic [organism]
  3. Click into the search field in Swate.

💡 You should see organism showing in a field in front of the search field
💡 The search will now yield results related to organism

  1. In the search field, search for "Talinum fruticosum"
  2. Select the first hit and click Fill selected cells with this term

Add a building block with a unit

  1. In the Building Blocks tab, select Parameter, search for light intensity exposure and select the term with id PECO:0007224.
  2. Check the box for This Parameter has a unit and search for microeinstein per square meter per second in the adjacent search bar.
  3. Select UO:0000160.
  4. Click Add building block.

💡 This adds four columns to your table, one visible and three hidden.

Insert unit-values to annotate your data

In the annotation table, select any cell below Parameter [light intensity exposure] and add "425" as light intensity.

💡 You can see the numbers being complemented with the chosen unit, e.g. 425.00 microeinstein per square meter per second

Showing ontology reference columns

Hold Ctrl and click the Autoformat Table quick access button to adjust column widths and un-hide all hidden columns.

💡 You can see that your organism of choice was added with id and source Ontology in the reference (hidden) columns.

⚠️ This feature is currently not supported on MacOS

Update ontology reference columns

Click the Update Ontology Terms quick access buttons.

💡 This updates all reference columns according to the main column. In this case the reference columns for Parameter [light intensity exposure] are updated with the id and source ontology of the microeinstein per square meter per second unit.

Your ISA table is growing

At this point. Your table should look similar to this:

w:1000

Hiding ontology reference columns

Click the Autoformat Table quick access button without holding Ctrl to hide all reference columns.

Exercise 📝

Try to add suitable building blocks for other pieces of metadata from the plant growth protocol (studies/talinum_drought/protocols/plant_material.txt).

Add a factor building block

  1. In the Building Blocks tab, select Factor, search for watering exposure and select the term with id PECO:0007383.
  2. Click Add building block.
  3. Add the drought treatment ("no water for 12 days", "re-water for 2 days") to the respective samples

💡 There are different options to add the drought treatment.

Link the protocol to the isa table

  1. In the Building Blocks tab, select Protocol Columns -> Protocol REF.
  2. Click Add building block.
  3. Add the name of the protocol file (plant_material.txt) to the Protocol REF column.

💡 This allows you to reference the free-text, human-readable protocol.

Fill out source name and sample name

Transfer the sample ids from the protocol.

  1. Invent names for Source Name (we do not have this information)
  2. Use the sample names (DB_*) as Sample Name

Let's annotate the RNA Seq data

  1. Navigate to the demo ARC.
  2. Open the lab notes assays/rnaseq/protocols/RNA_extraction.txt in a text editor.
  3. Open the empty assays/rnaseq/isa.assay.xlsx) workbook in Excel.

Use a template

  1. Navigate to Templates in the Navbar and click Browse database in the first function block.

💡 Here you can find community created workflow annotation templates

  1. Search for RNA extraction and click select
    • You will see a preview of all building blocks which are part of this template.
  2. Click Add template to add all Building Blocks from the template to your table, which do not exist yet.

bg right:30% w:350px

Adding / Updating unit references

Sometimes you need to add or update the unit of an existing building block.

  1. Select any number of rows of the Parameter [biosource amount] building block to mark it for the next steps.
  2. Open the Building Blocks tab
  3. In the bottom panel "Add/Update unit reference to existing building block", search for the unit "milligram". Select the unit term and click Update unit for cells. :bulb: If you already had values in the main column they will be updated automatically.
  4. Click the Update Ontology Terms quick access button, to update the reference columns.

Remove building blocks

If there are any Building Blocks which do not fit your experiment you can use the Remove Building Block quick access button to remove it including all related (hidden) reference columns.

⚠️ Due to the hidden reference columns, we recommend not to delete table columns via usual Excel functions.

New process, new worksheet

  1. Add a new sheet to the assays/rnaseq/isa.assay.xlsx) workbook.
  2. Add the template "RNASeq Assay"

Exercise 📝

Try to fill the two sheets with the protocol details:

  • assays/rnaseq/protocols/RNA_extraction.txt and
  • assays/rnaseq/protocols/Illumina_libraries.txt

Link samples across studies and assays

  1. Use the Sample Name of studies/talinum_drought/isa.study.xlsx as the Source Name to rna-extraction.
  2. Use the Sample Name of rna-extraction as the Source Name to illumina-libraries.
<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script>
flowchart LR %% Nodes S1(Seeds) S2(Leaves) M1(RNA) P1>plant growth] P2>RNA extraction] P6>Illumina] D2(fastq files) %% Links S1 ---P1--> S2 S2 ---P2--> M1 M1 ---P6--> D2

Link dataset files to samples

  1. In the Building Blocks tab, select Output Columns -> Raw Data File.
  2. Click Add building block.

💡 You see a warning about a changed output column.

  1. Click Continue.
  2. Go to the File Picker tab and click Pick file names.
  3. Select and open the *fastq.gz files from the dataset folder.
  4. Copy / paste them to the Raw Data File.

💡 This allows you to link your samples to the resulting raw data files.

Your ISA table is ready 🎉

Go ahead, adjust the Building Blocks you want to use to describe your experiment as you see fit. Insert values using Swate Term search and add input and output.

Re-use a protocol (process.json)

  1. Open the empty assays/metabolomics/isa.assay.xlsx) workbook in Excel.
  2. Navigate to Templates in the Navbar and scroll down to "Add template(s) from file."
  3. Click Upload protocol
  4. Select the file "swate_agilent_gc.json" from the demo data.
  5. Click Insert json

bg right:25% w:300px

💡 This adds not only an empty template, but a filled out table with keys (headers) and values (cells).

A small detour on "Excel Tables"

Swate uses Excel's "table" feature to annotate workflows. Each table represents one process from input (e.g. plant leaf material) to output (e.g. leaf extract).

Example workflows with three processes each:

  • Plant growth → sampling → extraction
  • Measured data files → statistical analysis → result files

💡 Excel tables allow to group data that belongs together inside one sheet. This is not to be confused with a (work)sheet or workbook.

workbook              (e.g. "isa.assay.xlsx")
 └─── worksheet       (e.g. "plant_growth")
          └─── table  (e.g. "annotationTable")

🚧 Known issues with ARCitect and Swate (Nov 2023)

  1. Annotation within ARCitect is not yet available.
  2. Swate and ARCitect handle isa.study.xlsx / isa.assay.xlsx files differently.

Contributors

Slides presented here include contributions by