Perform a transformation for every clustering entity

transform_in_every_clusteringEntity() takes a full Rxs project object (as produced by rxs_parseExtractionScripts()) and processes all Rxs trees, looking for clustering entities that match the entityId_regex regular expression (for information about what clustering entities are, see https://sysrevving.com/glossary.html) and/or that contain a field matching the requiredField_regex regular expression, and passes those to function fun with funArgs as arguments. For funArgs, you can pass entity identifiers of clustered entities contained in the clustering entity. These are then assigned the corresponding name before fun is called using do.call. This allows you to select values and rename them to match the function arguments.

transform_in_every_clusteringEntity(
  x,
  newEntityName,
  fun,
  funArgs = NULL,
  entityId_regex = NULL,
  requiredField_regex = NULL
)

Arguments

x

The full Rxs project object (as produced by rxs_parseExtractionScripts()).

newEntityName

The name of the new entity to add to the clustering entity (i.e., the target entity's parent entity, a container entity).

fun

The function to apply.

funArgs

The arguments, as a character vector where each element is a clustered entity stored in the clustering entity, and each element's name is how that entity's value should be passed to fun (allowing you to specify that you want to pass, for example, uni.mean and uni.sd as arguments mean and sd, respectively, to fun). Anything in this vector that is not the identifier of a clustered entity is passed as is.

entityId_regex

An optional regular expression: if specified, only entity nodes with entity identifiers that match this regular expression will be processed.

requiredField_regex

An optional regular expression specifying a field that the clustering entity must contain for it to be processed.

Value

Invisibly, the full Rxs project object. Note that the Rxs trees will be changed in place given data.tree's pass-by-reference logic; so you can discard the result.

Examples

### Load an example Rxs project
data('example_rxsProject_1', package="metabefor");

### Look at contents of a clustering entity holding
### information about an association between variables with
### identifiers 'chalk' and 'witches'
example_rxsProject_1$rxsTrees$qurid_7h50rzpq$associations$chalk_and_witches$value;
#> $associationIdentifier
#> [1] "chalk_and_witches"
#> 
#> $varId1
#> [1] "chalk"
#> 
#> $varId2
#> [1] "witches"
#> 
#> $r
#> [1] 0.8
#> 
#> $t
#> [1] NA
#> 

### Multiply the value of entity with identifier
### 'r' with 2 in all clustering entities
metabefor::transform_in_every_clusteringEntity(
  example_rxsProject_1,
  newEntityName = "double_the_r",
  fun = function(x) {
    return(x * 2);
  },
  funArgs = c(x = "r"),
  requiredField_regex = "^r$"
);

### See the added entity
example_rxsProject_1$rxsTrees$qurid_7h50rzpq$associations$chalk_and_witches$value;
#> $associationIdentifier
#> [1] "chalk_and_witches"
#> 
#> $varId1
#> [1] "chalk"
#> 
#> $varId2
#> [1] "witches"
#> 
#> $r
#> [1] 0.8
#> 
#> $t
#> [1] NA
#> 
#> $double_the_r
#> [1] 1.6
#>