From 430383cb1ff73f105aa10c1e46123e57c04c88d1 Mon Sep 17 00:00:00 2001 From: NielsGeudens Date: Thu, 27 Mar 2025 15:42:23 +0100 Subject: [PATCH 1/5] Added section 'user roles and permissions' --- _data/sidebars/userguide.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_data/sidebars/userguide.yml b/_data/sidebars/userguide.yml index 77b00790e..28c02cb72 100644 --- a/_data/sidebars/userguide.yml +++ b/_data/sidebars/userguide.yml @@ -1,6 +1,8 @@ title: User Guide title_url: /help/user-guide/ subitems: + - title: User roles and permissions + url: /help/user-guide/user-roles-permissions - title: Definitions url: /help/user-guide/definitions - title: Profile From d8f3f7239758841d1fdad2d56dd040b5185d9c13 Mon Sep 17 00:00:00 2001 From: NielsGeudens Date: Fri, 28 Mar 2025 14:12:01 +0100 Subject: [PATCH 2/5] * restructured the user guide to match the dropdown menus in the platform. * created dedicated pages for investigations, studies and assays. Currently, these are focussed on ISA-JSON compliant ISA, but could be expanded still. Content taken from 'Designing an ISA-JSON compliant experiment'. This page is no longer linked, but left intact if changes/reverts need to be done. * Created dedicated pages for SOPs and publications. Content needs to be expanded still. --- _data/sidebars/userguide.yml | 189 ++++++++++++++++---------- help/user-guide/assays.md | 80 +++++++++++ help/user-guide/general-attributes.md | 14 -- help/user-guide/investigations.md | 17 +++ help/user-guide/publications.md | 12 ++ help/user-guide/sops.md | 7 + help/user-guide/studies.md | 70 ++++++++++ 7 files changed, 300 insertions(+), 89 deletions(-) create mode 100644 help/user-guide/assays.md create mode 100644 help/user-guide/investigations.md create mode 100644 help/user-guide/publications.md create mode 100644 help/user-guide/sops.md create mode 100644 help/user-guide/studies.md diff --git a/_data/sidebars/userguide.yml b/_data/sidebars/userguide.yml index 28c02cb72..a80fa90a8 100644 --- a/_data/sidebars/userguide.yml +++ b/_data/sidebars/userguide.yml @@ -1,76 +1,107 @@ title: User Guide title_url: /help/user-guide/ subitems: - - title: User roles and permissions - url: /help/user-guide/user-roles-permissions - - 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 +# - hr: true +# title: Designing an ISA-JSON compliant experiment +# url: /help/user-guide/designing-experiments-isajson-compliant + - 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#browsing-samples-by-experiment-sample-templates - #hr: true title: Assets @@ -78,10 +109,22 @@ subitems: 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]" @@ -92,25 +135,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 @@ -123,19 +176,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 @@ -145,10 +188,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 diff --git a/help/user-guide/assays.md b/help/user-guide/assays.md new file mode 100644 index 000000000..ead54b7a1 --- /dev/null +++ b/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. diff --git a/help/user-guide/general-attributes.md b/help/user-guide/general-attributes.md index f702e8469..84a20cd9c 100644 --- a/help/user-guide/general-attributes.md +++ b/help/user-guide/general-attributes.md @@ -114,11 +114,6 @@ You can also add non-SEEK creators using free text. Creators can be removed easily where necessary. - -## SOPs -[Assay specific] -SOPs are standard operating procedures which describe the protocol required to reproduce the assay. They can be in any format (word files, e-lab notebooks, code, annotated spreadsheets etc). Relevant SOPs can be linked directly to the assay via the dropdown menu. - ## Data Files [Assay specific] Data files can be any file containing data relevant to the assay (raw data, processed data, calibration information etc). They can be in any format (word files, e-lab notebooks, code, annotated spreadsheets etc). Relevant data files can be linked directly to the assay via the dropdown menu. @@ -130,15 +125,6 @@ A Placeholder indicates data that will be consumed, used or produced when a Proj ## File Templates A File Template describes conforming DataFiles. It may be annotated with information about the format and type of data in the DataFiles. Annotations are *not* about the File Template itself. For example, a File Template that is a Word document may describe conformant PNG images. -## Publications -If your asset is directly related to a publication you can link the two together in SEEK. You can select publications within your project form the drop-down menu. If the publication is in another project you need to check the box that says associate publications from other projects. - -![add publication 1](/images/user-guide/add_publication_1.png){:.screenshot} - -When a publication is added a preview will be shown in the bottom right hand corner of SEEK. It can be removed easily if needed. - -![add publication 2](/images/user-guide/add_publication_2.png){:.screenshot} - ## Experimental assays and Modelling analysis It is best that assets are contextualised using the ISA graph (more later). This means that assets where possible should be linked to an assay or an experimental analysis. This can be done by selecting an appropriate assay or experimental analysis from the drop down menu. diff --git a/help/user-guide/investigations.md b/help/user-guide/investigations.md new file mode 100644 index 000000000..e2c283f8f --- /dev/null +++ b/help/user-guide/investigations.md @@ -0,0 +1,17 @@ +--- +title: Investigations +--- + +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 ISA Investigation +Select +* Create Investigation from header menu bar. +* Alternatively, in Experiment View, select the Design Investigation button at the top right corner + +Fill out the provided form, check the option for "Make Investigation compliant to ISA-JSON schemas?" and then click the 'Create' button. + +![select isajson compliance](/images/user-guide/isajson-compliance/select_isajson_compliance.png){:.screenshot} + diff --git a/help/user-guide/publications.md b/help/user-guide/publications.md new file mode 100644 index 000000000..db08b0873 --- /dev/null +++ b/help/user-guide/publications.md @@ -0,0 +1,12 @@ +--- +title: Publications +--- + +## Publications +If your asset is directly related to a publication you can link the two together in SEEK. You can select publications within your project form the drop-down menu. If the publication is in another project you need to check the box that says associate publications from other projects. + +![add publication 1](/images/user-guide/add_publication_1.png){:.screenshot} + +When a publication is added a preview will be shown in the bottom right hand corner of SEEK. It can be removed easily if needed. + +![add publication 2](/images/user-guide/add_publication_2.png){:.screenshot} \ No newline at end of file diff --git a/help/user-guide/sops.md b/help/user-guide/sops.md new file mode 100644 index 000000000..627afd4c1 --- /dev/null +++ b/help/user-guide/sops.md @@ -0,0 +1,7 @@ +--- +title: Standard Operating Procedures (SOPs) +--- + +## Standard Operating Procedures (SOPs) +[Assay specific] +SOPs are standard operating procedures which describe the protocol required to reproduce the assay. They can be in any format (word files, e-lab notebooks, code, annotated spreadsheets etc). Relevant SOPs can be linked directly to the assay via the dropdown menu. \ No newline at end of file diff --git a/help/user-guide/studies.md b/help/user-guide/studies.md new file mode 100644 index 000000000..64e8e23f2 --- /dev/null +++ b/help/user-guide/studies.md @@ -0,0 +1,70 @@ +--- +title: Studies +--- + +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. + +## 21. Creating an ISA Study +ISA Study can only be associated to an ISA Investigation. It is not possible to associate an ISA Study to an Investigation which is not ISA-JSON compliant. + +To start designing an ISA Study within the Investigation in Experiment View, select the Investigation and then select the "Design Study" button at the top right corner. + +Fill out the provided form as explained below. + +## 1.1 Design a Sources table for Study Sources +The Sources table can be used to register metadata about Study Sources material. +* Biological material and its origin or provenance +* Environmental and/or experimental conditions of the Sources in the Study +* Experimental groups of the Sources +* Observation units +* Experimental factor(s), confounding variables, covariates, events, comments etc +* Any other relevant information about the Sources in the Study + +The Study Sources table is a Sample Type associated with the Study and can only be accessed through the Study interface. The Study Sources table can only be created starting from an existing Experiment Sample Templates. + +### 1.1.1 Choose one Experiment Sample Template + +* Choose one Experiment Sample Templates by clicking on "Existing Experiment Sample Templates" button. + +![create isastudy source 1](/images/user-guide/isajson-compliance/create_isastudy_source_1.png){:.screenshot} + +* 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 + * organism + +![create isastudy source 2](/images/user-guide/isajson-compliance/create_isastudy_source_2.png){:.screenshot} + +* Choose a template from the resulting dropdown menu. +* Select "Apply". +* Give a Title to the Study Sources table. + +### 1.1.2 Customise the Study Sources table + +The Attributes table can be used to customise the Study Sources 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 Sources 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 "source_characteristic". Note that selecting "source" would generate an error since a "source" is already selected in the starting template. + +![create isastudy source 3](/images/user-guide/isajson-compliance/create_isastudy_source_3.png){:.screenshot} + +## 1.2 Link the sampling Protocol +Select Protocols already registered in the platform that describe the used method or procedure (SOP) used to collect Samples from Sources in your Study (Samples collection protocol). See how to [create an SOP](adding-assets) in SEEK. + +## 1.3 Design a Samples table for Study Samples + +Follow the same steps described for designing the Study Sources table to create and customise the Study Samples table. + +## 1.4 Visualise ISA Study +Upon creation, the newly designed ISA Study 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). + +## 2. Adding Sources to ISA Study +After you have designed the Sources table, you can then start by creating and describing your Study Sources according to the designed table. + +Follow the link to know how to [create samples in ISA-JSON compliant experiments](create-sample-isajson-compliant), including [Study Sources](create-sample-isa-json-compliant#create-study-sources). + +## 3. Adding Samples to ISA Study + +Follow the link to know how to [create samples in ISA-JSON compliant experiments](create-sample-isajson-compliant), including [Study Samples](create-sample-isajson-compliant#create-study-samples). \ No newline at end of file From 2e8719599b263888ad26ee23debe4595320647c6 Mon Sep 17 00:00:00 2001 From: Kevin De Pelseneer Date: Thu, 3 Apr 2025 13:15:35 +0200 Subject: [PATCH 3/5] Update assays.md --- help/user-guide/assays.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/help/user-guide/assays.md b/help/user-guide/assays.md index ead54b7a1..fd10b0931 100644 --- a/help/user-guide/assays.md +++ b/help/user-guide/assays.md @@ -6,21 +6,21 @@ The [ISA metadata framework](https://isa-specs.readthedocs.io/en/latest/isamodel 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 +## 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 +## 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 +### 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 +### 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. @@ -28,7 +28,7 @@ The Assay Samples table can be used to register metadata about Assay's outputs ( 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 +#### 2.2.1 Choose one Experiment Sample Template * Choose one Experiment Sample Templates by clicking on "Existing Experiment Sample Templates" button. @@ -45,7 +45,7 @@ The Assay Samples table is a Sample Type associated with the Assay and can only * Select "Apply". * Give a Title to the Assay Samples table. -### 2.2.2 Customise 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. @@ -59,22 +59,22 @@ The Attributes table can be used to customise the Assay Samples table. However, ![create isaassay 3](/images/user-guide/isajson-compliance/create_isaassay_3.png){:.screenshot} -## 2.3 Visualise ISA Assay +### 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 +## 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 +## 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 +### 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 +### 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 +### 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. From d5308fb836899c697d997e721fc83ab2ed4169fa Mon Sep 17 00:00:00 2001 From: NielsGeudens <167087988+NielsGeudens@users.noreply.github.com> Date: Mon, 7 Apr 2025 10:30:14 +0200 Subject: [PATCH 4/5] Update userguide.yml --- _data/sidebars/userguide.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/_data/sidebars/userguide.yml b/_data/sidebars/userguide.yml index a80fa90a8..ea61ea007 100644 --- a/_data/sidebars/userguide.yml +++ b/_data/sidebars/userguide.yml @@ -72,9 +72,6 @@ subitems: url: /help/user-guide/isa-overview - title: Generating the ISA structure url: /help/user-guide/generating-the-isa-structure -# - hr: true -# title: Designing an ISA-JSON compliant experiment -# url: /help/user-guide/designing-experiments-isajson-compliant - title: ISA-JSON compliant experiments url: /help/user-guide/isa-json-compliant-experiment - hr: true @@ -101,7 +98,7 @@ subitems: - title: Creating Experiment Sample Templates url: /help/user-guide/isajson-templates - title: Browse samples by Experiment Sample Template - url: /help/user-guide/browsing#browsing-samples-by-experiment-sample-templates + url: /help/user-guide/browsing#browse-samples-by-experiment-sample-template - #hr: true title: Assets From ab7f82f48693b4555f218a325c6e912f636a5ab9 Mon Sep 17 00:00:00 2001 From: NielsGeudens <167087988+NielsGeudens@users.noreply.github.com> Date: Mon, 7 Apr 2025 10:30:56 +0200 Subject: [PATCH 5/5] Delete help/user-guide/designing-experiments-isajson-compliant.md --- ...designing-experiments-isajson-compliant.md | 140 ------------------ 1 file changed, 140 deletions(-) delete mode 100644 help/user-guide/designing-experiments-isajson-compliant.md diff --git a/help/user-guide/designing-experiments-isajson-compliant.md b/help/user-guide/designing-experiments-isajson-compliant.md deleted file mode 100644 index 4bf8ac4a4..000000000 --- a/help/user-guide/designing-experiments-isajson-compliant.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Designing an ISA-JSON compliant experiment ---- - -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 ISA Investigation -Select -* Create Investigation from header menu bar. -* Alternatively, in Experiment View, select the Design Investigation button at the top right corner - -Fill out the provided form, check the option for "Make Investigation compliant to ISA-JSON schemas?" and then click the 'Create' button. - -![select isajson compliance](/images/user-guide/isajson-compliance/select_isajson_compliance.png){:.screenshot} - - -## 2. Creating an ISA Study -ISA Study can only be associated to an ISA Investigation. It is not possible to associate an ISA Study to an Investigation which is not ISA-JSON compliant. - -To start designing an ISA Study within the Investigation in Experiment View, select the Investigation and then select the "Design Study" button at the top right corner. - -Fill out the provided form as explained below. - - -## 2.1 Design a Sources table for Study Sources -The Sources table can be used to register metadata about Study Sources material. -* Biological material and its origin or provenance -* Environmental and/or experimental conditions of the Sources in the Study -* Experimental groups of the Sources -* Observation units -* Experimental factor(s), confounding variables, covariates, events, comments etc -* Any other relevant information about the Sources in the Study - -The Study Sources table is a Sample Type associated with the Study and can only be accessed through the Study interface. The Study Sources table can only be created starting from an existing Experiment Sample Templates. - -### 2.1.1 Choose one Experiment Sample Template - -* Choose one Experiment Sample Templates by clicking on "Existing Experiment Sample Templates" button. - -![create isastudy source 1](/images/user-guide/isajson-compliance/create_isastudy_source_1.png){:.screenshot} - -* 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 - * organism - -![create isastudy source 2](/images/user-guide/isajson-compliance/create_isastudy_source_2.png){:.screenshot} - -* Choose a template from the resulting dropdown menu. -* Select "Apply". -* Give a Title to the Study Sources table. - -### 2.1.2 Customise the Study Sources table - -The Attributes table can be used to customise the Study Sources 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 Sources 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 "source_characteristic". Note that selecting "source" would generate an error since a "source" is already selected in the starting template. - -![create isastudy source 3](/images/user-guide/isajson-compliance/create_isastudy_source_3.png){:.screenshot} - -## 2.2 Link the sampling Protocol -Select Protocols already registered in the platform that describe the used method or procedure (SOP) used to collect Samples from Sources in your Study (Samples collection protocol). See how to [create an SOP](adding-assets) in SEEK. - -## 2.3 Design a Samples table for Study Samples - -Follow the same steps described for designing the Study Sources table to create and customise the Study Samples table. - -## 2.4 Visualise ISA Study -Upon creation, the newly designed ISA Study 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 Sources to ISA Study -After you have designed the Sources table, you can then start by creating and describing your Study Sources according to the designed table. - -Follow the link to know how to [create samples in ISA-JSON compliant experiments](create-sample-isajson-compliant), including [Study Sources](create-sample-isa-json-compliant#create-study-sources). - -## 4. Adding Samples to ISA Study - -Follow the link to know how to [create samples in ISA-JSON compliant experiments](create-sample-isajson-compliant), including [Study Samples](create-sample-isajson-compliant#create-study-samples). - -## 5. 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. - -## 6. 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. - -## 6.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. - -## 6.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. - -### 6.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. - -### 6.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} - -## 6.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). - -## 7. 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).