dival package

Module contents

dival.get_config(key_path='/')[source]

Return (sub-)configuration stored in config file. Note that values may differ from the current CONFIG variable if it was manipulated directly.

Parameters

key_path (str, optional) – '/'-separated path to sub-configuration. Default is '/', which returns the full configuration dict.

Returns

(sub-)configuration, either a dict or a value

Return type

sub_config

dival.set_config(key_path, value, verbose=True)[source]

Updates (sub-)configuration both in CONFIG variable and in config file.

Parameters

  • key_path (str, optional) – '/'-separated path to sub-configuration. Pass '/' to replace the full configuration dict.

  • value (object) – (sub-)configuration value. Either a dict, which is copied, or a value.

class dival.DataPairs(observations, ground_truth=None, name='', description='')[source]

Bases: object

Bundles observations with ground_truth. Implements __getitem__() and __len__().

observations

The observations, possibly distorted or low-dimensional.

Type

list of observation space elements

ground_truth

The ground truth data (may be replaced with good quality references). If not known, it may be omitted (None).

Type

list of reconstruction space elements or None

__init__(observations, ground_truth=None, name='', description='')[source]

Initialize self. See help(type(self)) for accurate signature.

class dival.Dataset(space=None)[source]

Bases: object

Dataset base class.

Subclasses must either implement generator() or provide random access by implementing get_sample() and get_samples() (which then should be indicated by setting the attribute random_access = True).

space

The spaces of the elements of samples as a tuple. If only one element per sample is provided, this attribute is the space of the element (i.e., no tuple). It is strongly recommended to set this attribute in subclasses, as some functionality may depend on it.

Type

[tuple of ] odl.space.base_tensors.TensorSpace or None

shape

The shapes of the elements of samples as a tuple of tuple of int. If only one element per sample is provided, this attribute is the shape of the element (i.e., not a tuple of tuple of int, but a tuple of int).

Type

[tuple of ] tuple of int, optional

train_len

Number of training samples.

Type

int, optional

validation_len

Number of validation samples.

Type

int, optional

test_len

Number of test samples.

Type

int, optional

random_access

Whether the dataset supports random access via self.get_sample and self.get_samples. Setting this attribute is the preferred way for subclasses to indicate whether they support random access.

Type

bool, optional

num_elements_per_sample

Number of elements per sample. E.g. 1 for a ground truth dataset or 2 for a dataset of pairs of observation and ground truth.

Type

int, optional

standard_dataset_name

Datasets returned by get_standard_dataset have this attribute giving its name.

Type

str, optional

__init__(space=None)[source]

The attributes that potentially should be set by the subclass are: space (can also be set by argument), shape, train_len, validation_len, test_len, random_access and num_elements_per_sample.

Parameters

space ([tuple of ] odl.space.base_tensors.TensorSpace, optional) – The spaces of the elements of samples as a tuple. If only one element per sample is provided, this attribute is the space of the element (i.e., no tuple). It is strongly recommended to set space in subclasses, as some functionality may depend on it.

generator(part='train')[source]

Yield data.

The default implementation calls get_sample() if the dataset implements it (i.e., supports random access).

Parameters

part ({'train', 'validation', 'test'}, optional) – Whether to yield train, validation or test data. Default is 'train'.

Yields

data (odl element or tuple of odl elements) – Sample of the dataset.

get_train_generator()[source]
get_validation_generator()[source]
get_test_generator()[source]
get_len(part='train')[source]

Return the number of elements the generator will yield.

Parameters

part ({'train', 'validation', 'test'}, optional) – Whether to return the number of train, validation or test elements. Default is 'train'.

get_train_len()[source]

Return the number of samples the train generator will yield.

get_validation_len()[source]

Return the number of samples the validation generator will yield.

get_test_len()[source]

Return the number of samples the test generator will yield.

get_shape()[source]

Return the shape of each element.

Returns shape if it is set. Otherwise, it is inferred from space (which is strongly recommended to be set in every subclass). If also space is not set, a NotImplementedError is raised.

Returns

shape

Return type

[tuple of ] tuple

get_num_elements_per_sample()[source]

Return number of elements per sample.

Returns num_elements_per_sample if it is set. Otherwise, it is inferred from space (which is strongly recommended to be set in every subclass). If also space is not set, a NotImplementedError is raised.

Returns

