Package 'causalQual'

Causal Inference for Qualitative Outcomes under Difference-in-Differences

Description

Causal Inference for Qualitative Outcomes under Difference-in-Differences

Usage

causalQual_did(Y, D, unit_id, time)

Arguments

Y	Qualitative outcome before treatment. Must be labeled as $\{1, 2, \dots\}$.
D	Binary treatment indicator.
unit_id	Unit identifier.
time	Time identifier.
treatment_start	Denots at which time treatment starts. Must be zero for never-treated.
...	Other arguments for the att_gt function.

Details

Under a difference-in-difference design, identification requires that the probabilities time shift for $Y_{is} (0)$ for class $m$ evolve similarly for the treated and control groups (parallel trends on the probability mass functions of $Y_{is}(0)$). If this assumption holds, we can recover the probability of shift on the treated for class $m$:

$\delta_{m, T} := P(Y_{it} (1) = m | D_i = 1) - P(Y_{it}(0) = m | D_i = 1).$

causalQual_did applies, for each class $m$, the canonical two-group/two-period method to the binary variable $1(Y_{is} = m)$. Specifically, consider the following linear model:

$1(Y_{is} = m) = D_i \beta_{m1} + 1(s = t) \beta_{m2} + D_i 1(s = t) \beta_{m3} + \epsilon_{mis}.$

The OLS estimate $\hat{\beta}_{m3}$ of $\beta_{m3}$ is our estimate of the probability shift on the treated for class m. Standard errors are clustered at the unit level and used to construct conventional confidence intervals.

Value

An object of class causalQual.

Author(s)

Riccardo Di Francesco

References

• Di Francesco, R., and Mellace, G. (2025). Causal Inference for Qualitative Outcomes. arXiv preprint arXiv:2502.11691. doi:10.48550/arXiv.2502.11691.

See Also

causalQual_soo causalQual_iv causalQual_rd

Examples

## Generate synthetic data.
set.seed(1986)

data <- generate_qualitative_data_did(100, assignment = "observational",
                                      outcome_type = "ordered")

Y <- data$Y
D <- data$D
unit_id <- data$unit_id
time <- data$time

## Estimate probabilities of shift on the treated.
fit <- causalQual_did(Y, D, unit_id, time)

summary(fit)
plot(fit)

---

Causal Inference for Qualitative Outcomes under Instrumental Variables

Description

Causal Inference for Qualitative Outcomes under Instrumental Variables

Usage

causalQual_iv(Y, D, Z)

Arguments

Y	Qualitative outcome before treatment. Must be labeled as $\{1, 2, \dots\}$.
D	Binary treatment indicator.
Z	Binary instrument.

Details

Under an instrumental-variables design, identification requires the instrument to be independent of potential outcomes and potential treatments (exogeneity), that the instrument influences the outcome solely through its effect on treatment (exclusion restriction), that the instrument has a nonzero effect on treatment probability (relevance), and that the instrument can only increase/decrease the treatment probability (monotonicity). If these assumptions hold, we can recover the local probabilities of shift for all classes:

$\delta_{m, L} := P(Y_i(1) = m | i \, is \, complier) - P(Y_i(0) = m | i \, is \, complier), \, m = 1, \dots, M.$

causalQual_iv applies, for each class m, the standard two-stage least squares method to the binary variable $1(Y_i = m)$. Specifically, the routine first estimates the following first-stage regression model via OLS:

$D_i = \gamma_0 + \gamma_1 Z_i + \nu_i,$

and constructs the predicted values $\hat{D}_i$. It then uses these predicted values in the second-stage regressions:

$1(Y_i = m) = \alpha_{m0} + \alpha_{m1} \hat{D}_i + \epsilon_{mi}, \quad m = 1, \dots, M.$

The OLS estimate $\hat{\alpha}_{m1}$ of $\alpha_{m1}$ is then our estimate of $\delta_{m, L}$. Standard errors are computed using conventional procedures and used to construct conventional confidence intervals. All of this is done by calling the ivreg function.

Value

An object of class causalQual.

Author(s)

Riccardo Di Francesco

References

• Di Francesco, R., and Mellace, G. (2025). Causal Inference for Qualitative Outcomes. arXiv preprint arXiv:2502.11691. doi:10.48550/arXiv.2502.11691.

