532489da40462ffa8bc5745555fbd837fb572aeb gperez2 Tue Apr 29 17:40:46 2025 -0700 Adding the gateway tutorial markdown and makefile, refs #34938 diff --git docs/gatewayTutorial.md docs/gatewayTutorial.md new file mode 100644 index 00000000000..c71df758523 --- /dev/null +++ docs/gatewayTutorial.md @@ -0,0 +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 +width=90% +``` + +## Guided Walkthrough + +### Using the Popular Species Option + +
+
+ +```image +src=../images/popular_species.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 +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 +width=100% +``` + + +
+
+--- + +### Exploring the UCSC Species Tree + +
+
+ +```image +src=../images/species_tree.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 +width=130% +``` + +```image +src=../images/request_page.png +width=40% +``` + +
+
+--- + +### Using View sequences + +
+
+ +```image +src=../images/view_sequence.png +width=30% +``` + +```image +src=../images/sequences_list.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 +width=90% +``` +
+
+ +---- + +
+
+
+
+ +### Jumping to a Specific Genome Location + +
+
+ +```image +src=../images/Search_box.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. + +
+
+