---
title: "Frequently Asked Questions (FAQ)"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Frequently Asked Questions (FAQ)}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5,
  fig.alt = "Random walk visualization examples"
)
```

```{r setup, echo=FALSE, message=FALSE}
library(RandomWalker)
library(dplyr)
library(ggplot2)
```

Quick answers to common questions about RandomWalker.

## General Questions

### What is RandomWalker?

RandomWalker is an R package for generating, visualizing, and analyzing random walks. It supports 27+ probability distributions, multi-dimensional walks (1D, 2D, 3D), and provides tidyverse-compatible functions for data manipulation and analysis.

### Who should use RandomWalker?

RandomWalker is useful for:
- **Researchers**: Modeling stochastic processes, simulating experiments
- **Students**: Learning probability and statistics
- **Data Scientists**: Generating synthetic data, testing algorithms
- **Financial Analysts**: Modeling asset prices, risk analysis
- **Physicists/Biologists**: Simulating particle movement, organism behavior
- **Educators**: Teaching probability concepts

### Is RandomWalker free to use?

Yes! RandomWalker is open-source software licensed under the MIT License. You can use it freely for academic, commercial, or personal projects.

## Installation Questions

### How do I install RandomWalker?

```{r install_example, eval=FALSE}
# From CRAN (stable)
install.packages("RandomWalker")

# From GitHub (development)
devtools::install_github("spsanderson/RandomWalker")
```

### What R version do I need?

RandomWalker requires R version 4.1.0 or higher.

### Why am I getting dependency errors?

Try installing dependencies manually:
```{r dependencies_example, eval=FALSE}
install.packages(c("dplyr", "tidyr", "purrr", "rlang", "patchwork", "NNS", "ggiraph"))
```

## Usage Questions

### How do I generate a simple random walk?

```{r simple_walk_example}
library(RandomWalker)
rw30() |> head(10)  # Generates 30 walks with 100 steps each
```

### How do I visualize my random walks?

```{r visualize_example, fig.alt="Visualization of random walks showing multiple panels"}
library(RandomWalker)
rw30() |> visualize_walks()
```

### How do I create a custom random walk?

Use one of the generator functions:
```{r custom_walk_example, fig.alt="Custom normal random walk with specified parameters"}
random_normal_walk(
  .num_walks = 10,
  .n = 100,
  .mu = 0,
  .sd = 1,
  .initial_value = 0
) |> visualize_walks()
```

### Can I set a seed for reproducibility?

Yes:
```{r seed_example}
set.seed(123)
walks <- rw30()

# Same seed produces same result
set.seed(123)
walks2 <- rw30()
identical(walks, walks2)  # TRUE
```

## Distribution Questions

### Which distribution should I use?

It depends on your use case:

- **General purpose**: `random_normal_walk()`
- **Stock prices**: `geometric_brownian_motion()`
- **Particle diffusion**: `brownian_motion()`
- **Binary outcomes**: `discrete_walk()`
- **Heavy tails**: `random_cauchy_walk()` or `random_t_walk()`
- **Count data**: `random_poisson_walk()`

### What's the difference between `random_normal_walk()` and `brownian_motion()`?

Both use normal distributions, but:
- `random_normal_walk()`: Discrete steps, cumulative sum
- `brownian_motion()`: Continuous-time stochastic process, includes drift (μ) and volatility (σ) parameters

For most purposes, they're similar. Use `brownian_motion()` for financial modeling.

### What's the difference between `brownian_motion()` and `geometric_brownian_motion()`?

- **Brownian Motion**: Can go negative, additive process
  ```
  X(t) = X(0) + μt + σW(t)
  ```

- **Geometric Brownian Motion**: Always positive, multiplicative process
  ```
  X(t) = X(0) exp((μ - σ²/2)t + σW(t))
  ```

Use Geometric Brownian Motion for modeling stock prices (can't go negative).

### Can I use custom distributions?

Yes! Use `custom_walk()`:
```{r custom_distribution_example, eval=FALSE}
# Custom displacement function
my_displacement <- function() {
  # Your custom logic here
  return(some_value)
}

custom_walk(
  .num_walks = 10,
  .n = 100,
  .custom_fns = my_displacement
)
```

## Multi-Dimensional Questions

### How do I create a 2D random walk?

Add `.dimensions = 2`:
```{r twod_example}
random_normal_walk(.num_walks = 10, .n = 100, .dimensions = 2)
```

### How do I visualize 2D walks?

```{r visualize_2d, fig.alt="2D random walk visualization with x-y coordinates"}
library(ggplot2)

walk_2d <- random_normal_walk(.num_walks = 10, .n = 100, .dimensions = 2)

ggplot(walk_2d, aes(x = cum_sum_x, y = cum_sum_y, color = walk_number)) +
  geom_path() +
  coord_equal() +
  theme_minimal()
