Add drug-based report set construction

.Rbuildignore

@@ -5,6 +5,7 @@
 ^Scratch\.RConsole$
 ^data-raw$
 ^\.github$
+^_pkgdown\.yml$
 ^README\.Rmd$
 ^README\.md$
 ^README\.html$

DESCRIPTION

@@ -37,7 +37,8 @@ Suggests:
     knitr,
     pak,
     rmarkdown,
-    testthat (>= 3.0.0)
+    testthat (>= 3.0.0),
+    withr
 biocViews: Software, DataImport, BiomedicalInformatics, Pharmacogenomics, Pharmacogenomics
 Encoding: UTF-8
 ByteCompile: true
@@ -74,6 +75,7 @@ Collate:
     'period.R'
     'phv_.R'
     'phv_ebgm.R'
+    'restrict-drug.R'
     'restrict.R'
     'rxnorm.R'
     'sample.R'

NAMESPACE

@@ -31,6 +31,7 @@ export(faers_phv_signal_composite)
 export(faers_phv_table)
 export(faers_primaryid)
 export(faers_quarter)
+export(faers_reports_with)
 export(faers_restrict)
 export(faers_standardize)
 export(faers_year)

NEWS.md

@@ -1,5 +1,20 @@
 # faers 1.5.6
 
+* Added `faers_reports_with()`, a report set constructor for drug exposure
+  definitions: reports whose drug records match a combination of drug name
+  patterns (case-insensitive regular expressions), optionally restricted per
+  drug to specific role codes (`.roles`) and optionally excluding reports
+  containing other drugs (`.exclude_drugs`, report-level and role-agnostic).
+  `.logic = "and"/"or"` combines patterns; two patterns may be satisfied by
+  the same drug row (fixed-dose combination products). Returns the filtered
+  object, sorted `primaryid` vector or a count. On duckdb-backed objects
+  plain-literal patterns are pushed down to SQL (`regexp_matches`), other
+  patterns fall back to identical R matching. Per-drug matches are combined
+  across ASCII and non-ASCII rows before AND/OR and report-level exclusions;
+  object-mode returns build on a private copy, leaving the source database
+  untouched. Per-pattern hit counts are reported as a message; empty result
+  sets are a legitimate outcome, not an error.
+
 * Added `faers_restrict()`, a report-level restriction helper that narrows a
   standardized FAERS object to a sub-population by reporting period
   (`.period`), date window (`.date_range` on `.date_field`, with partial

R/available.R

@@ -10,7 +10,8 @@
 #' @return A logical indicates FAERS can have data for the `years` and
 #' `quarters` required?
 #' @examples
-#' faers_available(c(2011, 2023), c("q1", "q2"))
+#' # Queries the FDA website (falls back to bundled metadata without internet):
+#' faers_available(c(2011, 2023), c("q1", "q2"), internal = !curl::has_internet())
 #' @export
 faers_available <- function(years, quarters, force = FALSE, internal = FALSE) {
     assert_inclusive(quarters, FAERS_FILE_QUARTERS)

R/meta.R

@@ -11,7 +11,8 @@
 #' @return A [data.table][data.table::data.table] reporting years, period,
 #' quarter, and file urls and file sizes.
 #' @examples
-#' faers_meta()
+#' # Queries the FDA website (falls back to bundled metadata without internet):
+#' faers_meta(internal = !curl::has_internet())
 #' @seealso
 #' <https://fis.fda.gov/extensions/FPD-QDE-FAERS/FPD-QDE-FAERS.html>
 #' @export