Merge pull request #449 from akirbis/main

Update for ARCmanager knowledgebase articles

src/docs/ARCmanager-manual/02_login.md

@@ -2,13 +2,16 @@
 layout: docs
 title: Connect to your DataHUB
 author:
-- name: Ursula Eberhardt
-  github: https://github.com/UrsulaE/
-  orcid: https://orcid.org/0000-0003-1221-7074
+  - name: Ursula Eberhardt
+    github: https://github.com/UrsulaE/
+    orcid: https://orcid.org/0000-0003-1221-7074
+  - name: Lucas Beuter
+    github: https://github.com/Lu98Be
+    orcid: https://orcid.org/0009-0008-8744-825X
 add toc: false
 add sidebar: _sidebars/mainSidebar.md
 status: published
-date: 2024-06-13
+date: 2024-08-28
 ---
 
 To be able to use the [ARCmanager](https://nfdi4plants.de/arcmanager/app/index.html), you need to have registered to one of the DataHUBs. Information on the different DataHUBs can be found [here](https://www.nfdi4plants.de/content/datahub.html).
@@ -27,7 +30,7 @@ Clicking on the the `DataHUB` button (Fig. 1) brings you to the drop down menu o
 
 ---
 
-At present, there are three different DataHUBs available for managing research data. The DataHUBs "reference" and "federated" are available to all researchers, whereas the TRR356 PlantMicrobe DataHUB is only available for members of this project.  Members of the TRR356 project are advised to use this DataHUB. 
+At present, there are three different DataHUBs available for managing research data. The DataHUBs "reference" and "federated" are available to all researchers, whereas the TRR356 PlantMicrobe DataHUB is only available for members of this project. Members of the TRR356 project are advised to use this DataHUB.
 
 <!--Collaborators of TRR356 research are welcome to the TRR356 PlantMicrobe DataHUB and will be admitted upon request to (**whose email?**).-->
 
@@ -51,8 +54,8 @@ If you are using the ARCmanager for the first time, you will see a window (Fig.
 
 ---
 
-For the login process, you are presented with a selection of authentication options. Select one that you have used before in the registration process and enter your credentials (Fig. 5). 
-    
+For the login process, you are presented with a selection of authentication options. Select one that you have used before in the registration process and enter your credentials (Fig. 5).
+
 Different authentication options can be used for the same DataHUB user, if the logins of the different providers have been merged. This process is mediated by Life Science RI. If you are not presented with the option to merge your identities during the registration of an additional identity via another provider, you will have to get in touch with support@aai.lifescience-ri.eu for merging the identities. "Unmerged" identities will be treated as two different users in the DataHUB. Having different users complicates working with GitLab projects locally on your computer and is not recommended.
 
 ---
@@ -73,14 +76,16 @@ After successful login, you see the former lilac `Login` button change to a pink
 
 ---
 
-### Accessing the ISA metadata search
+### Session Timer
+
+After logging in, a session timer will display the remaining time left for the current user session. Your most recent activities are stored in this session to ensure proper function of the web service.
 
-Without logging in to any DataHUB, the ARC search button (Fig. 1) provides a list of published ARCs that can be searched using the ISA metadata search via the [ARC Metadata Registry](https://arc-metadata-registry.readthedocs.io/en/latest/).
+When the timer reaches 0:00:00, your current session has expired. To initialize a new session, logout and login again. Make sure to save any forms that you are editing during a session before it expires, otherwise input data may get lost.
 
 ---
 
-<img src="../img/ARCmanager_login_5.png" style="border: 1px solid  black;" />
+<img src="../img/ARCmanager_sessiontimer.png" style="border: 1px solid  black;" />
 
-**Fig. 7** Searching for published ARCs.
+**Fig. 8** Session timer
 
 ---

src/docs/ARCmanager-manual/03_view_ARCs.md

@@ -2,13 +2,16 @@
 layout: docs
 title: View ARCs
 author:
-- name: Ursula Eberhardt
-  github: https://github.com/UrsulaE/
-  orcid: https://orcid.org/0000-0003-1221-7074
+  - name: Ursula Eberhardt
+    github: https://github.com/UrsulaE/
+    orcid: https://orcid.org/0000-0003-1221-7074
+  - name: Lucas Beuter
+    github: https://github.com/Lu98Be
+    orcid: https://orcid.org/0009-0008-8744-825X
 add toc: false
 add sidebar: _sidebars/mainSidebar.md
 status: published
-date: 2024-06-13
+date: 2024-08-28
 ---
 
 For the sake of simplicity, we are here using the term "ARC" for (DataHUB) "Project", because the DataHUB does not make any distinction between Projects that have the ARC folder and file structure and those that have not. Both are initially shown in the ARCmanager, but the ARCmanager has not been created for manipulating Projects which are not ARCs.
@@ -29,7 +32,7 @@ With the `LOAD ARC` button (Fig. 1), all ARCs on the DataHUB will be listed for
 
 ---
 
-Use the `Your Arcs` check-box (Fig. 2) to filter the list of ARCs for those in which you are member and your own ARCs. Your own ARCs are again highlighted in yellow. 
+Use the `Your Arcs` check-box (Fig. 2) to filter the list of ARCs for those in which you are member and your own ARCs. Your own ARCs are again highlighted in yellow.
 
 ---
 
@@ -79,7 +82,7 @@ You can hide the ARC contents by clicking inside the `List ARC content` field ab
 
 ---
 
-Navigate through the ARC directories with a left-click. After clicking a directory, its contents will be displayed. You can go back one level in the directory hierarchy by using the `Return` field above the list of files (Fig. 6).
+Navigate through the ARC directories with a left-click. After clicking a directory, its contents will be displayed. You can go back one level in the directory hierarchy by using the `Return` field above the list of files (Fig. 6). Alternatively, you can click on the respective subdirectory in the path displayed above the `Return` field to jump directly to this position.
 
 ---
 
@@ -89,7 +92,9 @@ Navigate through the ARC directories with a left-click. After clicking a directo
 
 ---
 
-When you click on a file instead of a directory, another panel on the right side will open that allows you to edit the selected file (Fig. 7). Plain text files (.md, .txt or similar) can be changed directly in this editor. Do not forget to save your changes and synchronize with the DataHUB by using the `SAVE` button when you are done.
+When you click on a file instead of a directory, another panel on the right side will open that allows you to view the selected file (Fig. 7). You can display images, pdf files, text based files, and more.
+
+Plain text files (.md, .txt or similar) can be modified directly in this editor. Do not forget to save your changes and synchronize with the DataHUB by using the `SAVE` button when you are done.
 
 ---
 
@@ -109,14 +114,57 @@ When selecting an ISA file, the editor panel will open as well, but instead of a
 
 ---
 
-You can hide/view the editor panel by clicking on the double arrow symbol at the top of the panel (Fig. 9).
-
----
+You can hide/view the editor panel by clicking the double arrow symbol at the top of the panel (Fig. 9).
 
 <img src="../img/ARCmanager_view_7b.png" style="border: 1px solid  black;" />
 
 **Fig. 9** The panel on the right side of the browser window can be hidden/displayed with the double arrow symbol.
 
 ---
 
-When you expand the editor window without selecting a file to be edited first, a list of recent changes to the ARC will be shown instead.
+When you expand the editor window without selecting a file to be edited first, a list of recent changes to the ARC will be shown instead (Fig. 10).
+
+You can hide them by unchecking the checkbox, as well as switch to a different branch in the ARC (highlighted in red).
+After switching the branch you need to reload the ARC through the reload button.
+
+---
+
+<img src="../img/ARCmanager_view_9.png" style="border: 1px solid  black;" />
+
+**Fig. 10** The right side contains a list of changes by default, as well as the option to switch branches
+
+---
+
+The `NEW FOLDER` button below the listed ARC content (Fig. 11, #1) can be used to create new folders, e.g. to further organize raw data inside the dataset subdirectories. 
+
+These custom folders can be renamed (Fig. 11, #2) or deleted (Fig. 11, #3). This is in contrast to the directories which are part of the ARC specification (e.g. studies, assays, etc.), which can not be renamed or deleted via the ARCmanager.
+
+---
+
+<img src="../img/ARCmanager_view_12.png" style="border: 1px solid  black;" />
+
+**Fig. 11** UI elements to create (#1), edit (#2), and delete (#3) custom folders in an ARC using the ARCmanager.
+
+---
+
+### ARC quick validation
+
+When you click the `Validate` button, a basic validation process is started that checks your ARC.
+
+---
+
+<img src="../img/ARCmanager_view_10.png" style="border: 1px solid  black;" />
+
+**Fig. 12** Start the validation process by clicking the highlighted button.
+
+---
+
+Different requirements for a publication ready ARC are checked, like complete ARC structure (all necessary folders and files), all necessary fields filled out in the isa.investigation file, all contacts have names, email, and affiliation and more.
+
+Afterwards, a highlighted card structure will show you the results of the validation process. In case your ARC did not pass the validation test, the results will tell you exactly which information or element is missing.
+
+---
+
+<img src="../img/ARCmanager_view_10b.png" style="border: 1px solid  black;" />
+
+**Fig. 13** Validation results displayed in a card view

src/docs/ARCmanager-manual/04_create_ARCs.md

@@ -2,13 +2,16 @@
 layout: docs
 title: Create new ARCs
 author:
-  - name: Hamed Jalali
-    github: https://github.com/hamedjalali1982
-    orcid: https://orcid.org/0000-0002-1190-5652
+ - name: Hamed Jalali
+   github: https://github.com/hamedjalali1982
+   orcid: https://orcid.org/0000-0002-1190-5652
+ - name: Ursula Eberhardt
+   github: https://github.com/UrsulaE
+   orcid: https://orcid.org/0000-0003-1221-7074
 add toc: false
 add sidebar: _sidebars/mainSidebar.md
 status: published
-date: 2024-06-13
+date: 2024-08-27
 ---
 
 To create a new ARC in ARCmanager, follow the steps below:
@@ -29,7 +32,16 @@ To create a new ARC in ARCmanager, follow the steps below:
 - `Description of the ARC`: A short description about the project you are creating  
 - `Name of the ARC`: An identifier for your ARC (without space between the characters)
 
-
+---
+
+:bulb: Note:
+
+By default ARCs are created under your user name, i.e. in your namespace. If you wish to create an ARC in a group (or subgroup) tick the box `Group?` and select the group name from the drop down menu that is shown after ticking the box. 
+
+Be aware that you need at least the [maintainer role](https://docs.gitlab.com/ee/user/permissions.html#roles) in a (sub)group to be able to create new ARCs with all necessary files in the groups namespace. 
+
+---
+
 
 3. After submitting the form, you can see the new ARC when selecting `Your ARCs` in the List ARCs window.
 
@@ -61,4 +73,4 @@ To create a new ARC in ARCmanager, follow the steps below:
 
     <p float="center">
         <img src="../img/ARCmanager_createARCs_gitlab.png" width="600" align="center" style="border: 1px solid  black;"/>
-    </p>
+    </p>

src/docs/ARCmanager-manual/06_adding_metadata.md

@@ -8,7 +8,7 @@ author:
 add toc: false
 add sidebar: _sidebars/mainSidebar.md
 status: published
-date: 2024-06-13
+date: 2024-08-27
 ---
 
 Two different types of metadata are stored in ISA files: administrative and experimental metadata. Administrative metadata covers IDs, descriptions, contact details, connected publications and more, while experimental metadata is describing experimental procedures and similar processes. ISA files are normally stored in an Excel format (.xlsx) and need to adhere to the [ISA-XLSX specification](https://github.com/nfdi4plants/ARC-specification/blob/main/ISA-XLSX.md).
@@ -18,13 +18,13 @@ A typical ISA file has the administrative metadata recorded in the first sheet o
 #### Contents:
 
 - [Administrative metadata (top-level metadata sheets)](#administrative-metadata-top-level-metadata-sheets)
-   * [Alternative view](#alternative-view) 
+  - [Alternative view](#alternative-view)
 - [Experimental metadata (annotation table sheets)](#experimental-metadata-annotation-table-sheets)
-   * [Add new annotation table sheets](#add-new-annotation-table-sheets)
-   * [Import annotation table templates](#import-annotation-table-templates)
-   * [Edit annotation table sheets](#edit-annotation-table-sheets)
-   * [Ontology term search](#ontology-term-search)
-   * [Adding new building blocks to annotation tables](#adding-new-building-blocks-to-annotation-tables)
+  - [Add new annotation table sheets](#add-new-annotation-table-sheets)
+  - [Import annotation table templates](#import-annotation-table-templates)
+  - [Edit annotation table sheets](#edit-annotation-table-sheets)
+  - [Ontology term search](#ontology-term-search)
+  - [Adding new building blocks to annotation tables](#adding-new-building-blocks-to-annotation-tables)
 
 ### Administrative Metadata (top-level metadata sheets)
 
@@ -58,7 +58,7 @@ In assay metadata files (_isa.assay.xlsx_), it contains information about measur
 
 The **publication** part contains information about DOIs, publication titles, authors, etc. of publications that are associated with the experimental data stored inside the study/investigation.
 
-_isa.assay.xlsx_ files do not contain publication data, which is instead recorded in the connected study. 
+_isa.assay.xlsx_ files do not contain publication data, which is instead recorded in the connected study.
 
 The **contact details** part contains data about researchers associated with the investigation/study/assay. It contains information like first and last name, email, work address, and affiliation. Every ISA file has a contact section.
 
@@ -68,7 +68,7 @@ When you are done with your changes, just click the `SAVE` button in the bottom
 
 <div style="text-align: right">
 
-[Back to table of contents](#contents) 
+[Back to table of contents](#contents)
 
 </div>
 
@@ -104,7 +104,7 @@ Every time you click `SAVE`, the data is written into the excel file and changes
 
 <div style="text-align: right">
 
-[Back to table of contents](#contents) 
+[Back to table of contents](#contents)
 
 </div>
 
@@ -127,7 +127,7 @@ If you already have some annotation sheets in your study/assay you can click `ED
 
 <div style="text-align: right">
 
-[Back to table of contents](#contents) 
+[Back to table of contents](#contents)
 
 </div>
 
@@ -149,16 +149,15 @@ Every Template is listed with its title, the organisation where its originating
 
 If you found your desired template, click on the `IMPORT` button after expand it.
 
-
 <div style="text-align: right">
 
-[Back to table of contents](#contents) 
+[Back to table of contents](#contents)
 
 </div>
 
 #### Edit annotation table sheets
 
-After importing a template, you will see a table similar to the picture below. In this case it's the template "RNA extraction (DataPLANT) 1.2.0", extended to eight rows.
+After importing a template, you will see a table similar to the picture below. In this case it's the template "RNA extraction (DataPLANT) 1.2.1", extended to eight rows.
 
 ---
 
@@ -172,7 +171,8 @@ The following will explain the different interfaces:
 
 1. **Search term:** A click on the magnifying glass symbols opens a search bar above the sheet name bar (4). The search bar allows you to search for specific ontology terms or to get suggestions for terms that fit the parameter.
 
-2. **Add building block:** Clicking this button will open up additional input fields above that allow adding new columns to the metadata table.
+2. **Add building block or custom column:** <br>Clicking `Building Block` will open up additional input fields above that allow adding new columns to the metadata table. You can search for terms and add a new parameter or more. <br>
+Clicking `Custom Column` will open up a different input field above with which you can add a fully customizable columns (with term columns or unit column if desired).
 
 3. **Delete row/column:** Clicking the red "X" will delete the corresponding row or building block. The deletion of elements has to be confirmed in a pop-up menu before the action takes effect.
 
@@ -184,9 +184,13 @@ The following will explain the different interfaces:
 
 7. **Extend the table:** This button adds a new row to table.
 
+8. **Move a column:** You can shift a column to the left or right by clicking the respective arrow.
+
+9. **Template Name:** The name of the template currently in use is displayed next to the sheet name field.
+
 <div style="text-align: right">
 
-[Back to table of contents](#contents) 
+[Back to table of contents](#contents)
 
 </div>
 
@@ -230,7 +234,7 @@ Every cell of the annotation table sheets can also be filled out manually, inste
 
 <div style="text-align: right">
 
-[Back to table of contents](#contents) 
+[Back to table of contents](#contents)
 
 </div>
 
@@ -248,11 +252,11 @@ By default, input columns have the type "Source Name" and output columns have th
 
 ---
 
-To add additional attribute columns to the annotation sheet, click the `+BUILDING BLOCK` button. A new input area (Fig. 11) will open above the annotation table that assists you in designing the attribute column according to the ISA-XLSX specifications. 
+To add additional attribute columns to the annotation sheet, click the `+BUILDING BLOCK` button. A new input area (Fig. 11) will open above the annotation table that assists you in designing the attribute column according to the ISA-XLSX specifications.
 
 First, select a type for the new column from the drop-down menu (Fig. 11, 1). Available column types are [Characteristic](https://github.com/nfdi4plants/ARC-specification/blob/main/ISA-XLSX.md#characteristics), [Factor](https://github.com/nfdi4plants/ARC-specification/blob/main/ISA-XLSX.md#factors), [Component](https://github.com/nfdi4plants/ARC-specification/blob/main/ISA-XLSX.md#components), [Parameter](https://github.com/nfdi4plants/ARC-specification/blob/main/ISA-XLSX.md#parameters), [Comment](https://github.com/nfdi4plants/ARC-specification/blob/main/ISA-XLSX.md#comments), and [Protocol](https://github.com/nfdi4plants/ARC-specification/blob/main/ISA-XLSX.md#protocol-columns).
 
-Below the column type drop-down menu is a search bar that can be used to search for ontology terms that specify the contents of the new building block (Fig. 11, 2). 
+Below the column type drop-down menu is a search bar that can be used to search for ontology terms that specify the contents of the new building block (Fig. 11, 2).
 
 If the new building block will contain numeric values that have a unit, check the "Unit?" checkbox above (Fig. 11, 3). This will add a second search bar where you can search the ontology database for unit terms, like "liter" for the parameter "volume".
 
@@ -262,6 +266,6 @@ When you are done with editing the annotation table, name your sheet and click t
 
 <div style="text-align: right">
 
-[Back to table of contents](#contents) 
+[Back to table of contents](#contents)
 
-</div>
+</div>