-
Notifications
You must be signed in to change notification settings - Fork 39
/
clearmap.tex
9945 lines (7296 loc) · 374 KB
/
clearmap.tex
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
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\usepackage[utf8]{inputenc}
\DeclareUnicodeCharacter{00A0}{\nobreakspace}
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{longtable}
\usepackage{sphinx}
\usepackage{multirow}
\addto\captionsenglish{\renewcommand{\figurename}{Fig. }}
\addto\captionsenglish{\renewcommand{\tablename}{Table }}
\floatname{literal-block}{Listing }
\title{ClearMap Documentation}
\date{May 26, 2016}
\release{0.9.2}
\author{Christoph Kirst}
\newcommand{\sphinxlogo}{}
\renewcommand{\releasename}{Release}
\makeindex
\makeatletter
\def\PYG@reset{\let\PYG@it=\relax \let\PYG@bf=\relax%
\let\PYG@ul=\relax \let\PYG@tc=\relax%
\let\PYG@bc=\relax \let\PYG@ff=\relax}
\def\PYG@tok#1{\csname PYG@tok@#1\endcsname}
\def\PYG@toks#1+{\ifx\relax#1\empty\else%
\PYG@tok{#1}\expandafter\PYG@toks\fi}
\def\PYG@do#1{\PYG@bc{\PYG@tc{\PYG@ul{%
\PYG@it{\PYG@bf{\PYG@ff{#1}}}}}}}
\def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+\PYG@do{#2}}
\expandafter\def\csname PYG@tok@gd\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.63,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gu\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@gt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.27,0.87}{##1}}}
\expandafter\def\csname PYG@tok@gs\endcsname{\let\PYG@bf=\textbf}
\expandafter\def\csname PYG@tok@gr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{1.00,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@cm\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@vg\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@m\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@cs\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}
\expandafter\def\csname PYG@tok@ge\endcsname{\let\PYG@it=\textit}
\expandafter\def\csname PYG@tok@vc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@il\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@go\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.20,0.20,0.20}{##1}}}
\expandafter\def\csname PYG@tok@cp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@gi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.63,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gh\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@ni\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.84,0.33,0.22}{##1}}}
\expandafter\def\csname PYG@tok@nl\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.13,0.44}{##1}}}
\expandafter\def\csname PYG@tok@nn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@no\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.38,0.68,0.84}{##1}}}
\expandafter\def\csname PYG@tok@na\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@nb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@nd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.33,0.33,0.33}{##1}}}
\expandafter\def\csname PYG@tok@ne\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.49}{##1}}}
\expandafter\def\csname PYG@tok@si\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.44,0.63,0.82}{##1}}}
\expandafter\def\csname PYG@tok@s2\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@vi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@nt\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.45}{##1}}}
\expandafter\def\csname PYG@tok@nv\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@s1\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@gp\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@sh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@ow\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@sx\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@bp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c1\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@kc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@mf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@err\endcsname{\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}
\expandafter\def\csname PYG@tok@mb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@ss\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.32,0.47,0.09}{##1}}}
\expandafter\def\csname PYG@tok@sr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.14,0.33,0.53}{##1}}}
\expandafter\def\csname PYG@tok@mo\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@kd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@mi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@kn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@o\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.40,0.40,0.40}{##1}}}
\expandafter\def\csname PYG@tok@kr\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@s\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@kp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@w\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.73,0.73}{##1}}}
\expandafter\def\csname PYG@tok@kt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.56,0.13,0.00}{##1}}}
\expandafter\def\csname PYG@tok@sc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@k\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@se\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sd\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\def\PYGZbs{\char`\\}
\def\PYGZus{\char`\_}
\def\PYGZob{\char`\{}
\def\PYGZcb{\char`\}}
\def\PYGZca{\char`\^}
\def\PYGZam{\char`\&}
\def\PYGZlt{\char`\<}
\def\PYGZgt{\char`\>}
\def\PYGZsh{\char`\#}
\def\PYGZpc{\char`\%}
\def\PYGZdl{\char`\$}
\def\PYGZhy{\char`\-}
\def\PYGZsq{\char`\'}
\def\PYGZdq{\char`\"}
\def\PYGZti{\char`\~}
% for compatibility with earlier versions
\def\PYGZat{@}
\def\PYGZlb{[}
\def\PYGZrb{]}
\makeatother
\renewcommand\PYGZsq{\textquotesingle}
\begin{document}
\maketitle
\tableofcontents
\phantomsection\label{index::doc}
\emph{ClearMap} is a toolbox for the analysis and registration of volumetric data
from cleared tissues.
\emph{ClearMap} has been designed to analyze large 3D image stack datasets obtained with Light Sheet Microscopy
of iDISCO+ cleared mouse brains samples immunolabeled for nuclear proteins. ClearMap can perform image registration to a 3D annotated reference (such as the Allen Institute Brain Atlases), volumetric image processing, object detection and statistical analysis. The tools in \emph{ClearMap} have been written with the mapping of Immediate Early Genes in the brain as the primary application.
However, these tools should also be more broadly useful for data obtained with other types of microscopes, other types of markers, and other clearing techniques. Moreover, the registration and region segmentation capabilities of ClearMap are not depending on the Atlases and annotations we used in our study. Users are free to import their own reference files and annotation files, so the use of \emph{ClearMap} can be expanded to other species, and other organs or samples.
\emph{ClearMap} is written in Python 2.7, and is designed to take advantage of parallel processing capabilities of modern workstations. We hope the open structure of the code will enable in the future many new modules to be added to ClearMap to broaden the range of applications to different types of biological objects or structures.
\chapter{Author and License}
\label{index:clearmap}\label{index:author-and-license}
\section{Authors:}
\label{index:authors}
\subsection{ClearMap lead programming and design:}
\label{index:clearmap-lead-programming-and-design}
Christoph Kirst,
\emph{The Rockefeller University}
\subsection{Scripts and specific applications:}
\label{index:scripts-and-specific-applications}
Nicolas Renier and Christoph Kirst
\emph{The Rockefeller University}
\subsection{Documentation:}
\label{index:documentation}
Christoph Kirst and Nicolas Renier
\emph{The Rockefeller University}
\subsection{Additional programming and consulting:}
\label{index:additional-programming-and-consulting}
Kannan Umadevi Venkataraju
\emph{Cold Spring Harbor Laboratories}
\section{License}
\label{index:license}
GNU GENERAL PUBLIC LICENSE Version 3
See \code{LICENSE} or \href{http://www.gnu.org/licenses/gpl-3.0.en.html}{gnu.org} for details.
\chapter{Using ClearMap}
\label{index:using-clearmap}
\section{Overview of ClearMap}
\label{introduction::doc}\label{introduction:overview-of-clearmap}
\emph{ClearMap} is a toolbox to analyze and register microscopy images of cleared
tissue. It is targeted towards cleared brain tissue using the {\hyperref[introduction:idisco-clearing-method]{\emph{iDISCO+ Clearing Method}}}
but can be used with any volumetric imaging data. ClearMap contains a large number of functions dedicated to many aspects of 3D image manipulation and object detection, which could open a lot of possibilities for advanced users. For most users however, all relevant functions are explained in the tutorial in the next section, which contains a classic application case for ClearMap.
The ClearMap code package is structured into four main modules:
\begin{itemize}
\item {}
{\hyperref[introduction:io]{\emph{IO}}} for reading and writing images and data
\item {}
{\hyperref[introduction:alignment]{\emph{Alignment}}} for resampling, reorientation and registration of images onto references
\item {}
{\hyperref[introduction:image-processing]{\emph{Image Processing}}} for correcting and quantifying the image data
\item {}
{\hyperref[introduction:analysis]{\emph{Analysis}}} for the statistical analysis of the data
\end{itemize}
\subsection{IO}
\label{introduction:io}
ClearMap supports a wide range of image formats with a particular focus on volumetric data packaged as stacks or individual files:
\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textsf{\relax
Format
} & \textsf{\relax
Description
}\\
\hline
TIF
&
tif images and stacks
\\
\hline
RAW / MHD
&
raw image files with optional mhd header file
\\
\hline
NRRD
&
nearly raw raster data files
\\
\hline
IMS
&
Imaris image files
\\
\hline
pattern
&
folder, file list or file pattern of a stack of 2d images
\\
\hline\end{tabulary}
We recommend using when possible to use the pattern format, such as \code{image-Zxxxx.tif} where ‘’xxxx’’ is a number, such as 0001.
\begin{notice}{note}{Note:}
ClearMap can read the image data from a Bitplane’s Imaris, but can’t export image data as an Imaris file.
\end{notice}
Images are represented internally as numpy arrays. ClearMap assumes images
in arrays are arranged as {[}x,y{]}, {[}x,y,z{]} or {[}x,y,z,c{]} where x,y,z correspond to
the x,y,z coordinates as when viewed in an image viewer such as \phantomsection\label{introduction:id1}{\hyperref[introduction:imagej]{\emph{{[}ImageJ{]}}}} and
c to a possible color channel.
ClearMap also supports several data formats for storing data points, such as
cell center coordinates or intensities:
\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textsf{\relax
Format
} & \textsf{\relax
Description
}\\
\hline
CSV
&
comma separated values in text file, for exporting to other programs
\\
\hline
NPY
&
numpy binary file, faster and more compact format for the point data
\\
\hline
VTK
&
vtk point data file, for exporting to some programs
\\
\hline
IMS
&
Imaris data file, for writing points onto an existing Imaris file
\\
\hline\end{tabulary}
\emph{points} files simply contain all point coordinates arranged as an array of {[}x,y,z{]} coordinates where each line is a detected cell center. \emph{intensities} files are companion to point files (only for csv and npy formats), where each line contains informations about intensity and detected size for the corresponding center in the point file. Each line in the array of the intensities file has 4 rows organised as follows:
\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textsf{\relax
Row
} & \textsf{\relax
Description
}\\
\hline
0
&
Max intensity of the cell center in the raw data
\\
\hline
1
&
Max intensity of the cell center after the DoG filtering.
\\
\hline
2
&
Max intensity of the cell center after the background subtraction
\\
\hline
3
&
Cell size in voxels after the watershed detection
\\
\hline\end{tabulary}
\subsection{Alignment}
\label{introduction:alignment}
The Alignment module provides tools to resample, reorient and register
volumetric images in a fast parallel way.
Image registration is done by interfacing to the \phantomsection\label{introduction:id2}{\hyperref[introduction:elastix]{\emph{{[}Elastix{]}}}} software package. This package allows it to align cleared mouse brains onto the Allen brain atlas \phantomsection\label{introduction:id3}{\hyperref[introduction:aba]{\emph{{[}ABA{]}}}}.
\subsection{Image Processing}
\label{introduction:image-processing}
ClearMap provides a number of image processing tools with a focus on the
processing of large 3D volumetric images in parallel. For the detection of objects in 3D, ClearMap has a modular architecture. For the user, this is hidden and handled automatically by the \code{detectCells} function (see the example script).
The main processing modules include:
\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textsf{\relax
Module
} & \textsf{\relax
Description
}\\
\hline
{\hyperref[api/ClearMap.ImageProcessing:module-ClearMap.ImageProcessing.BackgroundRemoval]{\emph{\code{BackgroundRemoval}}}}
&
Background estimation and removal via morphological opening
\\
\hline
{\hyperref[api/ClearMap.ImageProcessing:module-ClearMap.ImageProcessing.IlluminationCorrection]{\emph{\code{IlluminationCorrection}}}}
&
Correction of vignetting and other illumination errors
\\
\hline
{\hyperref[api/ClearMap.ImageProcessing.Filter:module-ClearMap.ImageProcessing.Filter]{\emph{\code{Filter}}}}
&
Filtering of the image via large set of filter kernels
\\
\hline
{\hyperref[api/ClearMap.ImageProcessing:module-ClearMap.ImageProcessing.GreyReconstruction]{\emph{\code{GreyReconstruction}}}}
&
Reconstruction of images
\\
\hline
{\hyperref[api/ClearMap.ImageProcessing:module-ClearMap.ImageProcessing.SpotDetection]{\emph{\code{SpotDetection}}}}
&
Detection of local peaks
\\
\hline
{\hyperref[api/ClearMap.ImageProcessing:module-ClearMap.ImageProcessing.CellDetection]{\emph{\code{CellDetection}}}}
&
Detection of cell centers
\\
\hline
{\hyperref[api/ClearMap.ImageProcessing:module-ClearMap.ImageProcessing.CellSizeDetection]{\emph{\code{CellSizeDetection}}}}
&
Detection of cell shapes via watershed
\\
\hline
{\hyperref[api/ClearMap.ImageProcessing:module-ClearMap.ImageProcessing.IlastikClassification]{\emph{\code{IlastikClassification}}}}
&
Classification of voxels via interface to \phantomsection\label{introduction:id4}{\hyperref[introduction:ilastik]{\emph{{[}Ilastik{]}}}}
\\
\hline\end{tabulary}
The modular structure of this sub-packages allows for fast and flexible integration of
additional modules for future developments.
\subsection{Analysis}
\label{introduction:analysis}
This part of ClearMap provides a toolbox for the statistical analysis and
visualization of detected cells or structures and region specific analysis
of annotated data.
For cleared mouse brains aligned to the \phantomsection\label{introduction:id5}{\hyperref[introduction:aba]{\emph{{[}ABA{]}}}} a wide range of statistical
analysis tools with respect to the annotated brain regions in the atlas is
supported. Two types of analysis are done:
\begin{itemize}
\item {}
Voxel statistics, which are based on the heat-map generated from the detected cell centers. These are usually represented as image stacks of mean, standard deviation, p-values with False Discovery Rate options.
\item {}
Region statistics, which are based on the annotated regions from the reference annotation file. They are usually represented as spreadsheets containing the statistics for each region.
\end{itemize}
The Key modules are:
\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textsf{\relax
Module
} & \textsf{\relax
Description
}\\
\hline
{\hyperref[api/ClearMap.Analysis:module-ClearMap.Analysis.Statistics]{\emph{\code{Statistics}}}}
&
Statistical tools for the analysis of detected cells
\\
\hline
{\hyperref[api/ClearMap.Analysis:module-ClearMap.Analysis.Voxelization]{\emph{\code{Voxelization}}}}
&
For voxel-based statistics: voxelization of cells for visualization and analysis
\\
\hline
{\hyperref[api/ClearMap.Analysis:module-ClearMap.Analysis.Label]{\emph{\code{Label}}}}
&
For region-based statistics: tools to analyse data with the annotated reference files
\\
\hline\end{tabulary}
The use of the modules is explained in the tutorial.
\subsection{iDISCO+ Clearing Method}
\label{introduction:idisco-clearing-method}
Robust quantification of 3D datasets requires images as uniform as possible for the signal properties, both on each plane, and also at all imaging depths. The iDISCO+ method is an evolution of the iDISCO whole-mount labeling technique to improve the diffusion and background of staining in large samples \phantomsection\label{introduction:id6}{\hyperref[introduction:renier2014]{\emph{{[}Renier2014{]}}}}, and the 3DISCO clearing technique \phantomsection\label{introduction:id7}{\hyperref[introduction:erturk2012]{\emph{{[}Erturk2012{]}}}}. The iDISCO+ staining and clearing method is combined optimally with the very large field of view enabled by light sheet microscopy, in particular the ultramicroscope optical design, which enables low magnification imaging with high speed and relatively high resolution.
\begin{description}
\item[{The datasets used to develop ClearMap are usually composed of two channels:}] \leavevmode\begin{itemize}
\item {}
The signal channel. Typically obtained in the far-red light spectrum, where the optical properties of the cleared tissue are at their best for signal-to-noise and transparency. It is recommended when possible to use nuclear reporters or proteins to facilitate the object detection.
\item {}
The autofluorescence channel, usually collected in the blue-green light spectrum. The background tissue fluorescence highlights the major structures of the tissue to facilitate the 3D image registration. Only the contrast between regions is important here, so it doesn’t matter if the relative intensities between regions are not the same as on the reference scans.
\end{itemize}
\item[{See these videos for example of light sheet imaging of cleared tissues:}] \leavevmode\begin{itemize}
\item {}
\href{https://www.youtube.com/watch?v=-ctRUMQjizgvbLtLYkW6hI}{Dopaminergic system in the embryonic mouse}
\item {}
\href{https://www.youtube.com/watch?v=vbLtLYkW6hI}{Cortical and hippocampal neurons in the adult mouse brain}
\end{itemize}
\end{description}
More info can be found on the \phantomsection\label{introduction:id8}{\hyperref[introduction:idisco]{\emph{{[}iDISCO{]}}}} webpage.
\subsection{References}
\label{introduction:references}
\section{Installation}
\label{installation:installation}\label{installation::doc}
\subsection{Requirements}
\label{installation:requirements}
ClearMap is written in Python 2.7. It should run on any Python environment, but it also relies on external softwares such as \href{http://elastix.isi.uu.nl}{Elastix} which may not run optimally on Windows or Apple systems.
For typical use, we recommend a workstation running Ubuntu 14 or later with at least 4 CPU cores, 64Gb of RAM and SSD disks. 128Gb of RAM and 6 cores or above will have much increased performances. The processing time however will depend greatly on the parameters set, so your experience may be different. Also, large hard drives may be needed to host the raw data, although 1 to 4Tb of storage space should be enough for most users.
\subsection{Installation}
\label{installation:id1}
To install ClearMap, first create a folder to contain all the files for the program. Download the scripts from the latest version of ClearMap from \href{https://www.idisco.info}{The iDISCO website} and extract them in the ClearMap folder. You also need to download individually the following softwares:
\begin{itemize}
\item {}
To do the alignement, you should download \href{http://elastix.isi.uu.nl}{Elastix} (\href{http://elastix.isi.uu.nl}{http://elastix.isi.uu.nl})
\item {}
If you wish to use the machine learning filters, download \href{http://ilastik.org}{Ilastik} (\href{http://ilastik.org}{http://ilastik.org}). This is an optional download, only if you wish to use this more complete object detection framework for complex objects.
\end{itemize}
If you’re starting from a fresh Ubuntu 16.04LTS install, for instance, here are the steps to complete the installation. Open a terminal window and type the following instructions:
\begin{itemize}
\item {}
Installation tools:
\end{itemize}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }sudo apt\PYGZhy{}get update
\PYG{n+nv}{\PYGZdl{} }sudo apt\PYGZhy{}get install git
\PYG{n+nv}{\PYGZdl{} }sudo apt\PYGZhy{}get install python\PYGZhy{}pip
\PYG{n+nv}{\PYGZdl{} }sudo \PYGZhy{}H pip install \PYGZhy{}\PYGZhy{}upgrade pip
\end{Verbatim}
\begin{itemize}
\item {}
Download ClearMap:
\end{itemize}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }git clone https://github.com/ChristophKirst/ClearMap.git
\end{Verbatim}
\begin{itemize}
\item {}
Install Spyder:
\end{itemize}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }sudo apt\PYGZhy{}get install spyder
\end{Verbatim}
\begin{itemize}
\item {}
Install the necessary libraries:
\end{itemize}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }sudo apt\PYGZhy{}get install python\PYGZhy{}opencv
\PYG{n+nv}{\PYGZdl{} }sudo apt\PYGZhy{}get install cython
\PYG{n+nv}{\PYGZdl{} }sudo apt\PYGZhy{}get install python\PYGZhy{}tifffile
\PYG{n+nv}{\PYGZdl{} }sudo apt\PYGZhy{}get install python\PYGZhy{}h5py
\PYG{n+nv}{\PYGZdl{} }sudo apt\PYGZhy{}get install python\PYGZhy{}natsort
\PYG{n+nv}{\PYGZdl{} }sudo \PYGZhy{}H pip install scikit\PYGZhy{}image
\end{Verbatim}
We use \href{https://pythonhosted.org/spyder/}{Spyder} to run the code. Set the project explorer and working environment in the ClearMap folder.
\subsection{Configuration}
\label{installation:configuration}
Open the file \code{ClearMap/Settings.py} to set the paths of installations for Ilastik and Elastix:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{IlastikPath} \PYG{o}{=} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{/yourpath/ilastik}\PYG{l+s}{\PYGZsq{}}\PYG{p}{;}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{ElastixPath} \PYG{o}{=} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{/yourpath/elastix}\PYG{l+s}{\PYGZsq{}}\PYG{p}{;}
\end{Verbatim}
Note that Ilastik is optional. If you haven’t installed it, you can set the path to \code{None}. You can also set the installation to run on multiple machines by setting a host specific path:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{if} \PYG{n}{hostname} \PYG{o}{==} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{kagalaska.nld}\PYG{l+s}{\PYGZsq{}}\PYG{p}{:} \PYG{c}{\PYGZsh{}Christoph’s Laptop}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{n}{IlastikPath} \PYG{o}{=} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{/home/ckirst/programs/ilastik/}\PYG{l+s}{\PYGZsq{}}\PYG{p}{;}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{n}{ElastixPath} \PYG{o}{=} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{/home/ckirst/programs/elastix/}\PYG{l+s}{\PYGZsq{}}\PYG{p}{;}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{elif} \PYG{n}{hostname} \PYG{o}{==} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{mtllab\PYGZhy{}Ubuntu}\PYG{l+s}{\PYGZsq{}}\PYG{p}{:} \PYG{c}{\PYGZsh{}Nico’s Workstation}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{n}{IlastikPath} \PYG{o}{=} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{/usr/local/ilastik}\PYG{l+s}{\PYGZsq{}}\PYG{p}{;}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{n}{ElastixPath} \PYG{o}{=} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{/usr/local/elastix}\PYG{l+s}{\PYGZsq{}}\PYG{p}{;}
\end{Verbatim}
\subsection{Additionnal Informations:}
\label{installation:additionnal-informations}
We run ClearMap on Ubuntu 16.04LTS using the following libraries:
\begin{itemize}
\item {}
Matplotlib 1.5.1
\item {}
Numpy 1.11.0
\item {}
Scipy 0.16.0
\item {}
Skimage 0.12.3
\item {}
Mahotas 1.3.0 (\href{http://luispedro.org/software/mahotas/}{website})
\item {}
h5py 2.6.0 (for Imaris files input/output only)
\item {}
openCV 2.4.9.1
\item {}
PyQt4
\item {}
tifffile 0.6.2
\item {}
Cython 0.23.1
\end{itemize}
\section{Tutorial}
\label{tutorial::doc}\label{tutorial:tutorial}
The goal of this tutorial is to explain the scripts we used to analyze samples. As an example, we will use a dataset from a Light Sheet imaged adult mouse brain stained for c-fos. The tutorial files also contain an autofluorescence file to enable the registration of the scan to the reference atlas. The tutorial files are found in the ClearMap/Scripts folder. They consist of :
\begin{itemize}
\item {}
{\hyperref[tutorial:the-parameter-file]{\emph{The Parameter File}}} This sets the parameters individually for each sample
\item {}
{\hyperref[tutorial:the-run-file]{\emph{The Run File}}} This will run all the commands to process each sample individually
\item {}
{\hyperref[tutorial:analysis-tools]{\emph{Analysis Tools}}} This scripts will run the analysis tools and group statistics for all samples in the batch
\end{itemize}
A project will usually contain 1 parameter file for each sample, 1 run file for the whole experiment and 1 analysis file for the whole experiment.
\subsection{The Parameter File}
\label{tutorial:the-parameter-file}
The parameter is a Python script that will contain all the necessary informations to process each sample. An example script, \emph{parameter\_file\_template.py} is provided in the ClearMap/Scripts folder. Open this file to follow closely the tutorial. It contains the following sections:
\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textsf{\relax
Section
} & \textsf{\relax
Description
}\\
\hline
{\hyperref[tutorial:import-modules]{\emph{Import modules}}}
&
load from ClearMap the functions used here
\\
\hline
{\hyperref[tutorial:data-parameters]{\emph{Data parameters}}}
&
points to the files used, their resolution and orientation
\\
\hline
{\hyperref[tutorial:cell-detection]{\emph{Cell detection}}}
&
parameters for the cell detection, and module used
\\
\hline
{\hyperref[tutorial:heat-map-generation]{\emph{Heat map generation}}}
&
to generate a voxelized map of the detected cells
\\
\hline
{\hyperref[tutorial:config-parameters]{\emph{Config Parameters}}}
&
the parameters for memory and processors management
\\
\hline
{\hyperref[tutorial:run-parameters]{\emph{Run Parameters}}}
&
you would usually not change these. They specify how the data will be processed
\\
\hline\end{tabulary}
\subsubsection{\emph{Import Modules}}
\label{tutorial:import-modules}
You would usually not change these. They are all the functions that will be used later either in the parameter file or in the execution file.
\subsubsection{\emph{Data parameters}}
\label{tutorial:data-parameters}
This is where you point to the files used, their resolution and orientation. It also defines which atlas and annotation files to use.
To set the directory where all files will be read and written for this sample:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{BaseDirectory} \PYG{o}{=} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{/home/mtllab/pharmaco/sample1}\PYG{l+s}{\PYGZsq{}}\PYG{p}{;}
\end{Verbatim}
To set the image files used for the processing:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{cFosFile} \PYG{o}{=} \PYG{n}{os}\PYG{o}{.}\PYG{n}{path}\PYG{o}{.}\PYG{n}{join}\PYG{p}{(}\PYG{n}{BaseDirectory}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{cfos/0\PYGZus{}8x\PYGZhy{}cfos\PYGZhy{}Table Z}\PYG{l+s}{\PYGZbs{}}\PYG{l+s}{d\PYGZob{}4\PYGZcb{}.ome.tif}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}\PYG{p}{;}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{AutofluoFile} \PYG{o}{=} \PYG{n}{os}\PYG{o}{.}\PYG{n}{path}\PYG{o}{.}\PYG{n}{join}\PYG{p}{(}\PYG{n}{BaseDirectory}\PYG{p}{,} \PYGZbs{}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{autofluo/0\PYGZus{}8xs3\PYGZhy{}autofluo\PYGZhy{}Table Z}\PYG{l+s}{\PYGZbs{}}\PYG{l+s}{d\PYGZob{}4\PYGZcb{}.ome.tif}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}\PYG{p}{;}
\end{Verbatim}
Note the use of the command \code{os.path.join} to link the set \code{BaseDirectory} with the folder where the files are. On the LaVision ultramicroscope system, the images files are generated not as stacks, but as numbered files in the ome.tif format. Each Z stack will end by \code{-Table Z0000.ome.tif}. The 0000 is the plane number. To indicate \textbf{ClearMap} to read the next planes, replace the 4 digits with the command \code{\textbackslash{}d\{4\}}. On our system, files for each channel (here, c-fos and background fluorescence) are saved in a different stack, in a different folder.
To restrict the range for the object detection:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{cFosFileRange} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{x}\PYG{l+s}{\PYGZsq{}} \PYG{p}{:} \PYG{n+nb}{all}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{y}\PYG{l+s}{\PYGZsq{}} \PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{180}\PYG{p}{,} \PYG{l+m+mi}{2600}\PYG{p}{)}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{z}\PYG{l+s}{\PYGZsq{}} \PYG{p}{:} \PYG{n+nb}{all}\PYG{p}{\PYGZcb{}}\PYG{p}{;}
\end{Verbatim}
This range will only affect the region used for the cell detection. It will not be taken into account for the 3D image registration to the reference Atlas, nor for the voxelization or other analysis. This is useful to limit the amount of memory used. In our example, we use the full x range, the full z range, but restrict the y range. The camera on our system, an Andor sNEO CMOS, has a sensor size of 2160 x 2660. However, the lens used on for the acquisition, an Olympus 2X 0.5NA MVPLAPO, has a strong corner deformation, so we restrict the y range because no cells can be reliably detected outside of this range.
As a reminder, in the image files, the (0, 0, 0) coordinate corresponds to the upper left corner of the first plane. To the opposite, the (2160, 2660, 2400) coordinate will be the bottom right corner of the last plane (here 2400, but can vary).
When optimizing the parameters for the object detection, you should dramatically restrict the range to speed up the detection. We recommend using 500 planes, 500 pixels on each side:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{cFosFileRange} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{l+s}{\PYGZsq{}}\PYG{l+s}{x}\PYG{l+s}{\PYGZsq{}} \PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{500}\PYG{p}{,} \PYG{l+m+mi}{1000}\PYG{p}{)}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{y}\PYG{l+s}{\PYGZsq{}} \PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{500}\PYG{p}{,} \PYG{l+m+mi}{1000}\PYG{p}{)}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{z}\PYG{l+s}{\PYGZsq{}} \PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{500}\PYG{p}{,} \PYG{l+m+mi}{1000}\PYG{p}{)}\PYG{p}{\PYGZcb{}}\PYG{p}{;}
\end{Verbatim}
But of course adapting the range to where the relevant objects are on your sample.
Next, to set the resolution of the original data (in µm / pixel):
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{OriginalResolution} \PYG{o}{=} \PYG{p}{(}\PYG{l+m+mf}{4.0625}\PYG{p}{,} \PYG{l+m+mf}{4.0625}\PYG{p}{,} \PYG{l+m+mi}{3}\PYG{p}{)}\PYG{p}{;}
\end{Verbatim}
In this example, this is set for a zoom factor of 0.8X on the LaVision system with the 2X lens. This information can be found in the metadata of the tif file usually. If you don’t know the pixel size, we recommend opening the stack with the plugin BioFormat on ImageJ, and going to « image » -\textgreater{} « show info » to read the metadata. On the LaVision file, this information is at the end of the list.
The orientation of the sample has to be set to match the orientation of the Atlas reference files. It is not mandatory to acquire the sample in the same orientation as the atlas. For instance, you can acquire the left side of the brain, and map it onto the right side of the atlas:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{FinalOrientation} \PYG{o}{=} \PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{,}\PYG{l+m+mi}{2}\PYG{p}{,}\PYG{l+m+mi}{3}\PYG{p}{)}\PYG{p}{;}
\end{Verbatim}
The convention is as follow (examples given, any configuration is possible):
\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textsf{\relax
Value of the tuple
} & \textsf{\relax
Description
}\\
\hline
(1, 2, 3)
&
The scan has the same orientation as the atlas reference
\\
\hline
(-1, 2, 3)
&
The x axis is mirrored compared to the atlas
\\
\hline
(1, -2, 3)
&
The y axis is mirrored compared to the atlas
\\
\hline
(2, 1, 3)
&
Performs a rotation by exchanging the x and y axis
\\
\hline
(3, 2, 1)
&
Performs a rotation by exchanging the z and x axis
\\
\hline\end{tabulary}
For our samples, we use the following orientation to match our atlas files:
\begin{itemize}
\item {}
The right side of the brain is facing the objective, lateral side up.
\item {}
The rostral side of the brain is up
\item {}
The dorsal side is facing left
\item {}
The ventral side is facing right
\end{itemize}
This means that in our scans, if we want to image the right hemisphere, we use (1, 2, 3) and if we want to image the left hemisphere, we use (-1, 2, 3).
To set the output for the voxelized heat map file:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{VoxelizationFile} \PYG{o}{=} \PYG{n}{os}\PYG{o}{.}\PYG{n}{path}\PYG{o}{.}\PYG{n}{join}\PYG{p}{(}\PYG{n}{BaseDirectory}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{points\PYGZus{}voxelized.tif}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}\PYG{p}{;}
\end{Verbatim}
To set the resolution of the Atlas Files (in µm/ pixel):
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{AtlasResolution} \PYG{o}{=} \PYG{p}{(}\PYG{l+m+mi}{25}\PYG{p}{,} \PYG{l+m+mi}{25}\PYG{p}{,} \PYG{l+m+mi}{25}\PYG{p}{)}\PYG{p}{;}
\end{Verbatim}
To choose which atlas files you would like to use:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{PathReg} \PYG{o}{=} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{/home/mtllab/Documents/warping}\PYG{l+s}{\PYGZsq{}}\PYG{p}{;}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{AtlasFile} \PYG{o}{=} \PYG{n}{os}\PYG{o}{.}\PYG{n}{path}\PYG{o}{.}\PYG{n}{join}\PYG{p}{(}\PYG{n}{PathReg}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{half\PYGZus{}template\PYGZus{}25\PYGZus{}right.tif}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}\PYG{p}{;}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{AnnotationFile} \PYG{o}{=} \PYG{n}{os}\PYG{o}{.}\PYG{n}{path}\PYG{o}{.}\PYG{n}{join}\PYG{p}{(}\PYG{n}{PathReg}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{annotation\PYGZus{}25\PYGZus{}right.tif}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}\PYG{p}{;}
\end{Verbatim}
It is important to make sure that the Atlas used is in the correct orientation (see above), but also don’t contain too much information outside of the field of view. While the registration program can deal with a bit of extra « bleed » outside of the sample, this should be kept to a minimum. We usually prepare different crops of the atlas file to match the usual field of views we acquire.
\subsubsection{\emph{Cell detection}}
\label{tutorial:cell-detection}
At this point, two detection methods exist: the \code{SpotDetection} and \code{Ilastik}:
\begin{itemize}
\item {}
\code{SpotDetection} is designed for globular objects, such as neuron cell bodies or nuclei. This is the fastest method, and offers a greater degree of fine controls over the sensitivity of the detection. However, it is not well suited for complex objects.
\item {}
\code{Ilastik} is a framework that relies on the user generating a classifier through the graphical interface of the Ilastik program, by painting over a few objects and over the background. The program will then learn to classify the pixels between objects or backgrounds based on the user indications. This is a very easy way to tune very complex filters to detect complex objects or textures. However, the classification is a black box, and very dependent of the user’s classification.
\end{itemize}
In this tutorial, we will use the SpotDetection method. To choose which method to use for the cell detection, set the variable as follows:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{ImageProcessingMethod} \PYG{o}{=} \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{SpotDetection}\PYG{l+s}{\PYGZdq{}}\PYG{p}{;}
\end{Verbatim}
The parameters for the Spot Detection methods are then sorted in « dictionaries » by theme :
\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textsf{\relax
Dictionary name
} & \textsf{\relax
Description
}\\
\hline
correctIlluminationParameter
&
If you have an intensity profile for your microscope, you can correct variations in illuminations here
\\
\hline
removeBackgroundParameter
&
To set the background subtraction via morphological opening
\\
\hline
filterDoGParameter
&
To set the parameters for the Difference of Gaussian filter
\\
\hline
findExtendedMaximaParameter
&
If the object contains multiple peaks of intensity, this will collapse them into one peak
\\
\hline
findIntensityParameter
&
Often, the center of the mass of an object is not the voxel of highest intensity. This is a correction for this
\\
\hline
detectCellShapeParameter
&
This sets the parameters for the cell shape filling via watershed
\\
\hline\end{tabulary}
\paragraph{Correcting the illumination:}
\label{tutorial:correcting-the-illumination}
Because of the Gaussian shape of the light sheet and of the objecting lens vignetting, the sample illumination is not uniform. While correcting the illumination can improve the uniformity of the cell detection, it is usually not really necessary if all samples where imaged the same way, as the same anatomical features will be positioned in the same region of the lens across samples. Nevertheless, to correct for variation in the illumination use:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{correctIlluminationParameter} \PYG{o}{=} \PYG{p}{\PYGZob{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{flatfield}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{None}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{background}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{None}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{scaling}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{Mean}\PYG{l+s}{\PYGZdq{}}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{save}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{None}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{verbose}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{True}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{p}{\PYGZcb{}}
\end{Verbatim}
For this tutorial, we will not use the correction, so the \code{flatfield} parameter is set to \code{None}. Please note that you need to generate an intensity profile for your system if you wish to use this function.
\paragraph{Background Subtraction:}
\label{tutorial:background-subtraction}
This is the most important pre-treatment step, usually always turned on. The background subtraction via morphological opening is not very sensitive to the size parameter used, as long as it is in the range of the size of the objects detected. The parameters for the background subtraction are as follow:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{removeBackgroundParameter} \PYG{o}{=} \PYG{p}{\PYGZob{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{size}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{7}\PYG{p}{,}\PYG{l+m+mi}{7}\PYG{p}{)}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{save}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{None}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{verbose}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{True}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{p}{\PYGZcb{}}
\end{Verbatim}
The parameter \code{size} is a tuple with (x,y) in pixels and correspond to an ellipsoid of this size. Of importance, you can check the result of the background subtraction by setting the \code{save} parameter to a filename. This will output a series of tif images you can open with ImageJ to check the results. For instance you could set \code{save} like this:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{save}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n}{os}\PYG{o}{.}\PYG{n}{path}\PYG{o}{.}\PYG{n}{join}\PYG{p}{(}\PYG{n}{BaseDirectory}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{background/background}\PYG{l+s}{\PYGZbs{}}\PYG{l+s}{d\PYGZob{}4\PYGZcb{}.ome.tif}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}\PYG{p}{;}
\end{Verbatim}
You have to use the \code{\textbackslash{}d\{4\}} notation to save the files as a series of images, otherwise only the first plane is saved!
\begin{notice}{note}{Note:}
Only use the \code{save} function when you analyse a small subset of your data, otherwise the full stack will be written to the disk. Don’t forget to turn off this parameter when you’re done optimizing the filters.
\end{notice}
\paragraph{Difference of Gaussians filter:}
\label{tutorial:difference-of-gaussians-filter}
This is an optional filter to improve the contrast of objects. This filter has a ``Mexican Hat'' shape that weighs negatively the intensity at the border of the objects. The main parameter to set here is the \code{size}, as an (x,y,z) tuple, for instance \code{(6,6,11)} would work well for our example. However, we’ll bypass this filter and set it to \code{None}:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{filterDoGParameter} \PYG{o}{=} \PYG{p}{\PYGZob{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{size}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{None}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{sigma}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{None}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{sigma2}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{None}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{save}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{None}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{verbose}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{True}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{p}{\PYGZcb{}}
\end{Verbatim}
For this tutorial, we will not use the DoG filter, as it is unnecessary. The signal from a c-Fos nuclear staining has enough contrast and a simple shape that do not necessitate this additionnal filtering, but it could help increase the contrast of the relevant objects for other experiments.
\begin{notice}{note}{Note:}
As for the background subtraction seen above, you can save the output of the filter to files in a folder. This is important in order to check that the settings you used are effective!
\end{notice}
\paragraph{Extended Maxima:}
\label{tutorial:extended-maxima}
The extended maxima is another filter to use for objects that contain several peaks of intensity, like for instance a higher resolution view of a cell nucleus where you might have a more granular texture. In the case of our tutorial, the c-fos nuclear signal is imaged at low resolution, so the object only appears as a single peak, so we will turn off the extended maxima by setting the \code{hMax} parameter to \code{None}:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{findExtendedMaximaParameter} \PYG{o}{=} \PYG{p}{\PYGZob{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{hMax}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{None}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{size}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{l+m+mi}{0}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{threshold}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{l+m+mi}{0}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{save}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{None}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{verbose}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{True}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{p}{\PYGZcb{}}
\end{Verbatim}
\begin{notice}{note}{Note:}
Saving the files for the output of this filter as explained above would overlay in red the extended maxima found on top of the DoG filtered image (we recommend using also DoG if you use the Extended Maxima).
\end{notice}
\paragraph{Peak Intensity:}
\label{tutorial:peak-intensity}
By default, the code will look for the center of the 3D shape painted by the Extended Maxima and attribute the x,y,z to this coordinate. This is the coordinate that will be saved in the point file. However, we noticed that often, the pixel that contains the highest intensity (the peak) is not always the center of the volume. This is likely due to potential deformations of the shape of the nucleus by the objective lens. To look for the actual peak intensity for the detected object, we’ll use this function:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{findIntensityParameter} \PYG{o}{=} \PYG{p}{\PYGZob{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{method}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Max}\PYG{l+s}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{size}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{3}\PYG{p}{,}\PYG{l+m+mi}{3}\PYG{p}{,}\PYG{l+m+mi}{3}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{p}{\PYGZcb{}}
\end{Verbatim}
If the parameter \code{method} is set to \code{None}, then the peak intensity will be also the pixel at the center of the volume. We’ll set the parameter to \code{Max} to look if there is a voxel around the center that has a higher intensity than the center. This will be done by looking around the center with a box of a certain \code{size}, that we set here to (3,3,3), which indicates by how many pixels in each direction from the center the code will be looking for a peak of higher intensity.
\paragraph{Cell Volume:}
\label{tutorial:cell-volume}
The cell shape is not used for the cell detection itself (which is just searching for local maxima in intensity), but measuring the cell volume will be important to later remove the local peaks detected that do not correspond to an actual cell. This is done by setting these parameters:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{detectCellShapeParameter} \PYG{o}{=} \PYG{p}{\PYGZob{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{threshold}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{l+m+mi}{700}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{save}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{None}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{verbose}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{True}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{p}{\PYGZcb{}}
\end{Verbatim}
The shape detection is done by a watershed, which will paint the volume of the cell from the detected center outwards. The only parameter to set is the \code{threshold}. The threshold corresponds to the background intensity, and tells the watershed detection where to stop painting. This value is based on the background subtracted image here. If the \code{threshold} is set to \code{None}, then the cell shape detection is bypassed.
\begin{notice}{note}{Note:}
Saving the files for the output of this filter as explained above would show all detected objects. The most convenient is to open the folder of images generated with ImageJ, and apply a LUT (Lookup Table) to color each object differently, for instance using the LUT 3-3-2 RGB. The code will write on the image each detected object with a increasing intensity value, so you can make sure this way that adjacent cells are not blending together.
\end{notice}
\subsubsection{\emph{Heat map generation}}
\label{tutorial:heat-map-generation}
The voxelization makes it easier to look at the results of the cell detection. The voxelization function will create an image of a specified size (usually the size of the Atlas file) and plot the detected cell centers. To make them visible easily, each point will be expanded into a sphere (or cube, or gaussian) of a given diameter. The intensity value of this sphere is set to 1 by default. So if many points are detected, the overlapping spheres will create a high intensity region.
To set the output for the voxelized heat map file (you would usually not change this):
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{VoxelizationFile} \PYG{o}{=} \PYG{n}{os}\PYG{o}{.}\PYG{n}{path}\PYG{o}{.}\PYG{n}{join}\PYG{p}{(}\PYG{n}{BaseDirectory}\PYG{p}{,} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{points\PYGZus{}voxelized.tif}\PYG{l+s}{\PYGZsq{}}\PYG{p}{)}\PYG{p}{;}
\end{Verbatim}
And then let’s survey the parameters for the voxelization:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{voxelizeParameter} \PYG{o}{=} \PYG{p}{\PYGZob{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{method}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{l+s}{\PYGZsq{}}\PYG{l+s}{Spherical}\PYG{l+s}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{size}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{15}\PYG{p}{,}\PYG{l+m+mi}{15}\PYG{p}{,}\PYG{l+m+mi}{15}\PYG{p}{)}\PYG{p}{,}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} } \PYG{l+s}{\PYGZdq{}}\PYG{l+s}{weights}\PYG{l+s}{\PYGZdq{}} \PYG{p}{:} \PYG{n+nb+bp}{None}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{p}{\PYGZcb{}}\PYG{p}{;}
\end{Verbatim}
The \code{method} here is set to \code{Spherical} to paint the points as expanded spheres. the \code{size} of those spheres is set next, and is given in pixels. Here, we’ll choose \code{(15,15,15)}, but feel free to experiment! Note that the size is in pixels in the final resolution. So for instance, here each sphere will have a diameter of 15 x 25 = 375µm. The \code{weights} parameter will be changed later, but is set to \code{None} at this point, meaning that each sphere has an intensity value of 1. The weights allows to change this by integrating the size or intensity of the cells when drawing each sphere.
\subsubsection{\emph{Config parameters}}
\label{tutorial:config-parameters}
There are two configuration parameter you should change to match the processing power of your workstation. The first one is the number of processors to be used for the resampling/rotation operations. As this process is not very demanding for the memory, just use the max number of parallel processes your configuration can handle. For instance, we have a 6 cores machine:
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{ResamplingParameter} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{l+s}{\PYGZdq{}}\PYG{l+s}{processes}\PYG{l+s}{\PYGZdq{}}\PYG{p}{:} \PYG{l+m+mi}{12}\PYG{p}{\PYGZcb{}}\PYG{p}{;}