Swate Templates Contribution Guide

This tutorial guides you how to create Swate metadata templates with Swate-alpha.

Before contributing Swate templates you ideally have

• ☑️ Access to Swate-alpha
• ☑️ Some routine with Swate (e.g. from the Swate manual and quickstarts)
  • you know how to create an Annotation Table
  • you know how to add building blocks to your annotation table
  • you know the annotation principles
• ☑️ A GitHub account and some routine with GitHub
• 💡 Feel free to contact us for Data Steward support, if you are not familiar to GitHub or Swate, but would like to contribute a Swate template for your community

1. (Recommended) Create an issue with background information about the template you want to add. This also serves as a place for discussion.
2. Fork the Swate-templates repository.
3. (Recommended) Create a feature branch (e.g. "template-xy") on your fork.
4. Clone your fork-branch
5. Add/update ONE template (see steps below)
6. Commit, push and sync your branch.
7. Open a pull request

   👀 You can reference your issue typing # in the pull request's commenting dialog

Open Swate-alpha. To create a new template click "New File" and select "Template". If you want to edit an existing template, click "Import" and select the respective file.

Once you open a new template, you will see a "Metadata" sheet. Here you will enter a name for the template as well as further information describing the template. You can find explanations of the necessary information in the table below.

Here is an example for filled out template metadata and how it helps in Swate's template search.

To add the building blocks of your actual template, you need to switch from the "Metadata" sheet to the "New Table" sheet on the bottom left. Using the "Add Building Block" button, you can add your desired building blocks with or without a unit.

• Keep the template as concise as possible
• 👀 If you miss a term or ontology, please follow the DPBO contribution guide to let us know
• If you add a template to address a missing method, try to add building blocks that cover experimental procedures (as Parameters) and features of the sample (as Characteristics) that the experimenter would use when working on an experiment of that type
• The normal order of the columns is: Input → (all the Parameters and Characteristics in between in chronological order) → Output -or- Raw Data File -or- Derived Data File. Try to think about in which order the experimenter in the lab will do their work. Try to match this chronological order from left to right. This step is optional and only meant to increase readability.
• If you would like to save any background information on your template, that would help others reconstruct the creation of the template, you can save it in the Swate-templates GitHub repository. For this, please create a folder with the name of your template in the "Background information" folder.
• Avoid using the building block type Factor in templates. Any given characteristic or parameter in one study or assay can become a factor in another study or assay depending on the experimental context or scientific question. E.g. in one study all samples originate from the same species (-> Characteristic) whereas in another study multiple species were assayed (-> Factor).
  

• When creating a template to comply with repository requirements, please follow the following naming pattern: "Repository" - "Assay", e.g. MetaboLights - MS measurement
• The endpoint repository tag should be added ONLY in the "Endpoint repository" category in the metadata sheet
• By default repository templates should contain only mandatory information. In this case, please add "mandatory" as a tag.
• Optional or recommended information can be added with an extension template that contains ONLY the optional/recommended information. In this case, please add "-extension" to the template name.
• If applicable, templates should be split into different assays.
• Templates should be checked for validity of requirements every ~ 6 months.
  

Once the building blocks are established, please fill in one row of the table with example values. This will help the users interpret the building blocks and fill in the template in the intended way.

Save your template by clicking on the disc symbol in the top right corner. This will download an xlsx-file. Please adjust the name of the file to correspond to the name of the template, but use underscores instead of spaces. Save the file in a suitable folder within your local clone of the Swate templates repository.

• Well done! You created a new template.
• You can now submit your template via the git workflow described above.
• Once your pull request is merged, you will receive an Email from "Swobup Commit Report"
  

• Opening and saving a Swate template .xlsx file with a program other than Microsoft Excel (e.g. LibreOffice, python script, R script) often destroys the template (backend). Please, avoid to upload this file into the GitHub repository.

DataPLANT Support