Swate Templates - Contribution Guide

💡 This walk-through tutorial is meant for data stewards and data managers

Before contributing Swate templates you ideally have

• Access to an up-to-date installation of Swate Core and Swate Experts
• 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 workflows

💡 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. Fork the Swate-templates repository.
2. (Recommended) Create an issue with background information about the template you want to add. This also serves as a place for discussion.
3. (Recommended) Create a feature branch 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 a new Excel workbook <template>.xlsx

• Create an Annotation Table

• Save the Excel file in a suitable folder within your local clone of the Swate templates repository

  • 💡 check the subfolder README.md`s
  • 🚧 naming convention for files and directories is work in progress

• Add building blocks to your template's Annotation Table

• keep the template as concise as possible
• finding suitable building blocks is not always straight-forward
• 👀 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 do when working on an experiment of that type
• if you add a template with a specific endpoint repository (ER) in mind, you may want to add building blocks that match the required fields of this ER

• Open the "Template Metadata" tab in Swate Experts
• Click "Create Metadata"
• A new worksheet will open called "SwateMetadataSheet"

⚠️ Make sure to never change any of the fields in the first column. These "key" fields must exist to create a functional template. Always only change the "value" fields (second and following columns).

Key	Definition	Tip 💡
Id		Do not change this field. It maps your template to a database entry ⚠️
Name	This is the first info Swate users see about your template	Try using a short, descriptive and human readable name. (Think YouTube video title)
Version	The version of the template following the SemVer convention.	For a new template use 1.0.0. Raise the version number when updating an existing template
Description	Here you can describe your template	Users interested in your template can read this in Swate, but not search by it
Organisation	The name of an organisation or community you create this template for. This facilitates searching for relevant templates in a specific organisation or community.	Templates with the organisation "DataPLANT" are listed as curated in the Swate template database. All other templates are listed as community.
Table	This value must match the name of the annotation table you want to use as a template	To find the name click on any field in your annotation table, then open the Table Design (on macOS: Table) tab. Copy the name to the "Table" value field
ER list	You can add any number of endpoint repositories to which your template complies here	You may want to add them as ontology terms with unique identifier and source
TAGS list	You can add any number of tags here. These tags are the basis to search for your template	You may want to add them as ontology terms with unique identifier and source
AUTHORS list	Add your name/alias here with as much information as you like.

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

• 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"

• 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. The normal order of the columns is: Source Name → (all the Parameters and Characteristics in between in chronological order) → Sample Name -or- Raw Data File -or- Derived Data File. This step is optional and only meant to increase readability.
• Below the header you can add exemplary terms as in this example:
  
  These examples help as additional information for other Data Stewards and are not transferred into the Swate template database.
• Use ontology terms for ER list and TAGS list.
• Add protocol type and any minimal information standards your template complies with to the TAGS list.

• 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, even if the annotation table itself looks intact and can be worked on with the Swate plugin

DataPLANT Support