rbbt-rest 1.2.34 → 1.2.35

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NGY2MmY0MWQ5MDNkY2YyNDliMDYxZWI3MzU2ZTVlNDY0NThkYTZiMg==
+    ZTdlZWRiOGE3MmQyMjU0YTQxODM0ODM0NjZkNzE3ZmM5ZGI4MDMzZA==
   data.tar.gz: !binary |-
-    MjQxMGM2ODA5MjA5NGEyMmIxYjZlNjllZTUyNjU2NjhmMzg0M2E3ZA==
+    MmNlODFmYTYwZTRlMWJjMTZmNzhkODUyOTkyZjNlYzIyNTBiMmQwNg==
 SHA512:
   metadata.gz: !binary |-
-    MzQ4OTk3MDYzMmE1YzViM2Y1ZmM5YzRhZTBiNjhlOGViYzE0NmQxOTU0MDk2
-    NGRhNzI4YzlkMTNjZWQxNDA0Mzg4MWNlMDM0NzlkMmY2MzBhMzYyYWI0NmE1
-    OWFmYTBjM2EyZDk5ZjY4NGU5MWQ2ODQ2MWUwNjIxMDI0Njk2MWQ=
+    NzM4NGU4MDc1OTJiYTM4NjI0Zjk3MDZjYzA1YWI0OWZhZGE4OTczOTgyM2Fj
+    ODAyOWY5MTYzZTNiNGFlNTY1YzliMDMxOWM1ZmRmMTZkZWVjZWVmN2YzNjkz
+    YzM1ZDBmZTg3YjczYThjMTIzMWJiMDgwZTFiYjBkZjljODgwOGU=
   data.tar.gz: !binary |-
-    NWEzOTM5NjU3MjYxZGNjYjBlNGQxNjljZmQ3NjAyNGJmNjBhMDE0MjU4OTI5
-    NjE3MjIzMGYzNTUxZTEwZWRiZjcxMDRjNjg4MTNlNWFmNzNlMjIwNjJhZTky
-    ZjQzYzU4ZjIxMTU1OWU4MWQxOGE3OWQ1ZDBkOGZkMGZmNzNhY2I=
+    M2M5NjQ3MGYxNmZiYTBlNDdkMmE5MjViNjRkOTVkYWViNTg5ZDVkOGEwZjIw
+    YzQ4NzY3NGRmMThmOThhODMwYWJjMTNmNWNmM2FiMjJiNmU4ZjQ0MjczZjEz
+    YjdhZTJiNmYzNzI3NGFhYzkyOTRkYWRiZTVjOThmNGM5Zjg4MmI=

data/share/views/compass/help.sass

@@ -1,3 +1,23 @@
 a.help
   font-size: 1.2em
   display: block
+
+.UI
+  dd
+    .description, .images
+      +grid-column(6, $float:left)
+
+  & > dd
+    +grid-row()
+    & > .description, .images
+      +grid-column(6, $float:left)
+
+
+    & > .images > dl 
+      & > dt
+        width: 40%
+      & > dd > img
+        display: block
+        margin: auto
+
+

data/share/views/help.haml

@@ -1,78 +1,59 @@
 :markdown
 
-  Overview
-  ========
+  ##Overview
 
   This application is designed for integration of data and functionalities.
   It design is based on the idea of the `Entity`: any thing that can be 
   unambiguously identified and be subject of investigation. Examples of
   entities are: genes, proteins, SNPs, samples, pathways, etc.
 
-  Each entity has a report, which depends on the type of entity it is. 
-  All reports are computed on the fly and cached. In addition to the main
-  report, entities have `actions`, which are sub-reports that implement
-  particular analysis. For instance, for gene entities, one of the actions
-  is to display a summary of the relevance of that gene across the collection
-  of studies that you have access to.
- 
-  ## Miscellaneous comments
- 
-  ### A word on performance
+  Each entity has a report, which depends on the type of entity it is.  All
+  reports are computed on the fly and cached. In addition to the main reports,
+  entities have `actions`, which are sub-reports that implement particular
+  analysis. For instance, for gene entities, one of the actions is to display a
+  summary of the relevance of that gene across the collection of studies that
+  you have access to. In addition to entities, there are reports for lists of
+  entities and for entity maps, which are tables that relate entities to values, 
+  such as genes to their average mutation frequency. 
 
