inst/doc/discrete-distribution-generators.R

In RandomWalker: Generate Random Walks Compatible with the 'tidyverse'

## ----include = FALSE----------------------------------------------------------
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5,
  fig.alt = "Random walk visualization showing discrete distribution behavior"
)

## ----setup, echo=FALSE, message=FALSE-----------------------------------------
library(RandomWalker)
library(dplyr)
library(ggplot2)

## ----discrete_walk_example, fig.alt="Unbiased discrete random walk showing symmetric up and down movements"----
# Unbiased walk (50/50)
discrete_walk(
  .num_walks = 10,
  .n = 100,
  .upper_probability = 0.5
) |> visualize_walks()

## ----discrete_walk_biased, fig.alt="Biased discrete walk showing upward trend with 60% probability"----
# Biased upward (60% up, 40% down)
discrete_walk(
  .num_walks = 10,
  .n = 100,
  .upper_probability = 0.6
) |> visualize_walks()

## ----discrete_walk_gambler, fig.alt="Gambler's ruin simulation showing multiple walks starting at 100"----
# Gambler's ruin simulation
gambler <- discrete_walk(
  .num_walks = 100,
  .n = 1000,
  .upper_bound = 1,
  .lower_bound = -1,
  .upper_probability = 0.48,  # House edge
  .initial_value = 100
)

gambler |>
  summarize_walks(.value = cum_sum_y, .group_var = walk_number) |>
  summarize(
    prob_ruin = mean(min_val <= 0),
    avg_final = mean(max_val)
  )

## ----binomial_walk_example, fig.alt="Binomial random walk with 10 coin flips per step showing symmetric behavior"----
# Fair coin flips (10 per step)
random_binomial_walk(
  .num_walks = 10,
  .size = 10,
  .prob = 0.5
) |> visualize_walks()

## ----binomial_walk_defects, fig.alt="Quality control simulation using binomial distribution"----
# Quality control simulation
defects <- random_binomial_walk(
  .num_walks = 50,
  .n = 100,
  .size = 100,  # Batch size
  .prob = 0.05  # 5% defect rate
)

defects |>
  summarize_walks(.value = y, .group_var = walk_number) |>
  summarize(
    avg_defects_per_batch = mean(mean_val),
    max_defects = max(max_val)
  )

## ----geometric_walk_example, fig.alt="Geometric random walk with high probability showing short waiting times"----
# High probability (short waits)
random_geometric_walk(
  .num_walks = 10,
  .prob = 0.8
) |> visualize_walks()

## ----geometric_walk_conversion, fig.alt="Customer conversion modeling using geometric distribution"----
# Customer conversion modeling
conversion <- random_geometric_walk(
  .num_walks = 100,
  .n = 50,
  .prob = 0.05  # 5% conversion rate
)

conversion |>
  summarize_walks(.value = y) |>
  pull(mean_val)  # Average trials until conversion

## ----hypergeometric_walk_example, fig.alt="Hypergeometric random walk simulating drawing from an urn"----
# Drawing from an urn
random_hypergeometric_walk(
  .num_walks = 10,
  .m = 50,      # 50 white balls
  .n = 50,  # 50 black balls
  .k = 10       # Draw 10 balls
) |> visualize_walks()

## ----hypergeometric_walk_inspection, fig.alt="Quality inspection using hypergeometric distribution"----
# Quality inspection
inspection <- random_hypergeometric_walk(
  .num_walks = 100,
  .nn = 50,
  .m = 5,        # 5 defective items
  .n = 95,       # 95 good items
  .k = 10        # Sample 10 items
)

inspection |>
  summarize_walks(.value = y) |>
  pull(mean_val)  # Average defects found per sample

## ----multinomial_walk_example, fig.alt="Multinomial random walk simulating dice rolling outcomes"----
# Dice rolling (6 outcomes)
random_multinomial_walk(
  .num_walks = 10,
  .n = 100,  # Roll 100 times
  .size = 1,  # One die per roll
  .prob = rep(1/6, 100)  # Fair die: 6 categories
) |> visualize_walks()

## ----multinomial_walk_market, fig.alt="Market share simulation using multinomial distribution"----
# Market share simulation
market_share <- random_multinomial_walk(
  .num_walks = 50,
  .n = 52,  # Weekly for a year
  .size = 1000,  # Total customers
  .prob = rep(c(0.2, 0.2, 0.35, 0.25), 13)  # Four competitors
)