See Also

causalQual_soo causalQual_rd causalQual_did

Examples

## Generate synthetic data.
set.seed(1986)

data <- generate_qualitative_data_iv(100, outcome_type = "ordered")

Y <- data$Y
D <- data$D
Z <- data$Z

## Estimate local probabilities of shift.
fit <- causalQual_iv(Y, D, Z)

summary(fit)
plot(fit)

---

Causal Inference for Qualitative Outcomes under Regression Discontinuity

Description

Causal Inference for Qualitative Outcomes under Regression Discontinuity

Usage

causalQual_rd(Y, running_variable, cutoff)

Arguments

Y	Qualitative outcome. Must be labeled as $\{1, 2, \dots\}$.
running_variable	Running variable determining treatment assignment.
cutoff	Cutoff or threshold. Units with running_variable < cutoff are considered controls, while units with running_variable >= cutoff are considered treated.

Details

Under a regression discontinuity design, identification requires that the probability mass functions for class $m$ of potential outcomes are continuous in the running variable (continuity). If this assumption holds, we can recover the probability shift at the cutoff for class $m$:

$\delta_{m, C} := P(Y_i (1) = m | Running_i = cutoff) - P(Y_i(0) = m | Running_i = cutoff).$

causalQual_rd applies, for each class $m$, standard local polynomial estimators to the binary variable $1(Y_i = m)$. Specifically, the ruotine implements the robust bias-corrected inference procedure of Calonico et al. (2014) (see the rdrobust function).

Value

An object of class causalQual.

Author(s)

Riccardo Di Francesco

References

• Di Francesco, R., and Mellace, G. (2025). Causal Inference for Qualitative Outcomes. arXiv preprint arXiv:2502.11691. doi:10.48550/arXiv.2502.11691.

See Also

causalQual_soo causalQual_iv causalQual_did

Examples

## Generate synthetic data.
set.seed(1986)

data <- generate_qualitative_data_rd(100, outcome_type = "ordered")

Y <- data$Y
running_variable <- data$running_variable
cutoff <- data$cutoff

## Estimate probabilities of shift at the cutoff.
fit <- causalQual_rd(Y, running_variable, cutoff)

summary(fit)
plot(fit)

---

Causal Inference for Qualitative Outcomes under Selection-on-Observables

Description

Causal Inference for Qualitative Outcomes under Selection-on-Observables

Usage

causalQual_soo(Y, D, X, outcome_type, K = 5)

Arguments

Y	Qualitative outcome. Must be labeled as $\{1, 2, \dots\}$.
D	Binary treatment indicator.
X	Covariate matrix (no intercept).
outcome_type	String controlling the outcome type. Must be either "multinomial" or "ordered". Affects estimation of conditional class probabilities.
K	Number of folds for nuisance functions estimation.

Details

Under a selection-on-observables design, identification requires the treatment indicator to be (conditionally) independent of potential outcomes (unconfoundedness), and that each unit has a non-zero probability of being treated (common support). If these assumptions hold, we can recover the probabilities of shift of all classes:

$\delta_m := P(Y_i(1) = m) - P(Y_i(0) = m), \, m = 1, \dots, M.$

causalQual_soo constructs and averages doubly robust scores for qualitative outcomes to estimate $\delta_m$. For each class $m$, the doubly robust score for unit $i$ is defined as:

$\hat{\Gamma}_{m, i} = \hat{P}(Y_i = m \mid D_i = 1, X_i) - \hat{P}(Y_i = m \mid D_i = 0, X_i) +$

$D_i \frac{1\{Y_i = m\} - \hat{P}(Y_i = m \mid D_i = 1, X_i)} {\hat{P}(D_i = 1 | X_i)} - (1 - D_i) \frac{1\{Y_i = m\} - \hat{P}(Y_i = m \mid D_i = 0, X_i)} {1 - \hat{P}(D_i = 1 | X_i)}.$

The estimator for $\delta_m$ is then the average of the scores:

$\hat{\delta}_m = \frac{1}{n} \sum_{i=1}^{n} \hat{\Gamma}_{m, i},$

with its variance estimated as:

$\widehat{\text{Var}} ( \hat{\delta}_m ) = \frac{1}{n} \sum_{i=1}^{n} ( \hat{\Gamma}_{m, i} - \hat{\delta}_m )^2.$

causalQual_soo uses these estimates to construct confidence intervals based on conventional normal approximations.

If outcome_type == "multinomial", $\hat{P}(Y_i = m \mid D_i = 1, X_i)$ and $\hat{P}(Y_i = m \mid D_i = 0, X_i)$ are estimated using a multinomial_ml strategy with regression forests as base learners. Else, if outcome_type == "ordered", $\hat{P}(Y_i = m \mid D_i = 1, X_i)$ and $\hat{P}(Y_i = m \mid D_i = 0, X_i)$ are estimated using the honest version of the ocf estimator. $\hat{P}(D_i = 1 | X_i)$ is always estimated via a honest regression_forest. K-fold cross-fitting is employed for the estimation of all these functions.

Folds are created by random split. If some class of Y is not observed in one or more folds for one or both treatment groups, a new random partition is performed. This process is repeat until when all classes are observed in all folds and for all treatment groups up to 1000 times, after which the routine raises an error.

Value

An object of class causalQual.

Author(s)

Riccardo Di Francesco

References

• Di Francesco, R., and Mellace, G. (2025). Causal Inference for Qualitative Outcomes. arXiv preprint arXiv:2502.11691. doi:10.48550/arXiv.2502.11691.

See Also

causalQual_iv causalQual_rd causalQual_did

Examples

## Generate synthetic data.
set.seed(1986)

data <- generate_qualitative_data_soo(200, assignment = "observational",
                                      outcome_type = "ordered")
Y <- data$Y
D <- data$D
X <- data$X

# Estimate probabilities of shift.
fit <- causalQual_soo(Y, D, X, outcome_type = "ordered", K = 2)

summary(fit)
plot(fit)

---

Generate Qualitative Data (Difference-in-Differences)

Description

Generate a synthetic data set with qualitative outcomes under a difference-in-differences design. The data include two time periods, a binary treatment indicator (applied only in the second period), and a matrix of covariates. Probabilities time shift among the treated and control groups evolve similarly across the two time periods (parallel trends on the probability mass functions).

Usage

generate_qualitative_data_did(n, assignment, outcome_type)

Arguments

n	Sample size.
assignment	String controlling treatment assignment. Must be either "randomized" (random assignment) or "observational" (assignment based on covariates).
outcome_type	String controlling the outcome type. Must be either "multinomial" or "ordered".

Details

Outcome type

Potential outcomes are generated differently according to outcome_type. If outcome_type == "multinomial", generate_qualitative_data_did computes linear predictors for each class using the covariates:

$\eta_{mi} (d, s) = \beta_{m1}^d X_{i1} + \beta_{m2}^d X_{i2} + \beta_{m3}^d X_{i3}, \quad d = 0, 1, \quad s = t-1, t,$

and then transforms $\eta_{mi} (d, s)$ into valid probability distributions using the softmax function:

$P(Y_{is}(d) = m | X_i) = \frac{\exp(\eta_{mi} (d, s))}{\sum_{m'} \exp(\eta_{m'i}(d, s))}, \quad d = 0, 1, \quad s = t-1, t.$

It then generates potential outcomes $Y_{it-1}(1)$, $Y_{it}(1)$, $Y_{it-1}(0)$, and $Y_{it}(0)$ by sampling from {1, 2, 3} using $P(Y(d, s) = m \mid X), \, d = 0, 1, \, s = t-1, t$.

If instead outcome_type == "ordered", generate_qualitative_data_did first generates latent potential outcomes:

$Y_i^* (d, s) = \tau d + X_{i1} + X_{i2} + X_{i3} + N (0, 1), \quad d = 0, 1, \quad s = t-1, t,$

with $\tau = 2$. It then constructs $Y_i (d, s)$ by discretizing $Y_i^* (d, s)$ using threshold parameters $\zeta_1 = 2$ and $\zeta_2 = 4$. Then,

$P(Y_i(d, s) = m | X_i) = P(\zeta_{m-1} < Y_i^*(d, s) \leq \zeta_m | X_i) = \Phi (\zeta_m - \sum_j X_{ij} - \tau d) - \Phi (\zeta_{m-1} - \sum_j X_{ij} - \tau d), \quad d = 0, 1, \quad s = t-1, t,$