-  This application is intended to allow interactive investigation. But be
-  aware, some analysis are slow and will not feel that much interactive.  Some
-  process may require plenty of infrastructure: downloading of datasets,
-  building databases, computing preliminary results, etc. A lot of this
-  processing is reused system-wide. This means that the application starts slow
-  but gets quicker. Unlike other applications with a more limited scope this
-  system cannot foresee what the user will be interested in, so not all this
-  infrastructure can be built before hand and must be built on demand.  We pay
-  a price for flexibility by sacrificing responsiveness. But the system has
-  plenty of tricks to be as efficient as possible and to reuse as much as
-  possible.
-
-  ### Entity annotations
-
-  The `Entity` subsystem annotates identifiers for entities with additional information
-  to help their complete and unambiguous identification.
-
-  #### Organisms and builds
-
-  When you identify a gene with the string `TP53` we might think that the gene
-  is unambiguously identified, however, it is not. First of all, we need to
-  know to which organism this gene belongs to, each TP53 gene from different
-  organisms is a different gene. Not only that, but the TP53 gene changes
-  slightly from build to build, in particular, its chromosomal position may
-  shift. For that reason genes are not only characterized by the organism they
-  belong to but also by the version of the build we are considering.
-
-  We annotate entities with their organism and build using the following
-  convention.  The organism is specified with a three letter code, the first is
-  uppercase and is the first letter of the first term in the organism name ("H"
-  for Homo) and the last two the first two letter of the second term ("sa" for
-  sapiens); this is the convention followed by KeGG, it is succinct and
-  collision free in our experience.  The build is specified afterwards with a
-  date code; "Hsa/may2009" represents the _Homo s._ organism as was known in
-  May 2009 i.e. hg18 build; whereas "Hsa/jan2013" corresponds to a recent
-  version of the hg19 build.
-
-
-  #### Identifier formats
-
-  Genes can be identified through a substantial number of identifier formats:
-  Ensembl Gene ID, Entrez Gene ID, Associated Gene Name (gene symbol). We use
-  the Ensembl BioMart to download an identifier translation resource. The name
-  of the formats corresponds to the names used in the Ensembl BioMart and must
-  be *followed to the letter including case*. The gene `Entity` is prepared to handle all the
-  necessary translations between identifiers across different resources
-  transparently. But the user *must* be aware of this fact or may run into
-  trouble.
+:markdown
+  ##User interface
 
+  The user interface offers a general structure for all reports that allows to
+  enact workflows, explore the results and connect functionalities with one
+  another.  This web site is 'responsive', meaning that it adapts to the size
+  of the device you are using: computer, tablet, or phone. On small devices many
+  of the layout elements shift around or get hidden behind toggle buttons to
+  acomodate themselves better to the screen size. The examples bellow are taken
+  from a computer screen.
 
-%h2 Subsystems
-%ul
-  %li 
-    %a(href='/help/entity' class="help") Entity subsystem
+=partial_render('help/UI') 
 
-  %li 
-    %a(href='/help/workflow' class="help") Workflow subsystem
+:markdown
+  ##Workflows
+
+  In addition to exploring entity reports, this site servers collections of
+  core functionalities through the Workflow subsystem. This is the same
+  interface that is used as a REST web server, so it serves to document it.
+
+
+%table
+  %caption Available workflows on this site
+  %thead
+    %tr
+      %th Workflow
+      %th Description
+  %tbody
+    - Sinatra::RbbtRESTWorkflow::WORKFLOWS.each do |workflow|
+      - next if workflow.asynchronous_exports.empty? and workflow.synchronous_exports.empty? and workflow.exec_exports.empty?
+      %tr
+        %th
+          %a(href="#{'/' << workflow.to_s}")= Misc.humanize(workflow.to_s)
+        %td
+          - description = workflow.workflow_description || ""
+
+          - case
+          - when description.empty?
+            No description
+          - else
+            = description.split("\n\n").first

data/share/views/help/UI.haml

