Datasets

Base Dataset

class PyLorentz.dataset.base_dataset.BaseDataset(imshape=None, data_dir=None, scale=None, verbose=1)[source]

Bases: object

A base class for handling datasets, providing common attributes and methods.

__init__(imshape=None, data_dir=None, scale=None, verbose=1)[source]

Initialize the BaseDataset object.

Parameters:

  • imshape (tuple | np.ndarray | None, optional) – Shape of the image. Default is None.

  • data_dir (os.PathLike | None, optional) – Directory for data storage. Default is None.

  • scale (float | None, optional) – Scale factor for the dataset. Default is None.

  • verbose (int | bool, optional) – Verbosity level. Default is 1.

property shape: tuple[int, int]

overwritten by higher level classes get the shape of the image (y,x).

property orig_shape2D: tuple[int, int]

Get the original (uncropped/rotated/etc.) 2D shape of the image(s) (y,x).

property data_dir

Get the data directory.

property scale: float

Get the scale factor.

property transforms

Get the transformation parameters.

vprint(*args, **kwargs)[source]

Print messages if verbose is enabled.

property fov

Get the field of view.

Defocused Dataset

class PyLorentz.dataset.defocused_dataset.DefocusedDataset(images, scale=None, defvals=None, beam_energy=None, data_files=[], simulated=False, verbose=1)[source]

Bases: BaseDataset

A dataset class for handling defocused images and related metadata.

Parameters:

  • images (np.ndarray) – The set of defocused images.

  • scale (Optional[float]) – The scale of the images.

  • defvals (Optional[np.ndarray]) – The defocus values corresponding to the images.

  • beam_energy (Optional[float]) – The beam energy used during imaging.

  • data_files (List[os.PathLike]) – File paths of the data files.

  • simulated (bool) – Indicates if the data is simulated.

  • verbose (Union[int, bool]) – Verbosity level for logging.

__init__(images, scale=None, defvals=None, beam_energy=None, data_files=[], simulated=False, verbose=1)[source]

Initialize the BaseDataset object.

Parameters:

  • imshape (tuple | np.ndarray | None, optional) – Shape of the image. Default is None.

  • data_dir (os.PathLike | None, optional) – Directory for data storage. Default is None.

  • scale (float | None, optional) – Scale factor for the dataset. Default is None.

  • verbose (int | bool, optional) – Verbosity level. Default is 1.

property images_filtered: numpy.ndarray
property images_cropped: numpy.ndarray
classmethod from_TFS()[source]

Convert a Through Focal Series (TFS) to a DefocusedDataset.

classmethod load(images, metadata=None, **kwargs)[source]

Load images and metadata to create a DefocusedDataset instance.

Parameters:

  • images (Union[np.ndarray, os.PathLike, List[os.PathLike]]) – Image data or paths.

  • metadata (Optional[Union[os.PathLike, dict]]) – Metadata as a path or dict.

Returns:

The created dataset instance.

Return type:

DefocusedDataset

property images: numpy.ndarray
property image: numpy.ndarray
property defvals: numpy.ndarray
property shape: tuple[int, int]

overwritten by higher level classes get the shape of the image (y,x).

property energy: float | None
select_ROI(idx=0, image=None)[source]

Select a Region of Interest (ROI) for processing.

Parameters:

  • idx (int) – Index of the image to use for ROI selection.

  • image (Optional[np.ndarray]) – Specific image to use for ROI selection.

Return type:

None

apply_transforms()[source]

Apply transformations (e.g., rotation, cropping) to the images.

Return type:

None

preprocess(hotpix=True, median_filter_size=None, fast=True, **kwargs)[source]

Preprocess the images by filtering hot pixels and applying a median filter.

Parameters:

  • hotpix (bool) – Whether to filter hot pixels.

  • median_filter_size (Optional[int]) – Size of the median filter.

  • fast (bool) – Whether to use a fast filtering method.

Return type:

None

reset_transforms()[source]

Reset all transformations applied to the images.

Return type:

None

show_im(idx=0, **kwargs)[source]

Display an image with optional parameters.

Parameters:

idx (int) – Index of the image to display.

Return type:

None

show_all(**kwargs)[source]

Display all images.

Parameters:

idx (int) – Index of the image to display.

Return type:

None

filter(q_lowpass=None, q_highpass=None, filter_type='butterworth', butterworth_order=2, idx=None, show=False, v=None)[source]

Apply bandpass filtering to the images.

Parameters:

  • q_lowpass (Optional[float]) – Lowpass filter cutoff.

  • q_highpass (Optional[float]) – Highpass filter cutoff.

  • filter_type (str) – Type of filter (‘butterworth’ or ‘gaussian’).

  • butterworth_order (int) – Order of the Butterworth filter.

  • idx (Optional[Union[int, List[int]]]) – Indices of images to filter.

  • show (bool) – Whether to display the filtered images.

  • v (Optional[int]) – Verbosity level.

Return type:

None

copy()[source]

Create a deep copy of the dataset.

Returns:

A deep copy of the current dataset.

Return type:

DefocusedDataset

Through Focal Series

