Code Monkey home page Code Monkey logo

ili's Introduction

`ili

`ili is a visualization app for 3D molecular cartography. For more information about the molecular cartography, please see our recent protocol paper Protsyuk et al. (2017) Nature Protocols.

`ili is being developed mainly by Alexandrov Team at EMBL Heidelberg (contact information) in collaboration with the Dorrestein Lab and the Knight Lab at UCSD.

  • Developers: Ivan Protsyuk, Sergey Ryazanov, Richard Goater
  • External contributors:
    • Members of Knight lab: Antonio Gonzalez, Jamie Morton, Jose Navas, Yoshiki Vázquez Baeza
    • Members of Atomicus: Alexei Dolgolyov, Konstantin Senkevich, Violetta Nebyshinets
  • Principal investigator: Theodore Alexandrov

Table of contents

Hello bee

For a demonstration, open

       Screenshot of the human example

  • 3D bee example (data provided by Yi Zeng from the Dorrestein Lab, UCSD)

       Screenshot of the bee example

       Screenshot of the 3dmassomics example

Examples from real-life studies

On this page you can find examples of `ili being applied in research.

Installation

The best ways of running `ili are either from this website or as a Chrome extension.

Input

`ili takes two files:

  • for 2D mapping: a PNG or JPG file to be used as the background image (example), and a mapping file with intensities and coordinates in CSV format (example)
  • for 3D mapping: a 3D model in STL format (example), and a mapping file with intensities and coordinates in CSV format (example)

To create a mapping file suitable for input, you need two pieces of information: coordinates of your samples on your picture/model and intensities of features you're going to visualize in `ili. Please find the instruction on how to create a CSV table with coordinates here. Rows of the result table correspond to samples. Once you have it, you can add your features as new columns. Finally, you need to save it as a CSV file, and it is ready to be viewed in `ili. Refer to the examples above to have an idea of the final look of the table.

How to use it?

One of the fundamental ideas behind the `ili interface is the simplicity of usage. Therefore, most operations can be performed with keyboard shortcuts.

Action Shortcut on Windows, Linux Shortcut on OS X Alternative
Open files Ctrl+O +O Drag and drop files to `ili window. Also, when you just launched `ili, you can press Open button at the center of the window.
Switch between molecular maps Ctrl+, Ctrl+ + , + Click on a name of an active map above a colorbar at the right-bottom corner of an app window and select another map with mouse.
Find a molecular map by its name Ctrl+F +F Click on a name of an active map above a colorbar at the right-bottom corner of an app window and start typing.
Save view as image Ctrl+S +S NA
Save cartographical snapshot Ctrl+E +E NA

Many other controls for adjusting visualization are available in the `ili sidebar. Three main sections there "2D", "3D" and "Mapping" correspond to settings affecting 2D/3D views and colormaps.

Mouse buttons can be used to adjust point of view on a model/picture.

Action Mouse button Views where available
Rotate model Move mouse holding its left button 3D
Move image Move mouse holding its left button 2D
Zoom Rotate mouse wheel 2D, 3D
Display spot name Click at a spot with left button 2D, 3D
Move model Move mouse holding its right button 3D
Enable/disable model auto-rotation Double-click 3D

Demo

You can find a list of ready-made examples in the "Examples" tab in the `ili sidebar. Click on any of them, and necessary files will be loaded to the app automatically.

3D models with texture

In addition to plain models in STL format, `ili also supports 3D models in OBJ format, which can be visualized with textures on top of them. As a prerequisite for that, textures must be saved as images in PNG or JPG format associated with a material definition file in MTL format. Thus, at least three files are needed to visualize a 3D model with texture in `ili: model in OBJ format, material definition file and a texture image. All these file types are compatible with other input files, e.g. mapping files or cartographical snapshots, and can be opened in `ili using regular actions, like drag&drop.

