trackscan 0.0.1__tar.gz

trackscan-0.0.1/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: trackscan
+Version: 0.0.1
+Summary: Post-processing and analysis of cell track data
+Author: Chris Viets
+Project-URL: Homepage, https://github.com/cviets/trackscan
+Project-URL: Bug Tracker, https://github.com/cviets/trackscan/issues
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+
+<h2 align="center">Track Scan</h2>
+A Python package for post-processing and analyzing cell track data. Includes functionality for correcting automated tracking artifacts, measuring mean squared displacements, and measuring cell turning angles.
+
+## Cite
+```bibtex
+@inbook{viets_measuring_2025,
+author = {Viets, Chris and Stevens, Corey A.},
+editor = {Brockhausen, Inka},
+title = {Measuring and Analyzing Bacterial Movement in Mucus},
+bookTitle = {Dynamics of Bacteria-Mucus Interactions},
+year = {2025},
+publisher = {Springer US},
+address = {New York, NY},
+pages = {187--197},
+isbn = {978-1-0716-4627-4},
+doi = {10.1007/978-1-0716-4627-4_16},
+url = {https://doi.org/10.1007/978-1-0716-4627-4_16}
+}
+
+```
+
+## Installation
+```
+pip install trackscan
+```
+
+## Usage
+The first step to using `trackscan` is to read in a CSV file containing (note that the CSV file must contain columns labeled "Position_X", "Position_Y", "Frame", and "Track_ID -- not case-sensitive).
+```
+trackscan -i /path/to/track_data.csv
+```
+This command launches an interactive shell where the track data can be manipulated and measured. Once the interactive shell has appeared, simply type `?` to view the available commands. For example, the interactive shell contains commands to de-drift track data, correct artifacts arising from automated tracking, and measure mean squared displacement, turning angles, or mean cell speed.

trackscan-0.0.1/README.md

@@ -0,0 +1,32 @@
+<h2 align="center">Track Scan</h2>
+A Python package for post-processing and analyzing cell track data. Includes functionality for correcting automated tracking artifacts, measuring mean squared displacements, and measuring cell turning angles.
+
+## Cite
+```bibtex
+@inbook{viets_measuring_2025,
+author = {Viets, Chris and Stevens, Corey A.},
+editor = {Brockhausen, Inka},
+title = {Measuring and Analyzing Bacterial Movement in Mucus},
+bookTitle = {Dynamics of Bacteria-Mucus Interactions},
+year = {2025},
+publisher = {Springer US},
+address = {New York, NY},
+pages = {187--197},
+isbn = {978-1-0716-4627-4},
+doi = {10.1007/978-1-0716-4627-4_16},
+url = {https://doi.org/10.1007/978-1-0716-4627-4_16}
+}
+
+```
+
+## Installation
+```
+pip install trackscan
+```
+
+## Usage
+The first step to using `trackscan` is to read in a CSV file containing (note that the CSV file must contain columns labeled "Position_X", "Position_Y", "Frame", and "Track_ID -- not case-sensitive).
+```
+trackscan -i /path/to/track_data.csv
+```
+This command launches an interactive shell where the track data can be manipulated and measured. Once the interactive shell has appeared, simply type `?` to view the available commands. For example, the interactive shell contains commands to de-drift track data, correct artifacts arising from automated tracking, and measure mean squared displacement, turning angles, or mean cell speed.

trackscan-0.0.1/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trackscan"
+version = "0.0.1"
+description = "Post-processing and analysis of cell track data"
+readme = "README.md"
+requires-python = ">=3.6"
+authors = [
+    { name = "Chris Viets" }
+]
+dependencies = [
+    "numpy",
+    "matplotlib"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/cviets/trackscan"
+"Bug Tracker" = "https://github.com/cviets/trackscan/issues"
+
+[project.scripts]
+cell_track = "cell_track.cli:main"

trackscan-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

trackscan-0.0.1/src/cell_track.egg-info/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: cell_track
+Version: 0.0.1
+Summary: Post-processing and analysis of cell track data
+Author: Chris Viets
+Project-URL: Homepage, https://github.com/cviets/trackscan
+Project-URL: Bug Tracker, https://github.com/cviets/trackscan/issues
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+
+<h2 align="center">Track Scan</h2>
+A Python package for post-processing and analyzing cell track data. Includes functionality for correcting automated tracking artifacts, measuring mean squared displacements, and measuring cell turning angles.
+
+## Cite
+```bibtex
+@inbook{viets_measuring_2025,
+author = {Viets, Chris and Stevens, Corey A.},
+editor = {Brockhausen, Inka},
+title = {Measuring and Analyzing Bacterial Movement in Mucus},
+bookTitle = {Dynamics of Bacteria-Mucus Interactions},
+year = {2025},
+publisher = {Springer US},
+address = {New York, NY},
+pages = {187--197},
+isbn = {978-1-0716-4627-4},
+doi = {10.1007/978-1-0716-4627-4_16},
+url = {https://doi.org/10.1007/978-1-0716-4627-4_16}
+}
+
+```
+
+## Installation
+```
+pip install trackscan
+```
+
+## Usage
+The first step to using `trackscan` is to read in a CSV file containing (note that the CSV file must contain columns labeled "Position_X", "Position_Y", "Frame", and "Track_ID -- not case-sensitive).
+```
+trackscan -i /path/to/track_data.csv
+```
+This command launches an interactive shell where the track data can be manipulated and measured. Once the interactive shell has appeared, simply type `?` to view the available commands. For example, the interactive shell contains commands to de-drift track data, correct artifacts arising from automated tracking, and measure mean squared displacement, turning angles, or mean cell speed.

trackscan-0.0.1/src/cell_track.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+src/cell_track.egg-info/PKG-INFO
+src/cell_track.egg-info/SOURCES.txt
+src/cell_track.egg-info/dependency_links.txt
+src/cell_track.egg-info/entry_points.txt
+src/cell_track.egg-info/requires.txt
+src/cell_track.egg-info/top_level.txt
+src/trackscan/__init__.py
+src/trackscan/cli.py
+src/trackscan/modules/analysis_utils.py
+src/trackscan/modules/curve_fitting.py
+src/trackscan/modules/io_utils.py
+src/trackscan/modules/linking_functions.py
+src/trackscan/modules/make_tracks.py
+src/trackscan/modules/msd_analysis.py
+src/trackscan/modules/track_manipulations.py
+src/trackscan/modules/visualization_utils.py

trackscan-0.0.1/src/cell_track.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

trackscan-0.0.1/src/cell_track.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cell_track = cell_track.cli:main

trackscan-0.0.1/src/cell_track.egg-info/requires.txt

@@ -0,0 +1,2 @@
+numpy
+matplotlib

trackscan-0.0.1/src/cell_track.egg-info/top_level.txt

@@ -0,0 +1 @@
+trackscan

trackscan-0.0.1/src/trackscan/cli.py

@@ -0,0 +1,13 @@
+import argparse
+from .modules.make_tracks import Tracks
+
+def main():
+    parser = argparse.ArgumentParser("Cell track post-processing and analysis")
+    parser.add_argument("-i", "--input", type=str, required=True, help="Path to CSV file containing tracking data.")
+    args = parser.parse_args()
+
+    tracks = Tracks(args.input)
+    tracks.cmdloop()
+
+if __name__ == '__main__':
+    main()

trackscan-0.0.1/src/trackscan/modules/analysis_utils.py

@@ -0,0 +1,51 @@
+from typing import List, Dict, Union
+import numpy as np
+from numpy.typing import NDArray
+from tqdm import tqdm
+
+def turning_angle_analysis(tracks: List[Dict[str, Union[int, float]]], dt: int) -> NDArray[np.float64]:
+
+    out = []
+    for cell in tqdm(tracks, desc="Computing turning angles"):
+
+        t = np.array(cell['t'])
+        idx_t0, idx_t1 = get_timelag_indices(t, dt)
+        vx = np.gradient(cell['x'], t)
+        vy = np.gradient(cell['y'], t)
+
+        velocities_final = np.array([vx[idx_t1], vy[idx_t1]]).T
+        velocities_initial = np.array([vx[idx_t0], vy[idx_t0]]).T
+
+        for i in range(len(velocities_final)):
+            u = velocities_initial[i]
+            v = velocities_final[i]
+
+            angle = np.arctan2(u[0]*v[1] - u[1]*v[0], u[0]*v[0] + u[1]*v[1])
+            out.append(angle)
+    return np.array(out)*180/np.pi
+    
+def get_timelag_indices(t: NDArray[np.int_], tau: int):
+    
+    t1_vals = t[t>=tau]
+    indices_t1 = np.searchsorted(t,t1_vals)
+    indices_t0 = np.searchsorted(t,t1_vals-tau)
+    
+    valid_indices = t[indices_t0] == t1_vals - tau
+    indices_t0 = indices_t0[valid_indices]
+    indices_t1 = indices_t1[valid_indices]
+
+    return indices_t0, indices_t1
+
+def get_ensemble_mean_speed(tracks: List[Dict[str, Union[int, float]]]) -> float:
+    
+    means = np.zeros(shape=len(tracks))
+    for i, cell in tqdm(enumerate(tracks), desc="Computing mean speed"):
+        t = np.array(cell['t'])
+        vx = np.gradient(cell['x'], t)
+        vy = np.gradient(cell['y'], t)
+        speeds = np.sqrt(vx**2+ vy**2)
+        means[i] = np.mean(speeds)
+
+    return np.mean(means)
+
+        

trackscan-0.0.1/src/trackscan/modules/curve_fitting.py

@@ -0,0 +1,127 @@
+import numpy as np
+from numpy.linalg import inv
+from typing import List, Tuple
+from numpy.typing import NDArray
+
+def get_lsq_solution(n: int, f: int, t: List) -> Tuple[List, NDArray]:
+    """
+    Returns least squares n-degree polynomial fit to y = f(t).
+    Parameters
+    ----------
+    n : int
+        polynomial degree 
+    f : list
+        y values
+    t : list
+        x values
+
+    Returns
+    -------
+    beta : array
+        fitted parameters
+    cov : 2d array
+        covariances of parameters
+
+    """
+    A = np.array([[j**i for i in range(n, -1, -1)] for j in t])
+    AT = np.transpose(A)
+    cov = inv(np.matmul(AT, A))
+    beta = np.matmul(np.matmul(cov, AT), f)
+    beta = list(reversed(beta))
+    return beta, cov
+
+def least_squares(n: int, f: List[int], t: List[int], return_error: bool=False):
+    """
+    fit f, t to a n-degree polynomial. 
+    Returns best-fit polynomial as a function with input x
+    """
+    
+    A = np.array([[j**i for i in range(n, -1, -1)] for j in t])
+    AT = np.transpose(A)
+    cov = inv(np.matmul(AT, A))
+    beta = np.matmul(np.matmul(cov, AT), f)
+    beta = list(reversed(beta))
+    
+    beta, _ = get_lsq_solution(n, f, t)
+    
+    return lambda x: sum(beta[i]*x**i for i in range(len(beta)))
+
+def least_squares_error(n, f, t):
+    """
+    Returns functions corresponding to +/- 1 sigma in the error of the least-squares
+    n-degree polynomial fit to y = f(t). In other words, f(t) should fit within inf(t)
+    and sup(t) most of the time. May not be super reliable.
+    
+    inf: function corresponding to 1 sigma below the best fit. inf(t) < fit(t) < sup(t)
+    sup: function corresponding to 1 sigma above best fit.
+    """
+    
+    beta, cov = get_lsq_solution(n, f, t)
+    F = lambda x: sum(beta[i]*x**i for i in range(len(beta)))
+    
+    S = sum((F(T) - f[i])**2 for i, T in enumerate(t))
+    var_beta = list(reversed([cov[i][i]*S/(len(f)-n) for i in range(len(beta))]))
+    sup = lambda x: sum((beta[i]+np.sqrt(var_beta[i]))*x**i 
+                        for i in range(len(beta)))
+    inf = lambda x: sum((beta[i]-np.sqrt(var_beta[i]))*x**i 
+                        for i in range(len(beta)))
+    
+    return inf, sup
+
+def fit_recent(f, t):
+    """
+    Returns a list that fits y = f(t) based on its previous values. Fit at time 
+    i is determined by fitting a parabola to the previous four values 
+    (f(t=i-5) to f(t=i-1)). I.e., fits f(t) using its most recent values.
+    """
+    
+    assert len(f) >= 5, "f must have length >= 5 for accurate predictions"
+    prediction = f[0:4]
+    for i in range(len(f)-4):
+        sub_f = f[i:i+4]
+        sub_t = t[i:i+4]
+        F = least_squares(2, sub_f, sub_t)
+        prediction.append(F(t[i+4]))
+        
+    return prediction
+    
+
+def find_breakpoints(f, t):
+    """
+    Finds where f(t) changes abruptly, as determined by when it deviates significantly
+    from fit determined by fit_recent.
+    
+    Returns idx: set of indices where f changes abruptly.
+    """
+    F = fit_recent(f, t)
+    residuals = [F[i]-f[i] for i in range(len(f))]
+    for i in range(4, len(residuals)):
+        if residuals[i] == 0:
+            return set()
+    res2 = [r**2 for r in residuals]
+    partial_sums = [res2[i] + res2[i+1] + res2[i+2] for i in range(len(res2) - 2)]
+    ssr = sum(res2)
+    expected_res2 = ssr/len(res2)
+    exp_partial_sums = [0, 0, expected_res2, expected_res2*2]
+    exp_partial_sums.extend([expected_res2*3 for _ in range(len(partial_sums)-4)])
+    # standard deviation of each residual:
+    rmsd = np.sqrt(ssr/(len(t) - 2))
+    # standard deviations of the squared residuals:
+    d_res2 = [2*abs(x)*rmsd for x in residuals]
+    d_partial_sums = [np.sqrt(d_res2[i]**2 + d_res2[i+1]**2 + d_res2[i+2]**2) for i in range(len(res2) - 2)]
+    z_scores = [(partial_sums[i] - exp_partial_sums[i])/d_partial_sums[i] for i in range(2, len(partial_sums))]
+    res2_z_scores = [(res2[i] - expected_res2)/d_res2[i] for i in range(4, len(res2))]
+    idx = {i+1 for i in range(2, len(z_scores)) if z_scores[i]>2 and res2_z_scores[i-2] > 2}
+    
+    removals = {i for i in idx if i-1 in idx or i-2 in idx}
+    idx -= removals
+    
+    return idx
+
+def get_squared_distance_between_curves(x, f, g):
+    """
+    For array-like x and functions f, g of x, returns sum([(f(x) - g(x))]**2) 
+    over all x in the specified interval
+
+    """
+    return sum([f(X) - g(X)]**2 for X in x)

trackscan-0.0.1/src/trackscan/modules/io_utils.py

@@ -0,0 +1,110 @@
+import csv
+from typing import Dict, Union, List
+from tqdm import tqdm
+import os
+from .track_manipulations import sort_track_by_time
+from numpy.typing import NDArray
+import numpy as np
+
+def load_data_from_csv(filename: str) -> List[Dict[str, Union[float, int]]]:
+
+    with open(os.path.expanduser(filename), newline='') as csvfile:
+        
+        csv_read = csv.reader(csvfile,delimiter=',')
+        
+        prev_cell = None
+        cur_dict = {'x': [], 'y': [], 't': []}
+        tracks = []
+
+        header = next(csv_read)
+        header = [elt.upper() for elt in header]
+        assert "POSITION_X" in header, "File header must contain `POSITION_X` column"
+        assert "POSITION_Y" in header, "File header must contain `POSITION_Y` column"
+        assert "FRAME" in header, "File must contain `FRAME` column"
+        assert "TRACK_ID" in header, "File must contain `TRACK_ID` column"
+
+        counter = [0,0,0,0]
+        for i, label in enumerate(header):
+            if label == "POSITION_X":
+                x_column = i
+                counter[0] += 1
+            elif label == "POSITION_Y":
+                y_column = i
+                counter[1] += 1
+            elif label == "FRAME":
+                t_column = i
+                counter[2] += 1
+            elif label == "TRACK_ID":
+                cell_column = i
+                counter[3] += 1
+
+        assert counter == [1,1,1,1], "Position_x, Position_y, Frame, and Track_ID columns must each appear exactly once"
+            
+        for i, row in tqdm(enumerate(csv_read)):
+            
+            if row[x_column] == '' or not all([elt in '0123456789,. ' for elt in row[x_column]]):
+                continue
+            
+            cur_cell = row[cell_column]
+            x = row[x_column]
+            y = row[y_column]
+            t = row[t_column]
+            
+            if cur_cell != prev_cell and prev_cell is not None:
+                sort_track_by_time(cur_dict)
+                tracks.append(cur_dict)
+                cur_dict = {'x': [], 'y': [], 't': []}
+            
+            cur_dict['x'].append(float(x))
+            cur_dict['y'].append(float(y))
+            cur_dict['t'].append(int(float(t)))
+
+            prev_cell = cur_cell
+    
+    sort_track_by_time(cur_dict)
+    tracks.append(cur_dict) 
+
+    return tracks
+
+def save_track_data(track_data, filename: str, label=None) -> None:
+    with open(os.path.expanduser(filename), 'w', newline = '') as csvfile:
+        csv_write = csv.writer(csvfile)
+        header = [''] * 4
+        header[0] = 'TRACK_ID'
+        header[1] = 'POSITION_X'
+        header[2] = 'POSITION_Y'
+        header[3] = 'FRAME'
+        
+        csv_write.writerow(header)
+        cur_cell = 0
+        for cell in tqdm(track_data):
+            cur_cell += 1
+            for i, x in enumerate(cell['x']):
+                newrow = [''] * 4
+                if label is None:
+                    newrow[0] = str(cur_cell)
+                else:
+                    newrow[0] = label
+                newrow[1] = x
+                newrow[2] = cell['y'][i]
+                newrow[3] = cell['t'][i]
+                
+                csv_write.writerow(newrow)
+
+def save_MSD_data(filename: str, t: List[int], y: List[float], dy: List[float]) -> None:
+    
+    assert len(t) == len(y), "Input lists must have same length"
+    assert len(t) == len(dy), "Input lists must have same length"
+
+    with open(os.path.expanduser(filename), 'w', newline='') as csvfile:
+        writer = csv.writer(csvfile)
+        writer.writerow(["Time Lag", "MSD", "Error_MSD"])
+        for i, elt in tqdm(enumerate(t)):
+            writer.writerow([str(elt), str(y[i]), str(dy[i])])
+
+def save_turning_angles_data(filename: str, data: NDArray[np.float64], dt: int) -> None:
+    with open(os.path.expanduser(filename), 'w', newline='') as csvfile:
+        writer = csv.writer(csvfile)
+        writer.writerow([f"Turning angles [deg], delta_t={dt} frames"])
+        for elt in tqdm(data):
+            writer.writerow([str(elt)])

trackscan-0.0.1/src/trackscan/modules/linking_functions.py

@@ -0,0 +1,153 @@
+import numpy as np
+from .curve_fitting import least_squares
+from typing import Dict, List
+"""
+Start by finding candidates (newborn cells) to link to each cell when it dies. 
+`linking_candidates` is a dict: {cellid: {set of cell ids}}. 
+Keys indicate a cell that has died and value contains all cells that are candidates to link to key, 
+depending on whether they meet the max_time_gap and max_distance requirements. 
+No values in dict are empty sets.
+"""
+        
+def get_linking_candidates(track_dict: List[Dict], max_time_gap, max_distance: float):
+    """
+    Generates candidates of tracks to link to each track using criteria specified by parameters
+    """
+    linking_candidates = {i: set() for i in range(len(track_dict))}
+    
+    t_all = sorted({T for cell in track_dict for T in cell['t']})
+    queue = {time_gap: set() for time_gap in t_all 
+             if time_gap <= max_time_gap}
+    
+    remaining_cells = {i for i in range(len(track_dict))}
+    for t in t_all:
+        
+        # add newly dead cells to queue. 
+        # Remove checked cells from remaining_cells
+        queue[0] = {cell_id for cell_id in remaining_cells 
+                    if max(track_dict[cell_id]['t']) == t}
+        remaining_cells -= queue[0]
+        
+        # for cell in queue, check for newborns at distance <= max_distance
+        newborns = {cell_id for cell_id in remaining_cells 
+                    if min(track_dict[cell_id]['t']) == t}
+        cells_currently_in_queue = {c for cell_set in queue.values() 
+                                    for c in cell_set}
+        for dead_cell_id in cells_currently_in_queue:
+            dead_cell = track_dict[dead_cell_id]
+            death_point = (dead_cell['x'][-1], dead_cell['y'][-1])
+            for newborn_cell_id in newborns:
+                newborn_cell = track_dict[newborn_cell_id]
+                spawn_point = (newborn_cell['x'][0], newborn_cell['y'][0])
+                dist = np.sqrt((spawn_point[0] - death_point[0])**2 + 
+                               (spawn_point[1] - death_point[1])**2)
+                if dist <= max_distance:
+                    linking_candidates[dead_cell_id].add(newborn_cell_id)
+        # update queue such that queue[n+1] = queue[n], queue[0] = set()
+        time_gaps= sorted(queue.keys(), reverse=True)
+        for idx, time_gap in enumerate(time_gaps[:-1]):
+            queue[time_gap] = queue[time_gaps[idx+1]]
+        queue[0] = set()         
+    linking_candidates = {key: val 
+                          for key, val in linking_candidates.items() 
+                          if val != set()}
+    
+    return linking_candidates
+
+def choose_linking_partners(linking_candidates, track_dict):
+    """
+    Chooses best track to link using parabolic least squares fits to both tracks.
+    """
+    link_dict = {}
+    for dead_cell_id in linking_candidates:
+        min_dist = -1
+        best_candidate = -1
+        cell_1 = track_dict[dead_cell_id]
+        
+        # arbitrarily fit last 3 points of track to a quadratic
+        if len(cell_1['t']) >= 3:
+            t1_fit = cell_1['t'][-4:]
+            x1 = least_squares(2, cell_1['x'][-4:], t1_fit)
+            y1 = least_squares(2, cell_1['y'][-4:], t1_fit)
+        else:
+            x1 = least_squares(1, cell_1['x'], cell_1['t'])
+            y1 = least_squares(1, cell_1['y'], cell_1['t'])
+        
+        for spawn_cell_id in linking_candidates[dead_cell_id]: 
+            
+            cell_2 = track_dict[spawn_cell_id]
+                
+            if len(cell_2['t']) >= 3:
+                t2_fit = cell_2['t'][:4]
+                x2 = least_squares(2, cell_2['x'][:4], t2_fit)
+                y2 = least_squares(2, cell_2['y'][:4], t2_fit)
+            else:
+                x2 = least_squares(1, cell_2['x'], cell_2['t'])
+                y2 = least_squares(1, cell_2['y'], cell_2['t'])
+            
+            t_max = min(cell_2['t'])
+            t_min = max(cell_1['t'])
+            
+            t_all =  {T for cell in track_dict for T in cell['t'] 
+                      if T <= t_max and T >= t_min}
+            
+            
+            dist = sum(np.sqrt((x1(t) - x2(t))**2 + (y1(t) - y2(t))**2) 
+                       for t in t_all)/len(t_all)
+        
+            if dist < min_dist or min_dist == -1:
+                best_candidate = spawn_cell_id
+                min_dist = dist 
+                interpolation_domain = sorted(t_all)
+                x2_best = x2
+                y2_best = y2
+                
+        link_dict[dead_cell_id] = (best_candidate, interpolation_domain, 
+                                   (x1, y1), (x2_best, y2_best))
+        
+    return link_dict
+
+def link_partners(link_dict, track_dict):
+    """
+    Interpolates the space between tracks, links them, and deletes the old one.
+    """
+    
+    removals = set()
+    
+    while link_dict:
+        key_removals = set()
+        for key, (val, t_domain, (x1, y1), (x2, y2)) in link_dict.items():
+            if val not in link_dict:
+                
+                dead_cell = track_dict[key]
+                new_cell = track_dict[val]
+                
+                t_max = t_domain[-1]
+                t_min = t_domain[0]
+                
+                if t_max != t_min:
+                    weight = lambda t: (t - t_min)/(t_max - t_min)
+                else:
+                    weight = lambda t: 0.5
+                X = lambda t: (1 - weight(t)) * x1(t) + weight(t) * x2(t)
+                Y = lambda t: (1 - weight(t)) * y1(t) + weight(t) * y2(t)
+                
+                dead_cell['t'] = dead_cell['t'][:-1]
+                dead_cell['x'] = dead_cell['x'][:-1]
+                dead_cell['y'] = dead_cell['y'][:-1]
+                dead_cell['t'].extend(t_domain)
+                dead_cell['x'].extend([X(t) for t in t_domain])
+                dead_cell['y'].extend([Y(t) for t in t_domain])
+                dead_cell['t'].extend(new_cell['t'][1:])
+                dead_cell['x'].extend(new_cell['x'][1:])
+                dead_cell['y'].extend(new_cell['y'][1:])
+
+
+                key_removals.add(key)
+                removals.add(val)
+        for key in key_removals:
+            del link_dict[key]
+                
+    for idx in sorted(removals, reverse=True):
+        del track_dict[idx]
+    

trackscan-0.0.1/src/trackscan/modules/make_tracks.py

@@ -0,0 +1,232 @@
+from .linking_functions import get_linking_candidates, choose_linking_partners, link_partners
+from .io_utils import load_data_from_csv, save_track_data, save_MSD_data, save_turning_angles_data
+from .track_manipulations import scale_space, print_first_n, dedrift, split_tracks
+from .msd_analysis import msd, fit_msd
+from .analysis_utils import turning_angle_analysis, get_ensemble_mean_speed
+from .visualization_utils import plot_msd, plot_turning_angles
+import argparse
+import os
+import cmd
+import shlex
+
+class Tracks(cmd.Cmd):
+    intro = "Welcome to the trackscan command line interface for cell track post-processing and analysis.\n" \
+    "Type help or ? to list commands.\n"
+    prompt = "(trackscan) "
+
+    def __init__(self, filename: str):
+        """
+        Tracks object has filename and tracks attributes. 
+        
+        filename: file containing track data (must be .csv)
+        tracks: list of dicts with keys 'x', 'y', 't' and values list of x, y, 
+                and t data. Each dict represents one cell's track.
+        """
+        super().__init__()
+        self.tracks = load_data_from_csv(filename)
+        self.filename = filename 
+            
+    def do_scale_space(self, arg: str) -> None:
+        """Scale x and y data by a constant factor. Type scale_space -h to see available options."""
+
+        parser = argparse.ArgumentParser(prog="scale_space", add_help=False, formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+        parser.add_argument("-c", "--constant", default=1, type=float, help="Scale x and y data by a constant factor")
+        parser.add_argument("-h", "--help", action="help", help="Show this message")
+
+        try:
+            args = parser.parse_args(shlex.split(arg))
+        except SystemExit:
+            return
+        
+        scale_space(self.tracks, args.constant)
+
+    def do_show(self, arg: str) -> None:
+        """Print the first n lines of track data. Type show -h to see available options."""
+        parser = argparse.ArgumentParser(prog="show", add_help=False, formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+        parser.add_argument("-n", "--n", default=5, type=int, help="Print the first n lines of track data.")
+        parser.add_argument("-h", "--help", action="help", help="Show this message")
+
+        try:
+            args = parser.parse_args(shlex.split(arg))
+        except SystemExit:
+            return
+        
+        print_first_n(self.tracks, args.n)
+    
+    def do_save(self, arg: str) -> None:
+        """Save cell track data in CSV format. Type save -h to see available options."""
+
+        root_name, ext = os.path.splitext(self.filename)
+        default_filename = root_name + "PROCESSED" + ext
+
+        parser = argparse.ArgumentParser(prog="save", add_help=False, formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+        parser.add_argument("-o", "--out", default=default_filename, type=str, help="Path to CSV file to save data")
+        parser.add_argument("-h", "--help", action="help", help="Show this message")
+        
+        try:
+            args = parser.parse_args(shlex.split(arg))
+        except SystemExit:
+            return
+
+        save_track_data(self.tracks, args.output)
+                    
+    def do_dedrift(self, arg: str) -> None:
+        """Dedrift track data by cell-averaged velocity at each timepoint. Type dedrift -h to see available options."""
+
+        parser = argparse.ArgumentParser(prog="dedrift", add_help=False, formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+        parser.add_argument("-s", "--save", type=bool, default=False, help="Whether to save the drift velocities")
+        parser.add_argument("-o", "--out", type=str, default="", help="Path to CSV file to save drift velocities if --save is True")
+        parser.add_argument("-h", "--help", action="help", help="Show this message")
+
+        try:
+            args = parser.parse_args(shlex.split(arg))
+        except SystemExit:
+            return
+        
+        drift_velocities = dedrift(self.tracks)
+        if args.save:
+            save_track_data([drift_velocities], args.out, label="DRIFT")
+            
+    def do_link(self, arg:str) -> None:
+        """
+        Links tracks together by identifying candidates and choosing best one.
+        """
+
+        parser = argparse.ArgumentParser(prog="link", add_help=False, formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+        parser.add_argument("-t", "--time", type=int, default=3, help="Max time gap to consider linking two tracks")
+        parser.add_argument("d", "--dist", type=float, default=10, help="Max distance to consider linking two tracks")
+        parser.add_argument("-h", "--help", action="help", help="Show this message")
+
+        try:
+            args = parser.parse_args(shlex.split(arg))
+        except SystemExit:
+            return
+        
+        linking_candidates = get_linking_candidates(self.tracks, args.time, args.dist)
+        link_dict = choose_linking_partners(linking_candidates, self.tracks)
+        link_partners(link_dict, self.tracks)
+    
+    def do_split(self, arg: str) -> None:
+        """
+        Splits tracks where abrupt changes in direction occur.
+        """
+        parser = argparse.ArgumentParser(prog="split", add_help=False, formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+        parser.add_argument("-h", "--help", action="help", help="Show this message")
+
+        try:
+            args = parser.parse_args(shlex.split(arg))
+        except SystemExit:
+            return
+        
+        split_tracks(self.tracks)
+
+    def do_correct_artifacts(self, arg:str) -> None:
+        """
+        Fix tracking artifacts by first splitting tracks at locations of artifacts, then linking tracks correctly
+        """ 
+
+        parser = argparse.ArgumentParser(prog="correct_artifacts", add_help=False, formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+        parser.add_argument("-t", "--time", type=int, default=3, help="Max time gap to consider linking two tracks")
+        parser.add_argument("d", "--dist", type=float, default=10, help="Max distance to consider linking two tracks")
+        parser.add_argument("-h", "--help", action="help", help="Show this message")
+
+        try:
+            args = parser.parse_args(shlex.split(arg))
+        except SystemExit:
+            return
+        
+        print("Splitting tracks...")
+        split_tracks(self.tracks)
+        print("Linking tracks...")
+        linking_candidates = get_linking_candidates(self.tracks, args.time, args.dist)
+        link_dict = choose_linking_partners(linking_candidates, self.tracks)
+        link_partners(link_dict, self.tracks)
+
+    def do_MSD_analysis(self, arg:str) -> None:
+        """Compute mean squared displacements"""
+
+        root_name, ext = os.path.splitext(self.filename)
+        default_filename = root_name + "_MSD" + ext
+
+        parser = argparse.ArgumentParser(prog="MSD_analysis", add_help=False, formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+        parser.add_argument("-o", "--out", type=str, default=default_filename, help="Path to CSV file to save MSD data")
+        parser.add_argument("-p", "--plot", type=bool, default=False, help="Whether to output a plot of MSD data")
+        parser.add_argument("-h", "--help", action="help", help="Show this message")
+
+        try:
+            args = parser.parse_args(shlex.split(arg))
+        except SystemExit:
+            return
+        
+        t, y, dy = msd(self.tracks)
+        save_MSD_data(args.out, t, y, dy)
+
+        if args.plot:
+            root_name, ext = os.path.splitext(args.out)
+            save_to = root_name + "_MSD_plot" + ".png"
+
+            (a, d), (a_err, D_err), r2 = fit_msd(t, y, (1, len(t)//2))
+            plot_msd(save_to, t, y, dy, a, d, a_err, D_err, r2)
+
+    def do_turning_angle(self, arg:str) -> None:
+        """
+        Compute turning angles across a specified time
+        """
+
+        root_name, ext = os.path.splitext(self.filename)
+        default_filename = root_name + "_turning_angles" + ext
+
+        parser = argparse.ArgumentParser(prog="turning_angles", add_help=False, formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+        parser.add_argument("-t", "--time", type=int, default=10, help="Time lag to calculate turning angles")
+        parser.add_argument("-o", "--out", type=str, default=default_filename, help="Path to CSV file to save turning angle data")
+        parser.add_argument("-p", "--plot", type=bool, default=False, help="Whether to output a plot of turning angle data")
+        parser.add_argument("-h", "--help", action="help", help="Show this message")
+
+        try:
+            args = parser.parse_args(shlex.split(arg))
+        except SystemExit:
+            return
+        
+        if args.time <= 0:
+            print("turning_angle: time must be positive")
+            return
+        
+        turning_angles = turning_angle_analysis(self.tracks, args.time)
+        save_turning_angles_data(args.out, turning_angles, args.time)
+
+        if args.plot:
+            root_name, ext = os.path.splitext(args.out)
+            save_to = root_name + "_turning_angles_plot" + ".png"
+            plot_turning_angles(save_to, turning_angles)    
+        
+
+    
+    def do_mean_speed(self, arg:str) -> None:
+        """Measure and print ensemble mean cell speed"""
+
+        parser = argparse.ArgumentParser(prog="mean_speed", add_help=False, formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+        parser.add_argument("-h", "--help", action="help", help="Show this message")
+
+        try:
+            args = parser.parse_args(shlex.split(arg))
+        except SystemExit:
+            return
+        print(get_ensemble_mean_speed(self.tracks))
+        
+
+    def do_exit(self, arg:str) -> bool:
+        """Exit the program"""
+        return True
+    
+    
+    def get_cell_mean_stepsize(self, cell):
+        dists = []
+        for i in range(1, len(cell['t'])):
+            cur_x = cell['x'][i]
+            prev_x = cell['x'][i-1]
+            
+            cur_y = cell['y'][i]
+            prev_y = cell['y'][i-1]
+            dists.append(((cur_x - prev_x)**2 + (cur_y - prev_y)**2)**(1/2))
+            
+        return sum(dists)/len(dists)

trackscan-0.0.1/src/trackscan/modules/msd_analysis.py

@@ -0,0 +1,65 @@
+from scipy.stats import linregress
+import numpy as np
+import matplotlib.pyplot as plt
+from typing import List, Sequence
+from tqdm import tqdm
+import os
+from .analysis_utils import get_timelag_indices
+
+def msd_fit(x,alpha,D):
+    
+    return 4*D*x**alpha
+
+def msd(track_dict):
+    
+    # get all possible tau values
+    tau = set()
+    for cell in track_dict:
+        tau.update({t - cell['t'][0] for t in cell['t']})
+    tau = sorted(tau)
+    raw_data = {T: [] for T in tau}
+    
+    for cell in tqdm(track_dict, desc="Computing MSDs"):
+        
+        for tau_ in tau:
+        
+            t = np.array(cell['t'])
+            indices_t0, indices_t1 = get_timelag_indices(t, tau_)
+            
+            x = np.array(cell['x'])
+            y = np.array(cell['y'])
+            dx = x[indices_t1] - x[indices_t0]
+            dy = y[indices_t1] - y[indices_t0]
+            squared_disp = dx**2 + dy**2
+            
+            raw_data[tau_].extend(squared_disp)
+    
+    MSDs = [np.mean(raw_data[tau_]) for tau_ in tau]
+    dMSDs = [np.std(raw_data[tau_])/np.sqrt(len(raw_data[tau_])) for tau_ in tau]
+    # hack to avoid infinite error at zeroth timepoint
+    dMSDs[0] = dMSDs[1]
+    
+    return tau, MSDs, dMSDs
+
+    
+def fit_msd(t: List[int], y: List[float], fit_window: Sequence[int]):
+
+    for i in range(1, len(t)):
+        assert t[i] > t[i-1], "Time data must be sorted."
+        
+    [fit_from, fit_to] = fit_window
+    
+    xfit = np.log(t[fit_from:fit_to])
+    yfit = np.log(y[fit_from:fit_to])
+    
+    LinReg = linregress(xfit, yfit)
+    alpha = LinReg.slope
+    diffusivity = np.exp(LinReg.intercept)/4
+    
+    alpha_err = LinReg.stderr
+    diffusivity_err = diffusivity*LinReg.intercept_stderr
+    
+    return (alpha, diffusivity), (alpha_err, diffusivity_err), LinReg.rvalue**2
+
+
+    

trackscan-0.0.1/src/trackscan/modules/track_manipulations.py

@@ -0,0 +1,118 @@
+from typing import Dict, List, Union, Tuple
+import numpy as np
+from .curve_fitting import find_breakpoints
+
+def scale_space(track_data: List[Dict[str, Union[int, float]]], factor: float) -> None:
+    """
+    Scale all x and y values by factor.
+    """
+    for cell in track_data:
+        cell['x'] = [x*factor for x in cell['x']]
+        cell['y'] = [y*factor for y in cell['y']]
+
+def print_first_n(track_data: List[Dict[str, Union[int, float]]], n: int=5) -> None:
+    count = 0
+    cell_num = 0
+    idx = 0
+
+    header = ["Track ID", "Position_X", "Position_Y", "Frame"]
+
+    print(f"{header[0]:^12}", "|", f"{header[1]:^12}", "|", f"{header[2]:^12}", "|", f"{header[3]:^12}")
+    while count < n:
+        cur_cell = track_data[cell_num]
+        if idx >= len(cur_cell['x']):
+            idx = 0
+            cell_num += 1
+            cur_cell = track_data[cell_num]
+
+        print(f"{cell_num:<12}", "|", f"{cur_cell['x'][idx]:<12.2f}", "|", f"{cur_cell['y'][idx]:<12.2f}", "|", f"{cur_cell['t'][idx]:<12}")
+        idx += 1
+        count += 1
+
+def sort_track_by_time(track_dict: Dict[str, Union[int, float]]) -> None:
+    """
+    Track data is often not ordered chronologically. 
+    This function ensures that position and time data are chronologoically ordered.
+    Acts in place.
+    """
+    i_sort = np.argsort(track_dict['t'])
+    track_dict['t'] = list(np.array(track_dict['t'])[i_sort])
+    track_dict['x'] = list(np.array(track_dict['x'])[i_sort])
+    track_dict['y'] = list(np.array(track_dict['y'])[i_sort])
+
+def dedrift(track_data: List[Dict[str, Union[int, float]]]) -> Dict[int, Tuple[float, float]]:
+        """
+        Mutates track_data  to dedrift all tracks using mean velocity at every 
+        time point. Returns mean velocity at every time point.
+        """
+        velocities = {t: [] for cell in track_data for t in cell['t']}
+        del velocities[min(velocities.keys())]
+        
+        for cell in track_data:
+            for i in range(1,len(cell['t'])):
+                
+                dx = cell['x'][i] - cell['x'][i-1]
+                dy = cell['y'][i] - cell['y'][i-1]
+                
+                velocities[cell['t'][i]].append((dx, dy))
+
+        # get mean velocity at each available time point        
+        vbar = {t: (sum(elt[0] for elt in velocities[t])/len(velocities[t]), 
+                    sum(elt[1] for elt in velocities[t])/len(velocities[t])) 
+                for t in velocities}
+        
+        # subtract summed drift velocities from each available timepoint
+        for cell in track_data:
+            for i,t in enumerate(cell['t']):
+                if i == 0:
+                    continue
+                cell['x'][i] -= sum(vbar[T][0] for T in cell['t'][1:i+1])
+                cell['y'][i] -= sum(vbar[T][1] for T in cell['t'][1:i+1])
+
+        out = {'x': [], 'y': [], 't': []}
+        for key, val in vbar.items():
+            out['t'].append(int(key))
+            out['x'].append(val[0])
+            out['y'].append(val[1])
+        sort_track_by_time(out)
+        return out
+
+def split_tracks(self) -> None:
+    """
+    Splits tracks where abrupt changes in direction occur.
+    """
+    
+    new_tracks = []
+    
+    for i, cell in enumerate(self.tracks):
+        
+        X = cell['x']
+        if len(X) <= 4:
+            continue
+        
+        Y = cell['y']
+        T = cell['t']
+        
+        x_brks = find_breakpoints(X, T)
+        y_brks = find_breakpoints(Y, T)
+        
+        brks = x_brks.union(y_brks)
+        
+        removals = set()
+        for idx in brks:
+            if idx - 1 in brks or idx - 2 in brks:
+                removals.add(idx)
+        brks -= removals
+        
+        brks = sorted(brks, reverse=True)
+        
+        for idx in brks:
+            assert len(cell['x'][idx + 2:]) > 1, f"{i=}"
+            new_tracks.append({'x': cell['x'][idx + 2:], 
+                                'y': cell['y'][idx + 2:], 
+                                't': cell['t'][idx + 2:]})
+            cell['t'] = cell['t'][:idx+1]
+            cell['x'] = cell['x'][:idx+1]
+            cell['y'] = cell['y'][:idx+1]
+            
+    self.tracks.extend(new_tracks) 

trackscan-0.0.1/src/trackscan/modules/visualization_utils.py

@@ -0,0 +1,37 @@
+import matplotlib.pyplot as plt
+import os
+import numpy as np
+from typing import List
+from .msd_analysis import msd_fit
+from numpy.typing import NDArray
+
+def plot_msd(filename: str, t: List[int], y: List[float], dy: List[float], alpha: float, D: float, a_err: float, D_err: float, r2: float) -> None:
+
+    fig, axs = plt.subplots(1, 1, figsize=(10,10))
+    
+    axs.errorbar(t[1:], y[1:], yerr=dy[1:])
+    axs.set_xscale('log')
+    axs.set_yscale('log')
+        
+    t_all = np.logspace(np.log10(t[1]), np.log10(t[-1]), 100)
+    y_fit = [msd_fit(tau, alpha, D) for tau in t_all]
+    
+    axs.plot(t_all, y_fit, ls="--")
+    axs.axvline(len(t)//2, ls="--", color='black')
+    axs.text(0.05, 0.9, f"alpha = {alpha:.2f} +/- {a_err:.2f}\nD = {D:.2f} +/- {D_err:.2f}\nr^2 = {r2:.3f}", transform=axs.transAxes)
+
+    fig.savefig(os.path.expanduser(filename), dpi=400, bbox_inches='tight')
+        
+    return None
+
+def plot_turning_angles(filename: str, angles: NDArray[np.float64]):
+
+    fig, axs = plt.subplots(1,1,figsize=(10,10))
+    counts, bins = np.histogram(angles, bins='auto', density=True)
+    bin_centers = (bins[:-1] + bins[1:]) / 2
+    axs.scatter(bin_centers, counts)
+    axs.set_xlim(-185, 185)
+
+    fig.savefig(os.path.expanduser(filename), dpi=400, bbox_inches='tight')
+
+    return None

trackscan-0.0.1/src/trackscan.egg-info/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: trackscan
+Version: 0.0.1
+Summary: Post-processing and analysis of cell track data
+Author: Chris Viets
+Project-URL: Homepage, https://github.com/cviets/trackscan
+Project-URL: Bug Tracker, https://github.com/cviets/trackscan/issues
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+
+<h2 align="center">Track Scan</h2>
+A Python package for post-processing and analyzing cell track data. Includes functionality for correcting automated tracking artifacts, measuring mean squared displacements, and measuring cell turning angles.
+
+## Cite
+```bibtex
+@inbook{viets_measuring_2025,
+author = {Viets, Chris and Stevens, Corey A.},
+editor = {Brockhausen, Inka},
+title = {Measuring and Analyzing Bacterial Movement in Mucus},
+bookTitle = {Dynamics of Bacteria-Mucus Interactions},
+year = {2025},
+publisher = {Springer US},
+address = {New York, NY},
+pages = {187--197},
+isbn = {978-1-0716-4627-4},
+doi = {10.1007/978-1-0716-4627-4_16},
+url = {https://doi.org/10.1007/978-1-0716-4627-4_16}
+}
+
+```
+
+## Installation
+```
+pip install trackscan
+```
+
+## Usage
+The first step to using `trackscan` is to read in a CSV file containing (note that the CSV file must contain columns labeled "Position_X", "Position_Y", "Frame", and "Track_ID -- not case-sensitive).
+```
+trackscan -i /path/to/track_data.csv
+```
+This command launches an interactive shell where the track data can be manipulated and measured. Once the interactive shell has appeared, simply type `?` to view the available commands. For example, the interactive shell contains commands to de-drift track data, correct artifacts arising from automated tracking, and measure mean squared displacement, turning angles, or mean cell speed.

trackscan-0.0.1/src/trackscan.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+README.md
+pyproject.toml
+src/cell_track.egg-info/PKG-INFO
+src/cell_track.egg-info/SOURCES.txt
+src/cell_track.egg-info/dependency_links.txt
+src/cell_track.egg-info/entry_points.txt
+src/cell_track.egg-info/requires.txt
+src/cell_track.egg-info/top_level.txt
+src/trackscan/__init__.py
+src/trackscan/cli.py
+src/trackscan.egg-info/PKG-INFO
+src/trackscan.egg-info/SOURCES.txt
+src/trackscan.egg-info/dependency_links.txt
+src/trackscan.egg-info/entry_points.txt
+src/trackscan.egg-info/requires.txt
+src/trackscan.egg-info/top_level.txt
+src/trackscan/modules/analysis_utils.py
+src/trackscan/modules/curve_fitting.py
+src/trackscan/modules/io_utils.py
+src/trackscan/modules/linking_functions.py
+src/trackscan/modules/make_tracks.py
+src/trackscan/modules/msd_analysis.py
+src/trackscan/modules/track_manipulations.py
+src/trackscan/modules/visualization_utils.py

trackscan-0.0.1/src/trackscan.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

trackscan-0.0.1/src/trackscan.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cell_track = cell_track.cli:main

trackscan-0.0.1/src/trackscan.egg-info/requires.txt

@@ -0,0 +1,2 @@
+numpy
+matplotlib

trackscan-0.0.1/src/trackscan.egg-info/top_level.txt

@@ -0,0 +1 @@
+trackscan