---
title: "Getting Started with BFHtheme"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with BFHtheme}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

BFHtheme streamlines the process of producing ggplot2 graphics that follow the
visual identity for Bispebjerg og Frederiksberg Hospital and Region
Hovedstaden. The package bundles branded themes, colour palettes, scales, and
workflow helpers that keep your plots on-brand with minimal effort.

In this vignette you will learn how to:

- install and load the package,
- apply the core BFH theme and colour scales,
- explore the available palettes and theme variants,
- set global defaults for a session, and
- save or export plots using BFH-recommended dimensions.

| Task | Helpful functions |
| --- | --- |
| Apply the default styling | `theme_bfh()` |
| Use branded colour scales | `scale_color_bfh()`, `scale_fill_bfh()` |
| Manage fonts and defaults | `set_bfh_defaults()`, `set_bfh_fonts()` |
| Browse colours and palettes | `bfh_cols()`, `show_bfh_palettes()` |
| Export figures | `bfh_save()` |

## Installation

BFHtheme is currently distributed via GitHub. Install the package with
`devtools` or `remotes` and then load it alongside ggplot2:

```{r eval=FALSE}
# install.packages("remotes")
remotes::install_github("johanreventlow/BFHtheme")
```

```{r load-packages, message=FALSE}
library(BFHtheme)
library(ggplot2)
```

## Basic Usage

### Applying a Theme

Start by adding `theme_bfh()` to any ggplot. It injects BFH typography,
spacing, and colour defaults while leaving your existing geoms untouched.
Fonts are auto-detected the first time you call the theme.

```{r basic-theme, message=FALSE}
ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point() +
  labs(
    title = "Fuel Efficiency by Vehicle Weight",
    x = "Weight (1000 lbs)",
    y = "Miles per Gallon"
  ) +
  theme_bfh()
```

### Using Colour Scales

Pair the theme with branded colour scales. Use the discrete variants when
mapping factors and the continuous versions for numeric gradients.

```{r color-scales, message=FALSE}
ggplot(mtcars, aes(x = wt, y = mpg, color = factor(cyl))) +
  geom_point(size = 3) +
  labs(
    title = "Fuel Efficiency by Cylinder Count",
    x = "Weight (1000 lbs)",
    y = "Miles per Gallon",
    color = "Cylinders"
  ) +
  scale_color_bfh() +
  theme_bfh()
```

`scale_fill_bfh()` works the same way for fills (bars, areas, etc.).

For continuous colour mappings, switch to the gradient helpers:

```{r continuous-colors, message=FALSE}
ggplot(mtcars, aes(x = wt, y = mpg, color = hp)) +
  geom_point(size = 3) +
  labs(
    title = "Fuel Efficiency and Horsepower",
    x = "Weight (1000 lbs)",
    y = "Miles per Gallon",
    color = "Horsepower"
  ) +
  scale_color_bfh_continuous(palette = "blues") +
  theme_bfh()
```

The `palette` argument controls which sequential palette is used. Reverse the
direction with `reverse = TRUE` when needed for visual clarity.

### Available Colour Palettes

Use `show_bfh_palettes()` to preview every palette side by side:

```{r show-palettes, eval=FALSE}
# Display all available palettes
show_bfh_palettes()
```

| Palette | Description | Recommended for |
| --- | --- | --- |
| `main` | Core hospital colours | Default discrete scales |
| `hospital` | Full Bispebjerg & Frederiksberg Hospital palette | Hospital reports |
| `hospital_blues` / `hospital_blues_seq` | Monochrome blue gradients | Continuous hospital data |
| `regionh` | Region Hovedstaden primaries | Region-level reporting |
| `regionh_blues` / `regionh_blues_seq` | Navy-focused gradients | Region dashboards |
| `hospital_infographic`, `regionh_infographic` | High-contrast mixes | Infographics and slides |

Access individual colours programmatically:

```{r colors}
# Get specific colors
bfh_cols("hospital_primary", "hospital_blue")

# Get all colors
head(bfh_cols())
```

## Theme Variants

BFHtheme provides several theme variants for different use cases:

### Standard Theme

`theme_bfh()` is the all-purpose choice for reports and dashboards.

```{r theme-standard, message=FALSE}
ggplot(mtcars, aes(x = factor(cyl), fill = factor(cyl))) +
  geom_bar() +
  labs(title = "Vehicle Count by Cylinder") +
  scale_fill_bfh() +
  theme_bfh()
```

### Customizing theme_bfh()

You can customize `theme_bfh()` for specific use cases by adding additional
`theme()` calls after applying the base theme.

```{r theme-custom, message=FALSE}
# Example: Create a dark theme variant
ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point(color = "white") +
  labs(title = "Custom Dark Theme") +
  theme_bfh() +
  theme(
    plot.background = element_rect(fill = "#1a1a1a", color = NA),
    panel.background = element_rect(fill = "#1a1a1a", color = NA),
    text = element_text(color = "white"),
    axis.text = element_text(color = "grey80")
  )
```

```{r theme-custom-minimal, message=FALSE}
# Example: Create a minimal variant without gridlines
ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point() +
  labs(title = "Custom Minimal Theme") +
  theme_bfh() +
  theme(
    panel.grid.major = element_blank(),
    panel.grid.minor = element_blank()
  )
```

## Setting Global Defaults

Call `set_bfh_defaults()` at the start of a session to make BFH styling the
global ggplot2 default. This updates the active theme and seed colours for
common geoms.

```{r defaults, eval=FALSE}
# Set BFH theme and colors as defaults
set_bfh_defaults()

# Now all plots automatically use BFH styling
ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point()

# For plots with color mappings, still add the scale manually
ggplot(mtcars, aes(x = wt, y = mpg, color = factor(cyl))) +
  geom_point() +
  scale_color_bfh()

# Reset to ggplot2 defaults when done
reset_bfh_defaults()
```

Remember to reset the defaults before working on non-BFH projects.

## Saving Plots

`bfh_save()` wraps `ggplot2::ggsave()` with BFH-friendly presets so exported
figures drop straight into reports and slides.

```{r save-plot, eval=FALSE}
p <- ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point() +
  theme_bfh()

# Save with preset dimensions
bfh_save("plot.png", p, preset = "report_full")

# Custom dimensions
bfh_save("plot.pdf", p, width = 8, height = 6, dpi = 600)
```

Inspect the recommended sizes programmatically:

```{r dimensions, eval=FALSE}
# Internal function - use ::: to access
BFHtheme:::get_bfh_dimensions("presentation", "wide")
```

## Font Configuration

Consistent typography is central to the BFH visual language. The package
detects the best available font in this order:

1. Mari (official BFH font installed on hospital machines)
2. Roboto (open-source alternative)
3. Arial (universal fallback)
4. A system sans-serif font

Check which fonts are available on your machine:

```{r fonts, eval=FALSE}
check_bfh_fonts()
```

If you install new fonts during a session, run `clear_bfh_font_cache()` or call
`get_bfh_font(force_refresh = TRUE)` to re-detect them.

Set up fonts and update ggplot defaults in one go:

```{r font-setup, eval=FALSE}
# Setup and enable fonts
setup_bfh_fonts()

# Set as default for all themes
set_bfh_fonts()
```

Need Roboto? `install_roboto_font()` prints step-by-step installation guidance.

## Where to Next

- Deepen your workflow in `vignette("customization")` (advanced theme tweaks, palettes, and layout helpers).
- Configure organisation-specific branding with `vignette("theming")`.
- Browse documentation for individual helpers using `help(package = "BFHtheme")` or `?theme_bfh`.