Project

General

Profile

Refine Refactor documentation » History » Version 31

Amber Herold, 09/14/2012 11:45 AM

1 11 Amber Herold
h1. Refinement Web User Interface documentation
2 2 Amber Herold
3 6 Amber Herold
h2. Steps to add a new refinement method to the pipeline
4
5 14 Amber Herold
# Add an entry to selectRefinementType.php for the new method.
6 16 Amber Herold
## Add a logo image to the myamiweb/processing/img file if it does not already exist.
7 14 Amber Herold
## In myamiweb/processing, open selectRefinementType.php and copy and existing methods code block.
8
## Replace the logo image file with the appropriate file name
9
## Replace the method key with an appropriate short name that indicates the type of method you are adding. This key will be used in other files to identify the type of refinement to launch. For example, in the following line of code *method=eman* should be replaced with an appropriate method name.<pre><h3><a href='selectStackForm.php?expId=$expId&method=eman'>EMAN1 projection-matching refinement</a></h3></pre>
10 15 Amber Herold
## Edit the description of the method to be informative to a novice user.
11 19 Amber Herold
&nbsp;
12 18 Amber Herold
# Add a reference paper related to the method. 
13
## Open myamiweb/processing/inc/publicationList.inc and copy a $PUBLICATIONS array entry code block.
14
## Modify the fields for the publication that should be referenced for the method you are adding.
15
## Modify the $PUBLICATIONS array key to match the method key that you defined in selectRefinementType.php.
16 19 Amber Herold
&nbsp;
17 20 Amber Herold
# Create a python class to run the preprefine step. 
18
## You must name the file prepRefineMethod.py where _Method_ is the same method key that you used in the previous step, except the first leter of the method is capitalized. This file should be located in myami/appion/bin and can be created by copying a similar existing methods prepRefine file.
19 25 Amber Herold
## Modify the setRefineMethod() function. The _self.refinemethod_ parameter should be set to 'methodrecon' where _method_ is the same as the method key defined in selectRefinementType.php. 
20
<pre>	def setRefineMethod(self):
21
	  self.refinemethod = 'xmipprecon'
