Implementation of the Ordered Subsets version of Green's MAP One Step Late algorithm. More...

#include "stir/OSMAPOSL/OSMAPOSLReconstruction.h"

Inheritance diagram for stir::OSMAPOSLReconstruction< TargetT >:

[legend]

Public Member Functions
	OSMAPOSLReconstruction ()
	Default constructor (calling set_defaults()).
	OSMAPOSLReconstruction (const std::string &parameter_filename)
	Constructor, initialises everything from parameter file, or (when parameter_filename == "") by calling ask_parameters().
OSMAPOSLReconstruction &	get_parameters ()
	accessor for the external parameters
const OSMAPOSLReconstruction &	get_parameters () const
	accessor for the external parameters
std::string	method_info () const override
	gives method information
PoissonLogLikelihoodWithLinearModelForMean< TargetT > const &	get_objective_function () const
	Return current objective function.
Public Member Functions inherited from stir::RegisteredParsingObject< OSMAPOSLReconstruction< TargetT >, Reconstruction< TargetT >, IterativeReconstruction< TargetT > >
std::string	get_registered_name () const override
	Returns Derived::registered_name.
std::string	parameter_info () override
	Returns a string with all parameters and their values, in a form suitable for parsing again.
Public Member Functions inherited from stir::IterativeReconstruction< TargetT >
int	get_subiteration_num () const
	accessor for the subiteration counter
int	get_subset_num ()
	accessor for finding the current subset number
virtual TargetT *	get_initial_data_ptr () const
	Gets a pointer to the initial data.
Succeeded	reconstruct () override
	executes the reconstruction
Succeeded	reconstruct (shared_ptr< TargetT > const &target_data_sptr) override
	executes the reconstruction with target_data_sptr as initial value
std::string	make_filename_prefix_subiteration_num (const std::string &filename_prefix) const
	A utility function that creates a filename_prefix by appending the current subiteration number.
std::string	make_filename_prefix_subiteration_num () const
	A utility function that creates the output filename_prefix for the current subiteration number.
GeneralisedObjectiveFunction< TargetT > const &	get_objective_function () const
shared_ptr< GeneralisedObjectiveFunction< TargetT > >	get_objective_function_sptr () const
const int	get_max_num_full_iterations () const
	the maximum allowed number of full iterations
const int	get_num_subsets () const
	the number of ordered subsets
const int	get_num_subiterations () const
	the number of subiterations
const int	get_start_subiteration_num () const
	value with which to initialize the subiteration counter
const int	get_start_subset_num () const
	the starting subset number
const int	get_save_interval () const
	subiteration interval at which data will be saved
const bool	get_randomise_subset_order () const
	signals whether to randomise the subset order in each iteration
const DataProcessor< TargetT > &	get_inter_iteration_filter () const
	inter-iteration filter
shared_ptr< DataProcessor< TargetT > >	get_inter_iteration_filter_sptr ()
const int	get_inter_iteration_filter_interval () const
	subiteration interval at which to apply inter-iteration filters
const int	get_report_objective_function_values_interval () const
	subiteration interval at which to report the values of the objective function
void	set_objective_function_sptr (const shared_ptr< GeneralisedObjectiveFunction< TargetT > > &)
	The objective function that will be optimised.
void	set_max_num_full_iterations (const int)
	the maximum allowed number of full iterations
void	set_num_subsets (const int)
	the number of ordered subsets
void	set_num_subiterations (const int)
	the number of subiterations
void	set_start_subiteration_num (const int)
	value with which to initialize the subiteration counter
void	set_start_subset_num (const int)
	the starting subset number
void	set_save_interval (const int)
	subiteration interval at which data will be saved
void	set_randomise_subset_order (const bool)
	signals whether to randomise the subset order in each iteration
void	set_inter_iteration_filter_ptr (const shared_ptr< DataProcessor< TargetT > > &)
	inter-iteration filter
void	set_inter_iteration_filter_interval (const int)
	subiteration interval at which to apply inter-iteration filters
void	set_report_objective_function_values_interval (const int)
	subiteration interval at which to report the values of the objective function
void	set_input_data (const shared_ptr< ExamData > &arg) override
	set_input_data
const ExamData &	get_input_data () const override
	get input data
