Commit abcb5bc1 authored by Marek Ostaszewski's avatar Marek Ostaszewski
Browse files

Update README.md

parent fa7cd46c
Pipeline #14739 passed with stages
in 1 minute and 58 seconds
# Minerva plugin creation with starter-kit
# Gene Set Enrichment Analysis (GSEA) plugin
A plugin allowing to calculate the gene set enrichment based on the data overlays highlighted by the user.
This is a plugin for GSEA in maps hosted in MINERVA. The plugin calculates enrichment for uploaded data overlays.
Public overlays are available for GSEA to all the users. User-provided (private) overlays can be analyzed only when a given user is logged in.
## General comments
## Load the plugin
Use the plugin icon to invoke the plugin popup, and paste the address of the plugin in the URL field (see figure below).
The address of the plugin is: `https://minerva-dev.lcsb.uni.lu/plugins/gsea/plugin.js`
Press *UPLOAD* button to start the plugin.
* Minerva uses jQuery so plugins can use it as well since it is loaded in the global scope
* Minerva uses Bootstrap so Bootstrap styles are available to plugins as well
* Many of the functions which are used to interact with Minerva are asynchronous and thus return a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) and not the actual data. This holds mainly for functions for data retrieval such as `getAllBioentities` (see below).
## Building the starter-kit
## Plugin functionality
To use the plugin, select from the left panel the overlay for which you would like to calculate the enrichment.
Then, press the *Show enriched pathways* button.
The starter-kit example uses NPM (node package manager) and Browserify (and few other packages such as browserify-css or uglify) to build the plugin distriubtion file which you can publish at a URL address which can then be referenced from Minerva. To build the starter-kit you need to do the following steps:
After running the plugin you will:
* Download the starter-kit
* Download and install [NPM](https://nodejs.org/en/download/) if it is not yet installed on your system (try running `npm` from command line to find out)
* run `npm install` (this will create the *node_modules* directory with the required NPM modules)
* run `npm run build` to build the plugin which will be available in the *dist* directory
* run `npm run build-debug` if you want to obtained non-minified version of the compiled plugin, which can be used for
debugging the plugin in, e.g., Google Chrome DevTools
* publish the resulting *plugin.js* file somewhere where it can be accessed by Minerva (please beware that if the instance is running on HTTPS, the plugin must be also accessible through HTTPS)
1. See the results of the enrichment: the p-value is Bonferroni adjusted.
2The *Enriched area* column contains the names of pathways and submaps, for which are enriched in the considered overlay.
Enriched areas are highlighted in the map.
2. Have the possibility to download the tabular version of the enrichment results.
For the development process you might want to have your local instance of Minerva running, so that you do not have to publish the plugin file every time you do a change. However, if you do not have a local Minerva instance, you can use command line to commit and push your plugin to, e.g., GitHub and provide Minerva address of the raw file. So for example if your GitHub repository with the plugin is [https://github.com/davidhoksza/minerva-plugins-starter-kit/](https://github.com/davidhoksza/minerva-plugins-starter-kit/) you can run
```
npm run build && git commit -m "distribution commit" dist/plugin.js && git push
```
which will build your plugin and commit and push it to the Git repository (GitHub in our case) and your plugin will be available at [https://raw.githubusercontent.com/davidhoksza/minerva-plugins-starter-kit/master/dist/plugin.js](https://raw.githubusercontent.com/davidhoksza/minerva-plugins-starter-kit/master/dist/plugin.js)
## Plugin structure
The starter-kit contains CSS with styles sheets and JavaScript code. The kit actually uses SCSS ([Sass](https://sass-lang.com/) extension of CSS) which is then compiled into CSS during the build process. The JavaScript code consists of a single `index.js` file which:
* Registers required functions with Minerva
* Creates plugin's HTML structure
* Interacts with Minerva to do what needs to be done
#### Registering with Minerva
When the plugin is loaded into Minerva `minervaDefine` function is called, so this needs to be present in every plugin script. This function needs to return an object which maps keys `register`, `unregister`, `getName` and `getVersion` to the corresponding functions. Only the `register` function is passed an argument being the Minerva object which can then later be used to interact with the map.
#### Creating plugin's HTML structure
The Minerva object passed to the `register` function contains the `element` attribute being a jQuery object corresponding to the DOM element holding the plugin container (Minerva uses jQuery, so plugins do not need to include it). With the container element in hand, the plugin can add and modify its content freely. Of course, the plugin can also modify Minerva's DOM elements, however we strongly discourage from that.
#### Interacting with Minerva
###### Minerva proxy object
All the interaction with Minerva should happen through the minerva proxy object or ServerConnector (see next section) passed to the `register` function. To explore this object, starter-kit logs it into the console (`console.log('minerva object ', minervaProxy);`) so after the plugin is loaded, you can check out your browser's developers console and go through it. The structure of the object is following (not all attributes are mentioned):
* configuration: includes information about available types of elements, reactions, miriam types, configuration options, map types and so on
* project: content-related data and functionaliry
* data: functions to retrieve the data, mainly `getAllBioEntities` and `getBioEntityById`
* beware that most of these functions are asynchronous so they actually return a promise not the actual objects
* map: functions to interact with the visual aspect of the map, mainly `showBioEntity` (highlights a bioentity), `hideBioEntity`, `fitBounds` (zooms to provided coordinates) and `addListener` (enables listening to events such as selection of entities) - see examples of using these functions in the starter-kit and the Minerva's [JavaScript API documntation](https://git-r3lab.uni.lu/piotr.gawron/minerva#javascript-api-unstable-dev-api).
An example of interaction with Minerva (see the `index.html` for more examples):
```
minervaProxy.project.data.getAllBioEntities().then(function(bes){
console.log(bes);
let be = bes[0];
//the following line is valid only if the first bioineity is of type ALIAS and not REACTION
minervaProxy.project.data.getBioEntityById({id:be.getId(), modelId:bw.getModelId(), type:'ALIAS'}).then( function(be1) {
console.log(be1);
});
```
Some of the functions are also described in the [JavaScript API documntation](https://git-r3lab.uni.lu/piotr.gawron/minerva#javascript-api-unstable-dev-api).
###### ServerConnector object
Minerva also exposes variable called `ServerConnector` to the global scope (therefore you can explore it by typing `ServerConnector` in the browser developers console). It provides various functionality such as ability to retrieve list of models, overlays, projects, link to logo file, server address or add and modify comments, users.
###### Minerva's API
It can happen that there exists a (mainly data-related) functionality which is not available in the proxy object but is available through [Minerva's REST API](https://git-r3lab.uni.lu/piotr.gawron/minerva). In such case you can use Ajax to retrieve the data (the easiest way is probably to use jQuery's [getJSON](http://api.jquery.com/jquery.getjson/) function).
\ No newline at end of file
## Remarks
* The names of the pathways are not visible for the highlighted areas. Switch back to *Pathways and compartments* view to see the names.
* If multiple overlays are selected, the enrichment will be calculated for the union of the corresponding gene sets.
* The single elements behind the highlighted area are not clickable. Press *Reset* button to remove the highlighting.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment