---
title: "Number Formatting for Inline Reporting"
output: Rbearcat::UC_html_document
vignette: >
  %\VignetteIndexEntry{Number Formatting for Inline Reporting}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

Rbearcat provides six `bcat_fmt_*` functions for formatting numbers in inline
R expressions and tables. They wrap functions from the `scales` package with
sensible defaults.

| Function | Formats as |
|---|---|
| `bcat_fmt_dollar()` | Currency (`$1,234.56`) |
| `bcat_fmt_percent()` | Percentage (`12.3%`) |
| `bcat_fmt_comma()` | Comma-separated (`1,234`) |
| `bcat_fmt_scientific()` | Scientific notation (`1.23e+06`) |
| `bcat_fmt_date()` | Human-readable date (`March 10, 2026`) |
| `bcat_fmt_pvalue()` | P-value with `<`/`>` notation |

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

## Dollar Formatting — `bcat_fmt_dollar()`

```{r dollar}
bcat_fmt_dollar(c(1234.5, 67890, 0.99))
```

### Negative Values

The default uses a hyphen. Set `style_negative = "parens"` for accounting style:

```{r dollar-neg}
bcat_fmt_dollar(c(-500, 1200))
bcat_fmt_dollar(c(-500, 1200), style_negative = "parens")
```

### Scaling

Use `scale` to convert units (e.g., raw cents to dollars):

```{r dollar-scale}
bcat_fmt_dollar(c(150000, 275000), scale = 1e-3, accuracy = 1, suffix = "K")
```

## Percent Formatting — `bcat_fmt_percent()`

Multiplies by 100 by default (assumes proportions as input):

```{r percent}
bcat_fmt_percent(c(0.0523, 0.1, 0.9871))
```

### Pre-scaled Values

If values are already in percentage form, set `scale = 1`:

```{r percent-prescaled}
bcat_fmt_percent(c(5.23, 10, 98.71), scale = 1)
```

### Controlling Precision

```{r percent-accuracy}
bcat_fmt_percent(c(0.05234, 0.10011), accuracy = 0.01)
```

## Comma Formatting — `bcat_fmt_comma()`

```{r comma}
bcat_fmt_comma(c(1000, 50000, 1234567))
```

### With Suffix

```{r comma-suffix}
bcat_fmt_comma(c(5000, 10000, 80000), scale = 1e-3, accuracy = 1, suffix = "K")
```

## Scientific Notation — `bcat_fmt_scientific()`

```{r scientific}
bcat_fmt_scientific(c(0.00012, 3456789, 1.5e10))
```

### Controlling Digits

```{r scientific-digits}
bcat_fmt_scientific(c(123456, 789012), digits = 2)
```

## Date Formatting — `bcat_fmt_date()`

Converts character or Date objects to a human-readable format. The default
format is `"%B %e, %Y"` (e.g., "January  5, 2026").

```{r date}
bcat_fmt_date(Sys.Date())
bcat_fmt_date(c("2024-01-15", "2025-06-30"))
```

### Custom Format Strings

Use standard `strptime` codes:

```{r date-custom}
bcat_fmt_date("2025-12-25", format = "%d %b %Y")
bcat_fmt_date("2025-12-25", format = "%m/%d/%Y")
```

## P-value Formatting — `bcat_fmt_pvalue()`

Uses `<` and `>` notation for extreme values:

```{r pvalue}
bcat_fmt_pvalue(c(0.54, 0.045, 0.001, 0.00001))
```

### With "p=" Prefix

Useful in inline reporting:

```{r pvalue-prefix}
bcat_fmt_pvalue(c(0.032, 0.0001), add_p = TRUE)
```

### Controlling Precision

```{r pvalue-accuracy}
bcat_fmt_pvalue(c(0.0456, 0.00012), accuracy = 0.01)
```

## Inline Reporting Example

These formatters are most powerful inside inline R expressions in RMarkdown or
Quarto. For example, suppose you compute some values:

```{r inline-example}
avg_price <- 12345.67
pct_change <- 0.052
my_pval <- 0.003

bcat_fmt_dollar(avg_price)
bcat_fmt_percent(pct_change)
bcat_fmt_pvalue(my_pval, add_p = TRUE)
```

In your RMarkdown document you would reference these with inline R code like
`` `r "\u0060r bcat_fmt_dollar(avg_price)\u0060"` `` to produce formatted
numbers directly in your prose:

> The average price was `r bcat_fmt_dollar(avg_price)` with a
> `r bcat_fmt_percent(pct_change)` year-over-year change.
> The coefficient was significant (`r bcat_fmt_pvalue(my_pval, add_p = TRUE)`).

## Using Formatters as ggplot2 Scale Labels

The `bcat_fmt_*` functions can also serve as label functions for ggplot2 axis
scales:

```{r scale-labels}
library(ggplot2)
set_UC_geoms()

ggplot(economics, aes(date, pce)) +
  geom_line() +
  scale_y_continuous(labels = bcat_fmt_dollar) +
  labs(title = "Personal Consumption Expenditure",
       x = NULL, y = "Billions ($)") +
  theme_UC()
```