Type: Package
Title: Estimate the First-Exposure Effect (FEE) using Count Data Models
Version: 1.0.0
Author: Ryan T. Godwin [aut, cre]
Maintainer: Ryan T. Godwin <ryan.godwin@umanitoba.ca>
Description: Estimates the first-exposure effect (FEE) using a one-inflated positive Poisson model, or a one-inflated zero-truncated negative binomial model. In addition, estimates the marginal FEE, and standard errors for the FEE and marginal FEE.
License: GPL (≥ 3)
Imports: graphics, oneinfl
Encoding: UTF-8
RoxygenNote: 7.3.2
NeedsCompilation: no
Packaged: 2025-07-21 21:06:00 UTC; ryang
Repository: CRAN
Date/Publication: 2025-07-22 11:50:06 UTC

Marginal First-Exposure Effects

Description

Computes marginal first-exposure effects from a fitted oneinfl model. Dummy variables are automatically detected as those with exactly two unique values in the data, and corresponding marginal effects are instead calculated by differencing the FEE between both values of the dummy.

Usage

dfee(model, data, at = "AE")

Arguments

model

A fitted model object of class "oneinfl".

data

A data frame containing the variables used to fit the model.

at

A character string or list. Specifies where the marginal FEE should be evaluated. Options are "AE" (average), "EM" (means), or a named list of covariate values.

Details

The marginal effects can be evaluated in three ways, determined by the at argument:

Value

A list with components:

dfee

A named numeric vector of estimated marginal first-exposure effects for each variable.

sefee

A numeric vector of standard errors corresponding to the marginal effects.

where

A character string describing the evaluation point.

See Also

fee, dfee_pois, dfee_nb

Examples

df <- data.frame(x = runif(10,0,10), d = sample(c(0,1), 10, replace=TRUE), y = rpois(10, 3) + 1)
model <- oneinfl::oneinfl(formula = y ~ x + d | x + d, df = df, dist = "Poisson")
dfee(model, data = df)

Marginal First-Exposure Effects for One-Inflated Zero-Truncated Negative Binomial model

Description

This function is used internally by dfee. The function computes analytical derivatives of the FEE with respect to covariates, and uses discrete differences for binary indicators.

Usage

dfee_nb(b, g, a, X, Z, dummies)

Arguments

b

A numeric vector of estimated coefficients for the rate.

g

A numeric vector of estimated coefficients for inflation.

a

A dispersion parameter from the negative binomial model.

X

A numeric matrix of covariates for the rate.

Z

A numeric matrix of covariates for inflation.

dummies

A character vector naming the binary (dummy) variables to compute marginal effects for.

Value

A matrix of marginal first-exposure effects. Each column corresponds to a covariate, and each row corresponds to an observation in the data.

See Also

dfee, fee_negbin, dfee_pois

Marginal First-Exposure Effects for One-Inflated Poisson Model

Description

This function is used internally by dfee. The function computes analytical derivatives of the FEE with respect to covariates, and uses discrete differences for binary indicators.

Usage

dfee_pois(b, g, X, Z, dummies)

Arguments

b

A numeric vector of estimated coefficients for the rate.

g

A numeric vector of estimated coefficients for inflation.

X

A numeric matrix of covariates for the rate.

Z

A numeric matrix of covariates for inflation.

dummies

A character vector naming the binary (dummy) variables to compute marginal effects for.

Value

A matrix of marginal first-exposure effects. Each column corresponds to a covariate, and each row corresponds to an observation in the data.

See Also

dfee, fee_pois, dfee_nb

First-Exposure Effect

Description

Computes the first-exposure effect (FEE) from a fitted 'oneinfl' model object. The FEE measures the difference between the expected count for a first-time exposure and the expected count under the baseline (non-inflated) model. The function supports models estimated using either a one-inflated positive Poisson distribution or a one-inflated zero-truncated negative binomial distribution.

Usage

fee(model, data, at = "AE")

Arguments

model

A fitted model object of class "oneinfl".

data

The original data frame used to fit the model.

at

A character string or list. Specifies how the first-exposure effect should be evaluated. Options are "AE" (average effect across the data), "EM" (effect at means), or a named list specifying covariate values for evaluating a representative case.

Details

The effect can be evaluated in three ways, determined by the 'at' argument:

If 'at = "AE"', the returned object also includes the total number of treatment visits implied by the FEE across all observations.

Value

A list with components:

fee

The estimated first-exposure effect.

sefee

The standard error of the estimated effect.

where

A character string describing the evaluation point.