num_elements_per_sample

Return type

int

get_data_pairs(part='train', n=None)[source]

Return first samples from data part as DataPairs object.

Only supports datasets with two elements per sample.``

Parameters

  • part ({'train', 'validation', 'test'}, optional) – The data part. Default is 'train'.

  • n (int, optional) – Number of pairs (from beginning). If None, all available data is used (the default).

get_data_pairs_per_index(part='train', index=None)[source]

Return specific samples from data part as DataPairs object.

Only supports datasets with two elements per sample.

For datasets not supporting random access, samples are extracted from generator(), which can be computationally expensive.

Parameters

  • part ({'train', 'validation', 'test'}, optional) – The data part. Default is 'train'.

  • index (int or list of int, optional) – Indices of the samples in the data part. Default is '[0]'.

create_torch_dataset(part='train', reshape=None, transform=None)[source]

Create a torch dataset wrapper for one part of this dataset.

If supports_random_access() returns False, a subclass of of torch.utils.data.IterableDataset is returned that fetches samples via generator(). Note: When using torch’s DataLoader with multiple workers you might want to individually configure the datasets for each worker, see the PyTorch docs on IterableDataset. For this purpose it can be useful to modify the wrapped dival dataset in worker_init_fn(), which can be accessed there via torch.utils.data.get_worker_info().dataset.dataset.

If supports_random_access() returns True, a subclass of of torch.utils.data.Dataset is returned that retrieves samples using get_sample().

Parameters

  • part ({'train', 'validation', 'test'}, optional) – The data part. Default is 'train'.

  • reshape (tuple of (tuple or None), optional) – Shapes to which the elements of each sample will be reshaped. If None is passed for an element, no reshape is applied.

  • transform (callable, optional) – Transform to be applied on each sample, useful for augmentation. Default: None, i.e. no transform.

Returns

dataset – The torch dataset wrapping this dataset. The wrapped dival dataset is assigned to the attribute dataset.dataset.

Return type

torch.utils.data.Dataset or torch.utils.data.IterableDataset

create_keras_generator(part='train', batch_size=1, shuffle=True, reshape=None)[source]

Create a keras data generator wrapper for one part of this dataset.

If supports_random_access() returns False, a generator wrapping generator() is returned. In this case no shuffling is performed regardless of the passed shuffle parameter. Also, parallel data loading (with multiple workers) is not applicable.

If supports_random_access() returns True, a tf.keras.utils.Sequence is returned, which is implemented using get_sample(). For datasets that support parallel calls to get_sample(), the returned data generator (sequence) can be used by multiple workers.

Parameters

  • part ({'train', 'validation', 'test'}, optional) – The data part. Default is 'train'.

  • batch_size (int, optional) – Batch size. Default is 1.

  • shuffle (bool, optional) – Whether to shuffle samples each epoch. This option has no effect if supports_random_access() returns False, since in that case samples are fetched directly from generator(). The default is True.

  • reshape (tuple of (tuple or None), optional) – Shapes to which the elements of each sample will be reshaped. If None is passed for an element, no reshape is applied.

get_sample(index, part='train', out=None)[source]

Get single sample by index.

Parameters

  • index (int) – Index of the sample.

  • part ({'train', 'validation', 'test'}, optional) – The data part. Default is 'train'.

  • out (array-like or tuple of (array-like or bool) or None) –

    Array(s) (or e.g. odl element(s)) to which the sample is written. A tuple should be passed, if the dataset returns two or more arrays per sample (i.e. pairs, …). If a tuple element is a bool, it has the following meaning:

    True

    Create a new array and return it.

    False

    Do not return this array, i.e. None is returned.

Returns

sample – E.g. for a pair dataset: (array, None) if out=(True, False).

Return type

[tuple of ] (array-like or None)

get_samples(key, part='train', out=None)[source]

Get samples by slice or range.

The default implementation calls get_sample() if the dataset implements it.

Parameters

  • key (slice or range) – Indexes of the samples.

  • part ({'train', 'validation', 'test'}, optional) – The data part. Default is 'train'.

  • out (array-like or tuple of (array-like or bool) or None) –

    Array(s) (or e.g. odl element(s)) to which the sample is written. The first dimension must match the number of samples requested. A tuple should be passed, if the dataset returns two or more arrays per sample (i.e. pairs, …). If a tuple element is a bool, it has the following meaning:

    True

    Create a new array and return it.

    False

    Do not return this array, i.e. None is returned.

