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

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

## Overview

Rbearcat provides three table functions that apply UC styling automatically:

| Function | Purpose |
|---|---|
| `bcat_reg_table()` | Regression results (wraps `modelsummary`) |
| `bcat_sum_table()` | Descriptive / summary statistics |
| `bcat_cor_table()` | Correlation matrix with significance stars |

All three auto-detect the output format (HTML, PDF, Word) and style accordingly.

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

## Regression Tables with `bcat_reg_table()`

### Single Model

```{r reg-single}
m1 <- lm(mpg ~ wt + hp, data = mtcars)
bcat_reg_table(m1, caption = "Model 1: MPG predicted by Weight and Horsepower")
```

### Comparing Multiple Models

Pass a named list of models to display them side by side:

```{r reg-multi}
m2 <- lm(mpg ~ wt + hp + cyl, data = mtcars)
m3 <- lm(mpg ~ wt + hp + cyl + disp, data = mtcars)

bcat_reg_table(
  list("Base" = m1, "Add Cylinders" = m2, "Full" = m3),
  caption = "Comparing Nested OLS Models"
)
```

### Robust Standard Errors

Use `se_type` to pass a heteroskedasticity-consistent variance estimator:

```{r reg-robust}
bcat_reg_table(m1, se_type = "HC1", caption = "HC1 Robust Standard Errors")
```

### Custom Coefficient Names and GOF

```{r reg-rename}
bcat_reg_table(
  m2,
  coef_rename = c("wt" = "Weight (1000 lbs)",
                   "hp" = "Horsepower",
                   "cyl" = "Cylinders"),
  gof_map = c("nobs", "r.squared", "adj.r.squared"),
  caption = "Custom Labels"
)
```

### Changing Significance Stars

```{r reg-stars}
bcat_reg_table(
  m1,
  stars = c("+" = 0.1, "*" = 0.05, "**" = 0.01, "***" = 0.001),
  caption = "Alternative Star Convention"
)
```

## Summary Statistics with `bcat_sum_table()`

### Basic Usage

Pass a data frame (or subset of columns) to get mean, SD, min, median, max, N,
and percent missing:

```{r sum-basic}
bcat_sum_table(
  mtcars[, c("mpg", "wt", "hp", "qsec")],
  caption = "Descriptive Statistics for mtcars"
)
```

### Grouped Summaries

Use `by` to compute statistics within groups:

```{r sum-grouped}
bcat_sum_table(
  mtcars[, c("mpg", "wt", "hp", "cyl")],
  by = "cyl",
  caption = "Summary Statistics by Cylinder Count"
)
```

### Selecting Statistics

Choose only the statistics you need:

```{r sum-select}
bcat_sum_table(
  mtcars[, c("mpg", "hp")],
  stats = c("mean", "sd", "n"),
  caption = "Mean, SD, and N Only"
)
```

## Correlation Matrices with `bcat_cor_table()`

### Basic Correlation Matrix

By default, shows the lower triangle with Pearson correlations and significance
stars:

```{r cor-basic}
bcat_cor_table(
  mtcars[, c("mpg", "wt", "hp", "disp", "qsec")],
  caption = "Pearson Correlation Matrix"
)
```

### Full Matrix with Spearman Method

```{r cor-spearman}
bcat_cor_table(
  mtcars[, c("mpg", "wt", "hp")],
  method = "spearman",
  full_matrix = TRUE,
  caption = "Full Spearman Correlation Matrix"
)
```

### Without Stars

```{r cor-nostars}
bcat_cor_table(
  mtcars[, c("mpg", "wt", "hp")],
  stars = FALSE,
  caption = "Correlation Matrix (No Stars)"
)
```

## General Table Styling with `bcat_fmt_style_table()`

For any data frame, `bcat_fmt_style_table()` applies UC header colors and
formatting:

```{r style-table}
bcat_fmt_style_table(
  head(iris, 8),
  caption = "Iris Sample",
  striped = TRUE
)
```

### Spanning Headers

```{r style-header}
bcat_fmt_style_table(
  head(iris, 5),
  header = "Iris Dataset — First 5 Rows",
  caption = "With Spanning Header"
)
```

## Customizing Appearance

All table functions share these styling parameters:

| Parameter | Default | Description |
|---|---|---|
| `header_bg_color` | UC Red | Header background color |
| `header_txt_color` | `"white"` | Header text color |
| `font_size` | `12` | Font size |
| `striped` | `TRUE` | Zebra-striped rows |
| `caption` | `NULL` | Table caption |
| `footer` | `NULL` | Table footnote |

```{r custom-style}
bcat_reg_table(
  m1,
  header_bg_color = palette_UC[["Bearcats Black"]],
  font_size = 11,
  footer = "Source: mtcars dataset",
  caption = "Custom Styled Table"
)
```