Doc link to view url params #393

shreyasun · 2024-02-16T17:14:21Z

Fixes #197

…ation

…examples

adamnovak

This covers a lot of what we want to cover. But I think it can be made more consistent overall, and some pieces can maybe be made clearer. I've left a lot of line-item comments that I hope will be helpful.

adamnovak · 2024-02-16T22:58:16Z

public/help/help.md

+Users can compose URLs that link to a specific view. To do so, users will require specific information about files and tracks. 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, and 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.
+
+These are the fields that can be included in the URL:
+1. `tracks` 


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.

Example: foobar=this_foo

catCount: the number of cats to be included in the request. No cats will be harmed while processing the request.

Example: 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.

adamnovak · 2024-02-16T23:00:58Z

public/help/help.md

+1. `tracks` 
+   Information about tracks. Tracks are objects consisting of trackFile, trackType, and trackColorSettings. To retrieve this information, index the tracks array to access the object and respective keys.
+
+   A track JSON object might look like this:


We should call this "a track object in JSON format"; we're about to convert it to a different format as part of the query string.

adamnovak · 2024-02-16T23:02:09Z

public/help/help.md

+
+These are the fields that can be included in the URL:
+1. `tracks` 
+   Information about tracks. Tracks are objects consisting of trackFile, trackType, and trackColorSettings. To retrieve this information, index the tracks array to access the object and respective keys.


The field names here should be in backticks. And I think we should cut the sentence about "retrieving" the information, because that doesn't make any sense in the context of encoding information into a link.

adamnovak · 2024-02-16T23:05:51Z

public/help/help.md

+      }
+   }
+   ```
+


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 tracks.

adamnovak · 2024-02-16T23:06:26Z

public/help/help.md

+         * The palettes are used differently for different track types
+            * For graphs, the `mainPalette` colors the primary reference path while `auxPalette` is used for the other paths. 
+            * For haplotypes, only the `mainPalette` is used. 
+            - For reads, the `mainPalette` colors the forward-strand reads and the `auxPalette` colors the backward-strand reads. 


Suggested change

- For reads, the `mainPalette` colors the forward-strand reads and the `auxPalette` colors the backward-strand reads.

* For reads, the `mainPalette` colors the forward-strand reads and the `auxPalette` colors the reverse-strand reads.

adamnovak · 2024-02-16T23:37:42Z

public/help/help.md

+      * `examples`: Links to synthetic examples cannot currently be created.
+   * Example: `dataType=built-in`
+5. `Simplify`. 
+   This determines 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.


We might want to note here that it can't currently be used if there are any read tracks.

adamnovak · 2024-02-16T23:38:22Z

public/help/help.md

+   This determines 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.
+   * 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. 


We should probably reiterate that this should be custom if dataType is mounted files.

adamnovak · 2024-02-16T23:38:41Z

public/help/help.md

+      * `built-in`: If the `datatype` field is set to `built-in`, you should set the `name` field to the name of a preset 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 select custom tracks along with an optional bedfile.
+      * `examples`: Links to synthetic examples cannot currently be created.
+   * Example: `dataType=built-in`


We should have another example showing the space in mounted files being encoded to give mounted%20files.

adamnovak · 2024-02-16T23:41:14Z

public/help/help.md

+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. 
+   * Example: `name=snp1kg-BRCA1`
+


It might be useful to provide one or two complete examples with all the fields filled in for a complete custom view with mounted files and just some non-default coordinates with built-in.

adamnovak · 2024-02-16T23:48:48Z

public/help/help.md

@@ -30,3 +31,65 @@ 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. To do so, users will require specific information about files and tracks. 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, and 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.


I get a little lost reading about the nuances of encoding hierarchical structures right off here, before I have an idea of why I would need to encode one.

I would paragraph-break after the second sentence here.

I would also maybe replace that second sentence with something more explanatory of the concept of a view; right now you're just saying that I will need "specific" (but unspecified) information about some unspecified files and tracks. You might want to say that the link can describe which tracks and files will be displayed, or something.

The details of the brackets should maybe move down to the description of tracks so it can be near its examples and so that it can come after we've introduced the problem of encoding an object with some JSON representation as part of a query string. Or, we could leave it here but provide some examples here and maybe give it a little section heading: "Query String Encoding" or something.

adamnovak · 2024-03-05T16:18:54Z

public/help/help.md

+   * 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:


These sibling bullets for trackFile, trackType, and trackColorSettings should all use the same sentence structure.

adamnovak · 2024-03-05T16:21:16Z

public/help/help.md

+
+2. `region`
+
+   Region coordinates. This is documented at step 3 of


"This" here sounds a little vague; we should maybe say that the syntax for specifying genomic coordinates is what is documented there.

adamnovak · 2024-03-05T16:21:59Z

public/help/help.md

+2. `region`
+
+   Region coordinates. This is documented at step 3 of
+   [Displaying Visualizations](#displaying-visualizations). This region will be loaded in the tubemap visualization once the link is followed.


Suggested change

[Displaying Visualizations](#displaying-visualizations). This region will be loaded in the tubemap visualization once the link is followed.

[Displaying Visualizations](#displaying-visualizations). This region will be loaded in the Tube Map visualization once the link is followed.

adamnovak · 2024-03-05T16:23:08Z

public/help/help.md

+
+   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`.


