2.1.1.1.1.16. emicroml.modelling.cbed.distortion.estimation.MLModelTrainer

class MLModelTrainer(ml_dataset_manager, device_name=None, lr_scheduler_manager=None, checkpoints=None, output_dirname='results', misc_model_training_metadata={}, skip_validation_and_conversion=False)

Bases: _MLModelTrainer

A machine learning model trainer.

The current class is a subclass of fancytypes.PreSerializableAndUpdatable.

The current class represents a machine learning (ML) model trainer that can be used to train via supervised learning ML models represented by the class emicroml.modelling.cbed.distortion.estimation.MLModel.

As discussed in the documentation of the class emicroml.modelling.cbed.distortion.estimation.MLModel, a given ML model represented by said class takes as input a mini-batch of images, where each image is assumed to depict a distorted CBED pattern, and as output, the ML model predicts sets of coordinate transformation parameters that specify the coordinate transformations that describe the distortions of the input images. The coordinate transformation used to describe the distortions of an image is defined in the documentation for the class distoptica.StandardCoordTransformParams. The parameter set parameterizing said coordinate transformation is referred to as the “standard” coordinate transformation parameter set, and is represented by the class distoptica.StandardCoordTransformParams. Similarly, we refer to distortions fields that are specified by standard coordinate transformation parameters sets as standard distortion fields.

Consider an abstract undistorted CBED intensity pattern of non-overlapping CBED disks that share a common radius, and that outside the CBED disk supports the intensity is zero, and inside each CBED disk support the intensity is a common positive value. Next, consider an abstract distorted CBED intensity pattern obtained by distorting the abstract undistorted CBED intensity pattern according to a standard coordinate transformation. Under special circumstances, the abstract distorted CBED intensity pattern will not be perfectly correlated with the standard distortion field corresponding to the standard coordinate transformation. However, the abstract distorted CBED intensity pattern should be perfectly correlated with a vector field obtained by subtracting the original standard distortion field by its mean. We refer to the mean of the original standard distortion field as the “adjustment” vector.

Mathematically, the loss associated with a given predicted mini-batch of standard coordinate transformation parameter sets, during either training or validation, is calculated effectively as follows:

1. Let mini_batch_size be the mini-batch size.

2. Index the predicted coordinate transformations from 0 to mini_batch_size-1.

3. Set losses_of_ml_data_instances to a floating-point array of shape (mini_batch_size,).

4. Set n to -1.

5. Set n to n+1.

6. Set sampling_grid_dims_in_pixels to shape of n th input image.

7. Use the n th predicted standard coordinate transformation parameter set to construct an instance predicted_standard_coord_transform_params of the class distoptica.StandardCoordTransformParams.

8. Generate an instance predicted_distortion_model of the class distoptica.DistortionModel by calculating:

import distoptica

kwargs = \
    {"standard_coord_transform_params": \
     predicted_standard_coord_transform_params,
     "sampling_grid_dims_in_pixels": \
     sampling_grid_dims_in_pixels}
predicted_distortion_model = \
    distoptica.generate_standard_distortion_model(**kwargs)

9. Sample the flow field of the n th predicted standard coordinate transformation on a uniform grid by calculating predicted_distortion_model.flow_field_of_coord_transform, then store the result in predicted_flow_field.

10. Add to the sampled flow field from the previous step the adjustment vector, then store the result in predicted_adjusted_flow_field.

11. Calculate the ground truth corresponding to the predicted sampled adjusted flow field from the previous step, then store the result in target_adjusted_flow_field.

12. Calculate the end-point error (EPE) of the predicted adjusted flow field stored in predicted_adjusted_flow_field, using the ground truth stored in target_adjusted_flow_field, then store the result in epe_of_distortion_field.

13. Store epe_of_distortion_field in losses_of_ml_data_instances[n].

14. If n < mini_batch_size-1, then go to instruction 5. Otherwise, go to instruction 15.

15. Set mini_batch_loss to the average of the elements stored in losses_of_ml_data_instances.

16. Stop.

The number mini_batch_loss is the loss associated with the given predicted mini-batch of standard coordinate transformation parameter sets.

Note that the steps 6-12 describe the calculation of an EPE. Specifically, we refer to the resulting quantity as the EPE of an adjusted standard distortion field specified by a predicted standard coordinate transformation. We adopt this language elsewhere in the documentation of this module.

The above set of instructions made reference to a few objects from the distoptica library. See the documentation for said library for further details.

Parameters:

ml_dataset_manageremicroml.modelling.cbed.distortion.estimation.MLDatasetManager

The ML dataset manager to use during ML model training. The ML dataset manager must specify at least a ML training dataset.

If a ML validation dataset is specified, then mini-batch losses are calculated during the validation phase in addition to the training phase. Otherwise, mini-batch losses are not calculated during the validation phase.

Any ML testing dataset specified is ignored.

device_namestr | None, optional

This parameter specifies the device to be used to perform computationally intensive calls to PyTorch functions and to store intermediate arrays of the type torch.Tensor. If device_name is a string, then it is the name of the device to be used, e.g. ”cuda” or ”cpu”. If device_name is set to None and a GPU device is available, then a GPU device is to be used. Otherwise, the CPU is used.

lr_scheduler_manageremicroml.modelling.lr.LRSchedulerManager | None, optional

This parameter specifies the learning rate scheduler manager to use during ML model training. If lr_scheduler_manager is set to an instance of the class emicroml.modelling.lr.LRSchedulerManager, then the learning rate scheduler manager is represented by the object lr_scheduler_manager. Otherwise, if set to None, then the parameter lr_scheduler_manager will be reassigned to the value of emicroml.modelling.lr.LRSchedulerManager(). See the documentation for the class emicroml.modelling.lr.LRSchedulerManager for a discussion on learning rate scheduler managers. Among other things, lr_scheduler_manager specifies whether the global learning rate multiplier of each learning rate scheduler is updated in the training or validation phase of each training-validation cycle, except the last.

checkpointsarray_like (int, ndim=1) | None, optional

This parameter specifies after which global optimization steps are the real-time dictionary representations of the ML model to be trained saved to output files. By global optimization step, we mean a single update applied to each fitting parameter of the ML model that is subject to updates during optimization. We refer to the moments when dictionary representations are saved as “checkpoints”.

If checkpoints is not set to None, then it must be either an empty sequence, or a sequence of nonnegative integers.

If checkpoints is set to None, then only the final dictionary representation of the ML model is to be saved. Else if checkpoints is set to an empty sequence, then no dictionary representations of the ML model are to be saved. Else if checkpoints is set to a nonempty sequence of nonnegative integers, and the global learning rate multipliers are updated during the training phase of each training-validation cycle except the last, then for every nonnegative integer n less than len(checkpoints), checkpoints[n] specifies that the real-time dictionary representation of the ML model immediately after checkpoints[n]+1 global optimization steps is to be saved as long as said number of global optimization steps are to be performed. Otherwise, if checkpoints is set to a nonempty sequence of nonnegative integers, and the global learning rate multipliers are updated during the validation phase of each training-validation cycle except the last, then for every nonnegative integer n less than len(checkpoints), checkpoints[n] specifies that the real-time dictionary representation of the ML model immediately after checkpoints[n]+1 training epochs is to be saved as long as said number of training epochs are to occur.

Note that if checkpoints is set to None, then the parameter is reassigned to (lr_scheduler_manager.total_num_steps,) after all other parameter reassignments.

output_dirnamestr, optional

The relative or absolute path to the directory in which all output files are saved.

misc_model_training_metadatadict, optional

Miscellaneous ML model training metadata. Can be any dict object that is serializable, i.e. import json; json.dumps(misc_model_training_metadata) must not raise an exception. Note that misc_model_training_metadata is not used to train ML models, but is serialized and saved as output. See the documentation for the method emicroml.modelling.cbed.distortion.estimation.MLModelTrainer.train_ml_model(), for details on how misc_model_training_metadata is saved as output.

skip_validation_and_conversionbool, optional

Let validation_and_conversion_funcs and core_attrs denote the attributes validation_and_conversion_funcs and core_attrs respectively, both of which being dict objects.

Let params_to_be_mapped_to_core_attrs denote the dict representation of the constructor parameters excluding the parameter skip_validation_and_conversion, where each dict key key is a different constructor parameter name, excluding the name "skip_validation_and_conversion", and params_to_be_mapped_to_core_attrs[key] would yield the value of the constructor parameter with the name given by key.