which allows us to analytically compute the probabilities of shift on the treated.

Treatment assignment

Treatment is always assigned as $D_i \sim \text{Bernoulli}(\pi(X_i))$. If assignment == "randomized", then the propensity score is specified as $\pi(X_i) = P ( D_i = 1 | X_i)) = 0.5$. If instead assignment == "observational", then $\pi(X_i) = (X_{i1} + X_{i3}) / 2$.

Other details

The function always generates three independent covariates from $U(0,1)$. Observed outcomes $Y_{is}$ are always constructed using the usual observational rule.

Value

A list storing a data frame with the observed data, the true propensity score, and the true probabilities of shift on the treated.

Author(s)

Riccardo Di Francesco

See Also

generate_qualitative_data_soo generate_qualitative_data_iv generate_qualitative_data_rd

Examples

## Generate synthetic data.
set.seed(1986)

data <- generate_qualitative_data_did(100,
                                      assignment = "observational",
                                      outcome_type = "ordered")

data$pshifts_treated

---

Generate Qualitative Data (Instrumental Variables)

Description

Generate a synthetic data set with qualitative outcomes under an instrumental variables design. The data include a binary treatment indicator and a binary instrument. Potential outcomes and potential treatments are independent of the instrument. Moreover, the instrument does not directly impact potential outcomes, has an impact on treatment probability, and can only increase the probability of treatment.

Usage

generate_qualitative_data_iv(n, outcome_type)

Arguments

n	Sample size.
outcome_type	String controlling the outcome type. Must be either "multinomial" or "ordered". Affects how potential outcomes are generated.

Details

Outcome type

Potential outcomes are generated differently according to outcome_type. If outcome_type == "multinomial", generate_qualitative_data_iv computes linear predictors for each class using the covariates:

$\eta_{mi} (d) = \beta_{m1}^d X_{i1} + \beta_{m2}^d X_{i2} + \beta_{m3}^d X_{i3}, \quad d = 0, 1,$

and then transforms $\eta_{mi} (d)$ into valid probability distributions using the softmax function:

$P(Y_i(d) = m | X_i) = \frac{\exp(\eta_{mi} (d))}{\sum_{m'} \exp(\eta_{m'i}(d))}, \quad d = 0, 1.$

It then generates potential outcomes $Y_i(1)$ and $Y_i(0)$ by sampling from {1, 2, 3} using $P_i(Y(d) = m | X), \, d = 0, 1$.

If instead outcome_type == "ordered", generate_qualitative_data_iv first generates latent potential outcomes:

$Y_i^* (d) = \tau d + X_{i1} + X_{i2} + X_{i3} + N (0, 1), \quad d = 0, 1,$

with $\tau = 2$. It then constructs $Y_i (d)$ by discretizing $Y_i^* (d)$ using threshold parameters $\zeta_1 = 2$ and $\zeta_2 = 4$. Then,

$P(Y_i(d) = m | X_i) = P(\zeta_{m-1} < Y_i^*(d) \leq \zeta_m | X_i) = \Phi (\zeta_m - \sum_j X_{ij} - \tau d) - \Phi (\zeta_{m-1} - \sum_j X_{ij} - \tau d), \quad d = 0, 1,$

which allows us to analytically compute the local probabilities of shift.

Treatment assignment and instrument

The instrument is always generated as $Z_i \sim \text{Bernoulli}(0.5)$. Treatment is always modeled as $D_i \sim \text{Bernoulli}(\pi(X_i, Z_i))$, with $\pi(X_i, Z_i) = P ( D_i = 1 | X_i, Z_i)) = (X_{i1} + X_{i3} + Z_i) / 3$. Thus, $Z_i$ can increase the probability of treatment intake but cannot decrease it.

Other details

The function always generates three independent covariates from $U(0,1)$. Observed outcomes $Y_i$ are always constructed using the usual observational rule.

The DGPs outlined above ensure that $Z_i$ is a valid instrument for D_i.

Value

A list storing a data frame with the observed data, the true propensity score, the true instrument propensity score, and the true local probabilities of shift.

Author(s)

Riccardo Di Francesco

See Also

generate_qualitative_data_soo generate_qualitative_data_rd generate_qualitative_data_did

Examples

## Generate synthetic data.
set.seed(1986)

