KrisThielemans
commented
4 years ago sorry for the delay. These programmes are preliminary, need work, and hence are not documented. Help would be very much appreciated!
algorithm
Briefly: this is an implementation of https://ieeexplore.ieee.org/abstract/document/1009231. That proceedings talks about 2 update schemes, but only one of them (inter-update) is convergent (which we've proven, but never published). http://dx.doi.org/10.1109/nssmic.2002.1239610 and 10.1109/nssmic.2008.4774352 contain some useful info as well.
The method does a Max Likelihood optimisation of efficiencies (ε), geometric factors (g) and block-timing factors (B), see the proceedings. The "model" (A) is whatever STIR projector * attenuation + scatter you'd normally use. Sadly, the current algorithm/implementation doesn't handle a random background. There are subtleties on how you should handle scatter, but anyone doing normalisation will tell you should use data with as little scatter as possible...
I strongly recommend leaving the block-timing (B) off. In the implementation we used, there's too much freedom. It should only be necessary for not-very-well-set-up scanners anyway.
The implementation is limited to span=1, no view-mashing.
Also, the geometric norm factors code can currently not cope with "virtual crystals" (as used by many Siemens scanners) because of the implied symmetry. The efficiencies are fine though. Tahereh Niknejad implemented a modification of this to handle this, https://ieeexplore.ieee.org/abstract/document/8069577. This code is available but never made it into a PR.
Regarding the code:
out_filename_prefix measured_data model num_iterations num_eff_iterationsmeasured_data is a measured projection data (would have to be random corrected, but then truncated to zero. not good). model is A as projection data. num_iterations is the outer iterations, num_eff_iterations are the inner iterations to update efficiencies. Something like 5 and 10 should work ok.
The code outputs a series of text files with each norm-component. I'm not going to tell you what they are here, aside from saying that you can use them with apply_normfactors.
2D and 3D PET
find_ML_normfactors works in 2D only (direct sinograms). find_ML_normfactors3D et al. works in 3D, but sadly has a bug (or was it inefficiency? I cannot remember) for the g. This was fixed by Tahereh in her code. Efficiencies in 3D do work.
gefeichen
I found this command in stir4. However, no explanation is found in the documentation. Is there someplace where I can find documentation that applies to this command？ especially the input files