dcnum.feat.feat_background.bg_sparse_median

Attributes

ndi

Classes

BackgroundSparseMed	Sparse median background correction with cleansing
WorkerSparseMed	Worker process for median computation

Module Contents

dcnum.feat.feat_background.bg_sparse_median.ndi

class dcnum.feat.feat_background.bg_sparse_median.BackgroundSparseMed(input_data, output_path, kernel_size=200, split_time=1.0, thresh_cleansing=0, frac_cleansing=0.8, offset_correction=True, compress=True, num_cpus=None)

Bases: dcnum.feat.feat_background.base.Background

Sparse median background correction with cleansing

In contrast to the rolling median background correction, this algorithm only computes the background image every split_time seconds, but with a larger window (default kernel size is 200 frames instead of 100 frames).

1. At time stamps every split_time seconds, a background image is computed, resulting in a background series.

2. Cleansing: The background series is checked for images that contain event data using a lengthy algorithm that is documented in the source code (sorry). In short, this gets rid of background images that contain streaks of RBCs.

3. Each frame gets the background image closest to it based on time from the background series.

Parameters:

• input_data (array-like or pathlib.Path) – The input data can be either a path to an HDF5 file with the “evtens/image” dataset or an array-like object that behaves like an image stack (first axis enumerates events).

• output_path (pathlib.Path) – Path to the output file. If input_data is a path, you can set output_path to the same path to write directly to the input file. The data are written in the “events/image_bg” dataset in the output file.

• kernel_size (int) – Kernel size for median computation. This is the number of events that are used to compute the median for each pixel.

• split_time (float) – Time between background images in the background series

• thresh_cleansing (float) – A positive floating point value for scaling the thresholding operation when excluding background images from the series. Larger values mean more background images are excluded. Set to zero to enforce a fixed fraction via frac_cleansing.

• frac_cleansing (float) – Fraction between 0 and 1 indicating how many background images must still be present after cleansing (in case the cleansing factor is too large). Set to 1 to disable cleansing altogether.

• offset_correction (bool) – The sparse median background correction produces one median image for multiple input frames (BTW this also leads to very efficient data storage with internal HDF5 basins). In case the input frames are subject to frame-by-frame brightness variations (e.g. flickering of the illumination source), it is useful to have an offset value per frame that can then be used in a later step to perform a more accurate background correction. This offset is computed here by taking a 20px wide slice from each frame (where the channel wall is located) and computing the median therein relative to the computed background image. The data are written to the “bg_off” feature in the output file alongside “image_bg”. To obtain the corrected background image, add “image_bg” and “bg_off”. Set this to False if you don’t need the “bg_off” feature.

• compress (bool) – Whether to compress background data. Set this to False for faster processing.

• num_cpus (int) – Number of CPUs to use for median computation. Defaults to dcnum.common.cpu_count().

• versionchanged: (..) – 0.23.5: The background image data are stored as an internal mapped basin to reduce the output file size.

kernel_size = 200

kernel size used for median filtering

split_time = 1.0

time between background images in the background series

thresh_cleansing = 0

cleansing threshold factor

frac_cleansing = 0.8

keep at least this many background images from the series

offset_correction = True

offset/flickering correction

time = None

duration

duration of the measurement

step_times

bg_images

array containing all background images

shared_input_raw

mp.RawArray for temporary batch input data

shared_output_raw

mp.RawArray for the median background image

shared_input

numpy array reshaped view on self.shared_input_raw. The First axis enumerating the events

shared_output

numpy array reshaped view on self.shared_output_raw. The First axis enumerating the events

worker_counter

counter tracking process of workers

queue

queue for median computation jobs

workers

list of workers (processes)

__enter__()

__exit__(type, value, tb)

static check_user_kwargs(*, kernel_size: int = 200, split_time: float = 1.0, thresh_cleansing: float = 0, frac_cleansing: float = 0.8, offset_correction: bool = True)

Initialize user-defined properties of this class

This method primarily exists so that the CLI knows which keyword arguments can be passed to this class.

Parameters:

• kernel_size (int) – Kernel size for median computation. This is the number of events that are used to compute the median for each pixel.

• split_time (float) – Time between background images in the background series

• thresh_cleansing (float) – A positive floating point value for scaling the thresholding operation when excluding background images from the series. Larger values mean more background images are excluded. Set to 0 (default) to enforce a fixed fraction frac_cleansing.

• frac_cleansing (float) – Fraction between 0 and 1 indicating how many background images must still be present after cleansing (in case the cleansing factor is too large). Set to 1 to disable cleansing altogether.

• offset_correction (bool) – The sparse median background correction produces one median image for multiple input frames (BTW this also leads to very efficient data storage with internal HDF5 basins). In case the input frames are subject to frame-by-frame brightness variations (e.g. flickering of the illumination source), it is useful to have an offset value per frame that can then be used in a later step to perform a more accurate background correction. This offset is computed here by taking a 20px wide slice from each frame (where the channel wall is located) and computing the median therein relative to the computed background image. The data are written to the “bg_off” feature in the output file alongside “image_bg”. To obtain the corrected background image, add “image_bg” and “bg_off”. Set this to False if you don’t need the “bg_off” feature.

process_approach()

Perform median computation on entire input data

process_second(ii: int, second: float | int)

class dcnum.feat.feat_background.bg_sparse_median.WorkerSparseMed(job_queue, counter, shared_input, shared_output, kernel_size, *args, **kwargs)

Bases: dcnum.feat.feat_background.base.mp_spawn.Process

Worker process for median computation

queue

counter

shared_input_raw

shared_output_raw

kernel_size

run()

Main loop of worker process (breaks when self.counter <0)

start()

Start child process