One can find a 3D model of a coral and texture for it here (courtesy of John Burns, University of Hawaii) as an example of appropriate input files for `ili.

Cartographical snapshots

`ili facilitates reproducible data analysis by providing the feature of cartographical snapshots: a complete copy of all visualization settings saved to a file. The file can be reused later or shared with other users, who, afterwards, will be able not only to recover the same view, but also use it as a starting point for further analysis.

The cartographical snapshot is a file in JSON format that can be opened in `ili using drag&drop along with corresponding files of 3D model/image and spatial mapping.

Permanent links to `ili visualization

It is possible to create permanent web-links to `ili visualizations, which can be shared with other people or included into publications, without explicit sharing of the input files. In order to do that, one needs to deposit all necessary input files (model/picture, mapping file and cartographical snapshot(s)) to a public data repository, which can be one of recognized resources in a specific field (e.g. MassIVE, MetaboLights, etc) or an ordinary FTP server. The only requirement to the storage is it should allow downloading files without any authorization. After all the files are uploaded to the storage, a permanent link to `ili visualization can be composed by chaining all links to the files into a single URL, which starts with the `ili address (https://ili.embl.de) followed by question mark and all file links separated by semicolon. Example: https://ili.embl.de/?ftp://massive.ucsd.edu/MSV000081081/updates/2017-05-15_mernst_9ac10437/peak/EHorrida_20160915_Model3_withroots.stl;ftp://massive.ucsd.edu/MSV000081081/updates/2017-05-15_mernst_9ac10437/peak/EHorrida_Model3_features.csv . The order of the files does not matter. Links to visualization of different features in the same dataset or different visualization settings can be created by using different cartographical snapshot files. More examples can be found in the list of studies, where `ili was used.

Any questions?