Public Member Functions inherited from stir::Reconstruction< TargetT >
	Reconstruction ()
	default constructor (calls set_defaults())
	~Reconstruction () override
	virtual destructor
void	set_output_filename_prefix (const std::string &)
	file name for output reconstructed images
void	set_output_file_format_ptr (const shared_ptr< OutputFileFormat< TargetT > > &)
	defines the format of the output files
void	set_post_processor_sptr (const shared_ptr< DataProcessor< TargetT > > &)
	post-filter
void	set_disable_output (bool _val)
	set_disable_output
shared_ptr< TargetT >	get_target_image ()
	get_reconstructed_image
Public Member Functions inherited from stir::ParsingObject
	ParsingObject (const ParsingObject &)
ParsingObject &	operator= (const ParsingObject &)
bool	parse (std::istream &f)
bool	parse (const char *const filename)
void	ask_parameters ()
Public Member Functions inherited from stir::TimedObject
void	reset_timers ()
	reset all timers kept by this object
void	stop_timers () const
	stop all timers kept by this object
void	start_timers (bool do_reset=false) const
	start all timers kept by this object
double	get_CPU_timer_value () const
	get current value of the CPU timer (since first use or last reset)
double	get_wall_clock_timer_value () const
	get current value of the wall-clock timer (since first use or last reset)

Static Public Attributes
static const char *const	registered_name
	Name which will be used when parsing a OSMAPOSLReconstruction object.

Functions to set parameters
This can be used as alternative to the parsing mechanism. Warning Be careful with setting shared pointers. If you modify the objects in one place, all objects that use the shared pointer will be affected.
bool	enforce_initial_positivity
	operations prior to the iterations
bool	do_rim_truncation
	determines wether voxels outside a circular FOV will be set to 0 or not
int	inter_update_filter_interval
	subiteration interval at which to apply inter-update filters
shared_ptr< DataProcessor< TargetT > >	inter_update_filter_ptr
	inter-update filter object
double	maximum_relative_change
	restrict updates (larger relative updates will be thresholded)
double	minimum_relative_change
	restrict updates (smaller relative updates will be thresholded)
int	write_update_image
	boolean value to determine if the update images have to be written to disk
std::string	MAP_model
	should be either additive or multiplicative
void	set_inter_update_filter_interval (const int)
	subiteration interval at which to apply inter-update filters
void	set_inter_update_filter_ptr (const shared_ptr< DataProcessor< TargetT > > &)
	inter-update filter object
void	set_maximum_relative_change (const double)
	restrict updates (larger relative updates will be thresholded)
void	set_minimum_relative_change (const double)
	restrict updates (smaller relative updates will be thresholded)
void	set_enforce_initial_positivity (const bool)
void	set_write_update_image (const int)
	boolean value to determine if the update images have to be written to disk
void	set_MAP_model (const std::string &)
	should be either additive or multiplicative
void	ask_parameters () override
	prompts the user to enter parameter values manually
Succeeded	set_up (shared_ptr< TargetT > const &target_image_ptr) override
	operations prior to the iterations
void	update_estimate (TargetT &current_image_estimate) override
	the principal operations for updating the image iterates at each iteration
void	set_defaults () override
	Set defaults before parsing.
void	initialise_keymap () override
	Initialise all keywords.
bool	post_processing () override
	used to check acceptable parameter ranges, etc...
virtual void	compute_sub_gradient_without_penalty_plus_sensitivity (TargetT &gradient, const TargetT &current_estimate, const int subset_num)
virtual const TargetT &	get_subset_sensitivity (const int subset_num)
virtual void	apply_multiplicative_update (TargetT &current_image_estimate, const TargetT &multiplicative_update_image)
void	do_sensitivity (const char *const par_filename)

Additional Inherited Members
Static Public Member Functions inherited from stir::RegisteredParsingObject< OSMAPOSLReconstruction< TargetT >, Reconstruction< TargetT >, IterativeReconstruction< TargetT > >
static Reconstruction< TargetT > *	read_from_stream (std::istream *)
	Construct a new object (of type Derived) by parsing the istream.
