dival.reconstructors.reconstructor module

Provides the abstract reconstructor base class.

class dival.reconstructors.reconstructor.Reconstructor(reco_space=None, observation_space=None, name='', hyper_params=None)[source]

Bases: object

Abstract reconstructor base class.

There are two ways of implementing a Reconstructor subclass:

Implement reconstruct(). It has to support optional in-place and out-of-place evaluation.

Implement _reconstruct(). It must have one of the following signatures:

_reconstruct(self, observation, out) (in-place)

_reconstruct(self, observation) (out-of-place)

_reconstruct(self, observation, out=None) (optional in-place)

The class attribute HYPER_PARAMS defines the hyper parameters of the reconstructor class. The current values for a reconstructor instance are given by the attribute hyper_params. Properties wrapping hyper_params are automatically created by the metaclass (for hyper parameter names that are valid identifiers), such that the hyper parameters can be written and read like instance attributes.

reco_space

Reconstruction space.

Type:: odl.discr.DiscretizedSpace, optional

observation_space

Observation space.

Type:: odl.discr.DiscretizedSpace, optional

name

Name of the reconstructor.

Type:: str

hyper_params

Current hyper parameter values. Initialized automatically using the default values from HYPER_PARAMS (but may be overridden by hyper_params passed to __init__()). It is expected to have the same keys as HYPER_PARAMS. The values for these keys in this dict are wrapped by properties with the key as identifier (if possible), so an assignment to the property changes the value in this dict and vice versa.

Type:: dict

HYPER_PARAMS = {}

Specification of hyper parameters.

This class attribute is a dict that lists the hyper parameter of the reconstructor. It should not be hidden by an instance attribute of the same name (i.e. by assigning a value to self.HYPER_PARAMS in an instance of a subtype).

Note: in order to inherit HYPER_PARAMS from a super class, the subclass should create a deep copy of it, i.e. execute HYPER_PARAMS = copy.deepcopy(SuperReconstructorClass.HYPER_PARAMS) in the class body.

The keys of this dict are the names of the hyper parameters, and each value is a dict with the following fields.

Standard fields:

'default'
Default value.

'retrain'bool, optional
Whether training depends on the parameter. Default: False. Any custom subclass of LearnedReconstructor must set this field to True if training depends on the parameter value.

Hyper parameter search fields:

'range'(float, float), optional
Interval of valid values. If this field is set, the parameter is taken to be real-valued. Either 'range' or 'choices' has to be set.

'choices'sequence, optional
Sequence of valid values of any type. If this field is set, 'range' is ignored. Can be used to perform manual grid search. Either 'range' or 'choices' has to be set.

'method'{‘grid_search’, ‘hyperopt’}, optional
Optimization method for the parameter. Default: 'grid_search'. Options are:

'grid_search'
Grid search over a sequence of fixed values. Can be configured by the dict 'grid_search_options'.

'hyperopt'
Random search using the hyperopt package. Can be configured by the dict 'hyperopt_options'.

'grid_search_options'dict
Option dict for grid search.

The following fields determine how 'range' is sampled (in case it is specified and no 'choices' are specified):

'num_samples'int, optional
Number of values. Default: 10.

'type'{‘linear’, ‘logarithmic’}, optional
Type of grid, i.e. distribution of the values. Default: 'linear'. Options are:

'linear'
Equidistant values in the 'range'.

'logarithmic'
Values in the 'range' that are equidistant in the log scale.

'log_base'int, optional
Log-base that is used if 'type' is 'logarithmic'. Default: 10..

'hyperopt_options'dict
Option dict for 'hyperopt' method with the fields:

'space'hyperopt space, optional
Custom hyperopt search space. If this field is set, 'range' and 'type' are ignored.

'type'{‘uniform’}, optional
Type of the space for sampling. Default: 'uniform'. Options are:

'uniform'
Uniform distribution over the 'range'.

__init__(reco_space=None, observation_space=None, name='', hyper_params=None)[source]

reconstruct(observation, out=None)[source]

Reconstruct input data from observation data.

