Package: histocartography
Documentation|PaperWelcome to thehistocartographyrepository!histocartographyis a python-based library designed to facilitate the development of graph-based computational pathology pipelines. The library includes plug-and-play modules to perform,standard histology image pre-processing (e.g.,stain normalization,nuclei detection,tissue detection)entity-graph representation building (e.g.cell graph,tissue graph,hierarchical graph)modeling Graph Neural Networks (e.g.GIN,PNA)feature attribution based graph interpretability techniques (e.g.GraphGradCAM,GraphGradCAM++,GNNExplainer)visualization toolsAll the functionalities are grouped under a user-friendly API.If you encounter any issue or have questions regarding the library, feel free toopen a GitHub issue. We'll do our best to address it.InstallationPyPI installer (recommended)pip install histocartographyDevelopment setupClone the repo:git clone https://github.com/histocartography/histocartography.git && cd histocartographyCreate a conda environment:conda env create -f environment.ymlActivate it:conda activate histocartographyAddhistocartographyto your python path:export PYTHONPATH="<PATH>/histocartography:$PYTHONPATH"TestsTo ensure proper installation, run unit tests as:python-munittestdiscover-stest-p"test_*"-vRunning tests on cpu can take up to 20mn.Using histocartographyThehistocartographylibrary provides a set of helpers grouped in different modules, namelypreprocessing,ml,visualizationandinterpretability.For instance, inhistocartography.preprocessing, building a cell-graph from an H&E image is as simple as:>> from histocartography.preprocessing import NucleiExtractor, DeepFeatureExtractor, KNNGraphBuilder
>> 
>> nuclei_detector = NucleiExtractor()
>> feature_extractor = DeepFeatureExtractor(architecture='resnet34', patch_size=72)
>> knn_graph_builder = KNNGraphBuilder(k=5, thresh=50, add_loc_feats=True)
>>
>> image = np.array(Image.open('docs/_static/283_dcis_4.png'))
>> nuclei_map, _ = nuclei_detector.process(image)
>> features = feature_extractor.process(image, nuclei_map)
>> cell_graph = knn_graph_builder.process(nuclei_map, features)The output can be then visualized with:>> from histocartography.visualization import OverlayGraphVisualization, InstanceImageVisualization

>> visualizer = OverlayGraphVisualization(
...     instance_visualizer=InstanceImageVisualization(
...         instance_style="filled+outline"
...     )
... )
>> viz_cg = visualizer.process(
...     canvas=image,
...     graph=cell_graph,
...     instance_map=nuclei_map
... )
>> viz_cg.show()A list of examples to discover the capabilities of thehistocartographylibrary is provided inexamples. The examples will show you how to perform:stain normalizationwith Vahadane or Macenko algorithmcell graph generationto transform an H&E image into a graph-based representation where nodes encode nuclei and edges nuclei-nuclei interactions. It includes: nuclei detection based on HoverNet pretrained on PanNuke dataset, deep feature extraction and kNN graph building.tissue graph generationto transform an H&E image into a graph-based representation where nodes encode tissue regions and edges tissue-to-tissue interactions. It includes: tissue detection based on superpixels, deep feature extraction and RAG graph building.feature cube extractionto extract deep representations of individual patches depicting the imagecell graph explainerto generate an explanation to highlight salient nodes. It includes inference on a pretrained CG-GNN model followed by GraphGradCAM explainer.A tutorial with detailed descriptions and visualizations of some of the main functionalities is providedhereas a notebook.External RessourcesLearn more about GNNsWe have prepared a gentle introduction to Graph Neural Networks. In this tutorial, you can findslides,notebooksand a set ofreference papers.For those of you interested in exploring Graph Neural Networks in depth, please refer tothis contentorthis one.Papers already using this libraryHierarchical Graph Representations for Digital Pathology, Pati et al., preprint, 2021.[pdf][code]Quantifying Explainers of Graph Neural Networks in Computational Pathology,  Jaume et al., CVPR, 2021.[pdf][code]Learning Whole-Slide Segmentation from Inexact and Incomplete Labels using Tissue Graphs, Anklin et al., preprint, 2021.[pdf][code]If you use this library, please consider citing:@inproceedings{jaume2021,
    title = {HistoCartography: A Toolkit for Graph Analytics in Digital Pathology},
    author = {Guillaume Jaume, Pushpak Pati, Valentin Anklin, Antonio Foncubierta, Maria Gabrani},
    booktitle = {https://arxiv.org/pdf/2107.10073},
    year = {2021}
} 

@inproceedings{pati2021,
    title = {Hierarchical Graph Representations for Digital Pathology},
    author = {Pushpak Pati, Guillaume Jaume, Antonio Foncubierta, Florinda Feroce, Anna Maria Anniciello, Giosuè Scognamiglio, Nadia Brancati, Maryse Fiche, Estelle Dubruc, Daniel Riccio, Maurizio Di Bonito, Giuseppe De Pietro, Gerardo Botti, Jean-Philippe Thiran, Maria Frucci, Orcun Goksel, Maria Gabrani},
    booktitle = {Medical Image Analysis (MEDIA)},
    year = {2021}
}