Returns

samples – If the dataset has multiple arrays per sample, a tuple holding arrays is returned. E.g. for a pair dataset: (array, None) if out=(True, False). The samples are stacked in the first (additional) dimension of each array.

Return type

[tuple of ] (array-like or None)

supports_random_access()[source]

Whether random access seems to be supported.

If the object has the attribute self.random_access, its value is returned (this is the preferred way for subclasses to indicate whether they support random access). Otherwise, a simple duck-type check is performed which tries to get the first sample by random access.

Returns

supports – True if the dataset supports random access, otherwise False.

Return type

bool

dival.get_standard_dataset(name, **kwargs)[source]

Return a standard dataset by name.

The standard datasets are (currently):

'ellipses'

A typical synthetical CT dataset with ellipse phantoms.

EllipsesDataset is used as ground truth dataset, a ray transform with parallel beam geometry using 30 angles is applied, and white gaussian noise with a standard deviation of 2.5% (i.e. 0.025 * mean(abs(observation))) is added.

In order to avoid the inverse crime, the ground truth images of shape (128, 128) are upscaled by bilinear interpolation to a resolution of (400, 400) before the ray transform is applied (whose discretization is different from the one of ray_trafo).

Attributes of the returned dataset:
ray_trafoodl.tomo.RayTransform

Ray transform corresponding to the noiseless forward operator.

get_ray_trafo(**kwargs)function

Function that returns a ray transform corresponding to the noiseless forward operator. Keyword arguments (e.g. impl) are forwarded to the RayTransform constructor.

'lodopab'

The LoDoPaB-CT dataset, which is documented in the Data Descriptor article https://www.nature.com/articles/s41597-021-00893-z and hosted on https://zenodo.org/record/3384092. It is a simulated low dose CT dataset based on real reconstructions from the LIDC-IDRI dataset.

The dataset contains 42895 pairs of images and projection data. For simulation, a ray transform with parallel beam geometry using 1000 angles and 513 detector pixels is used. Poisson noise corresponding to 4096 incident photons per pixel before attenuation is applied to the projection data.

Attributes of the returned dataset:
ray_trafoodl.tomo.RayTransform

Ray transform corresponding to the noiseless forward operator.

Methods of the returned dataset:
get_ray_trafo(**kwargs)

Function that returns a ray transform corresponding to the noiseless forward operator. Keyword arguments (e.g. impl) are forwarded to the RayTransform constructor.

Parameters

  • name (str) – Name of the dataset.

  • kwargs (dict) –

    Keyword arguments. Supported parameters for the datasets are:

    'ellipses'
    impl{'skimage', 'astra_cpu', 'astra_cuda'}, optional

    Implementation passed to odl.tomo.RayTransform Default: 'astra_cuda'.

    fixed_seedsdict or bool, optional

    Seeds to use for random ellipse generation, passed to EllipsesDataset.__init__(). Default: False.

    fixed_noise_seedsdict or bool, optional

    Seeds to use for noise generation, passed as noise_seeds to GroundTruthDataset.create_pair_dataset(). If True is passed (the default), the seeds {'train': 1, 'validation': 2, 'test': 3} are used.

    'lodopab'
    num_anglesint, optional

    Number of angles to use from the full 1000 angles. Must be a divisor of 1000.

    observation_model{'post-log', 'pre-log'}, optional

    The observation model to use. Default is 'post-log'.

    min_photon_countfloat, optional

    Replacement value for a simulated photon count of zero. If observation_model == 'post-log', a value greater than zero is required in order to avoid undefined values. The default is 0.1, both for 'post-log' and 'pre-log' model.

    sorted_by_patientbool, optional

    Whether to sort the samples by patient id. Useful to resplit the dataset. Default: False.

    impl{'skimage', 'astra_cpu', 'astra_cuda'}, optional

    Implementation passed to odl.tomo.RayTransform Default: 'astra_cuda'.

Returns

dataset – The standard dataset. It has an attribute standard_dataset_name that stores its name.

Return type

Dataset

dival.get_reference_reconstructor(reconstructor_key_name_or_type, dataset_name, pretrained=True, **kwargs)[source]

Return a reference reconstructor.