Static Public Member Functions inherited from stir::RegisteredObject< Reconstruction< TargetT > >
static Reconstruction< TargetT > *	read_registered_object (std::istream *in, const std::string &registered_name)
	Construct a new object (of a type derived from Root, its actual type determined by the registered_name parameter) by parsing the istream.
static Reconstruction< TargetT > *	ask_type_and_parameters ()
	ask the user for the type, and then calls read_registered_object(0, type)
static void	list_registered_names (std::ostream &stream)
	List all possible registered names to the stream.
Protected Types inherited from stir::RegisteredObject< Reconstruction< TargetT > >
typedef Reconstruction< TargetT > ()	RootFactory(std::istream *)
	The type of a root factory is a function, taking an istream* as argument, and returning a Root*.
typedef FactoryRegistry< std::string, RootFactory, interfile_less >	RegistryType
	The type of the registry.
virtual void	end_of_iteration_processing (TargetT &current_estimate)
	operations for the end of the iteration
virtual void	check (TargetT const &target_data) const
	do consistency checks
void	initialise (const std::string &parameter_filename)
	This function initialises all parameters, either via parsing, or by calling ask_parameters() (when parameter_filename is the empty string).
void	set_defaults () override
	Set defaults before parsing.
void	initialise_keymap () override
	Initialise all keywords.
bool	post_processing () override
	used to check acceptable parameters after parsing
virtual void	set_key_values ()
	This will be called before parsing or parameter_info is called.
Static Protected Member Functions inherited from stir::RegisteredObject< Reconstruction< TargetT > >
static RegistryType &	registry ()
	Static function returning the registry.
shared_ptr< GeneralisedObjectiveFunction< TargetT > >	objective_function_sptr
int	subiteration_num
	the subiteration counter
bool	terminate_iterations
	used to abort the loop over iterations
int	max_num_full_iterations
	the maximum allowed number of full iterations
int	num_subsets
	the number of ordered subsets
int	num_subiterations
	the number of subiterations
int	start_subiteration_num
	value with which to initialize the subiteration counter
std::string	initial_data_filename
	name of the file containing the data for intializing the reconstruction
int	start_subset_num
	the starting subset number
int	save_interval
	subiteration interval at which data will be saved
bool	randomise_subset_order
	signals whether to randomise the subset order in each iteration
shared_ptr< DataProcessor< TargetT > >	inter_iteration_filter_ptr
	inter-iteration filter
int	inter_iteration_filter_interval
	subiteration interval at which to apply inter-iteration filters
int	report_objective_function_values_interval
	subiteration interval at which to report the values of the objective function
std::string	output_filename_prefix
	file name for output reconstructed images
shared_ptr< OutputFileFormat< TargetT > >	output_file_format_ptr
	defines the format of the output files
shared_ptr< DataProcessor< TargetT > >	post_filter_sptr
	post-filter
bool	_already_set_up
shared_ptr< TargetT >	target_data_sptr
	target_data_sptr
bool	_disable_output
	_disable_output
int	_verbosity
	Verbosity level.
KeyParser	parser

Detailed Description

template<typename TargetT>
class stir::OSMAPOSLReconstruction< TargetT >

Implementation of the Ordered Subsets version of Green's MAP One Step Late algorithm.

See Jacobson et al, PMB for a description of the implementation.

When no prior info is specified, this reduces to 'standard' OSEM.

Two different forms of the prior are implemented. (For background, see Mustavic&Thielemans, proc. IEEE MIC 2001).

When MAP_model == "additive" this implements the standard form of OSL (with a small modification for allowing subsets):

lambda_new = lambda / ((p_v + beta*prior_gradient)/ num_subsets) *

sum_subset backproj(measured/forwproj(lambda))

stir::IterativeReconstruction::num_subsets

int num_subsets

the number of ordered subsets

Definition IterativeReconstruction.h:271

with $p_v = sum_b p_{bv}$ . actually, we restrict 1 + beta*prior_gradient/p_v between .1 and 10

On the other hand, when MAP_model == "multiplicative" it implements

lambda_new = lambda / (p_v*(1 + beta*prior_gradient)/ num_subsets) *

sum_subset backproj(measured/forwproj(lambda))

with $p_v = sum_b p_{bv}$ . actually, we restrict 1 + beta*prior_gradient between .1 and 10.

Note that all this assumes 'balanced subsets', i.e.

