Configuration

The configuration is at the heart of ultrack, it is used to define the parameters for each step of the pipeline and where to store the intermediate results. The MainConfig is the main configuration that contains the other configurations of the individual steps plus the data configuration.

The configurations are documented below, the parameters are ordered by importance, most important parameters are at the top of the list. Parameters that should not be changed in most of the cases are at the bottom of the list and contain a SPECIAL tag.

ultrack.config.MainConfig
ultrack.config.DataConfig	Configuration for intermediate data storage and retrieval.
ultrack.config.SegmentationConfig	Segmentation hypotheses creation configuration
ultrack.config.LinkingConfig	Candidate cell hypotheses linking configuration
ultrack.config.TrackingConfig	Tracking (segmentation & linking selection) configuration

---

class ultrack.config.MainConfig

field data_config [Optional] (alias 'data')

Configuration for intermediate data storage and retrieval.

field segmentation_config [Optional] (alias 'segmentation')

Segmentation hypotheses creation configuration

field linking_config [Optional] (alias 'linking')

Candidate cell hypotheses linking configuration

field tracking_config [Optional] (alias 'tracking')

Tracking (segmentation & linking selection) configuration

---

class ultrack.config.DataConfig

Configuration for intermediate data storage and retrieval.

field n_workers = 1

Number of workers for parallel processing

field working_dir = PosixPath('.')

Working directory for auxiliary files (e.g. sqlite database, metadata)

field database = 'sqlite'

SPECIAL: Database type sqlite and postgresql supported

field address = None

SPECIAL: Postgresql database path, for example, postgres@localhost:12345/example

property database_path

Returns database path given working directory and database type.

metadata_add(data)

Adds data content to metadata file.

property metadata

Returns metadata as dictionary.

dict(*args, **kwargs)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

---

class ultrack.config.SegmentationConfig

Segmentation hypotheses creation configuration

field min_area = 100

Minimum segment number of pixels, regions smaller than this value are merged or removed when there is no neighboring region

field max_area = 1000000

Maximum segment’s number of pixels, regions larger than this value are removed

field n_workers = 1

Number of worker threads

field min_frontier = 0.0

Minimum average frontier value between candidate segmentations, regions sharing an average frontier value lower than this are merged

field threshold = 0.5

Threshold used to binarize the cell foreground map

field max_noise = 0.0

SPECIAL: Upper limit of uniform distribution for additive noise on contour map

field ws_hierarchy = <function watershed_hierarchy_by_area>

SPECIAL: Watershed hierarchy function from higra used to construct the hierarchy

field anisotropy_penalization = 0.0

SPECIAL: Image graph z-axis penalization, positive values will prioritize segmenting the xy-plane first, negative will do the opposite

dict(*args, **kwargs)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

---

class ultrack.config.LinkingConfig

Candidate cell hypotheses linking configuration

field max_distance = 15.0

Maximum distance between neighboring segments

field n_workers = 1

Number of worker threads

field max_neighbors = 5

Maximum number of neighbors per candidate segment

field distance_weight = 0.0

Penalization weight \(\gamma\) for distance between segment centroids, \(w_{pq} - \gamma \|c_p - c_q\|_2\), where \(c_p\) is region \(p\) center of mass

field z_score_threshold = 5.0

SPECIAL: z-score threshold between intensity values from within the segmentation masks of neighboring segments

---

class ultrack.config.TrackingConfig

Tracking (segmentation & linking selection) configuration

field appear_weight = -0.001

Penalization weight for appearing cell, should be negative

field disappear_weight = -0.001

Penalization for disappearing cell, should be negative

field division_weight = -0.001

Penalization for dividing cell, should be negative

field n_threads = -1

Number of worker threads

field window_size = None

Time window size for partially solving the tracking ILP. By default it solves the entire timelapse at once. Useful for large datasets.

field overlap_size = 1

Number of frames used to shared (overlap/pad) each size when window_size is set. This improves the tracking quality at the edges of the windows and enforce continuity of the tracks.

field solution_gap = 0.001

Solver solution gap. This will speed up the solver when finding the optimal solution might taken a long time, but may affect the quality of the solution.

field time_limit = 36000

Solver execution time limit in seconds

field method = 0

SPECIAL: Solver method, reference

field link_function = 'power'

SPECIAL: Function used to transform the edge and node weights, identity or power

field power = 4

SPECIAL: Expoent \(\eta\) of power transform, \(w_{pq}^\eta\)

field bias = -0.0

SPECIAL: Edge weights bias \(b\), \(w_{pq} + b\), should be negative