```

### What's the difference between x, y in 1D vs 2D walks?

- **1D**: `y` is the random value, `x` is renamed to `step_number`
- **2D**: `x` and `y` are the two spatial dimensions
- **3D**: `x`, `y`, and `z` are the three spatial dimensions

## Visualization Questions

### How do I make interactive plots?

Add `.interactive = TRUE`:
```{r interactive_example, eval=FALSE}
rw30() |> visualize_walks(.interactive = TRUE)
```

### How do I show only specific panels?

Use `.pluck`:
```{r pluck_example, fig.alt="Single panel visualization showing cumulative sum"}
# Single panel
random_normal_walk() |> visualize_walks(.pluck = "cum_sum_y")
```

```{r pluck_multiple, fig.alt="Multiple panel visualization showing y, cumulative sum, and cumulative mean"}
# Multiple panels
random_normal_walk() |> visualize_walks(.pluck = c("y", "cum_sum_y", "cum_mean_y"))
```

### How do I adjust transparency?

Use `.alpha`:
```{r alpha_example, eval=FALSE}
rw30() |> visualize_walks(.alpha = 0.3)  # More transparent
rw30() |> visualize_walks(.alpha = 0.9)  # More opaque
```

### How do I export plots?

```{r export_example, eval=FALSE}
library(ggplot2)

p <- rw30() |> visualize_walks()
ggsave("my_plot.png", p, width = 12, height = 8, dpi = 300)
```

### Can I customize colors?

Yes, using ggplot2:
```{r colors_example, fig.alt="Random walk with custom color palette"}
p <- random_normal_walk(.num_walks = 5) |>
  visualize_walks(.pluck = "y")

p + scale_color_viridis_d()
```

## Statistical Analysis Questions

### How do I get summary statistics?

```{r summary_example}
walks <- rw30()

# Overall summary
walks |> summarize_walks(.value = y)
```

```{r summary_by_walk}
# By walk
walks |> summarize_walks(.value = y, .group_var = walk_number) |> head()
```

### What statistics are included?

- Mean, median, range
- Variance, standard deviation
- Quantiles (2.5% and 97.5% by default)
- Min, max
- Harmonic mean, geometric mean
- Skewness, kurtosis

### How do I subset walks by extremes?

```{r subset_example, fig.alt="Maximum and minimum walks visualization"}
walks <- rw30()

# Get walk with maximum final value
max_walk <- walks |> subset_walks(.value = "y", .type = "max")

# Get walk with minimum final value
min_walk <- walks |> subset_walks(.value = "y", .type = "min")

# Visualize both walks together
combined <- dplyr::bind_rows(
  dplyr::mutate(max_walk, type = "Maximum"),
  dplyr::mutate(min_walk, type = "Minimum")
)
visualize_walks(combined, .pluck = "y") +
  ggplot2::facet_wrap(~type)
```

## Performance Questions

### How many walks can I generate?

This depends on your system, but RandomWalker can handle:
- **Light**: 1,000 walks × 1,000 steps each
- **Moderate**: 10,000 walks × 10,000 steps each
- **Heavy**: 100,000+ walks with careful memory management

### My visualization is slow. How do I speed it up?

1. **Reduce transparency**: `.alpha = 0.2`
2. **Sample walks**: Show fewer walks
3. **Downsample steps**: Keep every nth step
4. **Use static plots**: Disable `.interactive`

```{r speed_example, eval=FALSE}
# Sample walks
walks_large |>
  filter(walk_number %in% sample(levels(walk_number), 50)) |>
  visualize_walks(.alpha = 0.2)

# Downsample steps
walks_large |>
  filter(step_number %% 10 == 0) |>
  visualize_walks()
```

### Can I parallelize generation?

The functions are vectorized, but you can use parallel processing:
```{r parallel_example, eval=FALSE}
library(future)
library(furrr)

plan(multisession, workers = 4)

walks_list <- future_map(1:10, ~random_normal_walk(.num_walks = 100), .options = furrr_options(seed = 123))
```

## Data Structure Questions

### What format does RandomWalker return?

A tibble (tidyverse-compatible data frame) with columns:
- `walk_number` (factor)
- `step_number` (integer)
- Value columns (`y` for 1D, `x`/`y` for 2D, `x`/`y`/`z` for 3D)
- Cumulative function columns

### How do I access attributes?

```{r attributes_example}
walks <- rw30()
atb <- get_attributes(walks)
names(atb)
```

Common attributes: `fns`, `num_walks`, `n`, `initial_value`, distribution parameters.

### Can I convert to other formats?

Yes:
```{r convert_example, eval=FALSE}
# To base R data.frame
as.data.frame(walks)

# To matrix (values only)
walks |> select(y) |> as.matrix()

# To time series
ts(walks$y, frequency = 1)

# To wide format
walks |> tidyr::pivot_wider(names_from = walk_number, values_from = y)
```

## Error Messages

### "The value to summarize must be provided"

You forgot to specify `.value` in `summarize_walks()`:
```{r error_example1, eval=FALSE}
# Wrong
walks |> summarize_walks()

