Package 'decisionpaths'

Run a Decision Path Audit

Description

Produces an integrated audit summary including path descriptors, the Decision Reliability Index (DRI), Shannon entropy, and optional subgroup equity diagnostics. This is the flagship function of the decisionpaths package and implements the five-step decision infrastructure audit described in Hait (2025).

Usage

dp_audit(x, group = NULL)

Arguments

x	A decision_path object from dp_build.
group	Optional character string naming a group variable for stratified DRI and equity diagnostics. The variable must exist in the original data passed to dp_build. If the variable is not found in the path data, a warning is issued and equity diagnostics are skipped.

Value

An object of class dp_audit, a named list with components:

descriptors

Output of dp_describe.

dri

Output of dp_dri.

entropy

Output of dp_entropy.

equity

Output of dp_equity, or NULL if no group variable is supplied or found.

group

The group variable name used (or NULL).

References

Hait, S. (2025). Artificial intelligence as decision infrastructure: Rethinking institutional decision processes. Preprint.

Examples

dat <- data.frame(
  id       = c(1, 1, 1, 2, 2, 2),
  time     = c(1, 2, 3, 1, 2, 3),
  decision = c(0, 1, 1, 1, 1, 0)
)
dp  <- dp_build(dat, id, time, decision)
aud <- dp_audit(dp)
print(aud)

---

Build a Decision-Path Object from Panel Data

Description

Converts a longitudinal (panel) data frame into a decision_path object, the core data structure used by all other functions in the package. Supports unbalanced panels and optional outcome and group variables.

Usage

dp_build(
  data,
  id,
  time,
  decision,
  outcome = NULL,
  group = NULL,
  decision_labels = c("0", "1")
)

Arguments

data	A data frame in long format (one row per unit-wave).
id	Unquoted name of the unit identifier column.
time	Unquoted name of the time/wave column (numeric or integer).
decision	Unquoted name of the binary decision column (0/1).
outcome	Optional. Unquoted name of the outcome column.
group	Optional. Unquoted name of a grouping column for equity analysis.
decision_labels	Character vector of length 2 labelling decision values 0 and 1. Default c("0", "1").

Value

An object of class decision_path, which is a list containing:

paths

A tibble with one row per unit-wave (cleaned and sorted).

path_strings

A named character vector of decision sequences per unit.

ids

Unique unit identifiers.

times

Sorted unique time points.

n_units

Number of units.

n_waves

Maximum number of observed waves.

balanced

Logical: TRUE if all units have the same number of waves.

has_outcome

Logical: TRUE if outcome was supplied.

has_group

Logical: TRUE if group was supplied.

id_var

Character name of the id column.

time_var

Character name of the time column.

decision_var

Character name of the decision column.

outcome_var

Character or NULL name of the outcome column.

group_var

Character or NULL name of the group column.

decision_labels

Character vector of length 2.

Examples

dat <- data.frame(
  id       = c(1, 1, 2, 2),
  time     = c(1, 2, 1, 2),
  decision = c(0, 1, 1, 0)
)
dp <- dp_build(dat, id, time, decision)
print(dp)

---

Describe Decision Paths

Description

Computes per-unit path descriptors from a decision_path object, including dosage, switching rate, onset wave, duration, and longest run. Returns a flat tibble — one row per unit — so that all descriptors are directly accessible as columns (e.g. desc$dosage).

Usage

dp_describe(x, by = NULL)

Arguments

x	A decision_path object from dp_build.
by	Optional character string naming a group variable for stratified summaries. Defaults to x$group_var if set in dp_build.

Value

A tibble of class dp_describe with one row per unit and columns:

id

Unit identifier (column name matches original data).

n_periods

Number of observed waves for this unit.

treatment_count

Number of waves with decision = 1.

dosage

Proportion of waves with decision = 1.

switching_rate

Proportion of consecutive waves where decision changed.

onset

First wave where decision = 1 (NA if never treated).

duration

Total number of waves with decision = 1 (same as treatment_count).

longest_run

Length of longest uninterrupted run of decision = 1.

path

Decision sequence as a string e.g. "0-1-1-0".

group

Group value (NA if no group variable supplied).

Examples

dat <- data.frame(
  id       = c(1, 1, 2, 2),
  time     = c(1, 2, 1, 2),
  decision = c(0, 1, 1, 0)
)
dp   <- dp_build(dat, id, time, decision)
desc <- dp_describe(dp)
desc$dosage
desc$path

---

Compute the Decision Reliability Index (DRI)

Description

Computes the Decision Reliability Index (DRI), defined as one minus the mean switching rate across units. A DRI of 1 indicates perfectly consistent decisions; 0 indicates maximum instability.

Usage

dp_dri(x, by = NULL)

Arguments

