napari_track_edit.motile.backend ================================ .. py:module:: napari_track_edit.motile.backend Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/napari_track_edit/motile/backend/motile_run/index /autoapi/napari_track_edit/motile/backend/solve/index /autoapi/napari_track_edit/motile/backend/solver_params/index Classes ------- .. autoapisummary:: napari_track_edit.motile.backend.MotileRun napari_track_edit.motile.backend.SolverParams Functions --------- .. autoapisummary:: napari_track_edit.motile.backend.build_candidate_graph napari_track_edit.motile.backend.get_solver_name napari_track_edit.motile.backend.solve Package Contents ---------------- .. py:class:: 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: :py:obj:`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. .. py:attribute:: run_name .. py:attribute:: solver_params :value: None .. py:attribute:: input_segmentation :value: None .. py:attribute:: input_points :value: None .. py:attribute:: gaps :value: None .. py:attribute:: status :value: 'done' .. py:attribute:: time .. py:method:: _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 :rtype: str .. py:method:: _unpack_id(_id: str) -> tuple[datetime.datetime, str] :staticmethod: Unpack a string id created with _make_id into the time and run name :param _id: The id to unpack into time and run name :type _id: str :raises ValueError: If the provided id is not in the expected format :returns: A tuple of time and run name :rtype: tuple[datetime, str] .. py:method:: _resolve_name_and_time(run_dir: pathlib.Path, attrs: dict | None) -> tuple[datetime.datetime | None, str] :classmethod: 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. :param run_dir: The directory the run is being loaded from. :type run_dir: Path :param attrs: The loaded attrs, or None if there is no attrs file. :type attrs: dict | None :returns: The run time and run name. :rtype: tuple[datetime | None, str] .. py:method:: 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. :param path: The geff store to save the run to. Created if it does not exist, and replaced if it does. :type path: str | Path :param save_segmentation: Ignored. Kept for backwards compatibility; the segmentation is never written here. :type save_segmentation: bool :returns: The Path that the run was saved to. :rtype: (Path) .. py:method:: geff_path(run_dir: pathlib.Path | str) -> pathlib.Path | None :staticmethod: Return the geff store holding a saved run's graph. Mirrors the layouts that :meth:`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. :param run_dir: A directory created by MotileRun.save. :type run_dir: Path | str .. py:method:: _is_geff(directory: pathlib.Path) -> bool :staticmethod: 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. .. py:method:: load(run_dir: pathlib.Path | str, output_required: bool = True) :classmethod: Load a run from disk into memory. :param run_dir: A directory containing the saved run. Should be the subdirectory created by MotileRun.save that includes the timestamp and run name. :type run_dir: Path | str :param output_required: If the model outputs are required. If true, will raise an error if the output files are not found. Defualts to True. :type output_required: bool :returns: The run saved in the provided directory. :rtype: MotileRun .. py:method:: _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). :param run_dir: A directory in which to save the parameters file. :type run_dir: Path .. py:method:: _load_params(run_dir: pathlib.Path) -> napari_track_edit.motile.backend.solver_params.SolverParams | None :staticmethod: 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. :param run_dir: The directory in which to find the parameters file. :type run_dir: Path :returns: The solver parameters, or None if no params file exists in the run directory. :rtype: SolverParams | None .. py:method:: _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. :param run_dir: The directory in which to save the segmentation :type run_dir: Path :param filename: The filename to use :type filename: str :param array: The array to save :type array: np.array .. py:method:: _load_array(run_dir: pathlib.Path, filename: str, required: bool = True) -> numpy.ndarray | None :staticmethod: Load an array from file using np.load. In the future, could be lazy loading from a zarr. :param run_dir: The base run directory containing the array :type run_dir: Path :param filename: The name of the file to load :type filename: str :param required: 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. :type required: bool, optional :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. :rtype: np.ndarray | None .. py:method:: _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. :param directory: The directory in which to save the attributes :type directory: Path .. py:method:: _load_attrs(run_dir: pathlib.Path) -> dict | None :staticmethod: Load attrs from the attrs json file in the provided directory, if present. :param run_dir: The directory in which to find the attrs file. :type run_dir: Path :returns: The attrs dict, or None if the file was not found. :rtype: dict | None .. py:method:: _save_list(list_to_save: list | None, run_dir: pathlib.Path, filename: str) .. py:method:: _load_list(run_dir: pathlib.Path, filename: str, required: bool = True) -> list[float] :staticmethod: .. py:method:: 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. :param base_path: The parent directory where the run is saved (not the one created by self.save). :type base_path: str | Path .. py:class:: SolverParams(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` The set of solver parameters supported in the motile tracker. Used to build the UI as well as store parameters for runs. .. py:attribute:: model_config Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. .. py:attribute:: max_edge_distance :type: float .. py:attribute:: max_children :type: int .. py:attribute:: edge_selection_cost :type: float | None .. py:attribute:: appear_cost :type: float | None .. py:attribute:: division_cost :type: float | None .. py:attribute:: distance_cost :type: float | None .. py:attribute:: iou_cost :type: float | None .. py:attribute:: window_size :type: int | None .. py:attribute:: overlap_size :type: int | None .. py:attribute:: single_window_start :type: int | None .. py:method:: window_size_must_be_at_least_two(v: int | None) -> int | None :classmethod: .. py:method:: overlap_size_must_be_positive(v: int | None) -> int | None :classmethod: .. py:function:: 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. .. py:function:: get_solver_name() -> str Return the name of the ILP solver backend that will be used. Attempts Gurobi first; falls back to SCIP. .. py:function:: 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. :param solver_params: The solver parameters to use when initializing the solver :type solver_params: SolverParams :param input_data: The input segmentation or points list to run tracking on. If 2D, assumed to be a list of points, otherwise a segmentation. :type input_data: np.ndarray :param on_solver_update: 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. :type on_solver_update: Callable, optional :param scale: The scale of the data in each dimension. :type scale: list, optional :param cand_graph: A pre-built candidate graph. If provided, skips candidate graph construction (except for single-window mode which always builds its own). Defaults to None. :type cand_graph: td.graph.BaseGraph, optional :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. :rtype: td.graph.BaseGraph