If skip_validation_and_conversion is set to False, then for each key key in params_to_be_mapped_to_core_attrs, core_attrs[key] is set to validation_and_conversion_funcs[key] (params_to_be_mapped_to_core_attrs).

Otherwise, if skip_validation_and_conversion is set to True, then core_attrs is set to params_to_be_mapped_to_core_attrs.copy(). This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of params_to_be_mapped_to_core_attrs, as it is guaranteed that no copies or conversions are made in this case.

Attributes:

core_attrs

dict: The “core attributes”.

de_pre_serialization_funcs

dict: The de-pre-serialization functions.

pre_serialization_funcs

dict: The pre-serialization functions.

validation_and_conversion_funcs

dict: The validation and conversion functions.

Methods

de_pre_serialize([serializable_rep, ...])	Construct an instance from a serializable representation.
dump([filename, overwrite])	Serialize instance and save the result in a JSON file.
dumps()	Serialize instance.
get_core_attrs([deep_copy])	Return the core attributes.
get_de_pre_serialization_funcs()	Return the de-pre-serialization functions.
get_pre_serialization_funcs()	Return the pre-serialization functions.
get_validation_and_conversion_funcs()	Return the validation and conversion functions.
load([filename, skip_validation_and_conversion])	Construct an instance from a serialized representation that is stored in a JSON file.
loads([serialized_rep, ...])	Construct an instance from a serialized representation.
pre_serialize()	Pre-serialize instance.
train_ml_model(ml_model, ml_model_param_groups)	Train a machine learning model.
update(new_core_attr_subset_candidate[, ...])	Update a subset of the core attributes.

execute_post_core_attrs_update_actions

Methods

de_pre_serialize	Construct an instance from a serializable representation.
dump	Serialize instance and save the result in a JSON file.
dumps	Serialize instance.
execute_post_core_attrs_update_actions
get_core_attrs	Return the core attributes.
get_de_pre_serialization_funcs	Return the de-pre-serialization functions.
get_pre_serialization_funcs	Return the pre-serialization functions.
get_validation_and_conversion_funcs	Return the validation and conversion functions.
load	Construct an instance from a serialized representation that is stored in a JSON file.
loads	Construct an instance from a serialized representation.
pre_serialize	Pre-serialize instance.
train_ml_model	Train a machine learning model.
update	Update a subset of the core attributes.

Attributes

core_attrs	dict: The "core attributes".
de_pre_serialization_funcs	dict: The de-pre-serialization functions.
pre_serialization_funcs	dict: The pre-serialization functions.
validation_and_conversion_funcs	dict: The validation and conversion functions.

property core_attrs

dict: The “core attributes”.

The keys of core_attrs are the same as the attribute validation_and_conversion_funcs, which is also a dict object.

Note that core_attrs should be considered read-only.

property de_pre_serialization_funcs

dict: The de-pre-serialization functions.

de_pre_serialization_funcs has the same keys as the attribute validation_and_conversion_funcs, which is also a dict object.

Let validation_and_conversion_funcs and pre_serialization_funcs denote the attributes validation_and_conversion_funcs pre_serialization_funcs respectively, the last of which being a dict object as well.

Let core_attrs_candidate_1 be any dict object that has the same keys as validation_and_conversion_funcs, where for each dict key key in core_attrs_candidate_1, validation_and_conversion_funcs[key](core_attrs_candidate_1) does not raise an exception.

Let serializable_rep be a dict object that has the same keys as core_attrs_candidate_1, where for each dict key key in core_attrs_candidate_1, serializable_rep[key] is set to pre_serialization_funcs[key](core_attrs_candidate_1[key]).

The items of de_pre_serialization_funcs are expected to be set to callable objects that would lead to de_pre_serialization_funcs[key](serializable_rep[key]) not raising an exception for each dict key key in serializable_rep.

Let core_attrs_candidate_2 be a dict object that has the same keys as serializable_rep, where for each dict key key in validation_and_conversion_funcs, core_attrs_candidate_2[key] is set to de_pre_serialization_funcs[key](serializable_rep[key]).

The items of de_pre_serialization_funcs are also expected to be set to callable objects that would lead to validation_and_conversion_funcs[key](core_attrs_candidate_2) not raising an exception for each dict key key in core_attrs_candidate_2.

Note that de_pre_serialization_funcs should be considered read-only.

