### Complete texteffect Workflow Example

Source: https://context7.com/christianfong/texteffect/llms.txt

Demonstrates the full pipeline for analyzing text data using the texteffect package, from data loading and preparation to model fitting, parameter search, ranking, and causal effect estimation.

```r
library(texteffect)
library(ggplot2)

# ============================================
# Step 1: Load and Prepare Data
# ============================================
data(BioSample)
Y <- BioSample[,1]         # Outcome variable
X <- BioSample[,-1]        # Document-term matrix (250 docs x 50 words)

# Create reproducible train/test split
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

# ============================================
# Step 2: Search Parameter Space
# ============================================
# Run grid search over hyperparameters using training data only
sibp.search <- sibp_param_search(
  X = X, Y = Y,
  K = 2,                           # Discover 2 treatments
  alphas = c(2, 4, 6),             # Try different treatment prevalences
  sigmasq.ns = c(0.6, 0.8, 1.0),   # Try different noise levels
  iters = 3,                       # 3 random starts per configuration
  train.ind = train.ind,
  seed = 42
)

# ============================================
# Step 3: Rank and Select Best Configuration
# ============================================
# Automatically rank configurations by exclusivity metric
rankings <- sibp_rank_runs(sibp.search, X, num.words = 10)
print(head(rankings))

# ============================================
# Step 4: Qualitatively Examine Top Candidates
# ============================================
# Inspect top words for best-ranked configurations
best_alpha <- as.character(rankings$alpha[1])
best_sigmasq <- as.character(rankings$sigmasq.n[1])
best_iter <- rankings$iter[1]

sibp_top_words(
  sibp.search[[best_alpha]][[best_sigmasq]][[best_iter]],
  colnames(X),
  num.words = 10,
  verbose = TRUE
)

# ============================================
# Step 5: Select Final Model
# ============================================
# Choose configuration with most substantively interesting treatments
sibp.fit <- sibp.search[[best_alpha]][[best_sigmasq]][[best_iter]]

# ============================================
# Step 6: Estimate Causal Effects

```

--------------------------------

### sibp_rank_runs - Rank Parameter Configurations by Exclusivity

Source: https://context7.com/christianfong/texteffect/llms.txt

Calculates an exclusivity metric for each parameter configuration from a search and ranks them from most to least promising. The exclusivity metric measures how well the top words in a treatment distinguish documents with that treatment from documents without it.

```APIDOC
## sibp_rank_runs - Rank Parameter Configurations by Exclusivity

### Description
Calculates an exclusivity metric for each parameter configuration from a search and ranks them from most to least promising. The exclusivity metric measures how well the top words in a treatment distinguish documents with that treatment from documents without it.

### Method
`sibp_rank_runs()`

### Parameters
#### Arguments
- **sibp.search.results** (list) - The output from `sibp_param_search()` containing fitted models for various parameter configurations.
- **X** (Document-term matrix) - The input document-term matrix used in the search.
- **top.words** (integer) - The number of top words to consider for calculating exclusivity.

### Request Example
```r
# Assuming sibp.search is the output from sibp_param_search()
# and X is the document-term matrix
ranked.runs <- sibp_rank_runs(
  sibp.search.results = sibp.search,
  X = X,
  top.words = 10
)
```

### Response
#### Success Response
The function returns a data frame where each row represents a parameter configuration, ranked by its exclusivity metric. Columns typically include the parameter values (e.g., alpha, sigmasq.n) and the calculated exclusivity score.

#### Response Example
```r
# View the ranked results
print(ranked.runs)
```
```

--------------------------------

### sibp_rank_runs - Rank sIBP Model Runs

Source: https://context7.com/christianfong/texteffect/llms.txt

Ranks all parameter configurations from a `sibp_param_search` result based on the exclusivity metric calculated using a specified number of top words.

```APIDOC
## sibp_rank_runs - Rank sIBP Model Runs

### Description
Ranks all parameter configurations from a `sibp_param_search` result based on the exclusivity metric calculated using a specified number of top words.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
#### Function Arguments
- **sibp.search** (list) - Output from `sibp_param_search`.
- **X** (matrix) - Document-term matrix.
- **num.words** (integer) - Number of top words to use for calculating exclusivity.

### Request Example
```r
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