@@ -0,0 +1,250 @@
+%dl.tabs.UI.active
+
+  %dt.next.active.show Report structure
+  %dd.show
+    .description
+      :markdown
+
+        This application presents reports for individual entities, lists of
+        entities, and entity maps. Each type of entity (gene, study, pathway, etc.)
+        has its own report template, and they are prepared on demand.
+        
+        All reports have the same overall structure; the images show a report
+        for a genotyping study from the ICGC project. The top-bar is always
+        there and provides a placeholder for several functionalities, most
+        importantly the control of `favourites`. 
+
+        
+        Bellow the top-bar comes the report itself. It consists of a title, a
+        side-bar, a description, and an `action controller`. In general the
+        side-bar is used to show general meta-data about the entity and the
+        description to show a brief overview. 
+        
+        The action controller offers access to `actions` which are like
+        sub-reports. Each type of entity has its own actions. If the entity
+        type in particular does not have any action defined the action
+        controller will not be displayed. When an action is selected, it will
+        be displayed below, in the area called action loader. 
+
+        Actions can also be opened in their own page, these pages are like reports
+        but with no action controller or side-bar
+        
+    .images
+      %dl.tabs.active.show
+        %dt.next.show Snapshot
+        %dd.show
+          %img(src="/img/UI/report.png")
+
+        %dt.next Explanation
+        %dd 
+          %img(src="/img/UI/report_wire.png")
+
+
+  %dt.next Top-bar
+  %dd
+    .description
+      :markdown
+
+        The top-bar provides access to several functionalities. Clicking on the
+        title of the application will link to its front-page.
+        
+        Next to it is the reload-button, which is used to force the server to
+        recalculate a report, otherwise the report will be taken from a cache.
+        This is useful when a report has given an error or when when it was
+        updated somehow. *Note:* After a reload of the report, the browser might
+        still try to get the file from its own cache, so you might need to use
+        the reload button in the browser as well. I'm planning to fix this.
+
+        Next is the `favourites` controls, which we will discuss shortly. After
+        that there might be a search box, if the server was started with that
+        functionality. This search box can be configured to identify any type
+        of entity, but generally it is only genes.
+
+        The final component of the top-bar, which I label "Extra", has the user
+        controls, which allows to login or logout, and the job bookmarks,
+        where bookmarked actions are kept. Will discuss bookmarking actions
+        latter.
+
+    .images
+      %dl.tabs.active.show
+        %dt.next.show Snapshot
+        %dd.show
+          %img(src="/img/UI/topbar.png")
+
+        %dt.next Explanation
+        %dd 
+          %img(src="/img/UI/topbar_wire.png")
+
+
+  %dt.next Favourites
+  %dd
+    .description
+      :markdown
+
+        As we said before, we have reports for entities, lists, and maps.
+        Clicking the star on the favourites control makes a favourite out of
+        what-ever we are viewing: an entity, like a study; a list of entities,
+        such as the genes mutated in the study; or a map, which could for
+        instance map genes to the ratio of mutations per amino-acid in the
+        COSMIC database.
+
+        Favourites are used not only to track our interests, but as a means to
+        communicate between different functionalities or parts of the
+        application. We could for instance make a list of genes a favourite and
+        then go to a study report, open the "Gene list in study" action, select
+        our list from all the favourites and see a report of how these genes
+        are affected in the study
+
+        The favourite controls have an option to create a new list of entities
+        from scratch. This allows a user, for instance, to make a list with her
+        genes of interest instead of having to browse the application to find
+        it. *Note:* New lists are not made favourite be default, you still need to
+        click on the star once the report is shown.
+
+
+    .images
+      %dl.tabs.active.show
+        %dt.next.show Snapshot
+        %dd.show
+          %img(src="/img/UI/favourites.png")
+
+        %dt.next Explanation
+        %dd 
+          %img(src="/img/UI/favourites_wire.png")
+
+
+  %dt.next Actions
+  %dd
+    .description
+      :markdown
+
+        Actions are the primary way to integrate data and functionalities.
+        Some actions are defined globally, but most commonly they are defined
+        inside workflows; when a report is produced, all workflows are
+        interrogated to see if they provide actions for it. The great majority
+        of the actions are defined in the `Genomics` workflow.
+
+        When an action is selected, it loads bellow the action controller. An
+        action report consists of the content of the action, and optionally,
+        parameter controls and an action description. When the action is loaded
+        inside a report the parameter controls and description are hidden, but
+        they can be shown using the action control buttons in the top left.
+        Actions can also be opened in their own report by right clicking on its
+        button.
+
+        As with all reports, they are executed the first time they are
+        requested and the result is cached for further access. The action
+        control buttons can be used to reload the action, just like the reload
+        button in the top-bar does for the complete report. The actions will
+        of-course be recomputed for each configuration of parameters. The
+        parameters of the action can be favourites from the user, lists or
+        maps. These are presented to the user using an input `select`, and are
+        synchronized with the user current favourites.
+
+        If an action is used often with a particular combination of parameters.
+        For instance the "Enrichment" action of gene lists performs an
+        over-representation based analysis of functional classes. The
+        functional classes include several pathway databases, protein domains,
+        gene ages, etc. If we where interesting in performing enrichment
+        analysis using GO biological process terms, we can use the paperclip
+        button to set that configuration of parameters as default so that it
+        always uses it initially.
+
+        Some actions may require a significant amount of time to compute. The
+        action controller tries to reload the action periodically until it is
+        completed. Instead of having to wait on that page for it to finish, the
+        user can click on the bookmark button, which will place a link in the
+        "jobs" tab on the "Extra" menu of the top-bar, and come back to it
+        later.
+
+    .images
+      %dl.tabs.active.show
+
+        %dt.next.show.active Action Snapshot
+        %dd.show
+          %img(src="/img/UI/actions.png")
+
+        %dt.next Action Explanation
+        %dd 
+          %img(src="/img/UI/actions_wire.png")
+
+        %dt.next Controller Snapshot
+        %dd
+          %img(src="/img/UI/action_control.png")
+
+        %dt.next Controller Explanation
+        %dd 
+          %img(src="/img/UI/action_control_wire.png")
+
+
+  %dt.next Tables
+  %dd
+    .description
+      :markdown
+
+        Tables in this application come enhanced with several functionalities.
+        The rows can be sort by the values of any column. 
+        
+        The values of the columns can also be used to filter the rows of the
+        table through the `filter` button. The filters are defined per-column,
+        and can contain exact strings, regular expressions like
+        `/(COMPLETE|PARTIAL) RESPONSE/i`, statements such as `> \< ==` or `!=`.
+        And, for columns containing entities they can be prefixed with the term
+        `name:` to force the filtering to work over the human readible text of
+        the entities e.g. `name:/SF3B\d+/` for a column containing 'Ensembl
+        Gene ID'.
+
+        When a column contains entities, these are usualy listed in the table using
+        some identifier like 'Ensembl Gene ID' for genes or 'GO Term IDs', etc. When
+        displaying the table, it automatically substitutes these identifiers with
+        links to their corresponding reports, and lists them by name. Additionally
+        the `column` button allows the user to report the list of entities of any column
+        or, if the first column is itselve an entity, it allows the user to report
+        the `map` between the entities in this column and the values of any other column.
+        Maps are generally used as inputs to actions and tools.
+
+        The content of the table can be downloaded in two forms, as TSV files,
+        which is the original source of the table, or as Excel files. When
+        downloding as Excel files, since are generally intended to be read by
+        people, all entities listed that can be translated to a more human
+        readible identifier are translated automatically. This includes change
+        genes identifiers from `Ensembl Gene ID` to `Associated Gene Name`, or
+        changing KEGG pathway ids to their descriptive name.
+
+    .images
+      %img(src="/img/UI/table.png")
+
+
+  %dt.next Tools
+  %dd
+    .description
+      :markdown
+
+        Some workflows implement `tools`, which provide special interactive
+        visualization for different types of data. For instance: the `Graph`
+        workflow implements the `cytoscape` tool, which is used to display
+        different kinds of entities connected through databases or analitical
+        results; the `Structure` `jmol` tool displays mutations in the
+        secondary and tertiary structures and complexes; and the `D3Js`
+        workflow that implements a tool to display `d3js` interactive SVG
+        figures. Alternative R is used through a native interface in Rbbt to 
+        display plots using `ggplot2`.
+
+        These tools are used by different reports and actions. The `Graph`
+        workflow for instance redefines the template for `Gene` lists to
+        include a cytoscape plot to the description section of the report.
+        
+
+    .images
+      %dl.tabs.active.show
+        %dt.next.show Cytoscape
+        %dd.show
+          %img(src="/img/UI/cytoscape.png")
+
+        %dt.next Jmol
+        %dd 
+          %img(src="/img/UI/jmol.png")
+
+        %dt.next D3Js
+        %dd 
+          %img(src="/img/UI/d3js.png")