Feel free to leave your questions and suggestions as issues in this repository or at the "Support" section on the `ili page at Google web store.

How to stay updated

Please sign up to the mailing list by sending an email to [email protected]

Miscellaneous

  • Why is it called `ili? `ili in Hawaiian means skin and, among others, surface, area, or cover.
  • How to record videos or screencasts in `ili? Please use a third-party software, for example ScreenCastify plugin to Chrome
  • How can I cite `ili in my scientific publication? Please cite Protsyuk et al. (2017) Nature Protocols.

License

The content of this project is licensed under the Apache 2.0 licence, see the license file.

Funding

This project is funded from the European projects 3D-MASSOMICS (FP7 HEALTH program, grant agreement no. 305259), METASPACE (Horizon2020 program, grant agreement no. 634402) and from the internal funds of the European Molecular Biology Laboratory.

ili's People

Contributors

andy-d-palmer avatar antgonza avatar dolgolyov4000 avatar eldeveloper avatar iprotsyuk avatar lmacielvieira avatar richardgoater avatar senkevich4000 avatar sonicxconst1 avatar sryazanov avatar theodev avatar vviolka avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

ili's Issues

Better file parsing diagnostics

Currently the user could be notified when something goes wrong in file parsing (csv, stl, png) but it works inconsistently. If file has completely wrong format there is no notification. It's confusing (like in #11).

hotspot quantile makes spots transparent

Jeramie example, map 997.1115

changing the hs-quantile from 1 to any other value (e.g. 0.99) makes most of spots (having the same intensity) transparent, whereas it should change only the colors of spots with highest intensities

Make the menus more intuitive

You can change the values being displayed by clicking on the bottom right of the screen. This is not intuitive for common users - at least it wasn't for me.

Set intensity values corresponding to the first/last colors in the colormap

To set values corresponding to the first/last colors in the colormap.

Use-case: render two (or more) maps with comparable colors
1. have a look at two maps, write down min (m) and max (M) intensities across both of them
2. set values of the first/last color from auto to the m and M
3. plot each map separately, export each map into a PNG file
4. switch the mode into "auto"

support for tsv data files

csv is fine for most purposes, but some of my category labels have commas, which I have to change to periods or something else. Support for tsv files would be a convenient solution.

Global shortcuts for map selection

Currently the user needs to open MapSelector to change map. Since it's expected to be important operation we want to let changing a map from any context.

In addition to up/down/page-up/page-down key strokes to handle Ctrl+* strokes. Ctrl variant differ in the following way: it works in global context (whatever focus in, except opened combobox - platform limitation) and and if MapSelector isn't active it shows it shortly with 0.1 opacity (to give the user sense of conntext).

Ctrl+page up/down is intercepted by browser and won't work in a web page.

Some explanation regarding showing the MapSelector. Result of up/down depends on current filter. If we ignore the filter on Ctrl-... it would be confusing. If we apply the filter now showing it's applied it also may be confusing.
If we handle up/down globally (without Ctrl) we may interfere with dat.gui and cause the same sort of confusing that OrbitController caused with lighting. Ctrl gives some sort of uniformity - it's how we handle context independent shortcuts.

Easy way to place 3d point on model

Currently, there is no easy documentation or tool about how to place the 3D points (where the sample was taken). This info/tool will improve usability for non experts.

flip color map

It would be really nice to have a checkbox to flip the color map. For example, RdBu goes red-white-blue, but if I want high values to be red and low values blue, I need a color map that goes blue-white-red. Flipping the color map, or adding a BuRd color map if one exists, would allow for this.

Easy way to create models

Currently, there is no easy way to create models. The only options are to use a 3D scanner or buy a model. One option is to have a stl library with common models and perhaps a tutorial about how to modify or create your models.

Test issue

The issue is created to check the synchronization between GitHub and Asana using Zapier.

add front light in 3D

...with another slider of intensity “Front light” in “3D” dat.gui

the front light is the light with the coordinates equal to the coordinates of the camera

for multiple views, either: multiple lights, or the light only for the first view (what's easier)

Test issue

The issue is created to check the synchronization between GitHub and Asana using Zapier.

Export viewpoint in high resolution

At this moment you can only do a print screen (mac cmd-s). It will be great to generate high res images, like svg or pdf. The latter should be preferred.

Scale to the point (2D)

User should be able to zoom to a point of interest.

Now scaling with mouse wheel preserves point at the center of the screen.

Default zoom

When new image or mesh loaded appropriate view should take appropriate zoom factor for current layout and image/mesh size.

Test issue

The issue is created to check the synchronization between GitHub and Asana using Zapier.

Spot labels in 3D

with radius offset along x, y, and z i.e. at (x+r,y+r,z+r). Some labels will not be visible (hidden by the model), but this is fine

Separate input values files

Currently, in the same file you need to have the 3D value point and the values to plot in the model. I think a better way to go about this is to have:

  • The model (stl)
  • The sample names and position in 3D (csv) -- we could even perhaps merge this and the previous one
  • Multiple input formats where you have different information (rows vs features).

I believe this will be more convenient because the first 2 only are needed once but the 3rd kind can hold different kinds of values and could constantly change: family or species level taxonomic information, metobolomics, PCoA axes, etc.

[enhancement]: mouse-over shows tool tip/link

Can a mouse-over be easily implemented that shows the label of data points and provides a html link to another webpage?

perhaps this could be implemented with html code embedded in the data labels

2d data load fails

files: lung.csv/lung.png from demo
system: OSX 10, chrome Version 42.0.2311.135 (64-bit)

to reproduce: drag-drop pair of files into browser
result: data fails to load, see screenshot for log
screen shot 2015-05-04 at 14 00 48

webpage freezes when using Ctrl-s for a large dataset

dataset (15K spots) in the db, example_2D_Jeramie/bugreport. Ctrl-s of any map eats 1GB memory, second Ctrl-s (either the same or another map) eats 7GB memory, third Ctrl-s normally has not enough memory and freezes the webpage.

using a smaller PNG (e.g. 50% x, 50% y) doesn't help

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.