sibp.search <- sibp_param_search(
  X = X, Y = Y, K = 2,
  alphas = c(2, 4),
  sigmasq.ns = c(0.8, 1),
  iters = 1,
  train.ind = train.ind
)

rankings <- sibp_rank_runs(
  sibp.search = sibp.search,
  X = X,
  num.words = 10
)
print(rankings)
```

### Response
#### Success Response
- **rankings** (data.frame) - A data frame with columns: alpha, sigmasq.n, iter, exclu. 'exclu' is the exclusivity score.

#### Response Example
```
#   alpha sigmasq.n iter      exclu
# 1     4       0.8    1  0.1234567
# 2     2       0.8    1  0.0987654
```
```

--------------------------------

### sibp_param_search - Parameter Search for sIBP Model

Source: https://context7.com/christianfong/texteffect/llms.txt

Performs a grid search over specified parameter values (alpha and sigmasq.n) to find optimal configurations for the sIBP model. It returns a data frame ranking these configurations by an exclusivity metric.

```APIDOC
## sibp_param_search - Parameter Search for sIBP Model

### Description
Performs a grid search over specified parameter values (alpha and sigmasq.n) to find optimal configurations for the sIBP model. It returns a data frame ranking these configurations by an exclusivity metric.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
#### Function Arguments
- **X** (matrix) - Document-term matrix.
- **Y** (vector) - Outcome variable.
- **K** (integer) - Number of treatments.
- **alphas** (numeric vector) - Values of alpha parameter to search.
- **sigmasq.ns** (numeric vector) - Values of sigmasq.n parameter to search.
- **iters** (integer) - Number of iterations for each parameter combination.
- **train.ind** (integer vector) - Indices of training data.

### Request Example
```r
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

sibp.search <- sibp_param_search(
  X = X, Y = Y, K = 2,
  alphas = c(2, 4),
  sigmasq.ns = c(0.8, 1),
  iters = 1,
  train.ind = train.ind
)
print(sibp.search)
```

### Response
#### Success Response
- **rankings** (data.frame) - A data frame with columns: alpha, sigmasq.n, iter, exclu. 'exclu' is the exclusivity score.

#### Response Example
```
#   alpha sigmasq.n iter      exclu
# 1     4       0.8    1  0.1234567
# 2     2       0.8    1  0.0987654
```
```

--------------------------------

### sibp_param_search - Grid Search Over Hyperparameters

Source: https://context7.com/christianfong/texteffect/llms.txt

Performs a grid search over combinations of alpha and sigmasq.n parameters, fitting multiple sIBP models to help identify the most promising parameter configurations. Since it only uses training data, users can explore many configurations without affecting causal inference validity.

```APIDOC
## sibp_param_search - Grid Search Over Hyperparameters

### Description
Performs a grid search over combinations of alpha and sigmasq.n parameters, fitting multiple sIBP models to help identify the most promising parameter configurations. Since it only uses training data, users can explore many configurations without affecting causal inference validity.

### Method
`sibp_param_search()`

### Parameters
#### Arguments
- **X** (Document-term matrix) - The input document-term matrix.
- **Y** (vector) - The outcome variable.
- **K** (integer) - The number of latent treatments to discover.
- **alphas** (vector of numeric) - Vector of alpha values to try (treatment commonness).
- **sigmasq.ns** (vector of numeric) - Vector of noise variance values to try.
- **iters** (integer) - Number of random starting values per configuration.
- **a** (numeric) - Prior shape parameter for tau.
- **b** (numeric) - Prior rate parameter for tau.
- **sigmasq.A** (numeric) - Variance of treatment effects on words.
- **train.ind** (vector of integers) - Training set indices.
- **G** (matrix, optional) - Optional group membership matrix.
- **seed** (integer) - Seed for reproducibility.

### Request Example
```r
# Load data and prepare training/test split
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