data <- generate_qualitative_data_iv(100,
                                     outcome_type = "ordered")

data$local_pshifts

---

Generate Qualitative Data (Regression Discontinuity)

Description

Generate a synthetic data set with qualitative outcomes under a regression discontinuity design. The data include a binary treatment indicator and a single covariate (the running variable). The conditional probability mass fuctions of potential outcomes are continuous in the running variable.

Usage

generate_qualitative_data_rd(n, outcome_type)

Arguments

n	Sample size.
outcome_type	String controlling the outcome type. Must be either "multinomial" or "ordered". Affects how potential outcomes are generated.

Details

Outcome type

Potential outcomes are generated differently according to outcome_type. If outcome_type == "multinomial", generate_qualitative_data_rd computes linear predictors for each class using the covariates:

$\eta_{mi} (d) = \beta_{m1}^d X_{i1} + \beta_{m2}^d X_{i2} + \beta_{m3}^d X_{i3}, \quad d = 0, 1,$

and then transforms $\eta_{mi} (d)$ into valid probability distributions using the softmax function:

$P(Y_i(d) = m | X_i) = \frac{\exp(\eta_{mi} (d))}{\sum_{m'} \exp(\eta_{m'i}(d))}.$

It then generates potential outcomes $Y_i(1)$ and $Y_i(0)$ by sampling from {1, 2, 3} using $P(Y_i(d) = m | X_i), \, d = 0, 1$.

If instead outcome_type == "ordered", generate_qualitative_data_rd first generates latent potential outcomes:

$Y_i^* (d) = \tau d + X_{i1} + X_{i2} + X_{i3} + N (0, 1), \quad d = 0, 1,$

with $\tau = 2$. It then constructs $Y_i (d)$ by discretizing $Y_i^* (d)$ using threshold parameters $\zeta_1 = 2$ and $\zeta_2 = 4$. Then,

$P(Y_i(d) = m) = P(\zeta_{m-1} < Y_i^*(d) \leq \zeta_m) = \Phi (\zeta_m - \sum_j X_{ij} - \tau d) - \Phi (\zeta_{m-1} - \sum_j X_{ij} - \tau d), \quad d = 0, 1,$

which allows us to analytically compute the probabilities of shift at the cutoff.

Treatment assignment

Treatment is always assigned as $D_i = 1(X_i \geq 0.5)$.

Other details

The function always generates three independent covariates from $U(0,1)$. Observed outcomes $Y_i$ are always constructed using the usual observational rule.

The DGPs outlined above ensure identification under a standard regression discontinuity design.

Value

A list storing a data frame with the observed data, and the true probabilities of shift at the cutoff.

Author(s)

Riccardo Di Francesco

See Also

generate_qualitative_data_soo generate_qualitative_data_iv generate_qualitative_data_did

Examples

## Generate synthetic data.
set.seed(1986)

data <- generate_qualitative_data_rd(100,
                                     outcome_type = "ordered")

data$pshifts_cutoff

---

Generate Qualitative Data (Selection-on-Observables)

Description

Generate a synthetic data set with qualitative outcomes under a selection-on-observables design. The data include a binary treatment indicator and a matrix of covariates. The treatment is either independent or conditionally (on the covariates) independent of potential outcomes, depending on users' choices.

Usage

generate_qualitative_data_soo(n, assignment, outcome_type)

Arguments

n	Sample size.
assignment	String controlling treatment assignment. Must be either "randomized" (random assignment) or "observational" (random assigment conditional on the generated covariates).
outcome_type	String controlling the outcome type. Must be either "multinomial" or "ordered". Affects how potential outcomes are generated.

Details

Outcome type

Potential outcomes are generated differently according to outcome_type. If outcome_type == "multinomial", generate_qualitative_data_soo computes linear predictors for each class using the covariates:

$\eta_{mi} (d) = \beta_{m1}^d X_{i1} + \beta_{m2}^d X_{i2} + \beta_{m3}^d X_{i3}, \quad d = 0, 1,$

and then transforms $\eta_{mi} (d)$ into valid probability distributions using the softmax function:

$P(Y_i(d) = m | X_i) = \frac{\exp(\eta_{mi} (d))}{\sum_{m'} \exp(\eta_{m'i}(d))}, \quad d = 0, 1.$

