simonbrent · BurkovBA · Dec 15, 2016 · Dec 15, 2016 · Dec 15, 2016 · Dec 15, 2016
diff --git a/README b/README
diff --git a/README.md b/README.md
@@ -0,0 +1,48 @@
+# Genoverse
+
+Genoverse is a portable, customizable, back-end independent JavaScript and HTML5 based genome browser which allows the user to explore data in a dynamic and interactive manner.
+
+Data is visualized in the browser, meaning Genoverse can be installed on any website and show data from a wide range of online or local sources.
+
+Genoverse works with a variety of formats, such as JSON, BED, BAM, VCF, GFF, delimited text files, or XML, and can be customized to parse and display any data source as required.
+
+Genoverse works using a system of [**tracks**](docs/tracks.md) - essentially horizontal sections of the genome browser which display **features** - genes, variants, etc. with defined genomic start and end points. Each track has its own data set stored in a **model**, a method for displaying that data, stored in a **view**, and a **controller** to manage the creation of DOM elements, and user interactions with them. 
+
+Tracks can have multiple models and views, which allows for switching between displays at different zoom levels. An example of this would be a track where you show genes when looking at a large region of a chromosome, and then switch to showing transcripts as the user zooms in.
+
+In addition to this, Genoverse has a set of [plugins](docs/plugins.md), which allow additional functionality beyond the core genome browser. These include a control panel for adding and removing tracks, and interacting with the browser more easily, a way to add controls to each individual track, and a way to enable drag and drop of local data files onto the genome browser.
+
+## Installation
+
+1. Download the latest version from GitHub
+  ```
+  git clone git@github.com:wtsi-web/Genoverse.git
+  ```
+
+2. Embed Genoverse using either
+  ```html
+  <script src="/path/to/Genoverse/js/genoverse.combined.js"></script>
+  ```
+
+  which comes with jQuery and jQuery UI included, or 
+  ```html
+  <script src="/path/to/Genoverse/js/genoverse.combined.nojquery.js"></script>
+  ```
+
+  if you already have them in the page
+
+3. Add a script tag or JavaScript file which initializes Genoverse, e.g.
+  ```html
+  <script>
+    $(document).ready(function () {
+      var genoverse = new Genoverse({ ... configuration ... });
+    });
+  </script>
+  ```
+  See [index.html](/index.html) for example configuration, or the [documentation](docs/configuration.md) for more details about configuration properties.
+
+Once initalized, the instance of Genoverse is avaliable as a jQuery data attribute on the container DOM element, and can be accessed by
+```javascript
+var genoverse = $(container).data('genoverse');
+```
+
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,168 @@
+# API
+
+The following are methods that can be called on an instance of Genoverse or Genoverse.Track to perform actions required by UI changes external to the instance (i.e. from the website you have integrated Genoverse into).
+
+## Genoverse API
+
+#### genoverse.addTracks(tracks [, after ])
+> Add a number of tracks to the genome browser
+>
+> Argument | Type | Description
+> --- | --- | ---
+> tracks | Array | An array of `Genoverse.Track` class definitions to be added
+> after | Integer or undefined | The existing track after which the new tracks will be inserted. For example, if the existing tracks are `[ A, B, C, D, E ]`, `genoverse.addTracks([ X, Y ], 2)` will result in `[ A, B, X, Y, C, D, E ]`. If `undefined` , the tracks will be inserted after the existing tracks.
+
+#### genoverse.addTrack(track [, after ])
+> Add a single track to the genome browser
+>
+> Argument | Type | Description
+> --- | --- | ---
+> track | `Genoverse.Track` class | A `Genoverse.Track` class definition to be added
+> after | Integer or undefined | See `genoverse.addTracks`
+
+#### genoverse.removeTracks(tracks)
+> Remove a number of tracks from the genome browser
+>
+> Argument | Type | Description
+> --- | --- | ---
+> tracks | Array | An array of existing `Genoverse.Track` instances to be removed
+
+#### genoverse.removeTrack(track)
+> Remove a single track from the genome browser
+>
+> Argument | Type | Description
+> --- | --- | ---
+> track | `Genoverse.Track` instance | An existing `Genoverse.Track` instance to be removed
+
+#### genoverse.addHighlights(highlights)
+> Add a number of highlighted regions to the genome browser
+>
+> Argument | Type | Description
+> --- | --- | ---
+> tracks | Array | An array of highlighted regions to be added. See [configuration](configuration.md#highlights-default-) for the structure of highlights.
+
+#### genoverse.addHighlight(highlight)
+> Add a single highlighted regions to the genome browser
+>
+> Argument | Type | Description
+> --- | --- | ---
+> highlight | Object | A highlighted region to be added. See [configuration](configuration.md#highlights-default-) for the structure of highlights.
+
+#### genoverse.moveTo(chr, start, end [, update] [, keepLength])
+> Moves the viewpoint to the region between `start` and `end`
+>
+> Argument | Type | Description
+> --- | --- | ---
+> chr | String or undefined | The name of a chromosome defined by `genoverse.genome`. If `genoverse.genome` is undefined, `chr` must be undefined, or the current value of `genoverse.chr`.
+> start | Integer | A number between `1` and `genoverse.chromosomeSize`
+> end | Integer | A number between `start` and `genoverse.chromosomeSize`
+> update | Boolean or undefined | If `true`, the URL will be updated with the new `start` and `end`
+> keepLength | Boolean or undefined | if `true`, the new viewpoint will have the same zoom level as before (`end - start` remains unchanged), centered on the given `start` and `end`.
+
+#### genoverse.setWidth(width)
+> Resizes the `container` element for the instance of Genoverse
+>
+> Argument | Type | Description
+> --- | --- | ---
+> width | Integer | The width to resize to, in pixel
+
+#### genoverse.setDragAction(action)
+> Sets [`genoverse.dragAction`](/docs/configuration.md#dragaction-default-scroll), determining whether a drag (mousedown, mousemove, mouseup) results in the browser region moving, a region being selected, or nothing
+>
+> Argument | Type | Description
+> --- | --- | ---
+> action | `"select"`, `"scroll"`, or `"off"` | The value which `genoverse.dragAction` will be set to
+
+#### genoverse.setWheelAction(action)
+> Sets [`genoverse.wheelAction`](/docs/configuration.md#wheelaction-default-off), determining whether a mousewheel scroll zooms the browser in and out, or does nothing
+>
+> Argument | Type | Description
+> --- | --- | ---
+> action | `"zoom"` or `"off"` | The value which `genoverse.wheelAction` will be set to
+
+#### genoverse.closeMenus([ track ])
+> If `track` is a Genoverse.Track instance, closes (hides) all popup menus for that track. 
+> If `track` is `undefined`, closes all popup menus.
+> 
+> Argument | Type | Description
+> --- | --- | ---
+> track | Genoverse.Track instance or undefined | The object whose popup menus will be closed
+
+#### genoverse.on(events, [, onTracks ], callback)
+> Execute functions before or after Genoverse or Genoverse.Track functions
+>
+> Argument | Type | Description
+> --- | --- | ---
+> events | String | One or more space-separated events. Events are function names with an uppercase first letter, appended to "before" or "after", e.g. "beforeAddTrack" or "afterSetWidth".
+> onTracks | `"tracks"` or `Genoverse.Track` instance | If present, the callback will be executed on any track in the genome browser. *Note that providing a specific track instance does not mean the callback will be executed only for that track.* If omitted (i.e. `genoverse.on(events, callback)`, the callback will be executed on the instance of Genoverse.
+> callback | Function | The function to be executed for all of the space-separated events
+
+#### genoverse.on(events [, onTracks ])
+> Execute functions before or after Genoverse or Genoverse.Track functions
+>
+> Argument | Type | Description
+> --- | --- | ---
+> events | Object | An object whose keys are one or more space-separated events (see above), and whose values are the functions to be executed for those events
+> onTracks | `"tracks"` or `Genoverse.Track` instance | See above
+
+#### genoverse.once(events, [, onTracks ], callback)
+> Like [`genoverse.on`](#genoverseonevents--ontracks--callback), but the functions will only be called one time
+
+#### genoverse.once(events, [, onTracks ])
+> Like [`genoverse.on`](#genoverseonevents--ontracks-), but the functions will only be called one time
+
+#### genoverse.reset()
+> Removes all existing data visualizations, and recreates them
+
+#### genoverse.resetTrackHeights()
+> Sets all track heights to their initial values
+
+#### genoverse.destroy()
+> Removes the instance of Genoverse from the web page
+
+## Genoverse.Track API
+
+#### track.prop(key [, value ])
+> Get or set a property on the track or it's model, view or controller, without needing to know specifically which of these objects the property belongs to. Also available on `track.model`, `track.view`, and `track.controller` with identical functionality.
+>
+> Argument | Type | Description
+> --- | --- | ---
+> key | String | The name of the property to be returned.
+> value | Anything | If defined, the value of the property will be set to this argument. If `null`, the property will be removed from its object.
+
+#### track.setConfig(type, name)
+> Set the track's [configuration](/docs/tracks/configuration.md#changing-track-settings) after initalization
+>
+> Argument | Type | Description
+> --- | --- | ---
+> type | String | One of the keys in `track.configSettings`
+> name | String | One of the keys in `track.configSettings[type]`
+
+#### track.setConfig(config)
+> Set the track's [configuration](/docs/tracks/configuration.md#changing-track-settings) after initalization
+>
+> Argument | Type | Description
+> --- | --- | ---
+> config | Object | An object in the form `{ type1: "name1", type2, "name2" }`, where each `type` and `name` fulfills the criteria of `track.setConfig(type, name)`, above
+
+#### track.remove()
+> Remove the track from the genome browser
+
+#### track.disable()
+> Hide the track in the genome browser, without removing it
+
+#### track.enable()
+> Show the track in the genome browser, if it had previously been disabled
+
+#### track.reset()
+> Clears all data stored by the track's models and views, removes the images that have been drawn by the track so far, and then requests new data, and creates new images for the current location in the genome browser
+
+#### track.resetHeight()
+> Sets the track's height to its initial value
+
+#### track.updateName(name)
+> Changes the name of the track, as displayed in the label to the left of its images.
+>
+> Argument | Type | Description
+> --- | --- | ---
+> name | String | The name for the track.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,125 @@
+# Configuration
+
+Genoverse has a large number of configurable properties, in order to allow customization. A basic example with two tracks (a scalebar and some genes) and no plugins would be
+
+```js
+var genoverse = new Genoverse({ 
+  genome: 'grch38', 
+  tracks: [ Genoverse.Track.Scalebar, Genoverse.Track.Gene ] 
+});
+```
+
+The following properties can be provided to the constructor for Genoverse:
+
+## DOM element
+
+#### container (default `undefined`)
+> A DOM node, jQuery selector, or string to create a jQuery selector (e.g. `"#genoverse"`) inside which the instance of Genoverse will be created. 
+If `undefined`, a `<div>` element will be appended to `document.body`.
+
+#### width (default `1000`)
+> The width that the `container` DOM element will be
+
+## Genomic coordinates
+
+#### chr (default `1`)
+> A string or number defining the initial chromosome to display
+
+#### start (default `1`)
+> A string or number defining the initial start position
+
+#### end (default `1000000`)
+> A string or number defining the initial end position
+
+#### assembly (default `undefined`)
+> A string defining the assembly, which can be used by [track URL templates](/docs/tracks/configuration.md#url-default-undefined)
+
+#### genome (default `undefined`)
+> The genome to be used. Can be:
+>
+>  - an object with keys of the number/letter/name of the chromosomes, and values in the form `{ "size": 10000 }`. 
+>  Additionally an array of bands can be supplied for each chromosome for drawing purposes - see [js/genomes/grch38.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/js/genomes/grch38.js) for an example. These files can be created for species present in [Ensembl](http://www.ensembl.org/info/about/species.html) by modifying the example node script [utils/createGenome.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/utils/createGenome.js) for the species required.
+>  - a string (e.g. `"grch38"`) which will be used to obtain a javascript file from the [js/genomes](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/genomes) directory
+>  - `undefined`, in which case `chromosomeSize` **MUST** be set (see below)
+
+#### chromosomeSize (default `undefined`)
+> If `genome` not is provided, `chromosomeSize` **MUST** be set to the length of the chromosome. 
+>
+> If `genome` is provided, `chromosomeSize` will be set to the chromosome's `size` property, as defined by the genome object.
+
+## What is displayed
+
+#### tracks (default `[]`)
+> An array of `Genoverse.Track` definitions to be displayed
+
+#### highlights (default `[]`)
+> An array of regions to highlight, in the form 
+```
+{ "start": 100, "end", 200, "label": "My highlight", "removable": false }
+``` 
+> `label` defaults to "start-end" (e.g. "100-200") if not provided. 
+> 
+> If `removable === false`, the highlight cannot be removed.
+
+#### plugins (default `[]`)
+> An array of `Genoverse.Plugins` to be used (from the [js/plugins](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/plugins) directory), e.g. 
+```
+[ "controlPanel", "trackControls" ]
+```
+> The strings in this array correspond to the namespace of each plugin, which are the same as their file names. 
+
+## Interaction with the URL
+
+#### urlParamTemplate (default `"r=__CHR__:__START__-__END__"`)
+> The template used to alter the web browser's URL. Should contain placeholders for chr, start and end.
+>
+> If `false` or empty string, no changes will be made to the URL when navigation occurs. 
+
+#### useHash (default `undefined`)
+> Determines how the browser's URL gets updated on navigation. Can be:
+>
+> - `true` - use `window.location.hash`
+> - `false` - use `window.history.pushState`
+> - `undefined` - use `window.history.pushState` if present in the browser, else use `window.location.hash`
+
+## User actions
+
+#### dragAction (default `"scroll"`) 
+> The action performed when a mouse drag happens on the genome browser. Can be:
+>
+>  - `"scroll"` - Move the browser left or right
+>  - `"select"` - Select the region
+>  - `"off"`    - Do nothing
+
+#### wheelAction (default `"off"`) 
+> The action performed when a mouse drag happens on the genome browser. Can be:
+>
+>  - `"zoom"` - Zoom in or out
+>  - `"off"`    - Do nothing
+
+#### isStatic (default `false`)
+> If `true`, will stop drag, select and zoom actions occurring
+
+## Saving user configurations
+
+#### saveable (default `false`)
+> If `true`, track configuration and ordering will be saved in `window.sessionStorage`/`window.localStorage` (defined by `storageType`, below) so that users will see the same display when they refresh the page
+
+#### storageType (default `"sessionStorage"`)
+> The storage object used to save track configuration. Set to `"localStorage"` for permanence.
+>
+> See Mozilla's [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) and [localStorage](https://developer.mozilla.org/en/docs/Web/API/Window/localStorage) documentation for further details.
+
+#### saveKey (default empty string)
+> The default key used in configuration storage is `"genoverse"`. `saveKey` will be appended to this to allow different configurations for different instances of Genoverse.
+
+## Default track display settings
+
+#### autoHideMessages (default `true`)
+> Determines whether to collapse track messages (toggleable pop-outs on the left side of a track's image)  by default when the user interacts with the genome browser
+
+#### trackAutoHeight (default `false`)
+> Determines whether to automatically resize tracks to show all their features (can be overridden by `track.autoHeight`)
+
+#### hideEmptyTracks (default `true`)
+> Determines whether to hide an automatically resized tracks if it has no features, or to show it empty (can be overridden by `track.hideEmpty`)