# Search over multiple parameter configurations
sibp.search <- sibp_param_search(
  X = X,
  Y = Y,
  K = 2,                        # Number of treatments
  alphas = c(2, 4),             # Alpha values to search
  sigmasq.ns = c(0.8, 1),       # Noise variance values to search
  iters = 1,                    # Iterations per configuration
  a = 0.1,
  b = 0.1,
  sigmasq.A = 5,
  train.ind = train.ind,
  G = NULL,
  seed = 0                      # For reproducibility
)
```

### Response
#### Success Response
The function returns a list where each element corresponds to a parameter configuration, containing the fitted models. The structure allows access to models by their parameter values and iteration number.
- **alphas** (vector of numeric) - Vector of alpha values searched.
- **sigmasq.ns** (vector of numeric) - Vector of sigmasq.n values searched.
- **iters** (integer) - Number of iterations per configuration.

#### Response Example
```r
# Access results by parameter values:
sibp.search[["4"]][["0.8"]][[1]] # Model with alpha=4, sigmasq.n=0.8, iteration 1
sibp.search$alphas
sibp.search$sigmasq.ns
sibp.search$iters
```
```

--------------------------------

### Rank sibp Model Runs by Exclusivity

Source: https://context7.com/christianfong/texteffect/llms.txt

Ranks parameter configurations from a sibp parameter search based on the exclusivity metric. Uses a specified number of top words for calculation.

```r
rankings <- sibp_rank_runs(
  sibp.search = sibp.search,
  X = X,
  num.words = 10
)

print(rankings)
```

--------------------------------

### Grid Search Over sIBP Hyperparameters

Source: https://context7.com/christianfong/texteffect/llms.txt

Use `sibp_param_search()` to perform a grid search over `alpha` and `sigmasq.n` values. This function fits multiple sIBP models using only the training data, allowing exploration of parameter configurations without compromising causal inference validity. Results are stored in a nested list structure.

```r
# Load data and prepare training/test split
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

# Search over multiple parameter configurations
# alphas: vector of alpha values to try (treatment commonness)
# sigmasq.ns: vector of noise variance values to try
# iters: number of random starting values per configuration
sibp.search <- sibp_param_search(
  X = X,
  Y = Y,
  K = 2,                        # Number of treatments
  alphas = c(2, 4),             # Alpha values to search
  sigmasq.ns = c(0.8, 1),       # Noise variance values to search
  iters = 1,                    # Iterations per configuration
  a = 0.1,
  b = 0.1,
  sigmasq.A = 5,
  train.ind = train.ind,
  G = NULL,
  seed = 0                      # For reproducibility
)

# Access results by parameter values:
# sibp.search[["4"]][["0.8"]][[1]] - Model with alpha=4, sigmasq.n=0.8, iteration 1
# sibp.search$alphas - Vector of alpha values searched
# sibp.search$sigmasq.ns - Vector of sigmasq.n values searched
# sibp.search$iters - Number of iterations per configuration

```

--------------------------------

### sibp - Supervised Indian Buffet Process for Treatment Discovery

Source: https://context7.com/christianfong/texteffect/llms.txt

Fits the supervised Indian Buffet Process model using variational inference to discover latent binary treatments within a text corpus. It takes a document-term matrix (X), outcomes (Y), and key hyperparameters to identify K latent treatments that explain variation in the outcome.

```APIDOC
## sibp - Supervised Indian Buffet Process for Treatment Discovery

### Description
Fits the supervised Indian Buffet Process model using variational inference to discover latent binary treatments within a text corpus. It takes a document-term matrix (X), outcomes (Y), and key hyperparameters to identify K latent treatments that explain variation in the outcome. The function standardizes inputs and iterates until parameter convergence.

### Method
`sibp()`

### Parameters
#### Arguments
- **X** (Document-term matrix) - The input document-term matrix.
- **Y** (vector) - The outcome variable.
- **K** (integer) - The number of latent treatments to discover.
- **alpha** (numeric) - Controls treatment commonness (larger = more common treatments).
- **sigmasq.n** (numeric) - Noise variance parameter (larger = treatments explain more variation).
- **a** (numeric) - Prior shape parameter for tau.
- **b** (numeric) - Prior rate parameter for tau.
- **sigmasq.A** (numeric) - Variance of treatment effects on words.
- **train.ind** (vector of integers) - Training set indices.
- **G** (matrix, optional) - Optional group membership matrix.
- **silent** (boolean) - If FALSE, print convergence progress.

### Request Example
```r
# Load the Wikipedia biography sample dataset
data(BioSample)

