You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+35-28
Original file line number
Diff line number
Diff line change
@@ -5,14 +5,15 @@
5
5
6
6
## Purposes
7
7
8
+
Recent advances in the field of microscopy allow the capture, at nanometer resolution, of the motion of fluorescently-labeled particles in live cells such as proteins or chromatin loci. Therefore, the development of methods to characterize the dynamics of a group of particles has become more than necessary.
8
9
9
10
`TrackSegNet` is a tool designed for the classification and segmentation of experimental trajectories, specifically those obtained from single-particle tracking microscopy data, into different diffusive states.
10
11
11
-
To enable the training of the LSTM neural network, synthetic trajectories are initially generated, and the parameters of the generator can be fine-tuned.
12
+
-To enable the training of the LSTM neural network, synthetic trajectories are initially generated, and the parameters of the generator can be fine-tuned.
12
13
13
-
Upon completion of the training process, the experimental trajectories are classified at each point using the trained model. Subsequently, the trajectories are segmented and grouped based on their respective diffusive states. In this context, "diffusive states" refer to the distinct modes or patterns observed in the movement of particles.
14
+
-Upon completion of the training process, the experimental trajectories are classified at each point using the trained model. Subsequently, the trajectories are segmented and grouped based on their respective diffusive states. In this context, "diffusive states" refer to the distinct modes or patterns observed in the movement of particles.
14
15
15
-
For each segmented track, the diffusion constant ($D$) and anomalous exponent ($\alpha$) are further estimated. This is accomplished by computing the mean squared displacement (MSD), providing valuable insights into the dynamic behavior of the particles within each identified diffusive state.
16
+
-For each segmented track, the diffusion constant () and anomalous exponent () are further estimated. This is accomplished by computing the mean squared displacement (MSD), providing valuable insights into the dynamic behavior of the particles within each identified diffusive state.
16
17
17
18
18
19
@@ -27,32 +28,28 @@ cd TrackSegNet
27
28
28
29
### Either create and run a docker container
29
30
30
-
Build a docker image (Rebuild the image after changing the parameters):
31
31
```bash
32
+
# Build a docker image (Rebuild the image after changing the parameters):
32
33
docker compose build
33
-
```
34
-
Run the container:
35
-
36
-
```bash
34
+
# Run the container:
37
35
docker compose run tracksegnet-env
38
36
```
39
37
40
-
### Or create the environment and install the packages
41
-
42
-
```bash
43
-
sudo apt install python3-virtualenv
44
-
virtualenv -p /usr/bin/python3 tracksegnet-env
45
-
source tracksegnet-env/bin/activate # for Windows: tracksegnet-env\bin\activate
46
-
python -m pip install -r requirements.txt
47
-
```
38
+
### Or create a virtual environment and install the packages
48
39
49
-
Run the program:
40
+
Requirement: python3.8 or equivalent and the virtualenv library
50
41
51
42
```bash
52
-
./tracksegnet.py parms.csv
43
+
# Create the environment:
44
+
python -m venv tracksegnet-env
45
+
# virtualenv -p /usr/bin/python3 tracksegnet-env
46
+
# Activate the environment:
47
+
source ./tracksegnet-env/bin/activate # for Windows PowerShell: .\tracksegnet-env\Scripts\Activate.ps1 (run as administrator)
48
+
# Install the required python libraries:
49
+
python -m pip install -r requirements.txt
53
50
```
54
51
55
-
Note, to deactivate the virtual environment, type `deactivate`.
52
+
Note for later, to deactivate the virtual environment, type `deactivate`.
56
53
57
54
58
55
## Prepare your data
@@ -87,22 +84,32 @@ If `CSV` format is used, the headers should be: `x, y, frame, track_id`
87
84
88
85
### Change the main parameters
89
86
90
-
Update the main parameters in the `parms.csv` file according to your experiment:
87
+
Tune the main parameters of the training in the `params.csv` file according to your experiment:
88
+
89
+
*`num_states` the number of diffusive states for the classification(from 2 to 6 states). This number can vary from 2 to 6 states, but it is recommended to choose 2 to 4 states.
90
+
*`state_i_diff` and `state_i_alpha` the approximate motion parameters for each of the  diffusive state. The diffusion constant  is dimensionless, and the anomalous exponent value  is ranging from 0 to 2 (: subdiffusion, : Brownian motion, : superdiffusion).
91
+
*`pt_i_j` the probability of transitionning from state i to state j. The total number of probabilities should be .
92
+
93
+
The remaining parameters are related to the experimental dataset:
94
+
95
+
*`data_path`, the path of the dataset of trajectories to segment.
96
+
*`track_format`, the format of the files containing the trajectory coordinates, either `MDF` (see `MTrackJ` data file format) or `CSV`
97
+
*`time_frame`, the time interval between two trajectory points in seconds.
98
+
*`pixel_size`, the dimension of a pixel in .
91
99
92
-
-`data_path`: the path containing your data folder `SPT_experiment` to analyze
93
-
-`track_format`: The format of the files containing the trajectory coordinates, should be `MDF` or `CSV`
94
-
-`time_frame`: the time interval between two trajectory points (in second)
95
-
-`pixel_size`: the dimension of a pixel (in µm)
96
-
-`num_states`: the number of diffusive states for the classification(from 2 to 6 states)
97
-
-`state_X_diff`: The expected diffusion value for state X (in µm^2/s).
98
-
-`state_X_alpha`: The expected anomalous exponent α value for state X (from 0 to 2 -- ]0-1[: subdiffusion, 1: Brownian motion, ]1-2[: superdiffusion).
99
-
-`pt_i_j`: the probability of transitionning from the state i to the state j. The total number of probabilities should be $N^2$.
100
100
101
101
Note that the program will run on the toy example if the parameters are unchanged.
102
102
103
103
For updating the parameters of the track simulation and neural network training, please make the changes in the main file `tracksegnet.py`.
104
104
105
105
106
+
## Run the program
107
+
108
+
109
+
```bash
110
+
python tracksegnet.py parms.csv
111
+
```
112
+
106
113
## Reference
107
114
108
115
Yavuz, S., Kabbech, H., van Staalduinen, J., Linder, S., van Cappellen, W.A., Nigg, A.L., Abraham, T.E., Slotman, J.A., Quevedo, M. Poot, R.A., Zwart, W., van Royen, M.E., Grosveld, F.G., Smal, I., Houtsmuller, A.B. (2023). Compartmentalization of androgen receptors at endogenous genes in living cells, *Nucleic Acids Research* 51(20), [https://doi.org/10.1093/nar/gkad803](https://doi.org/10.1093/nar/gkad803).
Organize your data in a folder `SPT_experiment`, each sub-folder should contain a file storing the trajectory coordinates in a `MDF` or `CSV` file format.
8
+
9
+
If `CSV` format is used, the headers should be: `x, y, frame, track_id`
10
+
11
+
```bash
12
+
.
13
+
├── data/
14
+
│ └── SPT_experiment/
15
+
│ ├── Cell_1
16
+
│ │ ├── *.tif
17
+
│ │ └── *.mdf
18
+
│ ├── Cell_2
19
+
│ │ ├── *.tif
20
+
│ │ └── *.mdf
21
+
│ ├── Cell_3
22
+
│ │ ├── *.tif
23
+
│ │ └── *.mdf
24
+
│ └── ...
25
+
│
26
+
├── src/
27
+
├── tracksegnet-env/
28
+
├── parms.csv
29
+
├── tracksegnet.py
30
+
└── ...
31
+
```
32
+
33
+
## Change the main parameters
34
+
35
+
36
+
Tune the main parameters of the training in the `params.csv` file according to your experiment:
37
+
38
+
*`num_states` the number of diffusive states for the classification(from 2 to 6 states). This number can vary from 2 to 6 states, but it is recommended to choose 2 to 4 states.
39
+
*`state_i_diff` and `state_i_alpha` the approximate motion parameters for each of the  diffusive state. The diffusion constant  is dimensionless, and the anomalous exponent value  is ranging from 0 to 2 (: subdiffusion, : Brownian motion, : superdiffusion).
40
+
*`pt_i_j` the probability of transitionning from state i to state j. The total number of probabilities should be .
41
+
42
+
The remaining parameters are related to the experimental dataset:
43
+
44
+
*`data_path`, the path of the dataset of trajectories to segment.
45
+
*`track_format`, the format of the files containing the trajectory coordinates, either `MDF` (see `MTrackJ` data file format) or `CSV`
46
+
*`time_frame`, the time interval between two trajectory points in seconds.
47
+
*`pixel_size`, the dimension of a pixel in .
48
+
49
+
50
+
Note that the program will run on the toy example if the parameters are unchanged.
51
+
52
+
For updating the parameters of the track simulation and neural network training, please make the changes in the main file `tracksegnet.py`.
Recent advances in the field of microscopy allow the capture, at nanometer resolution, of the motion of fluorescently-labeled particles in live cells such as proteins or chromatin loci. Therefore, the development of methods to characterize the dynamics of a group of particles has become more than necessary.
4
+
5
+
`TrackSegNet` is a tool designed for the classification and segmentation of experimental trajectories, specifically those obtained from single-particle tracking microscopy data, into different diffusive states.
6
+
7
+
- To enable the training of the LSTM neural network, synthetic trajectories are initially generated, and the parameters of the generator can be fine-tuned.
8
+
9
+
- Upon completion of the training process, the experimental trajectories are classified at each point using the trained model. Subsequently, the trajectories are segmented and grouped based on their respective diffusive states. In this context, "diffusive states" refer to the distinct modes or patterns observed in the movement of particles.
10
+
11
+
- For each segmented track, the diffusion constant () and anomalous exponent () are further estimated. This is accomplished by computing the mean squared displacement (MSD), providing valuable insights into the dynamic behavior of the particles within each identified diffusive state.
0 commit comments