Parameters

  • reconstructor_key_name_or_type (str or type) – Key name of configuration or reconstructor type.

  • dataset_name (str) – Standard dataset name.

  • pretrained (bool, optional) – Whether learned parameters should be loaded (if any). Default: True.

  • kwargs (dict) – Keyword arguments (passed to construct_reconstructor()). For CT configurations this includes the 'impl' used by odl.tomo.RayTransform.

Raises

RuntimeError – If parameter files are missing and the user chooses not to download.

Returns

reconstructor – The reference reconstructor.

Return type

Reconstructor

class dival.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]

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 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.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 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}}
__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.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 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.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() 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.Measure(short_name=None)[source]

Bases: abc.ABC

Abstract base class for measures used for evaluation.

In subclasses, either __init__() should be inherited or it should call super().__init__() in order to register the short_name and to ensure it is unique.

measure_type

The measure type. Measures with type 'distance' should attain small values if the reconstruction is good. Measures with type 'quality' should attain large values if the reconstruction is good.

Type

{'distance', 'quality'}

short_name

Short name of the measure, used as identifier (key in measure_dict).

Type

str

name

Name of the measure.

Type

str

description

Description of the measure.

Type

str

measure_type = None

Class attribute, default value for measure_type.

name = ''

Class attribute, default value for name.

description = ''

Class attribute, default value for description.

measure_dict = {'l2': <dival.measure.L2Measure object>, 'mse': <dival.measure.MSEMeasure object>, 'psnr': <dival.measure.PSNRMeasure object>, 'ssim': <dival.measure.SSIMMeasure object>}

Class attribute, registry of all measures with their short_name as key.

__init__(short_name=None)[source]
Parameters

short_name (str, optional) – The short name of this measure, used as identifier in measure_dict. If None is passed and short_name was not set by the subclass, the __name__ of the subclass is used. If short_name is already taken by another instance, a unique short name is generated by appending a suffix of format '_%d'.

short_name = ''

Class attribute, default value for short_name.

abstract apply(reconstruction, ground_truth)[source]

Calculate the value of this measure.

Parameters

  • reconstruction (odl element) – The reconstruction.

  • ground_truth (odl element) – The ground truth to compare with.

Returns

value – The value of this measure for the given reconstruction and ground_truth.

Return type

float

classmethod get_by_short_name(short_name)[source]

Return Measure instance with given short name by registry lookup.

Parameters

short_name (str) – Short name, identifier in measure_dict.

Returns

measure – The instance.

Return type

Measure

as_operator_for_fixed_ground_truth(ground_truth)[source]

Return an odl operator that can be applied to different reconstructions for fixed ground truth.

Returns

op – odl operator.

Return type

odl operator

class dival.TaskTable(name='')[source]

Bases: object

Task table containing reconstruction tasks to evaluate.

name

Name of the task table.

Type

str

tasks

Tasks that shall be run. The fields of each dict are set from the parameters to append() (or append_all_combinations()). Cf. documentation of append() for details.

Type

list of dict

results

Results from the latest call to run().

Type

ResultTable or None

__init__(name='')[source]

Initialize self. See help(type(self)) for accurate signature.

run(save_reconstructions=True, reuse_iterates=True, show_progress='text')[source]

Run all tasks and return the results.

The returned ResultTable object is also stored as results.

Parameters

  • save_reconstructions (bool, optional) –

    Whether the reconstructions should be saved in the results. The default is True.

    If measures shall be applied after this method returns, it must be True.

    If False, no iterates (intermediate reconstructions) will be saved, even if task['options']['save_iterates']==True.

  • reuse_iterates (bool, optional) –

    Whether to reuse iterates from other sub-tasks if possible. The default is True.

    If there are sub-tasks whose hyper parameter choices differ only in the number of iterations of an IterativeReconstructor, only the sub-task with the maximum number of iterations is run and the results for the other ones determined by storing iterates if this option is True.

    Note 1: If enabled, the callbacks assigned to the reconstructor will be run only for the above specified sub-tasks with the maximum number of iterations.

    Note 2: If the reconstructor is non-deterministic, this option can affect the results as the same realization is used for multiple sub-tasks.

  • show_progress (str, optional) –

    Whether and how to show progress. Options are:

    'text' (default)

    print a line before running each task

    'tqdm'

    show a progress bar with tqdm

    None

    do not show progress