It then generates potential outcomes $Y_i(1)$ and $Y_i(0)$ by sampling from {1, 2, 3} using $P(Y_i(d) = m | X_i), \, d = 0, 1$.

If instead outcome_type == "ordered", generate_qualitative_data_soo first generates latent potential outcomes:

$Y_i^* (d) = \tau d + X_{i1} + X_{i2} + X_{i3} + N (0, 1), \quad d = 0, 1,$

with $\tau = 2$. It then constructs $Y_i (d)$ by discretizing $Y_i^* (d)$ using threshold parameters $\zeta_1 = 2$ and $\zeta_2 = 4$. Then,

$P(Y_i(d) = m | X_i) = P(\zeta_{m-1} < Y_i^*(d) \leq \zeta_m | X_i) = \Phi (\zeta_m - \sum_j X_{ij} - \tau d) - \Phi (\zeta_{m-1} - \sum_j X_{ij} - \tau d), \quad d = 0, 1,$

which allows us to analytically compute the probabilities of shift.

Treatment assignment

Treatment is always assigned as $D_i \sim \text{Bernoulli}(\pi(X_i))$. If assignment == "randomized", then the propensity score is specified as $\pi(X_i) = P ( D_i = 1 | X_i)) = 0.5$. If instead assignment == "observational", then $\pi(X_i) = (X_{i1} + X_{i3}) / 2$.

Other details

The function always generates three independent covariates from $U(0,1)$. Observed outcomes $Y_i$ are always constructed using the usual observational rule.

Controlling for $X_{i1}$ and $X_{i3}$ is sufficient for selection-on-observables to hold.

Value

A list storing a data frame with the observed data, the true propensity score, and the true probabilities of shift.

Author(s)

Riccardo Di Francesco

See Also

generate_qualitative_data_iv generate_qualitative_data_rd generate_qualitative_data_did

Examples

## Generate synthetic data.
set.seed(1986)

data <- generate_qualitative_data_soo(100,
                                      assignment = "observational",
                                      outcome_type = "ordered")

data$pshifts

---

Plot Method for causalQual Objects

Description

Plots an causalQual object.

Usage

## S3 method for class 'causalQual'
plot(x, hline = TRUE, ...)

Arguments

x	An causalQual object.
hline	Logical, whether to display an horizontal line at zero in the plot.
...	Further arguments passed to or from other methods.

Value

Plots an causalQual object.

Author(s)

Riccardo Di Francesco

See Also

causalQual

Examples

## Generate synthetic data.
set.seed(1986)

data <- generate_qualitative_data_soo(1000, assignment = "observational",
                                      outcome_type = "ordered")
Y <- data$Y
D <- data$D
X <- data$X

## Estimate probabilities of shifts.
fit <- causalQual_soo(Y = Y, D = D, X = X, outcome_type = "ordered")
plot(fit)

---

Print Method for causalQual Objects

Description

Prints an causalQual object.

Usage

## S3 method for class 'causalQual'
print(x, ...)

Arguments

x	An causalQual object.
...	Further arguments passed to or from other methods.

Value

Prints an causalQual object.

Author(s)

Riccardo Di Francesco

See Also

causalQual

Examples

## Generate synthetic data.
set.seed(1986)

data <- generate_qualitative_data_soo(1000, assignment = "observational",
                                      outcome_type = "ordered")
Y <- data$Y
D <- data$D
X <- data$X

## Estimate probabilities of shifts.
fit <- causalQual_soo(Y = Y, D = D, X = X, outcome_type = "ordered")
print(fit)

---

Summary Method for causalQual Objects

Description

Summarizes an causalQual object.

Usage

## S3 method for class 'causalQual'
summary(object, ...)

Arguments

object	An causalQual object.
...	Further arguments passed to or from other methods.

Value

Summarizes an causalQual object.

Author(s)

Riccardo Di Francesco

See Also

causalQual

Examples

## Generate synthetic data.
set.seed(1986)

data <- generate_qualitative_data_soo(1000, assignment = "observational",
                                      outcome_type = "ordered")
Y <- data$Y
D <- data$D
X <- data$X

## Estimate probabilities of shifts.
fit <- causalQual_soo(Y = Y, D = D, X = X, outcome_type = "ordered")
summary(fit)

---