treatment_visits

(Optional) Total implied treatment visits if at = "AE".

Examples

# Example usage
df <- data.frame(x = runif(10,0,10), d = sample(c(0,1), 10, replace=TRUE), y = rpois(10, 3) + 1)
model <- oneinfl::oneinfl(formula = y ~ x + d | x + d, df = df, dist = "Poisson")
fee(model, data = df)

First-Exposure Effect for One-Inflated Zero-Truncated Negative Binomial Model

Description

Computes the first-exposure effect (FEE) for a model estimated using the one-inflated zero-truncated negative binomial distribution. The FEE represents the change in expected counts associated with the first exposure to treatment, relative to the counterfactual zero-truncated negative binomial model. This function is used internally by fee at given covariate values.

Usage

fee_negbin(b, g, a, X, Z)

Arguments

b

A numeric vector of estimated coefficients for the rate.

g

A numeric vector of estimated coefficients for inflation.

a

A dispersion parameter from the negative binomial model.

X

A numeric matrix of covariates for the rate.

Z

A numeric matrix of covariates for inflation.

Value

A numeric vector of first-exposure effect(s).

See Also

fee, fee_pois

First-Exposure Effect for One-Inflated Positive Poisson Model

Description

Computes the first-exposure effect (FEE) for a model estimated using the one-inflated positive Poisson distribution. The FEE represents the change in expected counts associated with the first exposure to treatment, relative to the counterfactual positive Poisson model.This function is used internally by fee at given covariate values.

Usage

fee_pois(b, g, X, Z)

Arguments

b

A numeric vector of estimated coefficients for the rate.

g

A numeric vector of estimated coefficients for inflation.

X

A numeric matrix of covariates for the rate.

Z

A numeric matrix of covariates for inflation.

Value

A numeric vector of first-exposure effect(s).

See Also

fee, fee_negbin

Plot First-Exposure Effect Distribution

Description

Creates a bar plot of the observed count data overlaid with fitted values from a oneinfl model and its associated counterfactual (non-inflated) model.

Usage

feeplot(model, data, maxpred, ylimit, cex = 1.5, lwd = 1.5, ...)

Arguments

model

A fitted object of class "oneinflmodel".

data

A data frame containing the original data used to fit the model.

maxpred

Optional integer indicating the maximum count value to include on the x-axis. Defaults to the maximum observed value in data.

ylimit

Optional numeric value specifying the upper limit of the y-axis. Defaults to 110% of the maximum observed count frequency.

cex

A numeric value for point size in the overlay plot. Defaults to 1.5.

lwd

A numeric value for line width in the overlay plot. Defaults to 1.5.

...

Additional arguments passed to points() or lines().

Details

The factual predictions come from the fitted oneinfl model, while the counterfactual distribution is obtained by transforming the model into a non-inflated counterpart using the same estimated parameters.

The function detects whether the model is based on a Poisson or negative binomial distribution and selects the appropriate counterfactual model.

Value

A barplot with overlaid predicted values from the factual and counterfactual distributions, including a legend identifying each component.

See Also

feepred, fee, dfee

Examples

df <- data.frame(x = runif(10,0,10), d = sample(c(0,1), 10, replace=TRUE), y = rpois(10, 3) + 1)
model <- oneinfl::oneinfl(formula = y ~ x + d | x + d, df = df, dist = "Poisson")
feeplot(model, data = df)

Predicted Counts from One-Inflated or Truncated Count Models

Description

Computes the predicted count distribution from a fitted model of class "oneinflmodel", "truncmodel", or "basicPoisson". The function returns the expected frequency for each count value from 1 up to maxpred, based on the model's parameters.

Usage

feepred(model, data, maxpred)

Arguments

model

A fitted model object of class "oneinflmodel", "truncmodel", or "basicPoisson".

data

A data frame containing the covariates used to fit the model.

maxpred

Optional integer specifying the maximum count value for which to compute predicted frequencies. If not supplied, defaults to the maximum observed count in the data.

Details

The function determines the model type based on its class and the dist attribute, and applies the appropriate density function:

Value

A numeric vector of length maxpred, giving the predicted expected frequency of each count from 1 to maxpred.

See Also

feeplot, fee, dfee

Examples

df <- data.frame(x = runif(10,0,10), d = sample(c(0,1), 10, replace=TRUE), y = rpois(10, 3) + 1)
model <- oneinfl::oneinfl(formula = y ~ x + d | x + d, df = df, dist = "Poisson")
feepred(model, data = df)