classmethod de_pre_serialize(serializable_rep={}, skip_validation_and_conversion=False)

Construct an instance from a serializable representation.

Parameters:

serializable_repdict, optional

A dict object that has the same keys as the attribute validation_and_conversion_funcs, which is also a dict object.

Let validation_and_conversion_funcs and de_pre_serialization_funcs denote the attributes validation_and_conversion_funcs de_pre_serialization_funcs respectively, the last of which being a dict object as well.

The items of serializable_rep are expected to be objects that would lead to de_pre_serialization_funcs[key](serializable_rep[key]) not raising an exception for each dict key key in serializable_rep.

Let core_attrs_candidate be a dict object that has the same keys as serializable_rep, where for each dict key key in serializable_rep, core_attrs_candidate[key] is set to de_pre_serialization_funcs[key](serializable_rep[key])``.

The items of serializable_rep are also expected to be set to objects that would lead to validation_and_conversion_funcs[key](core_attrs_candidate) not raising an exception for each dict key key in serializable_rep.

skip_validation_and_conversionbool, optional

Let core_attrs denote the attribute core_attrs, which is a dict object.

If skip_validation_and_conversion is set to False, then for each key key in serializable_rep, core_attrs[key] is set to validation_and_conversion_funcs[key] (core_attrs_candidate), with validation_and_conversion_funcs and core_attrs_candidate_1 being introduced in the above description of serializable_rep.

Otherwise, if skip_validation_and_conversion is set to True, then core_attrs is set to core_attrs_candidate.copy(). This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of core_attrs_candidate, as it is guaranteed that no copies or conversions are made in this case.

Returns:

instance_of_current_clsCurrent class

An instance constructed from the serializable representation serializable_rep.

dump(filename='serialized_rep_of_fancytype.json', overwrite=False)

Serialize instance and save the result in a JSON file.

Parameters:

filenamestr, optional

The relative or absolute path to the JSON file in which to store the serialized representation of an instance.

overwritebool, optional

If overwrite is set to False and a file exists at the path filename, then the serialized instance is not written to that file and an exception is raised. Otherwise, the serialized instance will be written to that file barring no other issues occur.

Returns:

dumps()

Serialize instance.

Returns:

serialized_repdict

A serialized representation of an instance.

get_core_attrs(deep_copy=True)

Return the core attributes.

Parameters:

deep_copybool, optional

Let core_attrs denote the attribute core_attrs, which is a dict object.

If deep_copy is set to True, then a deep copy of core_attrs is returned. Otherwise, a shallow copy of core_attrs is returned.

Returns:

core_attrsdict

The attribute core_attrs.

classmethod get_de_pre_serialization_funcs()

Return the de-pre-serialization functions.

Returns:

de_pre_serialization_funcsdict

The attribute de_pre_serialization_funcs.

classmethod get_pre_serialization_funcs()

Return the pre-serialization functions.

Returns:

pre_serialization_funcsdict

The attribute pre_serialization_funcs.

classmethod get_validation_and_conversion_funcs()

Return the validation and conversion functions.

Returns:

validation_and_conversion_funcsdict

The attribute validation_and_conversion_funcs.

classmethod load(filename='serialized_rep_of_fancytype.json', skip_validation_and_conversion=False)

Construct an instance from a serialized representation that is stored in a JSON file.

Users can save serialized representations to JSON files using the method fancytypes.PreSerializable.dump().

Parameters:

filenamestr, optional

The relative or absolute path to the JSON file that is storing the serialized representation of an instance.

filename is expected to be such that json.load(open(filename, "r")) does not raise an exception.

Let serializable_rep=json.load(open(filename, "r")).

Let validation_and_conversion_funcs and de_pre_serialization_funcs denote the attributes validation_and_conversion_funcs de_pre_serialization_funcs respectively, both of which being dict objects as well.

filename is also expected to be such that de_pre_serialization_funcs[key](serializable_rep[key]) does not raise an exception for each dict key key in de_pre_serialization_funcs.

Let core_attrs_candidate be a dict object that has the same keys as de_pre_serialization_funcs, where for each dict key key in serializable_rep, core_attrs_candidate[key] is set to de_pre_serialization_funcs[key](serializable_rep[key])``.

filename is also expected to be such that validation_and_conversion_funcs[key](core_attrs_candidate) does not raise an exception for each dict key key in serializable_rep.

