Batch mode analysis of PET data
What is a script / batch file?
Batch file or shell script is a collection of commands in a text file. In their simplest form, they contain the commands just as you would have typed them on the command line. This text file then can be used as a program: when you double-click the text file icon in a file browser, or enter its name to the command prompt window, it executes the commands that it contains, line by line, as if you had given the commands by yourself.
Why to do analysis in batch mode?
Then why should one write the commands first into a text file, and then run it, instead of writing the commands directly to the command prompt?
1. For documentation and for easy correction of mistakes
When you save the batch file with the original PET data, everyone can later see from it what you actually have done, and, if necessary, make a correction to it, and run everything again with no trouble at all.
Sometimes you will notice an error in a data file only when you are inspecting the analysis results. If the data file can be repaired, it is easy to do the analysis again with the script / batch file.
2. To use text processing tools
You can create the script / batch file in any text editor or word processing program you like, as long as you save the file in ASCII (text only) format. You can use copy-paste, find-replace, and whatever functions you like to edit the file, instead of writing and editing the same commands again and again to the command-prompt window.
3. To have time for doing something else
You may need to have to analyze a whole bunch of PET studies, and the analysis software takes a few moments to execute, not so long that you had time to concentrate on doing something else, but long enough to get bored. The analyses go with a swing, if you write all the commands into a text file, start it, and go for a cup of coffee. You could also start it later, so that the batch mode analysis executes while you attend to a meeting, or during the night.
How to make the script / batch files?
Web tutorials for writing script and batch files are listed in references.
It is a good practice to test inside the scripts that each executed command was successful, and if not, then stop the execution of the script promptly with error message. Examples below will show how to do this in practice.
Batch files (*.bat) in Windows/MS-DOS and scripts in Unix/Linux look similar, and if they are kept very simple, can even be run on bothplatforms as such. There are also some differences between different versions of Windows and different Unix/Linux command shells.
Creating batch file in Windows
Use Notepad or similar program to create a text-only file. If you use MS Word or other word processor, make sure to save the file in ASCII format, without any formatting (MS-DOS text). Save with filename extension .bat, and run it like any other program from command line, without giving the filename extension.
Example #1 (MS Windows, but would work also in Unix/Linux)
This batch file converts old regional data format to DFT format from specified studies, then runs logan analysis for each of them, and then collects the results and calculates the mean values and standard deviations into a table in HTML format:
nci2dft uf0498.roi.kbq uf0498.dft nci2dft uf0499.roi.kbq uf0499.dft nci2dft uf0504.roi.kbq uf0504.dft nci2dft uf0505.roi.kbq uf0505.dft logan uf0498.dft cer 15 999 uf0498logan.res logan uf0499.dft cer 15 999 uf0499logan.res logan uf0504.dft cer 15 999 uf0504logan.res logan uf0505.dft cer 15 999 uf0505logan.res rescoll loganmeans.html *logan.res
Example #2 (Windows 2000/XP)
This batch file does exactly the same things as the previous example, but uses the for-loop:
for %%f in (uf0498 uf0499 uf0504 uf0505) do nci2dft %%f.roi.kbq %%f.dft for %%f in (uf0498 uf0499 uf0504 uf0505) do logan %%f.dft cer 15 999 %%flogan.res rescoll loganmeans.html *logan.res
Example #3 (Windows 2000/XP)
If the analysis commands are exactly the same for each PET study, the only difference being the study number, you could define the study number as a variable, and then just copy-paste the analysis command part:
set studynr=ua2826 imglhk3 -W %studynr%ap_pure.delay.kbq %studynr%dy1.img %studynr%k3.img ecat2tif -rb -s %studynr%k3.img %studynr%k3_plane20.tif 20 1 img2dft %studynr%k3.img ..\%studynr%*.roi %studynr%k3.dft dftavg -rm %studynr%k3.dft dftavg -h %studynr%k3.dft dftlist %studynr%k3.dft set studynr=ua2831 imglhk3 -W %studynr%ap_pure.delay.kbq %studynr%dy1.img %studynr%k3.img ecat2tif -rb -s %studynr%k3.img %studynr%k3_plane20.tif 20 1 img2dft %studynr%k3.img ..\%studynr%*.roi %studynr%k3.dft dftavg -rm %studynr%k3.dft dftavg -h %studynr%k3.dft dftlist %studynr%k3.dft set studynr=ua2831 ...
Be cautious about space characters (also trailing spaces) with
set.
Example #4 (Windows 2000/XP)
The previous example could also be written with two batch files, with runall.bat calling runone.bat:
runall.bat:call runone ua2826 if not %errorlevel%==0 goto FAILED call runone ua2831 if not %errorlevel%==0 goto FAILED call runone ua2831 if not %errorlevel%==0 goto FAILED ... :PASSED @echo ========================================================================== @echo Batch file executed successfully. @echo ========================================================================== goto END :FAILED @echo. @echo failed! @echo. :ENDrunone.bat:
imglhk3 -W %1ap_pure.delay.kbq %1dy1.img %1k3.img if not %errorlevel%==0 exit /b 1 ecat2tif -rb -s %1k3.img %1k3_plane20.tif 20 1 img2dft %1k3.img ..\%1*.roi %1k3.dft if not %errorlevel%==0 exit /b 1 dftavg -rm %1k3.dft if not %errorlevel%==0 exit /b 1 dftavg -h %1k3.dft if not %errorlevel%==0 exit /b 1 dftlist %1k3.dft
Notice that in runone.bat it is verified after each command that
the program return code is 0 (successful), and if it is not, then
runone.bat stops execution immediately, and returns error also to the
calling batch file, runall.bat, which then also stops, displaying text
failed!.
Creating script on Unix or Linux
Use textedit, nedit, or any other ASCII text editor. There are no requirements for the filename or its extension, but .sh (shell) extension is commonly used. After you have saved the file, give everyone the permission to execute it for example with command:
chmod 777 your_script_name
If you write the scripts in Windows, convert the script file to Unix/Linux format with dos2unix before trying to run it. Although the file may look fine without conversion, you will get strange errors if you don't do this.
Example #1 (Unix, Linux, and even Windows)
This script converts old regional data format to DFT format from specified studies, then runs logan analysis for each of them, and then collects the results and calculates the mean values and standard deviations into a table in HTML format:
nci2dft uf0498.roi.kbq uf0498.dft nci2dft uf0499.roi.kbq uf0499.dft nci2dft uf0504.roi.kbq uf0504.dft nci2dft uf0505.roi.kbq uf0505.dft logan uf0498.dft cer 15 999 uf0498logan.res logan uf0499.dft cer 15 999 uf0499logan.res logan uf0504.dft cer 15 999 uf0504logan.res logan uf0505.dft cer 15 999 uf0505logan.res rescoll loganmeans.html *logan.res
Example #2 (Unix, Linux)
If the analysis commands are exactly the same for each PET study, the only difference being the study number, you could define the study number as a variable, and then just copy-paste the analysis command part:
#! /bin/shstudynr=ua2826 imglhk3 -W $studynr'ap_pure.delay.kbq' $studynr'dy1.img' $studynr'k3.img' if [ $? -ne 0 ] ; then echo Failed! ; exit 1 ; fi ecat2tif $studynr'k3.img' $studynr'k3_plane20.tif' 20 1 if [ $? -ne 0 ] ; then echo Failed! ; exit 1 ; fi img2dft $studynr'k3.img' '../'$studynr'*.roi' $studynr'k3.dft' if [ $? -ne 0 ] ; then echo Failed! ; exit 1 ; fi dftavg -rm $studynr'k3.dft' if [ $? -ne 0 ] ; then echo Failed! ; exit 1 ; fi dftavg -h $studynr'k3.dft' if [ $? -ne 0 ] ; then echo Failed! ; exit 1 ; fi dftlist $studynr'k3.dft' studynr=ua2831 imglhk3 -W $studynr'ap_pure.delay.kbq' $studynr'dy1.img' $studynr'k3.img' if [ $? -ne 0 ] ; then echo Failed! ; exit 1 ; fi ecat2tif $studynr'k3.img' $studynr'k3_plane20.tif' 20 1 if [ $? -ne 0 ] ; then echo Failed! ; exit 1 ; fi img2dft $studynr'k3.img' '../'$studynr'*.roi' $studynr'k3.dft' if [ $? -ne 0 ] ; then echo Failed! ; exit 1 ; fi dftavg -rm $studynr'k3.dft' if [ $? -ne 0 ] ; then echo Failed! ; exit 1 ; fi dftavg -h $studynr'k3.dft' if [ $? -ne 0 ] ; then echo Failed! ; exit 1 ; fi dftlist $studynr'k3.dft' studynr=ua2831 ...
Notice that the script verifies after each command that the program
return code was 0 (successful), and stops the execution if it was not,
displaying Failed! on the screen.
Automatic making of batch files for PET studies
If data filenames start with valid PET study number (1-5 lowercase letters followed by 1-5 digits, for example 'ua2831'), the script / batch file can be made using domany.
For example, the following set of commands:
patlak pet\ut1234.dat plasma\ut1234ap.dat 10 60 ut1234.res patlak pet\ut1238.dat plasma\ut1238ap.dat 10 60 ut1238.res patlak pet\ut1239.dat plasma\ut1239ap.dat 10 60 ut1239.res patlak pet\ut1241.dat plasma\ut1241ap.dat 10 60 ut1241.res patlak pet\ut1242.dat plasma\ut1242ap.dat 10 60 ut1242.res patlak pet\ut1245.dat plasma\ut1245ap.dat 10 60 ut1245.res patlak pet\ut1246.dat plasma\ut1246ap.dat 10 60 ut1246.res patlak pet\ut1248.dat plasma\ut1248ap.dat 10 60 ut1248.res patlak pet\ut1248.dat plasma\ut1248ap.dat 10 60 ut1248.res
could be created and and written in batch file runpatlak.bat by entering the following command:
domany -o=runpatlak.bat "patlak pet\ut????.dat plasma\ut????ap.dat 10 60 STUDYNR.res"
assuming that these data files exist in the specified subdirectories. In Windows command prompt window the batch file can then be executed with command:
runpatlak
Using batch commands from command line
In Windows command shell
Run one command to all your datafiles
You can use 'for' loop to execute a certain command to all of your files, for example to convert all of your ECAT 6.3 format images in your current working directory to ECAT 7 image files, give this command:
for %g in (*.img) do e63to7 %g
This can be done also in batch files, but there you must use '%%' instead of '%'.
