nested_nodes: Search for parents or children in tquery

In vanatteveldt/rsyntax: Extract Semantic Relations from Text by Querying and Reshaping Syntax

Search for parents or children in tquery

Description

Enables searching for parents or children. Should only be used inside of the tquery function, or within other children/parents functions. Look-up conditions are specified in the same way as in the tquery function.

Multiple children() or parents() functions can be nested side by side. This works as an AND condition: the node must have all these parents/children (unless the req [required] argument is set to FALSE).

The custom_fill() function is used to include the children of a 'labeled' node. It can only be nested in a query if the label argument is not NULL, and by default will include all children of the node that have not been assigned to another node. If two nodes have a shared child, the child will be assigned to the closest node.

Usage

children(
  ...,
  g_id = NULL,
  label = NA,
  req = TRUE,
  depth = 1,
  connected = FALSE,
  fill = TRUE,
  block = FALSE,
  max_window = c(Inf, Inf),
  min_window = c(0, 0)
)

not_children(
  ...,
  g_id = NULL,
  depth = 1,
  connected = FALSE,
  max_window = c(Inf, Inf),
  min_window = c(0, 0)
)

parents(
  ...,
  g_id = NULL,
  label = NA,
  req = TRUE,
  depth = 1,
  connected = FALSE,
  fill = TRUE,
  block = FALSE,
  max_window = c(Inf, Inf),
  min_window = c(0, 0)
)

not_parents(
  ...,
  g_id = NULL,
  depth = 1,
  connected = FALSE,
  max_window = c(Inf, Inf),
  min_window = c(0, 0)
)

Arguments

...	Accepts two types of arguments: name-value pairs for finding nodes (i.e. rows), and functions to look for parents/children of these nodes. The name in the name-value pairs need to match a column in the data.table, and the value needs to be a vector of the same data type as the column. By default, search uses case sensitive matching, with the option of using common wildcards (* for any number of characters, and ? for a single character). Alternatively, flags can be used to to change this behavior to 'fixed' (__F), 'igoring case' (__I) or 'regex' (__R). See details for more information. If multiple name-value pairs are given, they are considered as AND statements, but see details for syntax on using OR statements, and combinations. To look for parents and children of the nodes that are found, you can use the parents and children functions as (named or unnamed) arguments. These functions have the same query arguments as tquery, but with some additional arguments.
g_id	Find nodes by global id, which is the combination of the doc_id, sentence and token_id. Passed as a data.frame or data.table with 3 columns: (1) doc_id, (2) sentence and (3) token_id.
label	A character vector, specifying the column name under which the selected tokens are returned. If NA, the column is not returned.
req	Can be set to false to not make a node 'required'. This can be used to include optional nodes in queries. For instance, in a query for finding subject - verb - object triples, make the object optional.
depth	A positive integer, determining how deep parents/children are sought. 1 means that only direct parents and children of the node are retrieved. 2 means children and grandchildren, etc. All parents/children must meet the filtering conditions (... or g_id)
connected	Controls behavior if depth > 1 and filters are used. If FALSE, all parents/children to the given depth are retrieved, and then filtered. This way, grandchildren that satisfy the filter conditions are retrieved even if their parents do not satisfy the conditions. If TRUE, the filter is applied at each level of depth, so that only fully connected branches of nodes that satisfy the conditions are retrieved.
fill	Logical. If TRUE (default), the default custom_fill() will be used. To more specifically control fill, you can nest the custom_fill function (a special version of the children function).
block	Logical. If TRUE, the node will be blocked from being assigned (labeld). This is mainly usefull if you have a node that you do not want to be assigned by fill, but also don't want to 'label' it. Essentially, block is shorthand for using label and then removing the node afterwards. If block is TRUE, label has to be NA.
max_window	Set the max token distance of the children/parents to the node. Has to be either a numerical vector of length 1 for distance in both directions, or a vector of length 2, where the first value is the max distance to the left, and the second value the max distance to the right. Default is c(Inf, Inf) meaning that no max distance is used.
min_window	Like max_window, but for the min distance. Default is c(0,0) meaning that no min is used.

Details

Having nested queries can be confusing, so we tried to develop the find_nodes function and the accompanying functions in a way that clearly shows the different levels. As shown in the examples, the idea is that each line is a node, and to look for parents or children, we put them on the next line with indentation (in RStudio, it should automatically align correctly when you press enter inside of the children() or parents() functions).

There are several flags that can be used to change search condition. To specify flags, add a double underscore and the flag character to the name in the name value pairs (...). By adding the suffix __R, query terms are considered to be regular expressions, and the suffix __I uses case insensitive search (for normal or regex search). If the suffix __F is used, only exact matches are valid (case sensitive, and no wildcards). Multiple flags can be combined, such as lemma__RI, or lemma__IR (order of flags is irrelevant)

The not_children and not_parents functions will make the matched children/parents a NOT condition. Note that this is different from using the NOT() look-up function. NOT operates at the node level, so you specify that a node should NOT be matched if certain conditions are met. the not_parents and not_children functions operate at the pattern level, so you can specify that a pattern is invalid if these parents/children are matched.

Next to the OR, AND, and NOT functions, children/parents functions can have the special BREAK function for cases where depth > 1. If depth > 1 in the children, parents or fill function, the children/parents will be retrieved recursively (i.e. children, children of children, etc.). If the look-up conditions (e.g., relation = 'nsubj') are not satisfied, a node will not be matched by the query, but the search will still continue for it's parents/children. The special BREAK look-up function allows you to specify a condition for breaking the recursive loop (lending it's name from the 'break' in a for loop). An example is that you might want to stop the recursive loop in a custom_fill() once it encounters a nested sentence, such as a relative clause: custom_fill(BREAK(relation = 'relcl')).

Value

Should not be used outside of tquery

vanatteveldt/rsyntax documentation built on June 14, 2022, 7:42 a.m.