$\‍[\sum_{b \in \rm{subset}} p_{bv} = { \sum_b p_{bv} \over \rm{numsubsets} } \‍]$

Warning: This class should be the last in a Reconstruction hierarchy.

Constructor & Destructor Documentation

◆ OSMAPOSLReconstruction() [1/2]

template<typename TargetT>

stir::OSMAPOSLReconstruction< TargetT >::OSMAPOSLReconstruction ( )

Default constructor (calling set_defaults()).

References OSMAPOSLReconstruction(), and set_defaults().

Referenced by get_parameters(), get_parameters(), OSMAPOSLReconstruction(), and OSMAPOSLReconstruction().

◆ OSMAPOSLReconstruction() [2/2]

template<typename TargetT>

stir::OSMAPOSLReconstruction< TargetT >::OSMAPOSLReconstruction ( const std::string & parameter_filename )

explicit

Constructor, initialises everything from parameter file, or (when parameter_filename == "") by calling ask_parameters().

References stir::info(), stir::Reconstruction< TargetT >::initialise(), OSMAPOSLReconstruction(), and stir::RegisteredParsingObject< OSMAPOSLReconstruction< TargetT >, Reconstruction< TargetT >, IterativeReconstruction< TargetT > >::parameter_info().

Member Function Documentation

◆ get_parameters() [1/2]

template<typename TargetT>

OSMAPOSLReconstruction & stir::OSMAPOSLReconstruction< TargetT >::get_parameters ( )

inline

accessor for the external parameters

References OSMAPOSLReconstruction().

◆ get_parameters() [2/2]

template<typename TargetT>

const OSMAPOSLReconstruction & stir::OSMAPOSLReconstruction< TargetT >::get_parameters ( ) const

inline

accessor for the external parameters

References OSMAPOSLReconstruction().

◆ method_info()

template<typename TargetT>

std::string stir::OSMAPOSLReconstruction< TargetT >::method_info ( ) const

overridevirtual

gives method information

Implements stir::Reconstruction< TargetT >.

References stir::IterativeReconstruction< TargetT >::inter_iteration_filter_interval, inter_update_filter_interval, method_info(), and stir::IterativeReconstruction< TargetT >::num_subsets.

Referenced by method_info().

◆ get_objective_function()

template<typename TargetT>

PoissonLogLikelihoodWithLinearModelForMean< TargetT > const & stir::OSMAPOSLReconstruction< TargetT >::get_objective_function ( ) const

Return current objective function.

References get_objective_function().

Referenced by get_objective_function().

◆ set_inter_update_filter_interval()

template<typename TargetT>

void stir::OSMAPOSLReconstruction< TargetT >::set_inter_update_filter_interval ( const int arg )

subiteration interval at which to apply inter-update filters

References inter_update_filter_interval, and set_inter_update_filter_interval().

Referenced by set_inter_update_filter_interval().

◆ set_inter_update_filter_ptr()

template<typename TargetT>

void stir::OSMAPOSLReconstruction< TargetT >::set_inter_update_filter_ptr ( const shared_ptr< DataProcessor< TargetT > > & arg )

inter-update filter object

References inter_update_filter_ptr, and set_inter_update_filter_ptr().

Referenced by set_inter_update_filter_ptr().

◆ set_maximum_relative_change()

template<typename TargetT>

void stir::OSMAPOSLReconstruction< TargetT >::set_maximum_relative_change ( const double arg )

restrict updates (larger relative updates will be thresholded)

References maximum_relative_change, and set_maximum_relative_change().

Referenced by set_maximum_relative_change().

◆ set_minimum_relative_change()

template<typename TargetT>

void stir::OSMAPOSLReconstruction< TargetT >::set_minimum_relative_change ( const double arg )

restrict updates (smaller relative updates will be thresholded)

References minimum_relative_change, and set_minimum_relative_change().

Referenced by set_minimum_relative_change().

◆ set_write_update_image()

template<typename TargetT>

void stir::OSMAPOSLReconstruction< TargetT >::set_write_update_image ( const int arg )

boolean value to determine if the update images have to be written to disk

References set_write_update_image(), and write_update_image.

Referenced by set_write_update_image().

◆ set_MAP_model()

template<typename TargetT>

