---
title: "UC-Branded Plots"
output: Rbearcat::UC_html_document
vignette: >
  %\VignetteIndexEntry{UC-Branded Plots}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

Rbearcat provides nine plot functions that wrap ggplot2 with UC themes, the
official UC expanded color palette, and a consistent interface. Every function
returns a ggplot object that can be further customized with standard `+`
layers.

| Function | Chart type |
|---|---|
| `bcat_plt_bar()` | Bar chart (counts, identity, or summary stats) |
| `bcat_plt_line()` | Line chart |
| `bcat_plt_point()` | Scatter plot |
| `bcat_plt_area()` | Stacked / filled area chart |
| `bcat_plt_hist()` | Histogram with optional density curve |
| `bcat_plt_box()` | Box plot or violin plot |
| `bcat_plt_coef()` | Coefficient (forest) plot |
| `bcat_plt_diag()` | Regression diagnostic dashboard |
| `bcat_plt_ts()` | Time series with decomposition and ACF/PACF |

```{r load}
library(Rbearcat)
library(ggplot2)
set_UC_geoms()
```

## Bar Charts — `bcat_plt_bar()`

### Frequency Counts

```{r bar-freq}
bcat_plt_bar(
  df = mpg,
  x = class,
  order = TRUE,
  title = "Vehicle Count by Class",
  x_lab = NULL, y_lab = "Count"
)
```

### Grouped Bars with Summary Statistic

Use `stat` to compute a summary (mean, median, sum) of `y` within each group:

```{r bar-stat}
bcat_plt_bar(
  df = mpg,
  x = class,
  y = hwy,
  fill = factor(year),
  stat = "mean",
  position = "dodge",
  order = TRUE,
  coord_flip = TRUE,
  x_lab = NULL, y_lab = "Highway MPG",
  title = "Mean Highway MPG by Class and Year"
)
```

### Stacked Proportions

```{r bar-fill}
bcat_plt_bar(
  df = mpg,
  x = class,
  fill = drv,
  position = "fill",
  y_scale = scale_y_continuous(labels = scales::percent_format()),
  title = "Drive Type Proportions by Class",
  x_lab = NULL, y_lab = NULL,
  legend_lab = "Drive"
)
```

## Line Charts — `bcat_plt_line()`

### Basic Line Plot

```{r line-basic}
bcat_plt_line(
  df = economics,
  x = date,
  y = unemploy,
  y_scale = scale_y_continuous(labels = scales::comma_format()),
  title = "US Unemployment Over Time",
  y_lab = "Number Unemployed"
)
```

### Multiple Series with Highlight Regions

```{r line-multi, fig.height = 6}
bcat_plt_line(
  df = economics_long,
  x = date,
  y = value,
  color = variable,
  facet = vars(variable),
  facet_scale = "free_y",
  ncol = 1,
  x_highlight_min = as.Date(c("2007-12-01")),
  x_highlight_max = as.Date(c("2009-06-01")),
  title = "Economic Indicators with Recession Shading",
  x_lab = NULL, y_lab = NULL,
  legend_lab = NULL
)
```

## Scatter Plots — `bcat_plt_point()`

### Basic Scatter

```{r point-basic}
bcat_plt_point(
  df = iris,
  x = Sepal.Length,
  y = Sepal.Width,
  title = "Sepal Width vs Length",
  x_lab = "Length", y_lab = "Width"
)
```

### Faceted with Fit Lines

```{r point-facet}
bcat_plt_point(
  df = iris,
  x = Sepal.Length,
  y = Sepal.Width,
  color = Species,
  facet = vars(Species),
  smooth = TRUE,
  method = "lm",
  nrow = 1,
  title = "By Species with Linear Fit",
  x_lab = "Length", y_lab = "Width",
  legend_lab = NULL
)
```

## Area Charts — `bcat_plt_area()`

```{r area}
set.seed(42)
d <- data.frame(
  t = rep(0:23, each = 4),
  category = rep(LETTERS[1:4], 24),
  value = round(runif(96, 10, 50))
)

bcat_plt_area(
  df = d, x = t, y = value, fill = category,
  position = "stack",
  title = "Stacked Area Chart",
  x_lab = "Hour", y_lab = "Value",
  legend_lab = "Category"
)
```

### Filled (100%) Area

```{r area-fill}
bcat_plt_area(
  df = d, x = t, y = value, fill = category,
  position = "fill",
  title = "Proportional Area Chart",
  x_lab = "Hour", y_lab = NULL,
  legend_lab = "Category"
)
```

## Histograms — `bcat_plt_hist()`

### Basic Histogram

A dashed vertical line at the mean is drawn by default.

```{r hist-basic}
bcat_plt_hist(
  mtcars, x = mpg,
  title = "Distribution of MPG",
  x_lab = "Miles per Gallon"
)
```