Suggested change

* `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`.

* `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`.

adamnovak · 2024-03-05T16:23:58Z

public/help/help.md

+         * `name=snp1kg-BRCA1`.
+         * `name=snp1kg-BRCA1`.


These are duplicated; maybe one is meant to be custom?

shreyasun added 6 commits January 29, 2024 09:02

Incorporated values to current viewTarget from copied URL to document…

91bb9e4

…ation

continuing to work on documentation and adding more descriptions and …

adb1357

…examples

updates to help documentation

250cf32

More documentation

5727a18

Updates

d7ecfb5

Refined and finalized instructions

6dae4ff

adamnovak requested changes Feb 16, 2024

View reviewed changes

shreyasun added 2 commits February 29, 2024 09:01

Started requested changes for help documentation

000a2d8

Resolved most of requested changes

c2fe067

adamnovak requested changes Mar 5, 2024

View reviewed changes

Fixed formatting and added examples

edfeada

adamnovak approved these changes Mar 5, 2024

View reviewed changes

adamnovak merged commit 4289886 into master Mar 5, 2024
1 check passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Doc link to view url params #393

Doc link to view url params #393

shreyasun commented Feb 16, 2024

adamnovak left a comment

adamnovak Feb 16, 2024

adamnovak Feb 16, 2024

adamnovak Feb 16, 2024

adamnovak Feb 16, 2024

adamnovak Feb 16, 2024

adamnovak Feb 16, 2024

adamnovak Feb 16, 2024

adamnovak Feb 16, 2024

adamnovak Feb 16, 2024

adamnovak Feb 16, 2024

adamnovak Mar 5, 2024

adamnovak Mar 5, 2024

adamnovak Mar 5, 2024

adamnovak Mar 5, 2024

adamnovak Mar 5, 2024

	- For reads, the `mainPalette` colors the forward-strand reads and the `auxPalette` colors the backward-strand reads.
	* For reads, the `mainPalette` colors the forward-strand reads and the `auxPalette` colors the reverse-strand reads.


		2. `region`

		Region coordinates. This is documented at step 3 of

	[Displaying Visualizations](#displaying-visualizations). This region will be loaded in the tubemap visualization once the link is followed.
	[Displaying Visualizations](#displaying-visualizations). This region will be loaded in the Tube Map visualization once the link is followed.

	* `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`.
	* `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`.

Doc link to view url params #393

Doc link to view url params #393

Conversation

shreyasun commented Feb 16, 2024

adamnovak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment