A cell tracker maximizing accuracy through diverse segmentation analysis and mixed integer programming optimization
Bactrack is inspired by ultrack(paper). Bactrack uses segmentation hierarchy to allow various segmentation scenarios, and hierarchy is built on Omnipose dynamic/pixel clustering logic, and using MIP solver to assign cell from frame to frame by maximize weights.
For assignment algorithm, Bactrack includes following MIP solvers: HiGHS, CBC, Gurobi for tracking assignment task. All of these MIP solver will return the same optimized global maximum result but with different run-time speed. For performance comparsion between MIP solvers check this benchmark. In short, the speed of Gurobi is the fastest (Gurobi > HiGHS > CBC).
( Those tools are not directly be used, but through Python interface libraries: specifically: Scipy.milp for HiGHS, and python_mip for CBC and Gurobi. So if you look at solvers name: MipSolver,ScipySolver, it's interface name rather than solver name)
Goes Bactrack Architecture Doc for more details for Bactrack.
First, make sure you have Conda installed. You can find the installation instructions on the Conda official documentation.
clone this repo
git clone https://github.com/yyang35/bactrack.git
setup the enviroment and install package
cd bactrack
conda env create -f environment.yaml
conda activate bactrack
For quick tastes of Bactrack (no need install it on your local), try this colAb notebook.
Examples of calling Bactrack functions includes in notebooks in the examples folder. You should start on Basic Function Notebook to explore the useage of core functions.
before you run it in GUI, you need install GUI dependences first.
Make sure you are in bactrack env first, then install GUI dependeces by command:
conda activate bactrack
pip install git+https://github.com/yyang35/bactrack[GUI]
and then you can start GUI by command:
python bactrack/gui/gui.py
python -m bactrack --basedir '[BASEDIR]' --outdir '[OUTPUTDIR]' --hypermodel omnipose --submodel bact_phase_omni --solver_name scipy_solver --weight_name overlap_weight
Change the '[BASEDIR]' and '[OUTPUTDIR]' by the dirctory stores images you want to run tracking on, and the desired dirctory you want to output files in.
Also feel free to change the models, weights, solvers. Options for them are listed in following. (submodels options depending on which hypermodel you are choose, check cellpose and omnipose for more information what models they provide, but bactrack automically accept all those models).
weights = [iou_weight, overlap_weight, distance_weight]\ solvers = [scipy_solver, mip_solver]
For understanding how Bactrack works, go to graphical architecture & framework in Bactrack Architecture Doc
For a more advance setup check document Advance Setup Doc