3400f3754a96dc0bf52ee14a4839fb0abac26d20 gperez2 Mon May 19 09:12:32 2025 -0700 Updating location for images and the interactive tutorial url, refs #34938 diff --git docs/gatewayTutorial.md docs/gatewayTutorial.md index c71df758523..f2286aaa21d 100644 --- docs/gatewayTutorial.md +++ docs/gatewayTutorial.md @@ -1,297 +1,297 @@ % UCSC Genome Browser Gateway tutorial The [UCSC Genome Browser Gateway](../cgi-bin/hgGateway) page is a tool for finding and accessing genome assemblies. It features two search boxes: one for selecting an assembly and another for specifying a genomic position. This tutorial will guide you through various features of the Gateway page, including: - Finding a genome browser using the Popular Species option - Exploring the UCSC Species Tree - Searching for an assembly using different identifiers - Viewing sequences - Using search terms to jump to a specific genome location ## Learning materials

Gateway Page Screenshot

A Gateway page screenshot highlighting its main features and functionalities.

Guided Walkthrough

A guided walkthrough that explains how to find a genome, explore the Species Tree, search with assembly identifiers, view sequences, and use search terms to jump to genome locations.

Interactive Tutorial

An interactive tutorial that covers the basic Browser introduction on the Gateway page.

- +

## Gateway page screenshot ```image -src=../images/gatewayPageAnnotated.jpg +src=../images/tutorialImages/gatewayPageAnnotated.jpg width=90% ``` ## Guided Walkthrough ### Using the Popular Species Option
```image -src=../images/popular_species.png +src=../images/tutorialImages/popularSpecies.png width=70% ```
The **Popular Species** section lists commonly used model organisms, allowing for quick selection of their genome browsers. Clicking on a species will display the default assembly version for that organism.
---
NCBI defines an assembly or assembled genome as the set of chromosomes, unlocalized and unplaced (sometimes called "random") and alternate sequences used to represent an organism's genome. The NCBI Assembly Data Model defines assemblies as comprising one or more assembly units. The different assemblies often differ in their sequence content, with newer versions using newer technologies to fill in gaps, correct errors, and refine genome structure. Some regions of an older assembly may shift or change, while sequencing errors from previous data may be corrected in an updated version. For example, the updated reference genome hg38 contains many improvements over the hg19 assembly, some of which may include contigs that were merged together or placed where there were previously sequence gaps. To change the assembly version, click the **Assembly** option under **Find Position**.
```image -src=../images/assembly_version.png +src=../images/tutorialImages/assemblyVersion.png width=90% ```
--- ### Using the search box
The search box allows users to find genome assemblies by entering different types of queries: Searching by **species name**: Ovis aries Searching by **common name**: dog Searching by **GC accession number**: GCF_016699485.2
```image -src=../images/Search_GCF_016699485_2.gif +src=../images/tutorialImages/searchByGCFid.gif width=100% ```
--- ### Exploring the UCSC Species Tree
```image -src=../images/species_tree.png +src=../images/tutorialImages/speciesTree.png width=60% ```
The **Species Tree** option displays a phylogenetic tree that can be navigated using scrolling or by clicking different parts of the tree. Hovering over a branch will reveal the lineage branch name. **Note**: The Species Tree does not include all available Genome Browser assemblies. The process of adding Genome Browsers has been streamlined, enabling rapid releases but omitting certain previous features, such as inclusion in the Species Tree. To find a specific assembly, use the assembly search box.
--- ### Requesting an Assembly
If a desired assembly is not listed, you can request it by clicking **"Unable to find a genome? Send us a request**". This will direct you to the **Genome Assembly Search and Request page.** Steps to request an assembly: 1. Enter the **species name, common name, or GC accession number** of the assembly. 2. Click the **request button**. 3. Fill out the required information on the submission page.
```image -src=../images/assembly_request.png +src=../images/tutorialImages/assemblyRequest.png width=130% ``` ```image -src=../images/request_page.png +src=../images/tutorialImages/requestPage.png width=40% ```
--- ### Using View sequences
```image -src=../images/view_sequence.png +src=../images/tutorialImages/viewSequence.png width=30% ``` ```image -src=../images/sequences_list.png +src=../images/tutorialImages/sequencesList.png width=70% ```
Clicking the **View sequences** link directs users to the **Assembly Browser Sequences** page. This page displays information about chromosomes, sequences, and contigs for the selected assembly. The third column displays alias sequence names, while subsequent columns show alternate naming schemes. These include: - **assembly** - Names from NCBI's assembly_report.txt file. - **genbank** - INSDC names. - **refseq** - Names from RefSeq annotations.
--- ### Assembly details on the Gateway Page
The **Gateway Page** provides various details about an assembly, including: - UCSC Genome Browser assembly ID - Common name - Taxonomic name - Sequencing/Assembly provider ID - Assembly date - Assembly type - Assembly level - Biosample - Assembly accession - NCBI Genome ID - NCBI Assembly ID - BioProject ID The Gateway page also offers **download links** for data files related to the genome assembly.
```image -src=../images/assembly_details.png +src=../images/tutorialImages/assemblyDetails.png width=90% ```
----
### Jumping to a Specific Genome Location
```image -src=../images/Search_box.png +src=../images/tutorialImages/searchBox.png width=70% ```
Once an assembly is selected, users can search for specific genome locations using: - Genome positions (e.g., chr1:1000000-2000000) - Gene names (e.g., BRCA1) For more details on valid position queries, visit the [Querying the Genome Browser](/goldenPath/help/query.html) page.