tmlib.workflow.align package

Module contents

Workflow step for registration and alignment of microscopy images.

When images are acquired at the different time points they may exhibit a displacement relative to each other. To overlay these image for visualization or analysis, they need to be registered and aligned between acquisitions. To this end, the align step computes translational shifts of each image acquired at the same site relative to one reference image (by default the one of the first acquisition time point). The computed shift values are stored and can later be applied for alignment. Note that translations are computed only per site and no attempt is made to find a globally optimal alignment. This is done for performance reasons and to simplify parallelization.

Submodules

tmlib.workflow.align.api module

class tmlib.workflow.align.api.ImageRegistrator(experiment_id)

Bases: tmlib.workflow.api.WorkflowStepAPI

Class for registeration and alignment of images between multiplexing cycles.

Parameters:

experiment_id: int

ID of the processed experiment
collect_job_output(obj, *args, **kwargs)

Not implemented.

create_run_batches(args)

Creates job descriptions for parallel computing.

Parameters:

args: tmlib.workflow.align.args.AlignBatchArguments

step-specific arguments
Returns:

generator

job descriptions
Raises:

ValueError

when args.ref_wavelength does not exist across all cycles
delete_previous_job_output()

Deletes the output of a previous submission.

has_collect_phase = False
run_job(batch, assume_clean_state=False)

Calculates the number of pixels each image is shifted relative its reference image. The calculated values can later be used to align images between cycles.

Parameters:

batch: dict

description of the run job

assume_clean_state: bool, optional

assume that output of previous runs has already been cleaned up

tmlib.workflow.align.args module

class tmlib.workflow.align.args.AlignBatchArguments(**kwargs)

Bases: tmlib.workflow.args.BatchArguments

Parameters:

**kwargs: dict, optional

keyword arguments to overwrite
batch_size

int: number of acquisition sites that should be processed per job

illumcorr

bool: wether images should be corrected for illumination artifacts

ref_cycle

int: zero-based index of the cycle whose sites should be used as reference

ref_wavelength

str: name of the wavelength whose images should be used as reference

class tmlib.workflow.align.args.AlignSubmissionArguments(**kwargs)

Bases: tmlib.workflow.args.SubmissionArguments

Parameters:

**kwargs: dict, optional

keyword arguments to overwrite

tmlib.workflow.align.cli module

class tmlib.workflow.align.cli.Align(api_instance, verbosity)

Bases: tmlib.workflow.cli.WorkflowStepCLI

Registration of images acquired in different multiplexing cycles relative to a reference cycle. The calculated shifts can then subsequently be used to align images.

Parameters:

api_instance: tmlib.workflow.align.api.ImageRegistrator

instance of API class to which processing is delegated

verbosity: int

logging verbosity

align

Registration of images acquired in different multiplexing cycles relative to a reference cycle. The calculated shifts can then subsequently be used to align images.
experiment_id

ID of the experiment that should be processed

-h, --help

show this help message and exit

--verbosity, -v

increase logging verbosity

align experiment_id cleanup

cleans up the output of a previous submission, i.e. removes files and database entries created by previously submitted jobs
-h, --help

show this help message and exit

align experiment_id collect

collects the output of run jobs, i.e. performs a post-processing operation that either cannot be parallelized or needs to be performed afterwards
-h, --help

show this help message and exit

align experiment_id info

prints the description of a given batch job to the console
-h, --help

show this help message and exit

--job, -j

ID of the job for which information should be displayed

--phase {collect,run}, -p {collect,run}

phase of the workflow step to which the job belongs

align experiment_id init

creates batches for parallel processing and thereby defines how the computational task should be distrubuted over the cluster (also cleans up the output of previous submissions)
-h, --help

show this help message and exit

--batch-size <batch_size>, -b <batch_size>

number of acquisition sites that should be processed per job (default: 100)

--illumcorr, -i

wether images should be corrected for illumination artifacts

--ref-cycle <ref_cycle>, -c <ref_cycle>

zero-based index of the cycle whose sites should be used as reference

--ref-wavelength <ref_wavelength>, -w <ref_wavelength>

name of the wavelength whose images should be used as reference

align experiment_id log

prints the log output of a given batch job to the console
-h, --help

show this help message and exit

--job, -j

ID of the job for which log output should be shown

--phase {collect,init,run}, -p {collect,init,run}

phase of the workflow step to which the job belongs

align experiment_id resubmit

resubmits previously created jobs for “run” and “collect” phases to the cluster and monitors their status upon processing
-h, --help

show this help message and exit

--depth <index>, -d <index>

number of child tasks that should be monitored (default: 1)

--interval <seconds>, -i <seconds>

seconds to wait between monitoring iterations (default: 10)

align experiment_id run

runs an invidiual batch job on the local machine
-h, --help

show this help message and exit

--assume-clean-state

assume that previous outputs have been cleaned up

--job <job_id>, -j <job_id>

ID of the job that should be run

align experiment_id submit

creates batch jobs for the “run” and “collect” phases, submits them to the cluster and monitors their status upon processing (requires a prior “init”)
-h, --help

show this help message and exit

--depth <index>, -d <index>

number of child tasks that should be monitored (default: 1)

--interval <seconds>, -i <seconds>

seconds to wait between monitoring iterations (default: 10)

--cores <number>

number of cores that should be allocated to each “run” job (may be increased in case memory requirements of a job exceed resources of a single core) (default: 1)

--duration <hh:mm:ss>

walltime that should be allocated to a each “run” job in the format “HH:MM:SS” (may need to be adapted depending on the choice of batch size) (default: 06:00:00)

--memory <mb>

amount of memory in megabytes that should be allocated to each “run” job (default: 2147)

tmlib.workflow.align.registration module

tmlib.workflow.align.registration.calculate_overlap(y_shifts, x_shifts)

Calculates the overlap of images acquired at the same site across different acquisition cycles.

Parameters:

y_shifts: List[int]

shifts along the y-axis

x_shifts: List[int]

shifts along the x-axis
Returns:

List[int]

number of overhanging pixels at the top, bottom, right and left side
tmlib.workflow.align.registration.calculate_shift(target_image, reference_image)

Calculates the displacement between two images acquired at the same site in different cycles based on fast Fourier transform.

Parameters:

target_image: numpy.ndarray

image that should be registered

reference_image: numpy.ndarray

image that should be used as a reference
Returns:

Tuple[int]

shift in y and x direction