# Prepare data: Y is the outcome, X is the document-term matrix
Y <- BioSample[,1]
X <- BioSample[,-1]

# Create training/test split (50% training)
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

# Fit sIBP model to discover 2 latent treatments
sibp.fit <- sibp(
  X = X,                    # Document-term matrix
  Y = Y,                    # Outcome variable
  K = 2,                    # Number of treatments to discover
  alpha = 4,                # Treatment prevalence parameter
  sigmasq.n = 0.8,          # Noise variance parameter
  a = 0.1,                  # Prior shape parameter for tau
  b = 0.1,                  # Prior rate parameter for tau
  sigmasq.A = 5,            # Variance of treatment effects on words
  train.ind = train.ind,    # Training set indices
  G = NULL,                 # Optional group membership matrix
  silent = FALSE            # Print convergence progress
)
```

### Response
#### Success Response
The function returns a list containing model results:
- **nu** (matrix) - Probability each document has each treatment (N x K matrix).
- **phi** (matrix) - Effect of each treatment on each word (K x D matrix).
- **m** (vector) - Treatment effect estimates on outcome (for training set only).
- **train.ind** (vector of integers) - Training set indices.
- **test.ind** (vector of integers) - Test set indices.

#### Response Example
```r
# Access key results:
sibp.fit$nu
sibp.fit$phi
sibp.fit$m
```
```

--------------------------------

### sibp_exclusivity - Calculate Exclusivity for Single Model

Source: https://context7.com/christianfong/texteffect/llms.txt

Calculates the exclusivity metric for a single fitted sIBP model. This metric quantifies how well the top words associated with each treatment appear exclusively in documents assigned that treatment versus documents without it.

```APIDOC
## sibp_exclusivity - Calculate Exclusivity for Single Model

### Description
The `sibp_exclusivity()` function calculates the exclusivity metric for a single fitted sIBP model. This metric quantifies how well the top words associated with each treatment appear exclusively in documents assigned that treatment versus documents without it.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
#### Function Arguments
- **sibp.fit** (list) - A fitted sIBP model object.
- **X** (matrix) - Document-term matrix.
- **num.words** (integer) - Number of top words to evaluate for exclusivity.

### Request Example
```r
# Fit a single sIBP model
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

sibp.fit <- sibp(X, Y, K = 2, alpha = 4, sigmasq.n = 0.8, train.ind = train.ind)

# Calculate exclusivity metric for this model
exclusivity_score <- sibp_exclusivity(
  sibp.fit = sibp.fit,
  X = X,
  num.words = 10           # Top words to evaluate
)

# Returns a single numeric value
print(exclusivity_score)
```

### Response
#### Success Response
- **exclusivity_score** (numeric) - A single numeric value representing the exclusivity score. Higher values indicate more distinct word distributions across treatments.

#### Response Example
```
# [1] 0.1234567
```
```

--------------------------------

### Parameter Search for sibp Model

Source: https://context7.com/christianfong/texteffect/llms.txt

Performs a parameter search for the sibp model to find optimal alpha and sigmasq.n values. Requires training indices for data splitting.

```r
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

sibp.search <- sibp_param_search(
  X = X, Y = Y, K = 2,
  alphas = c(2, 4),
  sigmasq.ns = c(0.8, 1),
  iters = 1,
  train.ind = train.ind
)
```

--------------------------------

### Fit sIBP Model for Treatment Discovery

Source: https://context7.com/christianfong/texteffect/llms.txt

Use `sibp()` to fit the supervised Indian Buffet Process model with variational inference. It requires a document-term matrix (X) and outcome variable (Y), along with hyperparameters like K (number of treatments), alpha (prevalence), and sigmasq.n (noise variance). Input data is standardized, and the function iterates until convergence.

