pages/auto/visual.html

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
"https://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!--  -->
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="application/xml+xhtml; charset=UTF-8"/>
<title>enclone visual</title>
<link rel="stylesheet" type="text/css" href="../enclone_css_v2.css">
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-58278925-3"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){{dataLayer.push(arguments);}}
gtag('js', new Date());
gtag('config', 'UA-58278925-3');
</script>

        
        </head>

        <! ––

        💩 💩 💩 🔴 🔨 🔨 🔨 🔨 🔨 🔨 🔴 💩 💩 💩

        PUT DOWN YOUR HAMMER.
        THIS IS AN AUTO-GENERATED FILE.  PLEASE DO NOT EDIT IT.
        THANK YOU FOR YOUR COOPERATION,

        SINCERELY,
        THE BENEVOLENT OVERLORDS

        💩 💩 💩 🔴 🔨 🔨 🔨 🔨 🔨 🔨 🔴 💩 💩 💩

        ––>

<body>

<br>
<a href="../../index.html#help">
<img src="../../img/enclone_banner.png" alt="enclone banner" title="enclone banner" width=100% />
</a>

<! --- ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ --->

<h1>enclone visual</h1>

<p>
<span style="color:rgb(120,123,175);font-weight:900">enclone visual</span> is a graphical user
interface (GUI) for <span style="color:rgb(120,123,175);font-weight:900">enclone</span> that can be run on a Mac or Linux or Windows computer.  It allows for 
simultaneous viewing of clonotype tables and graphical objects such as honeycomb plots that 
<span style="color:rgb(120,123,175);font-weight:900">enclone</span> can create, and has several other features that you may find convenient.
</p>

<p style="border: 2px; border-style: solid; border-color: black; background-color: #EBF4FC;
padding: 8px; width: 900px; font-size: 110%">

<span style="font-size:130%">
<b>Please note that <span style="color:rgb(120,123,175);font-weight:900">enclone visual</span> is alpha (α) software!</b>
</span>

<br>• Users <i>may</i> encounter bugs that we are unable to fix.  This is in part because different
operating system versions may yield different behavior, and we may be unable to replicate such 
problems.

<br>• There are a few features of <span style="color:rgb(120,123,175);font-weight:900">enclone</span> that are not properly delivered in
<span style="color:rgb(120,123,175);font-weight:900">enclone visual</span>.  Notably, clonotype
tables are in black and white rather than color.  To fix this, we are waiting on code changes
from developers outside 10x, and do not have a timeline for those changes.

<br>• Because of considerable
variability between Linux configurations, we anticipate that there may be problems with Linux.
Please see the debugging under Linux section, below.  
</p>

<! --- ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ --->

<h2>Getting started</h2>

<p><b>1.</b> To use <span style="color:rgb(120,123,175);font-weight:900">enclone visual</span>,
follow the installation instructions for <span style="color:rgb(120,123,175);font-weight:900">enclone</span>.  Choose the <code>medium</code> or a larger
option.  Then open a terminal window, and type <code>enclone VIS</code>.  An 
<span style="color:rgb(120,123,175);font-weight:900">enclone visual</span> window should appear.</p>

<p><b>2.</b> The operating system will intercede and ask if you will allow certain kinds of
access.  This may include asking for permission to capture the screen, which you should allow, and 
then restart your Terminal.
This <i>should</i> be a one-time operation.  The reason for needing access is
that upon pushing certain buttons, <span style="color:rgb(120,123,175);font-weight:900">enclone visual</span> will do a screen capture of the 
<span style="color:rgb(120,123,175);font-weight:900">enclone visual</span> window and copy that to your clipboard.</p>

<p><b>3.</b> 
<span style="color:rgb(120,123,175);font-weight:900">enclone visual</span> is primarily <b>command driven</b>.  This means that you still need to formulate an
<span style="color:rgb(120,123,175);font-weight:900">enclone</span> command!  It also means that <span style="color:rgb(120,123,175);font-weight:900">enclone visual</span>
commands can be reproduced in <span style="color:rgb(120,123,175);font-weight:900">enclone</span>, and, for example, scripted.  The commands for 
<span style="color:rgb(120,123,175);font-weight:900">enclone visual</span> are similar to, but not identical to <span style="color:rgb(120,123,175);font-weight:900">enclone</span> commands.  There are two differences:
<ul>
<li>In a plot argument, instead of putting in the name of an image file, you put in the text
<code>gui</code>.  This is illustrated below.</li>
<li>For <span style="color:rgb(120,123,175);font-weight:900">enclone visual</span>,
you do not have to quote (<code>"..."</code>) special characters, although arguments containing
blanks do still need to be quoted.</li>
</ul>

