TRONOS

TRacking of Nuclear OScillations

This repository contains the code and example input-output files for the pipeline used to assay nuclear oscillation patterns during meiotic prophase in S. pombe; check the preprint at bioRxiv. TRONOS uses .tiff or .dv files as source data.

Scripts

The software is composed of four main scripts:

tronos.py: the main script to convert image stack files into trajectory and morphology information of blobs, after projection, binarization and tracking. As an additional filtering step, allows conversion of reference images (i.e. brightfield) into suitable format for prediction with the neural script.
tracker.py: this script allows to reconstruct trajectory information from projected and thresholded images in .tiff format.
neural.py: allows training and prediction with a Faster-rCNN. The model provided in the models folder has been pre-trained to detect meiotic zygotes of fission yeast (S. pombe). You may generate your own models with this script, from .tiff images and .xml annotations generated with labelimg.
track-labeling.py: script to label each reconstructed track, i.e. according to the cell annotation generated by the neural information; using a coordinate map (R-tree), it checks whether the reconstructed track is contained within the coordinates of previously annotated objects.

You may learn about the commands in each script executing it with the --help argument.

Notebooks

After trajectory-morphology reconstruction and track annotation has been performed, you may want to analyze this data, i.e. to discover patterns or differences in velocities across groups. Two Jupyter Notebooks have been created with this aim:

TronosAnalysis-Global.ipynb: for analysis of group data, multiple tracks (from multiple particles, different conditions or strains...) can be analyzed at once.
TronosAnalysis-SC.ipynb: for analysis of single-particle data, generating plots for individual cases (spectrograms, motif discovery...)

Sample files

Contained in folder samples/*:

linked/: contains .csv files with reconstructed trajectories and its labeling
particle_results/: contains .tsv files with statistical analysis of each particle as input
unlinked/: contains .csv files with the labeling or annotation for each brightfield file, as the coordinates.

Models

Contains neural models (as the weighting file) in pth format, used during brightfield labeling. Note that models are splitted in several files, due to limitations in size for individual files. To retrieve the model, please run:

Example workflow (Linux systems)

Please, consider that only stacks with one wavelength, various Z-planes and various time points are supported. If you want to reconstruct a file with only one Z-stack, review the arguments (remove --stack), which avoids to perform the maximum projection.
Run a Terminal window, and type the following to clone this repository in the current directory

git clone https://github.com/danilexn/Tronos
cd Tronos/tronos

Install the prerequisites and dependencies using pip, and reconstruct the neural model into a single file

sudo apt-get install python3 pip
pip install mrc tifffile Rtree numpy pandas trackpy detecto Pillow
cat ../models/* > ../models/celltype.pth.xz
xz --decompress ../models/celltype.pth.xz

Execute the tronos.py script to reconstruct trajectories and morphologies from raw imaging files

python3 tronos.py --source *R3D.dv --workdir WORK_FOLDER --project --track --threshold MaxEntropy --convert --minframes 120 --sizes 500 10000

Replace WORK_FOLDER with the previously created folder that will be used to store the results
This will output one .csv file per image file, containing linked tracks for each of the particles that have been filmed

Execute the tronos.py script to convert reference images for later neural processing

python3 tronos.py --source *REF.dv --workdir WORK_FOLDER/REFERENCE --reference --individual --first

Replace WORK_FOLDER/REFERENCE with the previously created folder which will be used to store these results

Execute the neural.py script to detect cells with zygote shape. Please, keep the order of the --categories argument. The score threshold can be changed to make it more or less restrictive when filtering..

python3 neural.py --query WORK_FOLDER/REFERENCE/*.tiff --categories "ascus" "normal" --model ../models/celltype.pth --score 0.4

Execute the track-labeling.py script to link the shape predictions with the previously reconstructed tracks, with filtering aims (you may want only a certain type of cells in your analysis).

python3 track-labeling.py --source WORK_FOLDER/*.csv --outdir WORK_FOLDER --coordir WORK_FOLDER/REFERENCE --namedel "PRJ_trajs" --nameadd "REF_0_coords" --category "wt" --feature "celltype" --first

Replace WORK_FOLDER and WORK_FOLDER/REFERENCE as previously. Under the --namedel and --nameadd arguments, you have to specify what has to be removed from the trajectory .csv files and added to yield the reference annotations. For example:
- timelapse_1_R3D_PRJ_trajs.csv <---- Trajectories file
- timelapse_1_R3D_REF_0_coords.csv <- Reference annotation file should yield --namedel "PRJ_trajs" --nameadd "REF_0_coords"

For each of the .csv files, you may utilize the Jupyter notebooks provided. When performing a Global analysis, you may join all the annotated .csv files into a single .csv. Mixing different labels (i.e. genotypes) is allowed:

awk '(NR == 1) || (FNR > 1)' *.csv > globalanalysis.csv

danilexn / tronos