From 8a3767aa016cae516377cde88e76d045a3b2fd72 Mon Sep 17 00:00:00 2001 From: Chris Huynh <82407232+ChrisHuynh333@users.noreply.github.com> Date: Thu, 20 Jun 2024 15:13:09 -0500 Subject: [PATCH] Docs: Project and Sample (#623) * Add more to docs * Add import metadata * Add consistency to docs, reformat * add PR comment changes * Fix rebase * rephrase note in import * Add membership comment to viewing histories * Add missed file change for previous commit --- .../members/group-and-project-members.md | 42 +++-- .../user/project/projects/manage-projects.md | 12 +- .../user/project/projects/projects-intro.md | 10 +- .../user/project/samples/manage-samples.md | 78 +++++---- .../docs/user/project/samples/sample-files.md | 57 +++--- .../user/project/samples/sample-metadata.md | 164 +++++++++++++++++- .../user/project/samples/samples-intro.md | 7 +- 7 files changed, 289 insertions(+), 81 deletions(-) diff --git a/docs-site/docs/user/organization/members/group-and-project-members.md b/docs-site/docs/user/organization/members/group-and-project-members.md index 0c850a4cf0..698920d7db 100644 --- a/docs-site/docs/user/organization/members/group-and-project-members.md +++ b/docs-site/docs/user/organization/members/group-and-project-members.md @@ -79,15 +79,16 @@ To add a user to a group: 6. Select an optional **Access expiration** 7. Click the **Add member to group** button -## Edit member for a group or project +## Edit members for a group or project Prerequisite: You must have at least a **Maintainer** role, or you must be the owner of the group -1. From the left sidebar, select **Projects** or **Groups**, and find your project or group for which you would like to update a member -2. From the left sidebar, select **Members** -3. Find the member that you would like to update +1. From the left sidebar, select **Projects** or **Groups** +2. Select the project or group +3. From the left sidebar, select **Members** +4. Find the member that you would like to update To update a member's role: @@ -107,13 +108,14 @@ You must have at least a **Maintainer** role, or the project must be under your To add a direct user to a project: -1. From the left sidebar, select **Projects**, and find your project -2. From the left sidebar, select **Members** -3. Click the **Add Member** button -4. Select the user you want to add to the project -5. Select an access level (role) -6. Select an optional **Access expiration** -7. Click the **Add member to project** button +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Members** +4. Click the **Add Member** button +5. Select the user you want to add to the project +6. Select an access level (role) +7. Select an optional **Access expiration** +8. Click the **Add member to project** button ## Which roles you can assign @@ -137,10 +139,11 @@ Prerequisites: To remove a member from a project: -1. From the left sidebar, select **Projects**, and find your project -2. From the left sidebar, select **Members** -3. On the right hand side of the row for the member you want to remove, click the `ellipsis` and select **Remove** from the dropdown. -4. Confirm that you would like to remove the member from the project in the popup by clicking the **OK** button +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Members** +4. On the right hand side of the row for the member you want to remove, click **Remove**. +5. Confirm that you would like to remove the member from the project in the popup by clicking the **OK** button ## Remove a member from a group @@ -157,7 +160,8 @@ Prerequisites: To remove a member from a group: -1. From the left sidebar, select **Groups**, and find your group -2. From the left sidebar, select **Members** -3. On the right hand side of the row for the member you want to remove, click the `ellipsis` and select **Remove** from the dropdown. -4. Confirm that you would like to remove the member from the group in the popup by clicking the **OK** button +1. From the left sidebar, select **Groups** +2. Select the group +3. From the left sidebar, select **Members** +4. On the right hand side of the row for the member you want to remove, click **Remove**. +5. Confirm that you would like to remove the member from the group in the popup by clicking the **OK** button diff --git a/docs-site/docs/user/project/projects/manage-projects.md b/docs-site/docs/user/project/projects/manage-projects.md index 5dec2f2d47..25d5cce91e 100644 --- a/docs-site/docs/user/project/projects/manage-projects.md +++ b/docs-site/docs/user/project/projects/manage-projects.md @@ -75,7 +75,17 @@ To update the URL of the project: 3. Select **Change project URL** ## View Project History - + +Prerequisite: +- You must have at least the Maintainer role for the project. +- You must be a direct or inherited member of the project's ancestry. Shared groups and their members cannot see the history. + +To view a project's history: + +1. Select the project that you want to edit and then on the left sidebar +2. Select **History** + +A new project version is created each time the project's information is changed. Clicking a version within the project's history will display what changes were made to the project. ## Transfer Project diff --git a/docs-site/docs/user/project/projects/projects-intro.md b/docs-site/docs/user/project/projects/projects-intro.md index 05a26bc9c3..0c79e874e7 100644 --- a/docs-site/docs/user/project/projects/projects-intro.md +++ b/docs-site/docs/user/project/projects/projects-intro.md @@ -3,4 +3,12 @@ id: introduction --- # Projects - + +Projects are used to organize and manage samples. They can belong to either a group (or subgroup) or a user. + +Access to projects can be granted either through direct user invitation or inviting a group, allowing its members to access the project. + +Through a project, automated analysis of samples can be set up. Follow these steps to learn how. + + +Learn how to work with projects under [Manage Projects](manage-projects). diff --git a/docs-site/docs/user/project/samples/manage-samples.md b/docs-site/docs/user/project/samples/manage-samples.md index cbc54fcf39..5b842451fa 100644 --- a/docs-site/docs/user/project/samples/manage-samples.md +++ b/docs-site/docs/user/project/samples/manage-samples.md @@ -14,8 +14,9 @@ Prerequisite: To view samples that the project contains: -1. From the left sidebar, select **Projects**, select the project -2. From the left sidebar, select **Samples** +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** ## Create Sample @@ -26,12 +27,13 @@ Prerequisites: To create a new sample in a project: -1. From the left sidebar, select **Projects**, select the project -2. From the left sidebar, select **Samples** -3. Select **New Sample** -4. Enter the name of the sample in the **Name** field -5. Enter an optional description for the sample in the **Description** field -6. Select **Create sample** +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select **New Sample** +5. Enter the name of the sample in the **Name** field +6. Enter an optional description for the sample in the **Description** field +7. Select **Create sample** ## Update Sample @@ -42,13 +44,14 @@ Prerequisites: To update sample details: -1. From the left sidebar, select **Projects**, select the project -2. From the left sidebar, select **Samples** -3. Select the sample that you would like to edit -4. Select **Edit this sample** -5. Enter the name of the sample in the **Name** field -6. Enter an optional description for the sample in the **Description** field -7. Select **Update sample** +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select the sample +5. Select **Edit this sample** +6. Enter the name of the sample in the **Name** field +7. Enter an optional description for the sample in the **Description** field +8. Select **Update sample** ## Transfer Samples @@ -64,11 +67,12 @@ Otherwise: To transfer samples into another project: -1. From the left sidebar, select **Projects**, select the project -2. From the left sidebar, select **Samples** -3. Select the checkboxes for the samples that you would like to transfer -4. Select **Transfer samples** -5. From the transfer samples pop-up, select the project to which you would like to transfer the samples to, and select **Submit** +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select the checkboxes for the samples that you would like to transfer +5. Select **Transfer samples** +6. From the transfer samples pop-up, select the project to which you would like to transfer the samples to, and select **Submit** ## Clone Samples @@ -80,11 +84,12 @@ Prerequisites: To clone samples into another project: -1. From the left sidebar, select **Projects**, select the project -2. From the left sidebar, select **Samples** -3. Select the checkboxes for the samples that you would like to clone -4. Select **Clone samples** -5. From the clone samples pop-up, select the project to which you would like to clone the samples to, and select **Submit** +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select the checkboxes for the samples that you would like to clone +5. Select **Clone samples** +6. From the clone samples pop-up, select the project to which you would like to clone the samples to, and select **Submit** ## Delete Sample @@ -95,11 +100,24 @@ Prerequisites: To remove a sample: -1. From the left sidebar, select **Projects**, select the project -2. From the left sidebar, select **Samples** -3. Select the sample that you would like to remove -4. Select **Remove** +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select the sample +5. Select **Remove** ## View Sample History - +Prerequisite: +- You must have at least the Maintainer role for the sample's project. +- You must be a direct or inherited member of the project's ancestry. Shared groups and their members cannot see the history. + +To view a sample's history: + +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select the sample +5. Click the **History** tab + +A new sample version is created each time the sample's information is changed. Clicking a version within the sample's history will display what changes were made to the sample. diff --git a/docs-site/docs/user/project/samples/sample-files.md b/docs-site/docs/user/project/samples/sample-files.md index 08d1ff2748..fe10631b14 100644 --- a/docs-site/docs/user/project/samples/sample-files.md +++ b/docs-site/docs/user/project/samples/sample-files.md @@ -12,9 +12,11 @@ Prerequisites: - You must have access to the project either through membership, or through a namespace share -1. From the left sidebar, select **Projects**, select the project -2. From the left sidebar, select **Samples** -3. The table lists all the single-end and paired-end files which have been uploaded to the sample +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select the sample +5. The table lists all the single-end and paired-end files which have been uploaded to the sample ## Upload Files to Samples @@ -25,31 +27,40 @@ Prerequisites: To upload files to a sample: -1. From the left sidebar, select **Projects**, select the project -2. From the left sidebar, select **Samples** -3. Select **Upload Files** -4. From the dialog, select **Choose files** -5. Select the files you would like to upload. Multi file selection is enabled -6. Select **Upload** +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select the sample +5. Select **Upload Files** +6. From the dialog, select **Choose files** +7. Select the files you would like to upload. Multi file selection is enabled +8. Select **Upload** ## Concatenate Sample files Prerequisites: - You must have access to the project either through membership, or through a namespace share -- You must have an **Maintainer** role +- You must have a **Maintainer** role - Files of the same type (single-end or paired-end) and compression can be concatenated together -1. From the left sidebar, select **Projects**, select the project -2. From the left sidebar, select **Samples** -3. Select the checkboxes for the files you would like to concatenate, and select **Concatenate files** -4. In the dialog, the files to be concatenated are listed. -5. Enter the **Filename**. This will be the base name of the concatenated files. -6. Select the checkbox **Delete originals** if you would like to remove the original files after concatenation -7. Select **Concatenate** +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select the sample +5. Select the checkboxes for the files you would like to concatenate, and select **Concatenate files** +6. In the dialog, the files to be concatenated are listed. +7. Enter the **Filename**. This will be the base name of the concatenated files. +8. Select the checkbox **Delete originals** if you would like to remove the original files after concatenation +9. Select **Concatenate** ## Download Sample files - + +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select the sample +5. Click the filename you'd like to download ## Delete Sample files @@ -58,7 +69,9 @@ Prerequisites: - You must have access to the project either through membership, or through a namespace share - You must have an **Owner** role -1. From the left sidebar, select **Projects**, select the project -2. From the left sidebar, select **Samples** -3. To delete multiple files, select the checkboxes for the files you would like to delete, then click **Delete Files** -4. To delete individual single end and paired-end reads, select **Delete** for the files you would like to delete. +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select the sample +5. To delete multiple files, select the checkboxes for the files you would like to delete, then click **Delete Files** +6. To delete individual single end and paired-end reads, select **Delete** for the files you would like to delete. diff --git a/docs-site/docs/user/project/samples/sample-metadata.md b/docs-site/docs/user/project/samples/sample-metadata.md index c621582499..2357172e2d 100644 --- a/docs-site/docs/user/project/samples/sample-metadata.md +++ b/docs-site/docs/user/project/samples/sample-metadata.md @@ -4,10 +4,160 @@ id: sample-metadata title: Sample Metadata --- - +Metadata can be added to samples to give them any additional information required by users. + +A sample cannot have metadata with the same key, and metadata added by an analysis cannot be overwritten by a user. + +## View Metadata + +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Click the toggle beside **Metadata** + +The samples table will update with all the samples' metadata. + +To view individual sample metadata: + +5. Select the sample +6. Click the **Metadata** tab + +## Add Metadata + +Prerequisites: + +- You must have at least a **Maintainer** role for the sample's project +- A sample added to the project + +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select the sample +5. Click the **Metadata** tab +6. Click **Add Metadata** + +A dialog will pop-up where you can add new metadata. + +## Update Metadata + +Prerequisites: + +- You must have at least a **Maintainer** role for the sample's project +- A sample with existing metadata added to the project + +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select the sample +5. Click the **Metadata** tab +6. Click the **Update** link of the metadata you'd like to update + +A dialog will pop-up where you can update the metadata. + +## Learn About Importing Metadata + +Importing metadata allows you to add multiple metadata fields to multiple samples all at once. This requires a spreadsheet in .csv, .xls, or .xlsx format. + +This is an example of the expected spreadsheet format: + + | Sample Name | MetadataField1 | MetadataField2 | MetadataField3 | + | :---------- | :------------- | :------------- | :------------- | + | Sample 1 | value1 | value2 | value3 | + | Sample 2 | value4 | value5 | value6 | + +The following metadata will be added: + + - Sample 1: + + | Key | Value | + | :------------- | :----- | + | MetadataField1 | value1 | + | MetadataField2 | value2 | + | MetadataField3 | value3 | + + - Sample 2: + + | Key | Value | + | :------------- | :----- | + | MetadataField1 | value4 | + | MetadataField2 | value5 | + | MetadataField3 | value6 | + +When creating the spreadsheet, you are required to have a column that contains a sample identifier. The identifier is case-sensitive and can contain either the sample names or IDs. + +**An important note:** When importing a metadata spreadsheet, you will be asked if you'd like to **Ignore empty values**. If this is **selected**, any metadata fields without an associated value will be ignored and those metadata keys will not be removed from the sample if present. However, if this **not selected**, any samples with the metadata key and empty value will be **deleted**. + +For example, if the metadata above was imported and added to Sample 1 and Sample 2, and the following spreadsheet was then imported: + + | Sample Name | MetadataField1 | MetadataField2 | MetadataField3 | MetadataField4 | + | :---------- | :------------- | :------------- | :------------- | :------------- | + | Sample 1 | | newValue2 | newValue3 | anotherValue1 | + | Sample 2 | newValue4 | | newValue6 | anotherValue2 | + +This would result in the following sample metadata: +- If **Ignore empty values** was **checked**: + + - Sample 1: + + | Key | Value | + | :------------- | :------------ | + | MetadataField1 | value1 | + | MetadataField2 | newValue2 | + | MetadataField3 | newValue3 | + | MetadataField4 | anotherValue1 | + + - Sample 2: + + | Key | Value | + | :------------- | :------------ | + | MetadataField1 | newValue4 | + | MetadataField2 | value5 | + | MetadataField3 | newValue6 | + | MetadataField4 | anotherValue2 | + +- If **Ignore empty values** was **not checked**: + + - Sample 1: + + | Key | Value | + | :------------- | :------------ | + | MetadataField2 | newValue2 | + | MetadataField3 | newValue3 | + | MetadataField4 | anotherValue1 | + + - Sample 2: + + | Key | Value | + | :------------- | :------------ | + | MetadataField1 | newValue4 | + | MetadataField3 | newValue6 | + | MetadataField4 | anotherValue2 | + +## Steps to Import Metadata + +Prerequisites: + +- You must have at least a **Maintainer** role for the sample's project +- A sample added to the project + +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Click **Import Metadata** + +A dialog will pop-up to select the spreadsheet to be imported. After selecting the spreadsheet file, identify which column contains the sample identifier and whether you'd like to [Ignore empty values](sample-metadata#learn-about-importing-metadata) + +## Delete Metadata + +Prerequisites: + +- You must have at least a **Maintainer** role for the sample's project +- A sample with existing metadata added to the project + +1. From the left sidebar, select **Projects** +2. Select the project +3. From the left sidebar, select **Samples** +4. Select the sample +5. Click the **Metadata** tab +6. Click the checkboxes of the metadata you'd like to delete. +7. Click **Delete Metadata** diff --git a/docs-site/docs/user/project/samples/samples-intro.md b/docs-site/docs/user/project/samples/samples-intro.md index cdfe1cb1be..17a8731812 100644 --- a/docs-site/docs/user/project/samples/samples-intro.md +++ b/docs-site/docs/user/project/samples/samples-intro.md @@ -3,4 +3,9 @@ id: introduction --- # Samples - + +Samples belong to projects and contain the files to be analyzed by IRIDA Next. + +Access to samples is dependent on its project's membership. + +Learn how to [manage your samples](manage-samples), [work with sample files](sample-files) and [manage sample metadata](sample-metadata).