implemented filtering

Author: Pascal-Kueng

R/infer_dyad_compositions.R

@@ -117,11 +117,13 @@ infer_dyad_compositions <- function(data, seed = NULL, include_compositions = NU
       .i_pool_member = NA_character_
     )
 
-  # Filter and only include requested compositions, if filtering was requested!
+  # Apply composition filtering before exchangeability overrides and pooling.
   include_result <- apply_include_compositions(
     data = data,
     dyad_roles = dyad_roles,
     include_compositions = include_compositions,
+    set_exchangeable_compositions = set_exchangeable_compositions,
+    pool_compositions = pool_compositions,
     group_name = group_name
   )
   data <- include_result$data
@@ -217,7 +219,9 @@ infer_dyad_compositions <- function(data, seed = NULL, include_compositions = NU
 }
 
 
-apply_include_compositions <- function(data, dyad_roles, include_compositions, group_name) {
+apply_include_compositions <- function(data, dyad_roles, include_compositions,
+                                       set_exchangeable_compositions,
+                                       pool_compositions, group_name) {
   if (is.null(include_compositions)) {
     return(list(data = data, dyad_roles = dyad_roles))
   }
@@ -230,13 +234,44 @@ apply_include_compositions <- function(data, dyad_roles, include_compositions, g
     )
   }
 
-  # get cannonical composition-labels
+  # Get canonical composition labels for the filter.
   include_compositions_resolved <- resolve_composition_references(
     references = include_compositions,
     observed_compositions = dyad_roles[[interdep_composition_col]],
     arg_name = "include_compositions"
   )
 
+  # Resolve later composition references so we can catch references removed by
+  # the filter and provide a clearer error.
+  set_exchangeable_compositions_resolved <- resolve_composition_references(
+    references = set_exchangeable_compositions,
+    observed_compositions = dyad_roles[[interdep_composition_col]],
+    arg_name = "set_exchangeable_compositions"
+  )
+
+  pool_composition_references <- NULL
+  if (is.list(pool_compositions)) {
+    pool_composition_references <- unlist(pool_compositions, use.names = FALSE)
+  }
+  pool_compositions_resolved <- resolve_composition_references(
+    references = pool_composition_references,
+    observed_compositions = dyad_roles[[interdep_composition_col]],
+    arg_name = "pool_compositions"
+  )
+
+  # Check if later arguments refer to compositions removed by the filter.
+  referenced_later <- c(set_exchangeable_compositions_resolved, pool_compositions_resolved)
+  if (!all(referenced_later %in% include_compositions_resolved)) {
+    references_removed_by_include <- setdiff(referenced_later, include_compositions_resolved)
+    stop(
+      "`include_compositions` filters out composition(s) that are later referenced by ",
+      "`set_exchangeable_compositions` or `pool_compositions`: ",
+      paste(sort(references_removed_by_include), collapse = ", "),
+      ". Add them to `include_compositions` or remove them from the later argument.",
+      call. = FALSE
+    )
+  }
+
   # Get dyad-ids that we keep
   keep_dyads <- dyad_roles |>
     dplyr::filter(.data[[interdep_composition_col]] %in% include_compositions_resolved) |>

tests/testthat/test-prepare_interdep_data.R

@@ -434,7 +434,7 @@ test_that("prepare_interdep_data applies include_compositions before constrainin
       set_exchangeable_compositions = "female-male",
       seed = 123
     ),
-    "`set_exchangeable_compositions` contains unknown dyad composition",
+    "`include_compositions` filters out composition(s) that are later referenced by `set_exchangeable_compositions` or `pool_compositions`: female_x_male. Add them to `include_compositions` or remove them from the later argument.",
     fixed = TRUE
   )
 
@@ -448,7 +448,7 @@ test_that("prepare_interdep_data applies include_compositions before constrainin
       pool_compositions = list(couples = c("female-female", "female-male")),
       seed = 123
     ),
-    "`pool_compositions` contains unknown dyad composition",
+    "`include_compositions` filters out composition(s) that are later referenced by `set_exchangeable_compositions` or `pool_compositions`: female_x_male. Add them to `include_compositions` or remove them from the later argument.",
     fixed = TRUE
   )
 })

vignettes/getting-started.Rmd

@@ -318,6 +318,27 @@ We can use this data to model these dyad types as separate or in the same model;
 the [Actor-Partner Interdependence Model vignette](apim.html) shows both
 mixed-composition formulas and practical convergence notes.
 
+### Keeping only selected dyad compositions (filtering)
+
+Sometimes a mixed dataset contains dyad compositions that should not be part of
+a given analysis. Use `include_compositions` to keep only dyads whose *observed*
+composition matches the requested labels. The filtering happens before exchangeability
+constraints and pooling, so `set_exchangeable_compositions` and
+`pool_compositions` arguments can only refer to retained types of dyads.
+
+```{r prepare-mixed-cross-sectional-included}
+mixed_cross_data_included <- prepare_interdep_data(
+  example_dyadic_crosssectional_mixed,
+  group = coupleID,
+  member = personID,
+  role = gender,
+  include_compositions = c("female-female", "male-male"),
+  seed = 123
+)
+
+print(mixed_cross_data_included, n = 4)
+```
+
 ### Setting distinguishable dyads to be treated as exchangeable
 
 As mentioned earlier, omitting the `role` argument treated all
@@ -389,9 +410,6 @@ print(mixed_cross_data_pooled_constrained)
 ```
 
 
-If you want to exclude some dyad compositions completely, filter them before
-preparation. A dedicated composition-inclusion argument is planned.
-
 For model formulas and interpretation, continue with the
 [Actor-Partner Interdependence Model vignette](apim.html),
 [Dyad-Individual Model vignette](dim.html), or