feat: cohort building release 1

content/1.overview/4.faq.md

@@ -37,7 +37,7 @@ Please see the following questions in each application's dedicated frequently as
 
 ### How do I cite St. Jude Cloud?
 
-The manuscript for St. Jude Cloud is currently in preparation. In the meantime, please refer to the [citation guide](/overview/citing-stjude-cloud).
+Please refer to the [citation guide](/overview/citing-stjude-cloud).
 
 ### When can I publish my findings using St. Jude Cloud data?
 

content/3.genomics-platform/1.getting-started/1.overview.md

@@ -29,35 +29,11 @@ The information displayed below this point is primarily intended for employees o
 Please complete the following check-list to get started with using St. Jude
 Cloud.
 
-- [x] Join St. Jude Cloud help desk channel (#stjudecloud-helpdesk) on Slack ([link](#joining-slack)).
 - [x] Log in to your St. Jude Cloud account ([link](#login-to-st-jude-cloud)).
 - [x] Enable Microsoft Azure ([link](#enable-microsoft-azure)).
 - [x] Create your first project ([link](#create-your-first-project)).
 - [x] Set up your billing account ([link](#set-up-your-billing-account)).
 
-### Joining Slack
-
-The St. Jude Cloud team uses [Slack](https://slack.com/) to communicate on a day-to-day basis.
-When standing up a help desk, we decided to offer that functionality on Slack to allow our community to answer questions alongside our team.
-If you are an employee at SJCRH, you already have a Slack account (at no cost to you) — you might even like it so much, you decide to use it during this work from home period!
-
-If you have any issues with the instructions below, you can email [helpdesk@stjude.org](mailto:helpdesk@stjude.org) or [support@stjude.cloud](mailto:support@stjude.cloud).
-
-#### Steps
-
-1. Navigate to [https://stjude.slack.com](https://stjude.slack.com), click "Sign in with your St. Jude Account", and enter your St. Jude credentials
-   Congrats!
-   You're now on Slack.
-2. Download the desktop app by visiting [https://slack.com/download](https://slack.com/download).
-   The instructions differ depending on whether you are on a Windows/Mac/Linux machine.
-   Once you install and start up the app, the sign-in process should look the same as step 1.
-3. To join the `#stjudecloud-helpdesk` channel, you can click the word "Channels" in the left sidebar and search for `#stjudecloud-helpdesk`.
-   If you have issues, please see [the official Slack guide](https://slack.com/help/articles/205239967-Join-a-channel) on joining a channel.
-
-You should now see a screen similar to the one included below. You can type your questions into the chat box at the bottom. See you there!
-
-![Slack Helpdesk Channel](/img/genomics-platform/index/slack-messaging.png)
-
 ### Login to St. Jude Cloud
 
 Signing in to St. Jude Cloud is similarly easy — if you have a SJCRH account, you already have a St. Jude Cloud account.

content/4.pecan/1.overview/1.getting-started.md

@@ -4,7 +4,7 @@ navigation:
   title: Getting Started
 ---
 
-The PeCan platform presents curated pediatric cancer genomics data including variants, mutational signatures, and gene expression data in addition to histological slide images from over 11,000 hematological, CNS, and non-CNS solid tumor patient samples.
+The PeCan platform presents curated pediatric cancer genomics data including variants, mutational signatures, and gene expression data in addition to histological slide images from over 12,000 hematological, CNS, and non-CNS solid tumor patient samples.
 
 Data can be explored via a series of data facets containing both retrospective and prospective study cohorts from St. Jude Children's Research Hospital and other trusted institutions and research centers around the world such as [TARGET](https://ocg.cancer.gov/programs/target), [DKFZ](https://www.dkfz.de/en/index.html), and many others.
 [Learn more about the data](/pecan/overview/methods-and-data).
@@ -13,7 +13,7 @@ Data can be explored via a series of data facets containing both retrospective a
 
 ## Home page
 
-The [PeCan home page](https://pecan.stjude.cloud/) showcases key components for each of the 4 data facets --Variants, Mutational Signatures, Expression, and Histology--, and the tool: PIE (Pediatric Cancer **P**athogenicity variant **I**nformation **E**xchange).
+The [PeCan home page](https://pecan.stjude.cloud/) showcases key components for each of the 4 data facets: Variants, Mutational Signatures, Expression, and Histology, and the tool: PIE (Pediatric Cancer **P**athogenicity variant **I**nformation **E**xchange).
 
 To get started (**Figure 1**), click our navigational membrane which navigates the user to our Diagnosis Search and data facets or search by a gene, variant or diagnosis in the search bar.
 
@@ -23,24 +23,25 @@ To get started (**Figure 1**), click our navigational membrane which navigates t
 A user can become familiar by reading the key components that are offered in the PeCan Knowledge Base.
 Additionally, a user can navigate by using our navigational membrane or begin searching a diagnosis, gene, or variant of interest.
 
-## Diagnosis Search
+### Diagnosis Search
 
-PeCan's Subtype Tree and Sunburst provide a navigable hierarchy of pediatric cancer diagnoses where all samples have been mapped to the CC4K framework.
+PeCan's Subtype Tree and Subtype Search provide a navigable hierarchy of pediatric cancer diagnoses where all samples have been mapped to the CC4K framework.
 These tools allow users to explore the full diagnosis classification structure used across St. Jude Cloud data, from broad categories down to individual pediatric cancer subtypes.
-For both the Tree and Sunburst, diagnoses are organized under three root categories: 1) HM — Hematopoietic Malignancies, 2) BT — Brain Tumor, and 3) ST — Solid Tumor.
+For both the Tree and Search, diagnoses are organized under three root categories: 1) HM — Hematopoietic Malignancies, 2) BT — Brain Tumor, and 3) ST — Solid Tumor.
 PeCan metadata export is also available via the download all metadata option from both views.
 
-### Sunburst
+### Subtype Search
 
-The sunburst plot provides an at-a-glance distribution and hierarchy of pediatric cancer diagnoses, with all PeCan samples mapped to the CC4K framework (Figure 2).
+The sunburst plot in the Subtype Search provides an at-a-glance distribution and hierarchy of pediatric cancer diagnoses, with all PeCan samples mapped to the CC4K framework (Figure 2).
 The plot updates as a user selects a diagnosis or subtype within the sunburst.
 Users are encouraged to navigate via a subtype-centric experience by selecting a subtype and then navigating to each data facet for the available data.
-This will enable custom interface views per data facet based on the sunburst selection. Alternatively, a user can explore all of the available data within a data facet by clicking directly on the icon from the side navigation.
+This will enable custom interface views per data facet based on the selection.
+Alternatively, a user can explore all of the available data within a data facet by clicking directly on the icon from the side navigation.
 
-![PeCan Sunburst](/img/pecan/overview/getting-started/diagnosis_search_sidenav.png)
+![PeCan Subtype Search](/img/pecan/overview/getting-started/diagnosis_search_sidenav.png)
 
-**Figure 2: Diagnosis Search Interface and Facet Navigation**
-A user is able to filter by diagnoses and/or subtype by selecting the interactive sunburst or by navigating directly into a data facet for the available data by using the side navigation.
+**Figure 2: Subtype Search Interface and Facet Navigation**
+A user is able to filter by diagnoses and/or subtype by selecting the interactive subtype search or by navigating directly into a data facet for the available data by using the side navigation.
 
 ### Subtype Tree
 

content/4.pecan/1.overview/2.methods-and-data.md

@@ -4,7 +4,7 @@ navigation:
   title: Methods and Data
 ---
 
-The PeCan Knowledge Base consists of curated pediatric cancer genomics data, including variants, mutational signatures, gene expression data, and histological slide images from ~9000 hematological, CNS, and non-CNS solid tumor samples.
+The PeCan Knowledge Base consists of curated pediatric cancer genomics data, including variants, mutational signatures, gene expression data, and histological slide images from ~12,000 hematological, CNS, and non-CNS solid tumor samples.
 
 ## Variants
 

content/4.pecan/1.overview/4.faq.md

@@ -63,12 +63,13 @@ See our [Data Availability](/pecan/overview/methods-and-data) page for more deta
 
 ## Can I build cohorts?
 
-This feature will be implemented in the future.
-However, a user can currently lasso samples in the Expression facet, gather a list of samples from the table view in Mutational Signatures, and/or populate data tables from ProteinPaint and GenomePaint.
+Yes!
+Users can now explore PeCan's data by creating custom cohorts of samples to stratify and analyze in the browser.
+Cohort building features are currently in an initial release phase with some limitations while we continue to build out the full functionality throughout the application.
 
 ## What features are coming next?
 
 St. Jude Cloud is working with the COMET team to develop the Epigenetic Data Facet that will comprise of Methylation data.
-Additionally, we are working on cohort building and sample pages.
+
 We would love to hear your feedback and any ideas you may have for future feature developments.
 If you have a feature request, please email [support@stjude.cloud](mailto:support@stjude.cloud).

content/4.pecan/2.cohort-building/1.cohort-building.md

@@ -0,0 +1,107 @@
+---
+title: Cohort Building
+navigation:
+  title: Create Custom Cohorts
+---
+Cohort features in PeCan allow users to dynamically build and stratify cohorts of samples, then explore their data across OncoPrint, Histology, and Expression.
+
+## Getting Started
+
+To begin creating and exploring cohorts, start by logging in to PeCan.
+If you don't have a St. Jude Cloud account, you can find the account creation steps in our documentation. [Creating a St. Jude Cloud Account](https://docs.stjude.cloud/genomics-platform/getting-started/accounts-and-billing#creating-a-st-jude-cloud-account)
+
+### Creating a new cohort
+
+Once you are logged in, you can start creating your own custom cohorts through the Subtype Search, Subtype Tree, the Cohorts page, or from one of the following areas of PeCan: OncoPrint, Histology, or Expression.
+
+Select your samples of interest, then select "Add to Cohort."
+The "Add to Cohort" button is available in several locations throughout the app.
+If you would like to explore all samples in PeCan, use the Cohorts page to view all samples.
+You can easily apply filters and create cohorts from this view as well.
+After selecting "Add to Cohort," you'll be prompted to add a cohort name and an optional description.
+
+> **Note:** You can also add samples to an existing cohort at this step by selecting an existing cohort from the modal.
+>Review your samples in the confirmation modal, and deselect any samples you'd like to exclude before submitting.
+
+![Creating a Cohort](/img/pecan/cohort-building/creating-cohort-tree.png)
+
+**Figure 1: Creating a Cohort from Subtype Tree.**
+Selecting a group of samples from the subtype tree is an easy way to create a cohort containing all samples of a particular subtype.
+
+## Viewing a Cohort
+
+### Lens
+
+To view or compare cohorts in PeCan's data facets, use the Cohort Lens to make your selection.
+The primary lens defaults to All PeCan Samples; select from the lens menu to view one of your custom cohorts instead.
+To compare against another cohort's samples, select the Compare option and choose your secondary lens cohort.
+
+![Cohort Lens](/img/pecan/cohort-building/lens-cohort.png)
+
+**Figure 2: Cohort Lens.**
+Select a cohort from the lens menu to view the cohort's samples in cohort supported data facets.
+
+### Cohort Summary Page
+
+To view all your cohorts and their associated metadata in one place, navigate to the Cohort page using the left-side navigation.
+From there, select one of your existing cohorts to review its samples and their associated metadata.
+
+From the Cohort page, you can also create new cohorts from the All Samples dataset or edit your custom cohorts by filtering to remove samples or by copying samples into another cohort.
+
+![Cohort Summary Page](/img/pecan/cohort-building/cohort-summary.png)
+**Figure 3: Cohort Summary Page**
+The cohort summary page provides an easy way for you to view all of your cohorts and their associated data in one place. You can add and remove samples, update a cohort's name and description, and export cohort data from this view.
+
+---
+
+## Cohort Views in PeCan's Data Facets
+
+To view and compare your cohorts, make your selections in the lens, then navigate to OncoPrint (Variants > OncoPrint), Expression, or Histology to view the samples in the selected cohort(s).
+
+### OncoPrint
+
+View an OncoPrint visualization scoped to the samples in your custom cohort.
+Select another cohort in the lens to compare mutations across the two sets of samples.
+
+:callout[**Note:** Set the filter to the root type you'd like to view in order to render the plot.]{icon="i-heroicons-document-text-solid" color="blue"}
+
+### Expression
+
+Explore gene expression across custom cohorts using the t-SNE or Gene Expression plots.
+
+**t-SNE**  Select the cohort(s) you'd like to view.
+The t-SNE will scope to your cohorts' samples and differentiate them by shape; any sample belonging to both cohorts is represented as a diamond.
+Select the "Color by Cohort" toggle to adjust the view.
+The header shows the number of samples in view, and the number of samples off-plot — update the subtype root filter or select the quick link in the header to bring off-plot samples into view.
+
+![Comparison View tSNE](/img/pecan/cohort-building/tsne-cohort.png)
+**Figure 5: Comparing two cohorts in PeCan's Expression tSNE**
+
+**Gene Expression** Select the cohort(s) you'd like to view and one or more genes.
+The violin plots will scope to your cohorts' samples.
+To see more granular plots by subtype, select the subtypes of interest in the subtype filter.
+Toggle data points on or off to view individual sample values and metadata.
+
+![Comparison View Expression](/img/pecan/cohort-building/expression-cohort.png)
+**Figure 6: Comparing two cohorts in Gene Expression**
+
+### Histology
+
+Select the cohort(s) you'd like to view.
+The slide gallery will update to show samples within your cohorts.
+A cohort badge icon displays on each slide thumbnail to indicate which cohort it belongs to.
+
+![Cohort View Histology](/img/pecan/cohort-building/histology-cohort.png)
+**Figure 7: Histology Cohort View**
+
+---
+
+Don't see your cohort samples?
+Try clearing the page filters from the left-side filter panel, this resolves the issue in most cases.
+
+---
+
+This is the first release of a broader set of cohort-building features on St. Jude Cloud.
+We plan to continue expanding cohort support across the application, including St. Jude Cloud curated cohorts, cohort views in Variant Prevalence and Mutational Signatures, and more.
+
+Please share any feedback or questions with <support@stjude.cloud>.

content/4.pecan/2.cohort-building/_dir.yml

@@ -0,0 +1 @@
+title: Cohort Building

content/4.pecan/2.data-facets/5.use-cases.md → content/4.pecan/3.data-facets/5.use-cases.md

@@ -40,13 +40,13 @@ The following are common scenarios a user might want to achieve in PeCan.
        Select one to view the variant page.
      - Click a variant of interest on the lollipop and click the P/LP button to view the variant page.
        Read more about [Variants:Variant Details here](/pecan/data-facets/variants).
-10. A user can filter on the sunburst and then select the Variants data facet which will render the appropriate oncoprint.
-    A user can navigate to the Variants data facet without filtering from the sunburst and then use the Variants dropdown filter accordingly.
+10. A user can filter on the subtype search and then select the Variants data facet which will render the appropriate oncoprint.
+    A user can navigate to the Variants data facet without filtering from the subtype search and then use the Variants dropdown filter accordingly.
     **Read more about [Variants:Oncoprint here](/pecan/data-facets/variants).**
-11. A user can filter on the sunburst and then select the Variants data facet and toggle to Variant Prevalence which will render the appropriate visualization.
-    A user can navigate to the Variants data facet without filtering from the sunburst and then use the Variants dropdown filter accordingly.
+11. A user can filter on the subtype search and then select the Variants data facet and toggle to Variant Prevalence which will render the appropriate visualization.
+    A user can navigate to the Variants data facet without filtering from the subtype search and then use the Variants dropdown filter accordingly.
     **Read more about [Variants:Variant Prevalence here](/pecan/data-facets/variants).**
-12. A user can prefilter by the sunburst or navigate directly into the data facet.
+12. A user can prefilter by the subtype search, subtype tree or navigate directly into the data facet.
     Here, a user can select samples by subtype (y-axis), mutational signature (x-axis), or subtype with a specific mutational signature (cell).
     The selection will populate a sample summary page.
     **Read more about [Mutational Signatures here](/pecan/data-facets/mutational-signatures).**