```r
# Load the Wikipedia biography sample dataset
data(BioSample)

# Prepare data: Y is the outcome, X is the document-term matrix
Y <- BioSample[,1]
X <- BioSample[,-1]

# Create training/test split (50% training)
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

# Fit sIBP model to discover 2 latent treatments
# alpha: controls treatment commonness (larger = more common treatments)
# sigmasq.n: variance of word counts given treatments (larger = treatments explain more variation)
sibp.fit <- sibp(
  X = X,                    # Document-term matrix
  Y = Y,                    # Outcome variable
  K = 2,                    # Number of treatments to discover
  alpha = 4,                # Treatment prevalence parameter
  sigmasq.n = 0.8,          # Noise variance parameter
  a = 0.1,                  # Prior shape parameter for tau
  b = 0.1,                  # Prior rate parameter for tau
  sigmasq.A = 5,            # Variance of treatment effects on words
  train.ind = train.ind,    # Training set indices
  G = NULL,                 # Optional group membership matrix
  silent = FALSE            # Print convergence progress
)

# Access key results:
# sibp.fit$nu - Probability each document has each treatment (N x K matrix)
# sibp.fit$phi - Effect of each treatment on each word (K x D matrix)
# sibp.fit$m - Treatment effect estimates on outcome (for training set only)
# sibp.fit$train.ind - Training set indices
# sibp.fit$test.ind - Test set indices

```

--------------------------------

### sibp_top_words - Identify Words Associated with Treatments

Source: https://context7.com/christianfong/texteffect/llms.txt

Identifies and returns the words most strongly associated with each discovered treatment in a fitted sIBP model. This aids in the qualitative interpretation of treatments.

```APIDOC
## sibp_top_words - Identify Words Associated with Treatments

### Description
The `sibp_top_words()` function returns the words most strongly associated with each discovered treatment, enabling qualitative interpretation of what each treatment represents. This is essential for deciding which parameter configuration yields the most substantively interesting treatments.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
#### Function Arguments
- **sibp.fit** (list) - A fitted sIBP model object.
- **words** (character vector) - The vocabulary (e.g., column names of the document-term matrix).
- **num.words** (integer) - The number of top words to return per treatment.
- **verbose** (logical) - If TRUE, prints additional diagnostic information such as treatment frequencies.

### Request Example
```r
# Fit sIBP model
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

sibp.fit <- sibp(X, Y, K = 2, alpha = 4, sigmasq.n = 0.8, train.ind = train.ind)

# Get top 10 words for each treatment
top_words <- sibp_top_words(
  sibp.fit = sibp.fit,
  words = colnames(X),     # Vocabulary (column names of X)
  num.words = 10,          # Number of top words to return per treatment
  verbose = FALSE          # Set TRUE to print treatment frequencies
)

# Result is a matrix: rows are word ranks, columns are treatments
print(top_words)

# Verbose mode shows additional diagnostics
sibp_top_words(sibp.fit, colnames(X), num.words = 10, verbose = TRUE)
```

### Response
#### Success Response
- **top_words** (matrix) - A matrix where rows represent word ranks and columns represent treatments. Each column lists the top words associated with that treatment.

#### Response Example
```
#       [,1]       [,2]
# [1,] "word1"    "word5"
# [2,] "word2"    "word6"
# ...

# Verbose output example:
# [1] "Frequency of treatments: "
# [1] 45.2 38.7
# [1] "Relation between top words and treatments"
# ...
```
```

--------------------------------

### Infer Treatment Assignments for Test Set Documents

Source: https://context7.com/christianfong/texteffect/llms.txt

Applies a learned word-to-treatment mapping to infer treatment assignments for documents in a test set. Typically used internally by sibp_amce but can be used for validation. Set newX = TRUE for entirely new data, standardizing using training set parameters.

```r
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

sibp.fit <- sibp(X, Y, K = 2, alpha = 4, sigmasq.n = 0.8, train.ind = train.ind)

Z_test <- infer_Z(
  sibp.fit = sibp.fit,
  X = X,
  newX = FALSE
)

print(dim(Z_test))
```

```r
new_documents <- X[1:10, ]
Z_new <- infer_Z(sibp.fit, new_documents, newX = TRUE)
```

--------------------------------

### Identify Top Words Associated with Treatments

Source: https://context7.com/christianfong/texteffect/llms.txt

