README.md

# Robust Defect Identification

## Description
This software package implements the identification of robust topological defects, where 'robust' means that the topological charges of the identified defects remain unaffected by a certain noise level applied to the two-dimensional vector field in which they are identified.
It applies both to polar and nematic fields, whereby the latter are also known as line fields or orientation fields.

The code was developed by Karl B. Hoffmann during his PhD studies under supervision of Prof. Ivo F. Sbalzarini at the Technical University Dresden, the Center for Systems Biology Dresden, and the Max Planck Institute of Molecular Cell Biology and Genetics, Dresden. 

For usage example go through the main Jupyter Notebook [robust_defect_identification.ipynb](./robust_defect_identification.ipynb) 
or have a look at the [examples section](./README.md#example-workflows). 


## Citation
When using the software, please cite
> Hoffmann, Karl B. and Sbalzarini, Ivo F. "Robustness of topological defects 
> in discrete domains", Physical Review E 103 (2021),  
> __https://doi.org/10.1103/PhysRevE.103.012602__  
> [pdf also available from __https://sbalzarini-lab.org/docs/Hoffmann2021.pdf__]

A MATLAB implementation of the same concepts was used in this paper as well as for
> Hoffmann, Karl B. and Sbalzarini, Ivo F. "A robustness measure for singular 
> point and index estimation in discretized orientation and vector fields", 
> Proceedings in Applied Mathematics & Mechanics 20 (2020),  
> __https://doi.org/10.1002/pamm.202000261__  
> [pdf also available from __https://sbalzarini-lab.org/docs/Hoffmann2020.pdf__]

and for  

> Hoffmann, Karl B. and Sbalzarini, Ivo F. "Estimation of unordered core
> size using a robustness measure for topological defects in discretized
> orientation and vector fields", Proceedings in Applied Mathematics &
> Mechanics 21 (2021),  
> __https://doi.org/10.1002/pamm.202100105__  
> [pdf also available from __https://sbalzarini-lab.org/docs/Hoffmann2021a.pdf__]

See also
> Hoffmann, Karl B.: "Robust Identification of Topological Defects in
> Discrete Vector Fields with Applications to Biological Image Data",  
> PhD Thesis at Technical University Dresden, Germany (2022)

## Microscopy image data
The included `exampleData-ZebrafishOpticalCup.jpg` is courtesy of Karen Soans, 
imaged during her work with Caren Norden at the Max Planck Institute of Molecular
Cell Biology and Genetics, Dresden, Germany.
It is a 2D maximum projection after deconvolution and derotation of Zebrafish 
Danio rerio optic cup at 18 somite stage with fluorescent (GFP) labelling of laminin.
Scale: 1 pixel = 0.0902micrometer x 0.0902micrometer.
For more details see
> Soans, Karen G. and Ramos, Ana Patricia and Sidhaye, Jaydeep and Krishna, 
Abhijeet and Solomatina, Anastasia and Hoffmann, Karl B. and Schlüßler, Raimund
> and Guck, Jochen and Sbalzarini, Ivo F. and Modes, Carl D. and Norden, Caren.
> "Collective cell migration during optic cup formation features changing 
> cell-matrix interactions linked to matrix topology", Current Biology (2022),
> __https://doi.org/10.1016/j.cub.2022.09.034__  

The included image `exampleData-Amnioserosa.jpg` is courtesy of David Flores-Benitez, 
imaged during his work with Elisabeth Knust at the Max Planck Institute of Molecular 
Cell Biology and Genetics, Dresden, Germany.
It is a 2D maximum projection of the amnioserosa in a fruit fly Drosophila melanogaster
embryo with fluorescent (GFP) labelling of actin. 
Scale: 1 pixel = 0.114micrometer x 0.114micrometer, 
       z-spacing before projection was 1.00 micrometer.  
Hatching and imaging were performed as described in 
> Flores-Benitez, David and Knust, Elisabeth. "Crumbs is an essential regulator of 
> cytoskeletal dynamics and cell-cell adhesion during dorsal closure in Drosophila",
> eLife (2015), __https://doi.org/10.7554/eLife.07398__

## License
This work is licensed under CC-BY 4.0

## Disclaimer
*IN NO EVENT SHALL THE MOSAIC GROUP BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, 
SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING 
OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE MOSAIC GROUP 
HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE MOSAIC GROUP SPECIFICALLY 
DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED 
HEREUNDER IS ON AN "AS IS" BASIS, AND THE MOSAIC GROUP HAS NO OBLIGATIONS TO 
PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.*

## Example workflows
Output plots of the main Jupyter Notebook [robust_defect_identification.ipynb](./robust_defect_identification.ipynb) for 
the different examples follow below.   
Each example  
 - starts from original grayscale image (except for the synthethic data)
 - from which the orientation field is caluclated.
 - A look at the histogram of edge robustnesses and setting a quantile (and thereby indirectly a robustness threshold)
  - yields the graph of robust edges.
  - Filling in the microscopic charges, we find the robust topological charges as indicated by the coloring of connected areas.

### Synthetic example of differently sized defect cores
[Defect cores: orientation field](./examples/TwoCores/exampleData-Amnioserosa_orientation.jpg)  
[Defect cores: histogram of edge robustnesses](./examples/TwoCores/exampleData-TwoCores_magnaware0_3_robustnesshistogram.jpg)  
[Defect cores: graph of robust edges above quantile 0.3](./examples/TwoCores/exampleData-TwoCores_magnaware0_3_edges.jpg)   
[Defect cores: robust topological charges](./examples/TwoCores/exampleData-TwoCores_magnaware0_3_robust+micro.jpg)  

### Amnioserosa example
[Amnioserosa example: grayscale input image](./examples/Amnioserosa/exampleData-Amnioserosa.jpg)  
[Amnioserosa example: grayscale input image with orientation field](./examples/Amnioserosa/exampleData-Amnioserosa_orientation.jpg)  
[Amnioserosa example: histogram of edge robustnesses](./examples/Amnioserosa/exampleData-Amnioserosa_magnaware0_5_robustnesshistogram.jpg)  
[Amnioserosa example: graph of robust edges above quantile 0.5](./examples/Amnioserosa/exampleData-Amnioserosa_magnaware0_5_edges.jpg)   
[Amnioserosa example: robust topological charges](./examples/Amnioserosa/exampleData-Amnioserosa_magnaware0_5_robust+micro.jpg)  

Same procedure for a detail view (note that the robusutness threshold shifts slightly as it is calculated as quantile of of a subset of edges)
### Detail of Amnioserosa example
[Amnioserosa example (detail): grayscale input image with orientation field](./examples/Amnioserosa/exampleData-AmnioserosaDetail_orientation.jpg)  
[Amnioserosa example (detail): histogram of edge robustnesses](./examples/Amnioserosa/exampleData-AmnioserosaDetail_magnaware0_5_robustnesshistogram.jpg)  
[Amnioserosa example (detail): graph of robust edges above quantile 0.5](./examples/Amnioserosa/exampleData-AmnioserosaDetail_magnaware0_5_edges.jpg)   
[Amnioserosa example (detail): robust topological charges](./examples/Amnioserosa/exampleData-AmnioserosaDetail_magnaware0_5_robust+micro.jpg)  

### Zebrafish optical cup example
[Zebrafish optical cup example: grayscale input image](./examples/ZebrafishOpticalCup/exampleData-ZebrafishOpticalCup.jpg)  
[Zebrafish optical cup example: grayscale input image with orientation field](./examples/ZebrafishOpticalCup/exampleData-ZebrafishOpticalCup_orientation.jpg)  
[Zebrafish optical cup example: histogram of edge robustnesses](./examples/ZebrafishOpticalCup/exampleData-ZebrafishOpticalCup_magnaware0_3_robustnesshistogram.jpg)  
[Zebrafish optical cup example: graph of robust edges above quantile 0.3](./examples/ZebrafishOpticalCup/exampleData-ZebrafishOpticalCup_magnaware0_3_edges.jpg)   
[Zebrafish optical cup example: robust topological charges](./examples/ZebrafishOpticalCup/exampleData-ZebrafishOpticalCup_magnaware0_3_robust+micro.jpg)  


### Cake example
[Cake example: grayscale input image](./examples/Cake/exampleData-Cake.jpg)  
[Cake example: grayscale input image with orientation field](./examples/Cake/exampleData-Cake_orientation.jpg)  
[Cake example: histogram of edge robustnesses](./examples/Cake/exampleData-Cake_magnaware0_8_robustnesshistogram.jpg)  
[Cake example: graph of robust edges above quantile 0.8](./examples/Cake/exampleData-Cake_magnaware0_8_edges.jpg)   
[Cake example: robust topological charges](./examples/Cake/exampleData-Cake_magnaware0_8_robust+micro.jpg)