= e2ProjectManager =
The e2projectmanager is a GUI project manager system for EMAN2, which guides the user through a series of steps to achieve either a single particle reconstruction or an sub tomogram average depending on the mode e2projectmanager is being used. This GUI is intended to replace the antiquated e2workflow system.

To run, simply type (in any directory):

{{{
e2projectmanager.py
}}}
If you run the project manager in a project directory, e2projectmanager will load this project. If you are not in a project directory or you want to work with a different project, simply browse to the desired directory by clicking, Project->Open Project. To edit an existing project(or configure a new project), Project->Edit Project.

e2ProjectManger can, currently, be run in two modes, SPR (Single Particle Reconstruction) and Tomo(tomographic). To change modes use the combobox above the workflow tree.

=== Creating a new project ===
To create a new project:
 1. Move to the desired directory
 1. launch e2projectmanager by, at the command prompt, typing: e2projectmanager.py
 1. In the menu bar click Project->Edit Project
 1. This will pull up a dialog box. Set the project name (what every you like), a project icon (will appear in the upper left corner of e2projectmanager), and the microscope data collection parameters (CS, Voltage, apix).
 1. Click 'ok' to apply the changes
 1. Choose the mode. For now there are only two modes, SPR and tomo mode.
 1. Begin processing you data, as you would in e2workflow.py

The above steps outline an appoach to dataprocessing that closely mirrors e2workflow.py, however e2projectmanager.py has much extended capability. :D

=== Using e2projectmanger.py GUI interface to e2programs ===
When you click on a leaf node of the workflow tree, a GUI interface to an e2program is displayed in the main frame, to the right of the workflow tree(see diagram below).
This GUI has three tabs.
 1. The first Tab is a GUI interface to the e2program, you can fill out these item, and run the program by clicking 'Launch'
 1. The second tab lists the command that will be run when clicking on 'Launch'. This text can be edited and the changes will be instated when you launch the program. Alternately, when you tab to 'GUI', the text changes will be reflected in the GUI, provided the option name you listed is present.
 1. The third tab lists GUI help that is listed in the e2program.py body. This can be found in the line usage = """ blah, blah, blah """ in the e2program

When you fill the GUI with information, e2project manager will check your input for sanity. For example: Boxes supposed to contain integers will raise an error, in the status bar, if you enter a string. In addition to datatype checking, filename boxes will check to ensure that the file you list, exists. If you wish to know more information about a field in the GUI you can mouseover the field in question to popup a tooltip, which gives a quick description. If you want more help, you can use the wizard, in the projectmanager toolbar (described below).
 
{{attachment:pm.png}}

=== Using the Wizard to fill the GUI interface ===
For novice users it is advisable to use the wizard to help fill out the GUI interface. To use the GUI, open the desired GUI to fill out, then click on the Wizard tool: {{attachment:wizard.png}}<<BR>>
The wizard, usig the QT wizard framework, and walks the user through filling the fields in the GUI interface. The first step gives an introduction to the programs, and all subsequent steps give instructions on how to fill out each field in the GUI. To move from one step to the next, use the wizard ''next'' and ''previous'' buttons. When you reach the end click the ''finish'' button to close the wizard and finish filling out the GUI. At each step the wizard will check the input of sanity (data type checks and file existence). If the parameters are insane, an error will be printed to the PM status bar. You will not be permitted to proceed until these errors are corrected. :o

=== Description of the PM tools in the left vertical toolbar ===
{{attachment:browser.png}} This will display the filebrowser so you can browse through your files<<BR>>
{{attachment:e2help.png}} This is a GUI interface to the e2help.py. Using this GUI you can display help info for aligners, comparitors, processors, etc.<<BR>>
{{attachment:notepad.png}} This displays a widget to act as an electronic notebook for your project. Most programs that you run will display themselves along with all input parameters in this widget. The text is saved in your local directory as pmnotes.html<<BR>>
{{attachment:jobstatus.png}} This display a widget to display the job status of EMAN2 jobs, if you wish to terminate a job, use this widget to kill it. If you kill it manually your may create orpahn jobs, whereas this widget will remove the main job and all child jobs.<<BR>>
{{attachment:wiki.png}} This will load the wiki page in your default browser for the current e2program. If this toolbar is greyed out either there is no wiki page or it is not listed in the JSON file.<<BR>>
{{attachment:wizard.png}} This will load the wizard for the current e2program. If this tool is greyed out, there is no wizard available.<<BR>>
{{attachment:expert.png}} This will add fields to the e2program GUI interface, that are ment for expert users only. If this tool is greyed out, there are no expert fields for the current e2program.<<BR>> 
 
