2.1.1.1.1.6. emicroml.modelling.cbed.distortion.estimation.ml_data_dict_to_signals

ml_data_dict_to_signals(ml_data_dict, sampling_grid_dims_in_pixels=(512, 512), device_name=None, least_squares_alg_params=None)

Convert a dictionary representation of ML data instances to a sequence of Hyperspy signals.

See the documentation for the classes fakecbed.discretized.CBEDPattern, distoptica.DistortionModel, and hyperspy._signals.signal2d.Signal2D for discussions on “fake” CBED patterns, distortion models, and Hyperspy signals respectively.

The current function converts a dictionary representation ml_data_dict of complete or incomplete machine learning (ML) data instances to a sequence of Hyperspy signals. If incomplete, the ML data instances can, at the very least be used to evaluate ML models represented by the class emicroml.modelling.cbed.distortion.estimation.MLModel, and if complete, the ML data instances can be used to train such ML models as well.

Each dict key in ml_data_dict is the name of a feature of the ML data instances. The only required dict key is "cbed_pattern_images". If additional valid dict items are present in ml_data_dict, then more data and metadata can be stored potentially in the Hyperspy representations of the ML data instances. A complete dictionary representation is identical in structure to a dictionary returned by the method emicroml.modelling.cbed.distortion.estimation.MLDataset.get_ml_data_instances() of the class emicroml.modelling.cbed.distortion.estimation.MLDataset. See the documentation for said method for more details. An incomplete dictionary representation is identical in structure to a complete dictionary representation, except that at least one dict item is missing.

For each ML data instance, an instance distortion_model of the class distoptica.DistortionModel is constructed according to the ML data instance’s features. The object distortion_model is a distortion model that describes the distortion field of the imaged CBED pattern of the ML data instance. If no distortion information is present in ml_data_dict, then distortion_model.is_trivial yields True, i.e. the distortion model is assumed to be trivial. After constructing distortion_model, an instance of the class fakecbed.discretized.CBEDPattern is constructed according to the ML data instance’s features and distortion_model. fake_cbed_pattern is a fake CBED pattern representation of the CBED pattern of the ML data instance. Next, a Hyperspy signal fake_cbed_pattern_signal is obtained from fake_cbed_pattern.signal. The Hyperspy signal representation of the ML data instance is obtained by modifying in place fake_cbed_pattern_signal.data[1:3] according to the ML data instance’s features. Note that the illumination support of the fake CBED pattern representation of the CBED pattern of the ML data instance is inferred from the features of the ML data instance, and is stored in fake_cbed_pattern_signal.data[1]. Moreover, the illumination suport implied by the signal’s metadata should be ignored.

Parameters:

ml_data_dictdict

The dictionary representation of the ML data instances to be converted. The current function assumes that all normalizable features of the ML data instances are unnormalized. If the normalizable features of the ML data instances are not normalized, they can be unnormalized using the function emicroml.modelling.cbed.distortion.estimation.unnormalize_normalizable_elems_in_ml_data_dict() prior to using the current function.

sampling_grid_dims_in_pixelsarray_like (int, shape=(2,)), optional

The dimensions of the sampling grid, in units of pixels, used for all distortion models.

least_squares_alg_paramsdistoptica.LeastSquaresAlgParams | None, optional

least_squares_alg_params specifies the parameters of the least-squares algorithm to be used to calculate the mappings of fractional Cartesian coordinates of distorted images to those of the corresponding undistorted images. least_squares_alg_params is used to calculate the interim distortion models mentioned above in the summary documentation. If least_squares_alg_params is set to None, then the parameter will be reassigned to the value distoptica.LeastSquaresAlgParams(). See the documentation for the class distoptica.LeastSquaresAlgParams for details on the parameters of the least-squares algorithm.

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.

Returns:

signalsarray_like (hyperspy._signals.signal2d.Signal2D, ndim=1)

The ML data instances, represented as a sequence of Hyperspy signals, where each Hyperspy signal represents a ML data instance.