2 Introduction
This is the combined SRS and test document for fit_srtm.
Software is used to fit with standard non-linear methods the
simplified reference tissue (region) compartment model (1, 2) for
regional PET data to estimate regional binding potential (BPND).
2.1 References
- Lammertsma AA, Hume SP. Simplified reference tissue model for PET receptor studies. Neuroimage 1996;4:153-158.
- Oikonen V, Sederholm K. TPCMOD0002: Model equations for reference tissue compartmental models. http://www.turkupetcentre.net/reports/tpcmod0002.pdf
3 Software requirements
3.1 Features
User provides the software with
- filename of regional PET data from a dynamic (multi-frame) PET scan in DFT format
- filename of reference region data or name of reference region included in previous file
- fit time (in minutes). A large value can be given as the stop time to imply that all PET data after the start time should be used in the line fitting.
- filename for the results.
Fitted parameter values for each region are written in specified RES data file. The results are written in the following order with these titles: R1, k2, BP (optionally DVR instead of BP), WSS, AIC. Result file also contains the names of data files, and the time range, that were used in the model fit. Additional information may be included.
3.1.1 Program can run silently or verbosely
With option --silent the software does not print on screen any
other comments than error and warning messages.
With option --verbose the software prints lots of information about what it is doing.
3.1.2 Constraints for model parameters
With option -lim=<filename> any or all of the model parameters can be constrained to stay within certain limits. The file has a certain format, containing one or more of the following lines:
R1_lower := <value>
R1_upper := <value>
k2_lower := <value>
k2_upper := <value>
BP_lower := <value>
BP_upper := <value>
If a new file name is specified (file that does not exist), this file is created with default values. To prevent inadvertently creating this file instead of using one, the file is created only if no PET data file is given. Otherwise, if file does not exist or is not given, an error is printed and program exits.
The default constraints are:
R1: 0.001 - 10
k2: 0.000001 - 10.0
BP: 0 - 60 (note below)
- ratio of AUCs of ROI and reference region is calculated
- if ratio is less than 1, it is set to 1
- upper limit is set to 5x the ratio
3.1.3 Calculate standard deviations for model parameters
With option -SD[=<Y|n>] the standard deviations for model parameters are or are not estimated and saved in the results files. By default these values are not estimated.
3.1.4 Calculate confidence limits for model parameters
With option -CL[=<Y|n>] the 95% confidence limits for model parameters are or are not estimated and saved in the results files. By default these values are not estimated.
3.1.5 Fitted regional TACs can be saved
With option -fit=<filename> the fitted regional TACs are written into specified file in DFT format. This enables creating the plots in other software. File must contain the regional data in the same order as in original data file, and in place of the reference region the original reference tissue curve, because no fitted curve for that exists.
3.1.6 Fitted regional TACs can be plotted in SVG format
With option -svg=<filename> the fitted regional TACs are plotted with lines and original data with symbols in specified file in SVG format.
3.1.7 Distribution volume ratio is reported instead of BP
With option -dvr the distribution volume ratio (DVR=BP+1) is saved in result files instead of BP.3.2 Operating environment
Software will be used mainly in PC/Windows environment, but it may also be used in Linux/Unix.
3.3 Design and implementation constraints
Software uses C library functions.
3.4 External interface requirements
3.4.1 User interfaces
Software has a command line user interface. It may be used by scripts or GUI software, therefore it must get all required information from command line arguments.
3.4.2 Software interfaces
Because this software may be called from a script or GUI software, it returns code 0 when successful, and in other cases an error code is returned and error message is printed in stderr.
This software reads files in DFT format and writes the function parameters in RES format (unless HTML table format is set with .html extension). Result format must be in compliance with the format as understood by program rescoll, which may be used to collect the results for further statistical analysis.Plots are saved in SVG format.
3.5 User documentation
Software will print a short user information text with option -h or --help, and exit.
Software will print build information text with option --build, and exit.
4 Software implementation
Software will be programmed using ANSI C. It will use the most recent C libraries for file i/o.
5 Software test plan
5.1 Test cases
Software is considered to have passed a test when the test result is the same as the expected result.| Test case | ID | Expected result |
| Handling of command-line arguments | ||
| No command line options or arguments | 1.1.1 | User help text is printed on screen. Program exits with error code. |
| Unknown option |
1.1.2 | Error |
| An extra command-line argument is given. | 1.1.3 | Error |
| Any of the obligatory command-line arguments is missing | 1.1.4 | Error |
| Correct command-line arguments are specified | 1.1.5 | Test output contains appropriate filenames and default values |
| Option -h and --help | 1.2.1 | User help text is printed on screen. Program exits. |
| Option --build | 1.2.2 | Program version and compilation information is printed
on screen. Program exits. |
| Option --silent |
1.3.1 |
Test output contains correct switch value |
| Option --verbose | 1.3.2 | Test output contains correct switch value |
| Options -SD, -SD=y and -SD=n | 1.4.1 | Test output contains doSD=1, doSD=1 and doSD=0. |
| Options -CL, -CL=y and -CL=n | 1.4.2 | Test output contains doCL=1, doCL=1 and doCL=0. |
| Option -lim=<filename> | 1.5.1 | Test output contains correct filename. |
| Option -fit=<filename> | 1.6.1 | Test output contains correct filename. |
| Option -svg=<filename> | 1.7.1 | Test output contains correct filename. |
| Option -dvr | 1.8.1 | Test output contains doDVR=1 |
| General function and validity of results | ||
| Test data is simulated with reasonable parameter values using 1-tissue compartment model. Results are calculated with valid end time, with the same calibration units in data files. |
2.1.1 | Model parameter values and applied calculation time are written correctly in the output file. Estimated parameter values are similar to the ones calculated from model rate constants used to simulate the test data. |
| Test data is simulated with non-physiological parameter values. | 2.1.2 | Program executes normally and results are written correctly, although parameter values do not need to represent "true" values |
| Test data is simulated using realistic [C-11]raclopride parameter values for 2-tissue compartment model (1-tissue compartment model for cerebellum), normal framing and study length | 2.2.1 | Simulated data does not strictly comply with the model assumptions, therefore estimated R1 and k2 may not be correct. Estimated BP values are close to the ones calculated from model rate constants used to simulate the test data. |
| PET data files | ||
| Reference curve is given in a separate file | 3.1.1 | Program reads the reference curve(s) correctly. If more than one exist, then uses the first one as model reference, and warns the user about this. |
| Reference curve is specified as a region name in the data file | 3.1.2 | Program identifies correct reference region if it exists, and returns an error if it can not be found. If more than one matches, then selects the best match and tells user about this. |
| Reference curve is specified as the number of region in the data file | 3.1.3 | Program identifies correct reference region if it exists, and returns an error if it can not be found. |
| Data file does not exist | 3.2.1 | Error |
| Data file is in wrong format | 3.3.1 | Error |
| DFT formats are accepted. Specifically, regional data without headers must be supported, and regional data with frame middle times or frame start and end times must be supported | 3.3.2 | Results are calculated without errors. |
| Frame times | ||
| Time gap between first frame start time and injection time | 3.4.1 | If gap is substantial (>5 s), a warning is displayed, and if larger (>45 s), error with appropriate message. |
| Overlap or gaps between frames | 3.4.2 | Gaps are filled automatically and small overlap is corrected. Substantial overlap leads to an error with appropriate message. |
| Reference region file contains middle frame times while tissue file contains
frame start and end times. Program should check whether frame middle times are similar, and if they match, then frame start and end times are applied to reference curve too. |
3.4.3 | Results are equal to calculation with reference file that contains frame start
and end times. Early frame(s) can be very long without much affecting the results, if this works. |
| Program takes into account the frame lengths in the numerical calculations | 3.4.4 | Results do not change substantially with fewer and longer frames. |
| Input data: units | ||
| Reference and PET data are in different calibration units | 3.5.1 | At least units Bq/ml and kBq/ml are correctly converted, when necessary. |
| Reference or tissue data time units are in seconds | 3.5.2 | When unit is correctly defined in the file, program converts the sample times to minutes internally, and results are the same as if times were originally in minutes. |
| Fit duration | ||
| Zero entered as fit
duration |
4.1.1 |
Error |
| 999 or any longer fit time than is available in data entered as fit duration |
4.1.2 |
Program correctly finds the last measured tissue sample time and uses it as the
stop time. It is shown in result file. |
| A shorter time than
data length is given |
4.2.1 |
The end of closest
PET frame is used and printed in result file. |
| Data included in fitting contains less than 4 samples (frames); note that frames after fit end time are not counted | 4.3.1 | Error with appropriate message. |
| Output files | ||
| Program can write optional output files | 5.1.1 | Optional output files are created. |
| Program can overwrite and backup existing result and output files | 5.2.1 | New result and other output files are created and backup files are created from the old files. |
| Result file is compatible with rescoll | 5.3.1 | Result files that are produced can be read with rescoll without errors. |
| Parameter constraints | ||
| constraints not set by user | 6.1.1 | Default constraints are printed in test mode |
| constraints are given in file with option -lim; file does not exist, but other arguments are given to program | 6.2.1 | Error about non-existing file, exit |
| default constraints are written to a file with option -lim; file does not exist, and program is called without any other arguments | 6.2.2 | Default constraints are written in specified file |
| default constraints are tried to be written into a file with option -lim. Program is called without any other arguments, but file exists. | 6.2.3 | Error |
| all possible constraints are given in file with option -lim; constraints are different than the default constraints | 6.2.4 | User-defined constraints are printed in test mode |
| one constraint is given in file with option -lim; constraint is different than the default constraint | 6.2.5 | User-defined constraint is printed in test mode as set, others as default values |
| constraint file in wrong format | 6.2.6 | Error |
| DVR calculation | ||
| Option -dvr | 7.1.1 | Program operates as without option -dvr, but results contain column named as DVR instead of BP, and DVR values are the same as if BPhad been converted to DVR outside of the program. |
| Weights | ||
| File does not contain weights | 8.1.1 | Weights are set to 1 for the fit. These weights are checked in test mode output |
| File contains weights | 8.2.1 | Weights are applied and printed in test mode |
| Bootstrap method | ||
| Neither SD or CL calculation is requested. | 9.1.1 | Neither SD or CL95% is reported in results. |
| SD calculation is requested | 9.2.1 | SD is estimated and reported in results |
| CL calculation is requested | 9.3.1 | CL95% is estimated and reported in results |
5.2 Properties that are not tested
Parts that are implemented using common library functions are not thoroughly tested here.Correct handling of missing data values (NAs) is not tested, since these are not present in normal data.
WSS, SD, CL and AIC values are not tested.
Correctness of fitted TACs or SVG files is not tested, because this does not affect the results, and possible failure will be noticed when used.