The default implementation calls _reconstruct, automatically choosing in-place or out-of-place evaluation.

Parameters:

observation (observation_space element-like) – The observation data.
out (reco_space element-like, optional) – Array to which the result is written (in-place evaluation). If None, a new array is created (out-of-place evaluation). If None, the new array is initialized with zero before calling _reconstruct().

Returns:

reconstruction – The reconstruction.

Return type:

reco_space element or out

save_hyper_params(path)[source]

Save hyper parameters to JSON file. See also load_hyper_params().

Parameters:: path (str) – Path of the file in which the hyper parameters should be saved. The ending '.json' is automatically appended if not included.

load_hyper_params(path)[source]

Load hyper parameters from JSON file. See also save_hyper_params().

Parameters:: path (str) – Path of the file in which the hyper parameters are stored. The ending '.json' is automatically appended if not included.

save_params(path=None, hyper_params_path=None)[source]

Save all parameters to file. E.g. for learned reconstructors, both hyper parameters and learned parameters should be included. The purpose of this method, together with load_params(), is to define a unified way of saving and loading any kind of reconstructor. The default implementation calls save_hyper_params(). Subclasses must reimplement this method in order to include non-hyper parameters.

Implementations should derive a sensible default for hyper_params_path from path, such that all parameters can be saved and loaded by specifying only path. Recommended patterns are:

if non-hyper parameters are stored in a single file and path specifies it without file ending: hyper_params_path=path + '_hyper_params.json'

if non-hyper parameters are stored in a directory: hyper_params_path=os.path.join(path, 'hyper_params.json').

if there are no non-hyper parameters, this default implementation can be used: hyper_params_path=path + '_hyper_params.json'

Parameters:

path (str[, optional]) – Path at which all (non-hyper) parameters should be saved. This argument is required if the reconstructor has non-hyper parameters or hyper_params_path is omitted. If the reconstructor has non-hyper parameters, the implementation may interpret it as a file path or as a directory path for multiple files (the dir should be created by this method if it does not exist). If the implementation expects a file path, it should accept it without file ending.
hyper_params_path (str, optional) – Path of the file in which the hyper parameters should be saved. The ending '.json' is automatically appended if not included. If not specified, it should be determined from path (see method description above). The default implementation saves to the file path + '_hyper_params.json'.

load_params(path=None, hyper_params_path=None)[source]

Load of parameters from file. E.g. for learned reconstructors, both hyper parameters and learned parameters should be included. The purpose of this method, together with save_params(), is to define a unified way of saving and loading any kind of reconstructor. The default implementation calls load_hyper_params(). Subclasses must reimplement this method in order to include non-hyper parameters.

See save_params() for recommended patterns to derive a default hyper_params_path from path.

Parameters:

path (str[, optional]) – Path at which all (non-hyper) parameters are stored. This argument is required if the reconstructor has non-hyper parameters or hyper_params_path is omitted. If the reconstructor has non-hyper parameters, the implementation may interpret it as a file path or as a directory path for multiple files. If the implementation expects a file path, it should accept it without file ending.
hyper_params_path (str, optional) – Path of the file in which the hyper parameters are stored. The ending '.json' is automatically appended if not included. If not specified, it should be determined from path (see description of save_params()). The default implementation reads from the file path + '_hyper_params.json'.

class dival.reconstructors.reconstructor.LearnedReconstructor(reco_space=None, observation_space=None, name='', hyper_params=None)[source]

Bases: Reconstructor

train(dataset)[source]

Train the reconstructor with a dataset by adapting its parameters.

Should only use the training and validation data from dataset.

Parameters:: dataset (Dataset) – The dataset from which the training data should be used.

save_params(path, hyper_params_path=None)[source]

Save all parameters to file.

Calls save_hyper_params() and save_learned_params(), where save_learned_params() should be implemented by the subclass.

This implementation assumes that path is interpreted as a single file name, preferably specified without file ending. If path is a directory, the subclass needs to reimplement this method in order to follow the recommended default value pattern: hyper_params_path=os.path.join(path, 'hyper_params.json').

