---
title: "Customizing Style in phylobar"
output: BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{3. Customizing Style in phylobar}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    message = FALSE
)
```

# Overview

Phylobar draws a phylogenetic tree alongside a stacked bar chart.
This vignette shows how to customize visual style: text sizes, color
palettes, layout ratios, legend placement, and more.

We will use a small random dataset:

```{r example_data}
library(ape)
library(phylobar)

set.seed(1)
tree <- rtree(20)
samples <- matrix(rpois(100 * 20, 1), nrow = 100, ncol = 20)

phylobar(samples, tree)
```

The function signature and key styling parameters we will explore:

* `palette`: colors used for painted subtrees (stacked bars)
* `width`, `height`: widget size in pixels
* `sample_font_size`, `sample_label_margin`, `sample_label_space`
* `sample_magnify`, `sample_show_all`
* `rel_width`, `rel_height`, `rel_space`
* `legend_mode`, `legend_x_start`, `legend_spacing`
* `hclust_order`: optional hierarchical reordering of rows/columns

Internally, `phylobar()` ensures that the tree has node labels and that
the abundance matrix has row/column names. If they’re missing, helper
`check_inputs()` creates sensible defaults (e.g., `sample_1`, `sample_2`).

# Color Palette

If a palette is not provided, phylobar uses a default set of six colors.
It is possible to supply own vector of hex colors or R color names.

```{r palette_example}
# Custom qualitative palette (as many colors as you want; repeats if needed)
my_palette <- c(
    "#4E79A7", "#F28E2B", "#E15759",
    "#76B7B2", "#59A14F", "#EDC948"
)
phylobar(samples, tree, palette = my_palette)
```

# Widget Size

By default the widget adapts to the container. Fix its size by:

```{r widget_size}
phylobar(samples, tree,
    width = 800,
    height = 500
)
```

# Sample Label Styling

Control sample label font size, spacing, and hover magnification.

```{r sample_label_styling}
phylobar(samples, tree,
    width = 800, height = 500,
    sample_font_size = 10,
    sample_label_margin = 10, # space between labels and bars
    sample_label_space = 100, # reserved margin for labels
    sample_magnify = 1.3, # how much to enlarge labels on hover
    sample_show_all = TRUE
)
```

# Tree-bar Layout Ratio

Change how much horizontal and vertical space the tree occupies:

* `rel_width`: fraction of total width reserved for the tree panel (default 0.4)
* `rel_height`: fraction of total height for the tree panel (default 0.85)
* `rel_space`: pixels between the tree and bar panels (default 10)

```{r layout_ratio}
phylobar(
    samples, tree,
    width = 800, height = 500,
    sample_label_space = 100,
    sample_magnify = 1.3,
    rel_width = 0.2, # narrower tree
    rel_height = 0.70, # shorter tree (more space for legend)
    rel_space = 14 # larger gap between panels
)
```

# Legend Placement

Choose whether painted subtree labels appear in a separate legend
(`legend_mode = TRUE`, default) or placed inside the tree
(`legend_mode = FALSE`). `legend_x_start` and `legend_spacing`
can also be adjusted to control the legen position.

```{r legend_below}
# Legend below the tree (default)
phylobar(
    samples, tree,
    width = 800, height = 500,
    sample_label_space = 100,
    sample_magnify = 1.3,
    legend_mode = TRUE,
    legend_x_start = 20, # horizontal start in pixels
    legend_spacing = 20 # vertical spacing between legend items in pixels
)
```

```{r legend_inside}
# Put labels inside the tree instead of a separate legend
phylobar(
    samples, tree,
    width = 800, height = 500,
    sample_label_space = 100,
    sample_magnify = 1.3,
    legend_mode = FALSE,
    legend_x_start = 20, # horizontal start in pixels
    legend_spacing = 20 # vertical spacing between legend items in pixels
)
```

# Optional Hierarchical Reordering

`hclust_order = TRUE` (default) reorders samples/features by hierarchical
clustering, which can make patterns more visible. Turn it off to preserve
original order:

```{r hclust_no}
# Keep the input order as-is
phylobar(
    samples, tree,
    width = 800, height = 500,
    sample_label_space = 100,
    sample_magnify = 1.3,
    hclust_order = FALSE
)
```

# Session Info

```{r session}
sessionInfo()
```