---
title: "Function reference"
---

All functions and classes exported by awh.

## Functions

| Function | Description |
|----------|-------------|
| [`count_plus()`](#count_plus) | Augmented count with proportion and cumulative proportion |
| [`validate_colnames()`](#validate_colnames) | Validate Data Frame Column Names |
| [`validate_input_characters()`](#validate_input_characters) | Validate Character Inputs Against Allowed Values |

***

## Function Details

### `count_plus()` {#count_plus}

Augmented count with proportion and cumulative proportion

#### Usage

```r
count_plus(.data, ..., .wt, .sort = 1, na.rm = TRUE)
```

#### Arguments

| Argument | Description |
|----------|-------------|
| `.data` | A data frame, tibble, or lazy table (tbl_lazy). |
| `...` | Columns to group by (passed to dplyr::count()). |
| `.wt` | Column to use for weighted counting (passed to dplyr::count(wt = )). |
| `.sort` | Sorting option: 1 for descending (default), -1 for ascending, 0 for no sorting. |
| `na.rm` | Logical. Should NA values be removed when computing sums? Default is TRUE. |

#### Value

A tibble or lazy table with columns:
row_idRow number based on sort order
...Grouping columns
nCount (or weighted count)
prop_nProportion of total
cumsum_prop_nCumulative proportion

#### Description

Extends dplyr::count() by adding proportion and cumulative proportion columns,
with sorting options. Works seamlessly with both tibbles and lazy tables (dbplyr).

#### Examples

```r
# With a tibble
ggplot2::diamonds |> count_plus(color, cut)

# With weighted counts
ggplot2::diamonds |> count_plus(color, cut, .wt = price)

# Ascending order
ggplot2::diamonds |> count_plus(color, .sort = -1)
```

***

### `validate_colnames()` {#validate_colnames}

Validate Data Frame Column Names

#### Usage

```r
validate_colnames(.data, column_names)
```

#### Arguments

| Argument | Description |
|----------|-------------|
| `.data` | A data frame or tibble to check. |
| `column_names` | Character vector. The names of the columns that must be present in .data. |

#### Value

Returns TRUE invisibly if all columns are found; otherwise,
throws an error via cli::cli_abort.

#### Description

Checks if a specific set of required column names exists within a data frame or tibble.
If any columns are missing, the function execution is halted with a descriptive error.

#### Details

This function is used internally to ensure that data passed into transformation
functions contains the necessary schema to prevent downstream code failures.

#### Examples

```r
df <- data.frame(time = Sys.time(), temp = 72)
validate_colnames(df, c("time", "temp")) # Returns TRUE
validate_colnames(df, c("time", "humidity")) # Throws error
```

***

### `validate_input_characters()` {#validate_input_characters}

Validate Character Inputs Against Allowed Values

#### Usage

```r
validate_input_characters(input, valid_input, multiple = FALSE)
```

#### Arguments

| Argument | Description |
|----------|-------------|
| `input` | Character. The user-provided input to validate. |
| `valid_input` | Character vector. The set of allowed values for the input. |
| `multiple` | Logical. If FALSE (default), the function will throw an error if length(input) > 1. Set to TRUE if the function should allow vectors of inputs. |

#### Value

Returns NULL invisibly if validation passes; otherwise,
throws an error via cli::cli_abort.

#### Description

A robust input checker that ensures a character string matches a predefined
set of valid options. It can also enforce whether the input must be a single
string (scalar) or can be a vector.

#### Details

This is a utility function used throughout packages to validate arguments.
It utilizes the cli package to provide clean, user-friendly error messages.

#### Examples

```r
# Standard usage for a single argument
validate_input_characters("fcst", c("act", "fcst"))

# Throws error because "live" is not in the valid set
validate_input_characters("live", c("act", "fcst"))
```

***