An introduction to Leginon¶

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/
is the central location for leginon information and links.

Once registed for leginon download, the users have access to the bulletin board where users and
developers post their questions and answers.

Official bug report and feature request should be entered through bugzilla .

</abstract>

Terminology¶

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.

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.

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.

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".

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.

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.

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.

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).

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.

Graphical User Interface¶

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.

Leginon Window¶

The window is divided into sections.

• Status bar - Leginon status display such as completion of application
  loading.

• Main Menu - Submenus and options derived from Manager and Launcher

• 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.

• Error indicator - This icon will appear next to a node (in the Node Selector) that has an
  error.

• Message Log Information indicator
  - This icon will appear next to a node (in the Node Selector) that has information in
  its message log.

• User Input indicator - This icon will appear next to a node (in the Node Selector) that
  requires User input in order to continue processing.

• Processing indicator - This icon will appear next to a node (in the Node Selector) that
  currently doing processing.

Node Panel¶

• Node Panel - The main display/control panel for the node selected by the node
  selector.

• Toolbar - An area containing tools for general configuration and execution of the
  node as well as some tools for convenience specific for individual node.

• Message Log - Expandable/scrollable box showing logged information for the
  node.

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.

• Restricted-entry: The user can only select a valid entry from a list.

• 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.

• 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.

Image Viewing¶

• Display Panel - where the image is shown.

• (pixel value button) - 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) - 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)
  - Magnifying glass tool that zoom in (left click) or out (right click) at the location
  of the cursor.

• (zoom selector list) - Direct zoom factor selector.

• (cross hair button) - 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.

• Image Stats Panel

• 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.

• (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) - Display selection. Only one of the image type can be displayed at
  one time.

• (target/marker display tool) - 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) - 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) - 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.

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).

Settings Window¶

Settings windows are opened by left clicking its button
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.

• 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.

• 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.

• OK or Done: close the setting window and save all modified settings to the
  database.

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)
  : 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) : Pause data processing flow when the current input in a queue list is done.

• (Abort button)
  : Abort all data processing of the whole list in the queue.

Minimum Requirement and current NRAMM setup¶

*Recommendation is based on the current NRAMM setup

Electron Microscope with its Controling Computer¶

FEI Tecnai 12 with Scripting SW, network connected, and the ability to install software
on it

CCD¶

Gatan, or Tietz-minimal 1kx1k; NRAMM 4kx4k

A Second Computer¶

CPU¶

Minimal 1 GHz; NRAMM AMD Athlon 64 FX-60 Dual Core 2.6 GHz

RAM¶

Minimal 1 GB physical memory and 1GB swap; NRAMM 4GB physical memory and 2GB
swap

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

Network connection¶

100 Mbps; NRAMM 1 Gbps

Leginon system components developed at Leginon home¶

Leginon Home: http://www.leginon.org/

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.

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.

Getting Started¶

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).

Download Leginon System¶

http://www.leginon.org/

Install Leginon System¶

Refer to the <link linkend="completeinstall">Complete Installation</link>

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>.

Test run¶

Refer to <link linkend="runleg_chapter">Start Leginon</link> chapter for test run on
the microscope and on a remote computer.

Align the microscope¶

Refer to <link linkend="microscope_setup">Microscope Set-up</link>

Calibrate Leginon for the microscope¶

Refer to the <link linkend="calapp_chapter">Calibrations chapter</link>

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>

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 .

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>

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 .

Download Leginon System¶

Leginon Home: http://www.leginon.org/

Direct links to downloads:

• http://emg.nysbc.org/software/leginon/

• http://emg.nysbc.org/software/dbemtools/

• http://emg.nysbc.org/software/mrctools .

Install Leginon System¶

Refer to the <link linkend="completeinstall">Complete Installation</link>

Add Users, Groups, Instruments, Calibrations, and Applications¶

Refer to <link linkend="addusers">Administration</link>

Test run¶

Refer to <link linkend="runleg_chapter">Start Leginon</link> chapter for test run on
the microscope and on a remote computer.

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).

Align the microscope¶

Refer to <link linkend="microscope_setup">Microscope Set-up</link>

Recording images with Low Dose Kit on the microscope¶

Refer to using the <link linkend="manual_app">Manual</link> application

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>

Help yourself and others¶

Refer to <link linkend="MSI_troubleshooting">User Trouble Shooting</link>