havoc-clustering-v2 0.0.4

Histomic Atlases of Variation Of Cancers (HAVOC) is a versatile tool that helps map histomic heterogeneity across H&E-stained digital slide images to help guide regional deployment of molecular resources to the most relevant/biodiverse tumor niches

Histomic Atlases of Variation Of Cancers (HAVOC)

HAVOC is a versatile tool that maps histomic heterogeneity across H&E-stained digital slide images to help guide regional deployment of molecular resources to the most relevant/biodiverse tumor niches

Cloud usage

Explore HAVOC on https://www.codido.co to run on the cloud

Version Notes

• Current: Uses a foundation-model feature extractor (Prov-GigaPath) with 2x2 grid pooling to allow tiles larger than 256x256 (20x). This is recommended for all new applications.

• Legacy: VGG19-based implementation used in the original paper. Please visit the paper branch for more info (No longer updated).

Installation

Note: HAVOC requires the torch, torchvision, and timm packages, which are not installed automatically. Please install the appropriate PyTorch build (CPU or GPU) before installing HAVOC.

Note: System-level OpenSlide must be installed manually from: https://openslide.org/download/

Use the package manager pip to install havoc-clustering.

pip install havoc-clustering-v2

Usage

from huggingface_hub import login
from havoc_clustering_v2.havoc import HAVOC, HAVOCConfig
from havoc_clustering_v2.general_utility.slide import Slide

# Required to perform initial download of the feature extractor (prov-gigapath) from Huggingface.
login(token=hf_token)

# To run HAVOC, it requires:
# 1. a Slide object
s = Slide(slide_path)

# 2. a HAVOCConfig object
# Below are the default config values
config = HAVOCConfig(
    out_dir='./', # root save dir. results will be stored per slide in `root_save_dir`\<slide_name>\`
    k_vals=[7, 8, 9],
    # save the tiles belonging to each color cluster within the havoc map for a given k
    # ie [7,9] would save the colored tiles belonging to k=7 and k=9
    # NOTE: this should be a subset of k_vals
    save_tiles_k_vals=[], 

    tile_size=512, # at 20x magnification. minimum tile size of 256 required

    min_tissue_amt=0.5, # blank filtering
    
    # for each k value, make a tsne and/or dendrogram and/or pearson coefficient clustermap
    extra_metrics=['tsne', 'dendrogram', 'corr_clustmap']
)
    

havoc = HAVOC(config)
havoc.run(s)

Result output

• Colortiled maps
• CSV file of cluster info + DLFVs (cluster_info_df.csv)
• Optionally:
  • Original slide thumbnail
  • TSNEs
  • Dendrograms
  • Correlation clustermap

Multi-slide correlation map

By running HAVOC on multiple slides, you may want to combine all the generated correlation clustermaps into a mega clustermap.

1. Create a folder containing each slide's cluster_info_df.csv file

from havoc_clustering_v2.correlation_of_dlfv_groups import create_correlation_clustermap_multi_slide

create_correlation_clustermap_multi_slide(folder_of_csvs, target_k=9)

NOTE: the target_k should be a k-value you ran HAVOC with

Citation

Please refer to the paper "HAVOC: Small-scale histomic mapping of cancer biodiversity across large tissue distances using deep neural networks" (DOI: 10.1126/sciadv.adg1894)

License

GNU General Public License v3 (GPLv3)