720de849b76a5a3d95e66050d5a2c2683d60351a hiram Fri Jul 5 12:58:50 2024 -0700 adding list/genarkGenomes endpoint and examples refs #34045 diff --git src/hg/htdocs/goldenPath/help/api.html src/hg/htdocs/goldenPath/help/api.html index a8cf210..168ea69 100755 --- src/hg/htdocs/goldenPath/help/api.html +++ src/hg/htdocs/goldenPath/help/api.html @@ -102,64 +102,64 @@ </p> <!-- ========== Endpoint functions ======================= --> <a id="Endpoint"></a> <h2>Endpoint functions to return data</h2> <p> The URL <b>https://api.genome.ucsc.edu/</b> is used to access the endpoint functions. For example: <pre> curl -L 'https://api.genome.ucsc.edu/list/ucscGenomes' </pre> </p> <p> <ul> <li><b>/list/publicHubs</b> - list public hubs</li> -<li><b>/list/ucscGenomes</b> - list UCSC Genome Browser database genomes</li> +<li><b>/list/ucscGenomes</b> - list UCSC Genome Browser database genomes from database host</li> +<li><b>/list/genarkGenomes</b> - list UCSC Genome Browser database genomes from assembly hub host</li> <li><b>/list/hubGenomes</b> - list genomes from specified hub</li> <li><b>/list/files</b> - list download files available for specified genome</li> <li><b>/list/tracks</b> - list data tracks available in specified hub or database genome (see also: <a href='trackDb/trackDbHub.html' target=_blank>track definition help</a>)</li> <li><b>/list/chromosomes</b> - list chromosomes from a data track in specified hub or database <li><b>/list/schema</b> - list the schema for a data track in specified hub or database genome</li> <li><b>/getData/sequence</b> - return sequence from specified hub or database genome</li> <li><b>/getData/track</b> - return data from specified track in hub or database genome</li> <li><b>/search</b> - return search matches within a UCSC Genome Browser genome assembly</li> </ul> </p> <!-- ========== Parameters to endpoint functions ======================= --> <a id="Parameters"></a> <h2>Parameters to endpoint functions</h2> <p> <ul> <li>hubUrl=<url> - specify track hub or assembly hub URL</li> -<li>genome=<name> - specify genome assembly in UCSC Genome Browser or track/assembly hub</li> +<li>genome=<name> - specify genome assembly in UCSC Genome Browser or track/assembly hub. Use with with /list/genarkGenomes to test for existence.</li> <li>track=<trackName> - specify data track in track/assembly hub or UCSC database genome assembly</li> <li>chrom=<chrN> - specify chromosome name for sequence or track data</li> <li>start=<123> - specify start coordinate (0 relative) for data from track or sequence retrieval (start and end required together). See also: <a href='https://genome-blog.gi.ucsc.edu/blog/the-ucsc-genome-browser-coordinate-counting-systems/' target=_blank>UCSC browser coordinate counting systems</a></li> <li>end=<456> - specify end coordinate (1 relative) for data from track or sequence retrieval (start and end required together). See also: <a href='https://genome-blog.gi.ucsc.edu/blog/the-ucsc-genome-browser-coordinate-counting-systems/' target=_blank>UCSC browser coordinate counting systems</a></li> -<li>revComp=1 - on <em>/getData/sequence</em> function, return reverse complement of sequence data - together)</li> +<li>revComp=1 - on <em>/getData/sequence</em> function, return reverse complement of sequence data</li> <li>maxItemsOutput=1000 - limit number of items to output, default: 1,000, maximum limit: 1,000,000 (use <em>-1</em> to get maximum output)</li> <li>trackLeavesOnly=1 - on <em>/list/tracks</em> function, only show tracks, do not show composite container information</li> <li>jsonOutputArrays=1 - on <em>/getData/track</em> function, JSON format is array type for each item of data, instead of the default object type</li> <li>format=text - on <em>/list/files</em> function, return plain text listing of download files instead of JSON format output (which includes more meta-data information). Text output contains less meta-data in comment lines prefixed by the '#' hash character.</li> <li>search=<term>&genome=<name> - on <em>/search</em> function, specify term to be search within a UCSC Genome Browser genome assembly</li> <li>categories=helpDocs - on <em>/search?search=<term>&genome=<name></em> function, restrict the search within the UCSC Genome Browser help documentation</li> <li>categories=publicHubs - on <em>/search?search=<term>&genome=<name></em> function, restrict the search within the UCSC Genome Browser Public Hubs</li> <li>categories=trackDb - on <em>/search?search=<term>&genome=<name></em> function, restrict the search @@ -171,79 +171,88 @@ question mark <b>?</b>, and multiple parameters are separated with the semi-colon <b>;</b>. For example: <pre> https://api.genome.ucsc.edu/getData/sequence?genome=hg38;chrom=chrM </pre> </p> <!-- ========== Required and optional parameters ======================= --> <a id="Parameter_use"></a> <h2>Required and optional parameters</h2> <p> <table> <tr><th>Endpoint function</th><th>Required</th><th>Optional</th></tr> <tr><th>/list/publicHubs</th><td>(none)</td><td>(none)</td></tr> <tr><th>/list/ucscGenomes</th><td>(none)</td><td>(none)</td></tr> +<tr><th>/list/genarkGenomes</th><td>(none)</td><td>genome</td></tr> <tr><th>/list/hubGenomes</th><td>hubUrl</td><td>(none)</td></tr> <tr><th>/list/files</th><td>genome</td><td>format=text, maxItemsOutput</td></tr> <tr><th>/list/tracks</th><td>genome or (hubUrl and genome)</td><td>trackLeavesOnly=1</td></tr> <tr><th>/list/chromosomes</th><td>genome or (hubUrl and genome)</td><td>track</td></tr> <tr><th>/list/schema</th><td>(genome or (hubUrl and genome)) and track</td><td>(none)</td></tr> <tr><th>/getData/sequence</th><td>(genome or (hubUrl and genome)) and chrom</td><td>start, end, revComp=1</td></tr> <tr><th>/getData/track</th><td>(genome or (hubUrl and genome)) and track</td><td>chrom, (start and end), maxItemsOutput, jsonOutputArrays</td></tr> <tr><th>/search</th><td>search and genome</td><td>categories=helpDocs, categories=publicHubs, categories=trackDb</td></tr> </table> </p> <p> The <b>hubUrl</b> and <b>genome</b> parameters are required together to specify a unique genome in an assembly or track hub. The <b>genome</b> for a track hub will usually be a UCSC database genome. Assembly hubs will have their own unique <b>genome</b> sequences. Specify <b>genome</b> without a <b>hubUrl</b> to refer to a UCSC Genome Browser assembly. </p> <p> Using the <b>chrom=<name></b> parameter will limit the request to the single specified chromosome. To limit the request to a specific position, both <b>start=4321</b> and <b>end=5678</b> must be given together. Using the <b>revComp=1</b> parameter returns the reverse complement. </p> <p> +Use the <em>genome</em> argument with the <em>/list/genarkGenomes</em> function +to test for the existence of a specific genome assembly in the +<a href='https://hgdownload.soe.ucsc.edu/hubs/' target=_blank>Genark</a> set +of assembly hubs. +</p> +<p> The <b>/list/files</b> endpoint only works for UCSC hosted genome assemblies, not for external hosted assembly hubs. </p> <p> Any extra parameters not allowed in a function will be flagged as an error. </p> <!-- ========== Supported track types ======================= --> <a id="Track_types"></a> <h2>Supported track types for getData functions</h2> <p> <ul> -<li><a href='/FAQ/FAQformat.html#format21' target=_blank>barChart</a></li> +<li><a href='/goldenPath/help/bigBarChart.html' target=_blank>barChart/bigBarChart</a></li> <li><a href='/FAQ/FAQformat.html#format1' target=_blank>bed</a></li> -<li><a href='/FAQ/FAQformat.html#format1.5' target=_blank>bigBed</a></li> -<!-- not yet -<li><a href='/FAQ/FAQformat.html#format9.1' target=_blank>bigGenePred</a></li> ---> -<li><a href='/FAQ/FAQformat.html#format9.5' target=_blank>bigNarrowPeak</a></li> -<li><a href='/FAQ/FAQformat.html#format6.1' target=_blank>bigWig</a></li> +<li><a href='/goldenPath/help/bigBed.html' target=_blank>bigBed</a></li> +<li><a href='/goldenPath/help/bigChain.html' target=_blank>bigChain</a></li> +<li><a href='/goldenPath/help/bigGenePred.html' target=_blank>bigGenePred</a></li> +<li><a href='/goldenPath/help/bigLolly.html' target=_blank>bigLolly</a></li> +<li><a href='/goldenPath/help/bigNarrowPeak.html' target=_blank>bigNarrowPeak</a></li> +<li><a href='/goldenPath/help/bigMaf.html' target=_blank>bigMaf</a></li> +<li><a href='/goldenPath/help/bigPsl.html' target=_blank>bigPsl</a></li> +<li><a href='/goldenPath/help/bigWig.html' target=_blank>bigWig</a></li> <li><a href='/goldenPath/help/chain.html' target=_blank>chain</a></li> <li><a href='/FAQ/FAQformat.html#format9' target=_blank>genePred</a></li> -<li><a href='/FAQ/FAQformat.html#format22' target=_blank>interact</a></li> +<li><a href='/goldenPath/help/interact.html' target=_blank>interact/bigInteract</a></li> <li><a href='/FAQ/FAQformat.html#format9.5' target=_blank>narrowPeak</a></li> <li><a href='/FAQ/FAQformat.html#format17' target=_blank>peptideMapping</a></li> <li><a href='/FAQ/FAQformat.html#format2' target=_blank>psl</a></li> <li><a href='http://hgdownload.soe.ucsc.edu/goldenPath/hg38/database/rmsk.sql' target=_blank>rmsk - repeat masker</a></li> <li><a href='/FAQ/FAQformat.html#format6' target=_blank>wig</a></li> <li>(Work is underway to support additional track types)</li> </ul> </p> <!-- ========== API on mirrors and local installations ======================= --> <a id="Mirrors"></a> <h2>Using the API on mirrors and local installations</h2> <p> In order to access the API from a <a href='/mirror.html' target=_blank>mirror installation</a> or one of the UCSC official mirrors, the complete URL with the cgi-bin should be used:</p> @@ -268,30 +277,34 @@ <a id="list_examples"></a> <h2>Example data access</h2> <p> Your WEB browser can be configured to interpret JSON data and format in a convenient browsing format. Firefox has this function built in, other browsers have add-ons that can be turned on to format JSON data. With your browser thus configured, the following links can demonstrate the functions of the API interface. </p> <h3>Listing functions</h3> <ol> <li><a href='https://api.genome.ucsc.edu/list/publicHubs' target=_blank>list public hubs</a> - <b>api.genome.ucsc.edu/list/publicHubs</b></li> <li><a href='https://api.genome.ucsc.edu/list/ucscGenomes' target=_blank>list UCSC database genomes</a> - <b>api.genome.ucsc.edu/list/ucscGenomes</b></li> +<li><a href='https://api.genome.ucsc.edu/list/genarkGenomes;maxItemsOutput=5' target=_blank>list GenArk assembly hub genomes</a> - +<b>api.genome.ucsc.edu/list/genarkGenomes;maxItemsOutput=5</b></li> +<li><a href='https://api.genome.ucsc.edu/list/genarkGenomes;genome=GCF_028858775.2' target=_blank>test if genome GCF_028858775.2 exists in the GenArk assembly hub genomes</a> - +<b>api.genome.ucsc.edu/list/genarkGenomes;genome=GCF_028858775.2</b></li> <li><a href='https://api.genome.ucsc.edu/list/hubGenomes?hubUrl=http://hgdownload.soe.ucsc.edu/hubs/mouseStrains/hub.txt' target=_blank>list genomes from specified hub</a> - <b>api.genome.ucsc.edu/list/hubGenomes?hubUrl=http://hgdownload.soe.ucsc.edu/hubs/mouseStrains/hub.txt</b></li> <li><a href='https://api.genome.ucsc.edu/list/tracks?hubUrl=http://hgdownload.soe.ucsc.edu/hubs/mouseStrains/hub.txt;genome=CAST_EiJ' target=_blank>list tracks from specified hub and genome</a> - <b>api.genome.ucsc.edu/list/tracks?hubUrl=http://hgdownload.soe.ucsc.edu/hubs/mouseStrains/hub.txt;genome=CAST_EiJ</b></li> <li><a href='https://api.genome.ucsc.edu/list/tracks?genome=hg38' target=_blank>list tracks from UCSC database genome</a> - <b>api.genome.ucsc.edu/list/tracks?genome=hg38</b></li> <li><a href='https://api.genome.ucsc.edu/list/chromosomes?genome=hg38' target=_blank>list chromosomes from UCSC database genome</a> - <b>api.genome.ucsc.edu/list/chromosomes?genome=hg38</b></li> <li><a href='https://api.genome.ucsc.edu/list/chromosomes?genome=hg38;track=gold' target=_blank>list chromosomes from specified track in UCSC database genome</a> - <b>api.genome.ucsc.edu/list/chromosomes?genome=hg38;track=gold</b></li> <li><a href='https://api.genome.ucsc.edu/list/chromosomes?hubUrl=http://hgdownload.soe.ucsc.edu/hubs/mouseStrains/hub.txt;genome=CAST_EiJ' target=_blank>list chromosomes from assembly hub genome</a> -