== Customizing the e2projectmanager workflow tree: ==
Unlike, e2workflow.py, e2projectmanager can be easily customized. The SPR and Tomo workflow trees 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(except for those marked 'optional') 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 e2program 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. 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.
 * filecheck, this specifies whether or not to check for existence of a file. Only used with the filebox GUI type. Default is True
 * 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.

 * 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



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". Note that the order of quotation does matter. Single quotes should be inside double quotes.
 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

=== EM Browser widgets ===
These widgets derive from EMBrowser widget, and serve as a file browser suited to a particular task. Often you will use one of these as a value for the option 'browser' in your e2program. Admittedly, many of these derived classes exist simply to display results in a sub directory or filter files/directories. Perhaps this is not the best design, but it is workable. It might be redesigned in the future. 

 * EMRefine2dWidget, a browser to display results of e2refine2d. This displays directories named 'r2d_*'
 * EMValidateTable,  a browser to display results of e2tiltvalidate. This displays directories named 'TiltValidate*'
 * EMRefineTable, a browser to display results of e2refine and e2refinefromfrealign. This displays directories named refine* and frealign*. If you want to add additional directories just modify the attribute 'regex' in the EMRefineModel class in the module empmwidgets.
 * EMModelsTable, a browser to display files in the subdirectory 'initial_models'. Displayed columns: quality, and dimensions
 * EMSetsModel, a browser to display files in the subdirectory 'sets'. Displayed columns: number of images, and dimensions
 * EMParticlesModel, a browser to display files in the subdirectory 'particles'. Displayed columns: image type, number of images, dimensions, quality 
 * EMCTFParticlesTable, a browser to display files in the subdirectory 'particles'. Displayed columns: image type, number of images, defocus, bfactor, snr, quality, sampling
 * EMCTFcorrectedParticlesTable, this browser subclasses EMCTFParticlesTable, but filters files to pass *_ctf_wiener* and *_ctf_flip*
 * EMParticlesEditTable, this browser displays files in the subdirectory 'particles' and when a 2D stack is displayed, 'bad' particles can be demarcated. Displayed columns: image type, number of images, number of bad particles, defocus, bfactor, snr, quality, particle dimensions
 * EMBoxesTable, a browser to display files in the subdirectory 'micrographs'. Displayed columns: boxcount, quality, and micrograph quality
 * EMRCTBoxesTable, a browser to display files in the subdirectory 'micrographs'. Displayed columns: boxcount, quality, and micrograph quality. The only difference between this and EMBoxesTable, is the RCT and boxer have different databases.
 * EMRawDataTable, a browser to display files in the subdirectory 'micrographs'. Displayed columns: dimensions, micrograph quality
 * EMSubTomosTable, a browser to display files in the subdirectory 'subtomograms'. Displayed columns: number of sub tomograms, dimensions
 * EMTomoDataTable, a browser to display files in the subdirectory 'rawtomograms'. Displayed columns: dimensions

If you don't find these browser widgets suitable you can derive from EMBrowserWidget and write your own.<<BR>>
In addition to the above browser widgets you may find useful the empmwidget:

 * PMFSCTableWidget, a table widget to display FSC results.