f4c970b7a77aab27b11515a03c719731ff2b693e
jnavarr5
Wed Nov 6 10:49:33 2024 -0800
initial commit of the assembly hub guidelines. Copy of the public hubs guidelines with no edits, refs #34740
diff --git src/hg/htdocs/goldenPath/help/assemblyHubGuidelines.html src/hg/htdocs/goldenPath/help/assemblyHubGuidelines.html
new file mode 100755
index 0000000..58a4879
--- /dev/null
+++ src/hg/htdocs/goldenPath/help/assemblyHubGuidelines.html
@@ -0,0 +1,289 @@
+
+
+
+
+
+
+
+Public Hub Guidelines
+
+The Genome Browser provides links to a collection of public hubs that have been registered
+with UCSC and are available to view on the Public Hubs page.
+Here are guidelines for those who are trying to make a hub a UCSC public hub. If you have created a
+hub that meets the requirements and is of general interest to the research community, please
+contact us at
+
+genome-www@soe.ucsc.edu
+ to have it added to the list.
+
+
As a reference for interpreting trackDb.txt settings, use the Hub Track Database Definition glossary. For information on using the Track
+Hub features, refer to the Genome Browser Track Hub User Guide.
+See also the Basic Hub Quick Start Guide, Quick Start Guide to Organizing Track Hubs into
+Groupings, Track hub settings blog post, Quick Start Guide to Assembly Hubs and Quick Start Guide to Searchable Track Hubs.
+
+
+Contents
+
+
+
+
+
+
+Required Guidelines
+The following guidelines must be met before your hub will be added to our public list:
+Required for both track and assembly hubs:
+
+ - You MUST have a description page for every configuration page (composite, superTrack or stand
+ alone track). Note that multiple tracks and/or composites can use the same description page
+ with the "html" setting. You can
+ find more information on creating track description pages in the
+ recommendations section below.
+
+ - All of your description pages MUST have a contact email address prominently displayed.
+
+ - At least one track should have a visibility set to display (in full, pack,
+ squish, or dense), and try to have no more than 10 tracks enabled by default upon first
+ connecting your hub.
+
+ - Have a descriptionUrl html page specified in your hub.txt. This should be a URL to a description
+ page for your entire hub, often public hubs will link to a full-text paper or to their
+ laboratory webpage that describes the research presented in the hub. These links are presented
+ on the Public Hubs page as a hyperlink on the longLabel presented in the hub.txt, while the
+ shortLabel is a hyperlink to the hub.txt location.
+
+
+
+Required for only assembly hubs:
+
+ - Add a gateway page for each assembly by having a htmlPath line for each genome not already
+ hosted by UCSC in the genomes.txt.
+
+ - The following settings should properly be set in your genomes.txt (The last 3 settings will make
+ it easier to find assembly hub species in hgGateway by UI search):
+
+
+ - defaultPos
+ - scientificName
+ - organism
+ - description
+
+
+
+
+Recommended Guidelines
+These guidelines in the following sections are recommended to improve user experience, but are
+ not required to be implemented before the hub is added to our list of Public Hubs.
+
+
+Note on stability
+
+Keep in mind that users may start to rely on your track hub for their work. If the track hub web
+server is down or the URL changes, users of the track hub will have no access to the data. Users may
+also have stable session links in manuscripts that include the track hub data and the sessions
+could all stop working. We check public track hubs periodically and send an email after a 24-hour
+downtime. We will remove track hubs if they are offline for several days. Contact us
+(genome-www@soe.ucsc.edu) if there is a change such as moving webservers of the track hub.
+
+
+
+Sudden changes can also impact users where large changes to the track hub can change the analysis
+of users such as removing tracks or changing options. In these cases, keeping a previous version of
+the tracks and making them in a different track group with suffixes such as "V1",
+"(previous versions)" or hint in the track long labels. Labeling tracks with informative
+labels will help users. You can also add a "dataVersion" trackDb statement to indicate to
+users what version of the data is being used.
+
+
+Track organization recommendations
+
+Related tracks can be grouped in a few different ways, namely superTracks, multiWigs, and composites. If your hub includes a large number of tracks, the grouping of
+tracks may be necessary. This will prevent your hub's track group from being an overwhelming mess
+of individual tracks and can make user configuration of your tracks easier.
+
+Composite tracks
+
+Related tracks of the same data type (e.g. a set of related bigBed tracks) should be combined into
+composites where
+appropriate.
+
+ - Have multi-view only when there is
+ more than one view. Views ideally give alternate access to the same data (e.g. signals and
+ called peaks). Keep in mind that the value of views is that they allow for more than one
+ data/configuration type (e.g. bigBed and bigWig) in a single composite. All subtracks of a
+ view must have the same data type. Likewise, all subtracks of a non-multi-view composite must
+ be the same type.
+ - Recommendations for using dimensions with your composite tracks:
+
+ - There should be no
+ dimensions with a single entry (do not have only one cell line represented in dimX=cell),
+ unless data growth is expected to fill in additional entries.
+ - Using only one dimension: preferably use dimX (e.g. dimensions dimX=cell). This saves vertical
+ User Interface space, but is not always the best choice.
+ - Using two dimensions: use dimX and dimY (e.g. dimensions dimX=cell dimY=mark)
+ - Using more than two: use dimX, dimY on the most important dimensions. Then use dimA,B,C as
+ needed on lesser dimensions. (e.g. dimensions dimX=cell dimY=mark dimA=donor_id)
+ - The A,B,C dimensions should probably use filterComposite (e.g. filterComposite dimA)
+ - Each dimension and views should be represented in sortOrder, ideally in order of dimX, dimY,
+ dimA,B,C, view (e.g. sortOrder cell_type=+ mark=+ donor_id=+ view=+).
+
- Tags of subGroup/dimension should be short and sweet with no special chars. Also labels can
+ have HTML codes embedded (e.g. NOT CPG_methylation_%=CPG_methylation_% RATHER
+ mpct=CPG_methylation_&_#37)
+ - Never represent the same subgroup in both view and as a dimension (e.g. NOT dimensions
+ dimX=view). A subgroup should never be in two dimensions (e.g. NOT dimensions
+ dimX=cell dimY=mark dimA=cell). The composite will appear to function but multiple ways of
+ selecting the same thing will create a confusing and inconsistent user interface.
+
+
+
+Super tracks
+
+Extremely large hubs may use superTracks as well to achieve a meaningful hierarchy. Super tracks
+can be used to group together any type of related tracks; for example, you could combine a multiWig,
+a composite, and a bigBed track together into a single superTrack.
+
+Track display recommendations
+
+ - Avoid setting a composite track and all of its subtracks to the same visibility. When you have
+ composite tracks that are hidden by default, it is best to still designate some subtracks to
+ display when the composite track is turned on (visibility dense, versus the default of hide).
+ This provides an example of your track data to users who turn on your composite track. If no
+ subtracks are turned on by default, a user who changes your composite track visibility to
+ "show" won't see anything.
+ - The shortLabel text should be under 20 characters, or meaningful information may be cut off
+ from display when tracks are set to "dense" visibility.
+
+
+Track description page recommendations
+
+ - The description page should preferably contain UCSC's standard track description, Display
+ Conventions and Configuration, Methods, Credits, and References. More information can be
+ found on the template page.
+ - Your track description pages should provide meaningful documentation for your tracks.
+
+ - If you are creating a hub based on a paper, use the paper's abstract as a starting point for
+ your track's description section
+ - The Methods section expand upon the overview of the Description section and provide more
+ details about how the data for the track was produced
+ - You should assume a broad audience of students and researchers will use your hubs. You should
+ spell out common acronyms for those who may be new to genomics. For example, you might write
+ out a term and its acronym as follows "Fluorescent in situ hybridization (FISH)" which spells
+ it out and then provides the acronym that you can use throughout the rest of your description
+ page.
+
+ - It might be a good idea to include a "Data Access" section on your track description page
+ which describes how to access the data in your hub and where to download the raw data for the
+ tracks in your hub.
+
+
+
+Public Hub Examples
+
+Many of the public hubs in
+the Genome Browser provide excellent examples or templates for creating your own hub. As a
+reference for interpreting trackDb.txt lines used in these example hubs, please refer to the Hub
+Track Database Definition glossary.
+
+Some Hub Track Database Definition settings like filters have additional help documentation. Also note that if
+you are only displaying one genome you can use the useOneFile on setting.
+
+Example Track Hubs
+Example 1
+The Principal Splice Isoforms APPRIS hub provides a good example of basic hub that
+includes a few different annotation tracks. Each track includes its own description page and is
+colored in such a way that distinguishes it from the other tracks in the hub and native track in
+the UCSC Genome Browser.
+
+Here are some links to their configuration files and some description pages:
+
+
+Example 2
+The Roadmap Epigenomics Integrative Analysis Hub provides a great example of how
+you might use organize your hub if you have thousands of different tracks. The hub uses composites
+with dimensions to organize thousands of different tracks across a number of cell lines and uses
+supertracks to group these tracks even further.
+
+Here are some links to their configuration files and some description pages:
+
+
+Example Assembly Hub
+The C elegans isolates hub provides an excellent example of what your assembly hub could
+look like. The hub creators provide a detailed description page for each assembly, many different annotations
+tracks each with their own description page, and clearly defined track groups with those related
+tracks grouped together.
+
+Here are some links to their configuration files and some description pages:
+
+
+