An Introduction to Leginon » History » Revision 3
Revision 2 (Amber Herold, 04/14/2010 03:17 PM) → Revision 3/8 (Amber Herold, 04/14/2010 03:20 PM)
h1. An introduction to Leginon # [[What is the Leginon System?]] # [[Terminology]] # [[Graphical User Interface]] # [[Minimum Requirements and current NRAMM setup]] # [[Getting Started]] h2. What is Leginon System? <abstract> Leginon system include the python-side programs that are writen in python and c, the MySQL database and server, and the mainly php-based image and data viewers on a web server. The python-side programs provide a modular framework for building applications for TEM image acquisition and analysis. Nodes can be connected through abstract events in Leginon's modular architecture design. This gives Leginon the flexibility of application customization at multiple levels. Because nodes can be launched from different machines, Leginon's applications can inherently use distributed memory systems. The MySQL-side database and server keep track of all information (metadata) accompanying the acquired images efficiently. The php-side web server and scripts retrieve information from the database and the file storage system to display both raw information and organized reports. NRAMM development includes the python-side and the php-side scripts. MySQL side uses directly the open-source distribution. The website "http://leginon.scripps.edu/":http://leginon.scripps.edu is the central location for leginon information and links. 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 developers post their questions and answers. Official bug report and feature request should be entered through "bugzilla":http://emg.nysbc.org/bugzilla/enter_bug.cgi?product=Leginon . </abstract> h2. Terminology h2. Application A Leginon application is image acquisition process that is built of several smaller pieces called 'nodes'. An application defines your preferred scheme for how to acquire images. An application definition includes which nodes to use, how they are connected, and where they are running (possibly distributed across several machines). These three concepts of applications (nodes, events, launchers) are described in more detail below. A typical application involves several stages of image acquisition and image processing. Once an application is designed, it can be used repeatedly for different sessions. An application design can be exported for use on other Leginon installations. h2. Session A session is defined as an execution from start to finish of a Leginon application. All data (images, results, etc.) that are created by Leginon is associated with some session. The first thing a user must do when starting Leginon is create a session, or continue an existing session. h2. Instrument An instrument is the microscope/camera system used for acquiring data during a particular session. The facility at which Leginon is installed may have several different microscopes, each with a unique camera setup. Each system is an instance of an Instrument. h2. Node Nodes are the building blocks of Leginon applications. Nodes are defined for specific tasks. For instance, an "Acquisition" node is designed to acquire images when it receives targets from another node, which is typically some type of 'TargetFinder' node. Nodes can "publish" the data they create. This means they are making their data public for other nodes to use. The other nodes can "research" to find a specific item of data. Nodes may communicate with each other by generating "events". h2. Event An event is a message sent out from a node to notify other nodes that something of interest has happened. A common example is to announce that some data has been published. Another example is to announce that some process has finished. The declaration of which events are routed between which nodes is part of the application design process. h2. Manager Manager is the master of all nodes in an application. Its existence is usually transparent while running a session, but it is responsible for starting up the application with all its nodes and event bindings. It works behind the scenes to ensure that events are properly distributed throughout the system. h2. Launcher A Launcher is the parent process for a set of nodes. There is typically one launcher running on each machine that you intend to have nodes running on. The assignment of which nodes will be started on a particular launcher is defined as part of the application. h2. Preset A preset is a piece of data which encapsulates the state of an instrument. At any time, the current state of an instrument (magnification, image shifts, camera settings, etc) can be recorded for later use. There is a particular class of Node called the PresetsManager which maintains a list of presets for the current Leginon session. These presets are used by other nodes to set the state of the instrument prior to acquiring an image. This allows for a series of images to be acquired at a consistent state, but possibly different targets (see below). This is very similar to the "Low Dose" system on many microscopes, which consists of a few presets like "Search", "Focus", and "Exposure". The Leginon PresetsManager is a more generalized approach which allows for and unlimited number of presets to be used (like several search presets at different magnifications, or multiple exposure presets at different defocus). h2. Target A target is a location where an image will be acquired. Targets are often selected from existing images (using a TargetFinder node). Acquisition nodes are responsible for interpreting Targets and then acquiring images of them. h2. Graphical User Interface h2. How to use this manual Many places in the manual, a specific section of a window for a node on a launcher/computer/instrument is mentioned. The first time they are mentioned, the full path is shown as computer/program window/node/subsection of the node to open the setting window/setting window/section in the window> It is assumed that the user knows how to follow this path to the specific section of the window by reading the following graphical user interface (GUI) manual and by a little of practice. A abbreviated path rather than the full path will be shown in the latter steps for the same node or application. h2. Leginon Window The window is divided into sections. * Status bar - Leginon status display such as completion of application loading. !http://emg.nysbc.org/software/leginon/images/images/statusbar.png! * Main Menu - Submenus and options derived from Manager and Launcher !http://emg.nysbc.org/software/leginon/images/images/mainmenu.png! * Node Selector - Selection for the node shown in the toolbar, message log, and node panel. It is also used to indicate warning by turning red for broken node. !http://emg.nysbc.org/software/leginon/images/images/nodeselector.png! * 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 error. * Message Log Information indicator !http://emg.nysbc.org/software/leginon/images/icons/info.png! - This icon will appear next to a node (in the Node Selector) that has information in its message log. * 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 requires User input in order to continue processing. * 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 currently doing processing. h2. Node Panel * Node Panel - The main display/control panel for the node selected by the node selector. !http://emg.nysbc.org/software/leginon/images/images/nodepanel2.png! * Toolbar - An area containing tools for general configuration and execution of the node as well as some tools for convenience specific for individual node. !http://emg.nysbc.org/software/leginon/images/images/toolbar.png! * Message Log - Expandable/scrollable box showing logged information for the node. !http://emg.nysbc.org/software/leginon/images/images/messagelog.png! h2. Parameter Entry * Free entry box- For typing in either text or numbers. If in a setting window, the altered entry is saved to the database when it is exited with "OK" or after "Apply"/"Test". Most numerical entry accepts floating point number in any python format. For example, 10.2 can also be entered as 1.02e+2. !http://emg.nysbc.org/software/leginon/images/images/Entry_box.png! * Restricted-entry: The user can only select a valid entry from a list. !http://emg.nysbc.org/software/leginon/images/images/Entry_box_restricted.png! * List box- This type of selection box select either an ordered sequence or a simple unordered list. If ordered, the items in the sequence can order with "up" and "down" tools. !http://emg.nysbc.org/software/leginon/images/images/List_box.png! * If ordered, the items in the sequence can be shifted around with "up" and "down" tools. * Either free or restricted entry box is used for entering a new item to the list. "+" tool is used to add the entry to the list box. selecting an existing item and press "-" tool removes the item from the list. * Multiple items can be selected by holding down the "ctrl" or "shift" key. The latter selects a range between the first and the new items. h2. Image Viewing * Display Panel - where the image is shown. * (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 cursor. The coordinate origin is set at top-left corner. * (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 cursor position. Left click at any position inside the display panel defines the reference point. * (zoom button) !http://emg.nysbc.org/software/leginon/images/icons/zoom.png! - Magnifying glass tool that zoom in (left click) or out (right click) at the location of the cursor. * (zoom selector list) !http://emg.nysbc.org/software/leginon/images/images/zoomselector.png! - Direct zoom factor selector. * (cross hair button) !http://emg.nysbc.org/software/leginon/images/images/bluech.png! - Cross hair reference tool displaying a blue cross hair centered at the center of the image for reference. * (display range selection/input) - Contrast and brightness adjustment of the image display. The default is mean +/- 5*standard deviation of image intensity. This can be modified by setting the minimum (top scroll bar or entry box) and the maximaum (bottom scroll bar or entry box) of the display range. !http://emg.nysbc.org/software/leginon/images/images/contrbright.png! * Image Stats Panel !http://emg.nysbc.org/software/leginon/images/images/imstatpanel.png! * Image/Target/Marker Control Panel - where the image and targets to be displayed in the display panel are determined. Targets are indicated by short cross symbols or other shapes of different colors. The items shown with a screen icon are of image type. Items of image type can be displayed alone while markers will show only when one of the items of image type is also displayed. !http://emg.nysbc.org/software/leginon/images/images/imcontrolpanel.png! * (status indicator) <inlinegraphic fileref="http://emg.nysbc.org/software/leginon/images/icons/green.png" format="PNG"/> <inlinegraphic fileref="http://emg.nysbc.org/software/leginon/images/icons/red.png" format="PNG"/> - This can be either green or red. During a step-by-step testing of parameters, green indicates that the step has been tested and you can proceed to the next testing step. Skiping to a step below a red-indicated step will cause an error. * (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 one time. * (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 the green target) is active. More than one type of markers can be displayed on layers above the image. If the markers are overlapped, the marker last to be activated for display is at the top. * (marker tool) !http://emg.nysbc.org/software/leginon/images/icons/arrow.png! - Marker input selection. Certain markers can be manually edited. In general, these are targets for further acquisition. In such case, the marker selection tool can be activated by left clicking the icon. Once activated, left click in the display panel adds the marker to the image and right click removes the marker pointed to. * (settings) !http://emg.nysbc.org/software/leginon/images/icons/settings.png! - Settings are available for certain items in the image control panel, mainly steps in automatic hole finding. Left click opens the setting window and the behavior of the setting window is similar to others of the same type. h2. Tool Bar Tool bar of the node contains tools for setting and execution of the node functions. In addition, some tools are available as pop-up for convenience. The general rule for the flow of setting up and execution is to go from left to right up to the execution tool (execution icon). !http://emg.nysbc.org/software/leginon/images/images/toolbar.png! h2. Settings Window Settings windows are opened by left clicking its button !http://emg.nysbc.org/software/leginon/images/icons/settings.png! in the toolbar. Note that only one setting swindow can be opened at a time and that all functions in the main leginon window is inactivated when a settings window is open even if the leginon window is the focus. The content of the settings window depends on the purpose of the settings. The general controls are described here: * Test: found in settings of image processing steps. When clicked, the current setting in the window is saved to database and applied to the current input and the results saved as its output. If the item output is displayed in the node display panel, the content will be changed accordingly. !http://emg.nysbc.org/software/leginon/images/images/test.png! * Apply: save the modified setting to database for future execution but not the current test input. It is activated only if the modification of the input is completed, normally by pressing the Enter key on the keyboard. Since current GUI does not allow changes to the main window to be made while setting window is on, Using button is not necessary since "OK" button will save the settings anyway. !http://emg.nysbc.org/software/leginon/images/images/apply.png! * Cancel: close the setting window and revert the setting to the last saved values. This means you can not cancel setting modification if you have "test"ed or "apply"ed the settings. !http://emg.nysbc.org/software/leginon/images/images/cancel.png! * OK or Done: close the setting window and save all modified settings to the database. !http://emg.nysbc.org/software/leginon/images/images/ok.png! h2. Execution tools Found in the node toolbar. They may take on different meanings for different node classes. The general ones are described here: * (Execute/Submit button) !http://emg.nysbc.org/software/leginon/images/icons/play.png! : Perform one of the four possible functions if available and active for a node: * When the application is in standby, it executes, sometimes with setting up the main function of the node. * When the application is running automatically, it indicates that the node is in use. * When the application is paused for user input, it submit the user approved inputs and continue on the flow. * When the application is paused by the "pause" tool in the same node, it removes the pause flag and continue on the application flow. * (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. * (Abort button) !http://emg.nysbc.org/software/leginon/images/icons/stop.png! : Abort all data processing of the whole list in the queue. h2. Minimum Requirement and current NRAMM setup *Recommendation is based on the current NRAMM setup h2. Electron Microscope with its Controling Computer FEI Tecnai 12 with Scripting SW, network connected, and the ability to install software on it h2. CCD Gatan, or Tietz-minimal 1kx1k; NRAMM 4kx4k h2. A Second Computer h2. CPU Minimal 1 GHz; NRAMM AMD Athlon 64 FX-60 Dual Core 2.6 GHz h2. RAM Minimal 1 GB physical memory and 1GB swap; NRAMM 4GB physical memory and 2GB swap h2. Hard drive 10 GB for the softwares and maybe a few hours worth of data collection. Much larger for routine use. NRAMM 15Tb and growing h2. Network connection 100 Mbps; NRAMM 1 Gbps h2. Leginon system components developed at Leginon home Leginon Home: "http://www.leginon.org/":http://www.leginon.org/ h2. Supporting packages and programs available through internet or you Linux distribution There are minimum of ten packages or single programs, some of them are included in your Linux distribution. h2. Leginon supporting programs available upon request adaexp.exe that is required if film exposure is to be made through Leginon on FEI Tecnai machines is available by request. Please contact Max Otten: <email>mto@nl.feico.com</email> and let him know what version of the Tecnai user interface you are using. h2. Getting Started h2. Full (Super User) Manual - Getting Started These steps are a general overview of walking through the entire procedure involving installation, microscope alignment, calibrations, and using Leginon applications (e.g. Manual, Calibrations, MSI). h2. Download Leginon System "http://www.leginon.org/":http://www.leginon.org/ h2. Install Leginon System Refer to the <link linkend="completeinstall">Complete Installation</link> h2. Add Users, Groups, Instruments, Calibrations, and Applications Refer to <link linkend="addusers">Administration</link> For advanced Leginon users who would like to create an application, see the <link linkend="createapp">application creation chapter</link>. h2. Test run Refer to <link linkend="runleg_chapter">Start Leginon</link> chapter for test run on the microscope and on a remote computer. h2. Align the microscope Refer to <link linkend="microscope_setup">Microscope Set-up</link> h2. Calibrate Leginon for the microscope Refer to the <link linkend="calapp_chapter">Calibrations chapter</link> h2. Set-up and Run MSI Refer to <link linkend="MISQuickStart">MSI quick set-up checklist</link> AND Refer to <link linkend="leg1operation">MSI Operation</link> h2. Help yourself and others Refer to <link linkend="Inst_troubleshooting">Installation Trouble Shooting</link>, <link linkend="MSI_troubleshooting">User Trouble Shooting</link> and Leginon "Bulletin Board":http://emg.nysbc.org/bb/viewforum.php?f=2 . h2. Know the details For advanced Leginon users who would like to create an application, see the <link linkend="createapp">application creation chapter</link>. Refer to <link linkend="Nodes">Node Description</link> h2. Installation (System Administrator) - Getting Started These steps are geared soley towards the system administator(s) that will installing Leginon and setting it up initially for the rest of the Leginon users that need not be concerned with these details. Refer to <link linkend="Inst_troubleshooting">Installation Trouble Shooting</link>, and Leginon "Bulletin Board":http://emg.nysbc.org/bb/viewforum.php?f=2 . h2. Download Leginon System Leginon Home: "http://www.leginon.org/":http://www.leginon.org/ Direct links to downloads: * "http://emg.nysbc.org/software/leginon/":http://emg.nysbc.org/software/leginon/ * "http://emg.nysbc.org/software/dbemtools/":http://emg.nysbc.org/software/dbemtools/ * "http://emg.nysbc.org/software/mrctools":http://emg.nysbc.org/software/mrctools . h2. Install Leginon System Refer to the <link linkend="completeinstall">Complete Installation</link> h2. Add Users, Groups, Instruments, Calibrations, and Applications Refer to <link linkend="addusers">Administration</link> h2. Test run Refer to <link linkend="runleg_chapter">Start Leginon</link> chapter for test run on the microscope and on a remote computer. h2. Short Manual (Basic Leginon User) - Getting Started These steps are intended to help the basic Leginon user who will operate Leginon (and not care about installation or the first-time calibrations). h2. Align the microscope Refer to <link linkend="microscope_setup">Microscope Set-up</link> h2. Recording images with Low Dose Kit on the microscope Refer to using the <link linkend="manual_app">Manual</link> application h2. Set-up and run MSI Refer to <link linkend="MISQuickStart">MSI quick set-up checklist</link> AND Refer to <link linkend="leg1operation">MSI Operation</link> h2. Help yourself and others Refer to <link linkend="MSI_troubleshooting">User Trouble Shooting</link>