Identifies and returns the words most strongly associated with each discovered treatment in a fitted sIBP model. Essential for qualitative interpretation of treatments. Can optionally print verbose diagnostics.

```r
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

sibp.fit <- sibp(X, Y, K = 2, alpha = 4, sigmasq.n = 0.8, train.ind = train.ind)

top_words <- sibp_top_words(
  sibp.fit = sibp.fit,
  words = colnames(X),
  num.words = 10,
  verbose = FALSE
)

print(top_words)
```

```r
sibp_top_words(sibp.fit, colnames(X), num.words = 10, verbose = TRUE)
```

--------------------------------

### Calculate Exclusivity Score for a Single sibp Model

Source: https://context7.com/christianfong/texteffect/llms.txt

Calculates the exclusivity metric for a fitted sIBP model. Quantifies how well top words associated with each treatment appear exclusively in documents assigned that treatment. Requires the fitted model object, document-term matrix, and number of top words to evaluate.

```r
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

sibp.fit <- sibp(X, Y, K = 2, alpha = 4, sigmasq.n = 0.8, train.ind = train.ind)

exclusivity_score <- sibp_exclusivity(
  sibp.fit = sibp.fit,
  X = X,
  num.words = 10
)

print(exclusivity_score)
```

--------------------------------

### Visualize AMCE with sibp_amce_plot

Source: https://context7.com/christianfong/texteffect/llms.txt

Generates a coefficient plot for AMCE results, showing point estimates and confidence intervals. Useful for visualizing treatment effects and their significance.

```r
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

sibp.fit <- sibp(X, Y, K = 2, alpha = 4, sigmasq.n = 0.8, train.ind = train.ind)
amce_results <- sibp_amce(sibp.fit, X, Y)

# Plot all treatment effects with confidence intervals
sibp_amce_plot(
  sibp.amce = amce_results,
  xlab = "Feature",        # X-axis label
  ylab = "Outcome"         # Y-axis label
)
```

```r
# Plot only specific treatments (e.g., excluding intercept)
# subs parameter selects row indices to include
sibp_amce_plot(
  sibp.amce = amce_results,
  xlab = "Treatment",
  ylab = "Effect on Outcome",
  subs = 2:3               # Only plot Z1 and Z2, not intercept
)
```

--------------------------------

### Visualize AMCE Results

Source: https://context7.com/christianfong/texteffect/llms.txt

Plots treatment effects with confidence intervals. Use this to visually assess the statistical significance and magnitude of treatment effects on the outcome.

```R
sibp_amce_plot(amce_results, xlab = "Treatment", ylab = "Effect on Outcome")
```

--------------------------------

### infer_Z - Infer Treatment Assignments for Test Set

Source: https://context7.com/christianfong/texteffect/llms.txt

Infers the latent treatment assignments for documents in a test set, based on a fitted sIBP model trained on a training set. This function is typically used internally by `sibp_amce()` but can be called directly.

```APIDOC
## infer_Z - Infer Treatment Assignments for Test Set

### Description
The `infer_Z()` function applies the word-to-treatment mapping learned from the training set to infer which documents in the test set have which treatments. This is typically called internally by `sibp_amce()`, but can be used directly for validation experiments.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
#### Function Arguments
- **sibp.fit** (list) - A fitted sIBP model object.
- **X** (matrix) - Document-term matrix for the data to infer treatments on. If `newX` is FALSE, this should be the same data used to fit `sibp.fit`. If `newX` is TRUE, this is the new data.
- **newX** (logical) - If TRUE, `X` is new data and standardization parameters from `sibp.fit` are used. If FALSE, `X` contains the original training/test data and indices from `sibp.fit` are used to identify test documents.

### Request Example
```r
# Fit sIBP model on training data
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

sibp.fit <- sibp(X, Y, K = 2, alpha = 4, sigmasq.n = 0.8, train.ind = train.ind)

# Infer latent treatments for test set documents
# X should be the full data (same as used in sibp())
Z_test <- infer_Z(
  sibp.fit = sibp.fit,
  X = X,
  newX = FALSE             # FALSE = use test indices from sibp.fit
)

# Result is a matrix (N_test x K)
print(dim(Z_test))

