parismi/Parismi_operation_overview.html at master · cinquin/parismi · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<style>
h1,
h2,
h3,
h4,
h5,
h6,
p,
blockquote {
    margin: 0;
    padding: 0;
}
body {
    font-family: "Helvetica Neue", Helvetica, "Hiragino Sans GB", Arial, sans-serif;
    font-size: 13px;
    line-height: 18px;
    color: #737373;
    background-color: white;
    margin: 10px 13px 10px 13px;
}
table {
	margin: 10px 0 15px 0;
	border-collapse: collapse;
}
td,th {
	border: 1px solid #ddd;
	padding: 3px 10px;
}
th {
	padding: 5px 10px;
}

a {
    color: #0069d6;
}
a:hover {
    color: #0050a3;
    text-decoration: none;
}
a img {
    border: none;
}
p {
    margin-bottom: 9px;
}
h1,
h2,
h3,
h4,
h5,
h6 {
    color: #404040;
    line-height: 36px;
}
h1 {
    margin-bottom: 18px;
    font-size: 30px;
}
h2 {
    font-size: 24px;
}
h3 {
    font-size: 18px;
}
h4 {
    font-size: 16px;
}
h5 {
    font-size: 14px;
}
h6 {
    font-size: 13px;
}
hr {
    margin: 0 0 19px;
    border: 0;
    border-bottom: 1px solid #ccc;
}
blockquote {
    padding: 13px 13px 21px 15px;
    margin-bottom: 18px;
    font-family:georgia,serif;
    font-style: italic;
}
blockquote:before {
    content:"\201C";
    font-size:40px;
    margin-left:-10px;
    font-family:georgia,serif;
    color:#eee;
}
blockquote p {
    font-size: 14px;
    font-weight: 300;
    line-height: 18px;
    margin-bottom: 0;
    font-style: italic;
}
code, pre {
    font-family: Monaco, Andale Mono, Courier New, monospace;
}
code {
    background-color: #fee9cc;
    color: rgba(0, 0, 0, 0.75);
    padding: 1px 3px;
    font-size: 12px;
    -webkit-border-radius: 3px;
    -moz-border-radius: 3px;
    border-radius: 3px;
}
pre {
    display: block;
    padding: 14px;
    margin: 0 0 18px;
    line-height: 16px;
    font-size: 11px;
    border: 1px solid #d9d9d9;
    white-space: pre-wrap;
    word-wrap: break-word;
}
pre code {
    background-color: #fff;
    color:#737373;
    font-size: 11px;
    padding: 0;
}
sup {
    font-size: 0.83em;
    vertical-align: super;
    line-height: 0;
}
* {
	-webkit-print-color-adjust: exact;
}
@media screen and (min-width: 914px) {
    body {
        width: 854px;
        margin:10px auto;
    }
}
@media print {
	body,code,pre code,h1,h2,h3,h4,h5,h6 {
		color: black;
	}
	table, pre {
		page-break-inside: avoid;
	}
}
</style>
<title>Parismi can be run in interactive mode, as an ImageJ plugin, or in batch mode</title>

</head>
<body>
<p>Parismi can be run in interactive mode, as an ImageJ plugin, or in batch mode.</p>

<p><strong>Interactive mode</strong></p>