# Correct
walks |> summarize_walks(.value = y)
```

### "object 'y' not found"

You might be using a 2D/3D walk where `y` refers to a dimension. Use `cum_sum_y` or specify dimensions:
```{r error_example2, eval=FALSE}
walk_2d <- random_normal_walk(.dimensions = 2)

# Wrong
walk_2d |> summarize_walks(.value = y)

# Correct
walk_2d |> summarize_walks(.value = cum_sum_y)
```

## Integration Questions

### Does RandomWalker work with dplyr?

Yes! RandomWalker is designed for tidyverse:
```{r dplyr_example}
library(dplyr)

random_normal_walk(.num_walks = 10) |>
  filter(step_number > 50) |>
  mutate(positive = cum_sum_y > 0) |>
  group_by(walk_number) |>
  summarize(prop_positive = mean(positive))
```

### Can I use it in Shiny apps?

Yes:
```{r shiny_example, eval=FALSE}
library(shiny)
library(RandomWalker)

ui <- fluidPage(
  numericInput("num_walks", "Number of Walks:", 10),
  plotOutput("walks_plot")
)

server <- function(input, output) {
  output$walks_plot <- renderPlot({
    random_normal_walk(.num_walks = input$num_walks) |>
      visualize_walks(.pluck = "cum_sum_y")
  })
}

shinyApp(ui, server)
```

### Can I use it with ggplot2?

Yes, `visualize_walks()` returns ggplot2 objects:
```{r ggplot2_example, fig.alt="Custom ggplot2 theme applied to random walk"}
library(ggplot2)

p <- rw30() |> visualize_walks(.pluck = "y")

# Customize further
p +
  labs(title = "My Custom Title") +
  theme_bw()
```

## Application Questions

### How do I model stock prices?

Use Geometric Brownian Motion:
```{r stock_example, fig.alt="Stock price simulation using geometric Brownian motion"}
stock_prices <- geometric_brownian_motion(
  .num_walks = 100,
  .n = 252,  # Trading days
  .mu = 0.08,  # 8% expected return
  .sigma = 0.25,  # 25% volatility
  .initial_value = 100
)
visualize_walks(stock_prices)
```

### How do I simulate particle diffusion?

Use Brownian Motion in 2D or 3D:
```{r particle_example, eval=FALSE}
particles <- brownian_motion(
  .num_walks = 50,
  .n = 1000,
  .dimensions = 3
)
```

### How do I test an algorithm?

Generate synthetic data:
```{r algorithm_example, eval=FALSE}
# Generate test walks
test_data <- discrete_walk(
  .num_walks = 1000,
  .n = 100,
  .upper_probability = 0.5
)

# Run your algorithm
result <- my_algorithm(test_data)
```

## Getting Help

### Where can I find more examples?

- **Getting Started Vignette** - Basic examples
- **Package Documentation** - Function reference
- **GitHub Repository** - Real-world applications

### Where do I report bugs?

[GitHub Issues](https://github.com/spsanderson/RandomWalker/issues)

### Where can I ask questions?

- [GitHub Discussions](https://github.com/spsanderson/RandomWalker/discussions)
- Stack Overflow (use `randomwalker` tag)
- Email: spsanderson@gmail.com

### How do I cite RandomWalker?

```{r citation_example, eval=FALSE}
citation("RandomWalker")
```

### Is there a community?

Yes! Join us on:
- [GitHub Discussions](https://github.com/spsanderson/RandomWalker/discussions)
- Follow [@steveondata](https://t.me/steveondata) on Telegram

## Contributing

### Can I contribute?

Yes! We welcome contributions:
- Bug reports
- Feature requests
- Code contributions
- Documentation improvements
- Examples and tutorials

### How do I suggest a new feature?

Open an issue on [GitHub Issues](https://github.com/spsanderson/RandomWalker/issues) with:
- Clear description of the feature
- Use cases
- Example code (if applicable)

## Related Questions

### What's the difference between RandomWalker and other R packages?

RandomWalker is unique in:
- Tidyverse compatibility
- 27+ distributions in one package
- Multi-dimensional support (1D/2D/3D)
- Rich visualization capabilities
- Comprehensive statistical analysis tools
- Consistent API across all functions

### Can RandomWalker handle big data?

Yes, but:
- Use efficient data structures (tibbles)
- Sample or downsample for visualization
- Consider parallel processing for generation
- Use appropriate hardware

### Is RandomWalker actively maintained?

Yes! The package is actively developed with:
- Regular updates
- Bug fixes
- New features
- Community support

Check [NEWS.md](https://github.com/spsanderson/RandomWalker/blob/master/NEWS.md) for latest updates.

---

**Didn't find your answer?** Ask on [GitHub Discussions](https://github.com/spsanderson/RandomWalker/discussions)!