data/share/views/help/workflow.haml

@@ -1,7 +1,7 @@
 :markdown
 
   The Workflow subsystem
-  ===================
+  ======================
 
   The workflow subsystem is used to package related functionalities and
   offer a common, flexible, interface.  Each workflow is composed of a

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rbbt-rest
 version: !ruby/object:Gem::Version
-  version: 1.2.34
+  version: 1.2.35
 platform: ruby
 authors:
 - Miguel Vazquez
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-18 00:00:00.000000000 Z
+date: 2013-12-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -255,6 +255,7 @@ files:
 - share/views/error.haml
 - share/views/form.haml
 - share/views/help.haml
+- share/views/help/UI.haml
 - share/views/help/entity.haml
 - share/views/help/workflow.haml
 - share/views/job_info.haml
@@ -284,6 +285,20 @@ files:
 - share/views/partials/table/filters.haml
 - share/views/partials/table/page.haml
 - share/views/public/favicon.gif
+- share/views/public/img/UI/action_control.png
+- share/views/public/img/UI/action_control_wire.png
+- share/views/public/img/UI/actions.png
+- share/views/public/img/UI/actions_wire.png
+- share/views/public/img/UI/cytoscape.png
+- share/views/public/img/UI/d3js.png
+- share/views/public/img/UI/favourites.png
+- share/views/public/img/UI/favourites_wire.png
+- share/views/public/img/UI/jmol.png
+- share/views/public/img/UI/report.png
+- share/views/public/img/UI/report_wire.png
+- share/views/public/img/UI/table.png
+- share/views/public/img/UI/topbar.png
+- share/views/public/img/UI/topbar_wire.png
 - share/views/public/js/_ajax_replace.js
 - share/views/public/js/_ellipsis.js
 - share/views/public/js/_md5.js