<p>Open <code>Parismi/IJ/ij.jar</code> and select <code>A0PipelineManager</code> from the plugin menu. To load a
pre-existing pipeline (which can be a good way of exploring Parismi's functionality),
either click the "Load table" button and select an <code>.xml</code> file from our dataset release,
or drag such a file and drop it onto the Parismi control panel.</p>

<p>Dragging and dropping <code>.tiff</code> or <code>.proto</code> files (containing cell detections, annotations,
or fluorescence quantification results as explained below) onto the Parismi control panel
will cause the files to be opened and displayed using the corresponding GUI view. If one
<code>.tiff</code> file is dropped together with one <code>.proto</code> file, the cells in the <code>.proto</code> file will
be displayed as an overlay on the image.</p>

<p><em>Overall pipeline structure</em></p>

<p>Each step in the pipeline corresponds to one row in the GUI table. Table columns include
the following:</p>

<ul>
<li><em>Primary image input</em>. A right click in the field provides a popup menu to assist with
input selection (alternatively, one can drag the file from any file manager and drop it
onto the field, or directly type in the input specification). The input can be a file on
disk (specified with a full path name, in which <code>~/</code> or <code>~username/</code> can be used as
shorthand for user home directories, or a path name relative to the current working
directory), an image opened through ImageJ and specified by its name, or the output of
another plugin. In the latter case, the reference to the other plugin is given as number
specifying the row offset (i.e. -1 to specify the output of the preceding plugin), or as
a number prefixed by <code>$</code> to specify an absolute row in the table. Parismi can natively
read TIFFs with 32-bit or 64-bit offsets and LSM files. It can transparently decompress
GNU zipped files that it recognizes with the <code>.gz</code> extension. Large image files can be
opened as "virtual stacks", which means their contents are initially not fully loaded
into memory (this is done by default for files over 2 GB in size; this behavior can be
manually adjusted with the "Use virtual stacks to open files" checkbox). Note that some
(but not all) plugins will trigger a read of the full contents when they are given such
an input.</li>
<li><em>Channels</em>. For multiple channel images, a subset of channels to which to apply the
plugin can be specified by selecting from the list provided.</li>
<li><em>Plugin name</em>. A right click in the field provides a hierarchical popup menu of all
plugins that were loaded (note that deprecated plugin can be loaded from pre-existing
<code>.xml</code> files but are not offered for loading through the GUI). Hovering over a plugin
name in the popup menu displays a tooltip that gives a brief overview of the plugin.</li>
<li><em>Plugin parameters</em>. These parameters are plugin-specific and appear once a plugin has
been selected. For numerical values or ranges, the range of values covered by the
sliders can be manually adjusted (the range is saved along with the selected values to
facilitate adjustment of reloaded tables). Values can be adjusted by typing in a new
number, by using the sliders, or by using the mouse scrollwheel while over the slider.
Any change leads by default to coalesced live updates of the pipeline (this behavior
can be adjusted; see below). Hovering over parameter names displays a tooltip that
offers a brief description of the parameter.</li>
<li><em>Auxiliary inputs</em>. Some plugins require multiple inputs (e.g. a set of active contour
seeds and an image on which to run active contours). The inputs are specified in the
"Auxiliary inputs" column, following the same format as the primary image input column.</li>
<li style="page-break-after:always;"><em>Auxiliary outputs</em>. For plugins that have multiple outputs, this column provides a
list of names, which Parismi will use to match inputs and outputs of plugins that do
not follow the one input - one output model.</li>
<li><em>Show</em>. GUI views of plugin outputs are created by default for most plugins run in GUI
mode. This behavior can be adjusted on a plugin-by-plugin basis using the "Show"
checkbox. Note that all the outputs of a plugin can be brought to the foreground by
selecting the plugin in the table and clicking the "Bring outputs to front" button.</li>
<li><em>Autorange</em>. When this checkbox is selected, the output image display range
is automatically adjusted to match the minimal and maximal pixel values.</li>
<li><em>On</em>. If this checkbox is not selected, the plugin is skipped when the pipeline is
run.</li>
<li><em>C+</em>. This option will be documented at a later time and can be left to its default
value.</li>
<li>The <em>progress bar</em> shows progression of the plugin as it computes its output. Note
that some plugins provide more fine-grained progress reports than others.</li>
</ul>


<p><em>GUI views for Parismi data structures</em></p>

<p>GUI views of plugin outputs include an extended ImageJ image window for image outputs, and
a table view for cells.</p>

<ul>
<li style="page-break-after:always;"><em>Image windows</em> are based on a standard ImageJ display, to which a set of controls and
user interaction functionalities are added. The user can perform <em>de novo</em> cell
annotations, or edits of pre-existing annotations that can be derived from automatic
detection, previous user edits, or any combination thereof. The annotations include cell
position, as well as any combination of user-defined labels, e.g. to denote
manually-determined cell types. The annotations are overlaid with the image; their
graphical display parameters (thickness, diameter, transparency, and color) can be
manually adjusted to provide the most useful display for the particular kind of image
that is used. The position of annotations can be adjusted by dragging. All annotations
in a rectangular region can be deleted in one step by selecting delete mode and dragging
the mouse from one corner of the rectangle to the opposite corner. Hovering over an
annotation for a user-definable delay produces a table listing all information for that
annotation (the table can be preserved by clicking on it; if not it disappears when
moving the mouse away from the annotation). Displayed sections can be "thickened" by
projecting on an interval centered around the slice in view.
The image display can be adjusted in the following ways:

<ul>
<li>The image can be switched back and forth between the "Composite" mode (in which
multiple channels are drawn together, with a different color for each) or the
"Multiple channel" model with the "Make composite" button in the main Parismi window.</li>
<li>Orthogonal views (on which annotations also appear and can be manipulated) can be
toggled on or off with the "Orthogonal" button.</li>
<li>By default the scrollwheel changes the displayed z slice (in the main xy view), or
the displayed x or y slices (in the yz and xz orthogonal views, respectively). For
fine stepping through slices, one can press the x, y, or z keys (use shift for reverse
stepping).</li>
<li>The contrast can be adjusted by using the mouse scrollwheel while pressing shift</li>
<li>One can scroll through the channels by using the mouse scrollwheel while pressing
option</li>
<li>Option-click is a shortcut to add new cells without manually selecting the
corresponding tool. Shift-click is a shortcut to delete.</li>
</ul>
</li>
<li><em>Cell tables</em>. These tables give a spreadsheet-like presentation of all the fields in
cell objects, which can be the raw cell detections (made by the cell detector and/or by
users), or the detections on which various plugins have been run to add new fields (e.g.
fluorescence contents). Some features are as follows:

<ul>
<li>Interactive histograms are displayed for each column. A range can be selected by
clicking in these histograms, which will cause filtering of the displayed cells.</li>
<li>Cells can be sorted on the value of any field by clicking on the column header.</li>
<li>A scatterplot of two columns can be obtained by selecting cells in any two columns
and clicking "Scatter plot from selected columns". In the resulting graph window, the
x and y axes can be switched and a trendline with user-adjustable local averaging
window can be displayed. If cells were selected from a single column, a histogram
is displayed instead and standard statistics reported.</li>
<li>Basic spreadsheet-like computing functionality is included, which is not fully
implemented and will be documented at a later time.</li>
<li>The results can be exported to a tab-delimited text file (this is for user
convenience, and is of course not required for batch operation).</li>
<li>Note that the segmentation coordinates, which normally comprise a very large set of
numbers, are hidden from the table view. Segmentations can be displayed from cell/seed
objects by running e.g. the <code>DisplaySolidSegmentation</code> plugin, which produces an image
output in which the individual cells can be colored following a user-selected field.</li>
</ul>
</li>
</ul>


<p><em>Running pipelines</em></p>

<ul>
<li>A full run of the pipeline can be initiated by clicking the "Run" button.</li>
<li>A run of the pipeline starting from one particular point can be initiated by selecting
a row in the table and clicking the "Update step" button. If the "Update pipeline upon
param change" checkbox is selected, all plugins following the selected one will also be
run.</li>
<li>Any change to a plugin parameter will by default cause the plugin to recompute its
output (this behavior can be adjusted with the "Update current step upon param change"
checkbox), which will by default in turn cause the next plugins to be also re-run. If a
second parameter change occurs before the re-computing triggered by a first change has
completed, the update for the second change can either be put in a coalescing queue or
cancel the re-computation triggered by the first change.</li>
<li>A pipeline run can be interrupted at any time by clicking the "Stop all updates"
button. Note that plugins differ in how quickly they respond to that button.</li>
</ul>


<p><em>Semi-automated functionality</em></p>

<p style="page-break-after:always;">Pipelines often comprise steps for which there is no need for user interaction, and steps
at which it is desirable for a user to review the results and adjust them if need be.
Parismi can be paused at key steps using the <code>Pause</code> plugin; execution can be resumed
after user edits by selecting the appropriate row in the pipeline table and clicking
"Run". To avoid users spending time moving from one dataset to another, one can use the
"Open next and run" button. This button closes all current plugin outputs, goes through
all input and output file names to increment any numbers that occur between braces, and
runs the current pipeline on the new inputs (pausing at any positions specified by the
<code>Pause</code> plugin). If datasets are structured in numbered directories, naming files following
e.g. <code>~username/datasets/{1}/input_1.tiff</code> will make it possible to iterate through all the
directories without manual setup at each dataset change. Note that more sophisticated
batch functionality, which gives more flexibility in terms of file naming and directory
structure, is offered by the <code>BatchOpenV2</code> plugin.</p>

<p><em>File formats</em></p>

<p>The file formats that Parismi can read and write are as follows:</p>

<ul>
<li><em>Images</em>. Parismi can natively read 32-bit-offset Tagged Image File Format (i.e.
"regular" TIFF) or 64-bit-offset TIFF (i.e. BigTIFF); the latter removes the 2GB or 4GB
(depending on implementation) limit on file size. Parismi also natively reads the
proprietary Zeiss LSM file format (which is a TIFF variant). Note that other file types
can be opened through ImageJ, in particular with the LOCI Bio-Formats plugin, which can
read a broad array of file types. By default Parismi writes BigTIFF with ImageJ
metadata to specify channels, although for ease of browsing of output images (since
BigTIFF is not always supported by external programs) it can also rely on ImageJ to
output regular TIFF images, in which channels can be displayed as an RGB overlay.</li>
<li><em>Cell annotations and segmentations</em>. All data pertaining to automatic cell
detections, user detections and edits, annotations, segmentations, and quantification
results are stored in a unified format. Parismi relies on Google's <code>Protobuf</code> file
format, with fixed fields including cell position and x, y, and z coordinates of all
pixels in the segmentation mask, as well as optional fields specifying annotations and
analysis results. Parismi reads and writes corresponding files with the <code>.proto</code>
extension. To facilitate data exchange with other programs, Protobuf objects can be
exported to tab-delimited text files (without the segmentation mask) either manually or
through a plugin. Segmentation masks can also be exported as a single TIFF in which each
cell receives a pixel value matching its index. Such a file can easily be reused in
another program such as Matlab.</li>
</ul>


<p><em>Notes on saved pipelines</em></p>

<p>We normally include in each of our pipelines a plugin to save the pipeline itself in the
dataset directory in which it was run. This allows any interactive user edits that were
made to plugin parameters to be permanently recorded. As plugins evolve, we often find
that we need to add new parameters. To maximize backward compatibility, the programmer can
either transparently specify default values to be given to plugin parameters that did not
exist in earlier pipelines, or specify that an error should be thrown so manual review
must occur.</p>

<p><strong>Batch mode</strong></p>

<p>Batch runs can be performed with <code>java -jar A0PipeLine_Manager.jar batch path_to_pipeline.xml</code>.
This matches the semi-automated functionality described above, except that pauses for
user review are skipped, and no GUI windows are opened (for a command-line run without batch
functionality, replace <code>batch</code> by <code>singleRun</code>). When using long pipelines with
adjustments that may need to be made at select steps, it may be a good idea to split
the pipelines in smaller pieces and use <code>make</code> to handle updates. This is what we have
done for the datasets we have released.</p>
</body>
</html>