skip_validation_and_conversionbool, optional

Let core_attrs denote the attribute core_attrs, which is a dict object.

Let core_attrs_candidate be as defined in the above description of filename.

If skip_validation_and_conversion is set to False, then for each key key in core_attrs_candidate, core_attrs[key] is set to validation_and_conversion_funcs[key] (core_attrs_candidate), , with validation_and_conversion_funcs and core_attrs_candidate being introduced in the above description of filename.

Otherwise, if skip_validation_and_conversion is set to True, then core_attrs is set to core_attrs_candidate.copy(). This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of core_attrs_candidate, as it is guaranteed that no copies or conversions are made in this case.

Returns:

instance_of_current_clsCurrent class

An instance constructed from the serialized representation stored in the JSON file.

classmethod loads(serialized_rep='{}', skip_validation_and_conversion=False)

Construct an instance from a serialized representation.

Users can generate serialized representations using the method dumps().

Parameters:

serialized_repstr | bytes | bytearray, optional

The serialized representation.

serialized_rep is expected to be such that json.loads(serialized_rep) does not raise an exception.

Let serializable_rep=json.loads(serialized_rep).

Let validation_and_conversion_funcs and de_pre_serialization_funcs denote the attributes validation_and_conversion_funcs de_pre_serialization_funcs respectively, both of which being dict objects as well.

serialized_rep is also expected to be such that de_pre_serialization_funcs[key](serializable_rep[key]) does not raise an exception for each dict key key in de_pre_serialization_funcs.

Let core_attrs_candidate be a dict object that has the same keys as serializable_rep, where for each dict key key in de_pre_serialization_funcs, core_attrs_candidate[key] is set to de_pre_serialization_funcs[key](serializable_rep[key])``.

serialized_rep is also expected to be such that validation_and_conversion_funcs[key](core_attrs_candidate) does not raise an exception for each dict key key in serializable_rep.

skip_validation_and_conversionbool, optional

Let core_attrs denote the attribute core_attrs, which is a dict object.

If skip_validation_and_conversion is set to False, then for each key key in core_attrs_candidate, core_attrs[key] is set to validation_and_conversion_funcs[key] (core_attrs_candidate), with validation_and_conversion_funcs and core_attrs_candidate_1 being introduced in the above description of serialized_rep.

Otherwise, if skip_validation_and_conversion is set to True, then core_attrs is set to core_attrs_candidate.copy(). This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of core_attrs_candidate, as it is guaranteed that no copies or conversions are made in this case.

Returns:

instance_of_current_clsCurrent class

An instance constructed from the serialized representation.

property pre_serialization_funcs

dict: The pre-serialization functions.

pre_serialization_funcs has the same keys as the attribute validation_and_conversion_funcs, which is also a dict object.

Let validation_and_conversion_funcs and core_attrs denote the attributes validation_and_conversion_funcs and core_attrs respectively, the last of which being a dict object as well.

For each dict key key in core_attrs, pre_serialization_funcs[key](core_attrs[key]) is expected to yield a serializable object, i.e. it should yield an object that can be passed into the function json.dumps without raising an exception.

Note that pre_serialization_funcs should be considered read-only.

pre_serialize()

Pre-serialize instance.

Returns:

serializable_repdict

A serializable representation of an instance.

train_ml_model(ml_model, ml_model_param_groups)

Train a machine learning model.

See the summary documentation of the class emicroml.modelling.cbed.distortion.estimation.MLModelTrainer for additional context.

Let core_attrs be the attribute core_attrs, lr_scheduler_manager be core_attrs["lr_scheduler_manager"], lr_schedulers be lr_scheduler_manager.core_attrs["lr_schedulers"], num_lr_schedulers be len(lr_schedulers), let checkpoints be core_attrs["checkpoints"], output_dirname be core_attrs["output_dirname"], and misc_model_training_metadata be core_attrs["misc_model_training_metadata"].

As discussed in the summary documentation of the current class, namely in the description of the core attribute checkpoints, real-time dictionary representations of the machine learning (ML) model to be trained can be saved to output files at different moments during training called “checkpoints”. For each nonnegative integer n less than len(checkpoints), the real-time dictionary representation of the ML model at the n th checkpoint is saved to a file at the file path output_dirname+"/ml_model_at_lr_step_{}.pth".format(checkpoints[n]). To load/reconstruct a ML model from a dictionary representation stored in a file, users can use the function emicroml.modelling.cbed.distortion.estimation.load_ml_model_from_file().

