Restructure documentation sidebar

_data/sidebars/userguide.yml

@@ -1,85 +1,127 @@
 title: User Guide
 title_url: /help/user-guide/
 subitems:
-  - title: Definitions
-    url: /help/user-guide/definitions
+  - title: Introduction
+    subitems:
+    - title: Definitions
+      url: /help/user-guide/definitions
+    - title: Browsing content
+      url: /help/user-guide/browsing 
   - title: Profile
     description: Registering and logging into SEEK, managing your account and identities, editing your profile.
     subitems:
-    - title: Registering in SEEK
-      url: /help/user-guide/registering
+    - title: Registration and Login
       subitems:
+      - title: Registering in SEEK
+        url: /help/user-guide/registering
       - title: Logging into SEEK via LS Login
         url: /help/user-guide/aai
-    - title: Managing your account
-      url: /help/user-guide/managing-account
-      subitems:
       - title: Managing your identities/alternative login methods
         url: /help/user-guide/managing-identities
-    - title: Editing your profile
+    - title: My profile
+      subitems:
+      - title: Managing your account
+        url: /help/user-guide/managing-account
+    - title: Edit profile
       url: /help/user-guide/editing-profile
 #    - title: "[Favourites: drag and drop your favourite searchers]"
 #      url: ""
-  - 
-    #hr: true
-    title: Yellow Pages
-    description: Directory of common project tasks, specialist user roles, capabilities.
-    subitems: 
-    - title: "Directory"
+    - title: User roles and permissions
       subitems:
-      - title: Browsing content
-        url: /help/user-guide/browsing  
-      - title: Creating and managing your own Programmes
-        url: /help/user-guide/programme-creation-and-management
-      - title: Creating a Project
-        url: /help/user-guide/create-a-project
-      - title: Joining a Project
-        url: /help/user-guide/join-a-project
-      - title: Project Dashboard
-        url: /help/user-guide/project-dashboard
-      - title: Viewing Project in Experiment View
-        url: /help/user-guide/viewing-project-in-single-page
-    - title: Specialist user roles
-      url: /help/user-guide/roles
-    - title: Capabilities
-      subitems:
-      - title: Administer project members
-        url: /help/user-guide/administer-project-members
+      - title: Specialist user roles
+        url: /help/user-guide/roles
       - title: Adding admin items
         url: /help/user-guide/adding-admin-items
+      - title: Bulk changing of sharing permissions
+        url: /help/user-guide/bulk-change-sharing-permission
+      - title: Making an Investigation, Study or Assay citable
+        url: /help/user-guide/investigation-snapshots
+  -
+    #hr: true
+    title: Yellow Pages/Directory
+    description: Directory of common project tasks.
+    subitems: 
+      - title: "Programme"
+        subitems:
+        - title: Creating and managing your own Programmes
+          url: /help/user-guide/programme-creation-and-management
+      - title: "Projects"
+        subitems:
+        - title: Creating a Project
+          url: /help/user-guide/create-a-project
+        - title: Administer project members
+          url: /help/user-guide/administer-project-members
+        - title: Joining a Project
+          url: /help/user-guide/join-a-project
+        - title: Project Dashboard
+          url: /help/user-guide/project-dashboard
+        - title: Viewing Project in Experiment View
+          url: /help/user-guide/viewing-project-in-single-page
+#     - title: "[Institutions]"
+#       url: ""
+#     - title: "[People]"
+#       url: ""
   -
     #hr: true
     title: Experiments
-    description: Generating the ISA structure, designing an ISA-JSON compliant experiement, making items citable.
+    description: Generating the ISA structure, designing an ISA-JSON compliant experiment, making items citable.
     subitems: 
-    - title: Generating the ISA structure
-      url: /help/user-guide/generating-the-isa-structure
-    - title: ISA Overview Graph
-      url: /help/user-guide/isa-overview
-    - hr: true
-      title: Designing an ISA-JSON compliant experiment
-      url: /help/user-guide/designing-experiments-isajson-compliant
-    - title: ISA-JSON complient experiment
-      url: /help/user-guide/isa-json-compliant-experiment
+    - title: Introduction to the ISA structure
       subitems:
-        - title: Experiment Sample Templates
-          url: /help/user-guide/isajson-templates
-    - title: Export experiments as ISA-JSON
-      url: /help/user-guide/exporting-experiments-as-isajson
+      - title: Visualising ISA structure in SEEK
+        url: /help/user-guide/isa-overview
+      - title: Generating the ISA structure
+        url: /help/user-guide/generating-the-isa-structure
+    - title: ISA-JSON compliant experiments
+      url: /help/user-guide/isa-json-compliant-experiment
     - hr: true
