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 attributehyper_params
. Properties wrappinghyper_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 asHYPER_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. executeHYPER_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, optionalWhether training depends on the parameter. Default:
False
. Any custom subclass of LearnedReconstructor must set this field toTrue
if training depends on the parameter value.
Hyper parameter search fields:
'range'
(float, float), optionalInterval 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, optionalSequence 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’}, optionalOptimization 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'
dictOption 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, optionalNumber of values. Default:
10
.'type'
{‘linear’, ‘logarithmic’}, optionalType 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, optionalLog-base that is used if
'type'
is'logarithmic'
. Default:10.
.
'hyperopt_options'
dictOption dict for
'hyperopt'
method with the fields:'space'
hyperopt space, optionalCustom hyperopt search space. If this field is set,
'range'
and'type'
are ignored.'type'
{‘uniform’}, optionalType 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]¶ Initialize self. See help(type(self)) for accurate signature.
-
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 callssave_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 filepath + '_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 callsload_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 ofsave_params()
). The default implementation reads from the filepath + '_hyper_params.json'
.
-
class
dival.reconstructors.reconstructor.
LearnedReconstructor
(reco_space=None, observation_space=None, name='', hyper_params=None)[source]¶ Bases:
dival.reconstructors.reconstructor.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()
andsave_learned_params()
, wheresave_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 filepath + '_hyper_params.json'
.
-
load_params
(path, hyper_params_path=None)[source]¶ Load all parameters from file.
Calls
load_hyper_params()
andload_learned_params()
, whereload_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 filepath + '_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:
dival.reconstructors.reconstructor.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 inself.reconstruct
. This is e.g. required by theevaluation
module.-
callback
¶ Callback to be called after each iteration.
- Type
odl.solvers.util.callback.Callback
or None
-
HYPER_PARAMS
= {'iterations': {'default': 100, 'retrain': False}}¶
-
__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 withcallback
, i.e. also called after each iteration. If None, justcallback
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:
dival.reconstructors.reconstructor.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
toreconstruct()
.- 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 differentx0
toreconstruct()
.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 attributex0
, which can be set when calling__init__()
. If bothx0
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 withcallback
, i.e. also called after each iteration. If None, justcallback
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:
dival.reconstructors.reconstructor.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
-