Parameters:

path (str) – Path at which the learned parameters should be saved. Passed to save_learned_params(). If the implementation interprets it as a file path, it is preferred to exclude the file ending (otherwise the default value of hyper_params_path is suboptimal).
hyper_params_path (str, optional) – Path of the file in which the hyper parameters should be saved. The ending '.json' is automatically appended if not included. If not specified, this implementation saves to the file path + '_hyper_params.json'.

load_params(path, hyper_params_path=None)[source]

Load all parameters from file.

Calls load_hyper_params() and load_learned_params(), where load_learned_params() should be implemented by the subclass.

This implementation assumes that path is interpreted as a single file name, preferably specified without file ending. If path is a directory, the subclass needs to reimplement this method in order to follow the recommended default value pattern: hyper_params_path=os.path.join(path, 'hyper_params.json').

Parameters:

path (str) – Path at which the parameters are stored. Passed to load_learned_params(). If the implementation interprets it as a file path, it is preferred to exclude the file ending (otherwise the default value of hyper_params_path is suboptimal).
hyper_params_path (str, optional) – Path of the file in which the hyper parameters are stored. The ending '.json' is automatically appended if not included. If not specified, this implementation reads from the file path + '_hyper_params.json'.

save_learned_params(path)[source]

Save learned parameters to file.

Parameters:: path (str) – Path at which the learned parameters should be saved. Implementations may interpret this as a file path or as a directory path for multiple files (which then should be created if it does not exist). If the implementation expects a file path, it should accept it without file ending.

load_learned_params(path)[source]

Load learned parameters from file.

Parameters:: path (str) – Path at which the learned parameters are stored. Implementations may interpret this as a file path or as a directory path for multiple files. If the implementation expects a file path, it should accept it without file ending.

class dival.reconstructors.reconstructor.IterativeReconstructor(callback=None, **kwargs)[source]

Bases: Reconstructor

Iterative reconstructor base class. It is recommended to use StandardIterativeReconstructor as a base class for iterative reconstructors if suitable, which provides some default implementation.

Subclasses must call callback after each iteration in self.reconstruct. This is e.g. required by the evaluation module.

callback

Callback to be called after each iteration.

Type:: odl.solvers.util.callback.Callback or None

HYPER_PARAMS = {'iterations': {'default': 100, 'retrain': False}}

Specification of hyper parameters.

This class attribute is a dict that lists the hyper parameter of the reconstructor. It should not be hidden by an instance attribute of the same name (i.e. by assigning a value to self.HYPER_PARAMS in an instance of a subtype).

Note: in order to inherit HYPER_PARAMS from a super class, the subclass should create a deep copy of it, i.e. execute HYPER_PARAMS = copy.deepcopy(SuperReconstructorClass.HYPER_PARAMS) in the class body.

The keys of this dict are the names of the hyper parameters, and each value is a dict with the following fields.

Standard fields:

'default'
Default value.

'retrain'bool, optional
Whether training depends on the parameter. Default: False. Any custom subclass of LearnedReconstructor must set this field to True if training depends on the parameter value.

Hyper parameter search fields:

'range'(float, float), optional
Interval of valid values. If this field is set, the parameter is taken to be real-valued. Either 'range' or 'choices' has to be set.

'choices'sequence, optional
Sequence of valid values of any type. If this field is set, 'range' is ignored. Can be used to perform manual grid search. Either 'range' or 'choices' has to be set.

'method'{‘grid_search’, ‘hyperopt’}, optional
Optimization method for the parameter. Default: 'grid_search'. Options are:

'grid_search'
Grid search over a sequence of fixed values. Can be configured by the dict 'grid_search_options'.

'hyperopt'
Random search using the hyperopt package. Can be configured by the dict 'hyperopt_options'.

'grid_search_options'dict
Option dict for grid search.

The following fields determine how 'range' is sampled (in case it is specified and no 'choices' are specified):

'num_samples'int, optional
Number of values. Default: 10.