The only other output file that is generated by the end of the ML model training is the ML model training summary output data file, which is an HDF5 file generated at the file path output_dirname+"/ml_model_training_summary_output_data.h5". The HDF5 file is guaranteed to contain the following HDF5 objects:

• ml_model_trainer_params: <HDF5 1D dataset>

• num_training_mini_batches_per_epoch: <HDF5 0D dataset>

• num_validation_mini_batches_per_epoch: <HDF5 0D dataset>

• lr_schedules: <HDF5 group>

  • lr_schedule_0: <HDF5 1D dataset>

    • dim_0: “training mini batch instance idx” | “epoch”

• ml_data_instance_metrics: <HDF5 group>

  • training: <HDF5 group>

    • epes_of_adjusted_distortion_fields <HDF5 1D dataset>

      • dim_0: “ml training data instance idx”

• mini_batch_losses: <HDF5 group>

  • training: <HDF5 group>

    • total <HDF5 1D dataset>

      • dim_0: “training mini batch instance idx”

Note that the sub-bullet points listed immediately below a given HDF5 dataset display the HDF5 attributes associated with said HDF5 dataset. Some HDF5 datasets have attributes with names of the form "dim_{}".format(i) with i being an integer. Attribute "dim_{}".format(i) of a given HDF5 dataset labels the i th dimension of the underlying array of the dataset.

The HDF5 dataset at the HDF5 path "/ml_model_trainer_params" stores a serialized version of the attribute core_attrs, which is essentially the construction parameters used to construct an instance of the current class. From the output HDF5 file, users can reconstruct the instance of the current class that generated said output file by:

import h5pywrappers
import emicroml.modelling.cbed.distortion.estimation

filename = (output_dirname 
            +"/ml_model_training_summary_output_data.h5")

kwargs = {"filename": filename,
         "path_in_file": "ml_model_trainer_params"}
json_document_id = h5pywrappers.obj.ID(**kwargs)

serializable_rep = h5pywrappers.json.document.load(json_document_id)

MLModelTrainer = \
    emicroml.modelling.cbed.distortion.estimation.MLModelTrainer
ml_model_trainer = \
    MLModelTrainer.de_pre_serialize(serializable_rep)

where ml_model_trainer is the reconstructed instance of the current class, and serializable_rep is a “pre-serialized” version of it. See the documentation for the class fancytypes.PreSerializable for a discussion on pre-serialization.

The zero-dimensional HDF5 dataset, i.e. scalar, at the HDF5 path "/num_training_mini_batches_per_epoch" stores the number of training mini-batches per epoch.

The zero-dimensional HDF5 dataset, i.e. scalar, at the HDF5 path "/num_validation_mini_batches_per_epoch" stores the number of validation mini-batches per epoch.

The HDF5 dataset at the HDF5 path "/lr_schedules/lr_schedule_0" stores the learning rate schedule according to which the 0 th subset of the ML model fitting parameters are optimized. Note that the subsets of ML model fitting parameters that are to be updated during training are specified by the parameter ml_model_param_groups.

ml_model_param_groups must satisfy len(ml_model_param_groups) == num_lr_schedulers. Furthermore, for every nonnegative integer n less than num_lr_schedulers, import torch; torch.optim.AdamW(ml_model_param_groups[n]) must not raise an exception.

For every nonnegative integer n less than num_lr_schedulers, ml_model_param_groups[n] is the subset of the ML model fitting parameters that are optimized according to the learning rate schedule specified by lr_schedulers[n].

The HDF5 attribute "dim_0" of the HDF5 dataset at the HDF5 path "/lr_schedules/lr_schedule_0" is equal to "training mini batch instance idx" if the global learning rate multiplier of the 0 th learning rate scheduler is updated in the training phase of each training-validation cycle except the last. Otherwise, said HDF5 attribute is equal to "epoch".