void stir::OSMAPOSLReconstruction< TargetT >::set_MAP_model ( const std::string & arg )

should be either additive or multiplicative

References stir::error(), MAP_model, and set_MAP_model().

Referenced by post_processing(), and set_MAP_model().

◆ ask_parameters()

template<typename TargetT>

void stir::OSMAPOSLReconstruction< TargetT >::ask_parameters ( )

overridevirtual

prompts the user to enter parameter values manually

Reimplemented from stir::IterativeReconstruction< TargetT >.

References stir::ask(), stir::ask_num(), ask_parameters(), stir::ask_string(), enforce_initial_positivity, inter_update_filter_interval, inter_update_filter_ptr, stir::RegisteredObject< DataProcessor< DataT > >::list_registered_names(), MAP_model, maximum_relative_change, minimum_relative_change, stir::IterativeReconstruction< TargetT >::num_subiterations, stir::RegisteredObject< DataProcessor< DataT > >::read_registered_object(), and write_update_image.

Referenced by stir::KOSMAPOSLReconstruction< TargetT >::ask_parameters(), and ask_parameters().

◆ set_up()

template<typename TargetT>

Succeeded stir::OSMAPOSLReconstruction< TargetT >::set_up ( shared_ptr< TargetT > const & target_image_ptr )

overridevirtual

operations prior to the iterations

Reimplemented from stir::IterativeReconstruction< TargetT >.

References enforce_initial_positivity, stir::error(), stir::info(), stir::IterativeReconstruction< TargetT >::inter_iteration_filter_interval, stir::IterativeReconstruction< TargetT >::inter_iteration_filter_ptr, inter_update_filter_interval, inter_update_filter_ptr, stir::IterativeReconstruction< TargetT >::set_up(), set_up(), and stir::threshold_min_to_small_positive_value().

Referenced by set_up().

◆ update_estimate()

template<typename TargetT>

void stir::OSMAPOSLReconstruction< TargetT >::update_estimate ( TargetT & current_image_estimate )

overridevirtual

the principal operations for updating the image iterates at each iteration

Implements stir::IterativeReconstruction< TargetT >.

References stir::Reconstruction< TargetT >::_disable_output, stir::Reconstruction< TargetT >::check(), stir::divide(), stir::IterativeReconstruction< TargetT >::get_num_subsets(), stir::IterativeReconstruction< TargetT >::get_subset_num(), stir::info(), inter_update_filter_interval, inter_update_filter_ptr, MAP_model, maximum_relative_change, minimum_relative_change, stir::Reconstruction< TargetT >::output_file_format_ptr, stir::Reconstruction< TargetT >::output_filename_prefix, stir::IterativeReconstruction< TargetT >::subiteration_num, stir::threshold_upper_lower(), update_estimate(), and write_update_image.

Referenced by update_estimate().

◆ set_defaults()

template<typename TargetT>

void stir::OSMAPOSLReconstruction< TargetT >::set_defaults ( )

overrideprotectedvirtual

Set defaults before parsing.

Reimplemented from stir::IterativeReconstruction< TargetT >.

References enforce_initial_positivity, inter_update_filter_interval, inter_update_filter_ptr, MAP_model, maximum_relative_change, minimum_relative_change, set_defaults(), stir::ParsingObject::set_defaults(), and write_update_image.

Referenced by OSMAPOSLReconstruction(), stir::KOSMAPOSLReconstruction< TargetT >::set_defaults(), and set_defaults().

◆ initialise_keymap()

template<typename TargetT>

void stir::OSMAPOSLReconstruction< TargetT >::initialise_keymap ( )

overrideprotectedvirtual

Initialise all keywords.

Reimplemented from stir::IterativeReconstruction< TargetT >.

References enforce_initial_positivity, initialise_keymap(), stir::ParsingObject::initialise_keymap(), inter_update_filter_interval, inter_update_filter_ptr, MAP_model, maximum_relative_change, minimum_relative_change, and write_update_image.

Referenced by stir::KOSMAPOSLReconstruction< TargetT >::initialise_keymap(), and initialise_keymap().

◆ post_processing()

template<typename TargetT>

bool stir::OSMAPOSLReconstruction< TargetT >::post_processing ( )

overrideprotectedvirtual

