---
title: "Interactive Pedigree Plotting with ggPedigreeInteractive()"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Interactive Pedigree Plotting with ggPedigreeInteractive()}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5
)
```

# Introduction

The `ggPedigreeInteractive()` function extends the static pedigree plots generated by `ggPedigree()` into fully interactive `Plotly` widgets. This allows users to explore pedigree data in a more dynamic way, with features such as hover text, zooming, and panning.
This vignette walks through:
- Basic usage of `ggPedigreeInteractive()`
- Customizing the interactive plot
- Adding tooltips for additional information


```{r load-packages}
# Load required packages
library(BGmisc) # ships the sample 'potter' pedigree
library(ggplot2) # used internally by ggPedigree*
library(viridis) # viridis for color palettes
library(plotly) # conversion layer for interactivity
library(ggpedigree) # the package itself
```


# Example data
The package includes a small toy pedigree for the Harry Potter universe:

```{r load-data}
# Load the example data
data("potter")
# Display the first few rows of the dataset
head(potter)
```


# Basic Usage

A minimal call is just:

```r
ggPedigreeInteractive(potter)
```

...but you will usually want to identify the core primary‑key columns in advance:

```{r basic-usage-2}
plt <- ggPedigreeInteractive(
  potter,
  famID    = "famID",
  personID = "personID",
  momID    = "momID",
  dadID    = "dadID"
) |> plotly::hide_legend()
```

```{r eval=FALSE, include=TRUE}
plt
```

```{r echo=FALSE}
# reduce file size for CRAN
if (interactive()) {
  # If running interactively, use plotly::partial_bundle
  # to reduce file size for CRAN
  plotly::partial_bundle(plt)
} else {
  plotly::partial_bundle(plt, local = TRUE)
}
```


# Customising labels and tool‑tips

`ggPedigreeInteractive()` accepts the same config list as `ggPedigree()`, 
plus the tooltip_cols argument for hover text. Below we enable node labels, 
nudge them upward a little, color by sex, and show both the `personID` and name fields in the hover:

```{r customize-aesthetics}
plt <- ggPedigreeInteractive(
  potter,
  famID = "famID",
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  config = list(
    label_nudge_y   = -.25,
    include_labels  = TRUE,
    label_method    = "geom_text",
    sex_color       = TRUE
  ),
  tooltip_cols = c("personID", "name")
)
```
```{r eval=FALSE, include=TRUE}
plt
```

```{r echo=FALSE}
# reduce file size for CRAN
if (interactive()) {
  # If running interactively, use plotly::partial_bundle
  # to reduce file size for CRAN
  plotly::partial_bundle(plt)
} else {
  plotly::partial_bundle(plt, local = TRUE)
}
```

# Further customisation

## Adding tooltips

Because the function returns a Plotly object, you can layer additional modifications on top:

```{r further-customization} 
plt2 <- plt %>%
  plotly::layout(
    title = "The Potter Family Tree (interactive)",
    hoverlabel = list(bgcolor = "white"),
    margin = list(l = 50, r = 50, t = 50, b = 50)
  ) %>%
  plotly::config(displayModeBar = TRUE)
```  
```{r eval=FALSE, include=TRUE}
plt2
```

```{r echo=FALSE}
# reduce file size for CRAN
if (interactive()) {
  # If running interactively, use plotly::partial_bundle
  # to reduce file size for CRAN
  plotly::partial_bundle(plt2)
} else {
  plotly::partial_bundle(plt2, local = TRUE)
}
```
You can also save the widget as standalone HTML:

```{r save-widget, eval=FALSE}
htmlwidgets::saveWidget(
  plt,
  file = "potter_interactive.html",
  selfcontained = TRUE
)
# Note: The above code will save the widget in the current working directory.
```


## Static Plot customisation

You can also create a static version of the plot using the `return_static` argument. This is useful for generating high-quality images for reports or publications. The static plot can be further customized using ggplot2 functions. It can also be plotted using `plotly::ggplotly()` to retain interactivity.

```{r static-plot}
static <- ggPedigreeInteractive(
  potter,
  famID = "famID",
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  config = list(
    label_nudge_y = -.25,
    include_labels = TRUE,
    label_method = "geom_text",
    sex_color = TRUE,
    return_static = TRUE
  ),
  tooltip_cols = c("personID", "name")
)
```

The static plot can be further customized using ggplot2 functions. 
```{r static-plot-customization}
static_plot <- static +
  ggplot2::labs(
    title = "The Potter Family Tree (static)",
    subtitle = "This is a static plot"
  ) +
  theme_bw(base_size = 12) +
  theme(
    panel.grid.major = element_blank(),
    panel.grid.minor = element_blank(),
    panel.background = element_blank(),
    axis.line        = element_line(colour = "black"),
    axis.text.x      = element_blank(),
    axis.text.y      = element_blank(),
    axis.ticks.x     = element_blank(),
    axis.ticks.y     = element_blank(),
    axis.title.x     = element_blank(),
    axis.title.y     = element_blank()
  ) + scale_color_viridis(
    discrete = TRUE,
    labels = c("Female", "Male", "Unknown")
  )

static_plot
```

You can also convert the static plot back to an interactive plot using `plotly::ggplotly()`:

```{r static-to-interactive}
plt2 <- plotly::ggplotly(static_plot,
  tooltip = "text",
  width   = NULL,
  height  = NULL
)
```

```{r eval=FALSE, include=TRUE}
plt2
```

```{r echo=FALSE}
# reduce file size for CRAN
if (interactive()) {
  # If running interactively, use plotly::partial_bundle
  # to reduce file size for CRAN
  plotly::partial_bundle(plt2)
} else {
  plotly::partial_bundle(plt2, local = TRUE)
}
```


# Conclusion

`ggPedigreeInteractive()` provides a powerful way to visualize pedigree data interactively. By leveraging the capabilities of Plotly, users can explore their data in a more dynamic and engaging manner. The function is designed to be flexible, allowing for customization of labels, tooltips, and overall aesthetics.