# UC-Branded Plots

## 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

    library(Rbearcat)
    library(ggplot2)
    set_UC_geoms()

## Bar Charts — `bcat_plt_bar()`

### Frequency Counts

    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:

    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

    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

    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

    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

    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

    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()`

    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

    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.

    bcat_plt_hist(
      mtcars, x = mpg,
      title = "Distribution of MPG",
      x_lab = "Miles per Gallon"
    )

### With Density Curve

    bcat_plt_hist(
      mtcars, x = mpg,
      density = TRUE,
      bins = 15,
      title = "MPG with Density Overlay",
      x_lab = "Miles per Gallon"
    )

### Faceted

    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.

    bcat_plt_box(
      mtcars,
      x = factor(cyl),
      y = mpg,
      title = "MPG by Cylinder Count",
      x_lab = "Cylinders", y_lab = "MPG"
    )

### Violin Plot

    bcat_plt_box(
      mtcars,
      x = factor(cyl),
      y = mpg,
      violin = TRUE,
      title = "MPG Distribution (Violin)",
      x_lab = "Cylinders", y_lab = "MPG"
    )

### Ordered and Flipped

    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

    m1 <- lm(mpg ~ wt + hp + cyl + disp, data = mtcars)
    bcat_plt_coef(m1, title = "OLS Coefficient Estimates")

### Comparing Models

    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

    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.

    m <- lm(mpg ~ wt + hp + cyl, data = mtcars)
    bcat_plt_diag(m)
    #>
    #> --- Diagnostic Tests ---
    #>
    #> Breusch-Pagan (heteroskedasticity): stat=2.935, p=0.4017  [PASS - no evidence of heteroskedasticity]
    #> Shapiro-Wilk (normality):           stat=0.935, p=0.0525  [PASS - residuals appear normal]
    #> Durbin-Watson (autocorrelation):     stat=1.644, p=0.1002  [PASS - no evidence of autocorrelation]

### Select Specific Panels

    bcat_plt_diag(m, which = c(1, 2), tests = FALSE)

## Time Series — `bcat_plt_ts()`

### Basic Time Series

    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

    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

    bcat_plt_ts(economics, x = date, y = unemploy, decompose = TRUE)

### ACF / PACF

    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:

    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")