Tutorial to aid adding a new e2program to the e2projectmanager.py
This tutorial covers the necessary steps to incorporate a e2program into the projectmanager.
Modifications to the e2program itself
Canonical e2programs must maintain the following standards
Options are handled via EMArgumentParser, which is a subclass of Python's argparse module (version 2.7 and higher). For more information on argparse, see the python documentation. http://docs.python.org/dev/library/argparse.html
- Arguments are handled via EMArgumentParser.
- A line usage = """blah, blah, blah...""" must be present to give help info on the e2program
- A line progname = os.path.basename(sys.argv[0]) must be present
To illustrate what an e2program should look like, here is an example program:
1 #!/usr/bin/env python
2 #
3 # GPL licensing info goes here
4 #
5
6 from EMAN2 import *
7
8 def main():
9 progname = os.path.basename(sys.argv[0])
10 usage = """prog arg1, arg2, [options]
11 This is an example program """
12
13 parser = EMArgumentParser(usage=usage,version=EMANVERSION)
14 parser.add_argument("--option1",type=str,help="This is the first option",default="myvalue")
15 parser.add_argument("--option2",type=int,help="This is the second option",default=1)
16 parser.add_argument("--option3",type=float,help="This is the third option",default=3.14)
17 parser.add_argument("--option4",action="store_true",help="This is the fourth option",default=False)
18
19 (options, args) = parser.parse_args()
20
21 print "Arguments are", args
22 print "Options are", options
23
24 if __name__ == __main__:
25 main()
To enable this program to be integrated into the GUI the following item must be implemented:
- For each argument you must add the method: parser.add_pos_argument()
- To add dividing lines with help info into the GUI, add the method: parser.add_header()
- The option PPID must be added to enable cross platform PPID support
- To all parser 'add' methods the following keyword arguments must be added
- guitype="", this specifies what type of widget we want to use for this GUI
- row="", this specifies what row the widget should appear in
- col="", this specifies what column the widget should appear in
- rowspan="", this specifies how many rows the widget should span
- colspan="", this specifies how many columns the widget should span
- browser="", if the widget represents and option that refers to a file, this keyword argument lists a filebrowser to use.
To illustrate how to integrate the above example e2program int the GUI, the following example is given:
1 #!/usr/bin/env python
2 #
3 # GPL licensing info goes here
4 #
5
6 from EMAN2 import *
7
8 def main():
9 progname = os.path.basename(sys.argv[0])
10 usage = """prog arg1, arg2, [options]
11 This is an example program """
12
13 parser = EMArgumentParser(usage=usage,version=EMANVERSION)
14 #For the add_pos_Argument() and add_header() methods, you must add the name="" keyword argument. For the add_argument() method, the 'name' is taken from the --option argument
15 parser.add_pos_argument(name="argument1",help="First argument, this will be a file", default="", guitype='filetype', browser="EMBrowserWidget(withmodal=True,multiselect=True)", row=0, col=0,rowspan=1,colspan=2)
16 parser.add_header(name="header1", help="Use the header to display useful info in the GUI", title="### Actual info goes here ###", row=1, col=0,rowspan=1,colspan=2)
17 parser.add_argument("--option1",type=str,help="This is the first option",default="myvalue",guitype='strbox', row=2,col=0,rowspan=1,colspan=1)
18 parser.add_argument("--option2",type=int,help="This is the second option",default=1,guitype='intbox',row=2,col=1,rowspan=1,colspan=1)
19 parser.add_argument("--option3",type=float,help="This is the third option",default=3.14,guitype='floatbox',row=3,col=0,rowspan=1,colspan=1)
20 parser.add_argument("--option4",action="store_true",help="This is the fourth option",default=False,guitype='boolbox',row=3,col=1,rowspan=1,colspan=1)
21 # This is needed by all e2programs that run on the GUI
22 parser.add_argument("--ppid",type=int,help="Set the PID of the parent process, used for cross platform PPID",default=-1)
23 (options, args) = parser.parse_args()
24
25 print "Arguments are", args
26 print "Options are", options
27
28 if __name__ == __main__:
29 main()
Modification of the workflow JSON file
If your program is for single particle applications, modify the spr.json file found in /libEM/pmconfig. If your program is for tomographic applications, modify tomo.json file.
For example the spr.json will look something like this.
1 {
2 "ICON": "ctf",
3 "TABLE": "EMCTFcorrectedParticlesTable(withmodal=False,multiselect=True)",
4 "NAME": "CTF",
5 "CHILDREN": [
6 {
7 "ICON": "ctf",
8 "PROGRAM": "e2ctf.py",
9 "MODE": "autofit",
10 "WIKIPAGE": "http://blake.bcm.tmc.edu/emanwiki/EMAN2/Programs/e2ctf",
11 "NAME": "Automated Fitting -e2ctf",
12 "NOTELEVEL": "1",
13 "CHILDREN": []
14 },
15 {
16 "ICON": "ctf",
17 "PROGRAM": "e2ctf.py",
18 "MODE": "tuning",
19 "WIKIPAGE": "http://blake.bcm.tmc.edu/emanwiki/EMAN2/Programs/e2ctf",
20 "NAME": "Interactive Tuning -e2ctf",
21 "CHILDREN": []
22 },
23 {
24 "ICON": "ctf",
25 "PROGRAM": "e2ctf.py",
26 "MODE": "genoutp",
27 "WIKIPAGE": "http://blake.bcm.tmc.edu/emanwiki/EMAN2/Programs/e2ctf",
28 "NAME": "Generate Output - e2ctf",
29 "NOTELEVEL": "1",
30 "CHILDREN": []
31 },
32 {
33 "ICON": "ctf",
34 "PROGRAM": "e2ctf.py",
35 "MODE": "gensf",
36 "WIKIPAGE": "http://blake.bcm.tmc.edu/emanwiki/EMAN2/Programs/e2ctf",
37 "NAME": "Generate Structure Factor - e2ctf",
38 "NOTELEVEL": "1",
39 "CHILDREN": []
40 }
41 ]
42 },
Adding your new e2program is quite straight forward. To the JSON file just add(as a child in a CHILDREN list), in the appropriate location:
There are multiple other options, such as Wizard, Expert, etc. For a list and explanation see: EMAN2/Programs/e2projectmanager