22
</pre>
23 19 Amber Herold
&nbsp;
24 6 Amber Herold
# Create a new class which extends BasicRefineForm
25 22 Amber Herold
## You can copy an existing methods form, such as xmippRefineForm.inc in myamiweb/processing/inc/forms.
26
## Name the file methodRefineForm.inc where _method_ is the same as the method key used in the above steps.
27 31 Amber Herold
## There are several functions in this class to define AFTER you have created the RefineFormParameters class as described below.
28 22 Amber Herold
&nbsp;
29 6 Amber Herold
# Create a new class which extends RefineFormParameters. This is optional, but recommended.
30 30 Amber Herold
## Decide what information you need to collect from the user and add a form parameter for each item.
31 6 Amber Herold
### note that the parent constuctor is called first, passing any default values along. The RefineFormParameters base class defines parameters that are common to most refinement methods. You only need to add parameters that are not already defined in the base class.
32
### use the addParam(name, value, label) method to add parameters specific to your refine method to your form.
33
### if you find that the base class includes a parameter that your method does not need, you can remove the parameter from the form with the hideParam(name) method.
34
<pre>
35
class XmippParams extends RefineFormParameters
36
{
37
	function __construct( $id='', $label='', $outerMaskRadius='', $innerMaskRadius='', $outerAlignRadius='', 
38
							$innerAlignRadius='', $symmetry='', $numIters='', $angSampRate='', $percentDiscard='',  
39
							$filterEstimated='', $filterResolution='', $filterComputed='', $filterConstant='',
40
							$mask='', $maxAngularChange='', $maxChangeOffset='', $search5DShift='', $search5DStep='',
41
							$reconMethod='', $ARTLambda='', $doComputeResolution='', $fourierMaxFrequencyOfInterest='' ) 
42
	{
43
		parent::__construct($id, $label, $outerMaskRadius, $innerMaskRadius, $outerAlignRadius, 
44
							$innerAlignRadius, $symmetry, $numIters, $angSampRate, $percentDiscard,  
45
							$filterEstimated, $filterResolution, $filterComputed, $filterConstant );
46
									
47
		$this->addParam( "mask", $mask, "Mask filename" );
48
		$this->addParam( "maxAngularChange", $maxAngularChange, "Max. Angular change " );		
49
		$this->addParam( "maxChangeOffset", $maxChangeOffset, "Maximum change offset " );
50
		$this->addParam( "search5DShift", $search5DShift, "Search range for 5D translational search " );
51
		$this->addParam( "search5DStep", $search5DStep, "Step size for 5D translational search " );
52
		$this->addParam( "reconMethod", $reconMethod, "Reconstruction method " );
53
		$this->addParam( "ARTLambda", $ARTLambda, "Values of lambda for ART " );
54
		$this->addParam( "doComputeResolution", $doComputeResolution, "Compute resolution? " );
55
		$this->addParam( "fourierMaxFrequencyOfInterest", $fourierMaxFrequencyOfInterest, "Initial maximum frequency used by reconstruct fourier " );
56
		
57
		// disable any general params that do not apply to this method
58
		$this->hideParam("innerMaskRadius");		
59
	}
60
	
61
	function validate() 
62
	{
63
		$msg = parent::validate();
64
65
		if ( !empty($this->params["mask"]["value"]) && !empty($this->params["outerMaskRadius"]["value"]) )
66
			$msg .= "<b>Error:</b> You may not define both the outer mask raduis and a mask file.";
67
				
68
		return $msg;
69
	}
70 1 Amber Herold
}
71 7 Amber Herold
</pre>
72 30 Amber Herold
### define any restrictions that should be applied to the parameters.
73
## Override the advancedParamForm() function in your RefineForm class to add a user input field for each one of the methods parameters.
74
## Override the buildCommand() function in your RefineForm class  only if necessary. There is a default implementation available which adds all form parameters as --<name>=<value>.
75 23 Amber Herold
&nbsp;
76 24 Amber Herold
# Add your new form type to selectPreparedRecon.php
77 23 Amber Herold
## Add a require_once statement to the top of the file to include your new inc/forms/methodRefineForm.inc
78 1 Amber Herold
## Edit the createSelectedRefineForm() function to include your new method in the switch statement and create a new instance of your form.
79 26 Amber Herold
## The method key should correspond to the one used in prepRefineMethod.py setRefineMethod() function.
80 12 Amber Herold
<pre>
81
// based on the type of refinement the user has selected,
82
// create the proper form type here. If a new type is added to
83
// Appion, it's form class should be included in this file
84
// and it should be added to this function. No other modifications
85
// to this file should be necessary.
86
function createSelectedRefineForm( $method, $stacks='', $models='' )
87
{
88
	switch ( $method ) {
89
		case emanrecon:
90
			$selectedRefineForm = new EmanRefineForm( $method, $stacks, $models );
91
			break;
92 1 Amber Herold
		case frealignrecon:
93
			$selectedRefineForm = new FrealignRefineForm( $method, $stacks, $models );
94
			break;
95
		case xmipprecon:
96
			$selectedRefineForm = new XmippRefineForm( $method, $stacks, $models );
97
			break;
98
		case xmippml3drecon:
99
			$selectedRefineForm = new XmippML3DRefineForm( $method, $stacks, $models );
100
			break;
101
		default:
102
			Throw new Exception("Error: Not Implemented - There is no RefineForm class avaialable for method: $method"); 
103
	}		
104
	
105
	return $selectedRefineForm;
106
}
107 12 Amber Herold
</pre>
108 27 Amber Herold
&nbsp;
109 28 Amber Herold
# Edit refineJobsSingleModel.inc or RefineJobsMultiModel.inc setDBValues() function to include the method keys and job types used for the new method.
110 21 Amber Herold
111
h2. Class Diagram
112
113
The following class diagram shows the BasicForm class with it's extended classes as well as the FormParameter class and it's extended classes.
114
It also shows associations among the classes.
115
Notice that the specific refine parameter classes use polymorphism to override the validate() function. This allows the extended classes to provide more complex validations than a typical form requires.
116
Other forms, such as RunParameters and stack prep, just use the base FormParameters class that their parent, BasicForm, uses.
117
118
!refineClassDiagram.png!
119
120
h2. Sequence Diagram
121
122
The following sequence diagram shows how the Form and Parameter classes work together to display a form, validate the user input, and create a command string.
123
124
!refine_sequence_diagram.png!