---
title: "Exploring HoverNet Features from imageFeatureTCGA using HistoImagePlot"
author: "Ilaria Billato"
date: "2025-11-13"
output:
  BiocStyle::html_document:
    toc: true
    number_sections: true
    toc_float: true
    toc_depth: 3
package: HistoImagePlot
vignette: >
  %\VignetteIndexEntry{HistoImagePlot}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# imageFeatureTCGA

```{r setup, include=FALSE}
knitr::opts_chunk$set(cache = TRUE, echo = TRUE)
```

```{r load_packages, include=TRUE, results="hide", message=FALSE, warning=FALSE}
library(imageFeatureTCGA)
library(HistoImagePlot)
library(dplyr)
library(SpatialExperiment)
library(ggplot2)
```

# Installation

```{r install, eval=FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("waldronlab/HistoImagePlot")
```

# Introduction

HoverNet is a deep learning model for simultaneous segmentation and 
classification of nuclei in multi-tissue histology images. 
This vignette demonstrates how to import HoverNet output files 
into Bioconductor's spatial data structures and create 
visualizations of the segmentation results.

The package supports two main file formats:

- **JSON files** (`.json` or `.json.gz`): Contains cell coordinates, types, and 
    optional contours
- **H5AD files** (`.h5ad`): AnnData format with additional
    computed features like mean intensity and nearest neighbor distance

# Importing HoverNet JSON Data

## From Local Files

## Import the H5ad file into a `SpatialExperiment` 
object from URLs (with Automatic Caching)
The file will be automatically cached using `BiocFileCache`:

```{r h5ad}
hov_file <- paste0(
    "https://store.cancerdatasci.org/hovernet/h5ad/",
    "TCGA-23-1021-01Z-00-DX1.F07C221B-D401-47A5-9519-10DE59CA1E9D.h5ad.gz")

thumb_path <- paste0(
    "https://store.cancerdatasci.org/hovernet/thumb/",
    "TCGA-23-1021-01Z-00-DX1.F07C221B-D401-47A5-9519-10DE59CA1E9D.png")

hn_spe <- HoverNet(hov_file, outClass = "SpatialExperiment") |>
    import()
```


The package provides a convenient function to overlay the segmentation on the 
original tissue thumbnail image.

## Basic Overlay

```{r overlay-basic, fig.width=12, fig.height=6}

thumb_path <- paste0(
    "https://store.cancerdatasci.org/hovernet/thumb/",
    "TCGA-23-1021-01Z-00-DX1.F07C221B-D401-47A5-9519-10DE59CA1E9D.png")

plotHoverNetH5ADOverlay(hn_spe, thumb_path)
```

## Customized Overlay

```{r overlay-custom, fig.width=12, fig.height=6}
plotHoverNetH5ADOverlay(
    hn_spe,
    thumb_path,
    title = "Ovarian Cancer Tissue - Cell Segmentation",
    point_size = 0.02,
    legend_point_size = 3
)
```

## Custom Color Palette

```{r overlay-colors, fig.width=12, fig.height=6}
custom_colors <- c(
    "no label" = "#808080",
    "neoplastic" = "#E31A1C",
    "inflammatory" = "#1F78B4",
    "stromal" = "#33A02C",
    "necrotic" = "#FF7F00",
    "benign epithelial" = "#6A3D9A"
)

plotHoverNetH5ADOverlay(
    hn_spe,
    thumb_path,
    color_palette = custom_colors,
    title = "Custom Color Scheme"
)
```



H5AD files contain additional computed features like mean intensity and nearest 
neighbor distance.


## Visualizing Additional Features

```{r h5ad-features, fig.width=10, fig.height=8}
h5ad_coords <- data.frame(spatialCoords(hn_spe), colData(hn_spe))

p1 <- ggplot(h5ad_coords, aes(x = x_centroid, y = y_centroid, 
                            color = mean_intensity)) +
    geom_point(size = 0.5) +
    scale_color_viridis_c() +
    coord_fixed() +
    theme_minimal() +
    labs(title = "Mean Intensity", color = "Intensity")

p2 <- ggplot(h5ad_coords, aes(x = x_centroid, y = y_centroid, 
                                color = nearest_neighbor_distance)) +
    geom_point(size = 0.5) +
    scale_color_viridis_c(option = "plasma") +
    coord_fixed() +
    theme_minimal() +
    labs(title = "Nearest Neighbor Distance", color = "Distance")

cowplot::plot_grid(p1, p2, ncol = 2)
```




# Session Info

<details>
    <summary>Click here for Session Info</summary>
```{r sessioninfo}
sessionInfo()
```
</details>