Command-Line Interface¶
Tracx provides a fully featured command-line interface (CLI) that allows you to run cell tracking experiments without an interactive MATLAB session or the graphical user interface. The CLI is suitable for batch processing, high-performance computing clusters, pipeline integration with workflow managers such as Snakemake or Nextflow, and reproducible analyses where a single project XML file and a workflow file completely describe the run.
The CLI can be used in two ways: either directly from the MATLAB source (no compilation required) or as a standalone compiled executable that requires only the free MATLAB Runtime (MCR) and no MATLAB licence.
Overview¶
All CLI functionality is implemented in the class TracX.TrackerCommandLineParser,
located at src/+TracX/@TrackerCommandLineParser/TrackerCommandLineParser.m.
The compiled entry point is tracx_main.m, which collects command-line arguments
and passes them to the parser. The parser supports three top-level modes of
operation, each described in a dedicated section below.
Mode |
Description |
|---|---|
Normal workflow run |
Load a project XML and execute an ordered sequence of processing steps. |
Project creation |
Create a new project XML file interactively or non-interactively using the
|
Inline call |
Call any single method on the |
Installation and runtime requirements¶
Running from MATLAB source¶
No compilation is required. Add the src/ directory to your MATLAB path and call
tracx_main directly.
addpath(genpath('path/to/tracxdevel/src'));
tracx_main('project.xml', '--workflow', 'yeast', '--verbose');
Running as a compiled standalone executable¶
The standalone executable requires the MATLAB Runtime (MCR), which is a free download from MathWorks and does not require a MATLAB licence. The MCR version must match the MATLAB release used to compile the executable.
Download the MCR from: https://www.mathworks.com/products/compiler/matlab-runtime.html
Setting the MCR path on Windows (permanent, no administrator rights required):
setx MCR_ROOT "C:\Program Files\MATLAB\MATLAB Runtime\R2024a"
Setting the MCR path on Linux or macOS (add to ~/.bashrc or ~/.zshrc ):
export MCR_ROOT=/usr/local/MATLAB/MATLAB_Runtime/R2024a
Once the MCR path is configured, use the wrapper scripts provided in the distribution folder to launch the executable. The wrapper sets the required library paths automatically before calling the binary.
Linux:
./run_tracx.sh project.xml --workflow yeast --verbose
Windows:
run_tracx.bat project.xml --workflow yeast --verbose
Compiling the executable¶
To compile the executable yourself from the MATLAB source, set the TRACX_ROOT
environment variable to the root of your tracxdevel checkout and run the
deployment script from the deploy/ folder.
Windows (inside MATLAB):
setenv('TRACX_ROOT', 'C:\path\to\tracxdevel');
cd path/to/tracxdevel/deploy
deploy_tracx('windows');
Linux (inside MATLAB):
setenv('TRACX_ROOT', '/path/to/tracxdevel');
cd path/to/tracxdevel/deploy
deploy_tracx('linux');
Output binaries are written to dist/windows/ and dist/linux/ respectively.
Cross-compilation is not supported by MATLAB Compiler; each platform binary must be
built on the corresponding operating system. A GitHub Actions CI pipeline
(deploy/.github/workflows/deploy_tracx_ci.yml) is provided that builds both
platforms in parallel on tagged releases.
Normal workflow run¶
The most common use case is loading an existing project XML and executing a sequence of processing steps.
TracXRunner <projectConfig.xml> [options]
The first positional argument is either a Tracx project XML file produced by
Tracker.saveTrackingProject() or the GUI, or a .mat state file saved by
Tracker.saveCurrentTrackerState().
From MATLAB source:
tracx_main('TracX_Yeast_SCerevisiae_Experiment_Project.xml', '--workflow', 'yeast');
From compiled executable on Linux:
./run_tracx.sh TracX_Yeast_SCerevisiae_Experiment_Project.xml --workflow yeast
From compiled executable on Windows:
run_tracx.bat TracX_Yeast_SCerevisiae_Experiment_Project.xml --workflow yeast
Global options¶
Option |
Description |
|---|---|
|
Workflow XML or |
|
Override the tracker results directory stored in the project XML. Useful when running the same project on a different machine or scratch partition. |
|
Override the image directory stored in the project XML. This is the most common override needed when moving data between machines. |
|
Override the segmentation results directory stored in the project XML. |
|
Append all console output to the specified log file in addition to writing it to standard output. The log file can be used to monitor long-running batch jobs. |
|
Load a pre-tracked Tracx state from a |
|
Validate all inputs and print the resolved configuration, then exit without executing any workflow steps. |
|
Enable additional diagnostic output. |
|
Print a full usage summary and exit. |
Built-in workflows¶
The following keyword shortcuts can be passed directly to --workflow without
providing a file path. They cover the most common experimental scenarios and can
also serve as starting points for custom workflows when copied from the
resources/workflows/ directory.
Keyword |
Description |
|---|---|
|
Loads the project, imports data, runs the tracker, saves the tracker state, saves the project XML, saves the tracking results table, and saves control images for quality inspection. |
|
Extends the default workflow with crop reversion, asymmetric lineage reconstruction (budding genealogy), and saving of the cell-cycle results table. |
|
Runs parameter test steps only without executing the full tracker. Saves the updated project XML at the end. Intended for iterative parameter exploration before committing to a full run. |
|
Converts raw labeled segmentation masks (from Cellpose, StarDist, ilastik, or any tool that produces integer-labeled TIFF files) into the CellX- compatible format, then executes the default tracking pipeline. See Generic segmentation masks for details. |
Workflow step reference¶
A workflow XML file defines an ordered list of named steps. Each step maps to a specific Tracx API call. The following steps are available.
Project and data lifecycle
Step name |
Corresponding API call |
|---|---|
|
|
|
Applies any |
|
|
|
|
|
|
Image and filename utilities
Step name |
Corresponding API call |
|---|---|
|
|
|
|
|
|
Segmentation preparation and filtering
Step name |
Corresponding API call |
|---|---|
|
|
|
|
|
|
|
|
|
|
Test and diagnostic steps
These steps write control images and diagnostic output but do not modify the
tracker state permanently. They are therefore safe to set abortOnError="false"
on. Each step has a corresponding interactive MATLAB method that shows popup
images for parameter tuning.
Step name |
Corresponding API call |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Tracking and lineage reconstruction
Step name |
Corresponding API call |
|---|---|
|
|
|
|
Manual corrections
Step name |
Corresponding API call |
|---|---|
|
|
|
|
Save and export
Step name |
Corresponding API call |
|---|---|
|
|
|
|
|
|
|
|
|
|
Visualisation
Step name |
Corresponding API call |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Data retrieval
The three export steps below retrieve a segmentation or quantification property from the loaded tracker data and write it as a CSV file. The CSV is also printed to standard output without any timestamp or prefix, so the output can be captured directly by a calling process using standard output redirection.
TracXRunner state.mat --workflow export.xml > my_data.csv
Step name |
Corresponding API call |
|---|---|
|
|
|
|
|
|
Arbitrary method call and custom scripts
The CallMethod step and the CustomScript step allow arbitrary extension
without modifying the CLI source code. See Inline call mode for the
interactive equivalent of CallMethod.
Step name |
Description |
|---|---|
|
Calls any method reachable from the |
|
Executes an arbitrary |
Workflow XML format¶
A workflow XML file defines the sequence of steps, their parameters, and whether a failure in a given step should abort the run or allow it to continue.
<?xml version="1.0" encoding="UTF-8"?>
<TracXWorkflow version="1.0">
<Description>My custom workflow</Description>
<Steps>
<Step name="LoadProject" abortOnError="true"/>
<Step name="OverridePaths" abortOnError="true"/>
<Step name="ClearData" abortOnError="true"/>
<Step name="ImportData" abortOnError="true"/>
<Step name="RevertCrop" abortOnError="false"/>
<Step name="RunTracker" abortOnError="true"/>
<Step name="RunLineage" abortOnError="false">
<Param name="SymmetricalDivision" value="false"/>
<Param name="WriteControlImages" value="false"/>
<Param name="NuclearMarkerChannel" value="1"/>
</Step>
<Step name="SaveState" abortOnError="true"/>
<Step name="SaveProject" abortOnError="true"/>
<Step name="SaveTable" abortOnError="true"/>
<Step name="SaveCellCycleTable" abortOnError="false"/>
<Step name="SaveControlImages" abortOnError="false">
<Param name="IsParallel" value="false"/>
<Param name="MaxWorkers" value="4"/>
</Step>
</Steps>
</TracXWorkflow>
Each <Step> element requires a name attribute. The abortOnError attribute
controls whether a failure in that step terminates the run (true, the default)
or allows processing to continue with the next step (false). Step-specific
parameters are supplied as <Param name="..." value="..."/> child elements; all
values are strings and are converted to the appropriate MATLAB type internally.
Pre-built workflow XML files for the most common scenarios are provided in the
resources/workflows/ directory of the distribution.
Loading a saved tracker state¶
Instead of a project XML, you can provide a .mat state file saved by
Tracker.saveCurrentTrackerState(). The state file contains a fully configured
and potentially already-tracked Tracker instance, making it possible to resume
interrupted work or run post-processing steps without re-tracking.
From MATLAB source:
tracx_main('20240815_TracX_State_MyProject.mat', '--workflow', 'yeast');
From compiled executable:
./run_tracx.sh 20240815_TracX_State_MyProject.mat --workflow yeast
The .mat extension is detected automatically so that the state file can be
passed as the first positional argument just like a project XML. Alternatively the
--state flag can be used explicitly, which is useful when the path is
constructed dynamically in a shell script.
./run_tracx.sh --state 20240815_TracX_State_MyProject.mat --workflow yeast
Project creation¶
The --create-project flag launches a wizard that creates a new Tracx project
XML file. The wizard can be run interactively from the command line or
non-interactively by supplying all required parameters as flags. The resulting
XML is suitable for immediate use with the normal workflow run mode.
Interactive mode (prompts for missing values):
TracXRunner --create-project
From MATLAB source (non-interactive, CellX segmentation):
tracx_main( ...
'--create-project', ...
'--create-name', 'MyYeastExperiment', ...
'--create-image-dir', '/data/RawImages', ...
'--create-seg-dir', '/data/CellXSegmentation/mKOk_mKate', ...
'--create-fp-channel', 'BFdivide', ...
'--create-lineage-ch', 'mKate', ...
'--create-movie-length', '30', ...
'--create-division-type', 'asym');
From compiled executable (non-interactive, CellX segmentation):
./run_tracx.sh \
--create-project \
--create-name MyYeastExperiment \
--create-image-dir /data/RawImages \
--create-seg-dir /data/CellXSegmentation/mKOk_mKate \
--create-fp-channel BFdivide \
--create-lineage-ch mKate \
--create-movie-length 30 \
--create-division-type asym
After creation the wizard prints the path to the saved XML and the command to run the full tracking pipeline.
Project creation options¶
Option |
Description |
|---|---|
|
Project name used as the base of the XML filename and internal project identifier. |
|
Path to the raw microscopy images. |
|
Path to the segmentation results. For CellX-style segmentation this directory must already contain the result files. For generic masks (see below) the directory contains the raw mask TIFFs. |
|
File name identifier of the brightfield or phase-contrast channel used
to compute Fourier fingerprints, for example |
|
File name identifier of the fluorescence channel used for lineage
reconstruction, for example |
|
Well-position identifier for multi-well experiments. Leave empty for single-position experiments. |
|
CellX crop coordinates as four comma-separated integers. This parameter should only be supplied when CellX was used for segmentation with a cropped region. See the note in the GUI documentation for details. |
|
Number of frames to track. |
|
Cell division type. Use |
|
After saving the project XML, immediately run the |
|
Create a minimal project XML without running |
Generic segmentation masks¶
If your segmentation was produced by a tool other than CellX ? for example Cellpose, StarDist, or ilastik ? and the output is a set of integer-labeled mask TIFF files (one file per frame, where each pixel value identifies the cell it belongs to), the following two-step workflow applies.
In step one you create a minimal project XML. The segmentation directory
contains only the raw mask TIFFs at this point, so --create-from-generic-segmentation
is required to skip the configuration check that would otherwise fail.
From MATLAB source:
tracx_main( ...
'--create-project', ...
'--create-name', 'GenericMaskExperiment', ...
'--create-image-dir', '/data/RawImages', ...
'--create-seg-dir', '/data/GenericMasks', ...
'--create-fp-channel', 'BFdivide', ...
'--create-lineage-ch', 'mKate', ...
'--create-movie-length', '30', ...
'--create-division-type', 'asym', ...
'--create-from-generic-segmentation');
From compiled executable:
./run_tracx.sh \
--create-project \
--create-name GenericMaskExperiment \
--create-image-dir /data/RawImages \
--create-seg-dir /data/GenericMasks \
--create-fp-channel BFdivide \
--create-lineage-ch mKate \
--create-movie-length 30 \
--create-division-type asym \
--create-from-generic-segmentation
In step two you run the generic-masks workflow, which first converts the masks
to CellX-compatible format (quantifying fluorescence channels in the process) and
then proceeds with the standard tracking pipeline.
From MATLAB source:
tracx_main( ...
'GenericMaskExperiment_Project.xml', ...
'--workflow', 'generic-masks', ...
'--image-dir', '/data/RawImages', ...
'--seg-dir', '/data/GenericMasks', ...
'--verbose');
From compiled executable:
./run_tracx.sh \
GenericMaskExperiment_Project.xml \
--workflow generic-masks \
--image-dir /data/RawImages \
--seg-dir /data/GenericMasks \
--verbose
The --image-dir and --seg-dir overrides are recommended when the project
XML was created on a different machine or with placeholder paths. The
PrepareGenericMasks workflow step reads the ImagePath, SegPath,
SegRegex, and ImageRegex parameters from the workflow XML; you can
customise these in a copy of resources/workflows/generic_mask_workflow.xml
to match your mask file naming convention.
Note
Mask file names must follow the Tracx naming convention
ChannelName_positionXXYYZZZ_timeTTTT.tif. If your mask files use a
different naming scheme, use the ParseFileNames and ConvertFileNames
workflow steps or the file name converter in the GUI before running the
generic-mask pipeline.
Inline call mode¶
The --call flag provides direct access to any method reachable from the
Tracker object without needing a workflow file. This is useful for interactive
debugging, ad-hoc queries, and wrapper scripts that need to extract a specific
value from a tracked dataset.
The method is identified by a dotted path relative to the Tracker instance.
Arguments are supplied with repeated --call-arg flags. If the called method
returns a value it is serialised as CSV and printed to standard output (without
any timestamp or prefix), making the output suitable for capture by a calling
process.
TracXRunner <source> --call <method.path> [--call-arg <value>] ... [--call-out <file>]
Retrieve a data property for the full experiment and write to a file:
./run_tracx.sh state.mat \
--call data.getFieldArray \
--call-arg "'track_index'" \
--call-arg 1 \
--call-out track_indices.csv
Retrieve a property for a single track:
./run_tracx.sh state.mat \
--call data.getFieldArrayForTrackIndex \
--call-arg "'cell_area'" \
--call-arg 3 \
--call-out track3_area.csv
Call a parameter setter on a loaded state:
./run_tracx.sh state.mat \
--call configuration.ParameterConfiguration.setMaxCellCenterDisplacement \
--call-arg 25
Capture CSV output in a shell script:
./run_tracx.sh state.mat --call data.getFieldArray --call-arg "'cell_area'" \
> cell_areas.csv
The same functionality is available inside a workflow XML using the CallMethod
step, which accepts a Method parameter for the dotted path and a pipe-delimited
Args parameter for the argument list.
<Step name="CallMethod" abortOnError="false">
<Param name="Method" value="data.getFieldArray"/>
<Param name="Args" value="track_index|1"/>
<Param name="OutFile" value="track_indices.csv"/>
</Step>
Argument type inference¶
Arguments passed with --call-arg are converted to the appropriate MATLAB type
automatically using the following rules, applied in order.
Input string |
MATLAB type |
|---|---|
|
|
A numeric literal such as |
|
A string surrounded by single quotes such as |
|
Anything else |
|
Reproducing the demo analysis¶
The following commands reproduce the analysis from the Tracx demo dataset using the yeast S. cerevisiae experiment. Clone the demo data repository from https://gitlab.com/csb.ethz/tracx_demo_data before running these commands.
From MATLAB source:
demoDataPath = 'path/to/tracx_demo_data';
tracx_main( ...
fullfile(demoDataPath, 'scripts', ...
'TracX_Yeast_SCerevisiae_Experiment_Project.xml'), ...
'--workflow', 'yeast', ...
'--image-dir', fullfile(demoDataPath, 'data', 'yeast', ...
'scerevisiae', 'RawImages'), ...
'--seg-dir', fullfile(demoDataPath, 'data', 'yeast', ...
'scerevisiae', 'CellXSegmentation', 'mKO_mKate'), ...
'--verbose');
From compiled executable on Linux:
DEMO=/path/to/tracx_demo_data
./run_tracx.sh \
"$DEMO/scripts/TracX_Yeast_SCerevisiae_Experiment_Project.xml" \
--workflow yeast \
--image-dir "$DEMO/data/yeast/scerevisiae/RawImages" \
--seg-dir "$DEMO/data/yeast/scerevisiae/CellXSegmentation/mKO_mKate" \
--verbose
From compiled executable on Windows:
set DEMO=C:\path\to\tracx_demo_data
run_tracx.bat ^
"%DEMO%\scripts\TracX_Yeast_SCerevisiae_Experiment_Project.xml" ^
--workflow yeast ^
--image-dir "%DEMO%\data\yeast\scerevisiae\RawImages" ^
--seg-dir "%DEMO%\data\yeast\scerevisiae\CellXSegmentation\mKO_mKate" ^
--verbose
The --image-dir and --seg-dir overrides are required because the paths
stored in the demo project XML are placeholders that need to point to your local
copy of the data.
Parameter tuning workflow¶
Before committing to a full tracking run on a new dataset, it is advisable to
run the tuning workflow to verify that the tracking and lineage reconstruction
parameters are appropriate. The tuning workflow executes a short tracking dry run,
tests the bud-neck segmentation, and tests the marker tracking, then saves the
updated project XML with whatever parameter adjustments you have applied.
The general procedure is as follows. First create the project XML, then run the
tuning workflow and inspect the control images it produces, adjust parameters in
the project XML or by re-running with different --create-* flags, and repeat
until the results are satisfactory. Finally, run the full workflow.
Step 1: Create the project XML.
./run_tracx.sh \
--create-project \
--create-name MyExperiment \
--create-image-dir /data/RawImages \
--create-seg-dir /data/CellXResults \
--create-fp-channel BFdivide \
--create-lineage-ch mKate \
--create-movie-length 30 \
--create-division-type asym
Step 2: Run the tuning workflow and inspect the control images.
./run_tracx.sh MyExperiment_Project.xml --workflow tuning --verbose
Step 3: When satisfied, run the full yeast workflow.
./run_tracx.sh MyExperiment_Project.xml --workflow yeast
Note
The test steps in the tuning workflow (TestParameters, TestBudNeck,
TestMarkerTracking) open popup images when running from the MATLAB source.
When running from the compiled executable in a headless environment, these
steps will complete without displaying images but will write the control
images to the tracker results directory if WriteControlImages is set to
true in the workflow XML.
Batch processing¶
For experiments consisting of many well positions or time-lapse series, the
recommended approach is to create one project XML per position and then run the
CLI in a loop. The --output override ensures each position writes its results
to a dedicated directory.
Bash loop over positions:
for pos in position0101000 position0102000 position0103000; do
./run_tracx.sh "${pos}_Project.xml" \
--workflow yeast \
--image-dir "/data/RawImages/${pos}" \
--seg-dir "/data/CellXResults/${pos}" \
--output "/results/${pos}" \
--log "/logs/${pos}.log"
done
Submitting to a SLURM cluster:
for pos in position0101000 position0102000 position0103000; do
sbatch --job-name="tracx_${pos}" \
--output="/logs/${pos}.slurm.log" \
--wrap="./run_tracx.sh ${pos}_Project.xml \
--workflow yeast \
--image-dir /data/RawImages/${pos} \
--seg-dir /data/CellXResults/${pos} \
--output /results/${pos}"
done
Each job runs independently. The --log flag writes a timestamped log to disk
in addition to the standard output captured by the cluster scheduler, which is
useful for post-hoc inspection.