x	A decision_path object from dp_build.
by	Optional character string naming a group variable for stratified output. Defaults to x$group_var.

Value

A named list of class dp_dri with components:

group

Group variable name used (NA if none).

mean_switching_rate

Mean switching rate across units.

DRI

Decision Reliability Index = 1 - mean_switching_rate.

unit_dri

Per-unit tibble with switching_rate column.

by_group

By-group summary tibble (NULL if no group).

group_var

Group variable name.

References

Cronbach, L. J. (1951). Coefficient alpha and the internal structure of tests. Psychometrika, 16(3), 297–334.

Nunnally, J. C. (1978). Psychometric theory (2nd ed.). McGraw-Hill.

Examples

dat <- data.frame(
  id       = c(1, 1, 1, 2, 2, 2),
  time     = c(1, 2, 3, 1, 2, 3),
  decision = c(0, 1, 1, 1, 1, 0)
)
dp  <- dp_build(dat, id, time, decision)
dri <- dp_dri(dp)
print(dri)

---

Compute Decision Path Entropy

Description

Computes Shannon entropy (H) of the decision-path distribution, grounded in information theory (Shannon, 1948). Entropy is measured in bits.

Usage

dp_entropy(x, by = NULL, mutual_info = FALSE)

Arguments

x	A decision_path object from dp_build.
by	Optional character string naming a group variable for stratified entropy. Defaults to x$group_var.
mutual_info	Logical. Compute mutual information between path and group? Default FALSE.

Value

An object of class dp_entropy, a named list with:

entropy

Shannon entropy H in bits.

normalized_entropy

H divided by log2(number of unique paths).

path_frequencies

Tibble of path strings, counts, and proportions.

n_unique_paths

Number of unique decision paths observed.

by_group

By-group entropy tibble (NULL if no group variable).

mutual_info

Mutual information in bits (NULL if not requested).

group_var

Group variable name used.

References

Shannon, C. E. (1948). A mathematical theory of communication. Bell System Technical Journal, 27(3), 379–423.

Examples

dat <- data.frame(
  id       = c(1, 1, 2, 2),
  time     = c(1, 2, 1, 2),
  decision = c(0, 1, 1, 0)
)
dp  <- dp_build(dat, id, time, decision)
ent <- dp_entropy(dp)
print(ent)

---

Compare path descriptors across groups

Description

Produces simple subgroup summaries for key decision-path descriptors.

Usage

dp_equity(x, group)

Arguments

x	A decision_path object
group	Grouping variable name as a character string

Value

A tibble of grouped summaries

---

Plot a decision_path object

Description

Produces a heatmap or spaghetti plot of sampled decision paths across units and time periods.

Usage

## S3 method for class 'decision_path'
plot(x, type = "heatmap", sample_n = 50L, ...)

Arguments

x	A decision_path object from dp_build.
type	Character. "heatmap" (default) or "spaghetti".
sample_n	Integer. Maximum number of units to display. Default 50.
...	Ignored.

Value

A ggplot2 object.

---

Plot a dp_audit object

Description

Produces a multi-panel summary figure combining DRI distribution, prevalence over time, dosage distribution, and equity SMDs. Requires patchwork for the combined layout; falls back to DRI panel alone.

Usage

## S3 method for class 'dp_audit'
plot(x, ...)

Arguments

x	A dp_audit object from dp_audit.
...	Ignored.

Value

A ggplot2 or patchwork object.

---

Plot a dp_describe object

Description

Produces density or histogram plots of path descriptor distributions, optionally stratified by group.

Usage

## S3 method for class 'dp_describe'
plot(x, metrics = c("dosage", "switching_rate", "onset"), ...)

Arguments

x	A dp_describe object from dp_describe.
metrics	Character vector of metrics to plot. Defaults to c("dosage", "switching_rate", "onset").
...	Ignored.

Value

A ggplot2 object.

---

Plot a dp_dri object

Description

Produces a histogram or density plot of per-unit switching rates with the overall DRI marked.

Usage

## S3 method for class 'dp_dri'
plot(x, ...)

Arguments

x	A dp_dri object from dp_dri.
...	Ignored.

Value

A ggplot2 object.

---

Plot a dp_entropy object

Description

Produces a bar chart of the most frequent decision paths.

Usage

## S3 method for class 'dp_entropy'
plot(x, top = 10L, ...)

Arguments

x	A dp_entropy object from dp_entropy.
top	Integer. Number of top paths to display. Default 10.
...	Ignored.

Value

A ggplot2 object.

---

Plot a dp_equity object

Description

Produces a dot plot of standardized mean differences (SMDs) across path descriptor metrics and group comparisons.

Usage

## S3 method for class 'dp_equity'
plot(x, ...)

Arguments

x	A dp_equity object from dp_equity.
...	Ignored.

Value

A ggplot2 object.

---