### With Density Curve

```{r hist-density}
bcat_plt_hist(
  mtcars, x = mpg,
  density = TRUE,
  bins = 15,
  title = "MPG with Density Overlay",
  x_lab = "Miles per Gallon"
)
```

### Faceted

```{r hist-facet}
bcat_plt_hist(
  mtcars, x = mpg,
  facet = vars(cyl),
  facet_scale = "free_x",
  title = "MPG Distribution by Cylinder Count"
)
```

## Box Plots and Violin Plots — `bcat_plt_box()`

### Box Plot with Jittered Points

Points are overlaid by default to show the raw data.

```{r box-basic}
bcat_plt_box(
  mtcars,
  x = factor(cyl),
  y = mpg,
  title = "MPG by Cylinder Count",
  x_lab = "Cylinders", y_lab = "MPG"
)
```

### Violin Plot

```{r box-violin}
bcat_plt_box(
  mtcars,
  x = factor(cyl),
  y = mpg,
  violin = TRUE,
  title = "MPG Distribution (Violin)",
  x_lab = "Cylinders", y_lab = "MPG"
)
```

### Ordered and Flipped

```{r box-flip}
bcat_plt_box(
  mtcars,
  x = factor(gear),
  y = mpg,
  order = TRUE,
  coord_flip = TRUE,
  title = "MPG by Gear Count (Ordered)",
  x_lab = "Gears", y_lab = "MPG"
)
```

## Coefficient Plots — `bcat_plt_coef()`

Visualize regression coefficients with confidence intervals.

### Single Model

```{r coef-single}
m1 <- lm(mpg ~ wt + hp + cyl + disp, data = mtcars)
bcat_plt_coef(m1, title = "OLS Coefficient Estimates")
```

### Comparing Models

```{r coef-multi}
m2 <- lm(mpg ~ wt + hp, data = mtcars)
bcat_plt_coef(
  list("Full" = m1, "Base" = m2),
  title = "Coefficient Comparison",
  subtitle = "95% Confidence Intervals"
)
```

### Highlighting a Coefficient

```{r coef-highlight}
bcat_plt_coef(
  m1,
  highlight = "Wt",
  title = "Highlighting Weight"
)
```

## Regression Diagnostics — `bcat_plt_diag()`

A 4-panel dashboard: Residuals vs Fitted, Q-Q, Scale-Location, and
Residuals vs Leverage. Prints Breusch-Pagan, Shapiro-Wilk, and Durbin-Watson
test results to the console.

```{r diag, fig.height = 6, fig.width = 8}
m <- lm(mpg ~ wt + hp + cyl, data = mtcars)
bcat_plt_diag(m)
```

### Select Specific Panels

```{r diag-select}
bcat_plt_diag(m, which = c(1, 2), tests = FALSE)
```

## Time Series — `bcat_plt_ts()`

### Basic Time Series

```{r ts-basic}
bcat_plt_ts(
  economics,
  x = date, y = unemploy,
  y_scale = scale_y_continuous(labels = scales::comma_format()),
  title = "US Unemployment",
  y_lab = "Persons Unemployed"
)
```

### With Highlight Regions

```{r ts-highlight}
bcat_plt_ts(
  economics,
  x = date, y = unemploy,
  y_scale = scale_y_continuous(labels = scales::comma_format()),
  x_highlight_min = as.Date("2007-12-01"),
  x_highlight_max = as.Date("2009-06-01"),
  title = "US Unemployment with Great Recession Shading"
)
```

### STL Decomposition

```{r ts-decompose, fig.height = 7}
bcat_plt_ts(economics, x = date, y = unemploy, decompose = TRUE)
```

### ACF / PACF

```{r ts-acf}
bcat_plt_ts(economics, x = date, y = unemploy, acf = TRUE)
```

## Common Parameters

All `bcat_plt_*` functions share a consistent parameter interface:

| Parameter | Description |
|---|---|
| `df` | Data frame |
| `x`, `y` | Variables mapped to axes |
| `color` / `fill` | Grouping aesthetic |
| `facet` | Facetting variable(s) wrapped in `vars()` |
| `title`, `subtitle`, `caption` | Plot text |
| `x_lab`, `y_lab` | Axis labels |
| `legend_lab`, `legend_position`, `legend_hide` | Legend control |
| `x_scale`, `y_scale` | Custom axis scales |
| `x_refline`, `y_refline` | Reference lines |
| `facet_scale` | `"fixed"`, `"free"`, `"free_x"`, `"free_y"` |

Every function returns a standard ggplot object, so you can add more layers:

```{r addlayer}
bcat_plt_point(iris, Sepal.Length, Sepal.Width,
               title = "Adding a Custom Annotation") +
  annotate("text", x = 7, y = 4.2, label = "Outlier region",
           color = "red", fontface = "italic")
```