API

add_info_columns_from_filename(particle_data::AbstractDataFrame, translation_dict::AbstractDict)

Extract experimental metadata from the filename column and create a new column for each in particle_data. Returns a new DataFrame.

Assumes the filename is separated by underscores and periods are denoted by p. The translation_dict details the filename format. For full explanation, see the MicroTracker docs: Translation Dictionary.

add_resolution_column!(particle_data::AbstractDataFrame)

Look at a frame of the video in original_video which corresponds to the data and add a column for the resolution of type Tuple{Int, Int}. Modifies particle_data in place, signfified by the ! in the function name.

Uses getvideoresolution.

add_useful_columns(linked_data::AbstractDataFrame, linking_settings::NamedTuple)

After linking, add some useful columns to the dataframe, like include dx, dy, dp (speed), and size measurements in microns.

Uses the numerical_derivative and total_displacement functions.

Definitions

• particle_unique : a string which uniquely identifies a particle. This is a combination of the filename and the particle number.
• dx : numerical derivative of x, i.e. instantaneous velocity in the x direction. Units of pixels/frame.
• dy : numerical derivative of y, i.e. instantaneous velocity in the y direction. Units of pixels/frame.
• dp : instantaneous speed. √(dx^2 + dy^2). Units of pixels/frame.
• dx_um : dx converted to µm/s.
• dy_um : dy converted to µm/s.
• dp_um : dp converted to µm/s.
• total_displacement_um : total displacement of the microbot. Constant on every row, since this is a total. Units of µm.
• Area_um : area of the microbot. Units of µm^2.
• time : time, converted from the frame column. Units of seconds.
• Major_um : major axis of the fit ellipse of the microbot. Units of µm.
• Minor_um : minor axis of the fit ellipse of the microbot. Units of µm.

animate_trajectory_analyzer(linked_data, collapsed_data, particle_unique, savepath, [framerange]; animation_speed_multiplier=1, size_variable="Major_um", annotationkwargs...)

Export an animation of the trajectory analyzer and save it to savepath.

Arguments

• linked_data : AbstractDataFrame, time-series linked data, as returned by load_linked_data or batch_particle_data_to_linked_data.
• collapsed_data : AbstractDataFrame, collapsed data with a row per microbot, as returned by collapse_data.
• particle_unique : AbstractString. The unique identifier of the microbot to be analyzed.
• savepath : AbstractString. The path to save the animation to.
• framerange : (Optional) UnitRange{Int64}. The range of frames to be displayed. If not provided, the entire trajectory is animated.
• animation_speed_multiplier : (Optional) Int. The speed of the animation. Defaults to 1.
• size_variable : (Optional) AbstractString, The column name of the size variable to be displayed. Defaults to "Major_um".
• annotationkwargs : (Optional) Keyword arguments passed to plotannotatedframe_single().

Example