Returns

results – The results.

Return type

ResultTable

append(reconstructor, test_data, measures=None, dataset=None, hyper_param_choices=None, options=None)[source]

Append a task.

Parameters

  • reconstructor (Reconstructor) – The reconstructor.

  • test_data (DataPairs) – The test data.

  • measures (sequence of (Measure or str), optional) – Measures that will be applied. Either Measure objects or their short names can be passed.

  • dataset (Dataset, optional) – The dataset that will be passed to reconstructor.train if it is a LearnedReconstructor.

  • hyper_param_choices (dict of list or list of dict, optional) –

    Choices of hyper parameter combinations to try as sub-tasks.

    • If a dict of lists is specified, all combinations of the list elements (cartesian product space) are tried.

    • If a list of dicts is specified, each dict is taken as a parameter combination to try.

    The current parameter values are read from Reconstructor.hyper_params in the beginning and used as default values for all parameters not specified in the passed dicts. Afterwards, the original values are restored.

  • options (dict) –

    Options that will be used. Options are:

    'skip_training'bool, optional

    Whether to skip training. Can be used for manual training of reconstructors (or loading of a stored state). Default: False.

    'save_best_reconstructor'dict, optional

    If specified, save the best reconstructor from the sub-tasks (cf. hyper_param_choices) by calling Reconstructor.save_params(). For hyper_param_choices=None, the reconstructor from the single sub-task is saved. This option requires measures to be non-empty if there are multiple sub-tasks. The fields are:

    'path'str

    The path to save the best reconstructor at (argument to save_params()). Note that this path is used during execution of the task to store the best reconstructor params so far, so the file(s) are most likely updated multiple times.

    'measure'Measure or str, optional

    The measure used to define the “best” reconstructor (in terms of mean performance). Must be one of the measures. By default measures[0] is used. This field is ignored if there is only one sub-task.

    'save_iterates'bool, optional

    Whether to save the intermediate reconstructions of iterative reconstructors. Default: False. Will be ignored if save_reconstructions=False is passed to run. If reuse_iterates=True is passed to run and there are sub-tasks for which iterates are reused, these iterates are the same objects for all of those sub-tasks (i.e. no copies).

    'save_iterates_measure_values'bool, optional

    Whether to compute and save the measure values for each intermediate reconstruction of iterative reconstructors (the default is False).

    'save_iterates_step'int, optional

    Step size for 'save_iterates' and 'save_iterates_measure_values' (the default is 1).

append_all_combinations(reconstructors, test_data, measures=None, datasets=None, hyper_param_choices=None, options=None)[source]

Append tasks of all combinations of test data, reconstructors and optionally datasets. The order is taken from the lists, with test data changing slowest and reconstructor changing fastest.

Parameters

  • reconstructors (list of Reconstructor) – Reconstructor list.

  • test_data (list of DataPairs) – Test data list.

  • measures (sequence of (Measure or str)) – Measures that will be applied. The same measures are used for all combinations of test data and reconstructors. Either Measure objects or their short names can be passed.

  • datasets (list of Dataset, optional) – Dataset list. Required if reconstructors contains at least one LearnedReconstructor.

  • hyper_param_choices (list of (dict of list or list of dict), optional) – Choices of hyper parameter combinations for each reconstructor, which are tried as sub-tasks. The i-th element of this list is used for the i-th reconstructor. See append for documentation of how the choices are passed.

  • options (dict) – Options that will be used. The same options are used for all combinations of test data and reconstructors. See append for documentation of the options.

class dival.StandardLearnedReconstructor(op, hyper_params=None, num_data_loader_workers=8, use_cuda=True, show_pbar=True, log_dir=None, log_num_validation_samples=0, save_best_learned_params_path=None, torch_manual_seed=1, shuffle='auto', worker_init_fn=None, **kwargs)[source]

Bases: dival.reconstructors.reconstructor.LearnedReconstructor

Standard learned reconstructor base class.

Provides a default implementation that only requires subclasses to implement init_model().

By default, the Adam optimizer is used. This can be changed by reimplementing init_optimizer(). Also, a OneCycleLR scheduler is used by default, which can be changed by reimplementing init_scheduler().

The training implementation selects the best model reached after an integer number of epochs based on the validation set.

