-
Notifications
You must be signed in to change notification settings - Fork 26
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Doc link to view url params #393
Changes from 8 commits
91bb9e4
adb1357
250cf32
5727a18
d7ecfb5
6dae4ff
000a2d8
c2fe067
edfeada
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -1,6 +1,7 @@ | ||||||
#### Sequence Tube Map Usage Guide | ||||||
The Sequence Tube Map is used to generate visualizations of genomic sequence graphs. This guide will demonstrate how to select custom data to visualize. [You can also read this guide on Github.](https://github.com/vgteam/sequenceTubeMap/blob/master/public/help/help.md) | ||||||
|
||||||
|
||||||
##### Selecting Tracks | ||||||
The following procedure describes adding and updating settings of custom tracks. You can use a custom track to load your own graph file, haplotype database, or file of aligned reads. | ||||||
|
||||||
|
@@ -30,3 +31,91 @@ The following procedure describes adding and updating settings of custom tracks. | |||||
4. If simplifying the BED file chunk or graph is possible, users will see a "Simplify Off" button, which when clicked with toggle to "Simplify On". This option enables vg simplify, which would remove small snarls. This option will only appear when there aren't any reads to be displayed. | ||||||
5. Click Go to see the selected tracks render in the visualization area. | ||||||
![Go Button](helpGuideImages/img9.png) | ||||||
|
||||||
##### How to make link-to-view URLs | ||||||
Users can compose URLs that link to a specific view, or a visualization of genomic data. The link describes which tracks and files will be displayed. | ||||||
|
||||||
###### Query String Encoding | ||||||
The link has a [query string](https://en.wikipedia.org/wiki/Query_string#Structure) that consists of key-value pairs separated by ampersands, where the keys are not URL-econded and the values are URL-encoded. | ||||||
|
||||||
Keys can use brackets to encode hierarchical structures such as arrays and objects. | ||||||
* For arrays, put a number in brackets to assign a new value to or access a value in that entry in the array. | ||||||
* For objects, put the key's name in brackets to assign a new value to or access a value in that entry in the object. | ||||||
|
||||||
The key's name should **not** be in quotes. | ||||||
|
||||||
###### Fields that can be included in the link URL: | ||||||
1. `tracks` | ||||||
|
||||||
Information about tracks. Tracks are objects consisting of `trackFile`, `trackType`, and `trackColorSettings`. | ||||||
|
||||||
A track object in JSON format might look like this: | ||||||
``` | ||||||
{ | ||||||
"trackFile": "exampleData/internal/snp1kg-BRCA1.vg.xg", | ||||||
"trackType": "graph", | ||||||
"trackColorSettings": { | ||||||
"mainPalette": "greys", | ||||||
"auxPalette": "ygreys", | ||||||
"colorReadsByMappingQuality": false | ||||||
} | ||||||
} | ||||||
``` | ||||||
|
||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Now we need to explain (or call back to our previous explanation) about how we're going to encode the collection of tracks as a bunch of query string parameters that all start with |
||||||
The collection of tracks wil be encoded as query string parameters starting with tracks. | ||||||
|
||||||
* The `trackFile` is the path (from the server working directory) or URL (any HTTP/HTTPS URL) to the track file. | ||||||
* Examples: | ||||||
* File in server working directory: `tracks[0][trackFile]=exampleData/internal/snp1kg-BRCA1.vg.xg`. | ||||||
* HTTP/HTTPS URL: `tracks[0][trackFile]=https://public.gi.ucsc.edu/~anovak/graphs/trivial-brca1.vg`. | ||||||
* The `trackType` specifies the type of the track, which can be `graph`, `haplotype`, `read`. | ||||||
* Example: `tracks[0][trackType]=graph`. | ||||||
* `trackColorSettings` (optional): the color information for the track. It has subfields: | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. These sibling bullets for |
||||||
* `mainPalette` and `auxPalette` (optional): The "main" and "auxilliary" color palettes to use, respectively. The values for each palette can be a hex code starting with a `#`, or one of the premade palette names: `greys`, `ygreys`, `blues`, `reds`, `plainColors`, or `lightColors`. | ||||||
* The palettes are used differently for different track types. | ||||||
* Graphs: the `mainPalette` colors the primary reference path while `auxPalette` is used for the other paths. | ||||||
* Haplotypes: only the `mainPalette` is used. | ||||||
* Reads: the `mainPalette` colors the forward-strand reads and the `auxPalette` colors the reverse-strand reads. | ||||||
* Examples: | ||||||
* `tracks[0][trackColorSettings][mainPalette]=greys`. | ||||||
* `tracks[0][trackColorSettings][auxPalette]=ygreys`. | ||||||
* `colorReadsByMappingQuality` (optional) is a boolean value that determines if reads are colored based on their mapping quality or not. It defaults to `false`. | ||||||
* Example: `tracks[0][trackColorSettings][colorReadsByMappingQuality]=true`. | ||||||
|
||||||
|
||||||
2. `region` | ||||||
|
||||||
Region coordinates. This is documented at step 3 of | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "This" here sounds a little vague; we should maybe say that the syntax for specifying genomic coordinates is what is documented there. |
||||||
[Displaying Visualizations](#displaying-visualizations). This region will be loaded in the tubemap visualization once the link is followed. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
* Example: `region=17%3A1-100`. | ||||||
|
||||||
|
||||||
3. `bedFile` (optional) | ||||||
|
||||||
A BED file containing coordinates for regions of interest, some of which may have associated pre-extracted Tube Map views. More information on BED file structure and creation is documented [here](https://github.com/vgteam/sequenceTubeMap?tab=readme-ov-file#preparing-subgraphs-in-advance). | ||||||
* Examples: | ||||||
* File in server working directory: `bedFile=exampleData/internal/snp1kg-BRCA1.bed`. | ||||||
* HTTP/HTTPS URL: `bedFile=https://raw.githubusercontent.com/vgteam/sequenceTubeMap/ca4f2485231ee4182173bec19489ba940b27461a/exampleData/cactus.bed`. | ||||||
* No BED file: `bedFile=none`. | ||||||
|
||||||
4. `dataType` | ||||||
|
||||||
Information about the type of data. Data can be `built-in`, `mounted files`, or synthetic `examples`. | ||||||
* `built-in`: Predefined data sources from the server configuration file. If the `dataType` field is set to `built-in`, you should set the `name` field to the name of a data source defined in `DATA_SOURCES` in `config.json`. | ||||||
* `mounted files`: If the `dataType` field is set to `mounted files`, the `name` field must be set to `custom`, and you should provide `custom` tracks along with an optional `bedFile`. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
* Examples: | ||||||
* `dataType=built-in`. | ||||||
* `dataType=mounted%20files`. | ||||||
|
||||||
5. `Simplify` | ||||||
|
||||||
Whether small snarls (e.g. single base indels and SNPs) are displayed or removed. It defaults to false, which means that the small snarls are not removed. Currently, this option cannot be used if there are any read tracks. | ||||||
* Example: `simplify=false`. | ||||||
|
||||||
6. `name` | ||||||
|
||||||
Name of data. This is a field that indicates the name of preset data, which is defined in `DATA_SOURCES` in `config.json`. `name` is used when `dataType` is set to `built-in`. You do not have to use these presets. If `dataType` is `mounted files`, this field should be set to `custom`. | ||||||
* Examples: | ||||||
* `name=snp1kg-BRCA1`. | ||||||
* `name=snp1kg-BRCA1`. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. These are duplicated; maybe one is meant to be |
||||||
|
||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It might be useful to provide one or two complete examples with all the fields filled in for a complete custom view with |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The newlines here get lost when the Markdown is rendered (see the rich diff). And among the various fields there are several different structures right after the number: field name and a noun phrase, field name and a sentence, field name and a verb phrase ("Describes ..."). So we probably should settle on one structure with a separator between the
field
and the description. I would recommend using a colon and than an un-capitalized noun phrase with a "the", describing what goes in the field, and ending with a period, like this:foobar
: the foo to bar. Now I can talk more about what the semantics of foos and bar-ing are in a few more sentences.foobar=this_foo
catCount
: the number of cats to be included in the request. No cats will be harmed while processing the request.catCount=2
I like including the example as a nested bullet so I am showing that here too.
The important thing is to be consistent across all the fields. They should all, as far as possible, follow the same pattern.