# For entirely new data not in original train/test split:
# newX = TRUE standardizes using training set parameters
new_documents <- X[1:10, ]  # Example new documents
Z_new <- infer_Z(sibp.fit, new_documents, newX = TRUE)
```

### Response
#### Success Response
- **Z_test** or **Z_new** (matrix) - A matrix where rows represent documents and columns represent treatments. Values are probabilities (0 to 1) that a document belongs to a specific treatment.

#### Response Example
```
# [1] 125   2
```
```

--------------------------------

### Estimate AMCE using sibp_amce

Source: https://context7.com/christianfong/texteffect/llms.txt

Estimates Average Marginal Component Effects (AMCE) for each treatment using a fitted sIBP model. Can optionally account for group-level heterogeneous effects.

```r
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

sibp.fit <- sibp(X, Y, K = 2, alpha = 4, sigmasq.n = 0.8, train.ind = train.ind)

amce_results <- sibp_amce(
  sibp.fit = sibp.fit,
  X = X,                   # Full data (train + test)
  Y = Y,                   # Full outcomes (train + test)
  G = NULL,                # Optional group matrix for heterogeneous effects
  seed = 0,                # Random seed
  level = 0.05,            # Confidence level (0.05 = 95% CI)
  thresh = 0.5             # Threshold for binarizing treatment probabilities
)

print(amce_results)
```

```r
G <- cbind(BioSample$male, 1 - BioSample$male)  # Example group matrix
colnames(G) <- c("Male", "Female")
amce_by_group <- sibp_amce(sibp.fit, X, Y, G = G)
```

--------------------------------

### Compute AMCE using Test Set

Source: https://context7.com/christianfong/texteffect/llms.txt

Computes Average Marginal Component Analysis (AMCE) using the test set for valid causal inference. Requires a fitted sibp model, features (X), outcomes (Y), and a confidence level.

```R
amce_results <- sibp_amce(sibp.fit, X, Y, level = 0.05)
print(amce_results)
```

--------------------------------

### sibp_amce - Estimate Average Marginal Component Effects

Source: https://context7.com/christianfong/texteffect/llms.txt

Estimates the causal effect of each treatment on the outcome variable using the test set. It infers treatments on the test set and then regresses outcomes on these inferred treatments to compute Average Marginal Component Effects (AMCE) with confidence intervals.

```APIDOC
## sibp_amce - Estimate Average Marginal Component Effects

### Description
The `sibp_amce()` function estimates the causal effect of each treatment on the outcome using the test set. It first infers treatments on the test set, then regresses outcomes on the inferred treatments to compute the Average Marginal Component Effect (AMCE) with confidence intervals.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
#### Function Arguments
- **sibp.fit** (list) - A fitted sIBP model object.
- **X** (matrix) - Document-term matrix for the full dataset (training and test).
- **Y** (vector) - Outcome variable for the full dataset.
- **train.ind** (integer vector) - Indices of the training data, used to identify the test set.
- **num.words** (integer) - Number of top words to consider for treatment inference.
- **nboot** (integer) - Number of bootstrap samples for confidence interval calculation.

### Request Example
```r
# Fit sIBP model on training data
data(BioSample)
Y <- BioSample[,1]
X <- BioSample[,-1]
set.seed(1)
train.ind <- sample(1:nrow(X), size = 0.5*nrow(X), replace = FALSE)

sibp.fit <- sibp(X, Y, K = 2, alpha = 4, sigmasq.n = 0.8, train.ind = train.ind)

# Estimate AMCE for each treatment
amce_results <- sibp_amce(
  sibp.fit = sibp.fit,
  X = X,
  Y = Y,
  train.ind = train.ind,
  num.words = 10,
  nboot = 100
)

# Results include AMCE estimates and confidence intervals
print(amce_results)
```

### Response
#### Success Response
- **amce_results** (data.frame) - A data frame containing AMCE estimates and their confidence intervals for each treatment.

#### Response Example
```
#   treatment   amce    lower_ci    upper_ci
# 1           1 0.1234 -0.05678901  0.30336701
# 2           2 0.4567  0.23456789  0.67890123
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.