% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/filter-products.R
\name{exclude_products_with_ingredients}
\alias{exclude_products_with_ingredients}
\title{Exclude products containing specified ingredients}
\usage{
exclude_products_with_ingredients(
  data,
  ingredients = NULL,
  ingredient_rxcuis = NULL,
  product_id_col = "product_rxcui",
  ingredient_name_col = "ingredient_name",
  ingredient_rxcui_col = "ingredient_rxcui",
  return_excluded = FALSE
)
}
\arguments{
\item{data}{A data frame containing product RxCUIs and ingredient information,
such as that produced by \code{\link[=products_for_ingredients]{products_for_ingredients()}}.}

\item{ingredients}{Optional character vector of ingredient names to exclude.
These are resolved to ingredient RxCUIs using \code{\link[=find_ingredients]{find_ingredients()}}.}

\item{ingredient_rxcuis}{Optional character vector of ingredient RxCUIs to
exclude. These are used directly and do not require name resolution.}

\item{product_id_col}{Name of the column containing product RxCUIs. Default
is \code{product_rxcui}.}

\item{ingredient_name_col}{Name of the column containing ingredient names.
Used for reporting and, when needed, fallback matching. Default is
\code{ingredient_name}.}

\item{ingredient_rxcui_col}{Name of the column containing ingredient RxCUIs.
Default is \code{ingredient_rxcui}.}

\item{return_excluded}{Logical. If \code{FALSE}, return the filtered data frame.
If \code{TRUE}, return a list with \code{data}, \code{excluded}, and
\code{resolved_ingredients}.}
}
\value{
If \code{return_excluded = FALSE}, a data frame of the same general shape as
\code{data}, with excluded product rows removed.

If \code{return_excluded = TRUE}, a list with:
\describe{
\item{data}{The filtered data frame.}
\item{excluded}{Rows from the input data belonging to excluded products.}
\item{resolved_ingredients}{The ingredient names/RxCUIs used for exclusion.}
}
}
\description{
Remove all rows for products that contain one or more user-specified
ingredients. This is useful when broad ingredient-based product searches
return fixed-dose combination products that contain an ingredient of interest
but are not clinically relevant to a specific study definition.
}
\details{
Exclusions are applied at the product level. If any ingredient in a product
matches the exclusion list, all rows for that product are removed.
}
\examples{
\dontrun{
antihtn_clean <- antihtn_products |>
  exclude_products_with_ingredients(ingredients = "sacubitril")

antihtn_audit <- antihtn_products |>
  exclude_products_with_ingredients(
    ingredients = "sacubitril",
    return_excluded = TRUE
  )

antihtn_audit$data
antihtn_audit$excluded
antihtn_audit$resolved_ingredients
}

}