=== Customizing the e2projectmanager workflow tree: ===
Unlike, e2workflow.py, e2projectmanager can be easily customized. The SPR and Tomo workflow tree are constructed using the JSON files, spr.json and tomo.json, respectively.  These files reside in lib/pyemtbx or in the source code, libEM/pmconfig, and can be edited to customize the tree. The JSON file contains a list of dictionaries, which represents a toplevel(root/base) item in the workflow tree. Each dictionary must contain the following key-value pairs:

 * "ICON", the icon representing this item in the tree. The possibilites are: "single_image", "multiple_images", "green_boxes", "ctf", "web", "single_image_3d", "refine", "eulers", "resolution", "tomo_hunter". Additional icons can be added by editing the icons.json file.
 * "PROGRAM", the name of the e2 program that runs when this tree item is clicked
 * "NAME", the name of this tree item
 * "TABLE", the table to display when the user clicks on a node containing children(not a leaf node!). This table can be any QWidget, most often it is a EMBrowser widget or a EMPMwidget(table). Please note that if you have the PROGRAM flag in the same node as the TABLE flag, the PROGRAM and not the table will be displayed.
 * "CHILDREN", a list of dicts that list the child tree items. If the are no children then use a blank list, []
 * "MODE", a key-value pair, that determines the mode the program is run in. More on this in the following section. (optional)
 * "EXPERT", a flag to tell the PM that this program mode has a expert mode. This will enable the expert toolbar button. (optional)
 * "WIKIPAGE", link to this PROGRAM's Wiki (optional) 
 * "WIZARD", specify to wizard file for this PROGRAM. This must be a json file and these should reside in the same directory as spr.json and tomo.json. (optional) 
 * "NOTELEVEL", if set to 1 or greater, the program output will be loged in the notebook (optional)

=== Enabling your e2program to be read by e2projectmanager: ===
To enable e2projectmanger to read your e2program and construct a GUI, some flags  in the options code need to be set. You must use the EMAN2 parser, EMArgumentParser, a subclass of argparser. The standard key-value pairs of argparsers add_argument method can be set. In addition, in EMArgumentParser the following key-value pairs are used to build the GUI.

 * guitype (required), the type of gui widget you want to display. The possibilites are: 'intbox', 'floatbox', 'strbox',  'boolbox', 'filebox', 'combobox', 'comboparambox', 'symbox', 'automask3d'
 * row (required), determines which row the GUI is placed in (uses QGridLayout)
 * col (required), determines which colum the GUI is placed in (uses QGridLayout)
 * rowspan (required), determines the rowspan of the widget
 * colspan (required), determines the columnspan of the widget
 * expert, a boolean value which tells the widget(option) to only appear in expert mode. Default=False
 * choicelist, used in the combobox and comboparambox widgets. This is a string which is eval'ed to generate a list or a dictionary whose keys are displayed in the combobox widget
 * lrange, used in the intbox, float box widgets, sets the lower value bound
 * urange, used in intbox and floatbox widgets, sets the upper value bound
 * returnNone, specifies that a string or combobox returns the argument --arg=None rather than no argument(which means your program will use the default). You should specify this if this option is configured to process None. Otherwise your program might crash due to a bad design in some e2programs.
 * browser, used to specify what type of browser you want to use for file selection. This can only be used with the filebox guitype. The avaliable types are listed below.
 * nosharedb, for use only if modes are used. This, when set to True, allows each mode to own its on entry in the DB, otherwise they are shared.
 * mode, this is only used if in the JSON file you added the key-value pair, "MODE":"myvalue". This is used if you want to have multiple tree items that run the same program, but display different GUIs. The mode allows specification of which GUI should display which option(widget). For example if in the JSON file I set "MODE":"test", then I would add mode="test" as an option key-value pair. Each mode can set its own default, by appending mode with mode[default].

In addition to argparser's add_argument method, EMArgumentParser has the methods:

 * add_pos_argument, this method allows a positional argument widget to set. The above key-value pairs can be used, in addition to:

 * add_header, this method allows a header label to be displayed in the GUI. This method used the key-value pairs, row,col,colspan,rowspan in addition to:



The add_pos_argument method has in addition to add_arguments key-value options:
 
 * name, the name of this argument, displayed in the widget(it is set automatically by add_argument)

The add_header method has in addition to add_arguments's key-value options:

 * Title, the text to display in this header label

For examples please see the programs, e2boxer.py, e2refine.py, e2ctf.py, etc

=== Resolving widget default values: ===
The widget default values are set according to the following rules:

 1. If a value for this widget(option) is found in the database, the default is set to the DB value
 1. If the mode flag is set and it has a defined default, this value will be used. For example mode="boxing['abc']" sets the default to 'abc' in mode "boxing".
 1. If a value is not in the database, the default is set to default key-value pair, listed in the options code
 1. otherwise the default=""

In addition to strings you can set ''mode['default']'' to:

 1. self.getCS() which will set the default to the project spherical aberation
 1. self.getVoltage() which will set the default to the project voltage
 1. self.getAPIX() which will set the default to the project angstrom per pixel
 1. self.getMass() which will set the dafualt to the project mass

For example:
mode="autofit['self.pm().getCS()']")

=== Adding Help information ===
Help information for a program (this  will appear in the help tab of the GUI in e2projectmanager.py) can be added using a line of code:
usage = """Blah, Blah, blah """ Most e2programs already have this information, so for an example open one of these up, such as: e2ctf.py