Non-programming requirements for implementing CCP4i2 tasks

Supporting 'What next?'

After each job the GUI presents the user with a list of reasonable tasks to perform next and a web page with more discussion of the options. It is the responsibility of the task author to provide the information for these facilities. Note that if the user opts to follow from a sub-job in a pipeline then it is the parent pipeline that is queried to provide the 'what next' information.

There are two mechanisms to provide the information; the simplest is as a WHATNEXT attribute of either the wrapper class (CPluginScript) or gui class (CTaskWidget). So, for example, for buccaneer the WHATNEXT is set as a list of names of tasks..

class CTaskBuccaneer(CCP4TaskWidget.CTaskWidget):
  TASKNAME = 'buccaneer'
  ...
  WHATNEXT = ['refmac_simple']

The more flexible approach is to have a function whatNext() in either the wrapper module or the gui module (note it is a function and not a member of the class). This is passed four arguments:

jobId	The jobId of the job (or the jobId of the parent pipeline job if a sub-job is selected)
taskName	The taskname of the job (or of the sub-job if a sub-job was selected)
childJobNumber	The job number of the sub-job if a sub-job was selected
projectName	The project name

This function should return either a list of tasks that can be run next or a list of task name and text to appear on the GUI. For example for buccaneer_build_refine:

The WHATNEXT parameter or the return from whatNext() is normally expected to be a list of tasknames but the list item could be a list containing two items: the taskname and the filepath of a params file that provides default parameters to the next task. The params file path should be of the form

$CCP4I2/pipelines/bucref_mr/scripts/bucref_after_experimental.params.xml

i.e. the file is expected to be found somewhere in the CCP4I2 directory. The bucref_after_experimental.params.xml is used to set one input parameter in the Autobuild protein gui so that it expects input from experimental phasing.

In principle this mechanism could be used to pick up a project or task-specific file if the whatNext() function returns a list including a reference to a file in the current project directory of the form

$PROJECT/CCP4_JOBS/job_5/for_whatever_next_task.params.xml

This is interpreted in the context of the project viewer that understands $PROJECT to mean the current project directory. (Note this is not tested.) It is the responsibility of either the wrapper or the function to provide the params file in the project directory.

Each task should provide a web page with discussion of what to do next. This should be $CCP4I2/docs/whatnext/taskName.html.

Bibliographic References

Task documentation

Each task should have a page of documentation named $CCP4I2/docs/tasks/taskName/index.html and any images or other material for the page should be in the same directory. There is a template html file: ccp4i2/docs/tasks/resources/template.html. See the parrot documentation for example of required style.

In order to support installation of third party created pipelines with all resources in one directory the task documentation can as be in $CCP4I2/pipelines/taskName/docs/index.html.

Creating documentation images

There is a customised screen grab tool in the Developer tools sub-menu of the Utilities menu. The tool will grab either the task input frame or report as it appears in the Project viewer. You can resize the window and use the scroll bar to set up the required frame size. Beware with the task input you should resize the window to eliminate any space below the input widgets and for reports try to keep all screenshots the same width for a neater presentation in the web page.

For the first screenshot of a new task you will be prompted to select a directory to contain the screenshots and these will be automatically named:
directory/taskname_task_1.png or
directory/taskname_report_1.png etc.

To standardise documentation screenshot appearance please use the images of numbers in ccp4i2/docs/resources. One way to add these to the screenshot is using Inkscape: open the screenshot image then use File->Import to import each label svg file and then drag the label to correct place. Save by using the File->Export PNG image.