<! --- ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ --->

<h2>Read the help!</h2>

<p>In the <span style="color:rgb(120,123,175);font-weight:900">enclone visual</span> window, you will see a <code>Help</code> button.  Please push that button
and <b>read the help text there</b>.  This will take you about five minutes, and then you'll 
understand how the system works.  Some of the behavior is counterintuitive but easily grasped.</p>

<! --- ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ --->

<h2>Read the cookbooks!</h2>

<p>Push the <code>Archive</code> button.  You will see the following (without the red coloring
of the Snapshot button, which is how we captured the image):
<br>
<img src="../../img/visual_archive1.png" style="max-width: 80%" lt="enclone visual archive" 
title="enclone visual archive">
<br>
If you later save <span style="color:rgb(120,123,175);font-weight:900">enclone visual</span> sessions, they will appear as entries on this page.  For now,
there are only two entries, which are built-in cookbooks.  Please expand and read the documentation.
Then for each cookbook, in turn, check the <code>restore</code> box, push <code>Dismiss</code> to 
return to the main window, and work your way through.</p>

<! --- ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ --->

<h2>An example</h2>

<p>Here we show an example.  You would have seen this in the cookbooks, but we show it here too.
(Note that the outputs here may change over time as <span style="color:rgb(120,123,175);font-weight:900">enclone</span> is updated.)
Enter this command
<code>enclone BCR=123085 HONEY=out=gui,color=var,u_cell2</code> in the command box.
This will display a honeycomb plot showing all cells, colored by the variable <code>u_cell2</code>,
which is the UMI count for the second chain (relative to the numbering of columns in a given
clonotype).  The "undefined" cells arise from the case where there is no second chain.  Note that 
you could arrange to instead color by almost any variable that you can imagine!
</p>

<p>
You will see something like this:
<img src="../../img/visual1.png" style="max-width: 80%" lt="enclone visual example" title="enclone visual example">

<br>
This is the basic view.  Now suppose that you want to see only part of this view, for example
just the plot.  Push the <code>Pic</code> button.
<img src="../../img/visual2.png" style="max-width: 80%" lt="enclone visual example 2" title="enclone visual example 2">

<br>
Now if you push the <code>Dismiss</code> button, you'll be back to the main page.</p>

<p>Suppose that you now wish to reproduce the same plot from the command line in a terminal
window.  In the command <code>enclone BCR=123085 HONEY=out=gui,color=var,u_cell2</code>,
you would change <code>gui</code> to the name of a file (or path), ending with either 
<code>.svg</code> or <code>.png</code>, depending which you prefer.  For example, you could use
<code>enclone BCR=123085 HONEY=out=plot.svg,color=var,u_cell2</code> to put the plot output
of the command into a file <code>plot.svg</code>.  You could also to add the argument
<code>NOPRINT</code>, if you do not want to see the standard output (clonotype tables) that
<code>enclone</code> generates.</p>

<! --- ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ --->

<h2>States and sessions</h2>

<p>When you run a series of commands in <span style="color:rgb(120,123,175);font-weight:900">enclone visual</span>,
you create a series of <i>states</i>, and you can navigate instantaneously between those states 
using the up and down arrows on the right side of the window, which become visible only as you 
create multiple states.  You can also delete states that you're not interested in, and you can
annotate them with comments.</p>

<p>All these states comprise a <i>session</i>.  You can save your session by clicking on the
<code>Save</code> button.</p>

<p>When you're done, you can push the <code>Exit</code> button to leave <span style="color:rgb(120,123,175);font-weight:900">enclone visual</span>.
If you saved your session, then you can restart <span style="color:rgb(120,123,175);font-weight:900">enclone visual</span>
later, push the <code>Archive</code> button, and then restore your previously saved session.  
These saved sessions can also have names and narratives associated to them.</p>

<! --- ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ --->

<h2>Creating a session from the command line</h2>