julia> trajectory_analyzer(linked_data, collapsed_data, "5_13p5_61p35-2", "my_animation.mp4")
[ Info: Creating animation: Frame = 5
...
[ Info: Saved animation to ~/my_animation.mp4

batch_particle_data_to_linked_data(translation_dict::Dict, linking_settings::NamedTuple; save_to_csv=true)

Process all .csv files in particle_data into linked trajectory data and concatenate the results.

Returns a DataFrame containing all linked data for the entire experimental array. This is also saved to linked_data using save_linked_data_with_metadata for record keeping and further analysis.

The translation_dict is a dictionary detailing the information contained in the filename. linking_settings contains the input parameters for the linking algorithm and microscope information. Only one of these arguments may contain the FPS.

For full explanation, see the MicroTracker Linking docs.

check_working_directory()

Check if the MicroTracker folders are accessible from the current working directory.

Return true if folders are there, throws an error if not.

clip_trajectory_edges(linked_data::AbstractDataFrame, linking_settings::NamedTuple)

Iterate through each trajectory and remove the tracking data where the particle is out of frame.

The particle is out of frame when the center is within the radius of the particle from the edge of the video.

Uses find_trajectory_bounds to find the bounds of the trajectory with inbounds.

collapse_data(linked_data::AbstractDataFrame, translation_dict::Dict)

Collapse each time-series microbot trajectory into a single row of summary data for each microbot.

Uses the translation_dict from Translation Dictionary to include the experimental data.

Output column definitions

• V : The mean of the instantaneous speed, dp_um. Always positive, as it is a magnitude. Units of µm/s.
• Vx : The mean of the numerical derivative of the x-position. Can be positive or negative. Units of µm/s.
• Vy : The mean of the numerical derivative of the y-position. Can be positive or negative. Units of µm/s.
• Area_um_mean : The mean of the area of the microbot. Units of µm^2.
• Ω_est : The estimated rotation rate extracted from the FFT of the Major_um column in the linked data. Performed using the estimate_omega function. Units of Hz.
• R : The bounding-circle radius/radius of gyration. Calculated as the 95th percentile of the major axis Major_um divided by 2. Units of µm.
• Circularity : A quantifier based on the aspect ratio of the fit ellipse. Calculated from ImageJ. See their docs. Unitless.
• total_displacement_um : The total displacement of the microbot over its entire trajectory. This is already constant in linked_data, so just take one of the values. Units of µm.

Example

julia> collapse_data(linked_data, translation_dict)
37×13 DataFrame
 Row │ particle_unique  filename      V          Vx           Vy           Area_um_mean  Ω_est      R         Circularity  total_displacement_um  B_mT     FPS      f_Hz  
     │ String15         String15      Float64    Float64      Float64      Float64       Float64    Float64   Float64      Float64                Float64  Float64  Int64
─────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   1 │ 5_13p5_61p35-0   5_13p5_61p35  88.7683    73.1812      -0.533202       524.844    0.0866525  28.8823      0.466515            425.447         13.5    61.35      5
   2 │ 5_13p5_61p35-1   5_13p5_61p35  84.2168    75.1932      -1.43098        723.553    0.184789   37.7608      0.447464            204.647         13.5    61.35      5
   3 │ 5_13p5_61p35-2   5_13p5_61p35  34.589     25.285        3.95886         66.7345   4.94208    12.1932      0.706898            151.268         13.5    61.35      5
   4 │ 5_13p5_61p35-3   5_13p5_61p35  61.7119    51.8247      -3.01578         80.8338   5.06137    14.7728      0.647094            170.821         13.5    61.35      5
   5 │ 5_13p5_61p35-4   5_13p5_61p35  20.6538     7.68584      0.0244971       23.9995   2.51434     2.91041     0.984024             15.7076        13.5    61.35      5
   6 │ 5_13p5_61p35-5   5_13p5_61p35  21.9972     7.1295      -0.320993        24.6687   2.48485     2.94544     0.98336              41.961         13.5    61.35      5
   7 │ 5_13p5_61p35-6   5_13p5_61p35  22.2261     6.78449     -0.353836        24.5469   2.47104     2.94414     0.982008             40.0362        13.5    61.35      5
   8 │ 5_13p5_61p35-7   5_13p5_61p35  22.2123     6.55907      0.46061         24.4111   2.46496     2.94133     0.983553             36.1651        13.5    61.35      5
  ⋮  │        ⋮              ⋮            ⋮           ⋮            ⋮            ⋮            ⋮         ⋮           ⋮                 ⋮               ⋮        ⋮       ⋮
  31 │ 5_8p4_28p68-9    5_8p4_28p68   40.4129    15.381       35.4248          85.391    5.28316    14.6976      0.628366             54.0731         8.4    28.68      5
  32 │ 5_8p4_28p68-10   5_8p4_28p68   40.729     20.3822      33.0557         566.571    1.88684    26.3958      0.491463             54.3218         8.4    28.68      5
  33 │ 5_8p4_28p68-11   5_8p4_28p68   41.6894    18.5982      35.8152         707.16     1.50947    28.0554      0.509829             56.0121         8.4    28.68      5
  34 │ 5_8p4_28p68-12   5_8p4_28p68    0.700078  -0.0662316   -0.00804089      21.3812   2.64158     2.94514     0.96161               0.0593394      8.4    28.68      5
  35 │ 5_8p4_28p68-13   5_8p4_28p68   39.0276    18.1646      31.7101         660.916    1.50947    27.9988      0.504366             51.1676         8.4    28.68      5
  36 │ 5_8p4_28p68-14   5_8p4_28p68   12.5579    -0.761769     0.545299        15.3284   0.377368    2.89432     0.917512              1.12274        8.4    28.68      5
  37 │ 5_8p4_28p68-15   5_8p4_28p68   47.225     17.9276      40.9265         152.034    5.28316    19.533       0.609                62.9841         8.4    28.68      5
                                                                                                                                                           22 rows omitted

collapse_experimental(dfg::GroupedDataFrame, translation_dict::Dict)

Take a single value from each experimental column per particle and assemble it into a dataframe.

Takes a grouped dataframe of the linkeddata. Internal function used in [`collapsedata`](@ref).

Example

julia> collapse_experimental(groupby(linked_data, :particle_unique), translation_dict)
37×4 DataFrame
 Row │ particle_unique  B_mT     FPS      f_Hz  
     │ String15         Float64  Float64  Int64
─────┼──────────────────────────────────────────
   1 │ 5_13p5_61p35-0      13.5    61.35      5
   2 │ 5_13p5_61p35-1      13.5    61.35      5
   3 │ 5_13p5_61p35-2      13.5    61.35      5
   4 │ 5_13p5_61p35-3      13.5    61.35      5
   5 │ 5_13p5_61p35-4      13.5    61.35      5
   6 │ 5_13p5_61p35-5      13.5    61.35      5
   7 │ 5_13p5_61p35-6      13.5    61.35      5
   8 │ 5_13p5_61p35-7      13.5    61.35      5
  ⋮  │        ⋮            ⋮        ⋮       ⋮
  31 │ 5_8p4_28p68-9        8.4    28.68      5
  32 │ 5_8p4_28p68-10       8.4    28.68      5
  33 │ 5_8p4_28p68-11       8.4    28.68      5
  34 │ 5_8p4_28p68-12       8.4    28.68      5
  35 │ 5_8p4_28p68-13       8.4    28.68      5
  36 │ 5_8p4_28p68-14       8.4    28.68      5
  37 │ 5_8p4_28p68-15       8.4    28.68      5
                                 22 rows omitted

create_imagej_macro_here(;MPP::Float64, minimum_segmentation_diameter::Float64)

Create a macro script for batch segmenting videos in original_video with Fiji.

Required keyword arguments:

• MPP : microns per pixel, Float64 (unique to your microscope setup!)
• minimum_segmentation_diameter : only particles above this diameter*1.5 in microns will be segmented, Float64. See the following reference for why the 1.5:

J. Baumgartl, J. L. Arauz-Lara, and C. Bechinger, “Like-charge attraction in confinement: myth or truth?,” Soft Matter, vol. 2, no. 8, p. 631, 2006, doi: 10.1039/b603052a.

Example

julia> create_imagej_macro_here(MPP=0.605, minimum_segmentation_diameter=4.5)
[ Info: ImageJ macro created at ~/tutorial/imagej_macro.ijm. See MicroTracker segmentation docs for instructions on how to use it. 

create_project_here()
create_project_here(include_examples=false)

Create the folder structure for a MicroTracker project in the current working directory.

If include_examples is false, then example particle data and videos will not be included.

Example

julia> pwd()
"~/tutorial"

julia> create_project_here()
[ Info: New MicroTracker project created in ~/tutorial

detrend(y::AbstractVector)

Remove a linear trend in y.

download_original_video_artifact()

Use the Artifacts Pkg system to fetch the example video and download into the assets folder.

ellipse(major, minor, pos, angle)

Get points x, y for the ellipse with major and minor axes, pos vector, and angle in radians.

estimate_omega(x::AbstractVector, y::AbstractVector)

Get the highest frequency peak of x, y data and return the corresponding xf divided by 2.

This works for rolling microbots when the y data exhibits two peaks every rotation. Depending on the data, this could be the Angle, Major_m, or V columns.

extract_frame_from_label(label::AbstractString)

When using ImageJ data, the frame column does not exist, so we need to pull it out of the label column.

This function assumes the frame number is at the end of the label.

Example

julia> MicroTracker.extract_frame_from_label("5_8p4_28p68:slice:51")
51

fftclean(x::AbstractVector, y::AbstractVector)

Transform time data x, y into the frequency domain. Returns xf, yf.

filter_trajectories(collapsed_data::AbstractDataFrame, filter_settings::NamedTuple)

Filter out microbots that may be too small or large, going too slow, or stuck to the substrate.

The filter_settings is a NamedTuple with the following fields:

• MIN_VELOCITY : minimum velocity in um/s
• MIN_BOUNDING_RADIUS : minimum bounding radius in um
• MAX_BOUNDING_RADIUS : maximum bounding radius in um
• MIN_DISPLACEMENT : minimum total displacement in um

Example

filter_settings = (
    MIN_VELOCITY = 10.0,  # um / s  
    MIN_BOUNDING_RADIUS = 3.38,  # um
    MAX_BOUNDING_RADIUS = 75,  # µm
    MIN_DISPLACEMENT = 0,  # µm
)

filtered_collapsed_data = filter_trajectories(collapsed_data, filter_settings)

find_relevant_FPS(particle_data::AbstractDataFrame, linking_settings::NamedTuple)

Used to allow for the FPS to be specified either in the filename or in the linking_settings.

If FPS is in the particledata, it will be used. If FPS is in the linkingsettings, it will be used. If FPS is in both, an error will be thrown.

find_trajectory_bounds(df_1particle::AbstractDataFrame, video_resolution::Tuple{Int, Int})

Return a tuple of frame numbers, (low, high) where all trajectory points are in bounds.

This calculates the radius of the particle, then iterates forward and backward from the center of the trajectory until it finds a point that is out of bounds. This is the high and low bound of the trajectory.

fit_line(x::AbstractVector, y::AbstractVector)

Fit a linear equation to data x, y. Returns m, b.

$y = mx + b$

Dependent on Optim.

get_assets_path()

Always returns the path to the assets folder in the package root directory.

This works from the dev's, test suite's, or user's perspective.

get_names_in_particle_data()

Return a list of all .csv files contained in the particle_data folder.

getfileextension(imagename::AbstractString)

Get the file extension from the image name.

Example

julia> MicroTracker.getfileextension("a0001.tif")
"tif"

getframenumfromimagename(imagename::AbstractString)

Get the relevant frame number from the name of an image. Does not necessarily match the real frame number in the data.

Example

julia> MicroTracker.getframenumfromimagename("5 24p9 1 2022-04-04-16-30-31-16-a-985.tif")
985

julia> MicroTracker.getframenumfromimagename("05_23_8_2 kept stack0001.tif")
1

getimagenamedigitlength(tifname::AbstractString)

Get the length of the digits quantifying the frame in the image name. Used to catch leading zeros.

Example

julia> MicroTracker.getimagenamedigitlength("05_23_8_2 kept stack0001.tif")
4

getprefixfromimagename(imagename::AbstractString)

Return the prefix from the name of an image. This is everything besides the <framenumbers>.tif.

Example

julia> MicroTracker.getprefixfromimagename("5 24p9 1 2022-04-04-16-30-31-16-a-985.tif")
"5 24p9 1 2022-04-04-16-30-31-16-a-"

julia> MicroTracker.getprefixfromimagename("05_23_8_2 kept stack0001.tif")
"05_23_8_2 kept stack"

getvideoresolution(video_name::AbstractString)

Load in 1 frame of video_name and return the resolution of the video as a Tuple{Int, Int}

inbounds(row::DataFrameRow, radius::AbstractFloat, video_resolution::Tuple{Int, Int})

Check if dataframe row is in bounds. This is a single row in a dataframe of a single particle's trajectory.

This looks at x and y coordinates and checks if they are within radius of the edge of the video.

jldf_to_pydf(jldf)

Convert a DataFrame (from DataFrames.jl) to a pandas.DataFrame. Used internally to interface with trackpy.

link(particle_data::AbstractDataFrame, linking_settings::NamedTuple; trackpykwargs...)

Use trackpy to link particle data into trajectories across frames.

See the Linking Settings docs for the fields and format of linking_settings. Any kwargs will be passed to the trackpy.link function trackpy.link.

Example

julia> link(particle_data, linking_settings)

load_linked_data(filename)

Read a linked data .csv file into a DataFrame. Assumes the .csv file is in the linked_data folder.

load_particle_data(video_name::AbstractString)

Read a particle data .csv located in /particle_data into a DataFrame.

If the .csv file is from ImageJ (contains X, Y, and Label columns, not x, y, and frame), it will:

1. Extract the frame number from the label column and add it as a new column using extract_frame_from_label
2. Rename the X and Y columns to x and y so it works with link.
3. Remove any columns with a blank name.
4. Rename the Circ. column to Circ so it works with Julia symbol notation.

loadframe(vidname::AbstractString, framenumber::Integer)

Return an image corresponding to the framenumber frame in the video vidname. Must be present in the original_video folder.

It looks at the way the tifs are automatically named and matches the pattern. Does not necessarily match the real frame number in the data, especially if there is no particle in the first frame.

Normally, images from ImageJ index at 0, while Julia indexes at one. Therefore, this function will return the image named with framenumber-1.

numerical_derivative(x::AbstractVector)

Return the derivative of a Vector with spacing h = 1. Use on x and y columns of tracking data. Similar to Python's np.gradient function, but 61x faster here.

parse_to_tuple(s::AbstractString)

Convert a string to a Tuple{Int64, Int64}. Internal function used in load_linked_data.

particle_data_to_linked_data(video_name::AbstractString, translation_dict::Dict, linking_settings::NamedTuple)

Process particle data into linked trajectory data while calculating instantaneous velocity and other salient data. Returns a DataFrame that can then be saved to linked_data using save_linked_data_with_metadata.

A particle data csv corresponding to video_name must be present in the particle_data folder. The translation_dict` is a dictionary detailing the information contained in the filename. For full explanation, see the MicroTracker docs (ref needed).

plotannotatedframe(linked_data::AbstractDataFrame, filename::AbstractString, framenumber::Int; showimage=true, showellipse=true, plotkwargs...)

Display a single frame of a video with all microbot trajectories overlaid. Optionally, hide the fit ellipses or the image.

To plot a single microbot's trajectory, use plotannotatedframe_single. plotkwargs are passed to plot!() and are intended to change the appearance of the plot.

plotannotatedframe_single(linked_data::AbstractDataFrame, particle_unique::AbstractString, framenumber::Int; showimage=true, showellipse=true, plotkwargs...)

Display a single frame of a video, with a single chosen microbot trajectory overlaid. Optionally, hide the fit ellipses or the image.

To plot all microbot trajectories, use plotannotatedframe. plotkwargs are passed to plot!() and are intended to change the appearance of the plot.

pydf_to_jldf(pydf)

Convert a pandas.DataFrame to a DataFrame (from DataFrames.jl). Used internally to interface with trackpy.

save_linked_data_with_metadata(linked_data::AbstractDataFrame, translation_dict::Dict, linking_settings::NamedTuple)

Save linked data with the translation_dict and linking_settings in the filename. Will overwrite existing file.

total_displacement(x::AbstractVector, y::AbstractVector)

Return the total displacement of the particle in pixels.

trajectory_analyzer(linked_data, collapsed_data, particle_unique::AbstractString, [framenumber; [size_variable="Major_um"], [annotationkwargs...])

Display a comphrehensive dashboard of a single microbot, including instantaneous velocity, a chosen size_variable, and the FFT of the size_variable.

Arguments

• linked_data : AbstractDataFrame, time-series linked data, as returned by load_linked_data or batch_particle_data_to_linked_data.
• collapsed_data : AbstractDataFrame, collapsed data with a row per microbot, as returned by collapse_data.
• particle_unique : AbstractString. The unique identifier of the microbot to be analyzed.
• framenumber : (Optional) Int The frame number to be displayed. If not provided, the last frame is used.
• size_variable : (Optional) AbstractString, The column name of the size variable to be displayed. Defaults to "Major_um".
• annotationkwargs : (Optional) Keyword arguments passed to plotannotatedframe_single().

translation_dict_to_string(translation_dict::Dict)

Convert a dictionary into a string that can be used as a filename. Used internally to save linked_data.

Example

julia> test_translation_dict = Dict("f_Hz"=>(1, Int64), "B_mT"=>(2, Float64), "FPS"=>(3, Float64));

julia> MicroTracker.translation_dict_to_string(test_translation_dict)
"B_mT=(2, Float64), FPS=(3, Float64), f_Hz=(1, Int64)"

upperright(p::Plots.Plot)

Return a tuple of coordinates corresponding to the upper right corner of a plot, plus an increase of oob percentage in the y direction.

verify_download()

Verify that the example videos are downloaded into the MicroTracker assets folder in their entirety.

Returns true or false.