mris_pmake
(Using existing options file)
mris_pmake [--optionsFile=<fileName>] [--dir=<workingDir>] [--listen | --listenOnPort <port>]
(No options file; will create)
mris_pmake --subject <subj> --hemi <hemi> --surface0 <surface0File> --surface1 <surface1File> --curv0 <curv0File> --curv1 <curv1File> --useAbsCurvs --mpmProg <mpmProgName> --mpmArgs <argsForMpmProg>
'mris_pmake' calculates paths and related costs on FreeSurfer surfaces based on an edge cost and Dijkstra's algorithm.
In its simplest usage, a <start> and <end> vertex index on the surface is specified (typically in the <optionsFile>), and the program calculates the shortest path connected the points as well as the path cost. \"Shortest\" path in this case only has meaning in the context of the cost function that is being evaluated (see COST FUNCTION for details).
More complex use is enabled through embedded 'mpmProgs' that perform various functions based around Dijkstra calculations. Such mpmProgs include 'autodijk' which calculates the cost in moving from a reference to all other vertices in the mesh, and 'patchMake' which generates label patches about a set of seed vertices.
An interactive mode of operation is also available through a companion Python script called 'dsh' that allows asychronous setting of <start> and <end> vertices, changes in the cost function weights, etc. This 'dsh' script is probably the best and easiest way to run 'mris_pmake'.
******************************************
COST FUNCTION
The cost function is currently a multi-dimensional weight vector of following form:
p = w d + w c + w h + w dc + w dh + w ch + w dch + w (dir)
d c h dc dh ch dch dir
where
w_d : weighting factor for distance, d
w_c : weighting factor for curvature, c
w_h : weighting factor for sulcal height, h
w_dc : weighting factor for product of distance and curve
w_dh : weighting factor for product of distance and height
w_ch : weighting factor for product of curve and height
w_dch : weighting factor for product of distance, curve, and height
w_dir : weighting factor for direction
The curvature, c, is specified in the <optionsFile> with the 'curvatureFile' option, and the height, h, is specified in the <optionsFile> with the 'sulcalHeightFile'. These names are somewhat historical, and in theory any valid FreeSurfer overlay can be used for 'c' and 'h'.
An additional non-linear penalty is also available, and if 'b_transitionPenalties' is TRUE, will be applied to the cost function, by an index-to-index multiplication of the cost vector. It currently triggered if the original 'c' value undergoes a zero-crossing along a trajectory path.
| Argument | Explanation |
|---|---|
| --subject <subj> | Set the subject to <subj>. This is assumed relative to an env variable SUBJECTS_DIR. |
| --hemi <hemi> | The hemisphere to process. |
| Argument | Explanation |
|---|---|
| --optionsFile=<fileName> | The main configuration file that specifies the startup run-time behaviour of the program, including cost function variables, start and terminal vertex indices, cost function, input files, output files, etc. If the <fileName> contains a directory prefix, this directory will be assumed to be the working directory. Default is 'options.txt'. |
| --dir=<workingDir> | The working directory. This will override a working directory that might have been specified in the <fileName> prefix. Defaults is current directory. |
| --listen | Start in LISTEN mode, i.e. initialize the program and read the default 'options.txt' file parsing surfaces and curvatures, but do not actually calculate a path. Instead, once ready, start listening on the embedded server socket for instructions. Send a 'RUN' string in a UDP packet to the port specified in <optionsFile> to perform the path search. |
| --listenOnPort <port> | Similar to above, but do not interpret the <optionsFile> environment. Essentially create the server port on <port> and do nothing else. In this mode, the program requires an explicit 'HUP' text string to be sent as a UDP packet to <port> to read the default enviroment, or an options file can be spec'd by sending a UDP string 'OPT <optionsFile>'. |
| Argument | Explanation |
|---|---|
| --surface0 <surface0File> | The main mesh surface to read. This is relative to the 'surf' dir of <subj> and does not include a hemisphere prefix, e.g. 'smoothwm'. Defaults to 'inflated'. |
| --surface1 <surface1File> | The aux mesh surface to read. This is relative to the 'surf' dir of <subj> and does not include a hemisphere prefix, e.g. 'smoothwm'. Defaults to 'smoothwm'. |
| --curve0 <curv0File> | The main curvature function maps. This is relative to the 'surf' dir of <subj> and does not include a hemisphere prefix, e.g. 'smoothwm.H.crv'. This curvature map is used as the 'c' parameter in the internal cost function. Defaults to 'smoothwm.H.crv. |
| --curve1 <curv1File> | The aux curvature function maps. This is relative to the 'surf' dir of <subj> and does not include a hemisphere prefix, e.g. 'smoothwm.H.crv'. This curvature map is used as the 'h' parameter in the internal cost function. Defaults to 'sulc'. |
| --useAbsCurvs | If specified, use an fabs(...) on each curvature map. Otherwise, the curvature map field is offset so that its minimum value (most negative) is zero. |
| --mpmProg <mpmProgName> | The mpmProg to run. |
| --mpmArgs <argsForMpmProg> | A semi-colon delimited list of arguments for the specified <mpmProg>. This list is of course dependent on the particular mpmProg being executed. |
The best mechanism to run a 'mris_pmake' process is from a companion 'shell' called 'dsh'. The use of 'dsh' is beyond the scope of this help, but in the simplest case (and assuming a valid <optionsFile>), simply run 'dsh' and wait for it to provide a prompt. At the prompt type 'RUN' and wait for the next prompt, at which simply type 'quit'.
Alternatively, 'mris_pmake' can be evoked in a more conventional FreeSurfer manner, specifying subject and hemisphere by using appropriate command line args. This is most useful when non-interactive behaviour is desired and typically implies running an embedded mpmProg.
'mris_pmake' communicates on three different channels. Most operational data is sent to a channel called <userMessages> (in the <optionsFile>). System-type messages are sent to a channel called <sysMessages> and results are sent to <resultMessages>. If these are defined as files, then the channel simply logs to the file. If these are specifed as 'localhost:XXXX' then these channels are created as UDP sockets to which 'mris_pmake' transmits data.
HOW DO I RUN 'AUTODIJK'?
If you have an existing options file and 'dsh':
1. Start 'dsh' by typing 'dsh' at the Linux prompt. Make sure your current directory contains a valid 'options.txt' file.
2. When 'dsh' starts, it will parse the options file and control 'mris_pmake' to read relevant surface and curvature files.
3. Once done, 'dsh' will present a prompt. Type: >ENV mpmProg set 1
This will create an 'autodijk' mpmProg.
3a. Optionally set some parameters for the mpmProg: >MPMPROG polarVertex set 100
4. To run, type: >RUNPROG
This will run the created autodjik.
If you do not have an options file:
1. From the Linux prompt, make sure your SUBJECTS_DIR is properly set.
2. For a subject called '11' and using the rh.smoothwm.K1.crv file as main curvature function, type: >mris_pmake --subject 11 --hemi rh --curv0 smoothwm.K1.crv --mpmProg autodijk
Report bugs to <freesurfer@nmr.mgh.harvard.edu>