used to check acceptable parameter ranges, etc...

Reimplemented from stir::IterativeReconstruction< TargetT >.

References MAP_model, post_processing(), stir::ParsingObject::post_processing(), and set_MAP_model().

Referenced by stir::KOSMAPOSLReconstruction< TargetT >::post_processing(), and post_processing().

Member Data Documentation

◆ enforce_initial_positivity

template<typename TargetT>

bool stir::OSMAPOSLReconstruction< TargetT >::enforce_initial_positivity

protected

operations prior to the iterations

determines whether non-positive values in the initial image will be set to small positive ones

Referenced by ask_parameters(), initialise_keymap(), set_defaults(), and set_up().

◆ do_rim_truncation

template<typename TargetT>

bool stir::OSMAPOSLReconstruction< TargetT >::do_rim_truncation

protected

determines wether voxels outside a circular FOV will be set to 0 or not

Currently this circular FOV is slightly smaller than the actual image size (1 pixel at each end or so).

Deprecated

◆ inter_update_filter_interval

template<typename TargetT>

int stir::OSMAPOSLReconstruction< TargetT >::inter_update_filter_interval

protected

subiteration interval at which to apply inter-update filters

Referenced by ask_parameters(), initialise_keymap(), method_info(), set_defaults(), set_inter_update_filter_interval(), set_up(), and update_estimate().

◆ inter_update_filter_ptr

template<typename TargetT>

shared_ptr<DataProcessor<TargetT> > stir::OSMAPOSLReconstruction< TargetT >::inter_update_filter_ptr

protected

inter-update filter object

Referenced by ask_parameters(), initialise_keymap(), set_defaults(), set_inter_update_filter_ptr(), set_up(), and update_estimate().

◆ maximum_relative_change

template<typename TargetT>

double stir::OSMAPOSLReconstruction< TargetT >::maximum_relative_change

protected

restrict updates (larger relative updates will be thresholded)

Referenced by ask_parameters(), initialise_keymap(), set_defaults(), set_maximum_relative_change(), and update_estimate().

◆ minimum_relative_change

template<typename TargetT>

double stir::OSMAPOSLReconstruction< TargetT >::minimum_relative_change

protected

restrict updates (smaller relative updates will be thresholded)

Referenced by ask_parameters(), initialise_keymap(), set_defaults(), set_minimum_relative_change(), and update_estimate().

◆ write_update_image

template<typename TargetT>

int stir::OSMAPOSLReconstruction< TargetT >::write_update_image

protected

boolean value to determine if the update images have to be written to disk

Referenced by ask_parameters(), initialise_keymap(), set_defaults(), set_write_update_image(), and update_estimate().

◆ MAP_model

template<typename TargetT>

std::string stir::OSMAPOSLReconstruction< TargetT >::MAP_model

protected

should be either additive or multiplicative

Referenced by ask_parameters(), initialise_keymap(), post_processing(), set_defaults(), set_MAP_model(), and update_estimate().

The documentation for this class was generated from the following files:

/home/kris/devel/STIRdistrib/STIR/src/include/stir/OSMAPOSL/OSMAPOSLReconstruction.h
/home/kris/devel/STIRdistrib/STIR/src/iterative/OSMAPOSL/OSMAPOSLReconstruction.cxx

Public Member Functions

Static Public Attributes

Functions to set parameters

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ OSMAPOSLReconstruction() [1/2]

◆ OSMAPOSLReconstruction() [2/2]

Member Function Documentation

◆ get_parameters() [1/2]

◆ get_parameters() [2/2]

◆ method_info()

◆ get_objective_function()

◆ set_inter_update_filter_interval()

◆ set_inter_update_filter_ptr()

◆ set_maximum_relative_change()

◆ set_minimum_relative_change()

◆ set_write_update_image()

◆ set_MAP_model()

◆ ask_parameters()

◆ set_up()

◆ update_estimate()

◆ set_defaults()

◆ initialise_keymap()

◆ post_processing()

Member Data Documentation

◆ enforce_initial_positivity

◆ do_rim_truncation

◆ inter_update_filter_interval

◆ inter_update_filter_ptr

◆ maximum_relative_change

◆ minimum_relative_change

◆ write_update_image

◆ MAP_model