Project

General

Profile

An Introduction to Leginon » History » Version 2

Amber Herold, 04/14/2010 03:17 PM

1 1 Amber Herold
h1. An introduction to Leginon
2
3 2 Amber Herold
# [[What is the Leginon System?]]
4
# [[Terminology]]
5
# [[Graphical User Interface]]
6
# [[Minimum Requirements and current NRAMM setup]]
7
# [[Getting Started]]
8 1 Amber Herold
9
10
11
12
h2. What is Leginon System?
13
14
15
<abstract>
16
17
Leginon system include the python-side programs that are writen in python and c, the
18
MySQL database and server, and the mainly php-based image and data viewers on a web
19
server.
20
21
22
The python-side programs provide a modular framework for building applications for TEM
23
image acquisition and analysis. Nodes can be connected through abstract events in Leginon's
24
modular architecture design. This gives Leginon the flexibility of application customization
25
at multiple levels. Because nodes can be launched from different machines, Leginon's
26
applications can inherently use distributed memory systems.
27
28
29
The MySQL-side database and server keep track of all information (metadata) accompanying
30
the acquired images efficiently.
31
32
33
The php-side web server and scripts retrieve information from the database and the file
34
storage system to display both raw information and organized reports.
35
36
37
NRAMM development includes the python-side and the php-side scripts. MySQL side uses
38
directly the open-source distribution.
39
40
41
The website  "http://leginon.scripps.edu/":http://leginon.scripps.edu
42
is the central location for leginon information and links.
43
44
45
Once registed for leginon download, the users have access to the " bulletin board":http://emg.nysbc.org/bb.viewforum.php?f=2  where users and
46
developers post their questions and answers.
47
48
49
Official bug report and feature request should be entered through  "bugzilla":http://emg.nysbc.org/bugzilla/enter_bug.cgi?product=Leginon .
50
51
</abstract>
52
53
54
55
56
h2. Terminology
57
58
59
60
61
h2. Application
62
63
64
65
A Leginon application is image acquisition process that is built of several smaller
66
pieces called 'nodes'. An application defines your preferred scheme for how to acquire
67
images. An application definition includes which nodes to use, how they are connected, and
68
where they are running (possibly distributed across several machines). These three concepts
69
of applications (nodes, events, launchers) are described in more detail below. A typical
70
application involves several stages of image acquisition and image processing. Once an
71
application is designed, it can be used repeatedly for different sessions. An application
72
design can be exported for use on other Leginon installations.
73
74
75
76
77
78
h2. Session
79
80
81
82
A session is defined as an execution from start to finish of a Leginon application. All
83
data (images, results, etc.) that are created by Leginon is associated with some session.
84
The first thing a user must do when starting Leginon is create a session, or continue an
85
existing session.
86
87
88
89
90
91
h2. Instrument
92
93
94
95
An instrument is the microscope/camera system used for acquiring data during a
96
particular session. The facility at which Leginon is installed may have several different
97
microscopes, each with a unique camera setup. Each system is an instance of an
98
Instrument.
99
100
101
102
103
104
h2. Node
105
106
107
108
Nodes are the building blocks of Leginon applications. Nodes are defined for specific
109
tasks. For instance, an "Acquisition" node is designed to acquire images when it receives
110
targets from another node, which is typically some type of 'TargetFinder' node. Nodes can
111
"publish" the data they create. This means they are making their data public for other nodes
112
to use. The other nodes can "research" to find a specific item of data. Nodes may
113
communicate with each other by generating "events".
114
115
116
117
118
119
h2. Event
120
121
122
123
An event is a message sent out from a node to notify other nodes that something of
124
interest has happened. A common example is to announce that some data has been published.
125
Another example is to announce that some process has finished. The declaration of which
126
events are routed between which nodes is part of the application design process.
127
128
129
130
131
132
h2. Manager
133
134
135
136
Manager is the master of all nodes in an application. Its existence is usually
137
transparent while running a session, but it is responsible for starting up the application
138
with all its nodes and event bindings. It works behind the scenes to ensure that events are
139
properly distributed throughout the system.
140
141
142
143
144
145
h2. Launcher
146
147
148
149
A Launcher is the parent process for a set of nodes. There is typically one launcher
150
running on each machine that you intend to have nodes running on. The assignment of which
151
nodes will be started on a particular launcher is defined as part of the application.
152
153
154
155
156
157
h2. Preset
158
159
160
161
A preset is a piece of data which encapsulates the state of an instrument. At any time,
162
the current state of an instrument (magnification, image shifts, camera settings, etc) can
163
be recorded for later use. There is a particular class of Node called the PresetsManager
164
which maintains a list of presets for the current Leginon session. These presets are used by
165
other nodes to set the state of the instrument prior to acquiring an image. This allows for
166
a series of images to be acquired at a consistent state, but possibly different targets (see
167
below). This is very similar to the "Low Dose" system on many microscopes, which consists of
168
a few presets like "Search", "Focus", and "Exposure". The Leginon PresetsManager is a more
169
generalized approach which allows for and unlimited number of presets to be used (like
170
several search presets at different magnifications, or multiple exposure presets at
171
different defocus).
172
173
174
175
176
177
h2. Target
178
179
180
181
A target is a location where an image will be acquired. Targets are often selected from
182
existing images (using a TargetFinder node). Acquisition nodes are responsible for
183
interpreting Targets and then acquiring images of them.
184
185
186
187
188
189
190
191
192
193
h2. Graphical User Interface
194
195
196
197
198
h2. How to use this manual
199
200
201
202
Many places in the manual, a specific section of a window for a node on a
203
launcher/computer/instrument is mentioned. The first time they are mentioned, the full path
204
is shown as
205
206
207
computer/program window/node/subsection of the node to open the setting window/setting
208
window/section in the window>
209
210
211
It is assumed that the user knows how to follow this path to the specific section of the
212
window by reading the following graphical user interface (GUI) manual and by a little of
213
practice. A abbreviated path rather than the full path will be shown in the latter steps for
214
the same node or application.
215
216
217
218
219
220
h2. Leginon Window
221
222
223
224
The window is divided into sections.
225
226
227
* Status bar - Leginon status display such as completion of application
228
loading.
229
230
231
232
!http://emg.nysbc.org/software/leginon/images/images/statusbar.png!
233
234
235
236
* Main Menu - Submenus and options derived from Manager and Launcher
237
238
239
240
!http://emg.nysbc.org/software/leginon/images/images/mainmenu.png!
241
242
243
244
* Node Selector - Selection for the node shown in the toolbar, message log, and node
245
panel. It is also used to indicate warning by turning red for broken node.
246
247
248
249
!http://emg.nysbc.org/software/leginon/images/images/nodeselector.png!
250
251
252
253
* Error indicator !http://emg.nysbc.org/software/leginon/images/icons/error.png! - This icon will appear next to a node (in the Node Selector) that has an
254
error.
255
256
257
* Message Log Information indicator !http://emg.nysbc.org/software/leginon/images/icons/info.png!
258
- This icon will appear next to a node (in the Node Selector) that has information in
259
its message log.
260
261
262
* User Input indicator !http://emg.nysbc.org/software/leginon/images/icons/userinput.png! - This icon will appear next to a node (in the Node Selector) that
263
requires User input in order to continue processing.
264
265
266
* Processing indicator !http://emg.nysbc.org/software/leginon/images/icons/processing/green0.png! - This icon will appear next to a node (in the Node Selector) that
267
currently doing processing.
268
269
270
271
272
273
274
275
h2. Node Panel
276
277
278
279
280
281
* Node Panel - The main display/control panel for the node selected by the node
282
selector.
283
284
285
286
!http://emg.nysbc.org/software/leginon/images/images/nodepanel2.png!
287
288
289
290
* Toolbar - An area containing tools for general configuration and execution of the
291
node as well as some tools for convenience specific for individual node.
292
293
294
295
!http://emg.nysbc.org/software/leginon/images/images/toolbar.png!
296
297
298
299
* Message Log - Expandable/scrollable box showing logged information for the
300
node.
301
302
303
304
!http://emg.nysbc.org/software/leginon/images/images/messagelog.png!
305
306
307
308
309
310
311
312
313
h2. Parameter Entry
314
315
316
317
318
319
* Free entry box- For typing in either text or numbers. If in a setting window, the
320
altered entry is saved to the database when it is exited with "OK" or after
321
"Apply"/"Test". Most numerical entry accepts floating point number in any python format.
322
For example, 10.2 can also be entered as 1.02e+2.
323
324
325
326
!http://emg.nysbc.org/software/leginon/images/images/Entry_box.png!
327
328
329
330
* Restricted-entry: The user can only select a valid entry from a list.
331
332
333
334
!http://emg.nysbc.org/software/leginon/images/images/Entry_box_restricted.png!
335
336
337
338
* List box- This type of selection box select either an ordered sequence or a simple
339
unordered list. If ordered, the items in the sequence can order with "up" and "down"
340
tools.
341
342
343
344
!http://emg.nysbc.org/software/leginon/images/images/List_box.png!
345
346
347
348
* If ordered, the items in the sequence can be shifted around with "up" and "down"
349
tools.
350
351
352
* Either free or restricted entry box is used for entering a new item to the list.
353
"+" tool is used to add the entry to the list box. selecting an existing item and
354
press "-" tool removes the item from the list.
355
356
357
* Multiple items can be selected by holding down the "ctrl" or "shift" key. The
358
latter selects a range between the first and the new items.
359
360
361
362
363
364
365
366
367
368
h2. Image Viewing
369
370
371
372
373
374
* Display Panel - where the image is shown.
375
376
377
* (pixel value button) !http://emg.nysbc.org/software/leginon/images/icons/value.png! - Pixel value display tool that shows the (x,y) coordinate the intensity value at the
378
cursor. The coordinate origin is set at top-left corner.
379
380
381
* (ruler button) !http://emg.nysbc.org/software/leginon/images/icons/ruler.png! - Ruler tool that displays the distance between a reference point and the current
382
cursor position. Left click at any position inside the display panel defines the
383
reference point.
384
385
386
* (zoom button) !http://emg.nysbc.org/software/leginon/images/icons/zoom.png!
387
- Magnifying glass tool that zoom in (left click) or out (right click) at the location
388
of the cursor.
389
390
391
* (zoom selector list) !http://emg.nysbc.org/software/leginon/images/images/zoomselector.png! - Direct zoom factor selector.
392
393
394
* (cross hair button) !http://emg.nysbc.org/software/leginon/images/images/bluech.png! - Cross hair reference tool displaying a blue cross hair centered at
395
the center of the image for reference.
396
397
398
* (display range selection/input) - Contrast and brightness adjustment of the image
399
display. The default is mean +/- 5*standard deviation of image intensity. This can be
400
modified by setting the minimum (top scroll bar or entry box) and the maximaum (bottom
401
scroll bar or entry box) of the display range.
402
403
404
405
!http://emg.nysbc.org/software/leginon/images/images/contrbright.png!
406
407
408
409
* Image Stats Panel
410
411
412
413
!http://emg.nysbc.org/software/leginon/images/images/imstatpanel.png!
414
415
416
417
* Image/Target/Marker Control Panel - where the image and targets to be displayed in
418
the display panel are determined. Targets are indicated by short cross symbols or other
419
shapes of different colors. The items shown with a screen icon are of image type. Items
420
of image type can be displayed alone while markers will show only when one of the items
421
of image type is also displayed.
422
423
424
425
!http://emg.nysbc.org/software/leginon/images/images/imcontrolpanel.png!
426
427
428
429
* (status indicator)
430
431
432
433
<inlinegraphic
434
fileref="http://emg.nysbc.org/software/leginon/images/icons/green.png"
435
format="PNG"/>
436
<inlinegraphic
437
fileref="http://emg.nysbc.org/software/leginon/images/icons/red.png"
438
format="PNG"/>
439
440
441
- This can be either green or red. During a step-by-step testing of parameters,
442
green indicates that the step has been tested and you can proceed to the next
443
testing step. Skiping to a step below a red-indicated step will cause an
444
error.
445
446
447
* (image display tool) !http://emg.nysbc.org/software/leginon/images/icons/display.png! - Display selection. Only one of the image type can be displayed at
448
one time.
449
450
451
* (target/marker display tool) !http://emg.nysbc.org/software/leginon/images/images/target_display.png! - Display target or marker selection. Pressed down (as shown for
452
the green target) is active. More than one type of markers can be displayed on
453
layers above the image. If the markers are overlapped, the marker last to be
454
activated for display is at the top.
455
456
457
* (marker tool) !http://emg.nysbc.org/software/leginon/images/icons/arrow.png! - Marker input selection. Certain markers can be manually edited.
458
In general, these are targets for further acquisition. In such case, the marker
459
selection tool can be activated by left clicking the icon. Once activated, left
460
click in the display panel adds the marker to the image and right click removes the
461
marker pointed to.
462
463
464
* (settings) !http://emg.nysbc.org/software/leginon/images/icons/settings.png! - Settings are available for certain items in the image control
465
panel, mainly steps in automatic hole finding. Left click opens the setting window
466
and the behavior of the setting window is similar to others of the same type.
467
468
469
470
471
472
473
474
475
476
h2. Tool Bar
477
478
479
480
Tool bar of the node contains tools for setting and execution of the node functions. In
481
addition, some tools are available as pop-up for convenience. The general rule for the flow
482
of setting up and execution is to go from left to right up to the execution tool (execution
483
icon).
484
485
486
487
!http://emg.nysbc.org/software/leginon/images/images/toolbar.png!
488
489
490
491
492
493
494
h2. Settings Window
495
496
497
498
Settings windows are opened by left clicking its button !http://emg.nysbc.org/software/leginon/images/icons/settings.png!
499
in the toolbar. Note that only one setting swindow can be opened at a time and that all
500
functions in the main leginon window is inactivated when a settings window is open even if
501
the leginon window is the focus. The content of the settings window depends on the purpose
502
of the settings. The general controls are described here:
503
504
505
* Test: found in settings of image processing steps. When clicked, the current setting
506
in the window is saved to database and applied to the current input and the results
507
saved as its output. If the item output is displayed in the node display panel, the
508
content will be changed accordingly.
509
510
511
512
!http://emg.nysbc.org/software/leginon/images/images/test.png!
513
514
515
516
* Apply: save the modified setting to database for future execution but not the
517
current test input. It is activated only if the modification of the input is completed,
518
normally by pressing the Enter key on the keyboard. Since current GUI does not allow
519
changes to the main window to be made while setting window is on, Using button is not
520
necessary since "OK" button will save the settings anyway.
521
522
523
524
!http://emg.nysbc.org/software/leginon/images/images/apply.png!
525
526
527
528
* Cancel: close the setting window and revert the setting to the last saved values.
529
This means you can not cancel setting modification if you have "test"ed or "apply"ed the
530
settings.
531
532
533
534
!http://emg.nysbc.org/software/leginon/images/images/cancel.png!
535
536
537
538
* OK or Done: close the setting window and save all modified settings to the
539
database.
540
541
542
543
!http://emg.nysbc.org/software/leginon/images/images/ok.png!
544
545
546
547
548
549
550
551
552
h2. Execution tools
553
554
555
556
Found in the node toolbar. They may take on different meanings for different node
557
classes. The general ones are described here:
558
559
560
* (Execute/Submit button) !http://emg.nysbc.org/software/leginon/images/icons/play.png!
561
: Perform one of the four possible functions if available and active for a node:
562
563
564
* When the application is in standby, it executes, sometimes with setting up the
565
main function of the node.
566
567
568
* When the application is running automatically, it indicates that the node is in
569
use.
570
571
572
* When the application is paused for user input, it submit the user approved
573
inputs and continue on the flow.
574
575
576
* When the application is paused by the "pause" tool in the same node, it removes
577
the pause flag and continue on the application flow.
578
579
580
581
582
* (Pause button) !http://emg.nysbc.org/software/leginon/images/icons/pause.png! : Pause data processing flow when the current input in a queue list is done.
583
584
585
* (Abort button) !http://emg.nysbc.org/software/leginon/images/icons/stop.png!
586
: Abort all data processing of the whole list in the queue.
587
588
589
590
591
592
593
594
595
596
h2. Minimum Requirement and current NRAMM setup
597
598
599
600
*Recommendation is based on the current NRAMM setup
601
602
603
604
h2. Electron Microscope with its Controling Computer
605
606
607
608
FEI Tecnai 12 with Scripting SW, network connected, and the ability to install software
609
on it
610
611
612
613
614
615
h2. CCD
616
617
618
619
Gatan, or Tietz-minimal 1kx1k; NRAMM 4kx4k
620
621
622
623
624
625
h2. A Second Computer
626
627
628
629
630
h2. CPU
631
632
633
634
Minimal 1 GHz; NRAMM AMD Athlon 64 FX-60 Dual Core 2.6 GHz
635
636
637
638
639
640
h2. RAM
641
642
643
644
Minimal 1 GB physical memory and 1GB swap; NRAMM 4GB physical memory and 2GB
645
swap
646
647
648
649
650
651
h2. Hard drive
652
653
654
655
10 GB for the softwares and maybe a few hours worth of data collection. Much larger
656
for routine use. NRAMM 15Tb and growing
657
658
659
660
661
662
h2. Network connection
663
664
665
666
100 Mbps; NRAMM 1 Gbps
667
668
669
670
671
672
673
674
h2. Leginon system components developed at Leginon home
675
676
677
678
Leginon Home:  "http://www.leginon.org/":http://www.leginon.org/
679
680
681
682
683
684
h2. Supporting packages and programs available through internet or you Linux
685
distribution
686
687
688
689
There are minimum of ten packages or single programs, some of them are included in your
690
Linux distribution.
691
692
693
694
695
696
697
698
h2. Leginon supporting programs available upon request
699
700
701
702
adaexp.exe that is required if film exposure is to be made through Leginon on FEI Tecnai
703
machines is available by request. Please contact Max Otten: <email>mto@nl.feico.com</email>
704
and let him know what version of the Tecnai user interface you are using.
705
706
707
708
709
710
711
712
713
714
h2. Getting Started
715
716
717
718
719
h2. Full (Super User) Manual - Getting Started
720
721
722
723
These steps are a general overview of walking through the entire procedure involving
724
installation, microscope alignment, calibrations, and using Leginon applications (e.g.
725
Manual, Calibrations, MSI).
726
727
728
729
h2. Download Leginon System
730
731
732
"http://www.leginon.org/":http://www.leginon.org/
733
734
735
736
737
738
h2. Install Leginon System
739
740
741
742
Refer to the <link linkend="completeinstall">Complete Installation</link>
743
744
745
746
747
748
h2. Add Users, Groups, Instruments, Calibrations, and Applications
749
750
751
752
Refer to <link linkend="addusers">Administration</link>
753
754
755
For advanced Leginon users who would like to create an application, see the <link
756
linkend="createapp">application creation chapter</link>.
757
758
759
760
761
762
h2. Test run
763
764
765
766
Refer to <link linkend="runleg_chapter">Start Leginon</link> chapter for test run on
767
the microscope and on a remote computer.
768
769
770
771
772
773
h2. Align the microscope
774
775
776
777
Refer to <link linkend="microscope_setup">Microscope Set-up</link>
778
779
780
781
782
783
h2. Calibrate Leginon for the microscope
784
785
786
787
Refer to the <link linkend="calapp_chapter">Calibrations chapter</link>
788
789
790
791
792
793
h2. Set-up and Run MSI
794
795
796
797
Refer to <link linkend="MISQuickStart">MSI quick set-up checklist</link>
798
799
800
AND
801
802
803
Refer to <link linkend="leg1operation">MSI Operation</link>
804
805
806
807
808
809
h2. Help yourself and others
810
811
812
813
Refer to <link linkend="Inst_troubleshooting">Installation Trouble Shooting</link>,
814
<link linkend="MSI_troubleshooting">User Trouble Shooting</link> and Leginon  "Bulletin Board":http://emg.nysbc.org/bb/viewforum.php?f=2 .
815
816
817
818
819
820
821
822
h2. Know the details
823
824
825
826
For advanced Leginon users who would like to create an application, see the <link
827
linkend="createapp">application creation chapter</link>.
828
829
830
Refer to <link linkend="Nodes">Node Description</link>
831
832
833
834
835
836
837
838
h2. Installation (System Administrator) - Getting Started
839
840
841
842
These steps are geared soley towards the system administator(s) that will installing
843
Leginon and setting it up initially for the rest of the Leginon users that need not be
844
concerned with these details.
845
846
847
Refer to <link linkend="Inst_troubleshooting">Installation Trouble Shooting</link>, and
848
Leginon  "Bulletin
849
Board":http://emg.nysbc.org/bb/viewforum.php?f=2 .
850
851
852
853
h2. Download Leginon System
854
855
856
857
Leginon Home:  "http://www.leginon.org/":http://www.leginon.org/
858
859
860
Direct links to downloads:
861
862
863
*  "http://emg.nysbc.org/software/leginon/":http://emg.nysbc.org/software/leginon/
864
865
866
*  "http://emg.nysbc.org/software/dbemtools/":http://emg.nysbc.org/software/dbemtools/
867
868
869
*  "http://emg.nysbc.org/software/mrctools":http://emg.nysbc.org/software/mrctools .
870
871
872
873
874
875
876
877
h2. Install Leginon System
878
879
880
881
Refer to the <link linkend="completeinstall">Complete Installation</link>
882
883
884
885
886
887
h2. Add Users, Groups, Instruments, Calibrations, and Applications
888
889
890
891
Refer to <link linkend="addusers">Administration</link>
892
893
894
895
896
897
h2. Test run
898
899
900
901
Refer to <link linkend="runleg_chapter">Start Leginon</link> chapter for test run on
902
the microscope and on a remote computer.
903
904
905
906
907
908
909
910
h2. Short Manual (Basic Leginon User) - Getting Started
911
912
913
914
These steps are intended to help the basic Leginon user who will operate Leginon (and
915
not care about installation or the first-time calibrations).
916
917
918
919
h2. Align the microscope
920
921
922
923
Refer to <link linkend="microscope_setup">Microscope Set-up</link>
924
925
926
927
928
929
h2. Recording images with Low Dose Kit on the microscope
930
931
932
933
Refer to using the <link linkend="manual_app">Manual</link> application
934
935
936
937
938
939
h2. Set-up and run MSI
940
941
942
943
Refer to <link linkend="MISQuickStart">MSI quick set-up checklist</link>
944
945
946
AND
947
948
949
Refer to <link linkend="leg1operation">MSI Operation</link>
950
951
952
953
954
955
h2. Help yourself and others
956
957
958
959
Refer to <link linkend="MSI_troubleshooting">User Trouble Shooting</link>