-      title: Making an Investigation, Study or Assay citable
-      url: /help/user-guide/investigation-snapshots
+    - title: Investigations
+      subitems: 
+      - title: Creating an ISA-JSON compliant investigation
+        url: /help/user-guide/investigations
+      - title: Export experiments as ISA-JSON
+        url: /help/user-guide/exporting-experiments-as-isajson
+    - title: Studies
+      subitems: 
+      - title: Creating an ISA-JSON compliant study
+        url: /help/user-guide/studies
+      - title: Export experiments as ISA-JSON
+        url: /help/user-guide/exporting-experiments-as-isajson
+    - title: Assays
+      subitems: 
+      - title: Creating an ISA-JSON compliant assay
+        url: /help/user-guide/assays
+      - title: Export experiments as ISA-JSON
+        url: /help/user-guide/exporting-experiments-as-isajson
+    - title: Experiment Sample Templates
+      subitems: 
+      - title: Creating Experiment Sample Templates
+        url: /help/user-guide/isajson-templates
+      - title: Browse samples by Experiment Sample Template
+        url: /help/user-guide/browsing#browse-samples-by-experiment-sample-template
   -
     #hr: true
     title: Assets
     description: Adding different types of assets to SEEK, creating new asset versions.
     subitems:
     - title: Adding assets (data, models, SOPs, publications) to SEEK
       url: /help/user-guide/adding-assets
-    - title: Data file wizard
-      url: /help/user-guide/data-file-upload-wizard
-    - title: Simulate a model on JWS Online
-      url: /help/user-guide/simulate-on-jws-online
+    - title: Data files 
+      subitems:
+      - title: Data file wizard
+        url: /help/user-guide/data-file-upload-wizard
+    - title: Models
+      subitems:
+#     - title: Models
+#       url: 
+      - title: Simulate a model on JWS Online
+        url: /help/user-guide/simulate-on-jws-online
+      - title: Comparing two versions of a Model
+        url: /help/user-guide/model-comparison
+    - title: SOPs
+      url: /help/user-guide/sops
+    - title: Publications 
+      url: /help/user-guide/publications
     - title: Collections
       url: /help/user-guide/collections
 #    - title: "[Document]"
@@ -90,25 +132,35 @@ subitems:
 #      url: ""
     - title: Creating new asset versions
       url: /help/user-guide/uploading-new-versions
-      subitems:
-      - title: Comparing two versions of a Model
-        url: /help/user-guide/model-comparison
+#  -
+#    #hr: true
+#    title: Activities
+#    description: How to change the events and presentations.
+#    subitems:
+#    - title: "[Presentation]"
+#      url: ""
+#    - title: Events
+#      url: /help/user-guide/general-attributes#events
   -
     #hr: true
     title: Samples
     description: Creating and browsing samples, and samples in ISA-JSON compliant experiments.
     subitems:
-    - title: Samples introduction
+    - title: Introduction
       url: /help/user-guide/samples
+    - title: Sample types
+      description: Creating and browsing samples, and samples in ISA-JSON compliant experiments.
       subitems:
       - title: Create a Sample Type
         url: /help/user-guide/create-sample-type
+    - title: Samples 
+      subitems:
       - title: Create a Sample
         url: /help/user-guide/create-sample
+      - title: Working with samples in ISA-JSON compliant Experiments
+        url: /help/user-guide/create-sample-isajson-compliant
       - title: Legacy Biosamples
         url: /help/user-guide/legacy-biosamples
-    - title: Working with samples in ISA-JSON compliant Experiments
-      url: /help/user-guide/create-sample-isajson-compliant
   -
     #hr: true
     title: General attributes and links
@@ -121,19 +173,9 @@ subitems:
 #      url: ""
     - title: Licenses
       url: /help/user-guide/licenses
-    - title: Bulk changing of sharing permissions
-      url: /help/user-guide/bulk-change-sharing-permission
+
 #    - title: "[Extended metadata]"
 #      url: ""
-#  -
-#    #hr: true
-#    title: Activities
-#    description: How to change the events and presentations.
-#    subitems:
-#    - title: "[Presentation]"
-#      url: ""
-#    - title: Events
-#      url: /help/user-guide/general-attributes#events
   - 
     #hr: true
     title: Integrations
@@ -143,10 +185,6 @@ subitems:
       url: /help/user-guide/openbis
     - title: Using Copasi with SEEK
       url: /help/user-guide/copasi-button
-    - title: Experiment view (or Simple page)
-      url: /help/user-guide/viewing-project-in-single-page
-    - title: Compliance with ISA-JSON schemas
-      url: /help/user-guide/isa-json-compliant-experiment
   -
     #hr: true
     title: User guide for API

help/user-guide/assays.md