market_share |> visualize_walks()

## ----negbinomial_walk_example, fig.alt="Negative binomial random walk showing overdispersed count data"----
# Standard negative binomial
random_negbinomial_walk(
  .num_walks = 10,
  .size = 10,
  .prob = 0.5
) |> visualize_walks()

## ----negbinomial_walk_claims, fig.alt="Insurance claims modeling using negative binomial distribution"----
# Overdispersed count data
claims <- random_negbinomial_walk(
  .num_walks = 100,
  .n = 12,  # Monthly
  .size = 5,
  .prob = 0.3
)

claims |>
  summarize_walks(.value = y, .group_var = walk_number) |>
  summarize(
    avg_monthly_claims = mean(mean_val),
    sd_monthly_claims = mean(sd)
  )

## ----poisson_walk_example, fig.alt="Poisson random walk with low rate showing rare events"----
# Low rate (rare events)
random_poisson_walk(
  .num_walks = 10,
  .lambda = 0.5
) |> visualize_walks()

## ----poisson_walk_arrivals, fig.alt="Call center arrivals modeled using Poisson distribution"----
# Call center arrivals
arrivals <- random_poisson_walk(
  .num_walks = 100,
  .n = 24,  # Hourly for a day
  .lambda = 15  # 15 calls per hour average
)

arrivals |>
  summarize_walks(.value = cum_sum_y, .group_var = walk_number) |>
  summarize(
    avg_daily_calls = mean(max_val),
    max_daily_calls = max(max_val),
    min_daily_calls = min(max_val)
  )

## ----wilcox_walk_example, fig.alt="Wilcoxon rank sum random walk for nonparametric testing"----
random_wilcox_walk(
  .num_walks = 10,
  .m = 20,
  .k = 10
) |> visualize_walks()

## ----wilcoxon_sr_walk_example, fig.alt="Wilcoxon signed rank random walk for paired samples testing"----
random_wilcoxon_sr_walk(
  .num_walks = 10,
  .n = 20
) |> visualize_walks()

## ----smirnov_walk_example, fig.alt="Smirnov distribution random walk for goodness-of-fit testing"----
random_smirnov_walk(
  .num_walks = 10,
  .sizes = c(5,10)
) |> visualize_walks()

## ----traffic_example, fig.alt="Website traffic modeling using Poisson distribution"----
# Daily page views (Poisson)
traffic <- random_poisson_walk(
  .num_walks = 100,
  .n = 365,  # Days in year
  .lambda = 1000  # Average daily views
)

# Visualize cumulative page views for a sample of walks
traffic |>
  dplyr::filter(walk_number %in% levels(traffic$walk_number)[1:10]) |>
  visualize_walks(.pluck = "cum_sum_y") +
  ggplot2::labs(
    title = "Cumulative Website Page Views (Poisson Random Walk)",
    x = "Day",
    y = "Cumulative Page Views"
  )

# Compute total annual views (summary statistic)
traffic |>
  summarize_walks(.value = cum_sum_y) |>
  dplyr::pull(max_val) |>
  mean()  # Total annual views

## ----quality_example, fig.alt="Quality control using hypergeometric distribution"----
# Defect sampling (Hypergeometric)
quality <- random_hypergeometric_walk(
  .num_walks = 1000,
  .nn = 50,  # 50 inspections
  .m = 10,   # 10 defective in lot
  .n = 90,  # 90 good in lot
  .k = 5     # Sample 5 items
)

quality |>
  summarize_walks(.value = y, .group_var = walk_number) |>
  dplyr::summarize(
    prob_find_defect = mean(max_val > 0)
  )

## ----customer_service_example, fig.alt="Customer service call resolution using geometric distribution"----
# Calls until resolution (Geometric)
resolution <- random_geometric_walk(
  .num_walks = 500,
  .n = 100,
  .prob = 0.15  # 15% resolution rate per call
)

resolution |>
  summarize_walks(.value = y) |>
  pull(mean_val)  # Average calls until resolution

## ----validation_example, fig.alt="Distribution validation showing mean-variance relationship"----
# Check if distribution fits your expectations
walk <- random_poisson_walk(.num_walks = 1000, .n = 100, .lambda = 5)

walk |>
  summarize_walks(.value = y) |>
  summarize(
    empirical_mean = mean_val,
    empirical_var = variance,
    ratio = variance / mean_val  # Should be ≈ 1 for Poisson
  )