More generally, for every nonnegative integer n less than num_lr_schedulers, there is an HDF5 dataset at the HDF5 path "/lr_schedules/lr_schedule_{}".format(n) that stores the learning rate schedule according to which the n th subset of the ML model fitting parameters are optimized. Moreover, for every nonnegative integer m less than the number of elements in the HDF5 dataset at the HDF5 path "/lr_schedules/lr_schedule_{}".format(n), the m th data element of that HDF5 dataset is the value of the global learning rate multiplier of the n th learning schedule after m steps in said schedule. Note that all HDF5 datasets in the group at the HDF5 path "/lr_schedules" share the same HDF5 attribute in name and value, i.e. the attribute "dim_0".

The HDF5 group at the HDF5 path "/ml_data_instance_metrics" stores the performance metrics that are tracked during training.

The HDF5 dataset at the HDF5 path "/ml_data_instance_metrics/training/epes_of_adjusted_distortion_fields" stores the end-point errors (EPEs) of the “adjusted” standard distortion fields specified by the predicted standard coordinate transformation parameter sets, during training. For every nonnegative integer m less than the the total number of ML training data instances, the m th element of the aforementioned HDF5 dataset is the EPE of the adjusted standard distortion field specified by the m th predicted standard standard coordinate transformation set, during training. See the summary documentation of the class emicroml.modelling.cbed.distortion.estimation.MLModelTrainer for a definition of an adjusted standard distortion field, and how the EPE is calculated exactly.

If performance metrics are also calculated during validation, then the output HDF5 file will also include an additional HDF5 dataset, located at the HDF5 path "/ml_data_instance_metrics/validation/epes_of_adjusted_distortion_fields". One can simply replace every instance of the word “training” with “validation” in the previous paragraph to yield a description of the HDF5 dataset stored in HDF5 group at the HDF5 path "/ml_data_instance_metrics/validation".

The HDF5 group at the HDF5 path "/mini_batch_losses" stores the mini-batch losses that are tracked during training, which are used to optimize the ML model.

The HDF5 dataset at the HDF5 path "/mini_batch_losses/training/total" stores the mini-btach losses associated with the EPEs of the adjusted standard distortion fields specified by the predicted standard coordinate transformation parameter sets, during training. For every nonnegative integer m less than the total number of training mini-batches, the m th element of the aforementioned HDF5 dataset is the mean of the EPEs of the adjusted standard distortion fields specified by the m th predicted mini-batch of standard coordinate transformation sets, during training.

If mini-batch losses are also calculated during validation, then the output HDF5 file will also include an additional HDF5 dataset, located at the HDF5 path "/mini_batch_losses/validation/total". One can simply replace every instance of the word “training” with “validation” in the previous paragraph to yield a description of the HDF5 dataset stored in HDF5 group at the HDF5 path "/mini_batch_losses/validation".

For further discussion on how losses are calculated, see the summary documentation of the class emicroml.modelling.cbed.distortion.estimation.MLModelTrainer.

Parameters:

ml_modelemicroml.modelling.cbed.distortion.estimation.MLModel

The ML model to train.

ml_model_param_groupsarray_like

The ML model fitting parameter groups.

update(new_core_attr_subset_candidate, skip_validation_and_conversion=False)

Update a subset of the core attributes.

Parameters:

new_core_attr_subset_candidatedict, optional

A dict object.

skip_validation_and_conversionbool, optional

Let validation_and_conversion_funcs and core_attrs denote the attributes validation_and_conversion_funcs and core_attrs respectively, both of which being dict objects.

If skip_validation_and_conversion is set to False, then for each key key in core_attrs that is also in new_core_attr_subset_candidate, core_attrs[key] is set to validation_and_conversion_funcs[key] (new_core_attr_subset_candidate).

Otherwise, if skip_validation_and_conversion is set to True, then for each key key in core_attrs that is also in new_core_attr_subset_candidate, core_attrs[key] is set to new_core_attr_subset_candidate[key]. This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of new_core_attr_subset_candidate, as it is guaranteed that no copies or conversions are made in this case.

property validation_and_conversion_funcs

dict: The validation and conversion functions.

The keys of validation_and_conversion_funcs are the names of the constructor parameters, excluding skip_validation_and_conversion if it exists as a construction parameter.

Let core_attrs denote the attribute core_attrs, which is also a dict object.

For each dict key key in core_attrs, validation_and_conversion_funcs[key](core_attrs) is expected to not raise an exception.

Note that validation_and_conversion_funcs should be considered read-only.