Editing Scanco User Instructions (section)

===Your First IPL Script===
*'''Prerequisite''': you are familiar with navigating the VMS system. 
*'''"$" or "ipl>"''': the DCL and IPL prompts respectively, and you should only type the text after the prompt. 
*If you FTP the file to the OpenVMS system, ensure you use "binary" to transfer the file.
You can run these commands on almost any greyscale AIM file. Example file here: MJ7101.AIM 


[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]

====Interactive IPL====
*Command <code>$ ipl</code> starts IPL interactively, that is you see the result of each command as you run it. 
*While it is useful for testing, running large scripts interactively may interfere with others using the computer. 
<br>
*'''Reading an AIM file'''
:Before you can run any analysis on the AIM file, you need to read it into IPL and assign it a file handle. This is done using the command <pre>ipl> read in MJ7101.AIM</pre>
:A fraction of a second later, the file should have been read into memory and assigned the internal name "in". If we want to do some basic density calculations on it, we can use the command<pre>ipl> vox_ in 0</pre>
:*IPL, much like DCL, will automatically complete the command if it is given enough characters. 
:The "vox_" was expanded to the command "vox_scanco_param" (calculates voxel-counting parameters) and told you that the mean density of the cube is 114 mg HA/cm3 and a standard deviation of 283 mg HA/cm3. 
:The argument "in" is the internal name of the image.
:The argument "0" is the region. The command vox_scanco_param supports several numbered regions if, for example, you wanted to separately compute the density for the trabecular region and the cortical region.
<br>
*'''Segmenting an AIM file'''
:Some parameters, like average density, are computed from the [[Scanco_User_Instructions#Grayscale_Images|'''Greyscale Image''']]. Other parameters, like the trabecular number, require an image that has been segmented to [[Scanco_User_Instructions#Binary_Images|'''Binary Images''']], that is converted into "bone" and "not bone". 
:There are many ways to separate bone from non-bone, and parameters that work well for one dataset will not generally work for images of different samples, or acquired at different resolutions.
:One of the simplest segmentation methods "seg_gauss" is to apply Gaussian smoothing to the sample, to eliminate the noise present in the image, followed by a semi-arbitrary threshold that preserves the trabecular structure. 
<pre>
ipl> seg_gauss in seg

  -sigma                     [1.000000] >  
  -support                   [2] > 
  -lower_in_perm_aut_al      [300.000000] > 
  -upper_in_perm_aut_al      [100000.000000] > 
  -value_in_range            [127] > 
  -unit                      [0] > 2 
</pre>
:seg_gauss expects 8 parameters, and we have provided only 2. It will now prompt us for the remaining 6 one-by-one. 
:Leave everything at the defaults (simply hit "Enter") except the unit, which we will change to "2". 
:For young human trabecular bone from the distal tibia scanned at 20 um in the uCT 35, but then downscaled to 80 um, the above parameters give a reasonable representation of the trabecular structure. With other bones at other resolution, you may need to change the sigma, the support, and the lower threshold. 
:The unit of "2" simply means that we are working in units of mg HA/cm3.
:Now that the cube is segmented, we can run the same voxel-counting command as above and obtain more information. <pre>ipl> vox_ seg 0</pre>
:We now know that our combination of smoothing and threshold resulted in an object volume of 103 mm3 (i.e. volume of bone) and a bone volume ratio of 22.88%.
<br>
*'''Writing out a file'''
:we can write the segmented file out for future use. Accept the defaults for the remaining arguments. <pre>ipl> write seg MJ7101_SEG.AIM</pre>
:Now you can quit IPL and verify that the segmented file has been written out. <pre>ipl> quit</pre>


[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]

====Batch IPL====
*Command <code>$ ipl_batch</code> starts IPL inside a script that would be submitted to a queue.
While the following code is likely to work, it is not very readable:
<pre>
$ IPL_BATCH
read in MJ7101.AIM
vox_ in
seg_gauss in seg 1 2 300 100000 127 2
vox_ seg
write seg MJ7101_SEG.AIM
..
$ EXIT
</pre>
*Instead, it is recommended that you copy and paste the "pretty" output of the command after you have run it once interactively.
*Values that are likely to change should be variables, defined at the top of the script. 
*To substitute a variable from DCL into IPL, use a double-quote character before the variable name, as shown in the example below. 
Copy and paste the below into a text editor.
<pre>
$ modelname  :== MJ7101.AIM
$ threshold   == 300
$ outputfile :== MJ7101_SEG.AIM
$
$ IPL_BATCH

/read
  -name                      in
  -filename                  "modelname

/vox_scanco_param
  -input                     in

/seg_gauss
  -input                     in
  -output                    seg
  -sigma                     1.000000
  -support                   2
  -lower_in_perm_aut_al      "threshold
  -value_in_range            127
  -unit                      2

/vox_scanco_param
  -input                     seg

/write
  -name                      seg
  -filename                  "outputfile 

..
$ EXIT
</pre>
Now, it is clear what the full names of the commands are, and what the parameters mean. 
*If a parameter isn't important and can be left at the default (for example the region number during vox_scanco_param), you can leave it out of the file. 
Save the file as MYSCRIPT.COM and run it using <code>@MYSCRIPT.COM</code>.

<br>
*'''Submitting to the queue'''
:As mentioned in the introduction, running IPL interactively on larger models negatively impacts other users of the system. Copying the commands to a file and running it from the command line has the same effect. 
:*The correct way to run larger scripts is to submit the job to the queue. <pre>SUBMIT/QUE=SYS$FAST MYSCRIPT.COM</pre>


[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]