% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/effect_measures.R
\name{estimate_hr_ir}
\alias{estimate_hr_ir}
\title{Estimate Incidence Rates and Hazard Ratios}
\usage{
estimate_hr_ir(
  in_df_unwt = NULL,
  in_df_wted = NULL,
  out_xlsxpath = NULL,
  exposure_var = "exp",
  exp_value = 1,
  ref_value = 0,
  outcome_var = NULL,
  weight_var = NULL,
  survival_time = NULL,
  time_unit = c("days", "years"),
  ir_per_pyears = 1000,
  confidence_level = 0.95,
  readme_text = NULL,
  stratify_by = NULL,
  verbose = TRUE
)
}
\arguments{
\item{in_df_unwt}{Data frame for unweighted analysis. Set to NULL to skip unweighted analysis.
This could be the full cohort, matched data, or any specific population}

\item{in_df_wted}{Data frame for weighted analysis. Set to NULL to skip weighted analysis.
This could be the same as unweighted data or a different population (e.g., trimmed)}

\item{out_xlsxpath}{Character string. Path for output Excel file with all results}

\item{exposure_var}{Character string. Name of binary exposure/treatment variable (default: "exp")}

\item{exp_value}{Value representing the exposed/treated group (default: 1)}

\item{ref_value}{Value representing the reference/control group (default: 0)}

\item{outcome_var}{Character string. Name of the event indicator variable (0=censored, 1=event)}

\item{weight_var}{Character string. Name of weight variable in the weighted dataset.
Required when in_df_wted is not NULL.}

\item{survival_time}{Character string. Name of survival/follow-up time variable (required)}

\item{time_unit}{Character string. Unit of time for survival analysis: "days" or "years".
Default: "days"}

\item{ir_per_pyears}{Numeric. Multiplier for incidence rate per person-years.
Allowed values: 1, 100, 1000, 10000, 100000.
Default: 1000 (i.e., IR per 1,000 person-years).
Column name is fixed as IR_per_Npy_Unwt / IR_per_Npy_Wted. The actual
multiplier value is documented in the Analysis Summary sheet.}

\item{confidence_level}{Numeric. Confidence level for confidence intervals (default: 0.95 for 95\% CI)}

\item{readme_text}{Character string. Optional message to include in README sheet at beginning of Excel file.
Use this to document the analysis parameters, data sources, or any notes}

\item{stratify_by}{Character string. Name of the stratification variable.
When specified:
- Cox model uses strata() in the formula (separate baseline hazards per stratum)
- IR/IRD are computed via direct standardization using total cohort person-time
distribution as weights
Default: NULL (no stratification)}

\item{verbose}{Logical. Print progress messages (default TRUE).}
}
\value{
Invisibly returns a list containing:
\itemize{
\item incidence_rates: Data frame with event counts, person-years, and incidence rates
\item hazard_ratios: Data frame with unweighted and/or weighted HR estimates
\item unweighted_model: The unweighted Cox model object (if unweighted analysis performed)
\item weighted_model: The weighted Cox model object (if weighted analysis performed)
\item stratum_details_unwt: Data frame with stratum-level details (if stratified, unweighted)
\item stratum_details_wted: Data frame with stratum-level details (if stratified, weighted)
Also saves results to Excel file when out_xlsxpath is provided
}
}
\description{
This function estimates incidence rates and hazard ratios for time-to-event outcomes.
It can perform unweighted analysis, weighted (propensity score adjusted) analysis, or both,
using potentially different datasets for each analysis type.
Incidence rate CIs are estimated using Poisson distribution.
}
\details{
The function allows flexible analysis configurations:
\itemize{
\item Unweighted only: Set in_df_unwt = data, in_df_wted = NULL
\item Weighted only: Set in_df_unwt = NULL, in_df_wted = data
\item Both: Provide both datasets (can be the same or different populations)
}

For unweighted analysis:
\itemize{
\item Uses standard Cox regression without weights
\item Can be applied to matched data, trimmed data, or full cohort
}

For weighted analysis:
\itemize{
\item Uses weighted Cox regression with specified weights
\item Typically applied to PS-weighted data (IPTW, MW, OW, FS weights)
}

Stratification (stratify_by parameter):
When stratify_by is specified:
\itemize{
\item Cox model: Fits a stratified Cox proportional hazards model using strata() in the
model formula. This allows separate baseline hazard functions for each stratum while
estimating a common treatment effect (HR) across strata.
\item IR/IRD: Uses direct standardization with total cohort person-time distribution as
standard weights.
\itemize{
\item IR_std = sum(Rate_k * W_k) where W_k = PT_total_k / PT_total
\item Variance via delta method: Var = sum(W_k^2 * d_k / PT_k^2)
\item IRD_std = IR_std_exposed - IR_std_unexposed
\item CI for standardized IR uses log-transformation to ensure positive bounds
}
}

ir_per_pyears parameter:
Controls the person-year multiplier for incidence rates and incidence rate differences.
For example:
\itemize{
\item ir_per_pyears = 1000: rates expressed per 1,000 person-years (default)
\item ir_per_pyears = 100000: rates expressed per 100,000 person-years
Output column names are fixed (e.g., IR_per_Npy_Unwt, IR_per_Npy_Wted). The multiplier
value is recorded in the Analysis Summary sheet.
}
}
\section{Side Effects}{

Creates the output directory and writes an Excel workbook when
\code{out_xlsxpath} is provided.
}

\examples{
csv_path <- system.file("extdata", "sample_data.csv", package = "rwetools")
df <- read.csv(csv_path)

# Unweighted analysis only
result <- estimate_hr_ir(
  in_df_unwt    = df,
  in_df_wted    = NULL,
  exposure_var  = "exposure",
  outcome_var   = "outcome",
  survival_time = "follow_up_days",
  time_unit     = "days",
  ir_per_pyears = 1000,
  verbose       = FALSE
)
result$incidence_rates

\donttest{
# Weighted analysis with Excel output (requires openxlsx)
if (requireNamespace("openxlsx", quietly = TRUE)) {
  df_ps <- estimate_ps(
    in_df        = df,
    exposure_var = "exposure",
    class_vars   = c("cat1", "cat2", "cat3", "cat4"),
    cont_vars    = c("cont1", "cont2", "cont3"),
    verbose      = FALSE
  )
  df_wt <- create_ps_weights(
    in_df         = df_ps,
    exposure_var  = "exposure",
    ps_var        = "ps",
    weight_method = "mw",
    weight_var    = "mw_wt",
    verbose       = FALSE
  )
  out_xlsx <- tempfile(fileext = ".xlsx")
  result2 <- estimate_hr_ir(
    in_df_unwt    = df,
    in_df_wted    = df_wt,
    out_xlsxpath  = out_xlsx,
    exposure_var  = "exposure",
    outcome_var   = "outcome",
    survival_time = "follow_up_days",
    weight_var    = "mw_wt",
    ir_per_pyears = 1000,
    verbose       = FALSE
  )
}
}
}
