# Number Formatting for Inline Reporting

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

    library(Rbearcat)

## Dollar Formatting — `bcat_fmt_dollar()`

    bcat_fmt_dollar(c(1234.5, 67890, 0.99))
    #> [1] "$1,234.50"  "$67,890.00" "$0.99"

### Negative Values

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

    bcat_fmt_dollar(c(-500, 1200))
    #> [1] "-$500"  "$1,200"
    bcat_fmt_dollar(c(-500, 1200), style_negative = "parens")
    #> [1] "($500)" "$1,200"

### Scaling

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

    bcat_fmt_dollar(c(150000, 275000), scale = 1e-3, accuracy = 1, suffix = "K")
    #> [1] "$150K" "$275K"

## Percent Formatting — `bcat_fmt_percent()`

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

    bcat_fmt_percent(c(0.0523, 0.1, 0.9871))
    #> [1] "5.2%"  "10.0%" "98.7%"

### Pre-scaled Values

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

    bcat_fmt_percent(c(5.23, 10, 98.71), scale = 1)
    #> [1] "5.2%"  "10.0%" "98.7%"

### Controlling Precision

    bcat_fmt_percent(c(0.05234, 0.10011), accuracy = 0.01)
    #> [1] "5.23%"  "10.01%"

## Comma Formatting — `bcat_fmt_comma()`

    bcat_fmt_comma(c(1000, 50000, 1234567))
    #> [1] "1,000"     "50,000"    "1,234,567"

### With Suffix

    bcat_fmt_comma(c(5000, 10000, 80000), scale = 1e-3, accuracy = 1, suffix = "K")
    #> [1] "5K"  "10K" "80K"

## Scientific Notation — `bcat_fmt_scientific()`

    bcat_fmt_scientific(c(0.00012, 3456789, 1.5e10))
    #> [1] "1.20e-04" "3.46e+06" "1.50e+10"

### Controlling Digits

    bcat_fmt_scientific(c(123456, 789012), digits = 2)
    #> [1] "1.2e+05" "7.9e+05"

## 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”).

    bcat_fmt_date(Sys.Date())
    #> [1] "March 21, 2026"
    bcat_fmt_date(c("2024-01-15", "2025-06-30"))
    #> [1] "January 15, 2024" "June 30, 2025"

### Custom Format Strings

Use standard `strptime` codes:

    bcat_fmt_date("2025-12-25", format = "%d %b %Y")
    #> [1] "25 Dec 2025"
    bcat_fmt_date("2025-12-25", format = "%m/%d/%Y")
    #> [1] "12/25/2025"

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

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

    bcat_fmt_pvalue(c(0.54, 0.045, 0.001, 0.00001))
    #> [1] "0.540"  "0.045"  "0.001"  "<0.001"

### With “p=” Prefix

Useful in inline reporting:

    bcat_fmt_pvalue(c(0.032, 0.0001), add_p = TRUE)
    #> [1] "p=0.032" "p<0.001"

### Controlling Precision

    bcat_fmt_pvalue(c(0.0456, 0.00012), accuracy = 0.01)
    #> [1] "0.05"  "<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:

    avg_price <- 12345.67
    pct_change <- 0.052
    my_pval <- 0.003

    bcat_fmt_dollar(avg_price)
    #> [1] "$12,345.67"
    bcat_fmt_percent(pct_change)
    #> [1] "5%"
    bcat_fmt_pvalue(my_pval, add_p = TRUE)
    #> [1] "p=0.003"

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

> The average price was $12,345.67 with a 5% year-over-year change. The coefficient was significant (p=0.003).

## Using Formatters as ggplot2 Scale Labels

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

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