class PyLorentz.dataset.through_focal_series.ThroughFocalSeries(imstack, flipstack=None, flip=False, scale=None, defvals=None, beam_energy=None, use_mask=True, simulated=False, data_dir=None, data_files=[], verbose=1)[source]

Bases: BaseDataset

A class for handling through-focal series (TFS) datasets, including processing and visualization.

Parameters:

  • imstack (np.ndarray) – Stack of images in the TFS.

  • flipstack (Optional[np.ndarray]) – Stack of flipped images for comparison.

  • flip (Optional[bool]) – Indicates if the dataset includes flipped images.

  • scale (Optional[float]) – The scale of the images.

  • defvals (Optional[np.ndarray]) – The defocus values for the images.

  • beam_energy (Optional[float]) – The beam energy used during imaging.

  • use_mask (Optional[bool]) – Whether to use a mask in processing.

  • simulated (Optional[bool]) – Indicates if the data is simulated.

  • data_dir (Optional[os.PathLike]) – Directory where data is stored.

  • data_files (List[os.PathLike]) – List of file paths for the data.

  • verbose (Optional[int]) – Verbosity level for logging.

__init__(imstack, flipstack=None, flip=False, scale=None, defvals=None, beam_energy=None, use_mask=True, simulated=False, data_dir=None, data_files=[], verbose=1)[source]

Initialize the BaseDataset object.

Parameters:

  • imshape (tuple | np.ndarray | None, optional) – Shape of the image. Default is None.

  • data_dir (os.PathLike | None, optional) – Directory for data storage. Default is None.

  • scale (float | None, optional) – Scale factor for the dataset. Default is None.

  • verbose (int | bool, optional) – Verbosity level. Default is 1.

classmethod from_files(aligned_file, aligned_flip_file=None, metadata_file=None, flip=False, scale=None, defocus_values=None, beam_energy=None, dump_metadata=True, use_mask=True, legacy_data_loc=None, legacy_fls_filename=None, verbose=1)[source]

Create a ThroughFocalSeries instance from files.

Parameters:

  • aligned_file (Union[str, os.PathLike]) – Path to the aligned image stack.

  • aligned_flip_file (Optional[Union[str, os.PathLike]]) – Path to the flip image stack.

  • metadata_file (Optional[Union[str, os.PathLike]]) – Path to metadata file.

  • flip (bool) – Indicates if the dataset includes flipped images.

  • scale (Optional[float]) – The scale of the images.

  • defocus_values (Optional[List[float]]) – Defocus values.

  • beam_energy (Optional[float]) – Beam energy used during imaging.

  • dump_metadata (Optional[bool]) – Whether to save metadata to a file.

  • use_mask (Optional[bool]) – Whether to use a mask in processing.

  • legacy_data_loc (Optional[Union[str, os.PathLike]]) – Path for legacy data.

  • legacy_fls_filename (Optional[Union[str, os.PathLike]]) – FLS filename for legacy data.

  • verbose (Optional[Union[int, bool]]) – Verbosity level for logging.

Returns:

The created TFS instance.

Return type:

ThroughFocalSeries

property imstack: numpy.ndarray
property flipstack: numpy.ndarray
property flip: bool
property defvals_index: numpy.ndarray
property defvals: numpy.ndarray
property beam_energy: float | None
property full_stack: numpy.ndarray
property full_defvals: numpy.ndarray
property infocus: numpy.ndarray
property orig_infocus: numpy.ndarray
property shape: tuple

overwritten by higher level classes get the shape of the image (y,x).

property len_tfs: int
preprocess(hotpix=True, median_filter_size=None, fast=True, **kwargs)[source]

Preprocess the images by filtering hot pixels and applying a median filter.

Parameters:

  • hotpix (bool) – Whether to filter hot pixels.

  • median_filter_size (Optional[int]) – Size of the median filter.

  • fast (bool) – Whether to use a fast filtering method.

Return type:

None

filter(q_lowpass=None, q_highpass=None, filter_type='butterworth', butterworth_order=2, show=False, v=None)[source]

Apply filtering to the image stack.

Parameters:

  • q_lowpass (Optional[float]) – Lowpass filter cutoff.

  • q_highpass (Optional[float]) – Highpass filter cutoff.

  • filter_type (str) – Type of filter (‘butterworth’ or ‘gaussian’).

  • butterworth_order (int) – Order of the Butterworth filter.

  • show (Optional[bool]) – Whether to show the filtered images.

  • v (Optional[int]) – Verbosity level.

Return type:

None

apply_transforms(v=1)[source]

Apply image transformations, such as rotation and cropping.

Parameters:

v (int) – Verbosity level for logging.

Return type:

None

Returns:

None

select_ROI(image=None)[source]

Select a region of interest (ROI) from the image.

Parameters:

image (Optional[np.ndarray]) – Image to select ROI from.

Return type:

None

Returns:

None

show_tfs(vm_scale_each=True, **kwargs)[source]

Display the through-focal series images.

Parameters:

**kwargs – Additional keyword arguments for display.

Return type:

None

Returns:

None

reset_transforms()[source]

Reset transformations applied to the images.

Return type:

None

Returns:

None