Tutorial Brainstorming

[thinkh]

The Tutorial Section provide easy to read and replicated code snippets for newcomers.

I suggest a small project that is growing with every section, such as in the Angular 2 Tutorial. Every subsection covers a specific topic or part of the framework. We might also adapt these paragraphs for every subsection:

• "Where We Left Off" briefly explains the status of the last subsection and how to proceed
• "The Road We’ve Travelled" summarizes the subsection and functionality
• "The Road Ahead" gives an outlook for the next subsection

A list of topics that should be covered by the documentation:

• Introduction: Introduce the scope and topic of the project, shows the finished stage
• D3 visualization: Simple, self-contained D3 example, that is used in conjunction with Caleydo in the next step
• Caleydo Web Library: Visualize a matrix from a data array or (externally hosted) CSV file
• Visualization Switcher: Switch between different types of visualizations
• Multiple visualizations: Create multiple instances that work for the same dataset
• Selections: Explain how to select elements, broadcast and react on selections
• Caleydo Web Server: How to install the server side that provides data for the client
• Use Data Provider: Add new data (HDF, CSV, ...) to the server and adapt the visualization

Please comment, if you have further ideas. I will add them to the checklist later.

[alexsb]

I think this is great. For step 2, should we use pre-configured visualizations out of caleydo web? I'd prefer a simple, self-contained d3-example first. And then an example how to do this with a standard caleydo web view.

[thinkh]

@alexsb I think that's a good idea. I added your point to the list.

[thinkh]

I haven't checked that mini_mds example out, but maybe it is a useful basis for the tutorial.

[mstreit]

The plan is to create the following tutorials:

• how to use the library version only (see above)
• how to create an app (see https://github.com/Caleydo/caleydo_template_app)
• how to create a client plugin (see https://github.com/Caleydo/caleydo_template_server_plugin)
• how to create a server plugin (see https://github.com/Caleydo/caleydo_template_client_plugin)
• how to CLUEify an existing application

[mstreit]

@mccalluc: Do you plan to also include the JSFiddle in the library only tutorial?
http://www.caleydo.org/documentation/tutorial/web_bundle/

[mccalluc]

Maybe? With things somewhat in flux right now, I'd be reluctant to have to manage code samples outside version control. When it seems stable, perhaps for the final example that wraps it all together? But I'd like a clearer sense of what we get from it... Does it suffice to have an easy checkout of the samples, or is the in-browser editing part of the sell?

(TLDR: procrastinating on this particular question.)

[thinkh]

Sub-setting a dataset

• if it does not work parseRemoteMatrix does not work, remove it from the later tutorial steps for now and stick to Caleydo.d3.parser.parseMatrix
• use a sub-set of the same matrix and feed it into two different visualizations (use ranges as in matrix example
• show/emphasize the automatic selection propagation between these visualizations (should work out-of-the box) --> further background infos for you
• create a second matrix with the same row_ids but different column_ids
• pass each matrix to one of the two visualization --> result the selections should still be linked (should work out-of-the box)
• create a "range selector" (or "sub-set selector") with a from and to input field for each rows and columns
• when the input field changes -> update connected matrix visualization

Build dataset chooser

• append the matrix to the data set list (use Caleydo.core.data.create())
  • create matrix description? (i'm not sure here; you might have to implement a function)
• build a drop down using the data from Caleydo.core.data.list() (example: https://github.com/Caleydo/taco/blob/master/data_set_selector.ts)
  • Unfortunately the library version calls the server, which does not work
    --> work around: set Caleydo.core.main.offline = false before calling data.list()
  • TODO we could fix this by providing a valid Caleydo API backend or set it offline by default
• Update the visualization on selecting a dataset (example: also https://github.com/Caleydo/taco)

Further ideas

• scale and rotate heatmaps
• create visual links (in caleydo_d3)
• show how Caleydo.core.layout.* works

[mccalluc]

@thinkh:

when the input field changes -> update connected matrix visualization

I feel like I might be missing something here. So far, I know how to create visualizations like

multiform.create(matrix, $target[0])

Naively, if I wanted to update that, I'd destroy that one and call the same method again, with a different value for matrix... but is there a better idiom? Something like mutating the matrix object, or calling something on the visualization to update the backing data?

[thinkh]

No, you don't have to mutate the matrix object. The selection for the default visualizations work out-of-the-box. However, there was a CSS style missing to highlight the selection (the CSS class have been set before). Maybe that solves your problem?

I forgot to mention, that I have to update the CSS of the library on S3.

[thinkh]

I updated the library files at S3. The selection is now highlighted in the tutorials.

[mccalluc]

Not clear what is actionable here. If there should be a bug, please open a new one under Phovea.