migrating content from /using-gudmap/

docs/_docs/use_cases/gene-expression-multiple-regions.md

@@ -0,0 +1,55 @@
+---
+title: Which genes are expressed in multiple regions?
+permalink: /docs/gene-expression-multiple-regions/
+---
+
+Using the [Boolean Anatomy Search](../boolean-anatomy-search/), you can choose multiple anatomical regions and then query for expression of one or more genes. In this example, we'll be using the Boolean Anatomy Search to answer the question:
+
+> **Which genes are expressed in the renal medullary interstitium, outer medullary interstitium and inner medullary interstitium?**
+
+**On this page:**
+- [Step 1: Go to the Boolean Anatomy Search app](#step-1-go-to-the-boolean-anatomy-search-app)
+- [Step 2: Set up a Boolean query](#step-2-set-up-a-boolean-query)
+- [Step 3: Search Specimen records](#step-3-search-specimen-records)
+- [Video demonstration](#video-demonstration)
+
+## Step 1: Go to the Boolean Anatomy Search app
+
+In the top-level menu choose _BROWSE DATA_ > _Anatomy_ > _Boolean Anatomy Search_.
+
+Which opens the Boolean Anatomy Search app:
+
+[![screenshot of the Boolean Anatomy Search app](boolean-search-app.png){:.screenshot}](boolean-search-app.png)
+
+## Step 2: Set up a Boolean query
+
+You can find the [full documentation page here](../../boolean-anatomy-search/), but on this page we'll be demonstrating a particular query.
+
+We will set up three different conditions - each for one of the anatomical regions where we want to know if expression strength is present: the renal medullary interstitium, outer medullary interstitium and inner medullary interstitium.
+
+* In the left hand section, in the search field above the tree, type `renal medullary interstitium`. When you see the term appear in the tree, click the term to populate the condition box on the right side.
+
+  Make sure the "Strength" field is set to “present”
+
+* Click the plus (+) sign to add another condition.
+
+* Repeat this step with the terms `outer medullary interstitium` and `inner medullary interstitium`. You should now have three condition on the right side of the screen:
+
+**Note:** If you see no results for an anatomical region, make sure you are using the appropriate developmental stage in the dropdown box at the top of the anatomy tree.
+
+[![screenshot of the boolean conditions](boolean-conditions.png){:.screenshot}](boolean-conditions.png)
+
+
+## Step 3: Search Specimen records
+
+Now click the "Search Specimen" button to search all gene records that show expression present in those regions.
+
+[![screenshot of the specimen search results from the query](boolean-search-specimen-results.png){:.screenshot}](boolean-search-specimen-results.png)
+
+In the search results, you’ll see in the _Genes_ facet in the left sidebar the following genes, which indicate we have data that shows the expression of these genes in all three regions: _Crym, Wnt4, Ptch1_.
+
+## Video demonstration
+
+Here is a video demonstrating the above steps:
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/FCYddOXGhGk" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

docs/_docs/using_atlas/Boolean-Anatomy-Search.md

@@ -0,0 +1,102 @@
+---
+title: Boolean Anatomy Search
+permalink: /docs/boolean-anatomy-search/
+---
+
+Use the [*Boolean Anatomy Search* application](https://www.atlas-d2k.org/deriva-webapps/boolean-search/) to perform complex queries for **level of gene expression** based on **anatomical regions**. There are two ways to perform boolean search of scored specimen expression: using the graphical user interface (GUI) or entering a text search string.
+
+**On this page:**
+- [Getting to know the Boolean Anatomy Search app](#getting-to-know-the-boolean-anatomy-search-app)
+- [Using the graphical user interface (GUI)](#using-the-graphical-user-interface-gui)
+  - [Example of building a query with the GUI](#example-of-building-a-query-with-the-gui)
+- [Entering a search string](#entering-a-search-string)
+  - [Search syntax](#search-syntax)
+  - [Example search strings](#example-search-strings)
+- [Troubleshooting](#troubleshooting)
+
+## Getting to know the Boolean Anatomy Search app
+
+![Annotated view of the Boolean Anatomy Search app]({{ "/assets/img/boolean-anatomy-search-page.png" | relative_url }})
+
+|     |         |
+|---------- |-------------------|
+| ![First callout number in screenshot](/assets/img/callouts/callout-1.png)  | Tree view of anatomy terms that conform to the  [GUDMAP Ontology](/resources/ontology/). The dropdown button allows you to specify a [Theiler Age Stage](/help/theiler-stage-ref/) for the tree. The default is  *TS23 (15dpc)*. |
+| ![2nd callout number in screenshot](/assets/img/callouts/callout-2.png) | Text field that displays the query as a search string. |
+| ![First callout number in screenshot](/assets/img/callouts/callout-3.png) | Fields to add additional conditions to the query. |
+| ![First callout number in screenshot](/assets/img/callouts/callout-4.png) | The **Search Specimen** button opens a search results page of all GUDMAP [Specimen data](/chaise/recordset/#2/Gene_Expression:Specimen) that conforms to the query.|
+{: .callout }
+
+## Using the graphical user interface (GUI)
+
+The application can visually represent queries as rows of search filters for each condition.
+
+To build a query:
+1. Search and select an anatomical term for your first condition from the tree view in left panel. This will fill in the **Anatomical Source** field. **Note:** If you see no results for an anatomical region, make sure you are using the appropriate developmental stage in the dropdown box at the top of the anatomy tree.
+2. Select appropriate values for the dropdown fields:
+  - **Strength**: Choose from *Not detected*, *Present*, or *Uncertain* (required).
+  - **Stages**: Indicate a range of developmental stages (using [Theiler Stages](/help/theiler-stage-ref/)) (required).
+  - **With Pattern**: Choose from patterns of expression such as *graded*, *homogenous*, *regional*, etc.
+  - **At location**: Choose from various locations such as *dorsal*, *lateral*, etc.
+3. To add more conditions, click the plus (+) symbol on the top right corner.
+4. When you have built your query, click on the **Search Specimen** button. If all the values are valid, the resulting Specimen search results page will open in a new tab. If the query contains any invalid values, they will be highlighted in the table.
+4. Use the **Save** button to store the query in a text file. You may copy the contents and paste them into the text field to perform the query again.
+
+### Example of building a query with the GUI
+
+Here is an example of building a query to find out which genes are expressed in the renal medullary interstitium, outer medullary interstitium and inner medullary interstitium in the adult mouse.
+
+* In the left hand section, above the search field is a dropdown list of different age stages. Click and select `TS28: Range P4-Adult`.
+
+* In the search field underneath, "renal medullary interstitium". When you see the term appear in the tree, click the term to populate the condition box on the right side. Make sure the "Strength" field is set to `present`.
+
+  This is your first condition.
+
+* Click the plus (+) sign to add another condition and search for the term "outer medullary interstitium" and click to add your second condition.
+
+* Click the plus (+) sign one more time to add a third condition. Search for “inner medullary interstitium” and select it.
+
+  You should now have three condition on the right side of the screen:
+
+* Now click the "Search Specimen" button to search all gene records that show expression present in those regions:
+
+* In the search results, you’ll see in the Genes facet in the left sidebar the following genes: Crym, Wnt4, Ptch1. Select those facets and the search results will display specimen records with expression data related to those genes.
+
+Here is a video demonstrating the above steps:
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/FCYddOXGhGk" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+## Entering a search string
+
+Alternatively, you can enter the entire query as a search string in the text field. You can then save this as a text file to download and save locally. Then at anytime you can copy the contents and paste them into the right-side text field to search again:
+
+1. Enter a query string consisting of one or more filters using the correct search syntax (see [Search syntax](#search-syntax) below).
+2. Click the **Validate** button to check the validity of all values before submitting the query. This would also populate the table with any filters that were added directly in the text field.
+3. When you have built your query, click on the **Search Specimen** button. If all the values are valid, the resulting Specimen search results page will open in a new tab. If the query contains any invalid values, they will be highlighted in the table.
+4. Use the **Save** button to store the query in a text file. You may copy the contents and paste them into the text field to perform the query again.
+
+### Search syntax
+
+Each filter should conform to the following syntax:
+```
+<strength>{in <anatomical source> <from stage>..<to stage> pt=<pattern> lc=<location>}
+```
+Multiple filters are combined using the keyword AND:
+
+- `<strength>` is one of the following symbols: `p` for present, `nd` for not detected, and `u` for uncertain.
+- `<anatomical source>` is the anatomical name (e.g. `gonad`) shown in the tree view.
+- `<from stage>` and `<to stage>` identify the search range of specimens. Specimens without stage information will not be included.
+- `<pattern>` should be one of the symbols shown in the drop-down menu under **Pattern** in the GUI.
+- `<location>` should be one of the symbols shown in the drop-down menu under **Location** in the GUI.
+
+### Example search strings
+
+- One filter - where expression is detected in the bladder from TS17 through TS28 in the dorsal region: `p{in "bladder" TS17..TS28 pt=regional lc=dorsal}`
+- Multiple filters - where expression is present in the artery and not detected in the arteriole from TS17 through TS28: `p{in "artery" TS17..TS28} AND nd{in "arteriole" TS17..TS28}`
+
+## Troubleshooting
+
+The following errors could occur when using the app:
+
+- Incorrect formatting of the query in the text field. Please refer to the examples above.
+- The Anatomical Source entered in the text field does not exist. This can be resolved by searching for the term in the tree view in the left pane, and use the exact term in the text field.
+- Invalid values of Strength, Developmental Stages, Pattern or Pattern location. These can be resolved by selecting the proper values from the respective dropdown fields for each row.

docs/_docs/using_atlas/Collections.md

@@ -0,0 +1,15 @@
+---
+title: Using Data Collections
+permalink: /docs/collections/
+---
+
+[Data collections](https://www.atlas-d2k.org/chaise/recordset/#2/Common:Collection) are a curated set of GUDMAP data collected into one easily citable and referenced location with a permanent identifier (DOI), usually for the purposes of:
+
+- A publication. A collection can consolidate all of the source data related to a paper - not just the low resolution images available within a paper. Readers can unambiguously obtain full quality, source data that was referenced in the paper, which translates to repeatable experiments.
+- A collaboration between multiple projects. A data collection can help ensure that all parties are working with the exact same data and protocols.
+
+To see our currently available collections, [click here](https://www.atlas-d2k.org/chaise/recordset/#2/Common:Collection).
+
+**If you are a GUDMAP project publishing a paper**, please:
+- [Create and reference a “Data Collection”](../create-citable-datasets/) for data included in your paper and any additional data you wish to be considered relevant to the published project.
+- Refer to [Citing GUDMAP](https://www.atlas-d2k.org/gudmap/citing-gudmap/) to learn how to add your data citation in the bibliography section, and how to cite your data collection in the manuscript.

docs/_docs/using_atlas/Filtering-Sidebar.md

@@ -0,0 +1,97 @@
+---
+title: Querying by Filtering Sidebar and Search Results
+permalink: /docs/filtering-sidebar/
+---
+
+**On this page:**
+- [Anatomy of a search page](#anatomy-of-a-search-page)
+- [Using the filtering sidebar](#using-the-filtering-sidebar)
+  - [Selecting filters](#selecting-filters)
+  - [Searching attributes within the sidebar](#searching-attributes-within-the-sidebar)
+  - [Expanding/collapsing filters](#expandingcollapsing-filters)
+  - [Clearing filters](#clearing-filters)
+- [Main search results](#main-search-results)
+  - [Searching across columns](#searching-across-columns)
+  - [Sorting columns](#sorting-columns)
+- [How text search works](#how-search-works-when-typing-free-text)
+
+## Anatomy of a search page
+
+![Screenshot of the landing page]({{ "/assets/img/search-page-example.png" | relative_url }})
+
+Above is a typical search results page. Common elements are:
+
+1. Filtering sidebar
+2. Filters (which display attributes chosen through the filtering sidebar)
+3. Search bar above the results for free text search.
+4. Search results based on filters.
+
+
+## Using the filtering sidebar
+
+The filtering sidebar allows you to narrow your search results by various data attributes and metadata - such as *Species* (mus musculus) and *Assay Type* (ISH) in the example above.
+
+Selecting and de-selecting attributes in any of the facets will filter the results to show only data with those attributes.
+
+![Zoomed in view of sidebar]({{ "/assets/img/facet-panel-search.png" | relative_url }})
+*Zoomed in view of sidebar*
+
+
+### Searching attributes within the sidebar
+
+A filter displays up to 10 attributes. When there's more than 10, there are a couple of options for finding the one you're looking for.
+
+#### **Search in the filter**
+
+Use the small search box within the filter to search across those attributes only.
+
+The following example shows a user looking through Specimen records who wants to find `proximal tubule` within the regions listed in the "Anatomy" filter.
+
+Note how suggested matches are displayed as the user types.
+
+![Animation of searching within Anatomy filter]({{ "/assets/img/proximal-tubule-filter-search.gif" | relative_url }})
+
+#### **Use the "Show more" window**
+
+Click the "Show More" link to pull up a modal window where you can browse through all attributes and their descriptions.
+
+In the following example, the user searches just the term `tubercle` to see what's available.
+
+After reading the descriptions, they select both `genital tubercle of male` and `genital tubercle of female` and click *Submit* to see available specimen data for both.
+
+![Animation of using the Show More window]({{ "/assets/img/tubercle-showmore-search.gif" | relative_url }})
+
+Tips:
+- Selecting `All on page` will select all checkboxes that appear in the window.
+- Clicking `None on page` will de-select all checkboxes in the window.
+- You may also use the search field to narrow down your choices by typing in free text.
+
+### Expanding/collapsing filters
+
+If the filtering sidebar is long, you can manage which filters are shown by clicking the down and up arrow, as shown below, to expand and collapse the filters:
+
+![Animation of expanding and collapsing filters]({{ "/assets/img/expand-collapse-filters.gif" | relative_url }})
+
+### Clearing filters
+
+If you want to clear a filter, click the `X` icon next to the filter's name.
+
+You can also click "Clear all filters" to remove them all.
+
+![Animation of clearing filters]({{ "/assets/img/clear-filters.gif" | relative_url }})
+
+## Using the main search results
+The current search results are displayed in the main body of the page. You may also browse and refine the results from this area.
+
+### Searching across columns
+Note the larger search field above the search results. Enter a keyword or key phrase to search across text in all of the visible columns.
+
+![Animation of using free text search]({{ "/assets/img/searching-results-free-text.gif" | relative_url }})
+
+### Sorting columns
+Some columns are configured to be sort-able. To identify which columns you can sort, look for the double arrow icon and click to toggle the column sort between ascending and descending.
+
+![Animation of sorting columns]({{ "/assets/img/column-sort.png" | relative_url }})
+
+### How text search works
+The search automatically assumes a ‘wildcard’ at the end of the search string; therefore, typing in `uro` in any search field will search for words/symbols beginning with `uro`, e.g. `urothelium`, `urogenital`, `uroplakin`, etc.