napari_track_edit.motile.backend

Submodules

• napari_track_edit.motile.backend.motile_run
• napari_track_edit.motile.backend.solve
• napari_track_edit.motile.backend.solver_params

Classes

MotileRun	An object representing a motile tracking run. Contains a name,
SolverParams	The set of solver parameters supported in the motile tracker.

Functions

build_candidate_graph(→ tracksdata.graph.BaseGraph)	Build the candidate graph from input data.
get_solver_name(→ str)	Return the name of the ILP solver backend that will be used.
solve(→ tracksdata.graph.BaseGraph)	Get a tracking solution for the given segmentation and parameters.

Package Contents

class napari_track_edit.motile.backend.MotileRun(graph: tracksdata.graph.BaseGraph, run_name: str, time_attr: str = 't', pos_attr: str | tuple[str] | list[str] = 'pos', scale: list[float] | None = None, ndim: int | None = None, solver_params: napari_track_edit.motile.backend.solver_params.SolverParams | None = None, input_segmentation: numpy.ndarray | None = None, input_points: numpy.ndarray | None = None, time: datetime.datetime | None = None, gaps: list[float] | None = None, status: str = 'done', _features=None, _segmentation=None)

Bases: funtracks.data_model.Tracks

An object representing a motile tracking run. Contains a name, parameters, time of creation, information about the solving process (status and list of solver gaps), and optionally the input and output segmentations and tracks. Mostly used for passing around the set of attributes needed to specify a run, as well as saving and loading.

run_name

solver_params = None

input_segmentation = None

input_points = None

gaps = None

status = 'done'

time

_make_id() → str

Combine the time and run name into a unique id for the run

Returns:

A unique id combining the timestamp and run name

Return type:

str

static _unpack_id(_id: str) → tuple[datetime.datetime, str]

Unpack a string id created with _make_id into the time and run name

Parameters:

_id (str) – The id to unpack into time and run name

Raises:

ValueError – If the provided id is not in the expected format

Returns:

A tuple of time and run name

Return type:

tuple[datetime, str]

classmethod _resolve_name_and_time(run_dir: pathlib.Path, attrs: dict | None) → tuple[datetime.datetime | None, str]

Determine the run name and run time for a run being loaded.

Runs used to be saved in a directory named by _make_id, so the name and time could be recovered by unpacking the directory name. Newer runs store both in the attrs file instead, which lets them be saved to a directory the user named. Falls back through both, and finally to the directory name with no time, so that a run directory is loadable however it was named. A None time is replaced with the current time by __init__, so the run still displays.

Parameters:

• run_dir (Path) – The directory the run is being loaded from.

• attrs (dict | None) – The loaded attrs, or None if there is no attrs file.

Returns:

The run time and run name.

Return type:

tuple[datetime | None, str]

save(path: str | pathlib.Path, save_segmentation: bool = False) → pathlib.Path

Save the run as a geff store at the provided path.

The geff store is written at exactly path — no subdirectory is created — and the rest of the run (solver params, attrs, input points, gaps) is stored inside that store alongside the graph. A geff is a zarr directory, and writing a geff only replaces geff-controlled groups, so these files survive re-saving over the same store.

Parameters:

• path (str | Path) – The geff store to save the run to. Created if it does not exist, and replaced if it does.

• save_segmentation (bool) – Ignored. Kept for backwards compatibility; the segmentation is never written here.

Returns:

The Path that the run was saved to.

Return type:

(Path)

static geff_path(run_dir: pathlib.Path | str) → pathlib.Path | None

Return the geff store holding a saved run’s graph.

Mirrors the layouts that load() accepts. Runs saved by the current version are themselves the geff store. Returns None for v1 runs, which stored the graph as graph.json rather than as a geff.

Parameters:

run_dir (Path | str) – A directory created by MotileRun.save.

static _is_geff(directory: pathlib.Path) → bool

Whether the given directory is itself a geff store.

Distinguishes a run saved as a geff from an older run directory that merely contains one, which is exactly what load() needs.

classmethod load(run_dir: pathlib.Path | str, output_required: bool = True)

Load a run from disk into memory.

Parameters:

• run_dir (Path | str) – A directory containing the saved run. Should be the subdirectory created by MotileRun.save that includes the timestamp and run name.

• output_required (bool) – If the model outputs are required. If true, will raise an error if the output files are not found. Defualts to True.

Returns:

The run saved in the provided directory.

Return type:

MotileRun

_save_params(run_dir: pathlib.Path)

Save the run parameters in the provided run directory. Currently dumps the parameters dict into a json file. Skips writing if there are no params, which only happens for a run loaded from a directory that had no params file (see _load_params).

Parameters:

run_dir (Path) – A directory in which to save the parameters file.

static _load_params(run_dir: pathlib.Path) → napari_track_edit.motile.backend.solver_params.SolverParams | None

