Leginon

h1. An introduction to Leginon

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>