The hyper parameter 'normalize_by_opnorm' selects whether op should be normalized by the operator norm. In this case, the inputs to model are divided by the operator norm.

model

The neural network. Must be initialized by the subclass init_model() implementation.

Type

torch.nn.Module or None

non_normed_op

The original op passed to __init__(), regardless of self.hyper_params['normalize_by_opnorm']. See also op.

Type

odl.operator.Operator

HYPER_PARAMS = {'batch_size': {'default': 64, 'retrain': True}, 'epochs': {'default': 20, 'retrain': True}, 'lr': {'default': 0.01, 'retrain': True}, 'normalize_by_opnorm': {'default': False, 'retrain': True}}
__init__(op, hyper_params=None, num_data_loader_workers=8, use_cuda=True, show_pbar=True, log_dir=None, log_num_validation_samples=0, save_best_learned_params_path=None, torch_manual_seed=1, shuffle='auto', worker_init_fn=None, **kwargs)[source]
Parameters

  • op (odl.operator.Operator) – Forward operator.

  • num_data_loader_workers (int, optional) – Number of parallel workers to use for loading data.

  • use_cuda (bool, optional) – Whether to use cuda for the U-Net.

  • show_pbar (bool, optional) – Whether to show tqdm progress bars during the epochs.

  • log_dir (str, optional) – Tensorboard log directory (name of sub-directory in utils/logs). If None, no logs are written.

  • log_num_valiation_samples (int, optional) – Number of validation images to store in tensorboard logs. This option only takes effect if log_dir is not None.

  • save_best_learned_params_path (str, optional) – Save best model weights during training under the specified path by calling save_learned_params().

  • torch_manual_seed (int, optional) – Fixed seed to set by torch.manual_seed before training. The default is 1. It can be set to None or False to disable the manual seed.

  • shuffle ({'auto', False, True}, optional) – Whether to use shuffling when loading data. When 'auto' is specified (the default), True is used iff the dataset passed to train() supports random access.

  • worker_init_fn (callable, optional) – Callable worker_init_fn passed to torch.utils.data.DataLoader.__init__(), which can be used to configure the dataset copies for different worker instances (cf. torch’s IterableDataset docs)

property opnorm
property op

odl.operator.Operator: The forward operator, normalized if self.hyper_params['normalize_by_opnorm'] is True.

eval(test_data)[source]
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.

init_transform(dataset)[source]

Initialize the transform (_transform) that is applied on each training sample, e.g. for data augmentation. In the default implementation of train(), it is passed to Dataset.create_torch_dataset() when creating the training (but not the validation) torch dataset, which applies the transform to the (tuple of) torch tensor(s) right before returning, i.e. after reshaping to (1,) + orig_shape.

The default implementation of this method disables the transform by assigning None. Called in train() at the beginning, i.e. before calling init_model(), init_optimizer() and init_scheduler().

Parameters

dataset (dival.datasets.dataset.Dataset) – The dival dataset passed to train().

property transform

callable: Transform that is applied on each sample, usually set by init_transform(), which gets called in train().

init_model()[source]

Initialize model. Called in train() after calling init_transform(), but before calling init_optimizer() and init_scheduler().

init_optimizer(dataset_train)[source]

Initialize the optimizer. Called in train(), after calling init_transform() and init_model(), but before calling init_scheduler().

Parameters

dataset_train (torch.utils.data.Dataset) – The training (torch) dataset constructed in train().

property optimizer

torch.optim.Optimizer: The optimizer, usually set by init_optimizer(), which gets called in train().

init_scheduler(dataset_train)[source]

Initialize the learning rate scheduler. Called in train(), after calling init_transform(), init_model() and init_optimizer().

Parameters

dataset_train (torch.utils.data.Dataset) – The training (torch) dataset constructed in train().

property scheduler

torch learning rate scheduler: The scheduler, usually set by init_scheduler(), which gets called in train().

property batch_size
property epochs
property lr
property normalize_by_opnorm
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, convert_data_parallel='auto')[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.

  • convert_data_parallel (bool or {'auto', 'keep'}, optional) –

    Whether to automatically convert the model weight names if model is a nn.DataParallel-model but the stored state dict stems from a non-data-parallel model, or vice versa.

    'auto' or True:

    Auto-convert weight names, depending on the type of model.

    'keep' or False:

    Do not convert weight names. Convert to plain weight names.