Merge pull request #526 from Etschbeijer/Feature_Add_Annotate_Excel_G…

…uide

Feature add annotate excel guide

src/content/authors/patrick-blume.yml

@@ -0,0 +1,4 @@
+name: Patrick Blume
+socials:
+  - icon: simple-icons:github
+    href: https://github.com/Etschbeijer

src/content/docs/guides/annotate-in-excel.mdx

@@ -2,11 +2,58 @@
 title: Annotate in Excel
 authors:
   - kevin-frey
+  - patrick-blume
 sidebar:
+  order: 1
   badge:
-    text: beta
+    text: new
     variant: caution
-draft: true
 ---
 
-Lorem ipsum
+import { Steps } from '@astrojs/starlight/components';
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+## Installation
+
+With the help of an [Excel-Add-In](https://learn.microsoft.com/de-de/office/dev/add-ins/excel/excel-add-ins-overview) you can manage your data, utilizing the [ARC](https://nfdi4plants.github.io/nfdi4plants.knowledgebase/core-concepts/arc/) standard, directly in excel, without the necessity to upload it anywhere. 
+The functionality the excel-add-in provides are similar to [Swate](https://nfdi4plants.github.io/nfdi4plants.knowledgebase/swate/) and the differences will be explained in the different sections of swate.
+The excel-add-in will soon be published in the official [Microsoft Excel-Add-Ins Store](https://appsource.microsoft.com/en-us/marketplace/apps?product=excel).
+Currently, we recommend the installation using the [excel-browser version provided by microsoft](https://excel.cloud.microsoft/?wdOrigin=MARKETING.FREE.GO-TO-EXCEL) because the set up is much easier than with a local excel version.
+
+<Tabs syncKey="swateHost">
+<TabItem label="Browser">
+
+<Steps>
+
+1. In order to annotate your data in Excel, based on the DataPlant standard, you have to download the [Manifest File](https://github.com/nfdi4plants/Swate/tree/main/src/Client/public).
+2. After downloading the manifest file, you have to upload it to Excel, by clicking on the Add-Ins button (a) in the start tab of Excel.
+3. Then you click on the Additional Add-Ins button in the exanded widget
+
+    ![Swate Excel Brwoser Installation Step 1](@images/swate/swate-browser-excel-add-in-basic.png)
+
+4. In the next step you select My Add-Ins (a) and Upload My Add-In.
+
+    ![Swate Excel Brwoser Installation Step 2](@images/swate/swate-browser-excel-add-in-additional-ones.png)
+
+5. Then you select choose the folder where you have downloaded the [Manifest File](https://github.com/nfdi4plants/Swate/tree/main/src/Client/public) to and select it, in order to upload it.
+6. When the installation was successful, the icon of [Swate](https://nfdi4plants.github.io/nfdi4plants.knowledgebase/swate/), the Excel-Add-In for annotating data, should be available in the data tab.
+7. When you click on the icon the sidebar of swate should appear. Its size is adaptable and when it is big enough, the quick icons of the navbar are visible.
+8. When everything was successful, it should look similar to this:
+
+</Steps>
+
+</TabItem>
+<TabItem label="Excel">
+
+<Steps>
+
+1. Follow the installation guide for [Excel-Add-Ins](https://support.microsoft.com/en-us/office/add-or-remove-add-ins-in-excel-0af570c4-5cf3-4fa9-9b88-403625a0b460).
+2. When the installation was successful, the icon of [Swate](https://nfdi4plants.github.io/nfdi4plants.knowledgebase/swate/), the Excel-Add-In for annotating data, should be available in the data tab.
+3. When you click on the icon the sidebar of swate should appear. Its size is adaptable and when it is big enough, the quick icons of the navbar are visible.
+4. When everything was successful, it should look similar to this:
+
+</Steps>
+
+</TabItem>
+</Tabs>
+![Swate Sidebar Overview](@images/swate/swate-excel-overview.png)

src/content/docs/guides/vs-code-extension.mdx

@@ -19,8 +19,6 @@ Some features you know from [ARCitect](/nfdi4plants.knowledgebase/arcitect) are
 
 <Tabs>
 
-## Local installation
-
 <Steps>
 
 1. From the [GitHub release page](https://github.com/nfdi4plants/arc-vs-code/releases/latest) download the asset `arc-vs-code-x.x.x.vsix`
@@ -66,7 +64,7 @@ You only have to do this once for your account.
 
 ## Using the extension
 
-Once you open an ARC folder in VSCode, the functions become are available in the context menus of relevant files and folders in your ARC (e.g. studies and assays) via right-click: 
+Once you open an ARC folder in VSCode, the functions are available in the context menus of relevant files and folders in your ARC (e.g. studies and assays) via right-click: 
 
 - In the VSCode file tree, right-click on a study or assay name or the isa.investigation.xlsx to delete or edit the respective ISA metadata. 
 - Right-click on the folders `studies` or `assays` to add a new study or assay.

src/content/docs/swate/add-building-blocks.mdx

@@ -4,11 +4,24 @@ lastUpdated: 2024-04-26
 authors: 
   - kevin-frey
   - stella-eggels
+  - patrick-blume
 ---
 
+import { Steps } from '@astrojs/starlight/components';
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+<Tabs syncKey="swateHost">
+<TabItem label="Browser">
+
 ![](@images/swate/swate-alpha-add-building-block.png)
 
-import { Steps } from '@astrojs/starlight/components';
+</TabItem>
+<TabItem label="Excel">
+
+![](@images/swate/swate-excel-add-building-block.png)
+
+</TabItem>
+</Tabs>
 
 <Steps>
 
@@ -40,9 +53,37 @@ import { Steps } from '@astrojs/starlight/components';
       </p>
     </details>
 
+    :::note
     If you cannot find a fitting term, you can write an issue to request an ontology term [here](https://github.com/nfdi4plants/nfdi4plants_ontology/issues/new/choose) **OR** use free text input.
+    :::
+</Steps>
+
+<Tabs syncKey="swateHost">
+<TabItem label="Browser">
+
+<Steps>
 
-4. Click "Add column" to insert the building block into an existing [Annotation Table](/nfdi4plants.knowledgebase/swate/annotation-table). The new building block will be added to the right side of the table. To change the position you can use the [context menu](/nfdi4plants.knowledgebase/swate/context-menu).
+4. Click "Add column" to insert the building block into an existing [Annotation Table](/nfdi4plants.knowledgebase/swate/annotation-table). 
+The new building block will be added to the right side of the table. 
+To change the position you can use the [context menu](/nfdi4plants.knowledgebase/swate/context-menu).
+
+</Steps>
+
+</TabItem>
+<TabItem label="Excel">
+
+<Steps>
+
+4. Click "Add column" to insert the building block into an existing [Annotation Table](/nfdi4plants.knowledgebase/swate/annotation-table). 
+The new building block will be added at your selected column of the table. 
+When you have selected a column outside the table or the worksheet contains no annotation table, "Add column" fails.
+
+</Steps>
+
+</TabItem>
+</Tabs>
+
+<Steps>
 
 5. Depending on the [building block type](/nfdi4plants.knowledgebase/swate/building-blocks), multiple columns might be created.
 

src/content/docs/swate/annotation-table.mdx

@@ -1,27 +1,44 @@
 ---
 title: Annotation Table
-lastUpdated: 2024-04-25
+lastUpdated: 2024-11-14
 authors: 
   - kevin-frey
   - stella-eggels
+  - patrick-blume
 ---
 
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
 :::tip
 Consider reading about [Swate](/nfdi4plants.knowledgebase/swate)
 :::
 
-## Open or create an assay or study file
+<Tabs syncKey="swateHost">
+<TabItem label="Browser">
+
+## Add an annotation table
 
-To create an annotation table file with the [Swate standalone](https://swate-alpha.nfdi4plants.org/) in your browser, click "New File" and select which kind of file (investigation, study, assay) you want to create. If you already created a `isa.study.xlsx` or `isa.assay.xlsx` file, you can select "Import File" to modify and add to it.
+In the "New Table" sheet, you can create your annotation table by adding [building blocks](/nfdi4plants.knowledgebase/swate/building-blocks). 
+Your annotation table should consist of an "Input", multiple descriptive building blocks ("Characteristics", "Parameters", "Components") and an "Output".
 
-![Image showing add new file option in Swate](@images/swate/swate-alpha-new-file.png)
+To create an annotation table within ARCitect, add a new table to your assay or study by clicking the plus (+) symbol next to your metadata sheet. 
+Here, you can build your annotation table by adding [building blocks](/nfdi4plants.knowledgebase/swate/building-blocks) the same way as in the Swate standalone.
 
-In the "Metadata" sheet, you can fill in general metadata about your investigation, study or assay.
+![Image showing Swate integration in ARCitect with focus on "add new annotation table"-button.](@images/swate/swate-alpha-arcitect-newtable.png)
+
+</TabItem>
+<TabItem label="Excel">
 
 ## Add an annotation table
 
-In the "New Table" sheet, you can create your annotation table by adding [building blocks](/nfdi4plants.knowledgebase/swate/building-blocks). Your annotation table should consist of an "Input", multiple descriptive building blocks ("Characteristics", "Parameters", "Components") and an "Output".
+When you have an empty excel sheet or one hat already contains an annotation table, you can click on the "Create Annotation Table" icon of the navbar of the sidebar.
+When the excel sheet contains no annotation table, a new annotation table will be created in the active excel sheet.
+When an annotation table already exists in the active excel sheet, a new excel sheet will be created, become active and a new annotation table will be created in that sheet.
 
-To create an annotation table within ARCitect, add a new table to your assay or study by clicking the plus (+) symbol next to your metadata sheet. Here, you can build your annotation table by adding [building blocks](/nfdi4plants.knowledgebase/swate/building-blocks) the same way as in the Swate standalone.
+The new annotation table will be created in the cell that was selected, when you the "Create Annotation Table" icon was clicked.
+The newly created annotation table has a size of 1 Input [Source Name] column and row.
 
-![Image showing Swate integration in ARCitect with focus on "add new annotation table"-button.](@images/swate/swate-alpha-arcitect-newtable.png)
+![Image showing add new file option in Swate](@images/swate/swate-excel-add-annotation-table.png)
+
+</TabItem>
+</Tabs>

src/content/docs/swate/building-blocks.mdx

@@ -16,7 +16,7 @@ Check out the ISA-XLSX specification to find out more about the individual build
 <a href={"https://github.com/nfdi4plants/ARC-specification/blob/main/ISA-XLSX.md"}> ISA-XLSX specification <Icon name="external" class="!inline"/></a>
 :::
 
-import SwateOverview from '@images/swate/overview.png'
+import SwateOverview from '@images/swate/swate-alpha-overview.png'
 
 ## Usage in Swate
 

src/content/docs/swate/file-picker.mdx

@@ -4,8 +4,11 @@ lastUpdated: 2024-04-26
 authors: 
   - kevin-frey
   - stella-eggels
+  - patrick-blume
 ---
 
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
 You might want to add file names to a column, "Input" or "Output". Since typing them in name by name could get quite tedious, you can copy the file names with the file picker instead. For this, click on the 'File Picker' tab in the sidebar and select "Pick file names". The file names will appear in the sidebar and you can modify their order. Once your files are listed in the correct order, click on "Insert File Names" to directly paste their names into the selected column. 
 
 {/* reduce size of all images on this page */}
@@ -18,4 +21,20 @@ You might want to add file names to a column, "Input" or "Output". Since typing
 `}
 </style>
 
-![](@images/swate/swate-alpha-filepicker.png)
+
+<Tabs syncKey="swateHost">
+<TabItem label="Browser">
+
+
+![](@images/swate/swate-alpha-filepicker.png)
+
+
+</TabItem>
+<TabItem label="Excel">
+
+
+![](@images/swate/swate-excel-filepicker.png)
+
+
+</TabItem>
+</Tabs>

src/content/docs/swate/index.mdx

@@ -4,10 +4,13 @@ lastUpdated: 2024-09-04
 authors:
   - martin-kuhl
   - stella-eggels
+  - patrick-blume
 sidebar:
   order: 1
 ---
 
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
 Welcome to the Swate Manual.
 Here you can find documentation about Swate features and best practices.
 
@@ -16,7 +19,7 @@ Please explore the sections on the left to find guides on:
 - adding building blocks to your annotation table
 - filling cells with ontology terms
 - using and creating templates
-
+- handling top level metadata in excel
 
 Swate (Swate workflow annotation tool for Excel) is one of three central DataPLANT tools designed for convenient interaction with your [ARC](/nfdi4plants.knowledgebase/core-concepts/arc) (the other ones being [ARCitect](/nfdi4plants.knowledgebase/arcitect) and [ARC Commander](/nfdi4plants.knowledgebase/arc-commander)). Swate simplifies adding standardized metadata for your experimental workflows by leveraging a simple use of [ontologies](/nfdi4plants.knowledgebase/fundamentals/ontologies). Swate is integrated into ARCitect and will automatically be used when adding metadata to your studies and assays from within ARCitect, but it can also be used as a [standalone tool](https://swate-alpha.nfdi4plants.org/) in your browser.
 
@@ -35,7 +38,22 @@ Users can add and delete building blocks to their ISA compliant annotation table
 
 Combination of ISA terms (Characteristic, Parameter, Factor, Component) and biological or technological ontology terms (e.g. temperature, strain, instrument model) gives the flexibility to display an ontology term, e.g. temperature, as a regular process parameter or as the factor your study is based on within your annotation table (Parameter [temperature] or Factor [temperature]). For more information on these building blocks, please check our [annotation principles](https://nfdi4plants.github.io/AnnotationPrinciples/). 
 
-![Building Blocks](@images/swate/building-block-categories.png)
+<Tabs syncKey="swateHost">
+<TabItem label="Browser">
+
+
+![Building Blocks](@images/swate/swate-alpha-building-block-categories.png)
+
+
+</TabItem>
+<TabItem label="Excel">
+
+
+![Building Blocks](@images/swate/swate-excel-building-block-categories.png)
+
+
+</TabItem>
+</Tabs>
 
 Ontology terms within the Swate database can not only be used to standardize the headers of your annotation table, but also for standardization of the respective values. When filling in metadata via the "ontology term search", which can be activated by clicking the magnifying glass symbol, Swate will suggest matching metadata terms for the respective building block. Of course, users are not forced to use this feature in case they opt for more flexibility.
 
@@ -44,7 +62,23 @@ Ontology terms within the Swate database can not only be used to standardize the
 Metadata annotation as part of the data submission routine to public repositories is often bothersome due to a high variability between repository requirements. This can become particularly inconvenient when the same metadata is submitted repeatedly, e.g. to unrelated public repositories. To assist researchers in this process, DataPLANT provides a growing collection of templates as a starting point for their annotation tables. The template design process is initiated “backwards”, starting from the requirements of public repositories and thereby, compliance with metadata standards. Our Data stewards supervise the metadata harmonization between template and target repository and simultaneously contribute to the development of the DataPLANT biology ontology [(DPBO)](https://github.com/nfdi4plants/nfdi4plants_ontology).  
 From a technical perspective, these templates are ISA Protocols containing various Characteristics, Parameters, and the Study specific Factor. DataPLANT provides checklists and requirements of public repositories as templates that are considered useful for various technologies and common standards, e.g. MIAPPE. For finding metadata checklists and Swate templates that are suitable for your data, you might want to use the [Metadata recommendation quiz](/nfdi4plants.knowledgebase/resources/metadata-quiz). Swate templates can directly be integrated to the isa.study.xlsx and isa.assay.xlsx files using Swate. Once loaded into the table, they still can be modified to special needs in the sense of adding or deleting annotation building blocks. The modularity of the system also gives labs and institutions the possibility to create their own lab specific templates for experiments that are frequently run in the lab, e.g. a metabolomics experiment of a measurement facility. High flexibility is fostered by offering a manual or Swate-supported template customization, distribution, and use.
 
-![Templates](@images/swate/swate-add-template.png)
+
+<Tabs syncKey="swateHost">
+<TabItem label="Browser">
+
+
+![Templates](@images/swate/swate-alpha-add-template.png)
+
+
+</TabItem>
+<TabItem label="Excel">
+
+
+![Templates](@images/swate/swate-excel-add-template.png)
+
+
+</TabItem>
+</Tabs>
 
 
 ## There is no wrong or right

src/content/docs/swate/json.mdx

@@ -3,16 +3,32 @@ title: JSON import and export
 lastUpdated: 2024-04-30
 authors: 
   - kevin-frey
+  - patrick-blume
 ---
 
-import SwateOverview from '@images/swate/overview.png'
+import SwateOverview from '@images/swate/swate-alpha-overview.png'
+import { Tabs, TabItem } from '@astrojs/starlight/components';
 
 Utilizing [ARCtrl](https://github.com/nfdi4plants/ARCtrl) all json formats Swate supports multiple different import and export formats for json.
 
 ## Export
 
 The "File Export" function can be found in the <a href={SwateOverview.src} target="_blank">Sidebar</a>.
 
+<Tabs syncKey="swateHost">
+<TabItem label="Browser">
+
+You can export your data sheet simply by clicking on "Download".
+
+</TabItem>
+<TabItem label="Excel">
+
+In contrast to the web version of swate, you cannot simply download your annotation tables.
+In order to do so, you have to create a [top level metadata sheet](http://localhost:4321/nfdi4plants.knowledgebase/swate/annotation-table/).
+
+</TabItem>
+</Tabs>
+
 ![](@images/swate/json-export.png)
 
 ## Import