Package: dextrusion
DeXtrusionDeXtrusion is  a machine learning based python pipeline to detect cell extrusions in epithelial tissues movies. It can also detect cell divisions and SOPs, and can easily be trained to detect other dynamic events.This repository contains the code source of the python DeXtrusion library, the trained neural networks (ready to use) with Jupyter notebooks to run, train or retrain DeXtrusion networks, and Fiji macros for visualization/analysis of the results.PresentationInstallationUsageDataDeXtrusion networksFiji macrosJupyter notebooksReferencesPresentationDeXtrusion takes as input a movie of an epithelium and outputs thespatio-temporal location of cell extrusion eventsor other event as cell divisions.
The movie is discretized into small overlapping rolling windows which are individuallyclassified for event detectionby a trainedneural network. Results are then put together in eventprobability mapfor the whole movie or asspatio-temporal pointsindicating each event.![Example extrusion detection](https://gitlab.pasteur.fr/gletort/dextrusion/-/raw/main/images/SequenceExtrusion.png "Extrusion detection example") 
Example of the detection of an extrusion event (probability map, red).Event classificationThe movie is discretized into small windows that span all the movie in a rolling windows fashion with overlap between the different windows.
Each window is classified by a trained neural network as containing or not a cellular event as cell extrusion. The different classes available in the main DeXtrusion network are:No eventCell extrusion/cell deathCell divisionSOPsIt is easy to add or remove a cellular event to this list, but necessitates to train new neural networks for this. Jupyter notebook is available in this repository to do it.Event probability mapEach window is associated an event probability which allow to generate an events probability map on the whole movie. This probability maps can be refined to precise spatio-temporal spots for each event.
The results can be visualized by overlaying the initial movie and all the probability maps saved by DeXtrusion in Fiji with the saved by DeXtrusion with thedeXtrusion_overlayProbabilityMaps.ijmmacro.![Example probability maps](https://gitlab.pasteur.fr/gletort/dextrusion/-/blob/main/images/SequenceProbamaps.png?raw=True "Probability map example")Example of probability maps (green: division, red: extrusion, blue: SOPEvent spot localizationAn event is visible in the probability map as a volume of connected pixels of high probability. To convert the probability map to a list of event, we place the event localization at the center of each of these high probability volumes.
Moreover, to reduce false positive detections, the volumes can be thresholded to keep only big enough volume of high enough probability values.
The list of spots obtained in this way are saved in ROIS.zipfile that can be open in Fiji through theROIManagertool. The macrodeXtrusion_showROIs.ijmallows to directly visualize with Fiji the results saved by DeXtrusion.InstallationDeXtrusion is distributed as a python module, compatible withpython3.
You can install it in a virtual environment to be sure to have the required versions.DeXtrusioncan be installed either manually through the setup file or with pip:DeXtrusion can be directly installed via pip. In your python virtual environment, enter:pip install dextrusionto install it.
You should also download the trained neural networkDeXNetthat you want to use from this repository.To install manuallyDeXtrusion, clone this github repository, and inside this repository type:python setup.py install.
If you want to install it in a virtual environment, you should have activated it before.
It will install all the necessary dependencies.Detailled installation on Linux (Ubuntu)Here's a step by step command lines to run in a Terminal to install DeXtrusion on Linux from scratch. It is creating a new virtual environment on which DeXtrusion will be installed (not necessary but recommended). Tested withpython 3.8.Installation withpippython3-mvenvdextrusenv## create a virtual environment with python 3 called dextrusenv (you can choose the name)sourcedextrusenv/bin/activate## activate the virtual environment: now python commands will be runned in that environmentpipinstalldextrusion## install DeXtrusion, download all the necessary dependencies, can take timeDeXtrusion is installed and can be runned with:python-mdextrusion## run DeXtrusion. Next time to run it again with the same networks, you only have to do this lineDeXtrusion needs neural networks to classify each sliding window. To used our trained neural networks (in the DeXNets repository), you have to download and uncompress it. From the command line:mkdirDeXNets## create directory on which neural networks will be putmkdirDeXNets/notum_ExtSOPDiv## create directory for the neural networks traind with 4 events available in this repositorycdDeXNets/notum_ExtSOPDiv## go inside the desired neural networks directory (here the network trained with 4 events)wgethttps://gitlab.pasteur.fr/gletort/dextrusion/-/blob/main/DeXNets/notum_ExtSOPDiv/notumExtSOPDiv0.zip## download the first neural networkwgethttps://gitlab.pasteur.fr/gletort/dextrusion/-/blob/main/DeXNets/notum_ExtSOPDiv/notumExtSOPDiv1.zip## download the second neural networkunzipnotumExtSOPDiv0.zip## uncompress it. It is now ready to be usedunzipnotumExtSOPDiv1.zipcd../..## go back to main DeXtrusion directoryYou can also clone this repository and install DeXtrusion from the source codepython setup.py installinstead of using pip installation.Detailled installation on WindowsYou need to have anaconda installed to run python and create a new virtual environment. On the command prompt, write:$ C:\ProgramData\Anaconda3\Scripts\Activate     ## activate conda (should be the path of your anaconda installation)
$ conda create --name dextrusionenv python=3.8  ## to create virtual environment called dextrusionenv
$ conda activate dextrusionenv                  ## activate the virtual environment that you juste created
$ pip install dextrusion                        ## install DeXtrusion in it
$ python -m dextrusion                          ## Run itChoose the neural network DeXNets to useDeXtrusion needs neural networks to classify each sliding window. To used our trained neural networks (in theDeXNets repository), you have to download and uncompress it.
From DeXtrusion user interface, to select a network to run, you have to go inside its uncompressed directory (click onBrowseand go there). If you want to use several networks together for the detection for better results (see our paper), the networks folders should be placed within the same directory. Go inside that directy with the interface, and it will use all the networks presents in that directory.UsageDeXtrusion can be used directly within python.
To run an already trained network and detect cell events, runpython3 -m dextrusionin your virtual environment. It will open a graphical interface to perform the detection.We also proposeJupyter notebooksin this repository, to use dextrusion options.
You can find a notebook to perform the detection, train a new neural network, retrain a network or evaluate the performance of the network compared to a manual detection.DataData used for the training of our neural networks (raw movies with manual anotation of events) are freely available on Zenodo.DeXNets: deXtrusion neural networksDeXtrusion was trained on E-cadherin tagged drosophilia notum but can be easily adapted to other markers/biological conditions. Retraining of DeXtrusion network may be necessary when images are quite different.In thedeXNetsfolder of this repository, we proposed several trained networks:notum_Ext: trained on drosophilia notum movies with only extrusion eventsnotum_ExtSOP: trained on drosophilia notum movies with extrusion and SOP eventsnotum_ExtSOPDiv: trained on drosophilia notum movies with extrusion, division and SOP eventsnotum_all: trained on drosophilia notum movies with extrusion, division and SOP events, on all our annotated data (training and test). Networks to use by default.Download them and unzip to be ready to use in DeXtrusion.Train/retrain a new DeXNetIf you want to train/retrain a neural network, to add a new event to detect or to improve its performance on new datasets, Jupyter notebooks are proposed in this repository:Jupyter notebooks. You can just follow step by step the notebook.If you want to change the architecture of DeXNet, you will have to change it in thesrc/dextrusion/Network.pyfile. The architecture is defined in theaction_modelfunction.Fiji macrosFiji macros to prepare data for DeXtrusion neural network training or to handle DeXtrusion results are available in theFiji macrosfolder of this repository.deXtrusion_checkAndClearROIs.ijmallows to check manually all the detected ROIs and to keep only the correct ones.
It shows each event (point ROI) detected by deXtrusion as a pop-up window centered temporally and spatially around the event.
The user is asked wether the detection is correct (if there is an event in the current window) by pressingyorn.
If yes, the ROI is kept, else it will be removed from the list of ROIs.deXtrusion_scoreROIs_Random.ijmallows to score manually the precision of the detected events.
The macro will open randomly a given number of ROIs, and show a window centered temporally and spatially around the event.
The user is asked wether the detection is correct (if it contains the event) by pressingyorn.
The macro will output the count of correct and false detections and the precision.
The ROIs file will not be edited and the ROIs left after running this macro should not be saved as it deletes all the ROIs explored to be sure not to draw them twice.deXtrusion_overlayProbabilityMaps.ijmallows to visualize the probability maps together with the original image.
The user is asked for the original image to visualize and will open the probability maps in theresultsfolder where they should be saved by default.
The directory to look in can be changed in the macro.deXtrusion_showROIs.ijmdisplays the original movie (chosen by the user) and the ROI file found in theresultsfolder.
The location of the ROI file can be changed in the macro by changing theresfoldparameter and the event to show (by default extrusion) can be changed in thetypeparameter.deXtrusion_subsetMovieAndRois.ijmsave a temporal subset of a movie, and keep only the corresponding ROIs.Jupyter notebooksWe provide in this repository several jupyter notebooks to run, train/retrain, evaluate DeXtrusion.detectEventsOnMovie.ipynballows you to run DeXtrusion with the graphical interaface to choose the parameters.deXtrusion_TrainNetwork.ipynbto train a new DeXNet network with your own data (or using our data publicly available, seedata section).deXtrusion_RetrainNetwork.ipynbto retrain an already trained neural network with new data.deXtrusion_CompareRois.ipynbto compare two ROIs files (manual detection vs DeXtrusion detection) and gives the score. It can also generate ROIs files of the false detection (false positives and/or false negatives).deXtrusion_testClassification_OnWindows.ipynb: run the trained neural network (DeXNet) on test data on generated windows, and print the resulting confusion matrix of the classification (DeXtrusion classification compared to the manual classification).Notebooks usageIf you have Jupyter installed on your computer, to add your virtual environment to the environment Jupyter can see:ipython kernel install --user --name=dextrusionenvYou can refer to thistutorialfor instructions on creating virtual environment and using it with jupyter.You can also install Jupyter Lab or Jupyter notebook in your virtual environment if you don't have it installed in your computer:pipinstalljupyterlab
jupyter-labRefer toJupyterwebpage for more information.ReferencesTo know more about DeXtrusion, refer to our paper: Villars, Letort et al. 2023.LicenseDeXtrusion is distributed open-source under the BSD-3 license, see the license file in this repository.When you use DeXtrusion source code, neural networks or data for your projects, please cite our paper.