<p>It is possible to create a session outside <span style="color:rgb(120,123,175);font-weight:900">enclone visual</span>, from the <span style="color:rgb(120,123,175);font-weight:900">enclone</span> command
line.  For example, this command
<pre><code>enclone BCR=123085 PLOT=gui VIS_DUMP SESSION_NAME="123085 test"</code></pre>
will create a session in <code>~/enclone/visual/history</code> which has a single state
corresponding to the given command.  The <code>SESSION_NAME</code> argument is optional.
One may also specify e.g. <code>STATE_NARRATIVE="...narrative..."</code> or indirectly
as <code>STATE_NARRATIVE=@filename</code>, and likewise there are versions for
<code>SESSION_NARRATIVE</code>.</p>

<! --- ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ --->

<h2>Remote computation (unreleased)</h2>

<p>There is unreleased code in <span style="color:rgb(120,123,175);font-weight:900">enclone visual</span>
that enables doing "back end" computations on a remote server.  This is 
something that we could make public if there was sufficient demand.
</p>

<p>There are three motivations for this capability:
<ol>
<li>You may have datasets on the server, and not want to have to manually move them to your 
personal machine.  We believe this is the most compelling reason for remote computation.</li>
<li>Computation on the remote server <i>might</i> be faster.</li>
<li>Remote computation enables direct sharing of sessions between users who can access the same
server, instantaneously and just by pushing a button.  This can be a powerful enabler of 
collaboration.</li>
</ol>
</p>

<p>The catch with the remote computation is that for most system configurations, a "magic
incantation" is needed to "jump over" a firewall between your personal machine and the server.  
We only know
what this incantation is for our system, and thus some experimentation would be required for yours.
To release this feature we would need to devise general instructions.</p>

<! --- ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ --->

<h2>Debugging under Linux</h2>

<p>On a Linux computer, if you type <code>enclone VIS</code>, and get an error message, let
us know.  We provide here followup steps that may be applicable.  The idea of these steps is that
the problem may not be in <span style="color:rgb(120,123,175);font-weight:900">enclone</span>, but rather lie in upstream software, or be an issue with your
computer.</p>

<p><b>1.</b> The software underlying <span style="color:rgb(120,123,175);font-weight:900">enclone</span>_vis uses the GPU on your computer.  It is possible
that the GPU is not accessible to this software.
You can try the following two commands as a diagnostic:
<pre><code>sudo apt install -y mesa-utils</code>
<code>glxinfo | grep Accelerated</code></pre>
If when you do this you see
<pre><code>    Accelerated: no</code></pre>
then something is wrong.  It may help to reinstall the GPU driver.  Unless you solve this problem,
the steps that follow are unlikely to yield useful information.</p>

<p><b>2.</b> To run the next steps, you need to have a current version of Rust on your computer.
First, if Rust is not already installed in your computer, you can install it using
<pre><code>sudo apt update</code>
<code>sudo apt install cargo</code></pre>
Now you can tell what version you have by typing <code>rustc --version</code>.  Go to 
<a href="https://www.rust-lang.org">https://www.rust-lang.org</a> to see what the current version
is.  If those are different, you may need to update, using approximately the following steps:
<pre>
<code>sudo apt remove cargo</code>
<code>sudo apt autoremove cargo</code>
<code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code>
<code>go with option 1</code>
<code>need ~/.cargo/bin to be in path</code></pre>
Possibly you can get away without doing these things.</p>

<p><b>3.</b> Now you can test to see if your problem lies in a particular Rust crate called
<code>wgpu</code>, as follows:
<pre>
<code>git clone https://github.com/gfx-rs/wgpu</code>
<code>cd wgpu</code>
<code>cargo run --example cube</code>
</pre>
If a cube shows up on your screen, then probably <code>wgpu</code> is working.  Otherwise it may
make sense to file an issue at
<a href="https://github.com/gfx-rs/wgpu/issues">https://github.com/gfx-rs/wgpu/issues</a>.
For that you should show exactly what you typed and the terminal output, as well as the output of 
the command <code>lsb_release -a</code>.</p>

<p><b>4.</b> If <code>wgpu</code> works, then a next step would be to see if there is a problem 
in the <code>iced</code> crate.  Try this:
<pre>
<code>git clone https://github.com/hecrj/iced</code>
<code>cd iced</code>
<code>cargo run --package clock</code>
</pre>
A clock should show up.  If not, you could file an issue at
<a href="https://github.com/iced-rs/iced/issues">https://github.com/iced-rs/iced/issues</a>,
with details as above.</p>

<! --- ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ --->
<! --- ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ --->

</body>
</html>