Load parameters from the parameters json file in the provided directory. Returns None if the file is absent, which is the case for v1 run directories and for runs saved by versions that wrapped imported (CSV/geff) tracks in a MotileRun with no solver params.

Parameters:

run_dir (Path) – The directory in which to find the parameters file.

Returns:

The solver parameters, or None if no params

file exists in the run directory.

Return type:

SolverParams | None

_save_array(run_dir: pathlib.Path, filename: str, array: numpy.ndarray)

Save a segmentation as a numpy array using np.save. In the future, could be changed to use zarr or other file types.

Parameters:

• run_dir (Path) – The directory in which to save the segmentation

• filename (str) – The filename to use

• array (np.array) – The array to save

static _load_array(run_dir: pathlib.Path, filename: str, required: bool = True) → numpy.ndarray | None

Load an array from file using np.load. In the future, could be lazy loading from a zarr.

Parameters:

• run_dir (Path) – The base run directory containing the array

• filename (str) – The name of the file to load

• required (bool, optional) – If true, will fail if the array file is not present. If false, will return None if the file is not present. Defaults to True.

Raises:

FileNotFoundError – If the array file is not found, and it was required.

Returns:

The array, or None if the file was

not found and not required.

Return type:

np.ndarray | None

_save_attrs(directory: pathlib.Path)

Save the run name, run time, time_attr, scale, and shape in a json file.

The run name and time are stored here rather than being recoverable from the directory name alone (see _make_id), so that a run can be saved to a directory the user named.

Note that “time” is when the run was solved, while “time_attr” is the name of the graph’s time column.

Parameters:

directory (Path) – The directory in which to save the attributes

static _load_attrs(run_dir: pathlib.Path) → dict | None

Load attrs from the attrs json file in the provided directory, if present.

Parameters:

run_dir (Path) – The directory in which to find the attrs file.

Returns:

The attrs dict, or None if the file was not found.

Return type:

dict | None

_save_list(list_to_save: list | None, run_dir: pathlib.Path, filename: str)

static _load_list(run_dir: pathlib.Path, filename: str, required: bool = True) → list[float]

delete(base_path: str | pathlib.Path)

Delete this run from the file system. Will look inside base_path for the directory corresponding to this run and delete it.

Parameters:

base_path (str | Path) – The parent directory where the run is saved (not the one created by self.save).

class napari_track_edit.motile.backend.SolverParams(/, **data: Any)

Bases: pydantic.BaseModel

The set of solver parameters supported in the motile tracker. Used to build the UI as well as store parameters for runs.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

max_edge_distance: float

max_children: int

edge_selection_cost: float | None

appear_cost: float | None

division_cost: float | None

distance_cost: float | None

iou_cost: float | None

window_size: int | None

overlap_size: int | None

single_window_start: int | None

classmethod window_size_must_be_at_least_two(v: int | None) → int | None

classmethod overlap_size_must_be_positive(v: int | None) → int | None

napari_track_edit.motile.backend.build_candidate_graph(input_data: numpy.ndarray, solver_params: napari_track_edit.motile.backend.solver_params.SolverParams, scale: list | None = None, time_offset: int = 0) → tracksdata.graph.BaseGraph

Build the candidate graph from input data.

napari_track_edit.motile.backend.get_solver_name() → str

Return the name of the ILP solver backend that will be used.

Attempts Gurobi first; falls back to SCIP.

napari_track_edit.motile.backend.solve(solver_params: napari_track_edit.motile.backend.solver_params.SolverParams, input_data: numpy.ndarray, on_solver_update: collections.abc.Callable | None = None, scale: list | None = None, cand_graph: tracksdata.graph.BaseGraph | None = None) → tracksdata.graph.BaseGraph

Get a tracking solution for the given segmentation and parameters.

Constructs a candidate graph from the segmentation (unless one is provided), a solver from the parameters, and then runs solving and returns a networkx graph with the solution. Most of this functionality is implemented in the motile toolbox.

Parameters:

• solver_params (SolverParams) – The solver parameters to use when initializing the solver

• input_data (np.ndarray) – The input segmentation or points list to run tracking on. If 2D, assumed to be a list of points, otherwise a segmentation.

• on_solver_update (Callable, optional) – A function that is called whenever the motile solver emits an event. The function should take a dictionary of event data, and can be used to track progress of the solver. Defaults to None.

• scale (list, optional) – The scale of the data in each dimension.

• cand_graph (td.graph.BaseGraph, optional) – A pre-built candidate graph. If provided, skips candidate graph construction (except for single-window mode which always builds its own). Defaults to None.

Returns:

A solution graph where the ids of the nodes correspond to

the time and ids of the passed in segmentation labels. See funtracks for exact implementation details.

Return type:

td.graph.BaseGraph