@@ -0,0 +1,80 @@
+---
+title: Asssays
+---
+
+The [ISA metadata framework](https://isa-specs.readthedocs.io/en/latest/isamodel.html) requires the description (metadata) of different types of samples, namely Study Sources, Study Samples and Assay Samples. This description is based on customisable Experiment Sample Templates and includes the linking of applied Protocols. Follow the link for an overview about [ISA-JSON compliant experiments](isa-json-compliant-experiment.html).
+
+In the context of an ISA-JSON compliant experiment, we use the terms ISA Investigation, ISA Study, and ISA Assay when referring to Investigation, Study, and Assay, respectively.
+
+## 1. Creating an Assay Stream
+
+* Select an ISA-JSON compliant Study, then click on "Design Assay Stream" button at the top right corner of the page.
+* Fill out the form and click "Create". After creation, sharing permissions can be managed.
+  * Assay position: Assay position determines the order in which Assay Streams are visualized in the tree view relative to each other.
+
+## 2. Creating an ISA Assay
+
+* Select an Assay Stream, then click on "Design Assay" button at the top right corner of the page.
+* Fill out the provided form as explained below.
+
+### 2.1 Link the sampling Protocol 
+Select Protocols already registered in the platform that describe the used method or procedure (SOP) applied to the Assay. See how to [create an SOP](adding-assets) in SEEK.
+
+### 2.2 Design a Samples table for Assay
+
+The Assay Samples table can be used to register metadata about Assay's outputs (other material or data file).
+* The method, the protocol and its parameters (parameter value) applied to the Assay to generate the Assay’s outputs.
+* Any relevant characteristics of the Assay’s outputs (other material characteristic or data file comment), from sample’s amount and quality to storage of each physical tube in a laboratory or of each digital data file in a file storage system.
+
+The Assay Samples table is a Sample Type associated with the Assay and can only be accessed through the Assay interface. The Assay Samples table can only be created starting from an existing Experiment Sample Templates.
+
+#### 2.2.1 Choose one Experiment Sample Template
+
+* Choose one Experiment Sample Templates by clicking on "Existing Experiment Sample Templates" button.
+
+* Filter existing Experiment Sample Templates based on:
+  * the repository that will store metadata about your Study Sources (e.g. ENA, ArrayExpress or your institutional repository). Select "Project specific templates" if you want to use a template made for or by a specific Project
+  * ISA Level
+    * assay - material: if the output samples of the assay are physical materials
+    * assay - data file: if the output of the assays are digital data files
+  * organism
+
+![create isaassay 2](/images/user-guide/isajson-compliance/create_isaassay_2.png){:.screenshot}
+
+* Choose a template from the resulting dropdown menu.
+* Select "Apply".
+* Give a Title to the Assay Samples table.
+
+#### 2.2.2 Customise the Assay Samples table
+
+The Attributes table can be used to customise the Assay Samples table. However, be aware that applying changes may compromise the compliance to the original template.
+
+* If you want to add new attributes of your choice to your Samples table, select “Add new attribute” button.
+* Fill out the mandatory and optional fields. Note that for ISA-JSON compliant Experiments, the ISA Tag is a mandatory field.
+* For ISA tag, select 
+  * in case of ISA Level "assay - material": "other_material_characteristic" or "parameter_value";
+  * in case of ISA Level "assay - data file": "data_file_comment" or "parameter_value";
+
+  Note that selecting any other options would generate an error since other options are already selected in the starting template.
+
+![create isaassay 3](/images/user-guide/isajson-compliance/create_isaassay_3.png){:.screenshot}
+
+### 2.3 Visualise ISA Assay
+Upon creation, the newly designed ISA Assay will appear in the tree view on the left sidebar, in Experiment View. Follow the link to know more about [Experiment View](viewing-project-in-single-page).
+
+## 3. Adding samples to ISA Assay
+Follow the link to know how to [create samples in ISA-JSON compliant experiments](create-sample-isajson-compliant), including [Assay Samples](create-sample-isajson-compliant#create-assay-samples).
+
+## 4. Managing assays in an assay stream
+When editing or deleting an assay from an assay stream, different conditions apply depending on whether the assay has associated samples.
+
+### 4.1 Deleting an Assay
+An assay can only be deleted if it has no samples associated with it. If the assay contains samples, you must first delete those samples before proceeding with the assay deletion.
+If the assay is the last one in the assay stream, it can be removed without affecting the structure of the stream. If it is a midway assay (i.e., not the last assay in the assay stream), the system will automatically update the sample linkage. The input sample of the following assay will always link to the output sample of the preceding assay without requiring manual intervention. To remove, select the assay and click “Actions -> Delete ISA Assay” in the top right corner.
+
+### 4.2 Adding an Assay
+Adding a new assay is straightforward when it follows the last assay in the stream. This is permitted even if samples are associated with the assay. Select the last assay in the assay stream, and click the “Design the next Assay” button at the top right. 
+For adding a midway assay, the next assay in the stream cannot have samples associated with it. Sample linkage is updated automatically, and no manual re-establishment is needed. To add a midway assay, select the preceding assay where you want to add an additional assay, and select “Insert a new Assay”. The new assay will be added after the selected assay. 
+
+### 4.3 Editing an Assay
+Editing an assay follows similar rules to deletion. If an assay has associated samples, certain modifications to the metadata attributes may be restricted. However, it possible to add metadata attributes, or edit the assay’s title, description, etc.