'type'{‘linear’, ‘logarithmic’}, optional
Type of grid, i.e. distribution of the values. Default: 'linear'. Options are:

'linear'
Equidistant values in the 'range'.

'logarithmic'
Values in the 'range' that are equidistant in the log scale.

'log_base'int, optional
Log-base that is used if 'type' is 'logarithmic'. Default: 10..

'hyperopt_options'dict
Option dict for 'hyperopt' method with the fields:

'space'hyperopt space, optional
Custom hyperopt search space. If this field is set, 'range' and 'type' are ignored.

'type'{‘uniform’}, optional
Type of the space for sampling. Default: 'uniform'. Options are:

'uniform'
Uniform distribution over the 'range'.

__init__(callback=None, **kwargs)[source]

Parameters:: callback (odl.solvers.util.callback.Callback, optional) – Callback to be called after each iteration.

reconstruct(observation, out=None, callback=None)[source]

Reconstruct input data from observation data.

Same as Reconstructor.reconstruct(), but with additional optional callback parameter.

Parameters:

observation (observation_space element-like) – The observation data.
out (reco_space element-like, optional) – Array to which the result is written (in-place evaluation). If None, a new array is created (out-of-place evaluation).
callback (odl.solvers.util.callback.Callback, optional) – Additional callback for this reconstruction that is temporarily composed with callback, i.e. also called after each iteration. If None, just callback is called.

Returns:

reconstruction – The reconstruction.

Return type:

reco_space element or out

property iterations

class dival.reconstructors.reconstructor.StandardIterativeReconstructor(x0=None, callback=None, **kwargs)[source]

Bases: IterativeReconstructor

Standard iterative reconstructor base class.

Provides a default implementation that only requires subclasses to implement _compute_iterate() and optionally _setup().

x0

Default initial value for the iterative reconstruction. Can be overridden by passing a different x0 to reconstruct().

Type:: reco_space element-like or None

callback

Callback that is called after each iteration.

Type:: odl.solvers.util.callback.Callback or None

__init__(x0=None, callback=None, **kwargs)[source]

Parameters:

x0 (reco_space element-like, optional) – Default initial value for the iterative reconstruction. Can be overridden by passing a different x0 to reconstruct().
callback (odl.solvers.util.callback.Callback, optional) – Callback that is called after each iteration.

reconstruct(observation, out=None, x0=None, last_iter=0, callback=None)[source]

Reconstruct input data from observation data.

Same as Reconstructor.reconstruct(), but with additional options for iterative reconstructors.

Parameters:

observation (observation_space element-like) – The observation data.
out (reco_space element-like, optional) – Array to which the result is written (in-place evaluation). If None, a new array is created (out-of-place evaluation).
x0 (reco_space element-like, optional) – Initial value for the iterative reconstruction. Overrides the attribute x0, which can be set when calling __init__(). If both x0 and this argument are None, the default implementation uses the value of out if called in-place, or zero if called out-of-place.
last_iter (int, optional) – If x0 is the result of an iteration by this method, this can be used to specify the number of iterations so far. The number of iterations for the current call is self.hyper_params['iterations'] - last_iter.
callback (odl.solvers.util.callback.Callback, optional) – Additional callback for this reconstruction that is temporarily composed with callback, i.e. also called after each iteration. If None, just callback is called.

Returns:

reconstruction – The reconstruction.

Return type:

reco_space element or out

property iterations

class dival.reconstructors.reconstructor.FunctionReconstructor(function, *args, fun_args=None, fun_kwargs=None, **kwargs)[source]

Bases: Reconstructor

Reconstructor defined by a callable.

function

Callable that is used in reconstruct.

Type:: callable

fun_args

Arguments to be passed to function.

Type:: list

fun_kwargs

Keyword arguments to be passed to function.

Type:: dict

__init__(function, *args, fun_args=None, fun_kwargs=None, **kwargs)[source]

Parameters:

function (callable) – Callable that is used in reconstruct().
fun_args (list, optional) – Arguments to be passed to function.
fun_kwargs (dict, optional) – Keyword arguments to be passed to function.