Locked History Actions

VisualizationsRegistry/Cookbook


Configuration

I want my visualization to work on datasets of more than one type

You want to have your visualization to only be available for datasets from a history that are either a BED or GFF datatype but no other tabular datatypes.

You can have as many tests in a data source in your configuration as you may need. In this case, we can define two datatype tests, one for each of the two types:

   1     <data_sources>
   2         <data_source>
   3             <model_class>HistoryDatasetAssociation</model_class>
   4             <test type="isinstance" test_attr="datatype" result_type="datatype">interval.Bed</test>
   5             <test type="isinstance" test_attr="datatype" result_type="datatype">tabular.Gff</test>
   6             <to_param param_attr="id">dataset_id</to_param>
   7         </data_source>
   8     </data_sources>

Now your visualization will appear for both bed and gff datasets.

I want my visualization to work on any type of a dataset

Current implementation of the visualization plugin requires you to specify at least one test tag. In oder to have the plugin apply to every datatype and display the visualization option, it is necessary to specify the lowest common denominator datatype: data.Data.

   1     <test type="isinstance" test_attr="datatype" result_type="datatype">data.Data</test>

I want my visualization to work only on datasets produced by a specific tool

You want to have your visualization only to use datasets produced from a specific tool: the 'FASTQ Summary Statistics' from the tool shed.

You can test the data source's (dataset) attributes using the test type eq. This is the default test type, so you don't have to include the type="eq". In this case, you'll compare the dataset's creating_job.tool_id to the full id of the 'FASTQ Summary Statistics': toolshed.g2.bx.psu.edu/repos/devteam/fastq_stats/fastq_stats/1.0.0:

   1     <data_sources>
   2         <data_source>
   3             <model_class>HistoryDatasetAssociation</model_class>
   4             <test test_attr="creating_job.tool_id">
   5                 toolshed.g2.bx.psu.edu/repos/devteam/fastq_stats/fastq_stats/1.0.0
   6             </test>
   7             <to_param param_attr="id">dataset_id</to_param>
   8         </data_source>
   9     </data_sources>

Attributes are tested using string comparison - so be aware of how the attribute you're testing is converted to a string.

This can be done by almost any attribute of a data source accessible by getattr. In this case, the ORM-loaded attribute creating_job, then the tool_id attribute of that job.

I want my visualization to work only on datasets that can use a particular DataProvider

You're creating a visualization that uses intervals. No matter what the datatype of dataset is, if each datum contains a 'chrom', 'start', and 'end' entry the visualization can use it.

DataProviders yield data in configurable ways and many dataset datatypes have them. One format they can yield is the 'interval' type of data which yields the three values needed. You can use the type="has_dataprovider" test to see if a dataset (or any data source) has this data provider:

   1     <data_sources>
   2         <data_source>
   3             <model_class>HistoryDatasetAssociation</model_class>
   4             <test type="has_dataprovider" test_attr="datatype">interval</test>
   5             <to_param param_attr="id">dataset_id</to_param>
   6         </data_source>
   7     </data_sources>

Note: since dataproviders are attributes of a dataset's datatype we need to set test_attr="datatype" so that <the target HistoryDatasetAssociation>.datatype.has_dataprovider is called.

Interaction

How can I use some of the JavaScript UI elements Galaxy uses in my visualization?

First you'll need to load the base javascript libraries and CSS stylesheets that Galaxy normally includes on every one of it's pages. Load these in the head section of your mako template:

   1 <!DOCTYPE HTML>
   2 <html>
   3 <head>
   4 
   5 ## ----------------------------------------------------------------------------
   6 ${h.css( 'base' )}
   7 ## ... and any others you need
   8 ${h.stylesheet_link( '/plugins/visualizations/myvis/static/myvis.css' )}
   9 
  10 ## ----------------------------------------------------------------------------
  11 ${h.js( 'libs/jquery/jquery',
  12         'libs/jquery/jquery.migrate',
  13         'libs/jquery/jquery-ui',
  14         'libs/bootstrap',
  15         'libs/require',
  16         'libs/underscore',
  17         'libs/backbone/backbone',
  18         'mvc/ui'
  19 )}
  20 ## ... and any others you need
  21 <script type="text/javascript" src="/plugins/visualizations/myvis/static/myvis.js"></script>
  22 
  23 </head>

Galaxy often uses a module loading system called requirejs. Although it can seem complex at first, the example below is often all you have to do to load a Galaxy component:

   1 // (from within a script tag in your mako template)
   2 
   3 // point require at Galaxy's script directory:
   4 require.config({
   5     baseUrl: "/static/scripts"
   6 });
   7 // tell it to load the component's file asynchronously
   8 require([
   9     'mvc/dataset/dataset-choice'
  10 ], function( DATASET_CHOICE ){
  11     // this function is called when the page has loaded the script and
  12     //  the module is now loaded under the js namespace/obj DATASET_CHOICE
  13 
  14     // when the page is ready:
  15     $(function(){
  16     //    ... do something with DATASET_CHOICE
  17     });
  18 });

How can I add a way for the user to select a different (or additional) datasets?

The javascript libraries for Galaxy have code to create a javascript control to do this. See the section above for information on how to include Galaxy UI components. From within your mako template or scripts, you can then use this to allow a user dataset choice from datasets in the user's current history:

   1 require.config({
   2     baseUrl: "/static/scripts"
   3 });
   4 require([
   5     'mvc/dataset/dataset-choice'
   6 ], function( DATASET_CHOICE ){
   7     $(function(){
   8         // this ajax call will return the full detailed json for all datasets and collections in the current history
   9         //  it may be useful to cache this if you're adding more than one dataset choice control
  10         var historyContentsFetch = jQuery.ajax( '/api/histories/'
  11             + '${ trans.security.encode_id( trans.history.id ) }/contents?details=all' );
  12 
  13         // when the ajax completes successfully, ...
  14         historyContentsFetch.done( function( datasetJSON ){
  15             // ... create the controls and add them to the page
  16             $( '.my-controls' ).append([
  17 
  18                 // for a single dataset choice
  19                 new DATASET_CHOICE.DatasetChoice({
  20                     datasetJSON : datasetJSON,
  21                     label       : 'Input dataset',
  22                     // pass in the ids of any datasets you want previously/already selected
  23                     selected    : [ 'df7a1f0c02a5b08e' ]
  24                 }).render().$el,
  25 
  26                 // or to allow selection of multiple datasets
  27                 new DATASET_CHOICE.MultiDatasetChoice({
  28                     datasetJSON : datasetJSON,
  29                     label       : 'Input datasets',
  30                     selected    : [ 'df7a1f0c02a5b08e' /* , ... '<dataset2 id>', etc. */ ]
  31                 }).render().$el
  32             ]);
  33         });
  34     });
  35 });

See: this example repository for more info.